API Documentation

Transform

The Transform API provides an interface to perform linear transformations on coordinate frames.

PolySync provides a set of standard coordinate frames used within PolySync provided nodes. These are provided through the core.idl datamodel file (i.e. PSYNC_COORDINATE_FRAME_PLATFORM). You can use custom coordinate frames given that the identifier value does not conflict with the PolySync standard identifiers.

The API uses the notion of parent and child identifiers to distinguish between the current coordinate frame identifier (the parent), and a coordinate frame identifier that exist in the stack (a child).

Example view of a stack using all of the PolySync standard coordinate frames:

This stack would transform a vector in the local frame to a vector in the absolute frame.

Usage #include <polysync_transform.h>

Functions

psync_transform_apply (…)

This will apply transform to a vector in $R^3$.

psync_transform_apply uses the transform stack to apply a transformation to the given vector. That is, given an input vector in the first child’s coordinate frame, apply the transform stack to get an output vector in the parent’s coordinate frame.

Parameters
in/out type name description
in ps_transform *const transform A pointer to ps_transform that specifies the configuration.
in const double ix Input X coordinate.
in const double iy Input Y coordinate.
in const double iz Input Z coordinate.
out double *const ox A pointer to double that receives the output X coordinate.
out double *const oy A pointer to double that receives the output Y coordinate.
out double *const oz A pointer to double that receives the output Z coordinate.
Returns

psync_transform_apply_subframe ( … )

This will apply child transform to a vector in $R^3$.

psync_transform_apply_subframe uses the transform stack to apply a transformation to the given vector. That is, given an input vector in the first child’s coordinate frame, apply the transform stack to get an output vector in the given child coordinate frame.

Parameters
in/out type name description
in ps_transform *const transform A pointer to ps_transform that specifies the configuration.
in const ps_identifier child_id The coordinate frame identifier of the child frame to use.
in const double ix Input X coordinate.
in const double iy Input Y coordinate.
in const double iz Input Z coordinate.
out double *const ox A pointer to double that receives the output X coordinate.
out double *const oy A pointer to double that receives the output Y coordinate.
out double *const oz A pointer to double that receives the output Z coordinate.
Returns

psync_transform_copy_stack ( … )

This will copy transform data into a ‘ps_transform_stack’.

Parameters
in/out type name description
in const ps_transform *const transform A pointer to ps_transform that specifies the configuration.
out ps_transform_stack *const stack A pointer to ps_transform_stack that receives the configuration.
Returns

psync_transform_get_orientation_rpy ( … )

This will get a transform orientation roll/pitch/yaw vector.

psync_transform_get_orientation_rpy gets the orientation roll/pitch/yaw vector from a transform (either the parent or in the stack) by its coordinate frame identifier.

Parameters
in/out type name description
in ps_transform *const transform A pointer to ps_transform that specifies the configuration.
in const ps_identifier id Coordinate frame identifier to search for.
out double *const roll A pointer to double that receives the X axis rotation value. [radians]
out double *const pitch A pointer to double that receives the Y axis rotation value. [radians]
out double *const yaw A pointer to double that receives the Z axis rotation value. [radians]
Returns

psync_transform_get_origin ( … )

This will get a transform origin vector.

psync_transform_get_origin gets the origin vector from a transform (either the parent or in the stack) by its coordinate frame identifier.

Parameters
in/out type name description
in ps_transform *const transform A pointer to ps_transform that specifies the configuration.
in const ps_identifier id The coordinate frame identifier to search for.
out double *const x A pointer to double that receives the X position value. [meters]
out double *const y A pointer to double that receives the Y position value. [meters]
out double *const z A pointer to double that receives the Z position value. [meters]
Returns

psync_transform_get_timestamp ( … )

This will get a timestamp of transform.

psync_transform_get_timestamp gets the timestamp from the transform, given the coordinate frame identifier.

Parameters
in/out type name description
in const ps_transform *const transform A pointer to ps_transform that specifies the configuration.
in const ps_identifier id The coordinate frame identifier to search for.
out ps_timestamp *const timestamp A pointer to ps_timestamp that receives the timestamp value.
Returns

psync_transform_init ( … )

This will initialize a transform.

psync_transform_init initializes a transform, allocating dynamic resources. It sets ps_transform::id to the default PSYNC_COORDINATE_FRAME_LOCAL frame.

Parameters
in/out type name description
in ps_transform *const transform A pointer to ps_transform that receives the configuration.
Returns
  • DTC code:
    • DTC_NONE - (Zero) if success
    • DTC_USAGE - If argument is invalid
    • DTC_MEMERR - If memory allocation failed

