API Reference

This section provides complete API documentation for the einit library.

einit – Ellipsoid ICP initialization

Provides register_ellipsoid(src, dst) that:

  1. Centers src & dst by their centroids.

  2. Computes ellipsoid matrices; eigen-decomposes to get principal axes.

  3. Searches all 8 diagonal ±1 reflections for best alignment.

  4. Returns a 4×4 homogeneous transform for OpenCV.

einit.einit.register_ellipsoid(src_points, dst_points, max_correspondence_distance=None, min_inlier_fraction=0.5, leafsize=16, positive_only=False)[source]

Compute initial transformation between 3D point clouds using ellipsoid analysis.

This function computes an initial rigid transformation that aligns the source point cloud with the destination point cloud by analyzing their ellipsoids of inertia. The algorithm uses KD-tree correspondence recovery to handle point clouds with different orderings, partial overlaps, and outliers.

Parameters:

  • src_points (array_like, shape (N, 3)) – Source point cloud as N×3 array of 3D coordinates.

  • dst_points (array_like, shape (M, 3)) – Destination point cloud as M×3 array of 3D coordinates. N and M can be different (partial overlap).

  • max_correspondence_distance (float, optional) – Maximum distance for valid point correspondences. Points farther than this distance from their nearest neighbors are considered outliers. If None (default), automatically estimated as 3× the median nearest- neighbor distance within the destination point cloud.

  • min_inlier_fraction (float, default 0.5) – Minimum fraction of source points that must have valid correspondences within max_correspondence_distance. Transformations with fewer inliers are rejected. Must be between 0 and 1.

  • leafsize (int, default 16) – KD-tree leaf size parameter. Affects search performance vs memory usage. Smaller values may improve accuracy for small point clouds but increase build time. Typical range: 8-32.

  • positive_only (bool, default False) – If True, only search proper rotations (determinant +1) by considering only sign combinations with an even number of negative values. This prevents reflections and ensures chirality preservation. Recommended when point distributions are spatially biased (e.g., bounding box overlap).

Returns:

T – Homogeneous transformation matrix that transforms src_points to align with dst_points. Apply as: dst_aligned = (src @ T[:3,:3].T) + T[:3,3]

Return type:

ndarray, shape (4, 4)

Raises:

ValueError – If input arrays don’t have shape (N, 3) or (M, 3).

Examples

Basic usage:

>>> import numpy as np
>>> from einit import register_ellipsoid
>>> src = np.random.randn(100, 3)
>>> dst = np.random.randn(80, 3)  # Different size OK
>>> T = register_ellipsoid(src, dst)
>>> T.shape
(4, 4)

With custom parameters:

>>> T = register_ellipsoid(
...     src, dst,
...     max_correspondence_distance=0.1,
...     min_inlier_fraction=0.7,
...     leafsize=8,
...     positive_only=True
... )

Notes

The algorithm is permutation-invariant: point ordering in the input arrays does not affect the result. It handles partial overlaps, noise, and outliers through KD-tree correspondence recovery and distance-based filtering.

Time complexity is O(N + M log M) where N and M are the number of points in the source and destination clouds respectively.

einit.einit.barycentered(points)[source]

Center point cloud around barycenter (N×3 format)