TapeMeasure – Measuring distances between frames

class trep.TapeMeasure(system, frames)

Parameters:

• system – The System that the frames belong to.
• frames – A list of Frame objects or frame names.

A TapeMeasure object calculates the length of the line you get from playing “connect the dots” with the origins of a list of coordinate frames. TapeMeasure can calculate the length of the line and its derivatives with respect to configuration variables, and the velocity of the length (\(\tfrac{dx}{dt}\)) and its derivatives.

(figure here)

TapeMeasure can be used as the basis for new constraints, potentials, and forces, or used independently for your own calculations.

Length and Velocity Calculations

Let \((p_0, p_1, p_2 \dots p_{n} )\) be the points at the origins of the frames specified by frames. The length, \(x\) is calculated as follows.

\[v_k = p_{k+1} - p_k\]\[x_k = \sqrt{v_k^T v_k}\]\[x = \sum_{k=0}^{n-1} x_k\]

The velocity is calculated by applying the chain rule to \(x\):

\[\dot{x} = \sum_k \sum_i \frac{\partial x_k}{\partial q_i} \dot{q}_i\]

These calculations, and their derivatives, are optimized internally to take advantage of the fact that many of these terms are zero, significantly reducing the amount of calculation to do.

See the internal documentation on TapeMeasure for more details about the implementation and for the equations to calculate the derivatives.

Warning

The derivatives of the length and velocity do not exist when the length of any part of the segment is zero. TapeMeasure does not check for this condition and will return NaN or cause a divide-by-zero error. Be careful to avoid these cases.

TapeMeasure Objects

TapeMeasure.system

The system that the TapeMeasure works in.

(read-only)

TapeMeasure.frames

A tuple of Frame objects that define the lines being measured.

(read-only)

TapeMeasure.length()

Return type:Float

Calculate the total length of the line segments at the system’s current configuration.

TapeMeasure.length_dq(q1)

Parameters:q1 (Config) – Derivative variable Return type:Float

Calculate the derivative of the length with respect to the value of q1.

TapeMeasure.length_dqdq(q1, q2)

Parameters:

• q1 (Config) – Derivative variable
• q2 (Config) – Derivative variable

Return type:

Float

Calculate the second derivative of the length with respect to the value of q1 and the value of q2.

TapeMeasure.length_dqdqdq(q1, q2, q3)

Parameters:

• q1 (Config) – Derivative variable
• q2 (Config) – Derivative variable
• q3 (Config) – Derivative variable

Return type:

Float

Calculate the third derivative of the length with respect to the value of q1, the value of q2, and the value of q3.

TapeMeasure.velocity()

Return type:Float

TapeMeasure.velocity_dq(q1)

Parameters:q1 (Config) – Derivative variable Return type:Float

Calculate the derivative of the velocity with respect to the value of q1.

TapeMeasure.velocity_ddq(dq1)

Parameters:dq1 (Config) – Derivative variable Return type:Float

Calculate the derivative of the velocity with respect to the velocity of q1.

TapeMeasure.velocity_dqdq(q1, q2)

Parameters:

• q1 (Config) – Derivative variable
• q2 (Config) – Derivative variable

Return type:

Float

Calculate the second derivative of the velocity with respect to the value of q1 and the value of q2.

TapeMeasure.velocity_dddqdq(dq1, dq2)

Parameters:

• dq1 (Config) – Derivative variable
• q2 (Config) – Derivative variable

Return type:

Float

Calculate the second derivative of the velocity with respect to the velocity of q1 and the value of q2.

Visualization

TapeMeasure.opengl_draw(width=1.0, color=(1.0, 1.0, 1.0))

Draw a representation of the line defined by the TapeMeasure with the specified width and color. The current OpenGL coordinate system should be the root coordinate frame of the System.

This method can be called by constraints, forces, and potentials that are based on the TapeMeasure.

Verifying Derivatives

TapeMeasure.validate_length_dq([delta=1e-6, tolerance=1e-6, verbose=False])

TapeMeasure.validate_length_dqdq([delta=1e-6, tolerance=1e-6, verbose=False])

TapeMeasure.validate_length_dqdqdq([delta=1e-6, tolerance=1e-6, verbose=False])

TapeMeasure.validate_velocity_dq([delta=1e-6, tolerance=1e-6, verbose=False])

TapeMeasure.validate_velocity_ddq([delta=1e-6, tolerance=1e-6, verbose=False])

TapeMeasure.validate_velocity_dqdq([delta=1e-6, tolerance=1e-6, verbose=False])

TapeMeasure.validate_velocity_ddqdq([delta=1e-6, tolerance=1e-6, verbose=False])

Unlike Constraint, Potential, and Force, TapeMeasure is used directly and all of the calculations are already implemented and verified. These functions are primarily used for testing during developement, but they might be useful for debugging if you are using a TapeMeasure and having trouble.