Advanced topics

🌐 Antimeridian issues

When manipulating geographic coordinates you also have to handle geometries and bounding boxes spanning the antimeridian (longitude +180°). The rules specified by RFC 7946 about GeoJSON are respected. For example bounding boxes may have west longitude coordinate (minX) larger than east longitude coordinate (maxX).

// The bounding box of the Fiji archipelago spans the antimeridian.
GeoBox(west: 177.0, south: -20.0, east: -178.0, north: -16.0);

Special logic is also applied when merging geographic bounding boxes.

// a sample merging two boxes on both sides on the antimeridian
// (the result equal with p3 is then spanning the antimeridian)
const b1 = GeoBox(west: 177.0, south: -20.0, east: 179.0, north: -16.0);
const b2 = GeoBox(west: -179.0, south: -20.0, east: -178.0, north: -16.0);
const b3 = GeoBox(west: 177.0, south: -20.0, east: -178.0, north: -16.0);
b1.mergeGeographically(b2) == b3; // true

// a sample merging two boxes without need for antimeridian logic
const b4 = GeoBox(west: 40.0, south: 10.0, east: 60.0, north: 11.0);
const b5 = GeoBox(west: 55.0, south: 19.0, east: 70.0, north: 20.0);
const b6 = GeoBox(west: 40.0, south: 10.0, east: 70.0, north: 20.0);
b4.mergeGeographically(b5) == b6; // true

🔢 Coordinate arrays

Position and bounding box classes introduced in the coordinates chapter are used when handling positions or bounding boxes (bounds) individually.

However to handle coordinate data in geometry objects and geospatial data formats also, efficient array data structures for coordinate values (as double numeric values) are needed. These structures are mostly used when building or writing coordinate data of geometry objects described in the simple geometry chapter.

Following factory methods allow creating PositionSeries, Position and Box instances from coordinate arrays of double values.

Factory method	Description
PositionSeries.view	Coordinate values of 0 to N positions as a flat structure.
Position.view	Coordinate values of a single position.
Box.view	Coordinate values of a single bounding box.

For example series of positions can be created as:

  // A position series with three positions each with x and y coordinates.
  PositionSeries.view(
    [
      10.0, 11.0, // (x, y) for position 0
      20.0, 21.0, // (x, y) for position 1
      30.0, 31.0, // (x, y) for position 2
    ],
    type: Coords.xy,
  );

  // A shortcut to create a position series with three positions (with x and y).
  [
    10.0, 11.0, // (x, y) for position 0
    20.0, 21.0, // (x, y) for position 1
    30.0, 31.0, // (x, y) for position 2
  ].positions(Coords.xy);

  // A position series with three positions each with x, y and z coordinates.
  PositionSeries.view(
    [
      10.0, 11.0, 12.0, // (x, y, z) for position 0
      20.0, 21.0, 22.0, // (x, y, z) for position 1
      30.0, 31.0, 32.0, // (x, y, z) for position 2
    ],
    type: Coords.xyz,
  );

The coordinate type (using a Coords enum value) must be defined when creating series of positions. Expected coordinate values (exactly in this order) for each type are described below:

Type	Projected values	Geographic values
Coords.xy	x, y	lon, lat
Coords.xyz	x, y, z	lon, lat, elev
Coords.xym	x, y, m	lon, lat, m
Coords.xyzm	x, y, z, m	lon, lat, elev, m

See also specialized extension methods or getters on List<double>:

Method/getter	Created object	Description
positions()	PositionSeries	An array of 0 to N positions from a flat structure of coordinate values.
position	Position	A single position.
box	Box	A single bounding box.

For single positions there are also some more extension getters on List<double> to create instances of Position:

Getter	2D/3D	Coords	Values	x	y	z	m
.xy	2D	2	double	+	+
.xyz	3D	3	double	+	+	+
.xym	2D	3	double	+	+		+
.xyzm	3D	4	double	+	+	+	+

For geographic coordinates same getters on List<double> are used:

Getter	2D/3D	Coords	Values	lon (x)	lat (y)	elev (z)	m
.xy	2D	2	double	+	+
.xyz	3D	3	double	+	+	+
.xym	2D	3	double	+	+		+
.xyzm	3D	4	double	+	+	+	+

🧩 Content interfaces

Content interfaces allows writing geometry, property and feature data to format encoders and object builders. They are used in this package for encoding geometries and features to GeoJSON (text), WKT (text) and WKB (binary) representations, and decoding geometry and feature objects from GeoJSON and WKB representations.

Content interface	Description
CoordinateContent	Write coordinate data to format encoders and object builders.
SimpleGeometryContent	Write simple geometry data to format encoders and object builders.
GeometryContent	Write geometry (both simple and collection geometries) data to format encoders and object builders.
FeatureContent	Write geospatial feature objects to format encoders and object builders.