Cartesian3¶

class sargeom.coordinates.Cartesian3(x, y, z, origin=None)[source]¶

Bases: ndarray

A Cartesian3 object represents the coordinates of a point or a vector in a 3D Cartesian coordinate system. This class is inspired by the CesiumJS library.

Parameters:

xfloat or numpy.ndarray: The X component, in meters.
yfloat or numpy.ndarray: The Y component, in meters.
zfloat or numpy.ndarray: The Z component, in meters.
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.

Returns:

sargeom.coordinates.Cartesian3: The 3D cartesian point.

Raises:

ValueError: If the X, Y and Z components are not of equal size. If the X, Y and Z components are not 0- or 1-dimensional arrays.

Examples

Define a single XYZ Cartesian3 point:

>>> Cartesian3(x=1.0, y=2.0, z=3.0)
XYZ Cartesian3 point
[1. 2. 3.]

Define a set of XYZ Cartesian3 points:

>>> Cartesian3(x=[1.0, 2.0, 3.0], y=[4.0, 5.0, 6.0], z=[7.0, 8.0, 9.0])
XYZ Cartesian3 points
[[1. 4. 7.]
 [2. 5. 8.]
 [3. 6. 9.]]

Slice a Cartesian3 instance:

>>> A = Cartesian3(x=[1.0, 2.0, 3.0], y=[4.0, 5.0, 6.0], z=[7.0, 8.0, 9.0])
>>> A[1]
XYZ Cartesian3 point
[2. 5. 8.]
>>> A[1:]
XYZ Cartesian3 points
[[2. 5. 8.]
 [3. 6. 9.]]

Perform arithmetic operations on Cartesian3 points:

>>> A = Cartesian3.UNIT_X()
>>> B = Cartesian3.ONE()
>>> A + B
XYZ Cartesian3 point
[2. 1. 1.]
>>> A - B
XYZ Cartesian3 point
[ 0. -1. -1.]
>>> A * B
XYZ Cartesian3 point
[1. 0. 0.]
>>> A / B
XYZ Cartesian3 point
[1. 0. 0.]

Attributes Summary

`local_origin`	Returns the cartographic position of the origin of the local reference system, if the cartesian coordinate system used is one.
`x`	The X component, in meters.
`y`	The Y component, in meters.
`z`	The Z component, in meters.

Methods Summary

`ONE`([N, origin])	A Cartesian3 instance initialized to (x=1.0, y=1.0, z=1.0).
`UNIT_X`([N, origin])	A Cartesian3 instance initialized to (x=1.0, y=0.0, z=0.0).
`UNIT_Y`([N, origin])	A Cartesian3 instance initialized to (x=0.0, y=1.0, z=0.0).
`UNIT_Z`([N, origin])	A Cartesian3 instance initialized to (x=0.0, y=0.0, z=1.0).
`ZERO`([N, origin])	A Cartesian3 instance initialized to (x=0.0, y=0.0, z=0.0).
`angle_btw`(left, right[, degrees])	Returns the angle formed by two coordinate vectors (in degrees).
`append`(positions)	Create a new Cartesian3 instance with the appended positions.
`centroid`()	Computes the centroid of a set of cartesian points.
`cross`(right)	Computes the cross (outer) product with a provided cartesian point.
`distance`(left, right)	Computes the distance between two cartesian points.
`dot`(right)	Computes the dot (scalar) product with a provided cartesian point.
`from_array`(array[, origin])	Initializes a Cartesian3 instance using a numpy array representing XYZ coordinates.
`interp`(time_sampling, new_time_sampling)	Interpolates the set of Cartesian coordinates on the basis of the sampling times supplied as input.
`is_collection`()	Check if the Cartographic instance represents a set of cartesian points.
`is_local`()	Returns true if the cartesian coordinate system is local and the local origin is defined, false otherwise.
`magnitude`()	Computes the magnitude (length) of the supplied cartesian vector.
`middle`(left, right)	Computes the midpoint between two cartesian points.
`normalize`()	Computes the normalized form of the supplied cartesian point.
`proj_onto`(vector)	Projects the vector described by the current instance onto the provided vector.
`reject_from`(vector)	Rejects the vector described by the current instance from the provided vector.
`save_csv`(filename)	Saves the cartesian point coordinates to a CSV file.
`to_array`()	Converts cartesian point coordinates into a numpy array.
`to_pandas`()	Converts cartesian point coordinates into a Pandas DataFrame.

