The `Image` object#

The Image class is essential for all image operations and processing within this Toolbox. The class encapsulates a NumPy array that contains the pixel values of a greyscale or color image as a 2D or 3D array respectively. An Image instance has a very large number of methods that perform useful operations on an image and wrap low-level operations performed using NumPy or OpenCV.

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
size (tuple, optional) – new size 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
binary (bool, optional) – create binary image, non-zero values are set to True, defaults to False

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 pixel data is stored in a NumPy array, encapsulated by the object.

An image is considered to be a two-dimensional (width x height) grid of pixel values, that lie within one or more “color” planes.

The image data can be specified by:

a NumPy 2D or 3D array for a greyscale or color image respectively. For the latter case, the last index represents the color plane:
```
Image(nd.zeros((100, 200)))
Image(nd.zeros((100, 200, 4)), colororder="WXYZ")
```
a lists of lists of pixel values, each inner list must have the same number of elements (columns):
```
Image([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
```
a range of class methods that serve as constructors for common image types such as Zeros, Constant, Random and String, or read an image from a file Read.
an existing Image instance.

Pixel datatype

If dtype is a string or a NumPy dtype, the pixel data type is set to that type.

If dtype is True the pixel data type is inherited from the input if it is a NumPy array.

If dtype is not given and:

the input is a NumPy array,the image data type is determined by the dtype of the array:

if floating point, then the Image inherits the dtype of the array

if integer, then the Image is assigned the smallest integer dtype that can contain the values in the array. If the minimum value is negative, a signed integer type is used; otherwise an unsigned type is used.

the input is a list of lists then the image data 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 boolean pixel values which are stored as uint8 values. When used in a numerical expression, its values will be cast to integer 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).

Rather than rely on a limiting convention such as planes being in the order RGB or BGR, 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, eg:

Image(img, colororder="RGB")
Image(img, colororder="red:green:blue:alpha")
Image(img, colororder=dict("R"=2, "G"=1, "B"=0))

Image planes can be referenced by their index or by their name, eg.:

img.plane(0)
img.plane("alpha")

Seealso:: colororder colororder_str

Image domain

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

Binary images

If binary is True, the image is converted to a binary image, where zero valued pixels are set to False and all other values are set to True. To create an image where pixels have integer values of 0 and 1 use the dtype option:

Image([[0, 3], [4, 0]])  # pixel values are 0, 3, 4, 0
Image([[0, 3], [4, 0]], binary=True)  # pixel values are: False, True, True, False
Image([[0, 3], [4, 0]], binary=True, dtype="uint8")  # pixel values are 0, 1, 1, 0

Reshaping

Frequently we need to create an image from 1D data, for example:

1: Y0 Y1 Y2 ...  # (N,)
2: R0 G0 B0 R1 G1 B1 ... # (3N,)

Or a 2D array with one or more rows:

3: Y0 Y1 Y2 ... # (1, N)

4: R0 G0 B0 R1 G1 B1 ... # (1,3N)

5: R0 R1 R2 ... # (3,N)
   G0 G1 G2 ...
   B0 B1 B2 ...

Or a 2D array with one or more columns:

6: Y0 # (N,1)
   Y1
   Y2
    .
    .

7: R0 # (3N,1)
   G0
   B0
   R1
   .
   .

8: R0 G0 B0 # (N,3)
   R1 G1 B1
   R2 G2 B2
    .
    .

The size option can be used to reshape the data to the specified size. The number of planes is determined from any of: colororder, the third element of size, or the number of row/columns in the data (formats 5 or 8). For formats 2, 4 or 7 the number of planes must be given explicitly in colororder, the third element of size.

Seealso:: view1d

Example:

>>> from machinevisiontoolbox import Image
>>> import numpy as np
>>> img = Image([[1, 2], [3, 4]])
>>> print(img)
Image: 2 x 2 (uint8), 1 anonymous plane
  span=[1, 4]; mean=2.5, 𝜎=1.11803; median=2.5
>>> img.print()
   1 2
   3 4
>>> Image(np.array([[1, 2], [3, 4]]))
Image(size=(2, 2), dtype=uint8)
>>> Image([[1, 2], [3, 1000]])
Image(size=(2, 2), dtype=uint16)
>>> Image([[0.1, 0.2], [0.3, 0.4]])
Image(size=(2, 2), dtype=float32)
>>> Image([[True, False], [False, True]])
Image(size=(2, 2), dtype=bool)

