trimesh.registration
registration.py
Functions for registering (aligning) point clouds with meshes.
- trimesh.registration.icp(a, b, initial=array([[1., 0., 0., 0.], [0., 1., 0., 0.], [0., 0., 1., 0.], [0., 0., 0., 1.]]), threshold=1e-05, max_iterations=20, **kwargs)
Apply the iterative closest point algorithm to align a point cloud with another point cloud or mesh. Will only produce reasonable results if the initial transformation is roughly correct. Initial transformation can be found by applying Procrustes’ analysis to a suitable set of landmark points (often picked manually).
- Parameters
a ((n,3) float) – List of points in space.
b ((m,3) float or Trimesh) – List of points in space or mesh.
initial ((4,4) float) – Initial transformation.
threshold (float) – Stop when change in cost is less than threshold
max_iterations (int) – Maximum number of iterations
kwargs (dict) – Args to pass to procrustes
- Returns
matrix ((4,4) float) – The transformation matrix sending a to b
transformed ((n,3) float) – The image of a under the transformation
cost (float) – The cost of the transformation
- trimesh.registration.mesh_other(mesh, other, samples=500, scale=False, icp_first=10, icp_final=50, **kwargs)
Align a mesh with another mesh or a PointCloud using the principal axes of inertia as a starting point which is refined by iterative closest point.
- Parameters
mesh (trimesh.Trimesh object) – Mesh to align with other
other (trimesh.Trimesh or (n, 3) float) – Mesh or points in space
samples (int) – Number of samples from mesh surface to align
scale (bool) – Allow scaling in transform
icp_first (int) – How many ICP iterations for the 9 possible combinations of sign flippage
icp_final (int) – How many ICP iterations for the closest candidate from the wider search
kwargs (dict) – Passed through to icp, which passes through to procrustes
- Returns
mesh_to_other ((4, 4) float) – Transform to align mesh to the other object
cost (float) – Average squared distance per point
- trimesh.registration.nricp_amberg(source_mesh, target_geometry, source_landmarks=None, target_positions=None, steps=None, eps=0.0001, gamma=1, distance_threshold=0.1, return_records=False, use_faces=True, use_vertex_normals=True, neighbors_count=8)
Non Rigid Iterative Closest Points
Implementation of “Amberg et al. 2007: Optimal Step Nonrigid ICP Algorithms for Surface Registration.” Allows to register non-rigidly a mesh on another or on a point cloud. The core algorithm is explained at the end of page 3 of the paper.
Comparison between nricp_amberg and nricp_sumner: * nricp_amberg fits to the target mesh in less steps * nricp_amberg can generate sharp edges
only vertices and their neighbors are considered
nricp_sumner tend to preserve more the original shape
nricp_sumner parameters are easier to tune
nricp_sumner solves for triangle positions whereas nricp_amberg solves for vertex transforms
nricp_sumner is less optimized when wn > 0
- Parameters
source_mesh (Trimesh) – Source mesh containing both vertices and faces.
target_geometry (Trimesh or PointCloud or (n, 3) float) – Target geometry. It can contain no faces or be a PointCloud.
source_landmarks ((n,) int or ((n,) int, (n, 3) float)) – n landmarks on the the source mesh. Represented as vertex indices (n,) int. It can also be represented as a tuple of triangle indices and barycentric coordinates ((n,) int, (n, 3) float,).
target_positions ((n, 3) float) – Target positions assigned to source landmarks
steps (Core parameters of the algorithm) – Iterable of iterables (ws, wl, wn, max_iter,). ws is smoothness term, wl weights landmark importance, wn normal importance and max_iter is the maximum number of iterations per step.
eps (float) – If the error decrease if inferior to this value, the current step ends.
gamma (float) – Weight the translation part against the rotational/skew part. Recommended value : 1.
distance_threshold (float) – Distance threshold to account for a vertex match or not.
return_records (bool) – If True, also returns all the intermediate results. It can help debugging and tune the parameters to match a specific case.
use_faces (bool) – If True and if target geometry has faces, use proximity.closest_point to find matching points. Else use scipy’s cKDTree object.
use_vertex_normals (bool) – If True and if target geometry has faces, interpolate the normals of the target geometry matching points. Else use face normals or estimated normals if target geometry has no faces.
neighbors_count (int) – number of neighbors used for normal estimation. Only used if target geometry has no faces or if use_faces is False.
- Returns
result – The vertices positions of source_mesh such that it is registered non-rigidly onto the target geometry. If return_records is True, it returns the list of the vertex positions at each iteration.
- Return type
(n, 3) float or List[(n, 3) float]
- trimesh.registration.nricp_sumner(source_mesh, target_geometry, source_landmarks=None, target_positions=None, steps=None, distance_threshold=0.1, return_records=False, use_faces=True, use_vertex_normals=True, neighbors_count=8, face_pairs_type='vertex')
Non Rigid Iterative Closest Points
Implementation of the correspondence computation part of “Sumner and Popovic 2004: Deformation Transfer for Triangle Meshes” Allows to register non-rigidly a mesh on another geometry.
Comparison between nricp_amberg and nricp_sumner: * nricp_amberg fits to the target mesh in less steps * nricp_amberg can generate sharp edges (only vertices and their
neighbors are considered)
nricp_sumner tend to preserve more the original shape
nricp_sumner parameters are easier to tune
- nricp_sumner solves for triangle positions whereas nricp_amberg solves for
vertex transforms
nricp_sumner is less optimized when wn > 0
- Parameters
source_mesh (Trimesh) – Source mesh containing both vertices and faces.
target_geometry (Trimesh or PointCloud or (n, 3) float) – Target geometry. It can contain no faces or be a PointCloud.
source_landmarks ((n,) int or ((n,) int, (n, 3) float)) – n landmarks on the the source mesh. Represented as vertex indices (n,) int. It can also be represented as a tuple of triangle indices and barycentric coordinates ((n,) int, (n, 3) float,).
target_positions ((n, 3) float) – Target positions assigned to source landmarks
steps (Core parameters of the algorithm) – Iterable of iterables (wc, wi, ws, wl, wn). wc is the correspondence term (strength of fitting), wi is the identity term (recommended value : 0.001), ws is smoothness term, wl weights the landmark importance and wn the normal importance.
distance_threshold (float) – Distance threshold to account for a vertex match or not.
return_records (bool) – If True, also returns all the intermediate results. It can help debugging and tune the parameters to match a specific case.
use_faces (bool) – If True and if target geometry has faces, use proximity.closest_point to find matching points. Else use scipy’s cKDTree object.
use_vertex_normals (bool) – If True and if target geometry has faces, interpolate the normals of the target geometry matching points. Else use face normals or estimated normals if target geometry has no faces.
neighbors_count (int) – number of neighbors used for normal estimation. Only used if target geometry has no faces or if use_faces is False.
face_pairs_type (str 'vertex' or 'edge') – Method to determine face pairs used in the smoothness cost. ‘vertex’ yields smoother results.
- Returns
result – The vertices positions of source_mesh such that it is registered non-rigidly onto the target geometry. If return_records is True, it returns the list of the vertex positions at each iteration.
- Return type
(n, 3) float or List[(n, 3) float]
- trimesh.registration.procrustes(a, b, weights=None, reflection=True, translation=True, scale=True, return_cost=True)
Perform Procrustes’ analysis subject to constraints. Finds the transformation T mapping a to b which minimizes the square sum distances between Ta and b, also called the cost. Optionally specify different weights for the points in a to minimize the weighted square sum distances between Ta and b. This can improve transformation robustness on noisy data if the points’ probability distribution is known.
- Parameters
a ((n,3) float) – List of points in space
b ((n,3) float) – List of points in space
weights ((n,) float) – List of floats representing how much weight is assigned to each point of a
reflection (bool) – If the transformation is allowed reflections
translation (bool) – If the transformation is allowed translations
scale (bool) – If the transformation is allowed scaling
return_cost (bool) – Whether to return the cost and transformed a as well
- Returns
matrix ((4,4) float) – The transformation matrix sending a to b
transformed ((n,3) float) – The image of a under the transformation
cost (float) – The cost of the transformation