Cartographic¶

class sargeom.coordinates.Cartographic(longitude, latitude, height=None, degrees=True)[source]¶

Bases: ndarray

A Cartographic object represents the position of a point in a geodetic coordinate system. This class is inspired by the CesiumJS library.

Parameters:

longitudefloat or numpy.ndarray: The longitude, in degrees, originates at the prime meridian.
latitudefloat or numpy.ndarray: The latitude, in degrees, originates at the equator.
heightfloat or numpy.ndarray, optional: The height, in meters, above the ellipsoid. The default value is 0.0.
degreesbool, optional: If True (default), takes input angles in degrees. If False, takes input angles in radians.

Returns:

sargeom.coordinates.Cartographic: The cartographic position.

Raises:

ValueError: If the longitude, latitude, and height are not of equal size. If the longitude, latitude, and height are not 0- or 1-dimensional arrays.

Notes

The coordinate reference system (CRS) used is the GPS satellite navigation and positioning system : WGS84 Geographic System EPSG:4979.

Examples

Define a Cartographic position:

>>> Cartographic(longitude=10.0, latitude=20.0, height=30.0)
Lon.Lat.Height Cartographic position
[10. 20. 30.]

Define multiple Cartographic positions:

>>> Cartographic(longitude=[15.0, 25.0], latitude=[30.0, 40.0])
Lon.Lat.Height Cartographic positions
[[15. 30.  0.]
 [25. 40.  0.]]

Define a Cartographic position using radians:

>>> Cartographic(longitude=np.pi/6, latitude=np.pi/3, degrees=False)
Lon.Lat.Height Cartographic position
[30. 60.  0.]

Slice a Cartographic position:

>>> carto = Cartographic(longitude=[10.0, 20.0, 30.0], latitude=[40.0, 50.0, 60.0], height=[70.0, 80.0, 90.0])
>>> carto[1]
Lon.Lat.Height Cartographic position
[20. 50. 80.]
>>> carto[1:]
Lon.Lat.Height Cartographic positions
[[20. 50. 80.]
 [30. 60. 90.]]

Attributes Summary

`height`	The ellipsoidal height, in meters, is measured along a normal of the reference spheroid.
`latitude`	The latitude, in degrees, originates at the equator.
`longitude`	The longitude, in degrees, originates at the prime meridian.

Methods Summary

`ONERA_CP`()	A cartographic instance initialized at ONERA's position in Palaiseau (2.230784, 48.713028, 0.0).
`ONERA_SDP`()	A cartographic instance initialized at ONERA's position in Salon-de-Provence (5.117724, 43.619212, 0.0).
`ZERO`([N])	A Cartographic instance initialized to (0.0, 0.0, 0.0).
`append`(positions)	Creates a new Cartographic instance with the appended positions.
`bounding_box`()	Get the bounding box of the Cartographic instance.
`concatenate`(positions)	Concatenate a sequence of Cartographic instances into a single instance.
`crs`()
`dd_to_dms`(dd)	Converts decimal degrees representation of geodetic coordinates to Degrees - Minutes - Seconds.
`dms_to_dd`(d, m, s)	Converts Degrees - Minutes - Seconds representation of geodetic coordinates to decimal degrees.
`from_array`(array[, degrees])	Initializes a Cartographic instance using a numpy array representing Lon-Lat-Height coordinates.
`is_collection`()	Check if the Cartographic instance represents a set of positions.
`save_csv`(filename)	Saves the Cartographic positions to a CSV file.
`save_html`(filename[, link_markers])	Saves Cartographic positions to an HTML file using Folium.
`save_kml`(filename[, height_mode])	Saves Cartographic positions to a KML file.
`to_array`()	Convert Cartographic positions to a numpy array.
`to_ecef`()	Convert Cartographic positions to geocentric Earth-centered Earth-fixed (ECEF) coordinates.
`to_geojson`([clamp_to_Ground, link_markers])	Convert Cartographic positions to GeoJSON format.
`to_pandas`()	Convert Cartographic positions to a Pandas DataFrame.
`to_shapely`([clamp_to_Ground, link_markers])	Converts the Cartographic instance to a Shapely geometry object.
`to_trajviewer`([name, description, ...])	Open the Cartographic instance in the TrajViewer web application.

