weldx.CoordinateSystemManager.get_cs#

CoordinateSystemManager.get_cs(coordinate_system_name, reference_system_name=None, time=None, time_ref=None)#

Get a coordinate system in relation to another reference system.

If no reference system is specified, the parent system will be used as reference.

If any coordinate system that is involved in the coordinate transformation has a time dependency, the returned coordinate system will most likely be also time dependent. This won’t be the case if only a single time value is passed or if the passed time values do not overlap with any of the time dependent coordinate systems’ time ranges.

The timestamps of the returned system depend on the functions time parameter. By default, the time union of all involved coordinate systems is taken.

Parameters:
Returns:

The requested coordinate system.

Return type:

LocalCoordinateSystem

Notes

Reference time of the returned system

The reference time of the returned coordinate system depends on multiple factors like the one passed to the function and the internally stored reference times. Generally, the following rules apply:

  • if a reference time was passed to the function, it will be used as reference time of the returned coordinate system as long as a time was also passed to the function.

  • else the reference time of the CoordinateSystemManager will be used if it has one

  • if only the coordinate systems have a reference time, the lowest (earliest) will be used

  • if there is no reference time at all, the resulting coordinate system won’t have one either

  • if no time was passed to the function, a passed reference time will be ignored

  • a pandas.DatetimeIndex always has its lowest date as implicit reference time which will be used if the CoordinateSystemManager doesn’t possess one and the functions reference time isn’t set.

A overview of all possible combinations using a pandas.TimedeltaIndex or a pint.Quantity as time parameter is given in the table below.

function has time

function has reference time

CSM has reference time

CS have reference times

Returned system uses reference time of

Yes

Yes

Yes

all/mixed/none

function

No

Yes

Yes

all/mixed/none

CSM

Yes / No

No

Yes

all/mixed/none

CSM

Yes

Yes

No

all

function

No

Yes

No

all

CS (lowest)

Yes / No

Yes / No

No

mixed

impossible -> 1.

Yes

Yes

No

none

error -> 2.

No

Yes

No

none

None

Yes / No

No

No

all

CS (lowest)

Yes / No

No

No

none

None

  1. This case can not occur since it is not allowed to add a combination of coordinate systems with and without reference time to a CoordinateSystemManager without own reference time. See add_cs documentation for further details

  2. If neither the CoordinateSystemManager nor its attached coordinate systems have a reference time, the intention of passing a time and a reference time to the function is unclear. The caller might be unaware of the missing reference times. Therefore an exception is raised. If your intention is to add a reference time to the resulting coordinate system, you should call this function without a specified reference time and add it explicitly to the returned LocalCoordinateSystem.

Information regarding the implementation:

It is important to mention that all coordinate systems that are involved in the transformation should be interpolated to a common time line before they are combined using the LocalCoordinateSystem ‘s __add__ and __sub__ functions. If this is not done before, serious interpolation errors for rotations can occur. The reason is, that those operators also perform time interpolations if the timestamps of 2 systems do not match. When chaining multiple transformations already interpolated values might be used to perform another interpolation.

To see why this is problematic, consider a coordinate system which is statically attached to a not moving but rotating parent coordinate system. If it gets transformed to the reference systems of its parent, it will follow a circular trajectory around the parent system. For discrete timestamps, the trajectory is described by a set of corresponding coordinates. If we now interpolate again, the positions between those coordinates will be interpolated linearly, ignoring the originally circular trajectory. The dependency on the rotating parent system is not considered in further transformations.

Additionally, if the transformed system is rotating itself, the transformation to the parent’s reference system might cause the rotation angle between to time steps to exceed 180 degrees. Since the SLERP always takes the shortest angle between 2 keyframes, further interpolations wrongly change the rotation order.