Whole image features

These methods extract features such as histograms and moments from images.

class machinevisiontoolbox.ImageWholeFeatures.ImageWholeFeaturesMixin[source]

hist(nbins=256, opt=None)[source]

Image histogram

Parameters

nbins (int, optional) – number of histogram bins, defaults to 256
opt (str) – histogram option

Returns

histogram of image

Return type

Histogram

Returns an object that summarizes the distribution of pixel values in each color plane.

Example:

Note

The bins spans the greylevel range 0-255.
For a floating point image the histogram spans the greylevel range 0.0 to 1.0 with 256 bins.
For floating point images all NaN and Inf values are first removed.
Computed using OpenCV CalcHist. Only works on floats up to 32 bit, images are automatically converted from float64 to float32

References

Robotics, Vision & Control for Python, Section 14.4.3, P. Corke, Springer 2023.

Seealso

opencv.calcHist

mpq(p, q)[source]

Image moments

Parameters

p (int) – u exponent
q (int) – v exponent

Returns

moment

Type

scalar

Computes the pq’th moment of the image:

\[m(I) = \sum_{uv} I_{uv} u^p v^q\]

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('shark1.png')
>>> img.mpq(1, 0)
341888955

Note

Supports single channel images only.
mpq(0, 0) is the same as sum() but less efficient.

References

Robotics, Vision & Control for Python, Section 12.1.3.4, P. Corke, Springer 2023.

Seealso

sum npq upq

upq(p, q)[source]

Central image moments

Parameters

p (int) – u exponent
q (int) – v exponent

Returns

moment

Type

scalar

Computes the pq’th central moment of the image:

\[\mu(I) = \sum_{uv} I_{uv} (u-u_0)^p (v-v_0)^q\]

where \(u_0 = m_{10}(I) / m_{00}(I)\) and \(v_0 = m_{01}(I) / m_{00}(I)\).

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('shark1.png')
>>> img.upq(2, 2)
922044470450.7101

Note

The central moments are invariant to translation.
Supports single channel images only.

References

Robotics, Vision & Control for Python, Section 12.1.3.4, P. Corke, Springer 2023.

Seealso

sum mpq upq

npq(p, q)[source]

Normalized central image moments

Parameters

p (int) – u exponent
q (int) – v exponent

Returns

moment

Type

scalar

Computes the pq’th normalized central moment of the image:

\[\nu(I) = \frac{\mu_{pq}(I)}{m_{00}(I)} = \frac{1}{m_{00}(I)} \sum_{uv} I_{uv} (u-u_0)^p (v-v_0)^q \]

where \(u_0 = m_{10}(I) / m_{00}(I)\) and \(v_0 = m_{01}(I) / m_{00}(I)\).

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('shark1.png')
>>> img.npq(2, 2)
1.1596991128539824e-07

Note

The normalized central moments are invariant to translation and scale.
Supports single channel images only.

References

Robotics, Vision & Control for Python, Section 12.1.3.4, P. Corke, Springer 2023.

Seealso

sum mpq upq

moments(binary=False)[source]

Image moments

Parameters: binary (bool) – if True, all non-zero pixels are treated as 1’s
Returns: image moments
Type: dict

Compute multiple moments of the image and return them as a dict

Moment type	dict keys
moments	`m00` `m10` `m01` `m20` `m11` `m02` `m30` `m21` `m12` `m03`
central moments	`mu20` `mu11` `mu02` `mu30` `mu21` `mu12` `mu03` \|
normalized central moments	`nu20` `nu11` `nu02` `nu30` `nu21` `nu12` `nu03` \|

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('shark1.png')
>>> img.moments()
{'m00': 1995885.0, 'm10': 341888955.0, 'm01': 309659505.0, 'm20': 60967635585.0, 'm11': 52708208790.0, 'm02': 48962122365.0, 'm30': 11284951722945.0, 'm21': 9337817849640.0, 'm12': 8282294696220.0, 'm03': 7879402188375.0, 'mu20': 2403110298.7274823, 'mu11': -335510948.49559176, 'mu02': 918768646.3012627, 'mu30': 18092682198.754948, 'mu21': -6304121879.9286995, 'mu12': -657749179.1717323, 'mu03': -2112760503.1506472, 'nu20': 0.0006032574252131944, 'nu11': -8.422396218245323e-05, 'nu02': 0.00023064026991512026, 'nu30': 3.214875575229422e-06, 'nu21': -1.1201748437524005e-06, 'nu12': -1.1687497450720262e-07, 'nu03': -3.7541488118084844e-07}