Attributes Documentation

height¶

The ellipsoidal height, in meters, is measured along a normal of the reference spheroid.

Returns:

numpy.ndarray: The ellipsoidal height, in meters.

Examples

>>> position = Cartographic(longitude=10.0, latitude=20.0, height=30.0)
>>> position.height
array(30.)

>>> positions = Cartographic(longitude=[10.0, 15.0], latitude=[20.0, 25.0], height=[30.0, 35.0])
>>> positions.height
array([30., 35.])

latitude¶

The latitude, in degrees, originates at the equator.

More specifically, the latitude of a point is the angle a normal to the ellipsoid at that point makes with the equatorial plane, which contains the center and equator of the ellipsoid. An angle of latitude is within the range [-90°, 90°]. Positive latitudes correspond to north and negative latitudes correspond to south.

Returns:

numpy.ndarray: The latitude, in degrees.

Examples

>>> position = Cartographic(longitude=10.0, latitude=20.0)
>>> position.latitude
array(20.)

>>> positions = Cartographic(longitude=[10.0, 15.0], latitude=[20.0, 25.0])
>>> positions.latitude
array([20., 25.])

longitude¶

The longitude, in degrees, originates at the prime meridian.

More specifically, the longitude of a point is the angle that a plane containing the ellipsoid center and the meridian containing that point makes with the plane containing the ellipsoid center and prime meridian. Positive longitudes are measured in a counterclockwise direction from a vantage point above the North Pole. Typically, longitude is within the range [-180°, 180°] or [0°, 360°].

Returns:

numpy.ndarray: The longitude, in degrees.

Examples

>>> position = Cartographic(longitude=10.0, latitude=20.0)
>>> position.longitude
array(10.)

>>> positions = Cartographic(longitude=[10.0, 15.0], latitude=[20.0, 25.0])
>>> positions.longitude
array([10., 15.])

Methods Documentation

static ONERA_CP()[source]¶

A cartographic instance initialized at ONERA’s position in Palaiseau (2.230784, 48.713028, 0.0).

Returns:

sargeom.coordinates.Cartographic: Instance initialized to (longitude=2.230784, latitude=48.713028, height=0.0).

Examples

>>> Cartographic.ONERA_CP()
Lon.Lat.Height Cartographic position
[ 2.230784 48.713028  0.      ]

static ONERA_SDP()[source]¶

A cartographic instance initialized at ONERA’s position in Salon-de-Provence (5.117724, 43.619212, 0.0).

Returns:

sargeom.coordinates.Cartographic: Instance initialized to (longitude=5.117724, latitude=43.619212, height=0.0).

Examples

>>> Cartographic.ONERA_SDP()
Lon.Lat.Height Cartographic position
[ 5.117724 43.619212  0.      ]

static ZERO(N=())[source]¶

A Cartographic instance initialized to (0.0, 0.0, 0.0).

Parameters:

Nint, optional: Number of points to initialize. The default is only 1.

Returns:

sargeom.coordinates.Cartographic: Instance initialized to (0.0, 0.0, 0.0).

Examples

>>> Cartographic.ZERO()
Lon.Lat.Height Cartographic position
[0. 0. 0.]

>>> Cartographic.ZERO(2)
Lon.Lat.Height Cartographic positions
[[0. 0. 0.]
 [0. 0. 0.]]

append(positions)[source]¶

Creates a new Cartographic instance with the appended positions.

This is a convenience method for concatenating this instance with another single instance. For concatenating multiple instances, use the concatenate() class method.

Parameters:

positionssargeom.coordinates.Cartographic: The Cartographic instance to append.

Raises:

ValueError: If the instance to append is not a Cartographic instance.

