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 testshape (2-tuple) – required shape
- Raises
TypeError – if value is not a real Numpy array
ValueError – if value is not of the specified shape
Tests if the argument is a real 2D matrix with a specified shape
shape
but the valueNone
indicate an unspecified (wildcard, don’t care) dimension.assertsmatrix(A)
raises an exception ifm
is not convertible to a 2D arrayassertsmatrix(A, (N,M))
as above butm
must have shape (N
,``M``)assertsmatrix(A, (N,None))
as above butm
must haveN
rowsassertsmatrix(A, (None,M))
as above butm
must haveM
columns
- Seealso
- Return type
None
- assertvector(v, dim=None, msg=None)[source]
Assert that argument is a real vector
- Parameters
v (
Any
) – passed vectordim (int or None) – required dimension
- Raises
ValueError – if not a vector of specified length
assertvector(vec)
raise an exception ifvec
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 isN
.
- Seealso
- Return type
None
- getmatrix(m, shape, dtype=<class 'numpy.float64'>)[source]
Convert argument to 2D array
- Parameters
- Raises
ValueError – if
m
is inconsistent withshape
TypeError – if
m
is not required typeTypeError – if value is not a scalar or Numpy array
ValueError – if value is not of the specified shape
- Returns
a 2D array
- Return type
NumPy ndarray
getmatrix(m, shape)
is a 2D matrix with shapeshape
formed fromm
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 toshape
- a 2-tuple whereNone
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 toshape
. A n-array could be reshaped as (n,1) or (1,n) or any other shape with the correct number of elements. A value ofNone
in the shape stands for unspecified, ie.(None, 2)
will attempt to reshapem
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
- SymPy
supported
- getunit(v, unit='rad', dim=None)[source]
Convert values according to angular units
- Parameters
v (array_like(m)) – the value in radians or degrees
unit (str) – the angular unit, “rad” or “deg”
dim (int, optional) – expected dimension of input, defaults to None
- Returns
the converted value in radians
- Return type
ndarray(m) or float
- 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(1.5, 'rad', dim=0) 1.5 >>> # getunit([1.5], 'rad', dim=0) --> ValueError >>> getunit(90, 'deg') array([1.5708]) >>> getunit([90, 180], 'deg') array([1.5708, 3.1416]) >>> getunit(np.r_[0.5, 1], 'rad') array([0.5, 1. ]) >>> getunit(np.r_[90, 180], 'deg') array([1.5708, 3.1416]) >>> getunit(np.r_[90, 180], 'deg', dim=2) array([1.5708, 3.1416]) >>> # getunit([90, 180], 'deg', dim=3) --> ValueError
- Note
the input value is processed by
getvector()
and the argumentdim
can be used to check thatv
is the desired length.the output is always an ndarray except if the input is a scalar and
dim=0
.
- Seealso
- 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
[TypeVar
(ScalarType
, bound=generic
, covariant=True)]]]) – passed vectordim (int or None) – required dimension, or None if any length is ok
out (str) – output format, default is ‘array’
dtype (numPy type) – datatype for numPy array return (default np.float64)
- Return type
Union
[ndarray
[Any
,dtype
[TypeVar
(ScalarType
, bound=generic
, covariant=True)]],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)
isvec
converted to the output formatout
wherevec
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 anN
-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 [1, 2, 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
ofv
if it is a NumPy array, otherwise it is set to the value specified by thedtype
keyword which defaults tonp.float64
.If
v
is symbolic thedtype
is retained as'O'
- Seealso
- 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)
isTrue
ifx
is a Python or numPy int or real float.File "<input>", line 1, in <module> NameError: name 'isinteger' is not defined
- islistof(value, what, n=None)[source]
Test if argument is a list of specified type
- Parameters
value (list or tuple) – the value to test
what (type or callable) – type, tuple of types or function
n (int, optional) – 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 bywhat
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 testshape (2-tuple) – 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 valueNone
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
- 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)
isTrue
ifx``
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)
isTrue
ifx
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 testdim (int or None) – required dimension
- Returns
whether value is a valid vector
- Return type
bool
isvector(vec)
isTrue
ifvec
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 anN
-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
- 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)
isTrue
ifx
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 testedshape (2-tuple) – desired shape of value
- Raises
TypeError – argument is not a NumPy array
ValueError – argument has incorrect shape
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()
- Return type
None