SphericalGeometry.jl

A Julia Package for handling Spherical Geometry. Spherical geometry is the geometry of the two-dimensional surface of a sphere. This package only handles geometries generated using great circle sections (arcs).

Angles are specified in [deg].

Types:

• Point: specified by latitude ϕ [deg] and longitude λ [deg]
• Arc: specified as the shortest great circle between two points.
• Line: is a great circle line specified by a point and azimuth [deg]
• Arcs: is a string of continuous line sections defined by a set of points.
• Polygon: is a spherical polygon defined by a set of points.

It includes the calculation of:

• The angular distance to a point, line, arc, multi-arc, or polygon border
• The along line angular distance between a point and a line.
• The intersection points between lines, arcs, multi-arcs, and polygon borders.
• The self intersection points of multi-arcs and polygon borders
• The bounding box of a given polygon or set of arcs.
• The convexhull of a given polygon.
• The normalized point
• The (final) azimuth [deg] between two points
• The spherical angle [deg] and spherical excess [deg] between three points
• The midpoint between two points, of an arc, of an arcs
• The intermediate point at a given fraction between two points, of an arc, of an arcs
• The destination point given a start point, a direction and distance.
• The intersection points of arcs, and polygons
• The self intersection points of arcs or a polygon
• The highest/lowest latitude (point) of a great circle
• The area of a polygon/spherical triangle given a radius

And testing if:

• a point, arc, arcs or polygon is inside a polygon
• a point is on a line, arc, arcs or polygon border (within tolerance)
• a polygon/arcs is self-isselfintersecting
• a polygon is simple, complex, convex or concave

Point(ϕ::Float64, λ::Float64)

Point type with latitude ϕ [deg] and longitude λ [deg]

Arc(point₁::Point, point₂::Point)

Arc type with start position point₁ [deg] and end position point₂ [deg]. The Arc is defined along the shortest great circle distance between the two points.

Line(point::Point, azimuth::Float64)

Line type with point [deg] and azimuth [deg]. The line type of a great circle line that completely circles the sphere.

Arcs(points::Vector{Point})

Arcs type with a Vector of points [deg]. A minimum of two points are necessary for the continuous string of line sections.

Polygon(inside_point::Point, points::Vector{Point})

Polygon type with points [deg]. A minimum of three different points are necessary for a polygon. Also an inside point must be given.

along_line_angular_distance(angular_distance₁₃::Float64,
angular_distance_line3::Float64)

The along_line_angular_distance from the start point₁ [deg] to the closest point on the great circle line to point₃. As input we need the angular_distance₁₃ [deg] between point₁ and point₃ [deg] and the closest distance angular_distance_line3 [deg] between the great circle line and point3 [deg]. The distance is non-directional.

Source: www.movable-type.co.uk/scripts/latlong.html

along_line_angular_distance(point₃::Point, line₁::Line)

The along_line_angular_distance from the start point₁ [deg] to the closest point on the great circle line line₁ to point₃. The distance is non-directional.

Source: www.movable-type.co.uk/scripts/latlong.html

angular_distance(point₃::Point, point₁::Point, point₂::Point)

Return the angular_distance [deg] from point₃ [deg] to the closest point on a great circle line section starting in point₁ [deg] and ending in point₂ [deg]. The great circle line section does not continue around the unit sphere.

The angular_distance does not change sign when being left or right of the arc.

angular_distance(angular_distance₁₃::Float64, azimuth₁₃::Float64,
azimuth₁₂::Float64)

Return the angular_distance [deg] from point₃ [deg] to the closest point on a great circle line starting in point₁ [deg] with azimuth₁₂ [deg]. For the calculation we need the angular_distance₁₃ and azimuth₁₃ between point₁ and point₃ [deg], and the azimuth₁₂ from point₁ to point₂ along the great circle line. It is assumed that the great circle line does not stop in point₂, but continuous around the unit sphere.

Source: www.movable-type.co.uk/scripts/latlong.html

angular_distance(point₃::Point, arcs::Arcs)

Return the angular_distance [deg] from point₃ [deg] to the closest point on a an arcs.

The angular_distance does not change sign when being left or right of the arc.

angular_distance(point₃::Point, arc₁₂::Arc)