See also

concatenate: Class method for concatenating multiple instances

Examples

>>> A = Cartographic(longitude=10.0, latitude=20.0, height=30.0)
>>> B = Cartographic(longitude=15.0, latitude=25.0, height=35.0)
>>> A.append(B)
Lon.Lat.Height Cartographic positions
[[10. 20. 30.]
 [15. 25. 35.]]

bounding_box()[source]¶

Get the bounding box of the Cartographic instance.

Returns:

eastfloat: The maximum longitude.
westfloat: The minimum longitude.
northfloat: The maximum latitude.
southfloat: The minimum latitude.

Raises:

ValueError: If the Cartographic instance is not a collection of positions.

Examples

>>> positions = Cartographic(longitude=[10.0, 15.0], latitude=[20.0, 25.0])
>>> positions.bounding_box()
(np.float64(15.0), np.float64(10.0), np.float64(25.0), np.float64(20.0))

classmethod concatenate(positions)[source]¶

Concatenate a sequence of Cartographic instances into a single instance.

Parameters:

positionssequence of sargeom.coordinates.Cartographic: The sequence of Cartographic instances to concatenate. Can be a list, tuple, or any iterable.

Returns:

sargeom.coordinates.Cartographic: A new Cartographic instance containing all positions from the input instances.

Raises:

ValueError

If the input list is empty.
If not all items in the list are instances of Cartographic.

Examples

Concatenate multiple Cartographic positions:

>>> pos_1 = Cartographic(longitude=[1.0, 2.0], latitude=[45.0, 46.0], height=[100, 200])
>>> pos_2 = Cartographic(longitude=3.0, latitude=47.0, height=300)
>>> pos_3 = Cartographic(longitude=[4.0, 5.0], latitude=[48.0, 49.0], height=[400, 500])
>>> combined = Cartographic.concatenate([pos_1, pos_2, pos_3])
>>> len(combined)
5
>>> combined.longitude
array([1., 2., 3., 4., 5.])

Concatenate single positions:

>>> paris = Cartographic(longitude=2.3522, latitude=48.8566, height=35.0)
>>> london = Cartographic(longitude=-0.1276, latitude=51.5074, height=11.0)
>>> cities = Cartographic.concatenate([paris, london])
>>> len(cities)
2

static crs()[source]¶

Returns the coordinate reference system (CRS) for the WGS84 Geographic 3D System EPSG:4979.

Returns:

dict: A dictionary containing the name, EPSG code, and ellipsoid of the coordinate reference system (CRS).

static dd_to_dms(dd)[source]¶

Converts decimal degrees representation of geodetic coordinates to Degrees - Minutes - Seconds.

Parameters:

ddnumpy.ndarray: The decimal degrees expression of the geodetic coordinates to be converted.

Returns:

dnumpy.ndarray: The Degrees value of the geodetic coordinates.
mnumpy.ndarray: The Minutes value of the geodetic coordinates.
snumpy.ndarray: The Seconds value of the geodetic coordinates.

Notes

The orientation of latitude (North or South) and longitude (West or East) is returned through the sign of the Degrees value.

Examples

>>> d, m, s = Cartographic.dd_to_dms([-5.65475414, 43.23547474])
>>> print(f"{d[0]}°", f"{m[0]}'", f'{s[0]}"') 
-5° 39' 17.114..."
>>> print(f"{d[1]}°", f"{m[1]}'", f'{s[1]}"') 
43° 14' 7.709..."

static dms_to_dd(d, m, s)[source]¶

Converts Degrees - Minutes - Seconds representation of geodetic coordinates to decimal degrees.

Parameters:

dnumpy.ndarray: The Degrees value of the geodetic coordinates to be converted.
mnumpy.ndarray: The Minutes value of the geodetic coordinates to be converted.
snumpy.ndarray: The Seconds value of the geodetic coordinates to be converted.

Returns:

numpy.ndarray: The decimal degrees expression of the geodetic coordinates.

