Argument checking

Utility functions for testing and converting passed arguments. Used in all spatialmath functions and classes to provides for flexibility in argument types that can be passed.

assertmatrix(m, shape=(None, None))[source]

Assert that argument is a 2D matrix

Parameters:

  • m (Any) – value to test

  • shape (Tuple[Optional[int], Optional[int]]) – required shape

Raises:

  • TypeError – if value is not a real Numpy array

  • ValueError – if value is not of the specified shape

Return type:

None

Tests if the argument is a real 2D matrix with a specified shape shape but the value None indicate an unspecified (wildcard, don’t care) dimension.

  • assertsmatrix(A) raises an exception if m is not convertible to a 2D array

  • assertsmatrix(A, (N,M)) as above but m must have shape (N,``M``)

  • assertsmatrix(A, (N,None)) as above but m must have N rows

  • assertsmatrix(A, (None,M)) as above but m must have M columns

Seealso:

ismatrix()

assertvector(v, dim=None, msg=None)[source]

Assert that argument is a real vector

Parameters:

  • v (Any) – passed vector

  • dim (Optional[int]) – required dimension

Raises:

ValueError – if not a vector of specified length

Return type:

None

  • assertvector(vec) raise an exception if vec is not a vector, ie. it is not any of:

    • a Python native int or float, a 1-vector

    • Python native list or tuple

    • numPy real 1D array, ie. shape=(N,)

    • numPy real 2D array with a singleton dimension, ie. shape=(1,N) or (N,1)

  • assertvector(vec, N) as above but must also check the length is N.

Seealso:

getvector(), isvector()

getmatrix(m, shape, dtype=<class 'numpy.float64'>)[source]

Convert argument to 2D array

Parameters:

  • m (Union[float, List[float], Tuple[float, ...], ndarray[Any, dtype[floating]]]) – input value

  • shape (Tuple[Optional[int], Optional[int]]) – shape of returned matrix

Raises:

  • ValueError – if m is inconsistent with shape

  • TypeError – if m is not required type

  • TypeError – if value is not a scalar or Numpy array

  • ValueError – if value is not of the specified shape

Returns:

a 2D array

Return type:

ndarray

getmatrix(m, shape) is a 2D matrix with shape shape formed from m which can be a 2D array, 1D array-like or a scalar.

>>> from spatialmath.base import getmatrix
>>> import numpy as np
>>> getmatrix(3, (1,1))
array([[3.]])
>>> getmatrix([3,4], (1,2))
array([[3., 4.]])
>>> getmatrix([3,4], (2, 1))
array([[3.],
       [4.]])
>>> getmatrix([3,4,5,6], (2,2))
array([[3., 4.],
       [5., 6.]])
>>> getmatrix(np.r_[3,4,5,6], (2,2))
array([[3., 4.],
       [5., 6.]])

Note

  • If m is a 2D array its shape is compared to shape - a 2-tuple where None stands for unspecified, ie. (None, 2) will match any array where the second dimension is 2.

  • If m is a 1D array its shape is checked to see if it can be reshaped to shape. A n-array could be reshaped as (n,1) or (1,n) or any other shape with the correct number of elements. A value of None in the shape stands for unspecified, ie. (None, 2) will attempt to reshape m as an array with shape (k,2) where \(k \times 2 \eq n\).

  • If m is a scalar, return an array of shape (1,1)

Seealso:

ismatrix(), verifymatrix()

SymPy:

supported

getunit(v, unit='rad', dim=None, vector=True)[source]

Convert values according to angular units

Parameters:

  • v (Union[float, List[float], Tuple[float, ...], ndarray[Any, dtype[floating]]]) – the value in radians or degrees

  • unit (str) – the angular unit, “rad” or “deg”

  • dim (Optional[int]) – expected dimension of input, defaults to don’t check (None)

  • vector (bool) – return a scalar as a 1d vector, defaults to True

Returns:

the converted value in radians

Return type:

Union[float, NDArray]

Raises:

ValueError – argument is not a valid angular unit

The input value is assumed to be in units of unit and is converted to radians.

>>> from spatialmath.base import getunit
>>> import numpy as np
>>> getunit(1.5, 'rad')
array([1.5])
>>> getunit(90, 'deg')
array([1.5708])
>>> getunit(90, 'deg', vector=False) # force a scalar output
np.float64(1.5707963267948966)
>>> getunit(1.5, 'rad', dim=0) # check argument is scalar
array([1.5])
>>> getunit(1.5, 'rad', dim=3) # check argument is a 3-vector
!! [RUNBLOCK-ERROR] base/argcheck.py:docstring of spatialmath.base.argcheck.getunit:130
    ValueError: for dim==0 input must be a scalar
