Shape models

A set of functions that define 2D (grid) and 3D (cube, cylinder, sphere) shapes as NumPy arrays.

machinevisiontoolbox.base.shapes.mkgrid(n=2, side=1, pose=None)[source]

Create planar grid of points

Parameters:

n (int, array_like(2)) – number of points in each dimension, defaults to 2
s (float, array_like(2)) – side length of the whole grid, defaults to 1
pose (SE3, optional) – pose of the grid, defaults to None

Returns:

3D coordinates

Return type:

ndarray(3,n**2), ndarray(3,n[0]*n[1])

Compute a set of coordinates, as column vectors, that define a uniform grid of points over a planar region of given size.

If n or s are scalar it is assumed to apply in the x- and y-directions.

Example:

>>> from machinevisiontoolbox import mkgrid
>>> from spatialmath import SE3
>>> mkgrid()  # 2x2 grid, side length 1m
array([[-0.5, -0.5,  0.5,  0.5],
       [-0.5,  0.5,  0.5, -0.5],
       [ 0. ,  0. ,  0. ,  0. ]])
>>> mkgrid(side=2)  # 2x2 grid, side length 2m
array([[-1., -1.,  1.,  1.],
       [-1.,  1.,  1., -1.],
       [ 0.,  0.,  0.,  0.]])
>>> mkgrid([2, 3], [4, 6]) # 2x3 grid, side length 4x6m
array([[-2., -2.,  2.,  2.],
       [-3.,  3.,  3., -3.],
       [ 0.,  0.,  0.,  0.]])
>>> mkgrid(pose=SE3.Trans(1,2,3))
array([[0.5, 0.5, 1.5, 1.5],
       [1.5, 2.5, 2.5, 1.5],
       [3. , 3. , 3. , 3. ]])

Note

By default the grid lies in the xy-plane, symmetric about the origin. The pose argument can be used to transform all the points.

machinevisiontoolbox.base.shapes.mkcube(s=1, facepoint=False, pose=None, centre=None, edge=False, **kwargs)[source]

Create a cube

Parameters:

s (float) – side length, defaults to 1
facepoint (bool, optional) – add extra point in the centre of each face, defaults to False
pose (SE3, optional) – pose of the cube, defaults to None
centre (array_like(3), optional) – centre of the cube, defaults to None
edge (bool, optional) – create edges, defaults to False

Raises:

ValueError – centre and pose both specified

Compute vertices or edges of a cube.

Vertex mode

Returns:: vertex coordinates
Return type:: ndarray(3,8), ndarray(3,14)

Compute the eight vertex coordinates. If facepoint is True then add an extra point in the centre of each face.

By default, the cube is drawn centred at the origin but its centre can be changed using centre or it can be arbitrarily positioned and oriented by specifying its pose.

Example:

>>> from machinevisiontoolbox import mkcube
>>> from spatialmath import SE3
>>> mkcube()  # cube of side length 1
array([[-0.5, -0.5,  0.5,  0.5, -0.5, -0.5,  0.5,  0.5],
       [-0.5,  0.5,  0.5, -0.5, -0.5,  0.5,  0.5, -0.5],
       [-0.5, -0.5, -0.5, -0.5,  0.5,  0.5,  0.5,  0.5]])
>>> mkcube(pose=SE3.Trans(1,2,3))  # cube of side length 1
array([[0.5, 0.5, 1.5, 1.5, 0.5, 0.5, 1.5, 1.5],
       [1.5, 2.5, 2.5, 1.5, 1.5, 2.5, 2.5, 1.5],
       [2.5, 2.5, 2.5, 2.5, 3.5, 3.5, 3.5, 3.5]])

Edge mode

Returns:: edges as X, Y, Z coordinate arrays
Return type:: ndarray(2,5), ndarray(2,5), ndarray(2,5)

Compute the edge line segments in the form of three coordinate matrices matrices that can be used to create a wireframe plot.

By default, the cube is drawn centred at the origin but its centre can be changed using centre or it can be arbitrarily positioned and oriented by specifying its pose.

Example:

>>> from machinevisiontoolbox import mkcube
>>> import matplotlib.pyplot as plt
>>> S = mkcube(edge=True)  # cube of side length 1
>>> fig = plt.figure()
>>> ax = fig.gca(projection='3d')
>>> ax.plot_wireframe(*S)

We can also use MATLAB-like syntax:

>>> X, Y, Z = mkcube(edge=True)
>>> ax.plot_wireframe(X, Y, Z)

Seealso:: mksphere, mkcylinder

machinevisiontoolbox.base.shapes.mksphere(r=1, n=20, centre=[0, 0, 0])[source]

Create a sphere

Parameters:

r (float, optional) – radius, defaults to 1
n (int, optional) – number of points around the equator, defaults to 20

Returns:

edges as X, Y, Z coordinate arrays

Return type:

ndarray(n,n), ndarray(n,n), ndarray(n,n)

Computes a tuple of three coordinate arrays that can be passed to matplotlib plot_wireframe to draw a sphere. By default, the sphere is drawn about the origin but its position can be changed using the centre option.

Example:

>>> from machinevisiontoolbox import mksphere
>>> import matplotlib.pyplot as plt
>>> S = mksphere()
>>> fig = plt.figure()
>>> ax = fig.gca(projection='3d')
>>> ax.plot_wireframe(*S)

We can also use MATLAB-like syntax:

>>> X, Y, Z = mksphere()
>>> ax.plot_wireframe(X, Y, Z)

Seealso:: mkcube, mkcylinder

machinevisiontoolbox.base.shapes.mkcylinder(r=1, h=1, n=20, symmetric=False, pose=None)[source]

Create a cylinder

Parameters:

r (array_like(m), optional) – radius, defaults to 1
h (float, optional) – height of the cylinder, defaults to 1
n (int, optional) – number of points around circumference, defaults to 20
symmetric – the cylinder’s z-extent is [-h/2, h/2]
pose (SE3, optional) – pose of the cylinder, defaults to None

Returns:

three coordinate arrays

Return type:

three ndarray(2,n)

Computes a tuple of three coordinate arrays that can be passed to matplotlib plot_wireframe to draw a cylinder of radius r about the z-axis from z=0 to z=``h``. The cylinder can be repositioned or reoriented using the pose option.

If radius r is array_like(2) then it represents the radius at the bottom and top of the cylinder and can be used to create a cone or conical frustum. If len(r)>2 then it allows the creation of a more complex shape with radius as a function of z.

Example:

>>> from machinevisiontoolbox import mkcylinder
>>> import matplotlib.pyplot as plt
>>> # draw a horizontal diablo shape
>>> r = np.linspace(0, 2*pi, 50)
>>> S = mkcylinder(r=np.cos(r) + 1.5, symmetric=True, pose=SE3.Rx(pi/2))
>>> fig = plt.figure()
>>> ax = fig.gca(projection='3d')
>>> ax.plot_wireframe(*S)
>>> plt.show()

Note

We can also use MATLAB-like syntax:

>>> X, Y, Z = mkcylinder()
>>> ax.plot_wireframe(X, Y, Z)

Seealso:: mkcube, mksphere