Warning

If an image is constructed from an existing Image instance or a Numpy array, the encapsulated Numpy array is, by default, a reference to the passed image data. Use the option copy=True if you want to copy the data.

Image attributes and datatype#

Image attributes#

Describe the attributes of an Image.

`__repr__`	Readable representation of image parameters
`__str__`	Summary of image parameters
`center`	Coordinate of center pixel
`center_int`	Coordinate of centre pixel as integer
`centre`	Coordinate of centre pixel
`centre_int`	Coordinate of centre pixel as integer
`height`	Image height
`name`	Set/get image name
`npixels`	Number of pixels in image plane
`size`	Image size
`width`	Image width
`nplanes`	Number of color planes

Predicates#

Test attributes of an Image.

`isbgr`	Image has BGR color order?
`isbool`	Image has bolean values?
`iscolor`	Image has color pixels?
`isfloat`	Image has floating point pixel values?
`isint`	Image has integer values?
`isrgb`	Image has RGB color order?

Color planes and channels#

Return information about the color planes of an Image instance.

Image coordinates#

Describe the pixel coordinates of an Image.

`contains`	Test if coordinate lies within image
`meshgrid`
`umax`	Image maximum u-coordinate
`uspan`	Linear span of image horizontally
`vmax`	Image maximum v-coordinate
`vspan`	Linear span of image vertically

NumPy pixel data#

Return Image pixel data as a NumPy array.

`array`	Image as NumPy array
`array_as`	Convert Image to NumPy array of specified type
`bgr`	Image as NumPy array in BGR color order
`ndim`	Number of image array dimensions
`rgb`	Image as NumPy array in RGB color order
`shape`	Image shape
`to_float`	Image as float NumPy array
`to_int`	Image as integer NumPy array
`view1d`	Convert image to a column view

Getting pixels#

Access individual pixels or groups of pixels.

`__getitem__`	Return pixel value or slice from image
`pixel`	Return pixel value
`pixels_mask`	Return pixel values at locations specified by a mask

Image datatype#

Describe or change the datatype of Image pixel values.

`astype`	Cast image datatype
`cast`	Cast value to same type as image
`dtype`	Datatype of image
`false`	False value for logical image
`fixbad`	Fix bad values in image
`like`	Convert value to the same type as image
`maxval`	Maximum value of image datatype
`minval`	Minimum value of image datatype
`numinf`	Number of Inf pixels in image
`numnan`	Number of NaN pixels in image
`to`	Convert image datatype
`true`	True value for logical image

Image processing#

Sub images#

Extract sub-images or planes from an Image instance.

`blue`	Extract the blue plane of a color image
`copy`	Create image copy
`green`	Extract the green plane of a color image
`plane`	Extract plane(s) from color image
`red`	Extract the red plane of a color image
`roi`	Extract region of interest

Color space and gamma#

Convert between color spaces and perform gamma encoding and decoding.

`chromaticity`	Create chromaticity image
`colorize`	Colorize a greyscale image
`colorspace`	Transform a color image between color representations
`gamma_decode`	Gamma decoding
`gamma_encode`	Gamma encoding
`kmeans_color`	k-means color clustering
`mono`	Convert color image to monochrome

Composition#

Combine multiple Image instances into a single Image instance.

`anaglyph`	Convert stereo images to an anaglyph image
`blend`	Image blending
`Hstack`	Horizontal concatenation of images
`Overlay`	Overlay two greyscale images in different colors
`Pstack`	Concatenation of image planes
`stdisp`	Interactive display of stereo image pair
`Tile`	Tile images into a grid
`Vstack`	Vertical concatenation of images

Monadic functions#

Operate elementwise on an Image instance and returns a new Image instance.

`abs`	Absolute value of image
`apply`	Apply a function to an image
`clip`	Clip pixel values
`invert`	Invert image
`LUT`	Apply lookup table
`normhist`	Histogram normalisaton
`sqrt`	Square root of image
`stretch`	Image normalisation
`threshold`	Image threshold
`threshold_adaptive`	Adaptive threshold
`threshold_interactive`	Interactive thresholding

