Cartographic

class sargeom.coordinates.Cartographic(longitude, latitude, height=None, degrees=True)

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

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()

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=())

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)

Creates a new Cartographic instance with the appended positions.

Parameters:

positionssargeom.coordinates.Cartographic

The sequence of Cartographic instances to append.

Raises:

ValueError

If the instance to append is not a Cartographic instance.

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()

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

static crs()

Returns the WGS84 Geocentric System EPSG:4979.

Returns:

pyproj.crs.CRS

A pythonic coordinate reference system (CRS) manager.

static dd_to_dms(dd)

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)

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)

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.

originsargeom.coordinates.Cartographic, optional

The cartographic position describing the location of the local origin of the coordinate system. If the cartesian coordinate system used is not a local systems such as ENU, NED, and AER, this parameter is None. If not specified, the default local origin of the instance will be used.

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()

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)

Saves the Cartographic positions to a CSV file.

Parameters:

filenamestr or pathlib.Path

The name of the file to save the positions.

Examples

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

save_html(filename, link_markers=False)

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.

Examples

>>> position = Cartographic(longitude=2.230784, latitude=48.713028)
>>> position.save_html("my_map.html")

save_kml(filename)

Saves Cartographic positions to a KML file.

Parameters:

filenamestr or pathlib.Path

The name of the file to save the positions.

Notes

The ellipsoidal height is converted to orthometric height using the EGM96 geoid model. As a result, the output file is compatible with Google Earth and can be easily opened within the application.

Examples

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

to_array()

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()

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)

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()

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)

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')

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