Image class core

class machinevisiontoolbox.ImageCore.Image(image=None, colororder=None, copy=False, shape=None, dtype=None, name=None, id=None, domain=None, **kwargs)[source]

Create an Image instance

Parameters

image (array_like(H,W), Image) – image data
colororder (str, dict) – order of color channels
copy (bool, optional) – copy the image data, defaults to False
shape (tuple, optional) – new shape for the image, defaults to None
dtype (str or NumPy dtype, optional) – data type for image, defaults to same type as image
name (str, optional) – name of image, defaults to None
id (int, optional) – numeric id of image, typically a sequence number, defaults to None
domain (array_like(W), array_like(H), optional) – domain of image, defaults to None

Raises

TypeError – unknown type passed to constructor

Create a new image instance which contains pixel values as well as information about image size, datatype, color planes and domain.

The image can be specified in several ways:

as an Image instance and its pixel array will be referenced by the new Image.
an a NumPy 2D or 3D array for a greyscale or color image respectively.
a lists of lists of pixel values, each inner list must have the same number of elements (columns).

Pixel datatype

The dtype of an image comes from the internal NumPy pixel array. If image is an Image instance or NumPy ndarray then its dtype is determined by the NumPy ndarray.

If image is given as a list of lists and dtype is not given, then the Image type is:

float32 if the list contains any floating point values, otherwise
the smallest signed or unsigned int that can represent its value span.

An image can have bool values. When used in a numerical expression its values will bs cast to numeric values of 0 or 1 representing False and True respectively.

Color planes

Images can have multiple planes, typically three (representing the primary colors red, green and blue) but any number is possible. In the underlying Numpy array these planes are identified by an integer plane index (the last dimension of the 3D array). The Image contains a dictionary that maps the name of a color plane to its index value. The color plane order can be specified as a dict or a string.

Image domain

An Image has a width and height in units of pixesl, but for some applications it is useful to specify the pixel coordinates in other units, perhaps metres, or latitude/longitude, or for a spherical image as azimuth and colatitude. The domain is specified by two 1D arrays that map the pixel coordinate to the domain variable.

Example:

>>> from machinevisiontoolbox import Image
>>> import numpy as np
>>> Image([[1, 2], [3, 4]])
Image: 2 x 2 (uint8)
>>> Image(np.array([[1, 2], [3, 4]]))
Image: 2 x 2 (int64)
>>> Image([[1, 2], [3, 1000]])
Image: 2 x 2 (uint16)
>>> Image([[0.1, 0.2], [0.3, 0.4]])
Image: 2 x 2 (float32)
>>> Image([[True, False], [False, True]])
Image: 2 x 2 (bool)

Note

By default the encapsulated pixel data is a reference to the passed image data.

Seealso: colororder colororder_str

__str__()[source]

Single line summary of image parameters

Returns: single line summary of image
Return type: str

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> str(img)
'Image: 640 x 426 (uint8), R:G:B [.../images/flowers1.png]'

print(fmt=None, seperator=' ', precision=2)[source]

Print image pixels in compact format

Parameters

fmt (str, optional) – format string, defaults to None
separator (str, optional) – value separator, defaults to single space
precision (int, optional) – precision for floating point pixel values, defaults to 2

Very compact display of pixel numerical values in grid layout.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Squares(1, 10)
>>> img.print()
0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0
0 1 1 1 1 1 0 0 0
0 1 1 1 1 1 0 0 0
0 1 1 1 1 1 0 0 0
0 1 1 1 1 1 0 0 0
0 1 1 1 1 1 0 0 0
0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0
>>> img = Image.Squares(1, 10, dtype='float')
>>> img.print()
00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00
00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00
00 0.00 1.00 1.00 1.00 1.00 1.00 0.00 0.00 0.00
00 0.00 1.00 1.00 1.00 1.00 1.00 0.00 0.00 0.00
00 0.00 1.00 1.00 1.00 1.00 1.00 0.00 0.00 0.00
00 0.00 1.00 1.00 1.00 1.00 1.00 0.00 0.00 0.00
00 0.00 1.00 1.00 1.00 1.00 1.00 0.00 0.00 0.00
00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00
00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00
00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00

Note

For a boolean image True and False are displayed as 1 and 0 respectively.
For a multiplane images the planes are printed sequentially.

Seealso: showpixels

copy(copy=True)[source]

Create image copy

Parameters: copy (bool) – copy the image data
Returns: copy of image
Return type: Image

Create a new Image instance which contains a copy of the original image data. If copy is False the new Image instance contains a reference to the original image data.

property colororder

Set/get color order of image

The color order is a dict where the key is the color plane name, eg. ‘R’ and the value is the index of the plane in the 3D pixel value array.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.colororder
{'R': 0, 'G': 1, 'B': 2}
>>> img.colororder = "BGR"
>>> img.colororder
{'B': 0, 'G': 1, 'R': 2}

When setting the color order the value can be any of:

simple string, one plane per character, eg. "RGB"
colon separated string, eg. "R:G:B", "L*:a*:b*"
dictionary, eg. dict(R=0, G=1, B=2)

For the first two cases the color plane indices are implicit in the order in the string.

Note

Changing the color order does not change the order of the planes in the image array, it simply changes their label.

