Detailed Description

Blobs

Blobs are just maps (or dictionaries in Python) to represent disjoint regions in image.

blobs are probably the best way to handle measures on regions of images, as calling a function to evaluate a measure on a blobs map is equivalent to call the equivalent function for each blob. E.g. calling blobsArea() is equivalent to call area() for each blob in the map.

To handle blobs, you need to have a labeled image, generated by some method of segmentation (e.g. watershed()), and create them thanks to computeBlobs().

Example

import smilPython as sp
 
im = sp.Image("balls.png")
iml = sp.Image(im)
 
# this is just a binary image - no need to segment
sp.label(im, iml)
iml.showLabel()
 
# create blobs structure
blobs = sp.computeBlobs(iml)
 
# evaluate some measures :
areas = sp.blobsArea(blobs)
barys = sp.blobsBarycenter(im, blobs)
 
# print areas and barycenters of each region
print("{:3s} - {:>6s} - {:>13s}".format("ID", "Area", "Barycenter"))
for k in blobs.keys():
  bary = barys[k]
  print("{:3d} - {:6.0f} - {:6.0f} {:6.0f}".format(k, areas[k], bary[0], bary[1]))
 

Collaboration diagram for Mesures on blobs:

Classes
struct	PixelSequence
	Start offset and length of pixels in an image. More...

struct	Blob
	List of offset and size of line contiguous pixels. More...

Functions
template<class T >
map< T, Blob >	computeBlobs (const Image< T > &imIn, bool onlyNonZero=true)
	Create a map of blobs from a labeled image.

template<class labelT , class T >
RES_T	drawBlobs (map< labelT, Blob > &blobs, Image< T > &imOut, T blobsValue=ImDtTypes< T >::max(), bool fillFirst=true, T defaultValue=T(0))
	Represent Blobs in an image.

template<class labelT , class T >
RES_T	drawBlobs (map< labelT, Blob > &blobs, map< labelT, T > &lut, Image< T > &imOut, bool fillFirst=true, T defaultValue=T(0))
	Represent Blobs in an image with a lookup map.

template<class labelT >
int	getBlobIDFromOffset (map< labelT, Blob > &blobs, size_t offset)
	getBlobIDFromOffset() - get the blob ID which contains a pixel (or voxel) given its offset

template<class labelT , class T >
int	getBlobIDFromOffset (Image< T > imIn, map< labelT, Blob > &blobs, int x, int y, int z=0)
	getBlobIDFromOffset() - get the blob ID which contains a pixel (or voxel) given its coordinates

template<class T >
map< T, double >	blobsArea (const Image< T > &imLbl, const bool onlyNonZero=true)
	blobsArea() - Calculate the area of each region in a labeled image

template<class labelT >
map< labelT, double >	blobsArea (map< labelT, Blob > &blobs)
	blobsArea() - Measure areas from a pre-generated Blob map (faster).

template<class T , class labelT >
map< labelT, double >	blobsVolume (const Image< T > &imIn, map< labelT, Blob > &blobs)
	blobsVolume() - Measure the sum of values of each blob in imIn.

template<class T , class labelT >
map< labelT, T >	blobsMinVal (const Image< T > &imIn, map< labelT, Blob > &blobs)
	blobsMinVal() - Measure the minimum value of each blob in imIn.

template<class T , class labelT >
map< labelT, T >	blobsMaxVal (const Image< T > &imIn, map< labelT, Blob > &blobs)
	blobsMaxVal() - Measure the maximum value of each blob in imIn.

template<class T , class labelT >
map< labelT, vector< T > >	blobsRangeVal (const Image< T > &imIn, map< labelT, Blob > &blobs)
	blobsRangeVal() - Measure the min and max values of each blob in imIn.

template<class T , class labelT >
map< labelT, Vector_double >	blobsMeanVal (const Image< T > &imIn, map< labelT, Blob > &blobs)
	blobsMeanVal() - Measure the mean value and the std dev.