Attributes Documentation

local_origin¶

Returns the cartographic position of the origin of the local reference system, if the cartesian coordinate system used is one. To obtain its expression in the cartesian ECEF reference system, use the following method sargeom.coordinates.Cartesian3.to_ecef() on the result.

Returns:

sargeom.coordinates.Cartographic: The cartographic position of the origin of the local reference system used.

Raises:

ValueError: If the Cartesian coordinate system used is not a local system.

x¶

The X component, in meters.

Returns:

float or numpy.ndarray: The X component.

Examples

>>> A = Cartesian3(x=10.0, y=20.0, z=30.0)
>>> A.x
array(10.)

>>> A = Cartesian3(x=[10.0, 20.0, 30.0], y=[40.0, 50.0, 60.0], z=[70.0, 80.0, 90.0])
>>> A.x
array([10., 20., 30.])

y¶

The Y component, in meters.

Returns:

float or numpy.ndarray: The Y component.

Examples

>>> A = Cartesian3(x=10.0, y=20.0, z=30.0)
>>> A.y
array(20.)

>>> A = Cartesian3(x=[10.0, 20.0, 30.0], y=[40.0, 50.0, 60.0], z=[70.0, 80.0, 90.0])
>>> A.y
array([40., 50., 60.])

z¶

The Z component, in meters.

Returns:

float or numpy.ndarray: The Z component.

Examples

>>> A = Cartesian3(x=10.0, y=20.0, z=30.0)
>>> A.z
array(30.)

>>> A = Cartesian3(x=[10.0, 20.0, 30.0], y=[40.0, 50.0, 60.0], z=[70.0, 80.0, 90.0])
>>> A.z
array([70., 80., 90.])

Methods Documentation

classmethod ONE(N=(), origin=None)[source]¶

A Cartesian3 instance initialized to (x=1.0, y=1.0, z=1.0).

Parameters:

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

Returns:

sargeom.coordinates.Cartesian3: Instance initialized to (x=1.0, y=1.0, z=1.0).

Examples

>>> Cartesian3.ONE()
XYZ Cartesian3 point
[1. 1. 1.]

>>> Cartesian3.ONE(3)
XYZ Cartesian3 points
[[1. 1. 1.]
 [1. 1. 1.]
 [1. 1. 1.]]

classmethod UNIT_X(N=(), origin=None)[source]¶

A Cartesian3 instance initialized to (x=1.0, y=0.0, z=0.0).

Parameters:

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

Returns:

sargeom.coordinates.Cartesian3: Instance initialized to (x=1.0, y=0.0, z=0.0).

Examples

>>> Cartesian3.UNIT_X()
XYZ Cartesian3 point
[1. 0. 0.]

>>> Cartesian3.UNIT_X(3)
XYZ Cartesian3 points
[[1. 0. 0.]
 [1. 0. 0.]
 [1. 0. 0.]]

classmethod UNIT_Y(N=(), origin=None)[source]¶

A Cartesian3 instance initialized to (x=0.0, y=1.0, z=0.0).

Parameters:

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

Returns:

sargeom.coordinates.Cartesian3: Instance initialized to (x=0.0, y=1.0, z=0.0).

Examples

>>> Cartesian3.UNIT_Y()
XYZ Cartesian3 point
[0. 1. 0.]

>>> Cartesian3.UNIT_Y(3)
XYZ Cartesian3 points
[[0. 1. 0.]
 [0. 1. 0.]
 [0. 1. 0.]]

classmethod UNIT_Z(N=(), origin=None)[source]¶

A Cartesian3 instance initialized to (x=0.0, y=0.0, z=1.0).

Parameters:

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

Returns:

sargeom.coordinates.Cartesian3: Instance initialized to (x=0.0, y=0.0, z=1.0).

Examples

