## 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 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

- 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.