template<class T , class labelT >
map< labelT, vector< T > >	blobsValueList (const Image< T > &imIn, map< labelT, Blob > &blobs)
	blobsValueList() - Measure the list of values of each blob in imIn.

template<class T , class labelT >
map< labelT, T >	blobsModeVal (const Image< T > &imIn, map< labelT, Blob > &blobs)
	blobsModeVal() - Measure the mode value of imIn in each blob.

template<class T , class labelT >
map< labelT, T >	blobsMedianVal (const Image< T > &imIn, map< labelT, Blob > &blobs)
	blobsMedianVal() - Measure the median value of imIn in each blob.

template<class T >
map< T, Vector_double >	blobsBarycenter (const Image< T > &imLbl, const bool onlyNonZero=true)
	blobsBarycenter() - Measure barycenter of a labeled image.

template<class T , class labelT >
map< labelT, Vector_double >	blobsBarycenter (const Image< T > &imIn, map< labelT, Blob > &blobs)
	blobsBarycenter() - Measure the barycenter of each blob in imIn.

template<class T >
map< T, vector< size_t > >	blobsBoundBox (const Image< T > &imLbl, const bool onlyNonZero=true)
	blobsBoundBox() - Measure bounding boxes of labeled image.

template<class T , class labelT >
map< labelT, vector< size_t > >	blobsBoundBox (const Image< T > &imIn, map< labelT, Blob > &blobs)
	blobsBoundBox() - Measure bounding boxes of each blob (faster with blobs pre-generated).

template<class T , class labelT >
map< labelT, Vector_double >	blobsMoments (const Image< T > &imIn, map< labelT, Blob > &blobs, bool central=false)
	blobsMoments() - Measure blobs image moments (faster with blobs pre-generated).

template<class T >
map< T, Vector_double >	blobsMoments (const Image< T > &imLbl, const bool onlyNonZero=true, bool central=false)
	blobsMoments() - Measure image moments of each label.

template<class T , class labelT >
map< labelT, double >	blobsEntropy (const Image< T > &imIn, map< labelT, Blob > &blobs)
	blobsEntropy() - Measure blobs entropy.

Function Documentation

◆ computeBlobs()

template<class T >

map< T, Blob > computeBlobs	(	const Image< T > &	imIn,
		bool	onlyNonZero = `true`
	)

Create a map of blobs from a labeled image.

Parameters

[in]	imIn	: input labeled image
[in]	onlyNonZero	: ignore regions whose label is 0

Returns: a map of pairs <label, blob>

◆ drawBlobs() [1/2]

template<class labelT , class T >

RES_T drawBlobs	(	map< labelT, Blob > &	blobs,
		Image< T > &	imOut,
		T	blobsValue = `ImDtTypes<T>::max()`,
		bool	fillFirst = `true`,
		T	defaultValue = `T(0)`
	)

Represent Blobs in an image.

Parameters

[in]	blobs	: input blobs map
[in]	imOut	: output image
[in]	blobsValue	: value to assign to each blob
[in]	fillFirst	: fill the background before beginning
[in]	defaultValue	: default value for the background (default : 0)

Note: If blobsValue == 0, each blobs is represented with its label value.

◆ drawBlobs() [2/2]

template<class labelT , class T >

RES_T drawBlobs	(	map< labelT, Blob > &	blobs,
		map< labelT, T > &	lut,
		Image< T > &	imOut,
		bool	fillFirst = `true`,
		T	defaultValue = `T(0)`
	)

Represent Blobs in an image with a lookup map.

Parameters

[in]	blobs	: input blobs map
[in]	lut	: lookup table with value to assign to each blob
[in]	imOut	: output image
[in]	fillFirst	: fill the background before beginning
[in]	defaultValue	: default value for the background (default : 0)

◆ getBlobIDFromOffset() [1/2]

template<class labelT >

int getBlobIDFromOffset	(	map< labelT, Blob > &	blobs,
		size_t	offset
	)

