ros_sugar.io.datatypes#

Data containers for ROS message payloads processed by callbacks.

Module Contents#

Classes#

PointCloudData

Container for sensor_msgs/PointCloud2 data.

LaserScanData

Single scan from a planar laser range-finder (LiDAR)

CameraIntrinsics

Container for sensor_msgs/CameraInfo data.

Functions#

read_camera_info

Read the pinhole parameters out of a sensor_msgs/CameraInfo message.

API#

class ros_sugar.io.datatypes.PointCloudData#

Bases: ros_sugar.config.BaseAttrs

Container for sensor_msgs/PointCloud2 data.

Carries the raw (undecoded) point buffer along with the layout metadata needed to interpret it. Consumers that operate on the raw buffer pay no decoding cost. Consumers that want cartesian points can use the lazily decoded xyz property.

Parameters:

  • data – Raw point buffer as a flat uint8 array

  • point_step – Length of a single point in bytes

  • row_step – Length of a single row in bytes

  • height – Number of rows (1 for unorganized clouds)

  • width – Number of points per row

  • x_offset – Byte offset of the ‘x’ field within a point

  • y_offset – Byte offset of the ‘y’ field within a point

  • z_offset – Byte offset of the ‘z’ field within a point

  • x_field_datatype – Datatype of the coordinate fields as a sensor_msgs/PointField datatype constant (FLOAT32 assumed if not set)

  • is_bigendian – Endianness of the point buffer

  • frame_id – Coordinates frame of the cloud

  • timestamp – Message timestamp in seconds

property xyz: Optional[numpy.ndarray]#

Cartesian points decoded from the raw buffer, lazily and cached.

Non-finite points (NaN/inf padding in organized clouds) are dropped.

Returns:

Nx3 float32 array of finite points, or None if the cloud has no x/y/z fields

Return type:

Optional[np.ndarray]

filtered(translation: Optional[Sequence[float]] = None, rotation: Optional[Sequence[float]] = None, frame_id: Optional[str] = None, min_z: Optional[float] = None, max_z: Optional[float] = None, discard_underground: bool = False, get_2d: bool = False) → Optional[ros_sugar.io.datatypes.PointCloudData]#

A new cloud with the transform and the height filters applied.

Rebuilds raw buffer rather than only the decoded xyz, for downstream consumers of it.

Whole point records are kept or dropped and only x/y/z are rewritten, so every other field (intensity, rgb, …) survives intact.

Parameters:

  • translation – Sensor-to-target translation [x, y, z]

  • rotation – Sensor-to-target rotation quaternion [x, y, z, w]

  • frame_id – Frame the points end up in once transformed

  • min_z – Drop points below this height, in the target frame

  • max_z – Drop points above this height, in the target frame

  • discard_underground – Drop points below the ground plane. The transform’s z translation is the sensor’s height above the target frame, so the ground sits at z = 0 once transformed. Without a transform the ground cannot be located and this is ignored.

  • get_2d – Flatten the surviving points onto z = 0

Returns:

A new container, or None if no point survives

Return type:

Optional[PointCloudData]

asdict(filter: Optional[Callable] = None) → Dict#
to_dict() → Dict#
asdict_explicit() → Dict#
from_dict(dict_obj: Dict) → None#
from_file(file_path: str, nested_root_name: Union[str, None] = None, get_common: bool = False) → bool#
to_json() → Union[str, bytes, bytearray]#
from_json(json_obj: Union[str, bytes, bytearray]) → None#
has_attribute(attr_name: str) → bool#
get_attribute_type(attr_name: str) → Optional[type]#
update_value(attr_name: str, attr_value: Any) → bool#
classmethod get_fields_info(class_object) → Dict[str, Dict[str, Any]]#
class ros_sugar.io.datatypes.LaserScanData#

Bases: ros_sugar.config.BaseAttrs

Single scan from a planar laser range-finder (LiDAR)

attributes: angle_min float32 start angle of the scan [rad] angle_max float32 end angle of the scan [rad] angle_increment float32 angular distance between measurements [rad]

time_increment float32 time between measurements [seconds] - if your scanner is moving, this will be used in interpolating position of 3d points

scan_time float32 time between scans [seconds] range_min float32 minimum range value [m] range_max float32 maximum range value [m]