Dyadic functions#

Operate elementwise on two Image instances and return a new Image instance.

`apply2`	Apply a function to two images
`choose`	Pixel-wise image merge
`paste`	Paste an image into an image

Linear filtering#

Linear filtering operations including convolution, corner and edge detection.

`canny`	Canny edge detection
`convolve`	Image convolution
`gradients`	Compute horizontal and vertical gradients
`Harris_corner_strength`	Harris corner strength image
`pyramid`	Pyramidal image decomposition
`scalespace`	Compute image scalespace sequence
`smooth`	Smooth image

Non-linear (morphological) filtering#

Variety of non-linear morphological operations.

`close`	Morphological closing
`dilate`	Morphological dilation
`distance_transform`	Distance transform
`endpoint`	Find end points on a binary skeleton image
`erode`	Morphological erosion
`hitormiss`	Hit or miss transform
`medianfilter`	Median filter
`morph`	Morphological neighbourhood processing
`open`	Morphological opening
`rank`	Rank filter
`thin`	Morphological skeletonization
`thin_animate`	Morphological skeletonization with animation
`triplepoint`	Find triple points
`window`	Generalized spatial operator
`zerocross`	Compute zero crossing

Image labeling#

Binary, greyscale and color image segmentation using various algorithms.

`labels_binary`	Blob labelling
`labels_graphseg`	Blob labelling using graph-based segmentation
`labels_MSER`	Blob labelling using MSER

Image similarity#

Various scalar image similarity measures.

`ncc`	Normalised cross correlation
`sad`	Sum of absolute differences
`similarity`	Locate template in image
`ssd`	Sum of squared differences
`zncc`	Zero-mean normalized cross correlation
`zsad`	Zero-mean sum of absolute differences
`zssd`	Zero-mean sum of squared differences

Shape changing#

Changing the shape of an Image instance.

`decimate`	Decimate an image
`dice`	Dice an image into a grid of subimages
`pad`	Pad the edges of the image
`replicate`	Replicate image pixels
`samesize`	Automatic image trimming
`scale`	Scale an image
`trim`	Trim pixels from the edges of the image

Image distortion#

Distorting the image within an Image instance.

`interp2d`	Image warping
`roll`	Roll image by row or column
`rotate`	Rotate an image
`rotate_spherical`	Rotate a spherical image
`undistort`	Undistort image
`warp`	Image warping
`warp_affine`	Affine warp of image
`warp_perspective`	Perspective warp

Multiview operations#

Stereo image processing, rectification, and display.

`DSI_refine`	Refine disparity from disparity space image
`rectify_homographies`	Create rectification homographies
`stereo_BM`	Stereo block matching
`stereo_SGBM`	Stereo semi-global block matching
`stereo_simple`	Simple stereo matching

Operators#

Binary arithmetic and relational operators#

Image ☆ Image

Image ☆ scalar

scalar ☆ Image

The result is always an Image.

For the first case, the images must have:

the same shape,

the same width and height but can have different number of color planes. The image with one plane is broadcast across the color planes of the other image.

A scalar value is broadcast across the whole image.

Arithmetic and bitwise logical operations can be performed elementwise on:

`__add__`	Overloaded `+` operator
`__and__`	Overloaded `&` operator
`__floordiv__`	Overloaded `//` operator
`__invert__`	Overloaded `~` operator
`__lshift__`	Overloaded `<<` operator
`__mul__`	Overloaded `*` operator
`__neg__`	Overloaded unary `-` operator
`__or__`	Overloaded `\|` operator
`__pow__`	Overloaded `**` operator
`__radd__`
`__rfloordiv__`
`__rmul__`
`__rshift__`	Overloaded `>>` operator
`__rsub__`
`__rtruediv__`
`__sub__`	Overloaded `-` operator
`__truediv__`	Overloaded `/` operator
`__xor__`	Overloaded `^` operator

Logical operations can be performed elementwise on: Image ☆ Image. The result is always an Image with boolean pixel values:

`__eq__`	Overloaded `==` operator
`__ge__`	Overloaded `>=` operator
`__gt__`	Overloaded `>` operator
`__le__`	Overloaded `<=` operator
`__lt__`	Overloaded `<` operator
`__ne__`	Overloaded `!=` operator

