Perception Tool Kit (PTK) API Guide

Introduction

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.

Collaboration diagram for PTK Point:

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

Macro Definition Documentation

◆ PTK_PointCloud_getPoints

#define PTK_PointCloud_getPoints (   pc)    (PTK_Point*)((uint8_t*)pc + pc->pointOffset)

Macro for getting a pointer to the point representation.

◆ PTK_POINTCLOUD_INVALID_POINT

#define PTK_POINTCLOUD_INVALID_POINT   (~0U)

Constant for marking invalid result.

Typedef Documentation

◆ PTK_Point

Definition of a point.

◆ PTK_Point_d

Definition of a double precision Point.

Function Documentation

◆ PTK_Point_set()

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.

Parameters
[out]dstPTK_Point struct to be modified.
[in]xNew x coordinate.
[in]yNew y coordinate.
[in]zNew z coordinate.

◆ PTK_Vector_add()

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.

Parameters
[out]dstResulting vector.
[in]src1First source vector to be added.
[in]src2Second source vector to be added.

◆ PTK_Vector_subtract()

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.

Parameters
[out]dstResulting vector.
[in]src1The term subtracted from.
[in]src2The term being subtracted.

◆ PTK_Vector_scale()

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.

Parameters
[out]dstResulting vector.
[in]srcThe vector to be scaled.
[in]scaleThe magnitude of the scale factor.

◆ PTK_Point_transform()

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.

Parameters
[out]dstResulting vector.
[in]srcThe point to be transformed.
[in]MThe transformation to apply to src.

◆ PTK_Vector_dot2()

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.

Parameters
[in]p1First vector for dot product.
[in]p2Second vector for dot product.
Returns
Dot product value.

◆ PTK_Vector_dot3()

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.

Parameters
[in]p1First vector for dot product.
[in]p2Second vector for dot product.
Returns
Dot product value.

◆ PTK_Vector_dot4()

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.

Parameters
[in]p1First vector for dot product.
[in]p2Second vector for dot product.
Returns
Dot product value.

◆ PTK_Vector_computeCrossProduct()

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.

Parameters
[out]dstResulting vector.
[in]aFirst vector for cross product.
[in]bSecond vector for cross product.

◆ PTK_Vector_computeNorm()

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

Parameters
[in]vVector whose norm is to be computed.
Returns
Computed norm.

◆ PTK_Vector_normalize()

float PTK_Vector_normalize ( PTK_Vector *__restrict  dst,
const PTK_Vector *__restrict  in 
)

Normalizes the given input vector and writes to an output vector.

Parameters
[out]dstResulting normalized vector.
[in]inVector to be normalized.
Returns
Inverse of the vector norm i.e. 1.0/norm(v).

◆ PTK_Point_tag()

void PTK_Point_tag ( PTK_Point pt,
uint32_t  tag 
)

This sets tag bits for the given point.

Parameters
[out]ptThe point to tag.
[in]tagTag bits to be applied.

◆ PTK_Point_untag()

void PTK_Point_untag ( PTK_Point pt,
uint32_t  tag 
)

This removes tag bits for the given point.

Parameters
[out]ptThe point to untag.
[in]tagTag bits to be removed.

◆ PTK_Point_isTagged()

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.

Parameters
[out]ptPoint whose tag bits are to be queried.
[in]tagThe tag bits to check for.
Returns
  • 1 if all of the given tag bits are set
  • 0, otherwise

◆ PTK_Point_d_set()

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.

Parameters
[out]dstPTK_Point struct to be modified.
[in]xNew x coordinate.
[in]yNew y coordinate.
[in]zNew z coordinate.

◆ PTK_Vector_d_add()

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.

Parameters
[out]dstResulting vector.
[in]src1First source vector to be added.
[in]src2Second source vector to be added.

◆ PTK_Vector_d_subtract()

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.

Parameters
[out]dstResulting vector.
[in]src1The term subtracted from.
[in]src2The term being subtracted.

◆ PTK_Vector_d_scale()

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.

Parameters
[out]dstResulting vector.
[in]srcThe vector to be scaled.
[in]scaleThe magnitude of the scale factor.

◆ PTK_Point_d_transform()

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.

Parameters
[out]dstResulting vector.
[in]srcThe point to be transformed.
[in]MThe transformation to apply to src.

◆ PTK_Vector_d_dot2()

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.

Parameters
[in]p1First vector for dot product.
[in]p2Second vector for dot product.
Returns
Dot product value.

◆ PTK_Vector_d_dot3()

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.

Parameters
[in]p1First vector for dot product.
[in]p2Second vector for dot product.
Returns
Dot product value.

◆ PTK_Vector_d_dot4()

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.

Parameters
[in]p1First vector for dot product.
[in]p2Second vector for dot product.
Returns
Dot product value.

◆ PTK_Point_d_tag()

void PTK_Point_d_tag ( PTK_Point_d pt,
uint32_t  tag 
)

This sets tag bits for the given point.

Parameters
[out]ptThe point to tag.
[in]tagTag bits to be applied.

◆ PTK_Point_d_untag()

void PTK_Point_d_untag ( PTK_Point_d pt,
uint32_t  tag 
)

This removes tag bits for the given point.

Parameters
[out]ptThe point to untag.
[in]tagTag bits to be removed.

◆ PTK_Point_d_isTagged()

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.

Parameters
[out]ptPoint whose tag bits are to be queried.
[in]tagThe tag bits to check for.
Returns
  • 1 if all of the given tag bits are set
  • 0, otherwise