Point Cloud Registration

Experimental API for ICP-based local point cloud registration: aligns a source point cloud to a target using an optional initial-pose guess. Resides in Zivid::Experimental::Toolbox and may change without prior notice.

        %%{init: {'themeVariables': {'fontSize': '18px'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 35}}}%%
flowchart LR
  SourcePC["PointCloud (source)"]
  TargetPC["PointCloud (target)"]

  registrationOp(["localPointCloudRegistration()"])
  transformOp(["transform()"])
  residualOp(["residual()"])

  LocalPointCloudRegistrationResult
  Matrix4x4
  Residual["residual (mm)"]

  SourcePC -.-> registrationOp --> LocalPointCloudRegistrationResult
  TargetPC -.-> registrationOp
  LocalPointCloudRegistrationResult --> transformOp --> Matrix4x4
  LocalPointCloudRegistrationResult --> residualOp --> Residual

  classDef zividClass fill:#4A8FA4,stroke:#34323D,color:#FFFFFF
  classDef api fill:#91D2C8,stroke:#4A8FA4,color:#000000
  class SourcePC,TargetPC,LocalPointCloudRegistrationResult,Matrix4x4,Residual zividClass
  class registrationOp,transformOp,residualOp api

localPointCloudRegistration

Aligns the source point cloud to the target using ICP. An optional initial transformation guess can improve convergence speed and accuracy when the clouds have significant offset.

C++

LocalPointCloudRegistrationResult Zivid::Experimental::Toolbox::localPointCloudRegistration(const UnorganizedPointCloud &target, const UnorganizedPointCloud &source, const LocalPointCloudRegistrationParameters &params, const Pose &initialTransform = Pose{Matrix4x4::identity()})

Compute alignment transform between two point clouds.

Given a source point cloud and a target point cloud, this function attempts to compute the transform that must be applied to the source in order to align it with the target. This can be used to create a "stitched" unorganized point cloud of an object by combining data collected from different camera angles.

This function takes an argument initialTransform which is used as a starting-point for the computation of the transform that best aligns source with target. This initial guess is usually found from e.g. reference markers or robot capture pose, and this function is then used to refine the alignment. If the overlap of source and target is already quite good, one can pass the identity matrix as initialTransform.

The returned transform represents the total transform needed to align source with target, i.e. it includes both initialTransform and the refinement found by the algorithm.

Performance is very dependent on the number of points in either point cloud. To improve performance, voxel downsample one or both point clouds before passing them into this function. The resulting alignment transform can then be applied to the non-downsampled point clouds to still obtain a dense result.

Performance is also very dependent on MaxCorrespondenceDistance. To improve performance, try reducing this value. However, keep the value larger than the typical point-to-point distance in the point clouds, and larger than the expected translation error in the initial guess.

パラメータ:

target -- The point cloud to align with
source -- The point cloud to be aligned with target
params -- Parameters for the registration process and its convergence criteria
initialTransform -- Initial guess applied to source point cloud before refinement

戻り値:

Instance of LocalPointCloudRegistrationResult

C#

See Zivid::NET::Experimental::Toolbox::PointCloudRegistration in the C# API reference.

Python

local_point_cloud_registration( target: UnorganizedPointCloud, source: UnorganizedPointCloud, parameters: LocalPointCloudRegistrationParameters | None = None, initial_transform: Pose | Matrix4x4 | ndarray | None = None, ) → LocalPointCloudRegistrationResult

Compute alignment transform between two point clouds.

Given a source point cloud and a target point cloud, this function attempts to compute the transform that must be applied to the source in order to align it with the target. This can be used to create a "stitched" unorganized point cloud of an object by combining data collected from different camera angles.

This function takes an argument initial_transform which is used as a starting-point for the computation of the transform that best aligns source with target. This initial guess is usually found from e.g. reference markers or robot capture pose, and this function is then used to refine the alignment. If the overlap of source and target is already quite good, one can pass the identity pose as initial_transform.

The returned transform represents the total transform needed to align source with target, i.e. it includes both initial_transform and the refinement found by the algorithm.

