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.

class Image(image: Image | ndarray | None = None, colororder: str | dict | None = None, copy: bool = False, size: tuple | list | None = None, dtype: DTypeLike | None = None, name: str | None = None, id: int | None = None, domain=None, binary: bool = False, **kwargs)

Image attributes and datatype

Image attributes

Describe the attributes of an Image.

__repr__	Readable representation of image parameters
__str__	Single line 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

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?

Image coordinates

Describe the pixel coordinates of an Image.

contains	Test if coordinate lies within image
meshgrid	Coordinate arrays for image
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 and setting 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 info

Return information about the color planes of an Image instance.

colordict	Parse a color order specification
colordict2list	Convert a color dictionary to a list of color plane names
colordict2str	Convert a color dictionary to a color order string
colororder	Set/get color order of image
colororder2dict	Parse a color order specification to a color dictionary
colororder_str	Image color order as a string
nplanes	Number of color planes

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	Display 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.