Note

Converts a color image to greyscale.

References

Robotics, Vision & Control for Python, Section 12.1.3.4, P. Corke, Springer 2023.

Seealso

mpq npq upq opencv.moments

humoments()[source]

Hu image moment invariants

Returns: Hu image moments
Return type: ndarray(7)

Computes the seven Hu image moment invariants of the image.

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image.Read('shark1.png', dtype='float')
>>> img.humoments()
array([0.2126, 0.0109, 0.0004, 0.0002, 0.    , 0.    , 0.    ])

Note

Image is assumed to be a binary image of a single connected region
These invariants are a function of object shape and are invariant to position, orientation and scale.

References

M-K. Hu, Visual pattern recognition by moment invariants. IRE Trans. on Information Theory, IT-8:pp. 179-187, 1962.
Robotics, Vision & Control for Python, Section 12.1.3.6, P. Corke, Springer 2023.

Seealso

:func:`opencv.HuMoments <https://docs.opencv.org/master/d3/dc0/group__imgproc__shape.html#gab001db45c1f1af6cbdbe64df04c4e944>`_

nonzero()[source]

Find non-zero pixel values

Returns: coordinates of non-zero pixels
Return type: ndarray(2,N)

The (u,v) coordinates are given as columns of the returned array.

Example:

>>> from machinevisiontoolbox import Image
>>> import numpy as np
>>> pix = np.zeros((10,10)); pix[2,3]=10; pix[4,5]=11; pix[6,7]=12
>>> img = Image(pix)
>>> img.nonzero()
array([[3, 5, 7],
       [2, 4, 6]])

References

Robotics, Vision & Control for Python, Section 12.1.3.2, P. Corke, Springer 2023.

Seealso

flatnonzero

flatnonzero()[source]

Find non-zero pixel values

Returns: index of non-zero pixels
Return type: ndarray(N)

The coordinates are given as 1D indices into a flattened version of the image.

Example:

>>> from machinevisiontoolbox import Image
>>> import numpy as np
>>> pix = np.zeros((10,10)); pix[2,3]=10; pix[4,5]=11; pix[6,7]=12
>>> img = Image(pix)
>>> img.flatnonzero()
array([23, 45, 67])
>>> img.view1d()[23]
10.0

Seealso: view1d nonzero

peak2d(npeaks=2, scale=1, interp=False, positive=True)[source]

Find local maxima in image

Parameters

npeaks (int, optional) – number of peaks to return, defaults to 2
scale (int) – scale of peaks to consider
interp (bool, optional) – interpolate the peak positions, defaults to False
positive (bool, optional) – only select peaks that are positive, defaults to False

Returns

peak magnitude and positions

Return type

ndarray(npeaks), ndarray(2,npeaks)

Find the positions of the local maxima in the image. A local maxima is the largest value within a sliding window of width \(2 \mathtt{scale}+1\).

Example:

>>> from machinevisiontoolbox import Image
>>> import numpy as np
>>> peak = np.array([[10, 20, 30], [40, 50, 45], [15, 20, 30]])
>>> img = Image(np.pad(peak, 3, constant_values=10))
>>> img.A
array([[10, 10, 10, 10, 10, 10, 10, 10, 10],
       [10, 10, 10, 10, 10, 10, 10, 10, 10],
       [10, 10, 10, 10, 10, 10, 10, 10, 10],
       [10, 10, 10, 10, 20, 30, 10, 10, 10],
       [10, 10, 10, 40, 50, 45, 10, 10, 10],
       [10, 10, 10, 15, 20, 30, 10, 10, 10],
       [10, 10, 10, 10, 10, 10, 10, 10, 10],
       [10, 10, 10, 10, 10, 10, 10, 10, 10],
       [10, 10, 10, 10, 10, 10, 10, 10, 10]])
>>> img.peak2d(interp=True)
(array([7.5]), array([[4.1667],
       [4.    ]]))

Note

Edges elements will never be returned as maxima.
To find minima, use peak2d(-image).
The interp option fits points in the neighbourhood about the peak with a paraboloid and its peak position is returned.

Seealso: findpeaks2d

Whole image feature classes

