PTK Lidar

Introduction

The lidar component provides data structures, drivers for decoding data from Velodyne sensors, and algorithms for performing some basic LiDAR-related processing tasks. LiDAR measurements are stored in a normal PTK_PointCloud as defined in section 3, but an additional metadata structure is used to index this point cloud in scan order, in order to provide information that may accelerate some algorithms which depend on the physical arrangement of the laser scan.

Collaboration diagram for PTK Lidar:

Data Structures
struct	PTK_LidarGatingParams
	Lidar sensor range and angle gating configuration. More...
struct	PTK_LidarMetaConfig
	Metadata structure is used to index lidar point cloud in scan order, in order to provide information that may accelerate some algorithms which depend on the physical arrangement of the laser scan. More...
struct	PTK_LidarMeta
	This is an entirely opaque structure which is populated by the LiDAR driver appropriate to the sensor being used. A convenience method exists for HDL32E sensors to provide sin/cos table for both theta and alpha values (see the Velodyne driver section below). More...
struct	PTK_Lidar_VelodyneRecord
	A single record within a UDP packet is 100 bytes long. More...
struct	PTK_Lidar_VelodynePacket
	Format of the packet reveived from Velodyne HDL-32E unit. More...
struct	PTK_Lidar_VelodyneFrame
	Format of the Lidar frame. More...

Functions
uint32_t	PTK_LidarMeta_getSize (const PTK_LidarMetaConfig *cfg)
	Compute the size of the PTK_LidarMeta struct for the given configuration, in bytes. More...
PTK_LidarMeta *	PTK_LidarMeta_init (uint8_t *mem, const PTK_LidarMetaConfig *cfg)
	Initialize the given piece of user-allocated memory as a PTK_LidarMeta struct and convert the pointer type. More...
void	PTK_LidarMeta_clear (PTK_LidarMeta *meta)
	This clears the given LiDAR metadata struct (but not its configuration) so that it can be reused to record new data received from the LiDAR driver. More...
uint32_t	PTK_LidarMeta_getSlices (const PTK_LidarMeta *meta)
	Get the number of slices contained within a given LiDAR metadata structure. More...
uint32_t	PTK_LidarMeta_getLasers (const PTK_LidarMeta *meta)
	Get the number of lasers contained within a given LiDAR metadata structure. More...
uint64_t	PTK_LidarMeta_getTimestamp (const PTK_LidarMeta *meta, uint32_t slice)
	This reads the timestamp matching when a given slice was captured. If a slice was not captured for the slice number given, the timestamp produced is 0. More...
uint32_t	PTK_LidarMeta_getPointIndex (const PTK_LidarMeta *meta, uint32_t slice, uint32_t laser)
	This looks up the index in the matching PTK_PointCloud for the point identified by the given (slice, laser) combination. If no data was recorded for that coordinate, a value of PTK_POINTCLOUD_INVALID_POINT is returned. More...
void	PTK_LidarMeta_setPointIndex (PTK_LidarMeta *meta, uint32_t slice, uint32_t laser, uint32_t index)
	This stores the index in the matching PTK_PointCloud for the point identified by the given (slice, laser) combination. If the (slice, laser) combination is invalid then no updates are made. More...
void	PTK_Lidar_Velodyne_initParser ()
	This must be called once at startup to initialize the internal structures used to parse LiDAR data from a Velodyne sensor. This is independent of the general PTK initialization routine. More...
void	PTK_Lidar_Velodyne_setHDL32ETrigTables (PTK_LidarMetaConfig *cfg)
	This adds pointers to internally managed trig tables suitable for use with a Velodyne HDL32E to the given LiDAR metadata structure. More...
uint32_t	PTK_Lidar_Velodyne_parse (PTK_Lidar_VelodynePacket *packet, PTK_PointCloud *dst, PTK_LidarMeta *meta)
	This does incremental parsing of an additional packet of data from the Velodyne sensor, appending information to the given PTK_PointCloud and PTK_Lidar meta structures. If a packet does not fit, none of it is inserted to the given point cloud or metadata structure, and a 1 is returned indicating that the packet should be parsed with an empty cloud and metadata structure. More...
uint32_t	PTK_Lidar_Velodyne_mapPhysicalToLogicalLaser (uint32_t laser)
	This converts from the logical laser ordering in a Velodyne data packet to the physical laser order used for determining neighbors. More...