Return the angular_distance [deg] from point₃ [deg] to the closest point on a great circle line section starting in point₁ [deg] and ending in point₂ [deg]. The great circle line section does not continue around the unit sphere.

angular_distance(point₃::Point, line₁::Line)

Return the angular_distance [deg] from point₃ [deg] to the closest point on a great circle line starting in point₁ [deg] with azimuth₁₂ [deg]. A positive value indicates being right of the line, and negative being left of the line.

Source: www.movable-type.co.uk/scripts/latlong.html

angular_distance(point₃::Point, point₁::Point, azimuth₁₂::Float64)

Return the angular_distance [deg] from point₃ [deg] to the closest point on a great circle line starting in point₁ [deg] with azimuth₁₂ [deg] from point₁ to point₂. It is assumed that the great circle line does not stop in point₂, but continuous around the unit sphere. A positive value indicates being right of the line, and negative being left of the line.

Source: www.movable-type.co.uk/scripts/latlong.html

angular_distance(point₁::Point, point₂::Point)

Return the angular_distance [deg] of the great circle line between the positions point₁ [deg] and point₂ [deg] on a unit sphere.

Source: www.movable-type.co.uk/scripts/latlong.html

angular_distance(point₃::Point, polygon::Polygon)

Return the angular_distance [deg] from point₃ [deg] to the closest point on the border of a polygon.

The angular_distance does not change sign when being left or right of the arc.

angular_distance(point₃::Point, points::Vector{Points{T}}) where T<:Float64

Return the angular_distance [deg] from point₃ [deg] to the closest point on a an set of points representing an set of arcs.

The angular_distance does not change sign when being left or right of the arc.

angular_length(arcs::Arcs)

Return the angular_length [deg] along the arcs on a unit sphere.

angular_length(arc::Arc)

Return the angular_length [deg] of the great circle line section on a unit sphere.

angular_length(polygon::Polygon)

Return the angular_length deg along the polygon on a unit sphere.

angular_length(points::Vector{Points{Float64}})

Return the angular_length [deg] along the subsequent points on a unit sphere.

area(point₁::Point, point₂::Point, point₃::Point, radius::Float64=1.0)

Return the area of the spherical triangle 123 based on the points point₁ - point₂ - point₃. Without given radius a unit sphere is assumed.

Source: mathworld.wolfram.com/SphericalTriangle.html

area(angular_distance₁₂::Float64, angular_distance₂₃::Float64, angular_distance₁₃::Float64,
radius::Float64=1.0)

Return the area of the spherical triangle 123 based on the angular distances [deg] 12-23-13. Without given radius a unit sphere is assumed.

Source: mathworld.wolfram.com/SphericalTriangle.html

area(polygon::Polygon, radius::Float64=1.0)

Return the area of the spherical polygon. Without given radius a unit sphere is assumed.

Source: en.wikipedia.org/wiki/Spherical_trigonometry # Area and spherical excess

The method has been altered to allow for the usage of an internal point given with the Polygon. This method only works with polygons that fit within half a sphere as it uses great circle distances between subsequent points.

azimuth(line::Line)

output: angle [deg]

Return the initial azimuth [deg], measured clockwise from the north direction, of the line on a unit sphere.

azimuth(point₁::Point, point₂::Point)

output: angle [deg]

Return the initial azimuth [deg], measured clockwise from the north direction, of the great circle line between the positions point₁ and point₂ [deg] on a unit sphere.

Source: www.movable-type.co.uk/scripts/latlong.html

boundingbox(arcs::Arcs)

Output: [[ϕ_south,ϕ_north],[λ_west,λ_east]]

Generate bounding box values from the given arcs. All arcs stay within the lat/lon-limits of the bounding box.

Source: Chamberlain & Duquette - Some Algorithms for Polygons on a Sphere

boundingbox(polygon::Polygon)

Output: [[ϕ_south,ϕ_north],[λ_west,λ_east]]

Generate bounding box values from the given polygon. This bounding box can be used for quick point-in-polygon tests. Any arc of the polygon stays within the lat/lon-limits of the bounding box.

Source: Chamberlain & Duquette - Some Algorithms for Polygons on a Sphere

convexhull(polygon::Polygon)

output: Polygon

Generate a convex hull for the polygon.

Source: stackoverflow.com/questions/9678624/convex-hull-of-longitude-latitude-points-on-the-surface-of-a-sphere

