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.
Related Publications
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”
Re-exports
pub use kernel::*;
Modules
- Hermite radial basis function kernels (funcions
φ
) We require that the first derivative of the kernelf
go to zero asx -> 0
. This ensures that the HRBF fitting matrix is well defined. I.e. in its taylor series representation,f(x) = ∑ᵢ aᵢxⁱ
, we require thata₁ = 0
.
Structs
- An HRBF potential field.
- A builder for an HRBF potential.
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.