Macros
#define	PTK_LIDAR_DEFAULT_LASER_ENABLE_MASK   (0xFFFFFFFFU)
	Macro for default laser enable status. By default, all 32 lasers are enabled. More...
#define	PTK_LIDAR_MAX_GATING_ANGLE   (180.0)
	Macro for Maximum gating angle in degrees. More...
#define	PTK_LidarMeta_getPointsData(m)   (uint32_t*)((uint8_t*)m + m->pointOffset)
	Macro for getting a pointer to the point data. More...
#define	PTK_LidarMeta_getTimestampData(m)   (uint64_t*)((uint8_t*)m + m->timeOffset)
	Macro for getting a pointer to the timestamp data. More...
#define	PTK_LIDAR_HDL32E_LASERS   (32U)
	Maximum number of sensors for Velodyne HDL-32E module. More...
#define	PTK_LIDAR_HDL32E_RECORDS_PER_PACKET   (12U)
	Number of records per packet. More...
#define	PTK_LIDAR_HDL32E_MAX_PACKETS   (181U)
	Constant for marking invalid result. More...
#define	PTK_LIDAR_HDL32E_SLICES_PER_ROTATION
	Maximum number of slices per rotation, per laser. More...
#define	PTK_LIDAR_HDL32E_POINTS_PER_ROTATION
	Maximum number of points per rotation, across all lasers. More...

Macro Definition Documentation

PTK_LIDAR_DEFAULT_LASER_ENABLE_MASK

#define PTK_LIDAR_DEFAULT_LASER_ENABLE_MASK   (0xFFFFFFFFU)

Macro for default laser enable status. By default, all 32 lasers are enabled.

PTK_LIDAR_MAX_GATING_ANGLE

#define PTK_LIDAR_MAX_GATING_ANGLE   (180.0)

Macro for Maximum gating angle in degrees.

PTK_LidarMeta_getPointsData

#define PTK_LidarMeta_getPointsData

(

m

)

(uint32_t*)((uint8_t*)m + m->pointOffset)

Macro for getting a pointer to the point data.

PTK_LidarMeta_getTimestampData

#define PTK_LidarMeta_getTimestampData

(

m

)

(uint64_t*)((uint8_t*)m + m->timeOffset)

Macro for getting a pointer to the timestamp data.

PTK_LIDAR_HDL32E_LASERS

#define PTK_LIDAR_HDL32E_LASERS   (32U)

Maximum number of sensors for Velodyne HDL-32E module.

PTK_LIDAR_HDL32E_RECORDS_PER_PACKET

#define PTK_LIDAR_HDL32E_RECORDS_PER_PACKET   (12U)

Number of records per packet.

PTK_LIDAR_HDL32E_MAX_PACKETS

#define PTK_LIDAR_HDL32E_MAX_PACKETS   (181U)

Constant for marking invalid result.

PTK_LIDAR_HDL32E_SLICES_PER_ROTATION

#define PTK_LIDAR_HDL32E_SLICES_PER_ROTATION

Value:

(PTK_LIDAR_HDL32E_MAX_PACKETS *\
                                              PTK_LIDAR_HDL32E_RECORDS_PER_PACKET)

Maximum number of slices per rotation, per laser.

PTK_LIDAR_HDL32E_POINTS_PER_ROTATION

#define PTK_LIDAR_HDL32E_POINTS_PER_ROTATION

Value:

(PTK_LIDAR_HDL32E_SLICES_PER_ROTATION *\
                                              PTK_LIDAR_HDL32E_LASERS)

Maximum number of points per rotation, across all lasers.

Function Documentation

PTK_LidarMeta_getSize()

uint32_t PTK_LidarMeta_getSize

(

const PTK_LidarMetaConfig *

cfg

)

Compute the size of the PTK_LidarMeta struct for the given configuration, in bytes.

Parameters

[in]

cfg

LiDAR metadata configuration parameters.

Returns

Size required in bytes.

PTK_LidarMeta_init()

PTK_LidarMeta* PTK_LidarMeta_init	(	uint8_t *	mem,
		const PTK_LidarMetaConfig *	cfg
	)

Initialize the given piece of user-allocated memory as a PTK_LidarMeta struct and convert the pointer type.

Parameters

[out]	mem	Pointer to externally allocated memory to initialize.
[in]	cfg	Configuration to use when initializing this memory.

Returns

Initialized meta data object.

PTK_LidarMeta_clear()

void PTK_LidarMeta_clear