getBlobIDFromOffset() - get the blob ID which contains a pixel (or voxel) given its offset

Parameters

[in]	blobs	: the blobs map
[in]	offset	: the offset to look for

Returns: the ID of the blob containing the offset, or 0 if the offset is in the background.

◆ getBlobIDFromOffset() [2/2]

template<class labelT , class T >

int getBlobIDFromOffset	(	Image< T >	imIn,
		map< labelT, Blob > &	blobs,
		int	x,
		int	y,
		int	z = `0`
	)

getBlobIDFromOffset() - get the blob ID which contains a pixel (or voxel) given its coordinates

Parameters

[in]	blobs	: the blobs map
[in]	imIn	: input image where blobs are defined
[in]	x,y[,z]	: point coordinates

Returns: the ID of the blob containing pixel (voxel), or 0 if in the background.

◆ blobsArea() [1/2]

template<class T >

map< T, double > blobsArea	(	const Image< T > &	imLbl,
		const bool	onlyNonZero = `true`
	)

blobsArea() - Calculate the area of each region in a labeled image

Parameters

[in]	imLbl	: input labeled image
[in]	onlyNonZero	: skip a blob having a null label

Returns: a map of pairs <label, double> with the area of each blob.

Example

from smilPython import *
 
# Load an image
imIn = Image("https://smil.cmm.minesparis.psl.eu/images/DNA_small.png")
imIn.show()
 
imThr = Image(imIn)
threshold(imIn, imThr)
 
imLbl = Image(imIn, "UINT16")
label(imThr, imLbl)
imLbl.showLabel()
 
# Bounding boxes
bboxes = blobsBoundBox(imLbl)
imRec = Image(imIn)
drawRectangles(imRec, bboxes)
imIn.getViewer().drawOverlay(imRec)
 
# Blobs measures
blobs = computeBlobs(imLbl)
# areas
areas = blobsArea(imLbl, blobs) # equivalent but faster than measAreas(imLbl)
# barycenters
barys = blobsBarycenter(imLbl, blobs)
# volume of blobs in imIn
vols  = blobsVolume(imIn, blobs)
print("Label\tarea\tvolume\tbarycenter (x,y)")
for lbl in blobs.keys():
  print(str(lbl) + "\t" + str(areas[lbl]) + "\t" + str(vols[lbl]) + "\t" + str(barys[lbl]))
 

◆ blobsArea() [2/2]

template<class labelT >

map< labelT, double > blobsArea ( map< labelT, Blob > & blobs )

blobsArea() - Measure areas from a pre-generated Blob map (faster).

Parameters

[in] blobs : input Blob map

Returns: a map of pairs <label, double> with the area of each blob.

◆ blobsVolume()

template<class T , class labelT >

map< labelT, double > blobsVolume	(	const Image< T > &	imIn,
		map< labelT, Blob > &	blobs
	)

blobsVolume() - Measure the sum of values of each blob in imIn.

Parameters

[in]	imIn	: input labeled image
[in]	blobs	: input Blob map

Returns: a map of pairs <label, double> with the volume (sum of pixel values) in each blob.

◆ blobsMinVal()

template<class T , class labelT >

map< labelT, T > blobsMinVal	(	const Image< T > &	imIn,
		map< labelT, Blob > &	blobs
	)

blobsMinVal() - Measure the minimum value of each blob in imIn.

Parameters

[in]	imIn	: input labeled image
[in]	blobs	: input Blob map

Returns: a map of pairs <label, T> with the min image value in each blob.

◆ blobsMaxVal()

template<class T , class labelT >

map< labelT, T > blobsMaxVal	(	const Image< T > &	imIn,
		map< labelT, Blob > &	blobs
	)

blobsMaxVal() - Measure the maximum value of each blob in imIn.

Parameters

[in]	imIn	: input labeled image
[in]	blobs	: input Blob map

Returns: a map of pairs <label, T> with the max image value in each blob.

◆ blobsRangeVal()

template<class T , class labelT >

