Crate galileo_types

This crate contains a set of geometric primitives and operations on them used in GIS systems. It includes geometries themselves, projections and coordinate systems.

The approach taken by this crate is trait-first approach. All business logic and operations are defined in traits and some simple default implementations are provided for convenience. The traits are designed to be simple to implement.

Projected vs geographic coordinates

GIS systems work with geometries in two representations:

• geographic coordinates are defined by latitude and longitude
• projected coordinates are defined in cartesian X and Y on a flat surface of the Earth

Most GIS systems do not distinguish these coordinates and just consider latitude to be Y and longitude to be X. This brings a lot of confusion, starting with mixing of order of coordinates, as in geography latitude usually goes first, but in geometry nobody puts Y before X, and ending with euclidean operations being applied to angular coordinates.

Because of that, galileo-types crate makes strong distinction between geographic and cartesian coordinates. Basic trait for coordinates in any space is a point:

• GeoPoint is defined in geo module, and represents a point in geographic coordinate system
• CartesianPoint2d is defined in cartesian module, and represents a point in cartesian coordinate system on a flat surface of the Earth (or another stellar body)

Geometry traits are generic over point type they are constructed with.

Unfortunately, most of existing systems do not have this distinction and so a same point type might require implementation of both these traits. This creates a problem though for sometime it’s difficult to know which trait’s methods are to be used in a given moment. To help elevate this problem, Disambig struct can be used.

Z, H, M, T coordinates

GIS systems often work with 3rd and even 4th coordinates, but the meaning of those coordinates can differ between coordinate systems:

• Z is usually an up coordinate in projected cartesian coordinate system with same units as X and Y
• H means height above surface or above datum
• M is an arbitrary measure coordinate
• T is a time coordinate

Not distinguishing between those usages also brings confusion. For example, what would distance between two points defined in XYH space mean? It might be euclidean distance on the flat surface, or 3d distance in projection units, or 3d distance in H units (e.g. meters or feet).

Because of this reason, points in every of those spaces are represented by different traits and provide different set of methods with their own meaning.

At this point, one such trait is defined:

• CartesianPoint3d - a point in XYZ coordinate system, where Z is defined in projection units.

Converting between coordinate systems

Converting between different types of coordinates is done using Projections.

Geometry types

A subset of OGC geometry types are supported at the moment:

• GeoPoint, CartesianPoint2d, CartesianPoint3d (correspond to OGC Point geometry)
• MultiPoint
• Contour (corresponds to OGC LineString geometry with slight difference, check the trait’s documentation)
• MultiContour (corresponds to OGC MultiLineString geometry)
• Polygon
• MultiPolygon

Implementing Geometry trait

The most generic trait is Geometry, which provides operations that can be done on any type of geometry. Implementing this trait manually might be tedious for every geometry type, although for most use cases the default implementation provided by this crate would be sufficient. Unfortunately, Rust type system doesn’t allow to provide blanket implementations of a trait for a set of other traits (because of possible conflicting implementations), and at the same time let the user override default implementation with more specific one (because of trait specialization problem).

There is a way around those limitations though. You can use GeometryType trait to make your type, implementing any of the specific geometry traits, also implement Geometry trait automatically.

Implementation for foreign types

galileo-types provides geometry traits implementation for these crates:

• geo-types - enabled by geo-types feature
• geojson - enabled by geojson feature

Re-exports

• pub use contour::ClosedContour;
• pub use contour::Contour;
• pub use geometry::CartesianGeometry2d;
• pub use geometry::Geometry;

Modules

• cartesian
  Types and functions on geometries in cartesian coordinates.
• contour
  Contour is a sequence of points.
• error
  Error type used by the crate.
• geo
  Geometries in geographic coordinates (latitude and longitude) (see GeoPoint) and conversion between different geographic coordinate systems (see Projection).
• geometry
  Abstract geometry types:
• geometry_type
  See documentation for GeometryType trait.
• impls
  Implementations of geometry traits.

Macros

• latlon
  Creates a new GeoPoint2d from latitude and longitude values (in degrees).

Structs

• Disambig
  Wrapper type that disambiguates coordinate space for generic geometries.
• Segment
  A strait line segment between two points.

Traits

• Disambiguate
  A trait used to convert a geometry with no specified coordinate space into one of the specific coordinate spaces. This trait is auto-implemented for all types, that implement GeometryType<Space = AmbiguousSpace> trait.
• MultiContour
  Geometry consisting of several contours.
• MultiPoint
  Geometry type consisting of several points.
• MultiPolygon
  Geometry consisting of several polygons.
• Polygon
  Polygon geometry. Polygon consists of one outer contour, and zero or more inner contours.