Module Common.Position

This module deals with coordinates and conversion from and to different coordinate systems.

module type Unit = sig ... end

In order to avoid mixing up different unit, we introduce this module type. In practice, only floats are used internally, but the user can hide this fact to get stronger guarantees in their code, at the price of having to explicitly call the conversion functions.

module Units : sig ... end
module Earth : sig ... end

Model of the Earth

module type SphericalType = sig ... end

Spherical coordinates (WGS 84, EPSG:4326)

module Spherical : SphericalType with module Meters = Units.Meters and module Degrees = Units.Degrees and module Radians = Units.Radians

If one wants to hide the fact that Meters.t and Degrees.t are floats, one can cast it by locally defining module Spherical = Position.(Spherical : SphericalType).

We consider spherical coordinates as the default, as these are the coordinates used in OSM.

include module type of Spherical
module Meters = Units.Meters
module Degrees = Units.Degrees
module Radians = Units.Radians
type t = Degrees.t * Degrees.t

The (longitude, latitude) coordinates of each point, in degrees (following WGS 84's ellipsoid). North and East are positive.

val compare : t -> t -> int

Compare two positions

val normalise : t -> t

Normalise a representation of a position.

val normalise_angle : Degrees.t -> Degrees.t

Return an angle between -180 and 180 equivalent (modulo 360) to its argument.

val normalise_angle_around : Degrees.t -> Degrees.t -> Degrees.t

normalise_angle_around a0 a returns an angle between a0 - 180 and a0 + 180 equivalent to its argument.

val normalise_angle_rad : Radians.t -> Radians.t

Similar functions but for radians instead of degrees.

val normalise_angle_around_rad : Radians.t -> Radians.t -> Radians.t
val north_pole : t

Some specific coordinates.

val south_pole : t
val null_island : t
val test_coordinates : t list

Some specific coordinates, distances, and angles, for tests.

val test_angles : Degrees.t list
val test_distances : Meters.t list
val test_latitudes : Degrees.t list
val antimeridian : Degrees.t

Value of the longitude of the Antimeridian (that is, the 180th meridian).

val distance : t -> t -> Meters.t

Shortest distance between two points (around the world, as a great circle), in meters. In other words, the length of the geodesic between the provided two points. Several algorithms with various precision and computation speed can be used: it is assumed that long-distance measurements are rare and short-distance measurements frequent.

val fast_distance : t -> t -> Meters.t

Computing the distance can be quite costly, despite the fact that we try to use appropriate algorithms depending on the situation. This function is less accurate than distance, but is faster.

val precise_distance : t -> t -> Meters.t

In the rare cases in which precision is absolutely necessary, this function will choose the most appropriate algorithms to compute the distance without taking computation speed into account. It will always be slower than distance.

val is_distance_in : t -> t -> Meters.t -> Meters.t -> bool

State whether the distance between two points is within the provided interval (bounds included). This should typically be faster than calling distance and comparing it to the associated bounds.

val opposite : t -> t

The point placed exactly at the other side of the Earth.

val longitude_meters_to_radians : lat:Units.Degrees.t -> Units.Meters.t -> Units.Radians.t

Conversion of a distance in meters to the (assuming spherical Earth) corresponding angle of coordinates at the provided latitude, assuming it is taken parallel to the equator. The latitude is always expressed in degrees, even when converting to radians.

val longitude_meters_to_degrees : lat:Units.Degrees.t -> Units.Meters.t -> Units.Degrees.t
val latitude_meters_to_radians : ?lat:Units.Degrees.t -> Units.Meters.t -> Units.Radians.t

Similar, but with a distance taken perpendicular to the equator. The latitude is here optional as it doesn't change that much the result. Note that it must always be expressed in degrees, even in the conversion to radian.

val latitude_meters_to_degrees : ?lat:Units.Degrees.t -> Units.Meters.t -> Units.Degrees.t
val longitude_radians_to_meters : lat:Units.Degrees.t -> Units.Radians.t -> Units.Meters.t

The inverse functions.

val longitude_degrees_to_meters : lat:Units.Degrees.t -> Units.Degrees.t -> Units.Meters.t
val latitude_radians_to_meters : ?lat:Units.Degrees.t -> Units.Radians.t -> Units.Meters.t
val latitude_degrees_to_meters : ?lat:Units.Degrees.t -> Units.Degrees.t -> Units.Meters.t
val print : t -> string

Print-out the coordinates, mainly for debugging purposes.

module Ops : sig ... end

Useful operators to include when dealing with coordinates and distances.

val close_to : epsilon:float -> float -> float -> bool

Whether two floats are close enough (up to epsilon).

module TestOps : sig ... end

Operators to be used for tests.