differt.geometry.utils module

Utilities for working with 3D geometries.

normalize(vector)

Normalize vectors and also return their length.

This function avoids division by zero by checking vectors with zero-length, and returning unit length instead.

Parameters:

vector (Float[Array, '*batch 3']) – An array of vectors.

Return type:

tuple[Float[Array, '*batch 3'], Float[Array, '*batch']]

Returns:

The normalized vector and their length.

Examples

The following examples shows how normalization works and its special behavior at zero.

>>> from differt.geometry.utils import (
...     normalize,
... )
>>>
>>> vector = jnp.array([1.0, 1.0, 1.0])
>>> normalize(vector)  # [1., 1., 1.] / sqrt(3), sqrt(3)
(Array([0.5773503, 0.5773503, 0.5773503], dtype=float32),
 Array(1.7320508, dtype=float32))
>>> zero = jnp.array([0.0, 0.0, 0.0])
>>> normalize(zero)  # Special behavior at 0.
(Array([0., 0., 0.], dtype=float32), Array(1., dtype=float32))

orthogonal_basis(u, normalize=True)

Generate v and w, two other arrays of unit vectors that form with input u an orthogonal basis.

Parameters:

• u (Float[Array, '*batch 3']) – The first direction of the orthogonal basis. It must have a unit length.

• normalize (bool) –

  Whether the output vectors should be normalized.

  This may be needed, especially for vector v, as floating-point error can accumulate so much that the vector lengths may diverge from the unit length by 10% or even more!

Return type:

tuple[Float[Array, '*batch 3'], Float[Array, '*batch 3']]

Returns:

A pair of unit vectors, v and w.

Examples

The following example shows how this function works on basic input vectors.

>>> from differt.geometry.utils import (
...     normalize,
...     orthogonal_basis,
... )
>>>
>>> u = jnp.array([1.0, 0.0, 0.0])
>>> orthogonal_basis(u)
(Array([ 0., -1.,  0.], dtype=float32), Array([ 0.,  0., -1.], dtype=float32))
>>> u, _ = normalize(jnp.array([1.0, 1.0, 1.0]))
>>> orthogonal_basis(u)
(Array([ 0.4082483, -0.8164966,  0.4082483], dtype=float32),
 Array([ 0.7071068,  0.       , -0.7071068], dtype=float32))

pairwise_cross(u, v)

Compute the pairwise cross product between two arrays of vectors.

Parameters:

• u (Float[Array, 'm 3']) – First array of vectors.

• v (Float[Array, 'n 3']) – Second array of vectors.

Return type:

Float[Array, 'm n 3']

Returns:

A 3D tensor with all cross products.

path_lengths(paths)

Compute the path length of each path.

Each path is exactly made of path_length vertices.

Parameters:

paths (Float[Array, '*batch path_length 3']) – The array of path vertices.

Return type:

Float[Array, '*batch']

Returns:

The array of path lengths.

Examples

The following example shows how to compute the length of a very simple path.

>>> from differt.geometry.utils import (
...     path_lengths,
... )
>>>
>>> path = jnp.array([[1.0, 0.0, 0.0], [1.0, 1.0, 0.0]])
>>> path_lengths(path)
Array(1., dtype=float32)
>>> path_lengths(jnp.vstack((path, path[::-1, :])))
Array(2., dtype=float32)