Inplace arithmetic operators#

Arithmetic and bitwise logical operations can be performed elementwise on:

Image ☆= Image

Image ☆= scalar

The result is always an Image. A scalar value is broadcast across the whole image.

`__iadd__`	Overloaded in-place `+=` operator
`__iand__`	Overloaded in-place `&=` operator
`__ifloordiv__`	Overloaded in-place `//=` operator
`__ilshift__`	Overloaded in-place `<<=` operator
`__imul__`	Overloaded in-place `*=` operator
`__ior__`	Overloaded in-place `\|=` operator
`__irshift__`	Overloaded in-place `>>=` operator
`__isub__`	Overloaded in-place `-=` operator
`__itruediv__`	Overloaded in-place `/=` operator
`__ixor__`	Overloaded in-place `^=` operator

Plane stacking operators#

Stacking operations can be performed on multiple Image instances. A scalar value is broadcast across the whole image to create a new Image instance. In place stacking allows for planes to be appended.

`__imod__`	Overloaded in-place `%=` operator
`__mod__`	Overloaded `%` operator

Image statistics#

max

Maximum value of all pixels

mean

Mean value of all pixels

median

Median value of all pixels

min

Minimum value of all pixels

stats

Pixel value statistics

std

Standard deviation of all pixels

var

Variance of all pixels

hist

Image histogram

Image feature extraction#

Whole image features#

Histograms#

hist

Image histogram

Image moments#

`humoments`	Hu image moment invariants
`moments`	Image moments
`mpq`	Image moments
`npq`	Normalized central image moments
`upq`	Central image moments

Other#

`flatnonzero`	Find non-zero pixel values as 1D indices
`nonzero`	Find non-zero pixel values as 2D coordinates
`otsu`	Otsu threshold selection
`peak2d`	Find local maxima in image
`sum`	Sum of all pixels

Region features#

Find homogeneous regions, text or fiducual tags.

`blobs`	Find and describe blobs in image
`MSER`	Find MSER features in image
`ocr`	Optical character recognition

Fiducial features#

fiducial

Find fiducial markers in image

Line features#

Find lines in an image.

Hough

Find Hough line features

Point/corner features#

Find distincitive points in an image.

`AKAZE`	Find AKAZE features in image
`BRISK`	Find BRISK features in image
`ComboFeature`	Combination feature detector and descriptor
`Harris`	Find Harris features in image
`ORB`	Find ORB features in image
`SIFT`	Find SIFT features in image

Image i/o#

File#

`metadata`	Get image EXIF metadata
`Read`	Read image from file
`write`	Write image to file

Graphical#

`disp`	Display image
`showpixels`	Display image with pixel values

Text#

`print`	Print image pixels in compact format
`strhcat`	Format several small images concatenated horizontally

Constant images#

Create images that are constant, random, or have a simple geometric pattern.

`Chequerboard`	Create chequerboard pattern
`Circles`	Create image containing grid of circles
`Constant`	Create image with all pixels having same value
`Polygons`	Create an image containing filled polygons
`Ramp`	Create image of linear ramps
`Random`	Create image with random pixel values
`Sin`	Create image of sinusoidal intensity pattern
`Squares`	Create image containing grid of squares
`String`	Create a small image from text string
`Zeros`	Create image with zero value pixels

Graphical annotation#

Render simple graphical annotations into an image. The equivalent functions plot_xxx from SpatialMath Toolbox create graphical overlays rather than changing the the image data.

`draw_box`	Draw box into image
`draw_circle`	Draw circle into image
`draw_labelbox`	Draw label box into image
`draw_line`	Draw line into image
`draw_point`	Draw a marker in image
`draw_text`	Draw text into image :param pos: text position (u,v) :type pos: array_like(2) :param text: text to draw :type text: str :param kwargs: parameters passed to `draw_text`

Test images#

Sometimes, for pedagogy and unit tests, it is helpful to create, process and numerically display small example images.

`max`	Maximum value of all pixels
`mean`	Mean value of all pixels
`median`	Median value of all pixels
`min`	Minimum value of all pixels
`stats`	Pixel value statistics
`std`	Standard deviation of all pixels
`var`	Variance of all pixels
`hist`	Image histogram

The Image object#