psync_transform_is_frame_available ( … )

This will check if a coordinate frame is available in the transform.

psync_transform_is_frame_available checks the parent and the stack for the given identifier.

Parameters
in/out type name description
in ps_transform *const transform A pointer to ps_transform that specifies the configuration.
in const ps_identifier parent_id The coordinate frame identifier of the new parent frame.
Returns

psync_transform_pop ( … )

This will pop the top transform off the stack.

psync_transform_pop sets ps_transform::id to the child’s ID that is being removed.

It updates the orientation roll/pitch/yaw vector in a transform (either the parent or in the stack) by its coordinate frame identifier. The function also updates the timestamp of the parent.

Parameters
in/out type name description
in ps_transform *const transform A pointer to ps_transform that receives the configuration.
Returns

psync_transform_push ( … )

This will push the current transform onto the stack.

psync_transform_push pushes the current transform on the transformation stack as a child to the parent coordinate frame identifier. The function sets ps_transform::id to parent_id, and updates the timestamp of the parent and the child transformation.

Once a push operation is done, the transform becomes part of the overall transformation.

Parameters
in/out type name description
in ps_transform *const transform A pointer to ps_transform that receives the configuration.
in const ps_identifier parent_id The coordinate frame identifier of the new parent frame.
Returns

psync_transform_quaternion_to_rpy ( … )

This will convert quaternion to roll/pitch/yaw.

Parameters
in/out type name description
in const double qx Quaternion X value.
in const double qy Quaternion Y value.
in const double qz Quaternion Z value.
in const double qw Quaternion world value.
out double *const roll A pointer to double that receives the X axis rotation value. [radians]
out double *const pitch A pointer to double that receives the Y axis rotation value. [radians]
out double *const yaw A pointer to double that receives the Z axis rotation value. [radians]
Returns

psync_transform_release ( … )

This will release a transform.

psync_transform_release releases the dynamic memory, if any exist. It sets ps_transform::id to PSYNC_COORDINATE_FRAME_LOCAL.

Parameters
in/out type name description
in ps_transform *const transform A pointer to ps_transform that receives the configuration.
Returns

psync_transform_rpy_to_quaternion (…)

This will convert roll/pitch/yaw to quaternion.

Parameters
in/out type name description
in const double roll X axis rotation. [radians]
in const double pitch Y axis rotation. [radians]
in const double yaw Z axis rotation. [radians]
out double *const qx A pointer to double that receives the quaternion X value.
out double *const qy A pointer to double that receives the quaternion Y value.
out double *const qz A pointer to double that receives the quaternion Z value.
out double *const qw A pointer to double that receives the quaternion world value.
Returns

psync_transform_set_orientation_rpy ( … )

This will set a transform orientation roll/pitch/yaw vector.

Parameters
in/out type name description
in ps_transform *const transform A pointer to ps_transform that receives the configuration.
in const double roll X axis rotation of the origin. [radians]
in const double pitch Y axis rotation of the origin. [radians]
in const double yaw Z axis rotation of the origin. [radians]
Returns

psync_transform_set_origin ( … )

This will set a transform origin vector.

Parameters
in/out type name description
in ps_transform const * transform A pointer to ps_transform that receives the configuration.
in const double x X position of the origin. [meters]
in const double y Y position of the origin. [meters]
in const double z Z position of the origin. [meters]
Returns

psync_transform_update_orientation_rpy ( … )

This will update a transform orientation roll/pitch/yaw vector.

psync_transform_update_orientation_rpy updates the orientation roll/pitch/yaw vector in a transform (either the parent or in the stack) by its coordinate frame identifier.

This function updates the timestamp of the parent and the child transformation.

Parameters
in/out type name description
in ps_transform *const transform A pointer to ps_transform that receives the configuration.
in const ps_identifier id Coordinate frame identifier to search for
in const double roll X axis rotation of the origin. [radians]
in const double pitch Y axis rotation of the origin. [radians]
in const double yaw Z axis rotation of the origin. [radians]
Returns

psync_transform_update_origin (…)

This will update a transform origin vector.

psync_transform_update_origin updates the origin vector in a transform (either the parent or in the stack) by its coordinate frame identifier.
The function updates the timestamp of the parent and the child transformation.

Parameters
in/out type name description
in ps_transform *const transform A pointer to ps_transform that receives the configuration.
in const ps_identifier id The coordinate frame identifier to search for.
in const double x X position of the origin. [meters]
in const double y Y position of the origin. [meters]
in const double z Z position of the origin. [meters]
Returns