= RFC 61 : Support for measured geometries =

Author: Ari Jolma[[BR]]

Contact: ari.jolma at gmail.com[[BR]]

Status: Draft[[BR]]

Implementation version: 2.1 or 2.2

== Summary ==

This RFC defines how to implement measured geometries (geometries, where the points have M coordinate, i.e., they are XYM or XYZM).

== Rationale ==

M coordinate is in the OGC simple feature model and it is used in many vector data formats.

== Changes ==

Changes are required into the C++ API and the C API needs to be enhanced. Several drivers need to be changed to take advantage of this enhancement but also due to the changes in the C++ API.

=== Common API ===

ogr_core.h:
{{{
#define OGR_G_NOT_EMPTY 1
#define OGR_G_3D 3
#define OGR_G_MEASURED 5
}}}

New OGRwkbGeometryType values are needed - that is rather complex system now due to history.

=== C++ API ===

Change int nCoordDimension to int flags, which is used to keep track of whether the geometry is empty (currently hacks such as nCoordDimension == -2 is used for that), has Z, or is measured. IsEmpty = flags & ~OGR_G_NOT_EMPTY, Is3D = flags & OGR_G_3D, IsMeasured = flags & OGR_G_MEASURED.

Keep, but deprecate 
{{{
getCoordinateDimension();
setCoordinateDimension();
}}}

class OGRGeometry:
{{{
//Add methods:
int CoordinateDimension();
OGRBoolean Is3D();
OGRBoolean IsMeasured();
virtual void set3D(OGRBoolean bIs3D);
virtual void setMeasured(OGRBoolean bIsMeasured);

//Add now or later methods:
virtual OGRGeometry *LocateAlong(double mValue);
virtual OGRGeometry *LocateBetween(double mStart, double mEnd);
}}}

Add property double m to class OGRPoint. Add constructor, getters, and setters for it.

Add property double *padfM to class OGRSimpleCurce. Add constructor, getters, and setters for it. The getters and setters can take advantage of the flags to determine whether Z or M is to be set in some of them. For backwards compatibility Z is preferred.

Override methods set3D and setMeasured in those classes where setCoordinateDimension is overridden.

=== C API ===

ogr_core.h:
{{{
OGRwkbGeometryType CPL_DLL OGR_GT_SetM( OGRwkbGeometryType eType );
int                CPL_DLL OGR_GT_HasM( OGRwkbGeometryType eType );
}}}
ogr_api.h: (new versions of some functions are needed, use postfix M)
{{{
void   CPL_DLL OGR_G_Is3D( OGRGeometryH );
void   CPL_DLL OGR_G_IsMeasured( OGRGeometryH );

void   CPL_DLL OGR_G_Set3D( OGRGeometryH, int );
void   CPL_DLL OGR_G_SetMeasured( OGRGeometryH, int );

int    CPL_DLL OGR_G_GetPointsM( OGRGeometryH hGeom,
                                 void* pabyX, int nXStride,
                                 void* pabyY, int nYStride,
                                 void* pabyZ, int nZStride,
                                 void* pabyM, int nMStride);
double CPL_DLL OGR_G_GetM( OGRGeometryH, int );
void   CPL_DLL OGR_G_GetPointM( OGRGeometryH, int iPoint, 
                                double *, double *, double *, double * );
void   CPL_DLL OGR_G_SetPointM( OGRGeometryH, int iPoint, 
                                double, double, double, double );
void   CPL_DLL OGR_G_AddPointM( OGRGeometryH, double, double, double, double );
void   CPL_DLL OGR_G_SetPointsM( OGRGeometryH hGeom, int nPointsIn,
                                 void* pabyX, int nXStride,
                                 void* pabyY, int nYStride,
                                 void* pabyZ, int nZStride,
                                 void* pabyM, int nMStride );

}}}

ogr_p.g
{{{
const char CPL_DLL * OGRWktReadPointsM( const char * pszInput,
                                       OGRRawPoint **ppaoPoints, 
                                       double **ppadfZ,
                                        double **ppadfM,
                                       int * pnMaxPoints,
                                       int * pnReadPoints );
void CPL_DLL OGRMakeWktCoordinateM( char *, double, double, double, double, int );

}}}

pggeometry.h is internal, so we can change the function prototype
{{{
void OGRCreateFromMultiPatchPart(OGRMultiPolygon *poMP,
                                 OGRPolygon*& poLastPoly,
                                 int nPartType,
                                 int nPartPoints,
                                 double* padfX,
                                 double* padfY,
                                 double* padfZ,
                                 double* padfM);
}}}


== SWIG bindings (Python / Java / C# / Perl) changes ==

The new C API functions need to be exposed through swig. Further changes depend on whether the language bindings are aware of coordinates. At least Python and Perl are.

== Drivers ==

Drivers that are probably affected by the C++ changes are at least (these use the CoordinateDimension API) pg, mssqlspatial, sqlite, db2, mysql, gml, pgdump, geojson, libkml, gpkg, wasp, gpx, filegdb, vfk, bna, dxf.


== Utilities ==

to do

== Documentation ==

All new methods/functions are documented.

== Test Suite ==

to do

== Compatibility Issues ==

to do

== Related tickets ==

https://trac.osgeo.org/gdal/ticket/6063
https://trac.osgeo.org/gdal/ticket/6331

== Implementation ==

The implementation will be done by Ari Jolma.

The proposed implementation will be in https://github.com/ajolma/GDAL-XYZM

== Voting history