ranges List[float32] range data [m] (Note: values < range_min or > range_max should be discarded) angles float32[] angle of each range measurement [rad] (generated from the angle limits and increment if not provided) intensities float32[] intensity data [device-specific units]. If your device does not provide intensities, please leave the array empty. frame_id string coordinates frame of the scan timestamp float message timestamp in seconds

get_ranges(right_angle: float, left_angle: float) → numpy.ndarray#

Get ranges values in a defined zone between a left angle and a right angle

Parameters:

  • right_angle (float) – Value of the angle on the right of the ranges (rad)

  • left_angle (float) – Value of the angle on the left of the ranges (rad)

Returns:

Ranges values in the specified zone

Return type:

np.ndarray

get_angles(right_angle: float, left_angle: float) → numpy.ndarray#

Get angles values in a defined zone between a left angle and a right angle

Parameters:

  • right_angle (float) – Value of the angle on the right of the ranges (rad)

  • left_angle (float) – Value of the angle on the left of the ranges (rad)

Returns:

Angles values in the specified zone

Return type:

np.ndarray

asdict(filter: Optional[Callable] = None) → Dict#
to_dict() → Dict#
asdict_explicit() → Dict#
from_dict(dict_obj: Dict) → None#
from_file(file_path: str, nested_root_name: Union[str, None] = None, get_common: bool = False) → bool#
to_json() → Union[str, bytes, bytearray]#
from_json(json_obj: Union[str, bytes, bytearray]) → None#
has_attribute(attr_name: str) → bool#
get_attribute_type(attr_name: str) → Optional[type]#
update_value(attr_name: str, attr_value: Any) → bool#
classmethod get_fields_info(class_object) → Dict[str, Dict[str, Any]]#
class ros_sugar.io.datatypes.CameraIntrinsics#

Bases: ros_sugar.config.BaseAttrs

Container for sensor_msgs/CameraInfo data.

Carries the pinhole parameters that make an image metrically meaningful, which is what a consumer needs to turn a pixel into a direction in space (and, with a depth value, into a point).

Values are taken from the rectified projection matrix P when it is set, falling back to the raw intrinsics K, and are corrected for binning and for a region of interest, so they always describe the image as actually published rather than the sensor’s full frame.

When P was used the intrinsics describe the rectified image and distortion is empty — feed them rectified (or registered) frames. Only the K fallback pairs with the raw image and its distortion coefficients; distortion_model is reported in both cases as sensor metadata.

Parameters:

  • fx – Focal length in pixels along x

  • fy – Focal length in pixels along y

  • cx – Principal point in pixels along x

  • cy – Principal point in pixels along y

  • width – Width of the published image in pixels

  • height – Height of the published image in pixels

  • distortion_model – Distortion model named by the camera driver

  • distortion – Distortion coefficients, empty for a rectified image

  • frame_id – Optical frame the camera reports in

  • timestamp – Message timestamp in seconds

property matrix: numpy.ndarray#

Intrinsics as a 3x3 camera matrix

property focal_length: numpy.ndarray#

Focal length as (fx, fy)

property principal_point: numpy.ndarray#

Principal point as (cx, cy)

matches(width: int, height: int) → bool#

Whether these intrinsics describe an image of the given size.

Intrinsics that do not match the image they are used with put every deprojected point in the wrong place, so consumers should check.

Parameters:

  • width – Image width in pixels

  • height – Image height in pixels

asdict(filter: Optional[Callable] = None) → Dict#
to_dict() → Dict#
asdict_explicit() → Dict#
from_dict(dict_obj: Dict) → None#
from_file(file_path: str, nested_root_name: Union[str, None] = None, get_common: bool = False) → bool#
to_json() → Union[str, bytes, bytearray]#
from_json(json_obj: Union[str, bytes, bytearray]) → None#
has_attribute(attr_name: str) → bool#
get_attribute_type(attr_name: str) → Optional[type]#
update_value(attr_name: str, attr_value: Any) → bool#
classmethod get_fields_info(class_object) → Dict[str, Dict[str, Any]]#
ros_sugar.io.datatypes.read_camera_info(msg) → ros_sugar.io.datatypes.CameraIntrinsics#

Read the pinhole parameters out of a sensor_msgs/CameraInfo message.

When the rectified projection P is set, the returned intrinsics describe the rectified image. A consumer working on the raw stream of a distorted camera needs K with the distortion coefficients instead, which is only what this returns when the driver leaves P unset.

Parameters:

msg – sensor_msgs/CameraInfo message

Returns:

Camera intrinsics describing the published image

Return type:

CameraIntrinsics