>>> Cartesian3.UNIT_Z()
XYZ Cartesian3 point
[0. 0. 1.]

>>> Cartesian3.UNIT_Z(3)
XYZ Cartesian3 points
[[0. 0. 1.]
 [0. 0. 1.]
 [0. 0. 1.]]

classmethod ZERO(N=(), origin=None)[source]¶

A Cartesian3 instance initialized to (x=0.0, y=0.0, z=0.0).

Parameters:

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

Returns:

sargeom.coordinates.Cartesian3: Instance initialized to (x=0.0, y=0.0, z=0.0).

Examples

>>> Cartesian3.ZERO()
XYZ Cartesian3 point
[0. 0. 0.]

>>> Cartesian3.ZERO(3)
XYZ Cartesian3 points
[[0. 0. 0.]
 [0. 0. 0.]
 [0. 0. 0.]]

static angle_btw(left, right, degrees=True)[source]¶

Returns the angle formed by two coordinate vectors (in degrees).

Parameters:

leftsargeom.coordinates.Cartesian3: The first cartesian point.
rightsargeom.coordinates.Cartesian3: The second cartesian point.
degreesbool, optional: If True (default), returns the angle in degrees. If False, returns the angle in radians.

Returns:

numpy.ndarray: The angle formed by these two coordinate vectors (in degrees).

Examples

>>> A = Cartesian3(x=1.0, y=2.0, z=3.0)
>>> B = Cartesian3(x=4.0, y=5.0, z=6.0)
>>> Cartesian3.angle_btw(A, B) 
array([12.933...])

>>> A = Cartesian3(x=[1.0, 2.0, 3.0], y=[4.0, 5.0, 6.0], z=[7.0, 8.0, 9.0])
>>> B = Cartesian3(x=[4.0, 5.0, 6.0], y=[7.0, 8.0, 9.0], z=[10.0, 11.0, 12.0])
>>> Cartesian3.angle_btw(A, B) 
array([12.195...,  9.076...,  6.982...])

append(positions)[source]¶

Create a new Cartesian3 instance with the appended positions.

Parameters:

positionssequence of sargeom.coordinates.Cartesian3: The sequence of Cartesian3 instances to append.

Returns:

sargeom.coordinates.Cartesian3: The new Cartesian3 instance with the appended positions.

Raises:

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

Examples

>>> A = Cartesian3(x=10.0, y=20.0, z=30.0)
>>> B = Cartesian3(x=15.0, y=25.0, z=35.0)
>>> A.append(B)
XYZ Cartesian3 points
[[10. 20. 30.]
 [15. 25. 35.]]

centroid()[source]¶

Computes the centroid of a set of cartesian points.

Returns:

sargeom.coordinates.Cartesian3: The centroid of the set of cartesian points.

Examples

>>> positions = Cartesian3(
...     x=[1.0, 2.0, 3.0],
...     y=[4.0, 5.0, 6.0],
...     z=[7.0, 8.0, 9.0]
... )
>>> positions.centroid()
XYZ Cartesian3 point
[2. 5. 8.]

cross(right)[source]¶

Computes the cross (outer) product with a provided cartesian point.

Parameters:

rightsargeom.coordinates.Cartesian3: The provided Cartesian point.

Returns:

sargeom.coordinates.Cartesian3: The cross (outer) product with this cartesian point and the provided one.

Examples

>>> A = Cartesian3.UNIT_X()
>>> B = Cartesian3.UNIT_Y()
>>> A.cross(B)
XYZ Cartesian3 point
[0. 0. 1.]

>>> A = Cartesian3(x=[1.0, 0.0, 0.0], y=[0.0, 1.0, 0.0], z=[0.0, 0.0, 1.0])
>>> B = Cartesian3(x=[0.0, 1.0, 0.0], y=[0.0, 0.0, 1.0], z=[1.0, 0.0, 0.0])
>>> A.cross(B)
XYZ Cartesian3 points
[[ 0. -1.  0.]
 [ 0.  0. -1.]
 [-1.  0.  0.]]

static distance(left, right)[source]¶

Computes the distance between two cartesian points.

Parameters:

