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:

coordinate_system_name (str) – Name of the coordinate system.
reference_system_name (Optional[str]) – Name of the reference coordinate system.
time (Union[DatetimeIndex, datetime64, list[str], Time, TimedeltaIndex, Quantity, timedelta64, Timestamp, str, TimeDependent, None]) – Specifies the desired time of the returned coordinate system. You can also pass the name of another coordinate system to use its time attribute as reference.
time_ref (Union[Timestamp, str, Time, None]) – The desired reference time of the returned coordinate system.

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`

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