>>> getunit([1.5], 'rad', dim=1) # check argument is a 1-vector
array([1.5])
>>> getunit([1.5], 'rad', dim=3) # check argument is a 3-vector
!! [RUNBLOCK-ERROR] base/argcheck.py:docstring of spatialmath.base.argcheck.getunit:130
    ValueError: incorrect vector length: expected 3, got 1
>>> getunit([90, 180], 'deg')
array([1.5708, 3.1416])
>>> getunit(np.r_[90, 180], 'deg')
array([1.5708, 3.1416])
>>> getunit(np.r_[90, 180], 'deg', dim=2) # check argument is a 2-vector
array([1.5708, 3.1416])
>>> getunit([90, 180], 'deg', dim=3) # check argument is a 3-vector
!! [RUNBLOCK-ERROR] base/argcheck.py:docstring of spatialmath.base.argcheck.getunit:130
    ValueError: incorrect vector length: expected 3, got 2
Note:

  • the input value is processed by getvector() and the argument dim can be used to check that v is the desired length. Note that 0 means a scalar, whereas 1 means a 1-element array.

  • the output is always an ndarray except if the input is a scalar and vector=False.

Seealso:

getvector()

getvector(v, dim=None, out='array', dtype=<class 'numpy.float64'>)[source]

Return a vector value

Parameters:

  • v (Union[float, List[float], Tuple[float, ...], ndarray[Any, dtype[floating]]]) – passed vector

  • dim (Optional[int]) – required dimension, or None if any length is ok

  • out (str) – output format, default is ‘array’

  • dtype (DTypeLike) – datatype for numPy array return (default np.float64)

Return type:

Union[NDArray, List[float], Tuple[float, ...]]

Returns:

vector value in specified format

Raises:

  • TypeError – value is not a list or NumPy array

  • ValueError – incorrect number of elements

  • getvector(vec) is vec converted to the output format out where vec is any of:

    • a Python native int or float, a 1-vector

    • Python native list or tuple

    • numPy real 1D array, ie. shape=(N,)

    • numPy real 2D array with a singleton dimension, ie. shape=(1,N) or (N,1)

  • getvector(vec, N) as above but must be an N-element vector.

The returned vector will be in the format specified by out:

format

return type

‘sequence’

Python list, or tuple if a tuple was passed in

‘list’

Python list

‘array’

1D numPy array, shape=(N,) [default]

‘row’

row vector, a 2D numPy array, shape=(1,N)

‘col’

column vector, 2D numPy array, shape=(N,1)

 
>>> from spatialmath.base import getvector
>>> import numpy as np
>>> getvector([1,2])  # list
array([1., 2.])
>>> getvector([1,2], out='row')  # list
array([[1., 2.]])
>>> getvector([1,2], out='col')  # list
array([[1.],
       [2.]])
>>> getvector((1,2))  # tuple
array([1., 2.])
>>> getvector(np.r_[1,2,3], out='sequence')  # numpy array
[np.int64(1), np.int64(2), np.int64(3)]
>>> getvector(1)  # scalar
array([1.])
>>> getvector([1])
array([1.])
>>> getvector([[1]])
array([[1.]])
>>> getvector([1,2], 2)
array([1., 2.])
>>> # getvector([1,2], 3)  --> ValueError

Note

  • For ‘array’, ‘row’ or ‘col’ output the NumPy dtype defaults to the dtype of v if it is a NumPy array, otherwise it is set to the value specified by the dtype keyword which defaults to np.float64.

  • If v is symbolic the dtype is retained as 'O'

Seealso:

isvector()

isinteger(x)[source]

Test if argument is a scalar integer

Parameters:

x (Any) – value to test

Returns:

whether value is a scalar

Return type:

bool

isinteger(x) is True if x is a Python or numPy int or real float.

>>> from spatialmath.base import isinteger
>>> isinteger(1)
True
>>> isinteger(1.2)
False
islistof(value, what, n=None)[source]

Test if argument is a list of specified type

Parameters:

  • value (Any) – the value to test

  • what (Union[Type, Callable]) – type, tuple of types or function

  • n (Optional[int]) – length of list, defaults to None

Returns:

whether value is a specified list

Return type:

bool