Performance is very dependent on the number of points in either point cloud. To improve performance, voxel downsample one or both point clouds before passing them into this function. The resulting alignment transform can then be applied to the non-downsampled point clouds to still obtain a dense result.

Performance is also very dependent on MaxCorrespondenceDistance. To improve performance, try reducing this value. However, keep the value larger than the typical point-to-point distance in the point clouds, and larger than the expected translation error in the initial guess.

パラメータ:

target -- The target UnorganizedPointCloud to align with
source -- The source UnorganizedPointCloud to be aligned with target
parameters -- An optional LocalPointCloudRegistrationParameters instance. If not provided, default parameters are used.
initial_transform -- Optional transform (Pose/Matrix4x4/ndarray) be used as a starting point for the algorithm. If not provided, the identity transform is used.

戻り値:

A LocalPointCloudRegistrationResult instance

class LocalPointCloudRegistrationParameters( max_correspondence_distance: float | int = _zivid.toolbox.LocalPointCloudRegistrationParameters.MaxCorrespondenceDistance().value, max_iteration_count: int = _zivid.toolbox.LocalPointCloudRegistrationParameters.MaxIterationCount().value, convergence_criteria: ConvergenceCriteria | None = None, )

Input parameters for controlling the local point cloud registration process.

class ConvergenceCriteria( rmse_diff_threshold: float | int = _zivid.toolbox.LocalPointCloudRegistrationParameters.ConvergenceCriteria.RMSEDiffThreshold().value, source_coverage_diff_threshold: float | int = _zivid.toolbox.LocalPointCloudRegistrationParameters.ConvergenceCriteria.SourceCoverageDiffThreshold().value, )

Criteria for ending iteration early. Iteration will end when all criteria are satisfied.

property rmse_diff_threshold: Stop iteration when the absolute change in root mean square error (RMSE) from previous iteration is less than this threshold. RMSE is defined as the square root of the average squared distance between corresponding points in the source and target point clouds.

property source_coverage_diff_threshold: Stop iteration when the absolute change in coverage from previous iteration is less than this threshold. Coverage is defined as the fraction of points in the source point cloud that found a correspondence in the target point cloud.

property convergence_criteria: Criteria for ending iteration early. Iteration will end when all criteria are satisfied.

property max_correspondence_distance: The radius around each source point in which the algorithm will look for neighbors in the target point cloud. Should be larger than the typical distance between points in the point clouds. This parameter may have a significant performance impact.

property max_iteration_count: End iteration when reaching this number, even if convergence criteria are not yet satisfied.

LocalPointCloudRegistrationResult

Result of a point cloud registration. Provides the estimated 4×4 transformation and the per-point overlap residual.

C++

class LocalPointCloudRegistrationResult

The result of a call to localPointCloudRegistration()

Public Functions

Pose transform() const: The transform that must be applied to the source point cloud for it to align with the target point cloud.

bool converged() const: A boolean indicating whether the convergence criteria were satisfied before reaching the iteration limit.

float sourceCoverage() const: The fraction of points in the source point cloud that has a correspondence in the target point cloud after transformation.

float rootMeanSquareError() const: The root mean squared distance between corresponding points in the source and target point cloud after transformation.

std::string toString() const: Get string representation of the result.

C#

See Zivid::NET::Experimental::Toolbox::PointCloudRegistration in the C# API reference.

Python

class LocalPointCloudRegistrationResult(impl)

The result of a call to local_point_cloud_registration.

converged() → bool

A boolean indicating whether the convergence criteria were satisfied before reaching the iteration limit.

戻り値:: A boolean indicating convergence

root_mean_square_error() → float

The root mean squared distance between corresponding points in the source and target after transformation.

戻り値:: A float representing the root mean square error

source_coverage() → float

The fraction of points in the source that has a correspondence in the target after transformation.

戻り値:: A float in the range [0.0, 1.0]

transform() → Pose

The transform that must be applied to the source point cloud for it to align with the target point cloud.

戻り値:: A rigid transform as a Pose instance