Seealso: colororder_str colordict plane red green blue

static colordict(colororder)[source]

Parse a color order specification

Parameters: colororder (str, dict) – order of color channels
Raises: ValueError – colororder not a string or dict
Returns: dictionary mapping color names to plane indices
Return type: dict

The color order the value can be given in a variety of forms:

simple string, one plane per character, eg. "RGB"
colon separated string, eg. "R:G:B", "L*:a*:b*"
dictionary, eg. dict(R=0, G=1, B=2)

Example:

>>> from machinevisiontoolbox import Image
>>> Image.colordict('RGB')
{'R': 0, 'G': 1, 'B': 2}
>>> Image.colordict('red:green:blue')
{'red': 0, 'green': 1, 'blue': 2}
>>> Image.colordict({'L*': 0, 'U*': 1, 'V*': 2})
{'L*': 0, 'U*': 1, 'V*': 2}

property colororder_str

Image color order as a string

Returns: Image color plane order as a colon separated string.
Return type: str

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.colororder_str
'R:G:B'

Seealso: colororder

property name

Set/get image name

An image has a string-valued name that can be read and written. The name is shown by the Image repr and when images are displayed graphically.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.name[-70:]
'on/3.9.14/x64/lib/python3.9/site-packages/mvtbdata/images/flowers1.png'
>>> img.name = 'my image'
>>> img.name
'my image'

Note

Images loaded from a file have their name initially set to the full file pathname.

Seealso: Read

property isfloat

Image has floating point pixel values

Returns: True if image has floating point values
Return type: bool

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.isfloat
False
>>> img = Image.Read('flowers1.png', dtype='float32')
>>> img.isfloat
True

Seealso: isint isbool

property isint

Image has integer values

Returns: True if image has integer pixel values
Return type: bool

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.isint
True
>>> img = Image.Read('flowers1.png', dtype='float32')
>>> img.isint
False

Seealso: isfloat isbool

property isbool

Image has bolean values

Returns: True if image has boolean pixel values
Return type: bool

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png') > 200
>>> img.isint
False
>>> img.isbool
True

Seealso: isint isfloat

property dtype

Datatype of image

Returns: NumPy datatype of image
Return type: numpy.dtype

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.dtype
dtype('uint8')
>>> img = Image.Read('flowers1.png', dtype='float32')
>>> img.dtype
dtype('float32')

Seealso: to to_int to_float like cast numpy.dtype

property width

Image width

Returns: Width of image in pixels
Return type: int

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.width
640

Seealso: height size umax

property height

Image height

Returns: Height of image in pixels
Return type: int

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.height
426

Seealso: width size vmax

property umax

Image maximum u-coordinate

Returns: Maximum u-coordinate in image in pixels
Return type: int

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.umax
639

Seealso: width

property vmax

Image maximum v-coordinate

Returns: Maximum v-coordinate in image in pixels
Return type: int

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.vmax
425

Seealso: height

uspan(step=1)[source]

Linear span of image horizontally

Parameters: step (int, optional) – step size, defaults to 1
Returns: 1D array of values [0 … width-1]
Return type: ndarray(W)

Example:

>>> from machinevisiontoolbox import Image
>>> import numpy as np
>>> img = Image.Read('flowers1.png')
>>> with np.printoptions(threshold=10):
...     img.uspan()
... 
array([  0,   1,   2, ..., 637, 638, 639])

Note

If the image has a domain specified the horizontal component of this is returned instead.

Warning

Computed using numpy.arange and for step>1 the maximum coordinate may not be returned.

Seealso: umax vspan

vspan(step=1)[source]

Linear span of image vertically

Parameters: step (int, optional) – step size, defaults to 1
Returns: 1D array of values [0 … height-1]
Return type: ndarray(H)

Example:

>>> from machinevisiontoolbox import Image
>>> import numpy as np
>>> img = Image.Read('flowers1.png')
>>> with np.printoptions(threshold=10):
...     img.vspan()
... 
array([  0,   1,   2, ..., 423, 424, 425])

Note

If the image has a domain specified the vertical component of this is returned instead.

Warning

Computed using numpy.arange and for step>1 the maximum coordinate may not be returned.

Seealso: vmax uspan

property size

Image size

Returns: Size of image (width, height)
Return type: tuple

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.size
(640, 426)

Seealso: width height

property centre

Coordinate of centre pixel

Returns: Coordinate (u,v) of the centre pixel
Return type: tuple

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Zeros((50,50))
>>> img.centre
(24.5, 24.5)
>>> img = Image.Zeros((51,51))
>>> img.centre
(25.0, 25.0)

Note

If the image has an even dimension the centre will lie between pixels.

Seealso: center centre_int

property center

Coordinate of center pixel

Returns: Coordinate (u,v) of the centre pixel
Return type: tuple

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Zeros((50,50))
>>> img.center
(24.5, 24.5)
>>> img = Image.Zeros((51,51))
>>> img.center
(25.0, 25.0)

Note

If the image has an even dimension the centre will lie between pixels.
Same as centre, just US spelling

Seealso: center_int

property centre_int

Coordinate of centre pixel as integer

Returns: Coordinate (u,v) of the centre pixel
Return type: tuple

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Zeros((50,50))
>>> img.centre_int
(24, 24)
>>> img = Image.Zeros((51,51))
>>> img.centre_int
(25, 25)