map< labelT, vector< T > > blobsRangeVal	(	const Image< T > &	imIn,
		map< labelT, Blob > &	blobs
	)

blobsRangeVal() - Measure the min and max values of each blob in imIn.

Parameters

[in]	imIn	: input labeled image
[in]	blobs	: input Blob map

Returns: a map of pairs <label, <T, T>> with a vector with the min and max pixel values in each blob.

◆ blobsMeanVal()

template<class T , class labelT >

map< labelT, Vector_double > blobsMeanVal	(	const Image< T > &	imIn,
		map< labelT, Blob > &	blobs
	)

blobsMeanVal() - Measure the mean value and the std dev.

of each blob in imIn.

Parameters

[in]	imIn	: input labeled image
[in]	blobs	: input Blob map

Returns: a map of pairs <label, <double, double>> with a vector with the mean and standard deviation pixel values in each blob.

◆ blobsValueList()

template<class T , class labelT >

map< labelT, vector< T > > blobsValueList	(	const Image< T > &	imIn,
		map< labelT, Blob > &	blobs
	)

blobsValueList() - Measure the list of values of each blob in imIn.

Parameters

[in]	imIn	: input labeled image
[in]	blobs	: input Blob map

Returns: a map of pairs <label, vector<T>> with the list of pixel values in each blob.

◆ blobsModeVal()

template<class T , class labelT >

map< labelT, T > blobsModeVal	(	const Image< T > &	imIn,
		map< labelT, Blob > &	blobs
	)

blobsModeVal() - Measure the mode value of imIn in each blob.

Parameters

[in]	imIn	: input labeled image
[in]	blobs	: input Blob map

Returns: a map of pairs <label, T> with the mode value in each blob.

◆ blobsMedianVal()

template<class T , class labelT >

map< labelT, T > blobsMedianVal	(	const Image< T > &	imIn,
		map< labelT, Blob > &	blobs
	)

blobsMedianVal() - Measure the median value of imIn in each blob.

Parameters

[in]	imIn	: input labeled image
[in]	blobs	: input Blob map

Returns: a map of pairs <label, T> with the median value in each blob.

◆ blobsBarycenter() [1/2]

template<class T >

map< T, Vector_double > blobsBarycenter	(	const Image< T > &	imLbl,
		const bool	onlyNonZero = `true`
	)

blobsBarycenter() - Measure barycenter of a labeled image.

Parameters

[in]	imLbl	: input labeled image
[in]	onlyNonZero	: skip a blob having a null label

Returns: a map of pairs <label, Vector<double>> with the coordinates of the barycenter of each blob.

Example

from smilPython import *
 
# Load an image
imIn = Image("https://smil.cmm.minesparis.psl.eu/images/DNA_small.png")
imIn.show()
 
imThr = Image(imIn)
threshold(imIn, imThr)
 
imLbl = Image(imIn, "UINT16")
label(imThr, imLbl)
imLbl.showLabel()
 
# Bounding boxes
bboxes = blobsBoundBox(imLbl)
imRec = Image(imIn)
drawRectangles(imRec, bboxes)
imIn.getViewer().drawOverlay(imRec)
 
# Blobs measures
blobs = computeBlobs(imLbl)
# areas
areas = blobsArea(imLbl, blobs) # equivalent but faster than measAreas(imLbl)
# barycenters
barys = blobsBarycenter(imLbl, blobs)
# volume of blobs in imIn
vols  = blobsVolume(imIn, blobs)
print("Label\tarea\tvolume\tbarycenter (x,y)")
for lbl in blobs.keys():
  print(str(lbl) + "\t" + str(areas[lbl]) + "\t" + str(vols[lbl]) + "\t" + str(barys[lbl]))
 

◆ blobsBarycenter() [2/2]

template<class T , class labelT >

map< labelT, Vector_double > blobsBarycenter	(	const Image< T > &	imIn,
		map< labelT, Blob > &	blobs
	)

blobsBarycenter() - Measure the barycenter of each blob in imIn.

