Enhanced coordinate data structures for positions, bounding boxes and series of positions

[navispatial]

Goal

Analyze current class hierarchy on the package version 1.5.0 positions representing coordinates for a single point or location.

Suggest how to improve this in the version 2.0.0.

Documentation

Key documentation related to this issue on the doc site (v1):

• coordinates
• ellipsoidal geodesy
• spherical geodesy
• global grids

See also the API documentation (v 1.5.0):

• coordinates
• geodesy

Implementation in version 1.5

Positions, Box and PositionSeries

Geographic and projected coordinates can be represented as single positions, series of positions and bounding boxes (with minimum and maximum positions).

Class hierarchy:

• Positionable (contains data structures for (geospatial) position data, directly or within child objects)
  • ValuePositionable (A positionable object that has (geospatial) coordinate values directly available)
    • Box (A base class for axis-aligned bounding boxes with min & max coordinates)
    • Position (A base class for geospatial positions)
      • Geographic (A geographic position with longitude, latitude and optional elevation and m)
      • Projected (A projected position with x, y, and optional z and m coordinates)
  • Bounded (A positionable object with position data (directly or within child objects) and methods to resolve bounding boxes)
    • PositionSeries (A fixed-length (and random-access) view to a series of positions)

The PositionSeries class also implements ValuePositionable, not only Bounded. It's an abstract class that can be instantiated using two different data structures to store coordinate values of positions contained in a series:

• A list of Position objects (each object contain x and y coordinates, and optionally z and m too).
• A list of double values as a flat structure. For example a double list could contain coordinates like [x0, y0, z0, x1, y1, z1, x2, y2, z2] that represents three positions each with x, y and z coordinates.

The Bounded class is also implemented by FeatureObject and Geometry. Sub classes of FeatureObject are Feature and FeatureCollection. Sub classes of Geometry are different geometry data structures representing points, line strings (polylines), polygons, multi points, multi line strings, multi polygons and geometry collections. These are not discussed any further on this issue.

Scalable coordinates

Scalable coordinates are coordinates associated with a level of detail (LOD) or a zoom level. They are used for example by tiling schemes to represent pixels or tiles in tile matrices.

Class hierarchy:

• Scalable (A scalable object at the zoom level (a positive number))
  • Scalable2i (Scalable x, y coordinates at the zoom level.)

Coordinate values

Classes representing position, bounding box and scalable coordinates:

Coordinate values in position classes (projected and geographic):

Class	Required coordinates	Optional coordinates	Values
Position	x, y	z, m	double
Projected	x, y	z, m	double
Geographic	lon, lat	elev, m	double

Coordinate values in bounding box classes (projected and geographic):

Class	Required coordinates	Optional coordinates	Values
Box	minX, minY, maxX, maxY	minZ, minM, maxZ, maxM	double
ProjBox	minX, minY, maxX, maxY	minZ, minM, maxZ, maxM	double
GeoBox	west, south, east, north	minElev, minM, maxElev, maxM	double

Coordinate values in scalable classes:

Class	Required coordinates	Optional coordinates	Values
Scalable2i	zoom, x, y		int

Coordinates are stored as double values in all position and bounding box
classes but Scalable2i uses int coordinate values.

Geodesy (ellipsoidal and spherical)

On the geodesy sub package there are also other classes representing positions on spherical or ellipsoidal representations of the Earth.

Class hierarchy:

• Geocentric (geocentric cartesian position (X, Y, Z) representing an ECEF (earth-centric earth-fixed) position)
• Ellipsoidal (The base class for calculations related to the Earth surface modeled by ellipsoidal reference frames with geographic position (latitude, longitude) as an origin)
  • EllipsoidalVincenty (Calculations for Distances & bearings between points, and destination points given start points & initial bearings)
• Geodetic (not exported) (An abstract class with methods to calculate distances, bearings, destinations, etc on a geographic position.)
  • SphericalGreatCircle (Latitude/longitude points on a spherical model earth, and methods for calculating distances, bearings, destinations, etc on (orthodromic) great-circle paths)
  • SphericalRhumbLine (Latitude/longitude points on a spherical model earth, and methods for calculating distances, bearings, destinations, etc on (loxodromic) rhumb lines.)

These classes contain geographic positions in properties:

• Geocentric
  • origin → Position (The origin position for calculations.)
  • ellipsoid → Ellipsoid (The reference ellipsoid used for calculations)
  • datum → Datum (An optional datum used for calculations with a reference ellipsoid and datum transformation parameters)*
• Geodetic and sub classes
  • position : Geographic (The current geographic position for calculations)