Notes

The orientation of latitude (North or South) and longitude (West or East) must be passed through the sign of the Degrees value.

Examples

>>> Cartographic.dms_to_dd([-5, 43], [39, 14], [17.114904,  7.709064]) 
array([-5.654..., 43.235...])

static from_array(array, degrees=True)[source]¶

Initializes a Cartographic instance using a numpy array representing Lon-Lat-Height coordinates.

Parameters:

arrayarray_like: A numpy array object representing a list of Lon-Lat-Height coordinates.
degreesbool, optional: If True (default), takes input angles in degrees. If False, takes input angles in radians.

Returns:

sargeom.coordinates.Cartographic: The Cartographic instance initialized by the input numpy array.

Raises:

ValueError: If the numpy array has not at least 1 row and only 3 columns.

Examples

>>> array = np.array([10.0, 20.0, 30.0])
>>> Cartographic.from_array(array)
Lon.Lat.Height Cartographic position
[10. 20. 30.]

>>> array = np.array([[10.0, 20.0, 30.0], [15.0, 25.0, 35.0]])
>>> Cartographic.from_array(array)
Lon.Lat.Height Cartographic positions
[[10. 20. 30.]
 [15. 25. 35.]]

is_collection()[source]¶

Check if the Cartographic instance represents a set of positions.

Returns:

bool: true if the instance is a collections of positions, false otherwise.

Examples

>>> position = Cartographic(longitude=10.0, latitude=20.0)
>>> position.is_collection()
False

>>> positions = Cartographic(longitude=[10.0, 15.0], latitude=[20.0, 25.0])
>>> positions.is_collection()
True

save_csv(filename)[source]¶

Saves the Cartographic positions to a CSV file.

Parameters:

filenamestr or pathlib.Path: The name of the file to save the positions.

Returns:

pathlib.Path: The path to the saved .csv file.

Examples

>>> positions = Cartographic(longitude=[10.0, 15.0], latitude=[20.0, 25.0], height=[30.0, 35.0])
>>> filename = positions.save_csv("output.csv")
>>> print(filename)
output.csv

save_html(filename, link_markers=False)[source]¶

Saves Cartographic positions to an HTML file using Folium.

Parameters:

filenamestr or pathlib.Path: The name of the file to save the positions.
link_markersbool, optional: If True, link markers with a line. Default is False.

Returns:

pathlib.Path: The path to the saved .html file.

Examples

>>> position = Cartographic(longitude=2.230784, latitude=48.713028)
>>> filename = position.save_html("output.html")
>>> print(filename)
output.html

save_kml(filename, height_mode='orthometric')[source]¶

Saves Cartographic positions to a KML file.

Parameters:

filenamestr or pathlib.Path: The name of the file to save the positions.
height_modestr, optional: The height mode to use for the KML file. Can be “orthometric” or “ellipsoidal”. Default is “orthometric”.

Returns:

pathlib.Path: The path to the saved .kml file.

Notes

If “orthometric” is selected, the height is converted to orthometric height using the EGM96 geoid model and is compatible with Google Earth.

Examples

>>> positions = Cartographic(longitude=[10.0, 15.0], latitude=[20.0, 25.0], height=[30.0, 35.0])
>>> filename = positions.save_kml("output.kml")
>>> print(filename)
output.kml

to_array()[source]¶

Convert Cartographic positions to a numpy array.

Returns:

numpy.ndarray: A numpy array initialized with the point positions.

Examples

>>> position = Cartographic(longitude=10.0, latitude=20.0, height=30.0)
>>> position.to_array()
array([10., 20., 30.])

to_ecef()[source]¶

Convert Cartographic positions to geocentric Earth-centered Earth-fixed (ECEF) coordinates.

Returns:

sargeom.coordinates.CartesianECEF: The corresponding CartesianECEF instance.

Examples

>>> position = Cartographic(longitude=2.230784, latitude=48.713028, height=0.0)
>>> position.to_ecef() 
XYZ CartesianECEF point
[4213272.203...  164124.695... 4769561.521...]