Note

If the image has an even dimension the centre coordinate will be truncated toward zero.

Seealso: centre

property center_int

Coordinate of centre pixel as integer

Returns: Coordinate (u,v) of the centre pixel
Return type: tuple

Integer coordinate of centre pixel.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Zeros((50,50))
>>> img.center_int
(24, 24)
>>> img = Image.Zeros((51,51))
>>> img.center_int
(25, 25)

Note

If the image has an even dimension the centre coordinate will be truncated toward zero.
Same as centre_int, just US spelling

Seealso: center

property npixels

Number of pixels in image plane

Returns: Number of pixels in image plane: width x height
Return type: int

Note

Number of planes is not considered.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.npixels
272640
>>> img.width * img.height
272640

Seealso: size

property shape

Image shape

Returns: Shape of internal NumPy array
Return type: 2-tuple, or 3-tuple if color

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.shape
(426, 640, 3)
>>> img = Image.Read('street.png')
>>> img.shape
(851, 1280)

Seealso: nplanes ndim iscolor

property ndim

Number of image array dimensions

Returns: number of image dimensions
Return type: int

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.ndim
3
>>> img = Image.Read('street.png')
>>> img.ndim
2

Seealso: nplanes shape

contains(p)[source]

Test if coordinate lies within image

Parameters: p (array_like(2), ndarray(2,N)) – pixel coordinate
Returns: whether pixel coordinate lies within image bounds
Return type: bool, ndarray(N)

Example:

>>> from machinevisiontoolbox import Image
>>> import numpy as np
>>> img = Image.Zeros(10)
>>> img.contains((4,6))
True
>>> img.contains((-1, 7))
False
>>> img.contains(np.array([[4, 6], [-1, 7], [10, 10]]).T)
array([ True, False, False])

property iscolor

Image has color pixels

Returns: Image is color
Return type: bool
Returns: number of image dimensions
Return type: int

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.iscolor
True
>>> img = Image.Read('street.png')
>>> img.iscolor
False

Seealso: isrgb nplanes

property isbgr

Image has BGR color order

Returns: Image has BGR color order
Return type: bool

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.isbgr
False

Note

Is False if image is not color.

Seealso: colororder

property isrgb

Image has RGB color order

Returns: Image has RGB color order
Return type: bool

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.isrgb
True

Note

Is False if image is not color.

Seealso: colororder

to(dtype)[source]

Convert image datatype

Parameters: dtype (str) – Numpy data type
Returns: image
Return type: Image

Create a new image, same size as input image, with pixels of a different datatype. Integer values are scaled according to the maximum value of the datatype, floating values are in the range 0.0 to 1.0.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Random(3)
>>> img.image
array([[194, 140, 177],
       [226, 131, 219],
       [109, 235,   6]], dtype=uint8)
>>> img.to('float').image
array([[0.7608, 0.549 , 0.6941],
       [0.8863, 0.5137, 0.8588],
       [0.4275, 0.9216, 0.0235]])
>>> img = Image.Random(3, dtype='float')
>>> img.image
array([[0.7882, 0.6669, 0.2148],
       [0.3297, 0.8582, 0.6315],
       [0.5968, 0.955 , 0.0799]])
>>> img.to('uint8').image
array([[201, 170,  55],
       [ 84, 219, 161],
       [152, 244,  20]], dtype=uint8)

Seealso: astype to_int to_float

astype(dtype)[source]

Cast image datatype

Parameters: dtype (str) – Numpy data type
Returns: image
Return type: Image

Create a new image, same size as input image, with pixels of a different datatype. Values are retained, only the datatype is changed.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Random(3)
>>> img.image
array([[156, 100,  13],
       [166, 144, 242],
       [129, 253,  55]], dtype=uint8)
>>> img.astype('float').image
array([[156., 100.,  13.],
       [166., 144., 242.],
       [129., 253.,  55.]])
>>> img = Image.Random(3, dtype='float')
>>> img.image
array([[0.4456, 0.0919, 0.064 ],
       [0.6974, 0.0798, 0.0194],
       [0.8629, 0.559 , 0.8381]])
>>> img.astype('uint8').image
array([[0, 0, 0],
       [0, 0, 0],
       [0, 0, 0]], dtype=uint8)

Seealso: to

property image

Image as NumPy array

Returns: image as a NumPy array
Return type: ndarray(H,W) or ndarray(H,W,3)

Return a reference to the encapsulated NumPy array that holds the pixel values.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img
Image: 640 x 426 (uint8), R:G:B [.../images/flowers1.png]
>>> type(img)
<class 'machinevisiontoolbox.ImageCore.Image'>
>>> type(img.image)
<class 'numpy.ndarray'>

Note

For a color image the color plane order is given by the colororder dictionary.

Seealso: A colororder

property A

Set/get the NumPy array containing pixel values

Getting

Returns: image as a NumPy array
Return type: ndarray(H,W) or ndarray(H,W,3)

Return a reference to the encapsulated NumPy array that holds the pixel values.

Setting

Replace the encapsulated NumPy array with another.

Example:

