Crate hrbf

source ·
Expand description

An implementation of Hermite Radial Basis Functions with higher order derivatives.

Overview

Let p: &[Point3<f64>] be a slice of points in 3D space along with corresponding normal vectors n: &[Vector3<f64>]. This library lets us construct a 3D potential field whose zero level-set interpolates the points p and whose gradient is aligned with n at these points.

Additionally hrbf implements first and second order derivatives of the resulting potential field with respect to point positions p (i.e. the Jacobian and Hessian).

This library uses nalgebra for linear algebra computations and in API icalls.

Examples

Suppose that we have a function fn cube() -> (Vec<Point3<f64>, Vec<Vector3<f64>>) that samples a unit cube centered at (0.5, 0.5, 0.5) (see the integration tests for a specific implementation), with points and corresponding normals. Then we can construct and use an HRBF field as follows:

use hrbf::*;
use na::{Point3, Vector3};

// Construct a sampling of a unit cube centered at (0.5, 0.5, 0.5).
let (points, normals) = cube();

// Create a new HRBF field using the `x^3` kernel with samples located at `points`.
// Normals define the direction of the HRBF gradient field at `points`.
let hrbf = Pow3HrbfBuilder::new(points)
    .normals(normals)
    .build()
    .unwrap();

// The HRBF potential can then be queried at any 3D location as follows:
let mut query_point = Point3::new(0.1_f64, 0.2, 0.3);

// Inside the cube the potential is negative.
assert!(hrbf.eval(query_point) < 0.0);

// Outside it is positive.
query_point.z = 1.3;
assert!(hrbf.eval(query_point) > 0.0);

// The gradient of the HRBF potential can also be queried.

// We expect the gradient to point outward from the cube center.
let direction = Vector3::new(1.0, 1.0, 1.0);
assert!(hrbf.grad(query_point).dot(&direction) > 0.0);

query_point.z = 0.3;
assert!(hrbf.grad(query_point).dot(&direction) < 0.0);

What is the difference between “points” and “sites” when creating an HRBF field?

It may seem surprising that we can specify “points” and “sites” as two distinct sets. So why do we need to ever specify “points” in HrbfBuilder if we have already passed a set of “sites” in HrbfBuilder::new?

The reason is simply that “sites” and “points” have a different purpose. The set of “sites” (the set of points passed to HrbfBuilder::new) are used to evaluate the HRBF potential, these are the basis for the potential field. On the other hand, “points” are the 3D positions that define where the zero level-set (or an offset level-set if “offsets” are specified) of the HRBF potential field goes. However, currently there is a restriction in the implementation that “sites” and “points” must have the same size. Additionally, the closer “points” are to “sites”, the better quality the resulting HRBF potential will be.

The following publications introduce and analyse Hermite Radial Basis Functions and describe different uses for approximating scattered point data:

I. Macêdo, J. P. Gois, and L. Velho, “Hermite Radial Basis Function Implicits

R. Vaillant, L. Barthe, G. Guennebaud, M.-P. Cani, D. Rhomer, B. Wyvill, O. Gourmel, and M. Paulin, “Implicit Skinning: Real-Time Skin Deformation with Contact Modeling

Re-exports

Modules

  • Hermite radial basis function kernels (funcions φ) We require that the first derivative of the kernel f go to zero as x -> 0. This ensures that the HRBF fitting matrix is well defined. I.e. in its taylor series representation, f(x) = ∑ᵢ aᵢxⁱ, we require that a₁ = 0.

Structs

Enums

  • Error indicating that the building the HRBF potential failed.
  • HRBF specific kernel type. In general, we can assign a unique kernel to each HRBF site, or we can use the same kernel for all points. This corresponds to Variable and Constant kernel types respectively.

Traits

  • Floating point real trait used throughout this library.

Type Definitions

  • Shorthand for an HRBF with a CSRBF(3,1) (1-x)^4 (4x+1) kernel of type.
  • Shorthand for an HRBF builder with a CSRBF(3,1) (1-x)^4 (4x+1) kernel of type.
  • Shorthand for an HRBF with a CSRBF(4,1) (1-x)^6 (35x^2 + 18x + 3) kernel of type.
  • Shorthand for an HRBF builder with a CSRBF(4,1) (1-x)^6 (35x^2 + 18x + 3) kernel of type.
  • Shorthand for an HRBF with a Gaussian exp(-x*x) kernel.
  • Shorthand for an HRBF builder with a Gaussian exp(-x*x) kernel.
  • Shorthand for an HRBF with a x^3 kernel.
  • Shorthand for an HRBF builder with a x^3 kernel.
  • Shorthand for an HRBF with a x^5 kernel.
  • Shorthand for an HRBF builder with a x^5 kernel.
  • A Result with a custom Error type encapsulating all possible failures in this crate.