(

PTK_LidarMeta *

meta

)

This clears the given LiDAR metadata struct (but not its configuration) so that it can be reused to record new data received from the LiDAR driver.

Parameters

[out]

meta

The metadata to clear.

PTK_LidarMeta_getSlices()

uint32_t PTK_LidarMeta_getSlices

(

const PTK_LidarMeta *

meta

)

Get the number of slices contained within a given LiDAR metadata structure.

Parameters

[in]

meta

The LiDAR metadata to read.

Returns

The number of slices.

PTK_LidarMeta_getLasers()

uint32_t PTK_LidarMeta_getLasers

(

const PTK_LidarMeta *

meta

)

Get the number of lasers contained within a given LiDAR metadata structure.

Parameters

[in]

meta

The LiDAR metadata to read.

Returns

The number of lasers.

PTK_LidarMeta_getTimestamp()

uint64_t PTK_LidarMeta_getTimestamp	(	const PTK_LidarMeta *	meta,
		uint32_t	slice
	)

This reads the timestamp matching when a given slice was captured. If a slice was not captured for the slice number given, the timestamp produced is 0.

Parameters

[in]	meta	The LiDAR metadata to read.
[in]	slice	The slice number to look up.

Returns

Timestamp when the requested slice was recorded. If a slice was not captured for the slice number given, 0 is returned.

PTK_LidarMeta_getPointIndex()

uint32_t PTK_LidarMeta_getPointIndex	(	const PTK_LidarMeta *	meta,
		uint32_t	slice,
		uint32_t	laser
	)

This looks up the index in the matching PTK_PointCloud for the point identified by the given (slice, laser) combination. If no data was recorded for that coordinate, a value of PTK_POINTCLOUD_INVALID_POINT is returned.

Parameters

[in]	meta	The LiDAR metadata to read.
[in]	slice	The slice number to look up.
[in]	laser	The laser number to look up.

Returns

• The matching point cloud index, is found
• PTK_POINTCLOUD_INVALID_POINT, otherwise

PTK_LidarMeta_setPointIndex()

void PTK_LidarMeta_setPointIndex	(	PTK_LidarMeta *	meta,
		uint32_t	slice,
		uint32_t	laser,
		uint32_t	index
	)

This stores the index in the matching PTK_PointCloud for the point identified by the given (slice, laser) combination. If the (slice, laser) combination is invalid then no updates are made.

Parameters

[in,out]	meta	The LiDAR metadata to write to.
[in]	slice	The slice number to look up.
[in]	laser	The laser number to look up.
[in]	index	Index value to write.

PTK_Lidar_Velodyne_initParser()

void PTK_Lidar_Velodyne_initParser

(

)

This must be called once at startup to initialize the internal structures used to parse LiDAR data from a Velodyne sensor. This is independent of the general PTK initialization routine.

PTK_Lidar_Velodyne_setHDL32ETrigTables()

void PTK_Lidar_Velodyne_setHDL32ETrigTables

(

PTK_LidarMetaConfig *

cfg

)

This adds pointers to internally managed trig tables suitable for use with a Velodyne HDL32E to the given LiDAR metadata structure.

Parameters

[in]

cfg

The config to attach table pointers to.

PTK_Lidar_Velodyne_parse()

uint32_t PTK_Lidar_Velodyne_parse	(	PTK_Lidar_VelodynePacket *	packet,
		PTK_PointCloud *	dst,
		PTK_LidarMeta *	meta
	)

This does incremental parsing of an additional packet of data from the Velodyne sensor, appending information to the given PTK_PointCloud and PTK_Lidar meta structures. If a packet does not fit, none of it is inserted to the given point cloud or metadata structure, and a 1 is returned indicating that the packet should be parsed with an empty cloud and metadata structure.

Parameters

[in]	packet	The raw packet as received from the sensor.
[in]	dst	The point cloud to write decoded points to.
[in]	meta	The metadata structure to record additional information to.

Returns

• 0 if the packet was parsed completely
• 1 if the packet would not fit in the given cloud or metadata structure

PTK_Lidar_Velodyne_mapPhysicalToLogicalLaser()

uint32_t PTK_Lidar_Velodyne_mapPhysicalToLogicalLaser

(

uint32_t

laser

)

This converts from the logical laser ordering in a Velodyne data packet to the physical laser order used for determining neighbors.

Parameters

[in]

laser

The laser number within a packet.

Returns

The physical location of that laser in the scanner.