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.

Parameters:

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

Returns:

Instance of LocalPointCloudRegistrationResult

C#

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

Python

See zivid-python.

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

See zivid-python.