# Advanced topics

## πΊοΈ Using cartesian positions

Position objects can be manipulated in cartesian coordinate system using operators and functions available.

Other options to apply coordinate transforms on position objects are to use
`transform`

(with a custom transform as a parameter) or `project`

(geospatial
projections, discussed in the separate
chapter).

Also `PositionSeries`

has some helpful operators and functions worth mentioning
here.

Also `PositionSeries`

objects can be transformed using `transform`

and `project`

too, just like single positions. Some other methods are available too to add,
insert, replace and remove positions on a series, or to filter it. Please
consult the package documentation for more information.

## π Calculations along the Earth surface

Cartesian geometry used in the previous section is not enough when measuring distances between geographic positions located far apart.

The `geobase`

package provides geodesy functions that are based on calculations
on a spherical
earth model (with errors up to 0.3% compared to an ellipsoidal earth model).
Distance, bearing, destination point and midpoint are provided both for
*great circle paths* and *rhumb lines*. Intermediate points, intersections and
areas are available for great circle paths only.

Thereβs a separate chapter about these calculations.

## π 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).

Special logic is also applied when merging geographic bounding boxes.

## π’ 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:

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. |