Parameters

[in]	imIn	: input labeled image
[in]	blobs	: input Blob map

Returns: a map of pairs <label, Vector<double>> with the coordinates of the barycenter of each blob.

◆ blobsBoundBox() [1/2]

template<class T >

map< T, vector< size_t > > blobsBoundBox	(	const Image< T > &	imLbl,
		const bool	onlyNonZero = `true`
	)

blobsBoundBox() - Measure bounding boxes of labeled image.

Parameters

[in]	imLbl	: input labeled image
[in]	onlyNonZero	: skip a blob having a null label

Returns: a map of pairs <label, Vector<size_t>> with the coordinates of the bounding box of each label.

◆ blobsBoundBox() [2/2]

template<class T , class labelT >

map< labelT, vector< size_t > > blobsBoundBox	(	const Image< T > &	imIn,
		map< labelT, Blob > &	blobs
	)

blobsBoundBox() - Measure bounding boxes of each blob (faster with blobs pre-generated).

Parameters

[in]	imIn	: input labeled image
[in]	blobs	: input Blob map

Returns: a map of pairs <label, Vector<size_t>> with the coordinates of the bounding box of each label.

◆ blobsMoments() [1/2]

template<class T , class labelT >

map< labelT, Vector_double > blobsMoments	(	const Image< T > &	imIn,
		map< labelT, Blob > &	blobs,
		bool	central = `false`
	)

blobsMoments() - Measure blobs image moments (faster with blobs pre-generated).

Parameters

[in]	imIn	: input labeled image
[in]	blobs	: input Blob map
[in]	central	: moments are evaluated with respect to the blob barycenter

Returns: a map of pairs <label, Vector<double>> with the first and second order image moments of each label.

See also: measMoments()

Example : Calculating moments

import smilPython as sp
 
# How to print moments
def printBlobMoments(m, title=""):
    print(title.center(90))
    hdr = ["m00", "m10", "m01", "m11", "m20", "m02"]
    s = " " * 5
    for h in hdr:
        s += h.rjust(16)
    print(s)
    for label in m.keys():
        s = '{:3} :'.format(label)
        for v in m[label]:
            s += '  {:14.2f}'.format(v)
        print(s)
 
# Serious work begins here
#
binaryImage = False
if binaryImage:
    imageName = "https://smil.cmm.minesparis.psl.eu/images/balls.png"
    imo = sp.Image(imageName)
    iml = sp.Image(imo, 'UINT16')
    # normalize binary image values
    imo /= 255
    sp.label(imo, iml)
else:
    imageName = "https://smil.cmm.minesparis.psl.eu/images/tools.png"
    imo = sp.Image(imageName)
    imThr = sp.Image(imo)
    sp.topHat(imo, imThr, sp.hSE(20))
    sp.threshold(imThr, imThr)
    iml = sp.Image(imo, "UINT16")
    sp.label(imThr, iml)
 
# create blobs
blobs = sp.computeBlobs(iml)
 
print("=== > Image : ", imageName, "\n")
 
# Calculate not centered moments
moments = sp.blobsMoments(imo, blobs, False)
printBlobMoments(moments, "Not centered moments")
 
print("=" * 102)
# Calculate centered moments
moments = sp.blobsMoments(imo, blobs, True)
printBlobMoments(moments, "Centered moments")

Example : Getting blob orientation in space

from smilPython import *
from math import *
 
# Load an image
imIn = Image("https://smil.cmm.minesparis.psl.eu/images/tools.png")
imIn.show()
 
imThr = Image(imIn)
topHat(imIn, imThr, hSE(20))
threshold(imThr, imThr)
 
imLbl = Image(imIn, "UINT16")
label(imThr, imLbl)
imLbl.showLabel()
 
