Numerical utility functions

array2str(X, valuesep=', ', rowsep=' | ', fmt='{:.3g}', brackets=('[ ', ' ]'), suppress_small=True)[source]

Convert array to single line string

Parameters:

X (NDArray) 1D or 2D array to convert
valuesep (str) separator between numbers, defaults to ,
rowsep (str) separator between rows, defaults to |
format format string, defaults to {:.3g}
brackets (Tuple[str, str]) strings to be added to start and end of the string, defaults to ([ , ]). Set to None to suppress brackets.
suppress_small (bool) small values (\(|x| < 10^{-12}\) are converted to zero, defaults to True

Returns:

compact string representation of array

Return type:

str

Converts a small array to a compact single line representation.

Example:

>>> from spatialmath.base import array2str
>>> import numpy as np
>>> array2str(np.random.rand(2,2))
'[ 0.0277, 0.367 | 0.386, 0.269 ]'
>>> array2str(np.random.rand(2,2), rowsep="; ")  # MATLAB-like
'[ 0.239, 0.716; 0.612, 0.367 ]'
>>> array2str(np.random.rand(3,))
'[ 0.742, 0.365, 0.419 ]'
>>> array2str(np.random.rand(3,1))
'[ 0.83 | 0.0332 | 0.832 ]'

Seealso:: array2str()

bresenham(p0, p1)[source]

Line drawing in a grid

Parameters:

p0 (Union[List[float], Tuple[float, float], ndarray[Tuple[ResizeEventType[2]], dtype[floating]]]) initial point
p1 (Union[List[float], Tuple[float, float], ndarray[Tuple[ResizeEventType[2]], dtype[floating]]]) end point

Returns:

arrays of x and y coordinates for points along the line

Return type:

Tuple[NDArray, NDArray]

Return x and y coordinate vectors for points in a grid that lie on a line from p0 to p1 inclusive.

The end points, and all points along the line are integers.
Points are always adjacent, but the slope from point to point is not constant.

Example:

>>> from spatialmath.base import bresenham
>>> bresenham((2, 4), (10, 10))
(array([ 2,  3,  4,  5,  6,  7,  8,  9, 10]), array([ 4,  5,  6,  6,  7,  8,  8,  9, 10]))

(Source code, png, hires.png, pdf)

[_images/func_numeric-1.png]

Note

The API is similar to the Bresenham algorithm but this implementation uses NumPy vectorised arithmetic which makes it faster than the Bresenham algorithm in Python.

gauss1d(mu, var, x)[source]

Gaussian function in 1D

Parameters:

mu (float) mean
var (float) variance
x (Union[float, List[float], Tuple[float, ...], ndarray[Any, dtype[floating]]]) x-coordinate values

Returns:

Gaussian \(G(x)\)

Return type:

ndarray(n)

Example:

>>> g = gauss1d(5, 2, np.linspace(0, 10, 100))

(Source code, png, hires.png, pdf)

[_images/func_numeric-2.png]

Seealso:: gauss2d()

gauss2d(mu, P, X, Y)[source]

Gaussian function in 2D

Parameters:

mu (Union[List[float], Tuple[float, float], ndarray[Tuple[ResizeEventType[2]], dtype[floating]]]) mean
P (NDArray) covariance matrix
X (NDArray) array of x-coordinates
Y (NDArray) array of y-coordinates

Returns:

Gaussian \(g(x,y)\)

Return type:

NDArray

Computed \(g_{i,j} = G(x_{i,j}, y_{i,j})\)

Example (RVC3 Fig G.2):

>>> a = np.linspace(-5, 5, 100)
>>> X, Y = np.meshgrid(a, a)
>>> P = np.diag([1, 2])**2;
>>> g = gauss2d(X, Y, [0, 0], P)

(Source code, png, hires.png, pdf)

[_images/func_numeric-3.png]

Seealso:: gauss1d()

mpq_point(data, p, q)[source]

Moments of polygon

Parameters:

data (NDArray) polygon vertices, points as columns
p (int) moment order x
q (int) moment order y

Return type:

float

Returns the pqth moment of the polygon

\[M(p, q) = \sum_{i=0}^{n-1} x_i^p y_i^q\]

Example:

>>> from spatialmath.base import mpq_point
>>> import numpy as np
>>> p = np.array([[1, 3, 2], [2, 2, 4]])
>>> mpq_point(p, 0, 0)  # area
np.int64(3)
>>> mpq_point(p, 3, 0)
np.int64(36)

Note

is negative for clockwise perimeter.

numhess(J, x, dx=1e-08)[source]

Numerically compute Hessian given Jacobian function

Parameters:

J (Callable) the Jacobian function, returns an ndarray(m,n)
x (NDArray) function argument
dx (float) the numerical perturbation, defaults to 1e-8

Returns:

Hessian matrix

Return type:

ndarray(m,n,n)

Computes a numerical approximation to the Hessian for J(x) where \(f: \mathbb{R}^n \mapsto \mathbb{R}^{m \times n}\).

The result is a 3D array where

\[H_{i,j,k} = \frac{\partial J_{j,k}}{\partial x_i}\]

Uses first-order difference \(H[:,:,i] = (J(x + dx) - J(x)) / dx\).

numjac(f, x, dx=1e-08, SO=0, SE=0)[source]

Numerically compute Jacobian of function

Parameters:

f (Callable) the function, returns an m-vector
x (Union[float, List[float], Tuple[float, ...], ndarray[Any, dtype[floating]]]) function argument
dx (float) the numerical perturbation, defaults to 1e-8
SO (int) function returns SO(N) matrix, defaults to 0
SE (int) function returns SE(N) matrix, defaults to 0

Returns:

Jacobian matrix

Return type:

NDArray

Computes a numerical approximation to the Jacobian for f(x) where \(f: \mathbb{R}^n \mapsto \mathbb{R}^m\).

Uses first-order difference \(J[:,i] = (f(x + dx) - f(x)) / dx\).

If SO is 2 or 3, then it is assumed that the function returns an SO(N) matrix and the derivative is converted to a column vector

\[\vex{\dmat{R} \mat{R}^T}\]

If SE is 2 or 3, then it is assumed that the function returns an SE(N) matrix and the derivative is converted to a colun vector.

Example:

Traceback (most recent call last):
  File "<input>", line 1, in <module>
  File "/opt/hostedtoolcache/Python/3.12.14/x64/lib/python3.12/site-packages/spatialmath/base/numeric.py", line 59, in numjac
    J0 = f(x)
         ^^^^
  File "/opt/hostedtoolcache/Python/3.12.14/x64/lib/python3.12/site-packages/spatialmath/base/transforms3d.py", line 82, in rotx
    ct = sym.cos(theta)
         ^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.12.14/x64/lib/python3.12/site-packages/spatialmath/base/symbolic.py", line 161, in cos
    return math.cos(theta)
           ^^^^^^^^^^^^^^^
TypeError: only 0-dimensional arrays can be converted to Python scalars
Traceback (most recent call last):
  File "<input>", line 1, in <module>
  File "/opt/hostedtoolcache/Python/3.12.14/x64/lib/python3.12/site-packages/spatialmath/base/numeric.py", line 59, in numjac
    J0 = f(x)
         ^^^^
  File "/opt/hostedtoolcache/Python/3.12.14/x64/lib/python3.12/site-packages/spatialmath/base/transforms3d.py", line 82, in rotx
    ct = sym.cos(theta)
         ^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.12.14/x64/lib/python3.12/site-packages/spatialmath/base/symbolic.py", line 161, in cos
    return math.cos(theta)
           ^^^^^^^^^^^^^^^
TypeError: only 0-dimensional arrays can be converted to Python scalars

str2array(s)[source]

Convert compact single line string to array

Parameters:: s (str) string to convert
Returns:: array
Return type:: NDArray

Convert a string containing a MATLAB-like matrix definition to a NumPy array. A scalar has no delimiting square brackets and becomes a 1x1 array. A 2D array is delimited by square brackets, elements are separated by a comma, and rows are separated by a semicolon. Extra white spaces are ignored.

Example:

>>> from spatialmath.base import str2array
>>> str2array("5")
array([[5.]])
>>> str2array("[1 2 3]")
array([[1., 2., 3.]])
>>> str2array("[1 2; 3 4]")
array([[1., 2.],
       [3., 4.]])
>>> str2array(" [  1  , 2 ; 3 4  ] ")
array([[1., 2.],
       [3., 4.]])
>>> str2array("[1; 2; 3]")
array([[1.],
       [2.],
       [3.]])

Seealso:: array2str()