RFC 61 : Support for measured geometries

Author: Ari Jolma

Contact: ari.jolma at gmail.com

Status: Draft

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