• Ellipsoidal and sub classes
  • origin → Geographic (The origin position for calculations)
  • ellipsoid → Ellipsoid (The reference ellipsoid used for calculations)
  • datum → Datum (An optional datum used for calculations with a reference ellipsoid and datum transformation parameters)

Also following classes exists (the first defined on the coordinates sub package, the latter on the geodesy sub package):

• GeographicBearing (with geographic origin and bearing)
  • GeodeticArcSegment (with inherited properties, and geographic destination, distance and finalBearing)

Geodesy (global grids)

Classes related to UTM coordinates:

Class	Description
Utm	UTM coordinates, with functions to parse them and convert them to geographic points.
UtmMeta	Metadata (convergence and scale) as a result from UTM calculations related to position.
UtmZone	The UTM zone represented by the lonZone number and hemisphere.

Classes about MGRS grid references:

Class	Description
Mgrs	Military Grid Reference System (MGRS/NATO) grid references, with methods to parse references, and to convert between MGRS references and UTM coordinates.
MgrsGridSquare	The 100km grid square (or the 100,000-meter square identifier) as a part of the grid zone in MGRS/NATO grid references.
MgrsGridZone	A grid zone as a polygon of 6° × 8° in MGRS/NATO grid references.

The classes contains following properties:

• UtmZone
  • hemisphere → Hemisphere (The hemisphere of the Earth (north or south) is represented by 'N' or 'S' in UTM coordinates)
  • lonZone → int (represents UTM 6° longitudinal zone (1..60 covering 180°W..180°E))
• UtmMeta<T extends Object>
  • zone → UtmZone (The UTM zone of the position)
  • position → T (either a geographic position or projected UTM coordinates as indicated by T, potentially with the geodetic datum information.)
  • convergence → double (The meridian convergence specifies the bearing of the grid north clockwise from the true north, in degrees.)
  • scale → double (represents the UTM grid scale factor at position).
• Utm
  • datum → Datum (The datum used for calculations with a reference ellipsoid and datum transformation parameters)
  • zone → UtmZone (The UTM zone object with the longitudinal zone (1..60) and the hemisphere)
  • projected → Projected (The projected position as UTM coordinates (x=easting, y=northing, z=elev) in the specified zone)
  • easting → double (The easting (x) in metres from the false easting (-500km from the central meridian))
  • northing → double (The northing (y) in metres from the equator (N) or from the false northing -10,000km (S))
• MgrsGridZone
  • lonZone → int(represents UTM 6° longitudinal zone (1..60 covering 180°W..180°E))
  • band → String (represents 8° latitudinal band (C..X covering 80°S..84°N))
• MgrsGridSquare (extends MgrsGridZone)
  • inherited properties
  • column → String (represents the first letter (E) of a 100km grid square. Allowed letter characters are A..Z, omitting I and O.)
  • row → String (represents the second letter (N) of a 100km grid square. Allowed letter characters are A..V, omitting I and O.)
• Mgrs
  • datum → Datum (The datum used for calculations with a reference ellipsoid and datum transformation parameters)
  • gridSquare → MgrsGridSquare
    (The 100km grid square identified by a grid zone designator (GZD) and a 100km square identification)
  • easting → int (The easting (x) in metres within a 100km grid square)
  • northing → int (The northing (y) in metres within a 100km grid square)

Suggested refactoring for the version 2.0

Geodesy (ellipsoidal and spherical)

• Geocentric has the origin property with a generic position type Position, maybe there should be a new class Cartesian (extending Position) to better match geocentric cartesian position (X, Y, Z) representing an ECEF position description.
• SphericalGreatCircle and SphericalRhumbLine should use origin (of type Geographic) instead of position for consistency.

Geodesy (global grids)

• Refactor the UtmMeta class as a record type.

Suggested new features for the version 2.0

Coordinates

New features

• support for representing coordinate values (xy, xyz, xym, xyzm, ..) as records and transferring between objects instantiated from current position classes (as described above) and record representations

New classes

• Cartesian extends Position
  • would have x, y, z and m just like Position and Projected but meant to hold cartesian coordinates like geocentric cartesian coordinates (aggregated on the Geocentric class) or local coordinate systems that are not "projected" on the map.
• GeographicOrientation extends GeographicBearing (along position and bearing provide also tilt and roll angles, or map specific properties (tilt, zoom) like in google map CameraPosition)

Geodesy (ellipsoidal and spherical)

New features

• support for local tangent planes as suggested in Possibility for local tangent plane support? #269 with "ENU" (east, north, up) coordinates - how this would fit to coordinate classes consistently in the geobase package needs some analyzing before implementing it