Tests that every element of value is of the desired type. The type is specified by what and can be:

  • a single type, eg. int

  • a tuple of types, eg. (int, float)

  • a reference to a function which is passed each elemnent of the list and returns True if it is a valid member of the list.

The length of the list can also be tested by specifying the argument n.

>>> from spatialmath.base import islistof
>>> a = [3, 4, 5]
>>> islistof(a, int)
True
>>> islistof(a, int, 2)
False
>>> a = [3, 4.5, 5.6]
>>> islistof(a, int)
False
>>> islistof(a, (int, float))
True
>>> a = [[1,2], [3, 4], [5,6]]
>>> islistof(a, lambda x: islistof(x, int, 2))
True
ismatrix(m, shape)[source]

Test if argument is a real 2D matrix

Parameters:

  • m (Any) – value to test

  • shape (Tuple[Optional[int], Optional[int]]) – required shape

Return type:

bool

Returns:

True if value is of specified shape :rtype: bool

Tests if the argument is a real 2D matrix with a specified shape shape but the value None indicate an unspecified (wildcard, don’t care) dimension, for example:

>>> from spatialmath.base import ismatrix
>>> import numpy as np
>>> A = np.zeros((2,3))
>>> ismatrix(A, (2,3))
True
>>> ismatrix(A, (None,3))
True
>>> ismatrix(A, (2,None))
True
>>> ismatrix(A, (2,4))
False

Note

Unlike verifymatrix this function: - checks the argument is real valued - allows the shape to have an unspecified dimension

Seealso:

getmatrix(), verifymatrix(), assertmatrix()

isnumberlist(x)[source]

Test if argument is a list of scalars

Parameters:

x (Any) – the value to test

Returns:

True if the argument is a list of real scalars

Return type:

bool

isscalarlist(x) is True if x`` is a list of scalars.

>>> from spatialmath.base import isnumberlist
>>> import numpy as np
>>> isnumberlist((1,2,3))
True
>>> isnumberlist([1.1, 2.2, 3.3])
True
>>> isnumberlist(1)
False
>>> isnumberlist(np.r_[1,2])
False
isscalar(x)[source]

Test if argument is a real scalar

Parameters:

x (Any) – value to test

Returns:

whether value is a scalar

Return type:

bool

isscalar(x) is True if x is a Python or numPy int or real float.

>>> from spatialmath.base import isscalar
>>> isscalar(1)
True
>>> isscalar(1.2)
True
>>> isscalar([1])
False
isvector(v, dim=None)[source]

Test if argument is a real vector

Parameters:

  • v (Any) – value to test

  • dim (Optional[int]) – required dimension

Returns:

whether value is a valid vector

Return type:

bool

  • isvector(vec) is True if vec is a vector, ie. any of:

    • a Python native int or float, a 1-vector

    • Python native list or tuple

    • numPy real 1D array, ie. shape=(N,)

    • numPy real 2D array with a singleton dimension, ie. shape=(1,N) or (N,1)

  • isvector(vec, N) as above but must also be an N-element vector.

>>> from spatialmath.base import isvector
>>> import numpy as np
>>> isvector([1,2])  # list
True
>>> isvector((1,2))  # tuple
True
>>> isvector(np.r_[1,2,3])  # numpy array
True
>>> isvector(1)  # scalar
True
>>> isvector([1,2], 3)  # list
False
Seealso:

getvector(), assertvector()

isvectorlist(x, n)[source]

Test if argument is a list of vectors

Parameters:

x (Any) – the value to test

Returns:

True if the argument is a list of n-vectors

Return type:

bool

isvectorlist(x, n) is True if x is a list or tuple of 1D numPy arrays of shape=(n,).

>>> from spatialmath.base import isvectorlist
>>> import numpy as np
>>> isvectorlist([np.r_[1,2], np.r_[3,4], np.r_[5,6]], 2)
True
>>> isvectorlist([(1,2), (3,4), (5,6)], 2)
False
>>> isvectorlist([np.r_[1,2], np.r_[3,4], np.r_[5,6,7]], 2)
False
verifymatrix(m, shape)[source]

Assert that argument is array of specified size

Parameters:

  • m (ndarray) – value to be tested

  • shape (Tuple[Optional[int], Optional[int]]) – desired shape of value

Raises:

  • TypeError – argument is not a NumPy array

  • ValueError – argument has incorrect shape

Return type:

None

Raises an exception if the argument m is not a NumPy array of the specified shape.

Note

Unlike assertmatrix the specified shape cannot have wildcard dimensions.

Seealso:

assertmatrix(),:func:getmatrix, ismatrix()