def fitRectangle(mat):
    m00, m10, m01, m11, m20, m02 = mat
 
    if m00 == 0:
      return 0, 0, 0, 0, 0
 
    # COM
    xc = int (m10 / m00)
    yc = int (m01 / m00)
 
    # centered matrix (central moments)
    u00 = m00
    u20 = m20 - m10**2 / m00
    u02 = m02 - m01**2 / m00
    u11 = m11 - m10 * m01 / m00
 
    # eigen values
    delta = 4 * u11**2 + (u20 - u02)**2
    I1 = (u20 + u02 + sqrt(delta)) / 2
    I2 = (u20 + u02 - sqrt(delta)) / 2
 
    theta = 0.5 * atan2(-2 * u11, (u20 - u02))
 
    # Equivalent rectangle
    # I1 = a**2 * S / 12, I2 = b**2 * S / 12
    a = int (sqrt(12 * I1 / u00))
    b = int (sqrt(12 * I2 / u00))
 
    return xc, yc, a, b, theta
 
# Compute Blobs
blobs = computeBlobs(imLbl)
 
# Compute Inertia Matrices
 
mats  = blobsMoments(imIn, blobs)
bboxes = blobsBoundBox(imLbl)
imDraw = Image(imIn)
 
print("{:5s}      {:>5s} {:>5s} {:>6s}".format("Label", "A", "B", "Theta"))
for b in blobs.keys():
  mat = xc, yc, A, B, theta = fitRectangle(mats[b])
  #print(str(b) + "\t" + str(A) + "\t" + str(B) + "\t" + str(theta))
  print(f"{b:5d}      {A:>5d} {B:>5d} {theta:6.3f}")
  dx = A / 2 * cos(pi - theta)
  dy = A / 2 * sin(pi - theta)
  drawLine(imDraw, int(xc - dx), int(yc - dy), int(xc + dx), int(yc + dy), b)
  dx = B / 2 * sin(theta)
  dy = B / 2 * cos(theta)
  drawLine(imDraw, int(xc - dx), int(yc - dy), int(xc + dx), int(yc + dy), b)
 
 
print("on Overlay")
imIn.getViewer().drawOverlay(imDraw)
 
print("after overlay")
input()
 

◆ blobsMoments() [2/2]

template<class T >

map< T, Vector_double > blobsMoments	(	const Image< T > &	imLbl,
		const bool	onlyNonZero = `true`,
		bool	central = `false`
	)

blobsMoments() - Measure image moments of each label.

Parameters

[in]	imLbl	: input labeled image
[in]	onlyNonZero	: skip a blob having a null label
[in]	central	: moments are evaluated with respect to the blob barycenter

Returns: a map of pairs <label, Vector<double>> with the image moments of each label.

Note: Whenever possible it's better to privilegiate the other version of this function, as you have more control on what you get.

See also: measMoments()

◆ blobsEntropy()

template<class T , class labelT >

map< labelT, double > blobsEntropy	(	const Image< T > &	imIn,
		map< labelT, Blob > &	blobs
	)

blobsEntropy() - Measure blobs entropy.

Parameters

[in]	imIn	: input labeled image
[in]	blobs	: input Blob map

Returns: a map of pairs <label, double> with the entropy of the image in each blob.

See also: measEntropy()

Detailed Description

Classes

Functions

Function Documentation

◆ computeBlobs()

◆ drawBlobs() [1/2]

◆ drawBlobs() [2/2]

◆ getBlobIDFromOffset() [1/2]

◆ getBlobIDFromOffset() [2/2]

◆ blobsArea() [1/2]

◆ blobsArea() [2/2]

◆ blobsVolume()

◆ blobsMinVal()

◆ blobsMaxVal()

◆ blobsRangeVal()

◆ blobsMeanVal()

◆ blobsValueList()

◆ blobsModeVal()

◆ blobsMedianVal()

◆ blobsBarycenter() [1/2]

◆ blobsBarycenter() [2/2]

◆ blobsBoundBox() [1/2]

◆ blobsBoundBox() [2/2]

◆ blobsMoments() [1/2]

◆ blobsMoments() [2/2]

◆ blobsEntropy()