leftsargeom.coordinates.Cartesian3: The first Cartesian point.
rightsargeom.coordinates.Cartesian3: The second Cartesian point.

Returns:

numpy.ndarray: The distance between these two cartesian points.

Examples

>>> A = Cartesian3(x=1.0, y=2.0, z=3.0)
>>> B = Cartesian3(x=4.0, y=5.0, z=6.0)
>>> Cartesian3.distance(A, B) 
array([5.196...])

>>> A = Cartesian3(x=[1.0, 2.0, 3.0], y=[4.0, 5.0, 6.0], z=[7.0, 8.0, 9.0])
>>> B = Cartesian3(x=[4.0, 5.0, 6.0], y=[7.0, 8.0, 9.0], z=[10.0, 11.0, 12.0])
>>> Cartesian3.distance(A, B) 
array([5.196..., 5.196..., 5.196...])

dot(right)[source]¶

Computes the dot (scalar) product with a provided cartesian point.

Parameters:

rightsargeom.coordinates.Cartesian3: The provided Cartesian point.

Returns:

numpy.ndarray: The dot (scalar) product with this cartesian point and the provided one.

Examples

>>> A = Cartesian3(x=1.0, y=2.0, z=3.0)
>>> B = Cartesian3(x=4.0, y=5.0, z=6.0)
>>> A.dot(B)
array([32.])

>>> A = Cartesian3(x=[1.0, 2.0, 3.0], y=[4.0, 5.0, 6.0], z=[7.0, 8.0, 9.0])
>>> B = Cartesian3(x=[10.0, 20.0, 30.0], y=[40.0, 50.0, 60.0], z=[70.0, 80.0, 90.0])
>>> A.dot(B)
array([ 660.,  930., 1260.])

classmethod from_array(array, origin=None)[source]¶

Initializes a Cartesian3 instance using a numpy array representing XYZ coordinates.

Parameters:

arrayarray_like: A numpy array object representing a list of XYZ 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.

Returns:

sargeom.coordinates.Cartesian3: The Cartesian3 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([1.0, 2.0, 3.0])
>>> Cartesian3.from_array(array)
XYZ Cartesian3 point
[1. 2. 3.]

>>> array = np.array([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])
>>> Cartesian3.from_array(array)
XYZ Cartesian3 points
[[1. 2. 3.]
 [4. 5. 6.]]

interp(time_sampling, new_time_sampling)[source]¶

Interpolates the set of Cartesian coordinates on the basis of the sampling times supplied as input.

Parameters:

time_samplingnumpy.ndarray: Sampling time at which coordinates are acquired.
new_time_samplingnumpy.ndarray: Sampling time at which coordinates will be estimated.

Returns:

sargeom.coordinates.Cartesian3: Estimated cartesian coordinates.

Raises:

ValueError: If this Cartesian3 instance is not a set of cartesian points.

Notes

Interpolation is performed separately for each component (X, Y, and Z) using numpy’s interp function.

Examples

>>> time = np.array([0.0, 1.0, 2.0])
>>> positions = Cartesian3(x=[1.0, 2.0, 3.0], y=[4.0, 5.0, 6.0], z=[7.0, 8.0, 9.0])
>>> new_time = np.array([0.5, 1.5])
>>> positions.interp(time, new_time)
XYZ Cartesian3 points
[[1.5 4.5 7.5]
 [2.5 5.5 8.5]]

is_collection()[source]¶

Check if the Cartographic instance represents a set of cartesian points.

Returns:

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

Examples

>>> A = Cartesian3(x=10.0, y=20.0, z=30.0)
>>> A.is_collection()
False

>>> B = Cartesian3(x=[10.0, 20.0, 30.0], y=[40.0, 50.0, 60.0], z=[70.0, 80.0, 90.0])
>>> B.is_collection()
True

is_local()[source]¶

Returns true if the cartesian coordinate system is local and the local origin is defined, false otherwise.

Returns:

bool: true if the cartesian coordinate system is local and the local origin is defined, false otherwise.

Examples

>>> A = Cartesian3(x=10.0, y=20.0, z=30.0)
>>> A.is_local()
False

magnitude()[source]¶