to_geojson(clamp_to_Ground=False, link_markers=False)[source]¶

Convert Cartographic positions to GeoJSON format.

Parameters:

clamp_to_Groundbool, optional: If True, clamp positions to the ground. Default is False.
link_markersbool, optional: If True, link markers with a line. Default is False.

Returns:

GeoJSON object: The GeoJSON representation of the Cartographic positions.

Notes

If link_markers is True and the list of coordinates is cyclic, a GeoJSON Polygon is returned otherwise a GeoJSON LineString. If link_markers is False, a GeoJSON MultiPoint is returned.

Examples

>>> position = Cartographic(longitude=10.0, latitude=20.0, height=30.0)
>>> position.to_geojson()
{'coordinates': [10.0, 20.0, 30.0], 'type': 'Point'}
>>> positions = Cartographic(longitude=[10.0, 15.0, 20.0], latitude=[20.0, 25.0, 30.0], height=[30.0, 35.0, 40.0])
>>> positions.to_geojson()
{'coordinates': [[10.0, 20.0, 30.0], [15.0, 25.0, 35.0], [20.0, 30.0, 40.0]], 'type': 'MultiPoint'}
>>> positions.to_geojson(clamp_to_Ground=True, link_markers=True)
{'coordinates': [[10.0, 20.0], [15.0, 25.0], [20.0, 30.0]], 'type': 'LineString'}

to_pandas()[source]¶

Convert Cartographic positions to a Pandas DataFrame.

Returns:

pandas.DataFrame: A Pandas object initialized with the geodetic position(s).

Examples

>>> position = Cartographic(longitude=10.0, latitude=20.0, height=30.0)
>>> position.to_pandas()
   longitude  latitude  height
0       10.0      20.0    30.0

to_shapely(clamp_to_Ground=False, link_markers=False)[source]¶

Converts the Cartographic instance to a Shapely geometry object.

This method converts the Cartographic instance to an appropriate Shapely geometry object, allowing for geometric operations and manipulations commonly performed with Shapely.

Parameters:

clamp_to_Groundbool, optional: If True, clamp positions to the ground. Default is False.
link_markersbool, optional: If True, link markers with a line. Default is False.

Returns:

Shapely geometry: A Shapely geometry object representing the Cartographic instance.

Notes

If link_markers is True and the list of coordinates is cyclic, a Shapely Polygon is returned otherwise a Shapely LineString. If link_markers is False, a Shapely MultiPoint is returned.

Examples

>>> position = Cartographic(longitude=10.0, latitude=20.0, height=30.0)
>>> position.to_shapely()
<POINT Z (10 20 30)>
>>> positions = Cartographic(longitude=[10.0, 15.0, 20.0], latitude=[20.0, 25.0, 30.0], height=[30.0, 35.0, 40.0])
>>> positions.to_shapely()
<MULTIPOINT Z ((10 20 30), (15 25 35), (20 30 40))>
>>> positions.to_shapely(clamp_to_Ground=True, link_markers=True)
<LINESTRING (10 20, 15 25, 20 30)>

to_trajviewer(name=None, description=None, clamp_to_Ground=False, link_markers=False, url='https://oleveque.github.io/trajviewer')[source]¶

Open the Cartographic instance in the TrajViewer web application.

Parameters:

namestr, optional: The name of the Cartographic instance. Default is None.
descriptionstr, optional: The description of the Cartographic instance. Default is None.
clamp_to_Groundbool, optional: If True, clamp positions to the ground. Default is False.
link_markersbool, optional: If True, link markers with a line. Default is False.
urlstr, optional: The URL of the TrajViewer web application. Default is “https://oleveque.github.io/trajviewer”.

Notes

TrajViewer is a web-based application for visualizing spatial data, such as trajectories, locations, and raster files. For more information, visit the GitHub repository: https://github.com/oleveque/trajviewer