>>> from machinevisiontoolbox import Image
>>> import numpy as np
>>> img = Image.Read('flowers1.png')
>>> img
Image: 640 x 426 (uint8), R:G:B [.../images/flowers1.png]
>>> type(img)
<class 'machinevisiontoolbox.ImageCore.Image'>
>>> type(img.A)
<class 'numpy.ndarray'>
>>> img.A = np.zeros((50,50))
>>> img
Image: 50 x 50 (float64) [.../images/flowers1.png]

Seealso: image

property rgb

Image as NumPy array in RGB color order

Raises: ValueError – image is greyscale
Returns: image as a NumPy array in RGB color order
Return type: ndarray(H,W,3)

The image is guaranteed to be in RGB order irrespective of current color order.

Seealso: image bgr colororder

property bgr

Image as NumPy array in BGR color order

Raises: ValueError – image is greyscale
Returns: image as a NumPy array in BGR color order
Return type: ndarray(H,W,3)

The image is guaranteed to be in BGR (OpenCV standard) order irrespective of current color order.

Seealso: image rgb colororder

to_int(intclass='uint8')[source]

Convert image to integer NumPy array

Parameters: intclass (str, optional) – name of NumPy supported integer class, default is ‘uint8’
Returns: NumPy array with integer values
Return type: ndarray(H,W) or ndarray(H,W,P)

Return a NumPy array with pixels converted to the integer class intclass. For the case where the input image is:

a floating point class, the pixel values are scaled from an input range of [0,1] to a range spanning zero to the maximum positive value of the output integer class.
an integer class, then the pixels are scaled and cast to intclass. The scale factor is the ratio of the maximum value of the input and output integer classes.
boolean class, False is mapped to zero and True is mapped to the maximum positive value.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[5_000, 10_000], [30_000, 60_000]])
>>> img
Image: 2 x 2 (uint16)
>>> img.to_int('uint8')
array([[ 19,  38],
       [116, 233]], dtype=uint8)
>>> img.to_int('uint32')
array([[ 327685000,  655370000],
       [1966110000, 3932220000]], dtype=uint32)
>>> img = Image([[0.0, 0.3], [0.5, 1.0]])
>>> img
Image: 2 x 2 (float32)
>>> img.to_int('uint8')
array([[  0,  76],
       [128, 255]], dtype=uint8)
>>> img = Image([[False, True], [True, False]])
>>> img
Image: 2 x 2 (bool)
>>> img.to_int('uint8')
array([[  0, 255],
       [255,   0]], dtype=uint8)
>>> img.to_int('uint16')
array([[    0, 65535],
       [65535,     0]], dtype=uint16)

Note

Works for greyscale or color (arbitrary number of planes) image

Seealso: to_float cast like

to_float(floatclass='float32')[source]

Convert image to float NumPy array

Parameters: floatclass (str) – ‘single’, ‘double’, ‘float32’ [default], ‘float64’
Returns: Image with floating point pixel types
Return type: Image

Return a NumPy array with pixels converted to the floating point class floatclass and the values span the range 0 to 1. For the case where the input image is:

an integer class, the pixel values are scaled from an input range spanning zero to the maximum positive value of the integer class to [0.0, 1.0]
a floating class, the pixels are cast to change type but not their value.
boolean class, False is mapped to 0.0 and True is mapped to 1.0.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[50, 100], [150, 200]])
>>> img
Image: 2 x 2 (uint8)
>>> img.to_float()
array([[0.1961, 0.3922],
       [0.5882, 0.7843]], dtype=float32)
>>> img = Image([[0.0, 0.3], [0.5, 1.0]])
>>> img
Image: 2 x 2 (float32)
>>> img.to_float('float64')
array([[0. , 0.3],
       [0.5, 1. ]])
>>> img = Image([[False, True], [True, False]])
>>> img.to_float()
array([[0., 1.],
       [1., 0.]], dtype=float32)

Note

Works for greyscale or color (arbitrary number of planes) image

Seealso: to_int cast like

cast(value)[source]

Cast value to same type as image

Parameters: value (scalar, ndarray) – value to cast
Returns: value cast to same type as image
Return type: numpy type, ndarray

The value, scalar or integer, is cast to the same type as the image. The result has the same numeric value, but the type is changed.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> x = img.cast(12.5)
>>> x
12
>>> type(x)
<class 'numpy.uint8'>

Note

Scalars are cast to NumPy types not native Python types.

Seealso: like

like(value, maxint=None)[source]

Convert value to the same type as image

Parameters

value (scalar, ndarray) – scalar or NumPy array
maxint (int, optional) – maximum integer value for an integer image, defaults to maximum positive value of the class

Raises

ValueError – [description]

Returns

converted value

Return type

NumPy type

The value, scalar or integer, is converted to the same type as the image. The result is optionally rescaled and cast:

Float to float: values are cast
Float to int: values in the interval [0, 1] are scaled to the interval [0, maxint] and then cast
Int to float: values in the interval [0, maxint] are scaled to the interval [0, 1] and then cast.
Int to int: values are scaled and cast.

Warning

For integer to integer conversion, integer values greater than the maximum value of the destination class are wrapped not clipped.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.like(0.5)
127

Seealso: cast to_int to_float

property minval

Minimum value of image datatype

Returns: Minimum value
Return type: int or float

