API – fitting

HOMER.fitting.point_cloud_fit(mesh, data, normals=None, res=20, compile=True, surface_only=False, sob_weight=0.01)

Build a point-cloud fitting cost function and its sparse Jacobian.

Constructs a residual function suitable for scipy.optimize.least_squares that measures the distance from the mesh surface to the target point cloud, with an optional Sobolev smoothness regularisation term.

A KD-tree is built from data (and normals when provided) at construction time. Every evaluation then queries this tree against the current mesh surface.

Parameters:

Name	Type	Description	Default
mesh	Mesh	The :class:~HOMER.mesher.Mesh to fit.	required
data		Target point cloud, shape (n_pts, 3).	required
normals		Optional surface normals at each target point, shape (n_pts, 3). When provided, the distance metric is projected along the normal direction (useful for fitting to noisy oriented point clouds).	None
res		Number of xi grid points per direction used to sample the mesh surface.	20
compile		When True, JIT-compiles the mesh evaluation functions (recommended for iterative optimisation).	True
surface_only		When True, only sample the mesh surface faces (for volume meshes).	False
sob_weight		Scalar weight applied to the Sobolev smoothness term. Increase to produce smoother fits at the cost of surface accuracy.	0.01

Returns:

Name	Type	Description
fitting_function	Callable	Residual function (params) → residuals compatible with scipy.optimize.least_squares.
jacobian_fun	Callable	Sparse Jacobian function (params) → scipy.sparse.coo_array.

Examples:

::

fitting_fn, jac_fn = point_cloud_fit(mesh, target_pts, compile=True)
result = least_squares(fitting_fn, mesh.optimisable_param_array,
                       jac=jac_fn, verbose=2)
mesh.update_from_params(result.x)