destination_point(line::Line, angular_distance::Float64)

output: point::Point

Given a line with a startpoint and azimuth, calculate the `destina­tionpoint[deg] at theangular_distance`.

destination_point(start_point::Point, angular_distance::Float64,
azimuth::Float64)

output: point::Point

Given a start_point [deg], initial azimuth (clockwise from North) [deg], angular_distance [deg] calculate the position of the destina­tion_point [deg] traversing along a great circle line.

Source: www.movable-type.co.uk/scripts/latlong.html

final_azimuth(line::Line)

output: angle [deg]

Return the final_azimuth [deg] of the line on a unit sphere.

final_azimuth(point₁::Point, point₂::Point)

output: angle [deg]

Return the final azimuth [deg], measured clockwise from the north direction, of the great circle line between the positions point₁ and point₂ [deg] on a unit sphere.

Source: www.movable-type.co.uk/scripts/latlong.html

highest_latitude(point::Point, azimuth::Float64)

output: latitude [deg]

The highest latitude a great circle reaches when starting in a point along the given azimuth [deg].

Source: https://www.edwilliams.org/avform147.htm#Clairaut

highest_latitude_point(point::Point, azimuth::Float64)

output: point::Point

The highest latitude point a great circle reaches when starting in point along the given azimuth [deg].

Source: https://www.edwilliams.org/avform147.htm#XTE

highest_latitude_point(point₁::Point, point₂::Point)

output: point::Point

The highest latitude point a great circle reaches when starting in point₁ towards point₂. The point must be between point₁ and point₂.

Source: https://www.edwilliams.org/avform147.htm#XTE

intermediate_point(arc::Arc, fraction::Float64)

output: point::Point

Return the intermediate_point [deg] at any fraction along the great circle arc [deg]. The fraction along the great circle arc is such that fraction = 0.0 is at the start of the arc and fraction 1.0 is at the end of the arc.

intermediate_point(arcs::Arcs, fraction::Float64)

output: point::Point

Return the intermediate_point [deg] at any fraction along the great circle arcs [deg]. The fraction along the great circle arcs is such that fraction = 0.0 is at the start of the arcs and fraction 1.0 is at the end of the arcs.

intermediate_point(point₁::Point, point₂::Point, fraction::Float64)

output: point::Point

Return the intermediate_point [deg] at any fraction along the great circle line section between the two points point₁ and point₂ [deg]. The fraction along the great circle line section is such that fraction = 0.0 is at point₁ [deg] and fraction 1.0 is at point₂ [deg].

Source: www.movable-type.co.uk/scripts/latlong.html

intersection_point(point₁::Point, point₂::Point, point₃::Point, point₄::Point)

output: point::Point

Return the intersection point [deg] of two great circle line section given by two sets of two points: point₁ and point₂ [deg] and point₃ and point₄ [deg].

Under certain circumstances the results can be an ∞ or ambiguous solution. https://blog.mbedded.ninja/mathematics/geometry/spherical-geometry/finding-the-intersection-of-two-arcs-that-lie-on-a-sphere/

intersection_point(arc₁::Arc, arc₂::Arc)

output: point::Point

Return the intersection point [deg] of two great circle line sections.

Under certain circumstances the results can be an ∞ or ambiguous solution.

intersection_point(line₁::Line, line₂::Line)

output: point::Point

Return the intersection point point₃ [deg] of two great circle lines 'line₁' and line₂.

Under certain circumstances the results can be an ∞ or ambiguous solution.

intersection_point(point₁::Point, point₂::Point, azimuth₁₃::Float64,
azimuth₂₃::Float64)

output: point::Point

Return the intersection point point₃ [deg] of two great circle lines given by two start points [deg] point₁ and point₂ [deg] and two azimuths [deg] from point₁ to point₃ [deg], and from point₂ to point₃ [deg].

Under certain circumstances the results can be an ∞ or ambiguous solution.

Source: edwilliams.org/avform.htm

intersection_points(arcs₁::Arcs, arcs₂::Arcs)

output: points::Vector of Point

Return the intersection points [deg] of two line sections.

intersection_points(arcs::Arcs, polygon::Polygon)

output: points::Vector of Point

Return the intersection points [deg] of a arcs with a polygon.

intersection_points(polygon₁::Polygon, polygon₂::Polygon)

