YASMIN PCL

YASMIN PCL provides reusable YASMIN states for point cloud processing. It integrates the Point Cloud Library (PCL) with YASMIN’s state machine framework, enabling declarative point cloud pipelines using blackboard-based data exchange. The package includes 14 states covering format conversion, file I/O, and filtering.

Point Cloud Types

All states exchange data through the YASMIN blackboard using the following type aliases defined in yasmin_pcl/common/cloud_types.hpp:

Alias Underlying Type
RosPointCloud2Ptr std::shared_ptr<sensor_msgs::msg::PointCloud2>
PclPointCloud2Ptr pcl::PCLPointCloud2::Ptr
PclPointCloud2ConstPtr pcl::PCLPointCloud2::ConstPtr
Indices pcl::Indices
ModelCoefficients pcl::ModelCoefficients
Vector4fArray std::array<float, 4>

I/O States

Six states handle point cloud format conversion and file I/O. All states produce an outcome of succeeded or aborted.

RosToPclPointCloud2State

Converts a ROS sensor_msgs::msg::PointCloud2 message to a PCL PCLPointCloud2.

Direction Key Type
Input input_cloud RosPointCloud2Ptr
Output output_cloud PclPointCloud2Ptr

PclToRosPointCloud2State

Converts a PCL PCLPointCloud2 to a ROS sensor_msgs::msg::PointCloud2 message.

Direction Key Type
Input input_cloud PclPointCloud2Ptr
Output output_cloud RosPointCloud2Ptr

LoadPcdState

Loads a PCD (Point Cloud Data) file into memory.

Direction Key Type
Output output_cloud PclPointCloud2Ptr
Output sensor_origin Vector4fArray
Output sensor_orientation Vector4fArray
Output pcd_version int

Parameters:

  • file_path (string, required) — path to the PCD file

SavePcdState

Saves a point cloud to a PCD file.

Direction Key Type
Input input_cloud PclPointCloud2Ptr

Parameters:

  • file_path (string, required) — output file path
  • storage_mode (string, default: "binary") — ascii, binary, or binary_compressed
  • origin_x, origin_y, origin_z, origin_w (float, default: 0) — sensor position
  • orientation_x, orientation_y, orientation_z, orientation_w (float, default: 0,0,0,1) — sensor orientation quaternion

LoadPlyState

Loads a PLY (Polygon File Format) file into memory.

Direction Key Type
Output output_cloud PclPointCloud2Ptr
Output sensor_origin Vector4fArray
Output sensor_orientation Vector4fArray

Parameters:

  • file_path (string, required) — path to the PLY file

SavePlyState

Saves a point cloud to a PLY file.

Direction Key Type
Input input_cloud PclPointCloud2Ptr

Parameters:

  • file_path (string, required) — output file path
  • binary_mode (bool, default: true) — use binary encoding
  • use_camera (bool, default: false) — add camera info to the file
  • origin_x, origin_y, origin_z, origin_w (float, default: 0) — sensor position
  • orientation_x, orientation_y, orientation_z, orientation_w (float, default: 0,0,0,1) — sensor orientation quaternion

Filter States

Eight filter states process point clouds. Every filter reads input_cloud (PclPointCloud2Ptr) and writes output_cloud (PclPointCloud2Ptr). An optional input_indices (Indices) key restricts processing to a subset of points. When extract_removed_indices is enabled, the removed point indices are written to removed_indices (Indices). All filters produce an outcome of succeeded or aborted.

Common Filter Parameters

Parameter Type Default Description
negative bool false Invert the filter logic
keep_organized bool false Preserve cloud structure using NaN values
user_filter_value float NaN Replacement value for organized clouds
extract_removed_indices bool false Capture removed point indices

PassThroughState

Filters points by the value of a single field, keeping only those within the specified range.

Parameter Type Default Description
filter_field_name string "z" Point field to filter on
filter_limit_min double 0.0 Lower range bound
filter_limit_max double 1.0 Upper range bound
filter_limit_negative bool false Keep points outside the range

CropBoxState

Removes points outside an axis-aligned or rotated bounding box.

Parameter Type Default Description
min_x / min_y / min_z float -1.0 Minimum corner
max_x / max_y / max_z float 1.0 Maximum corner
translation_x / y / z float 0.0 Box center offset
rotation_roll / pitch / yaw float 0.0 Box orientation (radians)
use_transform bool false Apply an additional affine transform

VoxelGridState

Downsamples the cloud by replacing all points within each voxel with their centroid.

Parameter Type Default Description
leaf_size_x / y / z float 0.1 Voxel dimensions
downsample_all_data bool true Downsample all fields, not just XYZ
minimum_points_number_per_voxel int 0 Minimum points per voxel to keep

ExtractIndicesState

Extracts specific points by an index list. Requires input_indices to be set on the blackboard.

This state only uses the common filter parameters.

StatisticalOutlierRemovalState

Removes outliers by computing the mean distance to k-nearest neighbors and discarding points beyond the threshold.

Parameter Type Default Description
mean_k int 10 Number of neighbors for mean distance
stddev_mul_thresh double 1.0 Standard deviation multiplier — higher values keep more points

RadiusOutlierRemovalState

Removes isolated points that have fewer than the required number of neighbors within a search radius.

Parameter Type Default Description
radius_search double 1.0 Neighborhood search radius
min_neighbors_in_radius int 1 Minimum neighbors to keep the point

RandomSampleState

Randomly samples a subset of points from the cloud.

Parameter Type Default Description
sample int 1 Target number of samples
seed int — Random seed for reproducibility

In addition to output_cloud, this state also writes output_indices (Indices) with the sampled point indices.

ProjectInliersState

Projects points onto a geometric model such as a plane, sphere, or cylinder.

Direction Key Type
Input input_cloud PclPointCloud2Ptr
Input (required) input_model_coefficients ModelCoefficients
Input (optional) input_indices Indices
Output output_cloud PclPointCloud2Ptr
Parameter Type Default Description
model_type int 0 PCL model enum (0 = SACMODEL_PLANE, 1 = SACMODEL_SPHERE, 2 = SACMODEL_CYLINDER, …)
copy_all_fields bool — Copy all point fields to the output
copy_all_data bool — Copy all point data to the output

Plugin Identifiers

All 14 states are exported via pluginlib under the yasmin_pcl_states library. Use the identifiers below with the YASMIN CLI or XML factory: 

# I/O
yasmin_pcl/RosToPclPointCloud2State
yasmin_pcl/PclToRosPointCloud2State
yasmin_pcl/LoadPcdState
yasmin_pcl/SavePcdState
yasmin_pcl/LoadPlyState
yasmin_pcl/SavePlyState

# Filters
yasmin_pcl/PassThroughState
yasmin_pcl/CropBoxState
yasmin_pcl/VoxelGridState
yasmin_pcl/ExtractIndicesState
yasmin_pcl/StatisticalOutlierRemovalState
yasmin_pcl/RadiusOutlierRemovalState
yasmin_pcl/RandomSampleState
yasmin_pcl/ProjectInliersState

You can list them from the command line with:

ros2 yasmin list --type cpp --search pcl