Motion<T> and Motion<T, TDerivative>

Motion<T> holds a coordinate value and zero or more derivatives. For example, a Motion<Cartesian> is typically used to represent translational motion and holds a Cartesian position vector plus an optional Cartesian velocity vector, Cartesian acceleration vector, etc.

Motion<T, TDerivative> also holds a value and zero or more derivatives, but in this case the coordinate value and the derivatives are represented using different types. A common example of this is a Motion<UnitQuaternion, Cartesian>, which is typically used to represent rotational motion and holds a UnitQuaternion rotation plus an optional Cartesian rotational velocity vector, Cartesian rotational acceleration vector, etc.

You can obtain the coordinate value of a Motion<T> or Motion<T, TDerivative> instance by accessing the Value property. For example:

Motion<Cartesian> translationalMotion = GetTranslationalMotion();
Cartesian position = translationalMotion.Value;

Motion<UnitQuaternion, Cartesian> rotationalMotion = GetRotationalMotion();
UnitQuaternion rotation = rotationalMotion.Value;

Similarly, you can access the first and second derivatives:

Motion<Cartesian> translationalMotion = GetTranslationalMotion();
Cartesian velocity = translationalMotion.FirstDerivative;
Cartesian acceleration = translationalMotion.SecondDerivative;

Motion<UnitQuaternion, Cartesian> rotationalMotion = GetRotationalMotion();
Cartesian rotationalVelocity = rotationalMotion.FirstDerivative;
Cartesian rotationalAcceleration = rotationalMotion.SecondDerivative;

You can access higher-order derivatives by using Further derivatives can be accessed using the indexer (ItemInt32).

Motion<Cartesian> translationalMotion = GetTranslationalMotion();
Cartesian jerk = translationalMotion[3];

Motion<UnitQuaternion, Cartesian> rotationalMotion = GetRotationalMotion();
Cartesian rotationalJerk = rotationalMotion[3];

If an instance does not have a first, second, or higher-order derivative, it will throw an ArgumentOutOfRangeException when you attempt to access that derivative. You can determine the highest-order derivative available from a particular motion instance by accessing the Order property.

Methods that return Motion<T> or Motion<T, TDerivative> often accept an order parameter. This parameter indicates the highest derivative that the caller of the function would like returned. The order parameter is primarily an optimization which allows the method to avoid wasting time computing higher derivatives if they will not be utilized. An order of 0 indicates that you require only the coordinate value and not any of its derivatives. An order of 1 requests the first derivative in addition to the coordinate value. An order of 2 requests the coordinate value, its first derivative, and its second derivative. An arbitrarily high order can be requested, though not all methods will be able to fulfill all requests.

If a method is not able to provide a requested derivative, an exception or other error will not occur. Instead, the method will simply provide the highest derivative that it is able to provide. It is up to the caller of the method to verify that a required derivative is present in the return value.