For the datatype of the image, return its minimum possible value

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Zeros(20, dtype='float32')
>>> img.minval
-3.4028235e+38
>>> img = Image.Zeros(20, dtype='uint8')
>>> img.minval
0

Seealso: maxval

property maxval

Maximum value of image datatype

Returns: Maximum value
Return type: int or float

For the datatype of the image, return its maximum possible value

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Zeros(20, dtype='float32')
>>> img.maxval
3.4028235e+38
>>> img = Image.Zeros(20, dtype='uint8')
>>> img.maxval
255

Seealso: minval

property true

True value for logical image

Returns: Value used as true
Return type: int or float

The true value is 1.0 for a floating point image and maximum integer value for an integer value.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Zeros(20, dtype='float32')
>>> img.true
1.0
>>> img = Image.Zeros(20, dtype='uint8')
>>> img.true
255

Seealso: false maxval

property false

False value for logical image

Returns: Value used as true
Return type: int or float

The false value is 0.0 for a floating point image and 0 value for an integer value.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Zeros(20, dtype='float32')
>>> img.false
0
>>> img = Image.Zeros(20, dtype='uint8')
>>> img.false
0

Seealso: true

property nplanes

Number of color planes

Returns: Number of color planes
Return type: int

For a 2D or greyscale image this is one, otherwise it is the third dimension of the image.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('street.png')
>>> img.nplanes
1
>>> img = Image.Read('flowers1.png')
>>> img.nplanes
3

Note