output: points::Vector of Point

Return the intersection points [deg] of two polygons.

iscomplex(polygon::Polygon)

True if the polygon is 'complex' meaning that it self-intersects.

isconcave(polygon::Polygon)

Tests if a polygon is concave.

This is true when the polygon is simple and not convex.

isconvex(polygon::Polygon)

Tests if a polygon is convex.

The test is setup by checking exhaustively all possible arcs between all points of the polygon to intersect with the polygon. If false the polygon is convex.

isinside(arc::Arc, polygon::Polygon)

Determine if the arc is fully inside the polygon. The border is outside the polygon.

isinside(arcs::Arcs, polygon::Polygon)

Determine if the arcs is fully inside the polygon. The border is outside the polygon.

isinside(point::Point, polygon::Polygon)

Determine if the point is inside the polygon. The border is outside the polygon.

Source: M. Bevis and J.L. Chatelain, "Locating a point on a spherical surface relative to a spherical polygon" 1989

isinside(polygon₁::Polygon, polygon₂::Polygon)

Determine if the polygon₁ is fully inside the polygon₂. The border is outside the polygon₁.

ison(point::Point, arc::Arcs [,tolerance::Float64=tolerance_deg])

Determine if the point is on the arcs.

ison(point::Point, arc::Arc [,tolerance::Float64=tolerance_deg])

Determine if the point is on the arc.

ison(point::Point, line::Line [,tolerance::Float64=tolerance_deg])

Determine if the point is on the line.

ison(point::Point, polygon::Polygon [,tolerance::Float64=tolerance_deg])

Determine if the point is on the border of the polygon.

isselfintersecting(arcs::Arcs)

isselfintersecting(polygon::Polygon)

isselfintersecting(points::Vector{Point{Float64}})

issimple(polygon::Polygon)

True if the polygon is 'simple' meaning that it does not self-intersect.

lowest_latitude(point::Point, azimuth::Float64)

output: latitude [deg]

The lowest latitude a great circle reaches when starting in a point along the given azimuth [deg].

lowest_latitude_point(point::Point, azimuth::Float64)

output: point::Point

The lowest latitude point a great circle reaches when starting in point along the given azimuth [deg].

Source: https://www.edwilliams.org/avform147.htm#XTE

lowest_latitude_point(point₁::Point, point₂::Point)

output: point::Point

The lowest latitude point a great circle reaches when starting in point₁ towards point₂. The point must be between point₁ and point₂.

Source: https://www.edwilliams.org/avform147.htm#XTE

midpoint(arcs::Arcs)

output: point::Point

Return the half-way point midpoint [deg] on the great circle arcs [deg] on a unit sphere.

midpoint(arc::Arc)

output: point::Point

Return the half-way point midpoint [deg] on the great circle arc [deg] on a unit sphere.

midpoint(point₁::Point, point₂::Point)

output: point::Point

Return the half-way point midpoint [deg] on the great circle line between the positions point₁ and point₂ [deg] on a unit sphere.

Source: www.movable-type.co.uk/scripts/latlong.html

spherical_angle(point₁::Point, point₂::Point, point₃::Point)

output: angle [deg]

Return the 'spherical_angle' [deg] of angle₁₂₃ given the triangle point₁ - point₂ - point₃

Source: en.wikipedia.org/wiki/Spherical_trigonometry

spherical_angle(angular_distance₁₂::Float64, angular_distance₂₃::Float64, angular_distance₁₃::Float64)

output: angle [deg]

Return the 'spherical_angle' [deg] of angle₁₂₃ given the angular distances [deg] between point₁ and point₂, point₂ and point₃, and point₁ and point₃.

Source: en.wikipedia.org/wiki/Spherical_trigonometry

spherical_excess(angular_distance₁₂::Float64, angular_distance₂₃::Float64, angular_distance₁₃::Float64)

output: angle [deg]

Return the 'spherical_excess' [deg] of the spherical triangle 123 given the angular distances between the points point₁, point₂, and point₃

Source: mathworld.wolfram.com/SphericalExcess.html

spherical_excess(point₁::Point, point₂::Point, point₃::Point)

output: angle [deg]

Return the 'spherical_excess' [deg] of the spherical triangle 123 given the points point₁ - point₂ - point₃

Source: mathworld.wolfram.com/SphericalExcess.html