Computes the magnitude (length) of the supplied cartesian vector.

Returns:

float or ndarray: The magnitude.

Examples

>>> A = Cartesian3(x=3.0, y=4.0, z=0.0)
>>> A.magnitude()
array(5.)

static middle(left, right)[source]¶

Computes the midpoint between two cartesian points.

Parameters:

leftsargeom.coordinates.Cartesian3: The first cartesian point.
rightsargeom.coordinates.Cartesian3: The second cartesian point.

Returns:

sargeom.coordinates.Cartesian3: The midpoint between these two cartesian points.

Examples

>>> A = Cartesian3(x=1.0, y=2.0, z=3.0)
>>> B = Cartesian3(x=4.0, y=5.0, z=6.0)
>>> Cartesian3.middle(A, B)
XYZ Cartesian3 point
[2.5 3.5 4.5]

>>> A = Cartesian3(x=[1.0, 2.0, 3.0], y=[4.0, 5.0, 6.0], z=[7.0, 8.0, 9.0])
>>> B = Cartesian3(x=[4.0, 5.0, 6.0], y=[7.0, 8.0, 9.0], z=[10.0, 11.0, 12.0])
>>> Cartesian3.middle(A, B)
XYZ Cartesian3 points
[[ 2.5  5.5  8.5]
 [ 3.5  6.5  9.5]
 [ 4.5  7.5 10.5]]

normalize()[source]¶

Computes the normalized form of the supplied cartesian point.

Returns:

sargeom.coordinates.Cartesian3: The normalized cartesian point.

Notes

The normalized cartesian point is obtained by dividing each component by the Euclidean norm of the point.

Examples

>>> A = Cartesian3(x=3.0, y=4.0, z=0.0)
>>> A.normalize()
XYZ Cartesian3 point
[0.6 0.8 0. ]

proj_onto(vector)[source]¶

Projects the vector described by the current instance onto the provided vector.

Parameters:

vectorsargeom.coordinates.Cartesian3: The vector to project onto.

Returns:

sargeom.coordinates.Cartesian3: The projection vector.

Raises:

ValueError: If the vector is not a single Cartesian3 instance.

Notes

The projection vector is obtained by computing the dot product of the current instance with the provided vector, dividing by the magnitude of the provided vector, and multiplying the result by the normalized provided vector.

Examples

>>> A = Cartesian3(x=1.0, y=2.0, z=3.0)
>>> B = Cartesian3(x=2.0, y=3.0, z=4.0)
>>> A.proj_onto(B) 
XYZ Cartesian3 point
[ 7.427... 11.141... 14.855...]

reject_from(vector)[source]¶

Rejects the vector described by the current instance from the provided vector.

Parameters:

vectorsargeom.coordinates.Cartesian3: The vector to reject from.

Returns:

sargeom.coordinates.Cartesian3: The rejection vector.

Raises:

ValueError: If the vector is not a single Cartesian3 instance.

Notes

The rejection vector is obtained by subtracting the projection vector from the current instance.

Examples

>>> A = Cartesian3(x=1.0, y=2.0, z=3.0)
>>> B = Cartesian3(x=2.0, y=3.0, z=4.0)
>>> A.reject_from(B) 
XYZ Cartesian3 point
[ -6.427...  -9.141... -11.855...]

save_csv(filename)[source]¶

Saves the cartesian point coordinates to a CSV file.

Parameters:

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

Examples

>>> positions = Cartesian3(x=1.0, y=2.0, z=3.0)
>>> positions.save_csv("positions.csv")

to_array()[source]¶

Converts cartesian point coordinates into a numpy array.

Returns:

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

Examples

>>> position = Cartesian3(x=1.0, y=2.0, z=3.0)
>>> position.to_array()
array([1., 2., 3.])

to_pandas()[source]¶

Converts cartesian point coordinates into a Pandas DataFrame.

Returns:

pandas.DataFrame: A Pandas object initialized with the point coordinates.

Examples

>>> positions = Cartesian3(x=1.0, y=2.0, z=3.0)
>>> positions.to_pandas()
     x    y    z
0  1.0  2.0  3.0