![]() |
Perception Tool Kit (PTK) API Guide
|
The geometry component provides a common framework for representing and manipulating geometric quantities, such as points, vectors, and transformations between coordinate spaces. These are fundamental elements which are used to build most other components. For example, Points structs are necessary to represent position information in the geodesy component, and RigidTransforms are needed to represent the conversion between coordinate systems.
Mathematically, a "point" with 3 coordinates and a "vector" with 3 components are similar and we may implicitly convert between a point and a vector from the origin to a point. They are however, semantically distinct, leading to the natural requirement for distinct types. In the interest of providing ease of use and reusing implementation logic where possible, point and vector types are provided as aliases of the same type, ptk abstract vector, and the specific type name used in a function description is used to indicate the semantic usage of that function. For instance, points are not added together, but vectors are. Points may be further broken down by the coordinate system they are associated with, and this is stored within the metadata field.
The abstract vector type has a fixed layout on all platforms, shown below, chosen for effective memory alignment and compatibility with C7x, ARM, and x86 architectures. Although it is largely a transparent structure, several convenience functions are provided for interacting with its fields, and the metadata union should only be accessed through the provided API.
Note that PTK_Point and PTK Vector are aliases and thus may be supplied interchangeably to all of the functions below, but the appropriate semantic name is used in determining the function name and as the argument type.
![]() |
Data Structures | |
union | PTK_Vector_Meta |
Definition of vector meta data. More... | |
struct | PTK_Vector |
Definition of a point. More... | |
union | PTK_Vector_d_Meta |
Definition of doube precision vector meta data. More... | |
struct | PTK_Vector_d |
Definition of a double precision Vector. More... | |
struct | PTK_2D_Vector |
Definition of a 2D point. More... | |
Functions | |
void | PTK_Point_set (PTK_Point *dst, float x, float y, float z) |
Updates all three components stored within the given PTK_Point to match those given as arguments, to be used primarily for convenience when initializing a point. More... | |
void | PTK_Vector_add (PTK_Vector *dst, const PTK_Vector *src1, const PTK_Vector *src2) |
Perform component-wise addition of the vectors stored in src1 and src2, writing the result to dst. More... | |
void | PTK_Vector_subtract (PTK_Vector *dst, const PTK_Vector *src1, const PTK_Vector *src2) |
Perform component-wise subtraction, subtracting src2 from src1 and writing the result to dst. More... | |
void | PTK_Vector_scale (PTK_Vector *dst, const PTK_Vector *src, float scale) |
Perform component-wise scaling of the given PTK Vector and store the result at dst. More... | |
void | PTK_Point_transform (PTK_Point *dst, const PTK_Point *src, const PTK_RigidTransform *M) |
Perform a rigid transformation on the given point, d = (Mr*s) + Mt. More... | |
float | PTK_Vector_dot2 (const PTK_Vector *p1, const PTK_Vector *p2) |
Compute the dot product of the two given vectors in 2D, given by r = ax*bx + ay*by. More... | |
float | PTK_Vector_dot3 (const PTK_Vector *p1, const PTK_Vector *p2) |
Compute the dot product of the two given vectors in 3D, given by r = ax*bx + ay*by + az*bz. More... | |
float | PTK_Vector_dot4 (const PTK_Vector *p1, const PTK_Vector *p2) |
Compute the dot product of the two given vectors in 3D, given by r = ax*bx + ay*by + az*bz + aw*bw. More... | |
void | PTK_Vector_computeCrossProduct (PTK_Vector *__restrict dst, const PTK_Vector *__restrict a, const PTK_Vector *__restrict b) |
Computes the cross product of the two given vectors in 3D, given by rx = ay*bz - az*by ry = az*bx - ax*bz rz = ax*by - ay*bx. More... | |
float | PTK_Vector_computeNorm (const PTK_Vector *v) |
Computes the L2 norm of the given vector, given by v = sqrt(vx*vx + vy*vy + vz*vz). More... | |
float | PTK_Vector_normalize (PTK_Vector *__restrict dst, const PTK_Vector *__restrict in) |
Normalizes the given input vector and writes to an output vector. More... | |
void | PTK_Point_tag (PTK_Point *pt, uint32_t tag) |
This sets tag bits for the given point. More... | |
void | PTK_Point_untag (PTK_Point *pt, uint32_t tag) |
This removes tag bits for the given point. More... | |
uint32_t | PTK_Point_isTagged (PTK_Point *pt, uint32_t tag) |
This checks if all of the bits set in tag are also set in the tag for the given PTK_Point. Additional bits may be set, but none may be missing from the given mask. More... | |
void | PTK_Point_d_set (PTK_Point_d *dst, double x, double y, double z) |
Updates all three components stored within the given PTK_Point to match those given as arguments, to be used primarily for convenience when initializing a point. More... | |
void | PTK_Vector_d_add (PTK_Vector_d *dst, PTK_Vector_d *src1, PTK_Vector_d *src2) |
Perform component-wise addition of the vectors stored in src1 and src2, writing the result to dst. More... | |
void | PTK_Vector_d_subtract (PTK_Vector_d *dst, PTK_Vector_d *src1, PTK_Vector_d *src2) |
Perform component-wise subtraction, subtracting src2 from src1 and writing the result to dst. More... | |
void | PTK_Vector_d_scale (PTK_Vector_d *dst, PTK_Vector_d *src, double scale) |
Perform component-wise scaling of the given PTK Vector and store the result at dst. More... | |
void | PTK_Point_d_transform (PTK_Point_d *dst, PTK_Point_d *src, const PTK_RigidTransform_d *M) |
Perform a rigid transformation on the given point, d = (Mr*s) + Mt. More... | |
double | PTK_Vector_d_dot2 (const PTK_Vector_d *p1, const PTK_Vector_d *p2) |
Compute the dot product of the two given vectors in 2D, given by r = ax*bx + ay*by. More... | |
double | PTK_Vector_d_dot3 (const PTK_Vector_d *p1, const PTK_Vector_d *p2) |
Compute the dot product of the two given vectors in 3D, given by r = ax*bx + ay*by + az*bz. More... | |
double | PTK_Vector_d_dot4 (const PTK_Vector_d *p1, const PTK_Vector_d *p2) |
Compute the dot product of the two given vectors in 3D, given by r = ax*bx + ay*by + az*bz + aw*bw. More... | |
void | PTK_Point_d_tag (PTK_Point_d *pt, uint32_t tag) |
This sets tag bits for the given point. More... | |
void | PTK_Point_d_untag (PTK_Point_d *pt, uint32_t tag) |
This removes tag bits for the given point. More... | |
uint32_t | PTK_Point_d_isTagged (PTK_Point_d *pt, uint32_t tag) |
This checks if all of the bits set in tag are also set in the tag for the given PTK_Point. Additional bits may be set, but none may be missing from the given mask. More... | |
Typedefs | |
typedef PTK_Vector | PTK_Point |
Definition of a point. More... | |
typedef PTK_Vector_d | PTK_Point_d |
Definition of a double precision Point. More... | |
Macros | |
#define | PTK_PointCloud_getPoints(pc) (PTK_Point*)((uint8_t*)pc + pc->pointOffset) |
Macro for getting a pointer to the point representation. More... | |
#define | PTK_POINTCLOUD_INVALID_POINT (~0U) |
Constant for marking invalid result. More... | |
#define PTK_PointCloud_getPoints | ( | pc | ) | (PTK_Point*)((uint8_t*)pc + pc->pointOffset) |
Macro for getting a pointer to the point representation.
#define PTK_POINTCLOUD_INVALID_POINT (~0U) |
Constant for marking invalid result.
typedef PTK_Vector PTK_Point |
Definition of a point.
typedef PTK_Vector_d PTK_Point_d |
Definition of a double precision Point.
void PTK_Point_set | ( | PTK_Point * | dst, |
float | x, | ||
float | y, | ||
float | z | ||
) |
Updates all three components stored within the given PTK_Point to match those given as arguments, to be used primarily for convenience when initializing a point.
[out] | dst | PTK_Point struct to be modified. |
[in] | x | New x coordinate. |
[in] | y | New y coordinate. |
[in] | z | New z coordinate. |
void PTK_Vector_add | ( | PTK_Vector * | dst, |
const PTK_Vector * | src1, | ||
const PTK_Vector * | src2 | ||
) |
Perform component-wise addition of the vectors stored in src1 and src2, writing the result to dst.
[out] | dst | Resulting vector. |
[in] | src1 | First source vector to be added. |
[in] | src2 | Second source vector to be added. |
void PTK_Vector_subtract | ( | PTK_Vector * | dst, |
const PTK_Vector * | src1, | ||
const PTK_Vector * | src2 | ||
) |
Perform component-wise subtraction, subtracting src2 from src1 and writing the result to dst.
[out] | dst | Resulting vector. |
[in] | src1 | The term subtracted from. |
[in] | src2 | The term being subtracted. |
void PTK_Vector_scale | ( | PTK_Vector * | dst, |
const PTK_Vector * | src, | ||
float | scale | ||
) |
Perform component-wise scaling of the given PTK Vector and store the result at dst.
[out] | dst | Resulting vector. |
[in] | src | The vector to be scaled. |
[in] | scale | The magnitude of the scale factor. |
void PTK_Point_transform | ( | PTK_Point * | dst, |
const PTK_Point * | src, | ||
const PTK_RigidTransform * | M | ||
) |
Perform a rigid transformation on the given point, d = (Mr*s) + Mt.
[out] | dst | Resulting vector. |
[in] | src | The point to be transformed. |
[in] | M | The transformation to apply to src. |
float PTK_Vector_dot2 | ( | const PTK_Vector * | p1, |
const PTK_Vector * | p2 | ||
) |
Compute the dot product of the two given vectors in 2D, given by r = ax*bx + ay*by.
[in] | p1 | First vector for dot product. |
[in] | p2 | Second vector for dot product. |
float PTK_Vector_dot3 | ( | const PTK_Vector * | p1, |
const PTK_Vector * | p2 | ||
) |
Compute the dot product of the two given vectors in 3D, given by r = ax*bx + ay*by + az*bz.
[in] | p1 | First vector for dot product. |
[in] | p2 | Second vector for dot product. |
float PTK_Vector_dot4 | ( | const PTK_Vector * | p1, |
const PTK_Vector * | p2 | ||
) |
Compute the dot product of the two given vectors in 3D, given by r = ax*bx + ay*by + az*bz + aw*bw.
Note that this reads the w field from the metadata, so it cannot be used to store tag bits simultaneously.
[in] | p1 | First vector for dot product. |
[in] | p2 | Second vector for dot product. |
void PTK_Vector_computeCrossProduct | ( | PTK_Vector *__restrict | dst, |
const PTK_Vector *__restrict | a, | ||
const PTK_Vector *__restrict | b | ||
) |
Computes the cross product of the two given vectors in 3D, given by rx = ay*bz - az*by ry = az*bx - ax*bz rz = ax*by - ay*bx.
[out] | dst | Resulting vector. |
[in] | a | First vector for cross product. |
[in] | b | Second vector for cross product. |
float PTK_Vector_computeNorm | ( | const PTK_Vector * | v | ) |
Computes the L2 norm of the given vector, given by v = sqrt(vx*vx + vy*vy + vz*vz).
[in] | v | Vector whose norm is to be computed. |
float PTK_Vector_normalize | ( | PTK_Vector *__restrict | dst, |
const PTK_Vector *__restrict | in | ||
) |
Normalizes the given input vector and writes to an output vector.
[out] | dst | Resulting normalized vector. |
[in] | in | Vector to be normalized. |
void PTK_Point_tag | ( | PTK_Point * | pt, |
uint32_t | tag | ||
) |
This sets tag bits for the given point.
[out] | pt | The point to tag. |
[in] | tag | Tag bits to be applied. |
void PTK_Point_untag | ( | PTK_Point * | pt, |
uint32_t | tag | ||
) |
This removes tag bits for the given point.
[out] | pt | The point to untag. |
[in] | tag | Tag bits to be removed. |
uint32_t PTK_Point_isTagged | ( | PTK_Point * | pt, |
uint32_t | tag | ||
) |
This checks if all of the bits set in tag are also set in the tag for the given PTK_Point. Additional bits may be set, but none may be missing from the given mask.
[out] | pt | Point whose tag bits are to be queried. |
[in] | tag | The tag bits to check for. |
void PTK_Point_d_set | ( | PTK_Point_d * | dst, |
double | x, | ||
double | y, | ||
double | z | ||
) |
Updates all three components stored within the given PTK_Point to match those given as arguments, to be used primarily for convenience when initializing a point.
[out] | dst | PTK_Point struct to be modified. |
[in] | x | New x coordinate. |
[in] | y | New y coordinate. |
[in] | z | New z coordinate. |
void PTK_Vector_d_add | ( | PTK_Vector_d * | dst, |
PTK_Vector_d * | src1, | ||
PTK_Vector_d * | src2 | ||
) |
Perform component-wise addition of the vectors stored in src1 and src2, writing the result to dst.
[out] | dst | Resulting vector. |
[in] | src1 | First source vector to be added. |
[in] | src2 | Second source vector to be added. |
void PTK_Vector_d_subtract | ( | PTK_Vector_d * | dst, |
PTK_Vector_d * | src1, | ||
PTK_Vector_d * | src2 | ||
) |
Perform component-wise subtraction, subtracting src2 from src1 and writing the result to dst.
[out] | dst | Resulting vector. |
[in] | src1 | The term subtracted from. |
[in] | src2 | The term being subtracted. |
void PTK_Vector_d_scale | ( | PTK_Vector_d * | dst, |
PTK_Vector_d * | src, | ||
double | scale | ||
) |
Perform component-wise scaling of the given PTK Vector and store the result at dst.
[out] | dst | Resulting vector. |
[in] | src | The vector to be scaled. |
[in] | scale | The magnitude of the scale factor. |
void PTK_Point_d_transform | ( | PTK_Point_d * | dst, |
PTK_Point_d * | src, | ||
const PTK_RigidTransform_d * | M | ||
) |
Perform a rigid transformation on the given point, d = (Mr*s) + Mt.
[out] | dst | Resulting vector. |
[in] | src | The point to be transformed. |
[in] | M | The transformation to apply to src. |
double PTK_Vector_d_dot2 | ( | const PTK_Vector_d * | p1, |
const PTK_Vector_d * | p2 | ||
) |
Compute the dot product of the two given vectors in 2D, given by r = ax*bx + ay*by.
[in] | p1 | First vector for dot product. |
[in] | p2 | Second vector for dot product. |
double PTK_Vector_d_dot3 | ( | const PTK_Vector_d * | p1, |
const PTK_Vector_d * | p2 | ||
) |
Compute the dot product of the two given vectors in 3D, given by r = ax*bx + ay*by + az*bz.
[in] | p1 | First vector for dot product. |
[in] | p2 | Second vector for dot product. |
double PTK_Vector_d_dot4 | ( | const PTK_Vector_d * | p1, |
const PTK_Vector_d * | p2 | ||
) |
Compute the dot product of the two given vectors in 3D, given by r = ax*bx + ay*by + az*bz + aw*bw.
Note that this reads the w field from the metadata, so it cannot be used to store tag bits simultaneously.
[in] | p1 | First vector for dot product. |
[in] | p2 | Second vector for dot product. |
void PTK_Point_d_tag | ( | PTK_Point_d * | pt, |
uint32_t | tag | ||
) |
This sets tag bits for the given point.
[out] | pt | The point to tag. |
[in] | tag | Tag bits to be applied. |
void PTK_Point_d_untag | ( | PTK_Point_d * | pt, |
uint32_t | tag | ||
) |
This removes tag bits for the given point.
[out] | pt | The point to untag. |
[in] | tag | Tag bits to be removed. |
uint32_t PTK_Point_d_isTagged | ( | PTK_Point_d * | pt, |
uint32_t | tag | ||
) |
This checks if all of the bits set in tag are also set in the tag for the given PTK_Point. Additional bits may be set, but none may be missing from the given mask.
[out] | pt | Point whose tag bits are to be queried. |
[in] | tag | The tag bits to check for. |