A greyscale image is stored internally as a 2D NumPy array which has zero planes, but nplanes will return ` in that case.

Seealso: shape ndim

plane(planes)[source]

Extract the i’th plane of a color image

Parameters: planes (int, list, str) – planes to extract
Raises: ValueError – if image is not color
Return out: image containing only the selected planes
Return type: Image

Create a new image from the selected planes of the image.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read("flowers4.png") # in BGR order
>>> img.colororder_str
'R:G:B'
>>> img.nplanes
3
>>> red = img.plane(0) # red plane
>>> red
Image: 640 x 426 (uint8)
>>> red.iscolor
False
>>> red.nplanes
1
>>> green_blue = img.plane('G:B') # green and blue planes
>>> green_blue
Image: 640 x 426 (uint8), G:B
>>> green_blue.iscolor
True
>>> green_blue.nplanes
2
>>> red_blue = img.plane([0, 2]) # blue and red planes
>>> red_blue
Image: 640 x 426 (uint8), R:B

Note

This can also be performed using the overloaded __getitem__ operator.
To select more than one plane, use either a sequence of integers or a string of colon separated plane names.

Seealso: red green blue :meth:__getitem__

__getitem__(key)[source]

Extract slice of image

Parameters: key – slice to extract
Returns: slice of image
Return type: Image

Create a new image from the selected slice of the image, either a plane or a region of interest. If key is:

an int, select this plane
a string, select this named plane or planes
a 2-tuple of slice objects, select this uv-region across all planes
a 3-tuple of slice objects, select this region of uv and planes

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read("flowers4.png") # in RGB order
>>> red = img[0] # red plane
>>> red
Image: 640 x 426 (uint8)
>>> green = img["G"]
>>> green
Image: 640 x 426 (uint8)
>>> roi = img[100:200, 300:400]
>>> roi
Image: 100 x 100 (uint8), R:G:B
>>> roi = img[100:200, 300:400, 1:]
>>> roi
Image: 100 x 100 (uint8), G:B

Seealso: red green blue plane roi

red()[source]

Extract the red plane of a color image

Raises: ValueError – if image is not color
Return out: greyscale image representing the red image plane
Return type: Image

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read("flowers4.png")
>>> red = img.red() # red plane
>>> red
Image: 640 x 426 (uint8)
>>> red.iscolor
False

Seealso: plane green blue

green()[source]

Extract the green plane of a color image

Raises: ValueError – if image is not color
Return out: greyscale image representing the green image plane
Return type: Image

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read("flowers4.png")
>>> green = img.green() # green plane
>>> green
Image: 640 x 426 (uint8)
>>> green.iscolor
False

Seealso: plane red blue

blue()[source]

Extract the blue plane of a color image

Raises: ValueError – if image is not color
Return out: greyscale image representing the blue image plane
Return type: Image

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read("flowers4.png")
>>> blue = img.blue() # blue plane
>>> blue
Image: 640 x 426 (uint8)
>>> blue.iscolor
False

Seealso: plane red green

__mul__(other)[source]

Overloaded * operator

Returns: elementwise product of images
Return type: Image

Compute the product of an Image with another image or a scalar. Supports:

image * image, elementwise
scalar * image
image * scalar

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[1, 2], [3, 4]])
>>> z = img * img
>>> z.image
array([[ 1,  4],
       [ 9, 16]], dtype=uint8)
>>> z = 2 * img
>>> z.image
array([[2, 4],
       [6, 8]], dtype=uint8)

..warning:: Values will be wrapped not clipped to the range of the: pixel datatype.

__pow__(other)[source]

Overloaded ** operator

Returns: elementwise exponent of image
Return type: Image

Compute the elementwise power of an Image.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[1, 2], [3, 4]])
>>> z = img**3
>>> z.image
array([[ 1,  8],
       [27, 64]], dtype=uint8)

..warning:: Values will be wrapped not clipped to the range of the: pixel datatype.

__add__(other)[source]

Overloaded + operator

Returns: elementwise addition of images
Return type: Image

Compute the sum of an Image with another image or a scalar. Supports:

image + image, elementwise
scalar + image
image + scalar

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[1, 2], [3, 4]])
>>> z = img + img
>>> z.image
array([[2, 4],
       [6, 8]], dtype=uint8)
>>> z = 10 + img
>>> z.image
array([[11, 12],
       [13, 14]], dtype=uint8)

..warning:: Values will be wrapped not clipped to the range of the: pixel datatype.

__sub__(other)[source]

Overloaded - operator

Returns: elementwise subtraction of images
Return type: Image

Compute the difference of an Image with another image or a scalar. Supports:

image - image, elementwise
scalar - image
image - scalar

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[1, 2], [3, 4]])
>>> z = img - img
>>> z.image
array([[0, 0],
       [0, 0]], dtype=uint8)
>>> z = img - 1
>>> z.image
array([[0, 1],
       [2, 3]], dtype=uint8)

..warning:: Values will be wrapped not clipped to the range of the: pixel datatype.

__truediv__(other)[source]

Overloaded / operator

Returns: elementwise division of images
Return type: Image

Compute the quotient of an Image with another image or a scalar. Supports:

image / image, elementwise
scalar / image
image / scalar

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[1, 2], [3, 4]])
>>> z = img / img
>>> z.image
array([[1., 1.],
       [1., 1.]])
>>> z = img / 2
>>> z.image
array([[0.5, 1. ],
       [1.5, 2. ]])

Note

The resulting values are floating point.

__floordiv__(other)[source]

Overloaded // operator

Returns: elementwise floored division of images
Return type: Image

Compute the integer quotient of an Image with another image or a scalar. Supports:

image // image
scalar // image
image // scalar

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[1, 2], [3, 4]])
>>> z = img / 2
>>> z.image
array([[0.5, 1. ],
       [1.5, 2. ]])
>>> z = img // 2
>>> z.image
array([[0, 1],
       [1, 2]], dtype=uint8)

__and__(other)[source]

Overloaded & operator

Returns: elementwise binary-and of images
Return type: Image

Compute the binary-and of an Image with another image or a scalar. Supports:

image & image
scalar & image
image & scalar

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[1, 2], [3, 4]])
>>> z = img & Image([[2, 2], [2, 2]])
>>> z.image
array([[0, 2],
       [2, 0]], dtype=uint8)
>>> z = img & 1
>>> z.image
array([[1, 0],
       [1, 0]], dtype=uint8)

__or__(other)[source]

Overloaded | operator

Returns: elementwise binary-or of images
Return type: Image

Compute the binary-or of an Image with another image or a scalar. Supports:

image | image
scalar | image
image | scalar

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[1, 2], [3, 4]])
>>> z = img | Image([[2, 2], [2, 2]])
>>> z.image
array([[3, 2],
       [3, 6]], dtype=uint8)
>>> z = img | 1
>>> z.image
array([[1, 3],
       [3, 5]], dtype=uint8)

__eq__(other)[source]

Overloaded == operator

Returns: elementwise comparison of pixels
Return type: bool Image

Compute the equality between an Image and another image or a scalar. Supports:

image == image

scalar == image

image == scalar

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[1, 2], [3, 4]])
>>> z = img == 2
>>> z.image
array([[False,  True],
       [False, False]])
>>> z = img == Image([[0, 2], [3, 4]])
>>> z.image
array([[False,  True],
       [ True,  True]])

Seealso: true false

__ne__(other)[source]

Overloaded != operator

Returns: elementwise comparison of pixels
Return type: bool Image

Compute the inequality between an Image and another image or a scalar. Supports:

image != image

scalar != image

image != scalar

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[1, 2], [3, 4]])
>>> z = img != 2
>>> z.image
array([[ True, False],
       [ True,  True]])
>>> z = img != Image([[0, 2], [3, 4]])
>>> z.image
array([[ True, False],
       [False, False]])

Seealso: true false

__gt__(other)[source]

Overloaded > operator

Returns: elementwise comparison of pixels
Return type: bool Image

Compute the inequality between an Image and another image or a scalar. Supports:

image > image

scalar > image

image > scalar

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[1, 2], [3, 4]])
>>> z = img > 2
>>> z.image
array([[False, False],
       [ True,  True]])
>>> z = img > Image([[0, 2], [3, 4]])
>>> z.image
array([[ True, False],
       [False, False]])

Seealso: true false

__ge__(other)[source]

Overloaded >= operator

Returns: elementwise comparison of pixels
Return type: bool Image

Compute the inequality between an Image and another image or a scalar. Supports:

image >= image

scalar >= image

image >= scalar

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[1, 2], [3, 4]])
>>> z = img >= 2
>>> z.image
array([[False,  True],
       [ True,  True]])
>>> z = img >= Image([[0, 2], [3, 4]])
>>> z.image
array([[ True,  True],
       [ True,  True]])

Seealso: true false

__lt__(other)[source]

Overloaded < operator

Returns: elementwise comparison of images
Return type: bool Image

Compute the inequality between an Image and another image or a scalar. Supports:

image < image

scalar < image

image < scalar

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[1, 2], [3, 4]])
>>> z = img < 2
>>> z.image
array([[ True, False],
       [False, False]])
>>> z = img < Image([[10, 2], [3, 4]])
>>> z.image
array([[ True, False],
       [False, False]])

Seealso: true false

__le__(other)[source]

Overloaded <= operator

Returns: elementwise comparison of images
Return type: bool Image

Compute the inequality between an Image and another image or a scalar. Supports:

image <= image

scalar <= image

image <= scalar

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[1, 2], [3, 4]])
>>> z = img <= 2
>>> z.image
array([[ True,  True],
       [False, False]])
>>> z = img <= Image([[0, 2], [3, 4]])
>>> z.image
array([[False,  True],
       [ True,  True]])

Seealso: true false

__invert__()[source]

Overloaded ~ operator

Returns: elementwise inversion of logical values
Return type: boo, Image

Returns logical not operation where image values are interpretted as:

floating image: True is 1.0, False is 0.0

integer image: True is maximum value, False is 0 True is 1 and False is 0.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[True, False], [False, True]])
>>> z = ~img
>>> z.image
array([[False,  True],
       [ True, False]])

abs()[source]

Absolute value of image

Returns: elementwise absolute value of image
Return type: Image

Return elementwise absolute value of pixel values.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[-1, 2], [3, -4]], dtype='int8')
>>> z = img.abs()
>>> z.image
array([[1, 2],
       [3, 4]], dtype=int8)

sqrt()[source]

Square root of image

Returns: elementwise square root of image
Return type: Image

Return elementwise square root of pixel values.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[1, 2], [3, 4]])
>>> z = img.sqrt()
>>> z.image
array([[1.   , 1.414],
       [1.732, 2.   ]], dtype=float16)

sum(*args, **kwargs)[source]

Sum of all pixels

Parameters

args – additional positional arguments to numpy.sum
kwargs – additional keyword arguments to numpy.sum

Returns

sum

Computes the sum of pixels in the image:

\[\sum_{uvc} I_{uvc}\]

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.sum()  # R+G+B
86260474
>>> img.sum(axis=(0,1)) # sum(R), sum(G), sum(B)
array([28267315, 30542247, 27450912], dtype=uint64)
>>> img = Image.Read('flowers1.png', dtype='float32')
>>> img.sum(axis=2)
array([[0.6275, 0.6196, 0.851 , ..., 2.5412, 2.5569, 2.8471],
       [0.6078, 0.6275, 0.8588, ..., 2.6431, 2.7451, 2.9961],
       [0.6118, 0.6196, 0.8157, ..., 2.3608, 2.9098, 2.9843],
       ...,
       [1.0784, 0.8784, 0.8353, ..., 1.098 , 1.1216, 1.1725],
       [1.0314, 0.851 , 0.7412, ..., 1.0706, 1.0902, 1.1412],
       [0.9647, 0.8039, 0.7059, ..., 1.0157, 1.0588, 1.1059]],
      dtype=float32)

Note

The return value type is the same as the image type.
By default the result is a scalar computed over all pixels, if the axis option is given the results is a 1D or 2D NumPy array.

Seealso: numpy.sum mpq npq upq

min(*args, **kwargs)[source]

Minimum value of all pixels

Parameters

args – additional positional arguments to numpy.min
kwargs – additional keyword arguments to numpy.min

Returns

minimum value

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.min()
0
>>> img = Image.Read('flowers1.png', dtype='float32')
>>> img.min(axis=2)
array([[0.0667, 0.0627, 0.1529, ..., 0.698 , 0.6353, 0.8667],
       [0.0627, 0.0667, 0.149 , ..., 0.7529, 0.8   , 0.9961],
       [0.0667, 0.0627, 0.1412, ..., 0.5804, 0.9294, 0.9843],
       ...,
       [0.2039, 0.1608, 0.1529, ..., 0.2627, 0.2549, 0.2627],
       [0.2078, 0.1725, 0.1412, ..., 0.2549, 0.2471, 0.2549],
       [0.2039, 0.1765, 0.1686, ..., 0.2275, 0.2314, 0.251 ]],
      dtype=float32)

Note

The return value type is the same as the image type.
By default the result is a scalar computed over all pixels, if the axis option is given the results is a 1D or 2D NumPy array.

Seealso: numpy.min

max(*args, **kwargs)[source]

Maximum value of all pixels

Parameters

args – additional positional arguments to numpy.max
kwargs – additional keyword arguments to numpy.max

Returns

maximum value

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.max()
255
>>> img = Image.Read('flowers1.png', dtype='float32')
>>> img.max(axis=2)
array([[0.4353, 0.4039, 0.4157, ..., 0.9294, 0.9686, 1.    ],
       [0.4275, 0.4118, 0.4157, ..., 0.949 , 0.9765, 1.    ],
       [0.4157, 0.4157, 0.4118, ..., 0.9176, 0.9961, 1.    ],
       ...,
       [0.502 , 0.4314, 0.4235, ..., 0.502 , 0.5176, 0.5451],
       [0.4706, 0.4078, 0.3725, ..., 0.4902, 0.5059, 0.5255],
       [0.4392, 0.3804, 0.3333, ..., 0.4706, 0.4941, 0.5098]],
      dtype=float32)

Note

The return value type is the same as the image type.
By default the result is a scalar computed over all pixels, if the axis option is given the results is a 1D or 2D NumPy array.

Seealso: numpy.max

mean(*args, **kwargs)[source]

Mean value of all pixels

Parameters

args – additional positional arguments to numpy.mean
kwargs – additional keyword arguments to numpy.mean

Returns

mean value

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.mean()
105.4632164514867
>>> img = Image.Read('flowers1.png', dtype='float32')
>>> img.mean(axis=2)
array([[0.2092, 0.2065, 0.2837, ..., 0.8471, 0.8523, 0.949 ],
       [0.2026, 0.2092, 0.2863, ..., 0.881 , 0.915 , 0.9987],
       [0.2039, 0.2065, 0.2719, ..., 0.7869, 0.9699, 0.9948],
       ...,
       [0.3595, 0.2928, 0.2784, ..., 0.366 , 0.3739, 0.3908],
       [0.3438, 0.2837, 0.2471, ..., 0.3569, 0.3634, 0.3804],
       [0.3216, 0.268 , 0.2353, ..., 0.3386, 0.3529, 0.3686]],
      dtype=float32)

Note

The return value type is the same as the image type.
By default the result is a scalar computed over all pixels, if the axis option is given the results is a 1D or 2D NumPy array.

Seealso: numpy.mean

std(*args, **kwargs)[source]

Standard deviation of all pixels

Parameters

args – additional positional arguments to numpy.std
kwargs – additional keyword arguments to numpy.std

Returns

standard deviation value

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.std()
64.30520799436279
>>> img = Image.Read('flowers1.png', dtype='float32')
>>> img.std()
0.25217727

Note

The return value type is the same as the image type.
By default the result is a scalar computed over all pixels, if the axis option is given the results is a 1D or 2D NumPy array.

Seealso: numpy.std

var(*args, **kwargs)[source]

Variance of all pixels

Parameters

args – additional positional arguments to numpy.var
kwargs – additional keyword arguments to numpy.var

Returns

variance value

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.var()
64.30520799436279
>>> img = Image.Read('flowers1.png', dtype='float32')
>>> img.var()
0.25217727

Note

The return value type is the same as the image type.
By default the result is a scalar computed over all pixels, if the axis option is given the results is a 1D or 2D NumPy array.

Seealso: numpy.var

median(*args, **kwargs)[source]

Median value of all pixels

Parameters

args – additional positional arguments to numpy.median
kwargs – additional keyword arguments to numpy.median

Returns

median value

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.median()
92.0
>>> img = Image.Read('flowers1.png', dtype='float32')
>>> img.median()
0.36078432

Note

The return value type is the same as the image type.
By default the result is a scalar computed over all pixels, if the axis option is given the results is a 1D or 2D NumPy array.

Seealso: numpy.median

stats()[source]

Display pixel value statistics

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('flowers1.png')
>>> img.stats()
R: range=0 - 255, mean=103.680, sdev=74.346
G: range=0 - 255, mean=112.024, sdev=50.040
B: range=0 - 255, mean=100.686, sdev=65.614

draw_line(start, end, **kwargs)[source]

Draw line into image

Parameters

start (array_like(2)) – start coordinate (u,v)
end (array_like(2)) – end coordinate (u,v)
kwargs – parameters passed to draw_line

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Zeros(100)
>>> img.draw_line((20,30), (60,70), color=200)
>>> img.disp()
<matplotlib.image.AxesImage object at 0x7feeddc25940>
>>> img = Image.Zeros(100, colororder="RGB")
>>> img.draw_line((20,30), (60,70), color=[0, 200, 0]) # green line
>>> img.disp()
<matplotlib.image.AxesImage object at 0x7feeddc41670>

Note

If the image has N planes the color should have N elements.

Seealso: draw_line

draw_circle(centre, radius, **kwargs)[source]

Draw circle into image

Parameters

centre (array_like(2)) – centre coordinate (u,v)
radius (int) – circle radius in pixels
kwargs – parameters passed to draw_circle

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Zeros(100)
>>> img.draw_circle((20,30), 15, color=200)
>>> img.disp()
<matplotlib.image.AxesImage object at 0x7f27c7cb8940>
>>> img = Image.Zeros(100, colororder="RGB")
>>> img.draw_circle((20,30), 15, color=[0, 200, 0], thickness=-1) # filled green circle
>>> img.disp()
<matplotlib.image.AxesImage object at 0x7f27c7cd4670>

Note

If the image has N planes the color should have N elements.

Seealso: draw_circle

draw_box(**kwargs)[source]

Draw box into image

Parameters: kwargs – parameters passed to draw_box

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Zeros(100)
>>> img.draw_box(lt=(20,70), rb=(60,30), color=200)
>>> img.disp()
<matplotlib.image.AxesImage object at 0x7f630ff119d0>
>>> img = Image.Zeros(100, colororder="RGB")
>>> img.draw_box(lt=(20,70), rb=(60,30), color=[0, 200, 0], thickness=-1)  # filled green box
>>> img.disp()
<matplotlib.image.AxesImage object at 0x7f630ff2d700>

Note

If the image has N planes the color should have N elements.

Seealso: draw_box