class machinevisiontoolbox.ImageWholeFeatures.Histogram(h, x, isfloat=False)[source]

Create histogram instance

Parameters

h (ndarray(N), ndarray(N,P)) – image histogram
x (ndarray(N)) – image values
isfloat (bool, optional) – pixel values are floats, defaults to False

Create Histogram instance from histogram data provided as Numpy arrays.

Seealso: hist

property x

Histogram bin values

Returns: array of left-hand bin values
Return type: ndarray(N)

Bin \(i\) contains grey values in the range \([x_{[i]}, x_{[i+1]})\).

Example:

>>> from machinevisiontoolbox import Image
>>> import numpy as np
>>> hist = Image.Read('flowers1.png').hist()
>>> with np.printoptions(threshold=10):
...     hist.x
... 
array([  0.,   1.,   2., ..., 253., 254., 255.])

property h

Histogram count values

Returns: array of histogram count values
Return type: ndarray(N) or ndarray(N,P)

For a greyscale image this is a 1D array, for a multiplane (color) image this is a 2D array with the histograms of each plane as columns.

Example:

>>> from machinevisiontoolbox import Image
>>> import numpy as np
>>> hist = Image.Read('flowers1.png').hist()
>>> with np.printoptions(threshold=10):
...     hist.h
... 
array([[ 388.,    2.,  546.],
       [ 443.,    2.,  596.],
       [ 555.,    2.,  610.],
       ...,
       [1003.,  186.,  407.],
       [1284.,  324.,  487.],
       [   0.,    0.,    0.]], dtype=float32)

property cdf

Cumulative histogram values

Returns: array of cumulative histogram count values
Return type: ndarray(N) or ndarray(N,P)

For a greyscale image this is a 1D array, for a multiplane (color) image this is a 2D array with the cumulative histograms of each plane as columns.

Example:

>>> from machinevisiontoolbox import Image
>>> import numpy as np
>>> hist = Image.Read('flowers1.png').hist()
>>> with np.printoptions(threshold=10):
...     hist.cdf
... 
array([[   388.,      2.,    546.],
       [   831.,      4.,   1142.],
       [  1386.,      6.,   1752.],
       ...,
       [266651., 269436., 269391.],
       [267935., 269760., 269878.],
       [267935., 269760., 269878.]], dtype=float32)

property ncdf

Normalized cumulative histogram values

Returns: array of normalized cumulative histogram count values
Return type: ndarray(N) or ndarray(N,P)

For a greyscale image this is a 1D array, for a multiplane (color) image this is a 2D array with the normalized cumulative histograms of each plane as columns.

Example:

>>> from machinevisiontoolbox import Image
>>> import numpy as np
>>> hist = Image.Read('flowers1.png').hist()
>>> with np.printoptions(threshold=10):
...     hist.ncdf
... 
array([[0.0014, 0.    , 0.002 ],
       [0.0031, 0.    , 0.0042],
       [0.0052, 0.    , 0.0065],
       ...,
       [0.9952, 0.9988, 0.9982],
       [1.    , 1.    , 1.    ],
       [1.    , 1.    , 1.    ]], dtype=float32)

plot(type='frequency', block=False, bar=None, style='stack', alpha=0.5, **kwargs)[source]

Plot histogram

Parameters

type (str, optional) – histogram type, one of: ‘frequency’ [default], ‘cdf’, ‘ncdf’
block (bool, optional) – hold plot, defaults to False
bar (bool, optional) – histogram bar plot, defaults to True for frequency plot, False for other plots
style (str, optional) – Style for multiple plots, one of: ‘stack’ [default], ‘overlay’
alpha (float, optional) – transparency for overlay plot, defaults to 0.5

Raises

ValueError – invalid histogram type
ValueError – cannot use overlay style for 1-channel histogram

peaks(**kwargs)[source]

Histogram peaks

Parameters: kwargs – parameters passed to findpeaks
Returns: positions of histogram peaks
Return type: ndarray(M), list of ndarray

For a greyscale image return an array of grey values corresponding to local maxima. For a color image return a list of arrays of grey values corresponding to local maxima in each plane.

Example:

>>> from machinevisiontoolbox import Image
>>> import numpy as np
>>> hist = Image.Read('street.png').hist()
>>> hist.peaks(scale=20)
array([ 40., 197., 153.])

Seealso: findpeaks