Python package for coordinate conversions

• Python package for coordinate conversions
  • Usage
  • Mounttree
    • Coordinate frames
    • Mounttree structure
    • Open variables

This package allows to convert position and direction vectors between different coordinate frames. These frames must be arranged in a so called "mounttree", a tree-like structure which defines their relative orientation.

Usage

Load a mounttree in yaml format to get a CoordinateUniverse object

import mounttree as mnt
universe=mnt.load_mounttree('test/testmounttree.yaml')

If there are open variables in the tree, specify them before use:

universe.update(lat=0, lon=0, height=10, roll=0, pitch=0, yaw=0)

Now, we can get a transformation from 'HALO' to 'EARTH' coordinates

transform=universe.get_transformation('HALO','EARTH')

Use the transformation to convert positional or direction vectors

p1=transform.apply_point(0, 0, 0)
p2=transform.apply_direction(0, 1, 0)

We can also convert multiple points at once, if we provide numpy arrays of coordinates.

import numpy as np
x=np.array([[0,0,0],[0,1,1]])
y=np.array([[0,1,1],[0,0,0]])
z=np.array([[0,0,0],[1,1,1]])
px, py, pz=transform.apply_point(x,y,z)

We can also update the mounttree with multiple locations which differ, e.g., in the height coordinate as shown here:

universe.update(lat=[0, 0], lon=[0, 0], height=[10, 100], roll=[0, 0], pitch=[0, 0], yaw=[0, 0])

Note: With universe.variables, you can have a look at the variables of the mounttree.

We specify the transformation:

transform_multiple_locations = universe.get_transformation('HALO','EARTH')

and apply the transformation as before. In this case, the point (0, 0, 0) and the direction (0, 1, 0) are transformed from 'HALO' to 'EARTH' for the two HALO positions defined above.

p1 = transform_multiple_locations.apply_point(0,0,0)
p2 = transform_multiple_locations.apply_direction(0,1,0)
print(p1)
(array([6378147., 6378237.]), array([0., 0.]), array([0., 0.]))
print(p2)
(array([0., 0.]), array([1., 1.]), array([0., 0.]))

For the transformation of the same but multiple points/directions to different HALO positions, repeat the array according to the number of positions. For example, the transformation of the different viewing angles of a polarization camera of specMACS (view_dirs_HALO_coords with shape (2040, 2440, 3)) from 'HALO' to 'EARTH' coordinates for the two different positions would look like this:

vx, vy, vz = transform_multiple_locations.apply_direction(*np.array([view_dirs_HALO_coords, view_dirs_HALO_coords]).transpose(3,1,2,0))
view_dirs_EARTH_coords = np.stack([xv, vy, vz])
print(view_dirs_EARTH_coords.shape)
(2, 2040, 2440, 3)

In the next example, we will apply the transformation to two different points which correspond to the two different HALO positions:

import numpy as np
x = np.array([0, 0])
y = np.array([0, 0])
z = np.array([0, 333])
px, py, pz = transform_multiple_locations.apply_point(x,y,z)

Again, we see the difference in the px element:

print(px)
array([6378147., 6377904.])

Note: So far, the combination (= transform N vectors at M different mounttree positions, which would result in N x M transformed vectors) is not possible. In this case, just loop over the smaller number of N or M.

Mounttree

Coordinate frames

Coordinate frames are objects to relate tuples of numbers (coordinates) to points in space. A point can be expressed in natural coordinates and cartesian coordinates. Each coordinate frame must provide functions to convert between natural and cartesian coordinates. Additionally, there must be a function to provide a natural orientation at each point in space. In mounttree_py, there are some predefined coordinate frames which are specified by the framespec keyword. Examples are 'WGS-84' and 'GRS-80' geospatial coordinate frames, where natural coordinates are latitude, longitude and height and natural orientation lets the x-axis of subframes point northward. If framespec is not given, a CartesianCoordinateFrame is assumed, where natural and cartesian coordinates are similar.

#Example how to specify a coordinate frame
framename: EARTH
framespec: WGS-84
position: [0,0,0]
rotation: [0,0,0]

Mounttree structure

A mounttree is a tree-like datastructure containing different coordinate frames with their relative orientation (see https://nbn-resolving.org/urn:nbn:de:bvb:19-261616, sec. 3.3.2). There must be exactly one root coordinate frame in the tree. Each coordinate frame can have any number of child frames, specified by the subframes keyword. A child frame in the tree needs a position and rotation relative to the parent.

Positions must be given as three floating point numbers in natural coordinates of the parent frame.

Rotations are assumed to be three floating point numbers, interpreted as euler angles relative to the local frame orientation of the parent frame at the childframe's position. Euler angles are in the "roll, pitch, yaw" convention, i.e. as sequence of rotations around 'x', 'y' and 'z' axis. Alternatively, a single string of a form similar to Ry(-85deg)*Rz(-90deg) can be provided at initialization, defining the rotation as a product of rotation matrices.

framename: EARTH
framespec: WGS-84
subframes:
    - framename: HALO
        position: [10.2,20.7,6000]
        rotation: [0,0,90]
        subframes:
            - framename: VNIR
            position: [0, 0, 0]
            rotation: Ry(-85deg)*Rz(-90deg)

Open variables

Instead of defining position and rotation of frames as three floating point numbers, some of the numbers can also be replaced by arbitrary strings. In this case, the strings are interpreted as open variables and must be associated to numbers with the "universe.update()" method before they can be used for transformations. If a transformation is requested and open variables without associated numbers are found to be necessary for this transformation, an error is thrown.

#Examples for open variables
framename: HALO
position: [lat, lon, height]
rotation: [roll, pitch, yaw]