Python functions

Process

FoamQuant.Process.BubbleSegmentation(image, SigSeeds=1, SigWatershed=1, watershed_line=False, radius_opening=None, verbose=False, esti_min_dist=None, compactness=None)

Perform the bubble watershed segmentation

Parameters:

  • image (int numpy array) – 3D image

  • SigSeeds (int) – Optional, Gaussian filter Sigma for the seeds

  • SigWatershed (int) – Optional, Gaussian filter Sigma for the watershed

  • watershed_line (Bool) – Optional, If True keep the 0-label surfaces between the segmented bubble regions

  • radius_opening (None or int) – Optional, if not None, perform a radius opening operation on the labelled image with the given radius

  • verbose (Bool) – Optional, if True, print progression steps of the segmentation

  • esti_min_dist (None or float) – Optional, min distance between the seeds

  • compactness (None or float) – Optional, compactness of the diffusion

Returns:

int numpy array

FoamQuant.Process.BubbleSegmentation_Batch(nameread, namesave, dirread, dirsave, imrange, verbose=False, n0=3, endread='.tiff', endsave='.tiff', writeparameters=False, Binning=None, SigSeeds=1, SigWatershed=1, watershed_line=False, esti_min_dist=None, compactness=None, radius_opening=None, ITK=False, ITKLevel=1)

Uses BubbleSegmentation function batchwise

Parameters:

  • nameread (str) – read image name

  • namesave (str) – saved image name

  • dirread (str) – read image directory

  • dirread – saved image directory

  • imrange (list or numpy array) – image indexes array

  • verbose (Bool) – if True, print the progression

  • n0 (int) – number of digit for the saving index, default is 3

  • endread (str) – read image file extension, default is ‘.tiff’

  • endsave (str) – saved image file extension, default is ‘.tiff’

  • writeparameters (str) – saved in a text file the segmentation parameters

  • Binning (str) – saved image file extension, default is ‘.tiff’

  • SigSeeds (int) – Optional, Gaussian filter Sigma for the seeds

  • SigWatershed (int) – Optional, Gaussian filter Sigma for the watershed

  • watershed_line (Bool) – Optional, If True keep the 0-label surfaces between the segmented bubble regions

  • esti_min_dist (None or float) – Optional, min distance between the seeds

  • compactness (None or float) – Optional, compactness of the diffusion

  • radius_opening (None or int) – Optional, if not None, perform a radius opening operation on the labelled image with the given radius

  • ITK (Bool) – If True, the ITKwatershed from SPAM is used

  • ITKLevel (float) – Optional, default is 1

FoamQuant.Process.FastLocalThickness_Batch(nameread, namesave, dirread, dirsave, imrange, verbose=False, endread='.tiff', endsave='.tiff', n0=3, WalThickness=True, Separation=False, scale=1)

Uses localthickness function batchwise. IMPORTANT, please refer to Dahl, V. A. and Dahl A. B. work: Git-link February 2023: https://github.com/vedranaa/local-thickness.git

Parameters:

  • nameread (str) – read image name

  • namesave (str) – saved image name

  • dirread (str) – read image directory

  • dirread – saved image directory

  • imrange (list or numpy array) – image indexes array

  • verbose (Bool) – if True, print the progression

  • endread (str) – read image file extension, default is ‘.tiff’

  • endsave (str) – saved image file extension, default is ‘.tiff’

  • n0 (int) – number of digit for the saving index, default is 3

  • WalThickness (Bool) – If True, save the wall thickness (zeros in the binary image)

  • Separation (Bool) – If True, save the separation thickess (ones in the binary image)

  • scale (float) – Optional downscaling factor, default is 1

FoamQuant.Process.GetContacts(image, image_noedge, maximumCoordinationNumber=20, returnCoordImage=False)

Return labels [0], centroids [1], coordinations [2] of the no-edge image, (and coordination image [3])

Parameters:

  • image (int numpy array) – full 3D image

  • image_noedge (int numpy array) – 3D image with removed label at the edges

  • maximumCoordinationNumber (int) – the maximum coordination number, default 20

  • returnCoordinationImage (Bool) – if True, additionally returns image_noedge coordination image

Returns:

labels [0], centroids [1], coordinations [2] of the no-edge image, (and coordination image [3])

FoamQuant.Process.GetContacts_Batch(nameread, nameread_noedge, namesave, dirread, dirread_noedge, dirsave, imrange, verbose=False, endread='.tiff', endread_noedge='.tiff', endsave='.tiff', n0=3, save='all', maximumCoordinationNumber=20)

Uses GetContacts function batchwise

Parameters:

  • nameread (str) – read image name

  • namesave (str) – saved image name

  • dirread (str) – read image directory

  • dirread – saved image directory

  • imrange (list or numpy array) – image indexes array

  • verbose (Bool) – if True, print the progression

  • endread (str) – read labeled image file extension, default is ‘.tiff’

  • endread_noedge (str) – read labeled no-edge image file extension, default is ‘.tiff’

  • endsave (str) – saved image file extension, default is ‘.tiff’

  • n0 (int) – number of digit for the saving index, default is 3

  • save (str or list of str) – ‘all’: save all, ‘coord’:save the coordination image, ‘image’: save contact image, table’: save the contact table or ‘pair’: save the contact pairs

  • maximumCoordinationNumber (int) – the maximum coordination number, default 20

FoamQuant.Process.MaskCyl(image, rpercent=None, out=True)

Create a cylindrical mask of the size of the image along the Z axis

Parameters:

image (float numpy array) – 3D image

Returns:

int numpy array

FoamQuant.Process.Masking_Batch(nameread, namesave, dirread, dirsave, imrange, verbose=False, n0=3, endread='.tiff', endsave='.tiff', Masktype=[False, True])

Uses MaskCyl function batchwise

Parameters:

  • nameread (str) – read image name

  • namesave (str) – saved image name

  • dirread (str) – read image directory

  • dirread – saved image directory

  • imrange (list or numpy array) – image indexes array

  • verbose (Bool) – if True, print progression steps of the cleaning

  • n0 (int) – number of digit for the saving index, default is 3

  • endread (str) – read image file extension, default is ‘.tiff’

  • endsave (str) – saved image file extension, default is ‘.tiff’

FoamQuant.Process.PhaseSegmentation(image, method='ostu_global', th=0.5, th0=0.3, th1=0.7, returnOtsu=False)

Perform the phase segmentation

Parameters:

  • image (float numpy array) – 3D image

  • method (str) – Optional, method for segmenting the phase, either ‘simple’ for simple threshold, ‘ostu_global’ for a global Otsu threshold, ‘niblack’, ‘sauvola’, or ‘sobel’, Default is ‘ostu_global’

  • th (float) – Optional, given threshold for ‘simple’ method

  • th0 (float) – Optional, given low threshold for ‘sobel’ method

  • th1 (float) – Optional, given high threshold for ‘sobel’ method

  • returnotsu (Bool) – Optional, if True, returns Otsu threshold for ‘ostu_global’ method

Returns:

int numpy array and float

FoamQuant.Process.PhaseSegmentation_Batch(nameread, namesave, dirread, dirsave, imrange, method='ostu_global', th=None, th0=None, th1=None, returnOtsu=False, verbose=False, ROIotsu=False, n0=3, endread='.tiff', endsave='.tiff')

Uses PhaseSegmentation function batchwise

Parameters:

  • nameread (str) – read image name

  • namesave (str) – saved image name

  • dirread (str) – read image directory

  • dirread – saved image directory

  • imrange (list or numpy array) – image indexes array

  • method (str) – Optional, method for segmenting the phase, either ‘simple’ for simple threshold, ‘ostu_global’ for a global Otsu threshold, ‘niblack’, ‘sauvola’, or ‘sobel’, Default is ‘ostu_global’

  • th (float) – Optional, given threshold for ‘simple’ method

  • th0 (float) – Optional, given low threshold for ‘sobel’ method

  • th1 (float) – Optional, given high threshold for ‘sobel’ method

  • returnOtsu (Bool) – Optional, if True, returns Otsu threshold for ‘ostu_global’ method

  • verbose (Bool) – if True, print progression steps of the cleaning

  • ROIotsu (list or numpy array) – list of length 6 defining the region of interest for determining the single Otsu threshold such as [zmin,zmax,ymin,ymax,xmin,xmax]

  • n0 (int) – number of digit for the saving index, default is 3

  • endread (str) – read image file extension, default is ‘.tiff’

  • endsave (str) – saved image file extension, default is ‘.tiff’

FoamQuant.Process.RemoveBackground(image, method='white_tophat', radius=5)

Remove grey-scale image low frequency background

Parameters:

  • image (float numpy array) – 3D image

  • method (str) – method for removing the background, either ‘white_tophat’:white tophat filter or ‘remove_gaussian’: remove the Gaussian filtered image

  • radius (int) – white_tophat kernel radius or sigma gaussian filter radius

Returns:

float numpy array

FoamQuant.Process.RemoveBackground_Batch(nameread, namesave, dirread, dirsave, imrange, method='white_tophat', radius=5, verbose=False, Binning=None, n0=3, endread='.tiff', endsave='.tiff')

Uses RemoveBackground function batchwise

Parameters:

  • nameread (str) – read image name

  • namesave (str) – saved image name

  • dirread (str) – read image directory

  • dirread – saved image directory

  • imrange (list or numpy array) – image indexes array

  • method (str) – method for removing the background, either ‘white_tophat’:white tophat filter or ‘remove_gaussian’: remove the Gaussian filtered image

  • radius (int) – white_tophat kernel radius or sigma gaussian filter radius

  • verbose (Bool) – if True, print progression

  • Binning (None or int) – the binning number

  • n0 (int) – number of digit for the saving index, default is 3

  • endread (str) – read image file extension, default is ‘.tiff’

  • endsave (str) – saved image file extension, default is ‘.tiff’

FoamQuant.Process.RemoveEdgeBubble(image, mask=None, verbose=False)

Remove the bubbles on the image edges and in intersection with the masks (if given)

Parameters:

  • image (int numpy array) – 3D image

  • mask (None, Bool or int numpy array) – 3D image, if given, removes also the labels at the intersection with the mask

  • rpercent (float) – If mask is True, will create a cylindrical mask with rpercent of the half-size of the image

  • masktopbottom (array) – list as [zmin, zmax] for top and bottom edges masking

  • returnmask (Bool) – if True, aditionally returns the mask

  • verbose (Bool) – Optional, if True, print progression steps of the segmentation

Returns:

int numpy array image or [image, mask] arrays if returnmask is True

FoamQuant.Process.RemoveEdgeBubble_Batch(nameread, namesave, dirread, dirsave, imrange, verbose=False, endread='.tiff', endsave='.tiff', n0=3, masktopbottom=None, Masktype=[False, True])

Uses RemoveEdgeBubble function batchwise

Parameters:

  • nameread (str) – read image name

  • namesave (str) – saved image name

  • dirread (str) – read image directory

  • dirread – saved image directory

  • imrange (list or numpy array) – image indexes array

  • verbose (Bool) – if True, print the progression

  • endread (str) – read image file extension, default is ‘.tiff’

  • endsave (str) – saved image file extension, default is ‘.tiff’

  • n0 (int) – number of digit for the saving index, default is 3

  • maskcyl (Bool) – if True, create a cylindrical mask

  • rpercent (float) – If mask is True, will create a cylindrical mask with rpercent of the half-size of the image

  • masktopbottom (array) – list as [zmin, zmax] for top and bottom edges masking

FoamQuant.Process.RemoveSpeckle(image, method='median', radius=1, weight=0.1)

Remove speckle from the image

Parameters:

  • image (float numpy array) – 3D image

  • method (str) – method for removing the speckle, either ‘median’, ‘gaussian’ or ‘tv_chambolle’

  • radius (int) – kernel radius or sigma gaussian filter radius

  • weight (int) – weight for tv_chambolle

Returns:

float numpy array

FoamQuant.Process.RemoveSpeckleBin(image, RemoveObjects=True, RemoveHoles=True, BinClosing=False, ClosingRadius=None, GiveVolumes=False, verbose=False, Vminobj=None, Vminhole=None)

Remove small objects and holes in binary image

Parameters:

  • image (int numpy array) – 3D image

  • RemoveObjects (Bool) – if True, removes the small objects

  • RemoveHoles (Bool) – if True, removes the small holes

  • BinClosing (Bool) – if True, perform a binnary closing of radius ClosingRadius

  • ClosingRadius (int) – radius of the binnary closing

  • GiveVolumes (Bool) – if True, returns in addition the used min volume thresholds for objects and holes

  • verbose (Bool) – if True, print progression steps of the cleaning

  • Vminobj (int) – if given the min volume threshold for the objects is not computed, Vminobj is used as the threshold

  • Vminhole (int) – if given the min volume threshold for the holes is not computed, Vminobj is used as the threshold

Returns:

int numpy array, int, int

FoamQuant.Process.RemoveSpeckleBin_Batch(nameread, namesave, dirread, dirsave, imrange, verbose=False, RemoveObjects=True, RemoveHoles=True, Cobj=0.5, Chole=0.5, BinClosing=False, ClosingRadius=None, n0=3, endread='.tiff', endsave='.tiff')

Uses RemoveSpeckleBin function batchwise

Parameters:

  • nameread (str) – read image name

  • namesave (str) – saved image name

  • dirread (str) – read image directory

  • dirread – saved image directory

  • imrange (list or numpy array) – image indexes array

  • verbose (Bool) – if True, print the progression

  • RemoveObjects (Bool) – If True, remove the small objects with a volume below Cobj*MaxObjVol

  • RemoveHoles (Bool) – If True, remove the small holes with a volume below Chole*MaxholeVol

  • Cobj (float) – volume thresholding coefficient for removing the small objects

  • Chole (float) – volume thresholding coefficient for removing the small holes

  • BinClosing (float) – volume thresholding coefficient for removing the small holes

  • n0 (int) – number of digit for the saving index, default is 3

  • endread (str) – read image file extension, default is ‘.tiff’

  • endsave (str) – saved image file extension, default is ‘.tiff’

FromBinary

FoamQuant.FromBinary.LiqFrac_Batch(nameread, namesave, dirread, dirsave, imrange, TypeGrid='Global', Nz=None, Ny=None, Nx=None, Nr=None, Naz=None, crop=None, Masktype=[False, True], Mask=None, verbose=False, endread='.tif', endsave='.pkl', n0=3, structured=True)

Read 3D binary images and save liquid fraction informations in series (for loop). Save liquid fraction dictionary as pickle: {“crop”, “1D, 2D or 3D grid”,”lf”}

Parameters:

  • series (str) – series name

  • series – read image directory

  • savedir (str) – save liquid fraction directory

  • imrange (int numpy array) – image index range

  • TypeGrid (str) – Optional, type of method: ‘Global’ for global liquid fraction, ‘CartesMesh’ for cartesian grid liquid fraction, ‘CylMesh’ for cylindrical grid liquid fraction

  • Nz (int) – Optional, number of sub-regions along z

  • Ny (int) – Optional, number of sub-regions along y

  • Nx (int) – Optional, number of sub-regions along x

  • Nr (int) – Optional, number of sub-regions along r

  • crop ([zmin, zmax, ymin, ymax, xmin, xmax] int array) – Optional, Study crop region inside the image

  • Mask (int numpy array) – Optional, 3D image

  • verbose (int numpy array) – if True or 1, print progress image by image. If 10, print additionally the extracted liquid fraction dictionary

Returns:

None

FoamQuant.FromBinary.LiqFrac_CartesMesh(image, Nz, Ny, Nx, crop=None, Mask=None, structured=True)

Return a 3D zyx grid with its corresponding non-overlapping subvolume (cuboids) liquid fraction

Parameters:

  • image (int numpy array) – 3D image

  • Nz (int) – number of sub-regions along z

  • Ny (int) – number of sub-regions along y

  • Nx (int) – number of sub-regions along x

  • crop ([zmin, zmax, ymin, ymax, xmin, xmax] int array) – Study crop region inside the image

  • Mask (int numpy array) – 3D image

Returns:

int numpy array

FoamQuant.FromBinary.LiqFrac_Glob(image, Nz, Nr, crop=None, Mask=None)

Return the global liquid fraction of an image

Parameters:

  • image (int numpy array) – 3D image

  • crop ([zmin, zmax, ymin, ymax, xmin, xmax] int array) – Study crop region inside the image

  • Mask (int numpy array) – 3D image

Returns:

int numpy array

FromLabelled

FoamQuant.FromLabelled.Read_RegionProp(nameread, dirread, imrange, verbose=False, endread='.tsv', n0=3)

Read the saved files generated by the .tsv RegionProp_Batch function on a batch of images

Parameters:

  • nameread (str) – file name (without the ending number)

  • dirread (str) – folder directory

  • imrange (int array) – list of image indexes

  • verbose (Bool) – if True, print the image number

  • readend (str) – ending

  • n0 (int) – number of 0 in the indexing

Returns:

dictionary of ‘lab’, ‘z’, ‘y’, ‘x’, ‘vol’, ‘rad’, ‘area’, ‘sph’, ‘volfit’, ‘S1’, ‘S2’, ‘S3’, ‘e1z’, ‘e1y’, ‘e1x’, ‘e2z’, ‘e2y’, ‘e2x’, ‘e3z’, ‘e3y’, ‘e3x’, ‘U1’, ‘U2’, ‘U3’, ‘U’, ‘type’

FoamQuant.FromLabelled.RegionProp(image, field=False)

Return basic region properties from a labeled image: labels [0], centroids [1], volumes [2], (inertia components [3])

Parameters:

  • image (int numpy array) – 3D image

  • IncludeInertia (Bool) – if True, also return inertial components

Returns:

array of labels [0], centroids [1], volumes [2], (inertia components [3])

FoamQuant.FromLabelled.RegionProp_Batch(nameread, namesave, dirread, dirsave, imrange, verbose=False, endread='.tif', endsave='.tsv', n0=3, field=False)

Run RegionProp function on a batch of images and save the outputs as .tsv

Parameters:

  • readdir (str) – Labeled images folder

  • readdir – folder to save the .tsv doc

  • readend (str) – tiff image saving end, default is ‘.tiff’

  • imrange (int array) – list of image indexes

  • IncludeInertia (Bool) – if True, also return inertial components

  • verbose (Bool) – if True, print verbose including the number of labels

Batchelor

FoamQuant.Batchelor.Batchelor_Batch(nameread, namesave, dirread, dirsave, imrange, verbose=False, endread='.tif', endsave='.tsv', n0=3)

Compute Batchelor tensors for a batch of labeled images and save to TSV.

Parameters:

  • nameread (str) – Base name of input images

  • namesave (str) – Base name for output files

  • dirread (str) – Directory containing labeled images

  • dirsave (str) – Directory to save TSV files

  • imrange (list or array) – Image indices to process

  • verbose (bool) – Print progress information

  • endread (str) – Input image file extension

  • endsave (str) – Output file extension

  • n0 (int) – Zero-padding for image indices

Returns:

None

FoamQuant.Batchelor.Read_Batchelor(nameread, dirread, imrange, verbose=False, endread='.tsv', n0=3, normalised=True)

Read Batchelor tensor TSV files generated by Batchelor_Batch.

Parameters:

  • nameread (str) – Base file name

  • dirread (str) – Directory containing TSV files

  • imrange (list or array) – Image indices to read

  • verbose (bool) – Print progress information

  • endread (str) – File extension

  • n0 (int) – Zero-padding for image indices

  • normalised (bool) – If True, return volume-normalized tensors

Returns:

  • Labels

  • Coordinates

  • Volumes

  • Mesh surface areas

  • Batchelor tensors

Return type:

tuple of lists

class FoamQuant.Batchelor.Results(**kwargs)

A minimal class for use when returning multiple values from a function

This class supports dict-like assignment and retrieval (obj['im'] = im), namedtuple-like attribute look-ups (obj.im), and generic class-like object assignment (obj.im = im)

FoamQuant.Batchelor.extend_slice(slices, shape, pad=1)

Extend slice indices by a fixed padding while respecting image bounds.

Parameters:

  • slices (tuple of slice) – Slice objects defining the region of interest

  • shape (tuple or list) – Shape of the full image

  • pad (int or array-like) – Number of voxels to extend in each direction

Returns:

Extended slice objects

Return type:

tuple of slice

FoamQuant.Batchelor.mesh_Batchelor_tensor(mesh=None, verts=None, faces=None)

Compute the Batchelor tensor from a surface mesh.

Parameters:

  • mesh (Results or None) – Mesh object returned by mesh_region

  • verts (numpy.ndarray or None) – Mesh vertices

  • faces (numpy.ndarray or None) – Mesh faces

Returns:

  • Batchelor tensor (3x3)

  • Surface area of the mesh

Return type:

tuple (numpy.ndarray, float)

FoamQuant.Batchelor.mesh_batchelor(verts, faces)

Compute the Batchelor tensor from triangular mesh geometry.

Parameters:

  • verts (numpy.ndarray) – Vertex coordinates (V, 3)

  • faces (numpy.ndarray) – Triangle indices (F, 3)

Returns:

  • Batchelor tensor (3x3)

  • Surface area

Return type:

tuple (numpy.ndarray, float)

FoamQuant.Batchelor.mesh_region(region: bool, strel=None)

Generate a triangular surface mesh of a region using marching cubes.

Parameters:

  • region (numpy.ndarray) – Boolean image defining the region of interest

  • strel (numpy.ndarray or None) – Structuring element used to blur the region prior to meshing

Returns:

Mesh object containing vertices, faces, normals and values

Return type:

Results

FoamQuant.Batchelor.mesh_surface_area1(mesh=None, verts=None, faces=None)

Compute the surface area of a triangular mesh.

Parameters:

  • mesh (Results or None) – Mesh object returned by mesh_region

  • verts (numpy.ndarray or None) – Mesh vertices

  • faces (numpy.ndarray or None) – Mesh faces

Returns:

Surface area of the mesh

Return type:

float

FoamQuant.Batchelor.ps_round(r, ndim, smooth=True)

Create a spherical (or circular) structuring element.

Parameters:

  • r (float) – Radius of the structuring element

  • ndim (int) – Dimensionality of the element (2 or 3)

  • smooth (bool) – If True, use smooth sphere faces

Returns:

Structuring element

Return type:

numpy.ndarray

FoamQuant.Batchelor.region_Batchelor_tensors(regions, voxel_size=1, strel=None)

Compute the Batchelor tensor for each labeled region in an image.

Parameters:

  • regions (numpy.ndarray) – Labeled image where each integer label defines a region

  • voxel_size (float) – Physical voxel size

  • strel (numpy.ndarray or None) – Structuring element used to blur regions before meshing

Returns:

  • Batchelor tensor for each region (N, 3, 3)

  • Surface area of each region

Return type:

tuple (numpy.ndarray, numpy.ndarray)

FoamQuant.Batchelor.region_surface_areas(regions, voxel_size=1, strel=None)

Compute the surface area of each labeled region in a 2D or 3D image.

Optionally computes interfacial areas by meshing each region using the marching cubes algorithm.

Parameters:

  • regions (numpy.ndarray) – Labeled image where each integer label defines a region (label 0 is ignored)

  • voxel_size (float) – Physical size of one voxel edge

  • strel (numpy.ndarray or None) – Structuring element used to blur the region prior to meshing

Returns:

Surface area of each region (index = label - 1)

Return type:

numpy.ndarray

FoamQuant.Batchelor.show_mesh(mesh)

Visualize a triangular surface mesh in 3D.

Parameters:

mesh (Results) – Mesh object returned by marching_cubes or mesh_region

Returns:

Matplotlib figure handle

Return type:

matplotlib.figure.Figure

Tracking

FoamQuant.Tracking.Combine_Tracking(nameread, dirread, imrange, verbose=False, endread='.tsv', n0=3)

Combine the LabelTracking result tables for a full time-series tracking of the labels present in the first image

Parameters:

  • nameread (str) – read image name

  • dirread (str) – read image directory

  • imrange (list or numpy array) – image indexes array

  • verbose (Bool) – if True, print progression

  • endread (str) – read RegionProperties file extension, default is ‘.tsv’

  • n0 (int) – number of digit for the saving index, default is 3

Returns:

combined dictionary {‘lab’,’labtransl’,’laborig’,’z’,’y’,’x’, ‘dz’, ‘dy’, ‘dx’, ‘vol’, ‘rad’, ‘area’, ‘sph’, ‘volfit’, ‘U’, ‘type’, ‘Utype’}

FoamQuant.Tracking.LabelTracking(Prop1, Prop2, searchbox=[- 10, 10, - 10, 10, - 10, 10], Volpercent=0.05, ddictsv=None)

Return tracked properties from RegionProperties tables

Parameters:

  • Prop1 (dic type) – RegionProperties table at time 1

  • Prop1 – RegionProperties table at time 2

  • searchbox (searchbox size (1,6) array corresponding to [zmin,zmax,ymin,ymax,xmin,xmax], default is [-10,10,-10,10,-10,10]) – method for removing the background, either ‘white_tophat’:white tophat filter or ‘remove_gaussian’: remove the Gaussian filtered image

  • Volpercent (float) – allowed volume variation percentage from one image to the next, default is 0.05 (5 %)

Returns:

numpy arrays: Found label, Found coordinate, Number of candidates, Lost label, Lost coordinates, Volume,Radius,Area,Sphericity,Volume fit, U, type

FoamQuant.Tracking.LabelTracking_Batch(nameread, namesave, dirread, dirsave, imrange, verbose=False, endread='.tsv', endsave='.tsv', n0=3, searchbox=[- 10, 10, - 10, 10, - 10, 10], Volpercent=0.05, namedirddic=[])

Run LabelTracking batchwise

Parameters:

  • nameread (str) – read image name

  • namesave (str) – saved image name

  • dirread (str) – read image directory

  • dirsave (str) – saved image directory

  • imrange (list or numpy array) – image indexes array

  • verbose (Bool) – if True, print progression

  • endread (str) – read RegionProperties file extension, default is ‘.tsv’

  • endsave (str) – saved Tracking file extension, default is ‘.tsv’

  • n0 (int) – number of digit for the saving index, default is 3

  • searchbox (searchbox size (1,6) array corresponding to [zmin,zmax,ymin,ymax,xmin,xmax], default is [-10,10,-10,10,-10,10]) – method for removing the background, either ‘white_tophat’:white tophat filter or ‘remove_gaussian’: remove the Gaussian filtered image

  • Volpercent (float) – allowed volume variation percentage from one image to the next, default is 0.05 (5 %)

Returns:

numpy arrays: Found label, Found coordinate, Number of candidates, Lost label, Lost coordinates, Volume,Radius,Area,Sphericity,Volume fit, U, type

FoamQuant.Tracking.Read_LabelTracking(nameread, dirread, imrange, verbose=False, endread='.tsv', n0=3)

Read the full batch of LabelTracking result tables

Parameters:

  • nameread (str) – read image name

  • dirread (str) – saved image name

  • imrange (list or numpy array) – image indexes array

  • verbose (Bool) – if True, print progression

  • endread (str) – read RegionProperties file extension, default is ‘.tsv’

  • n0 (int) – number of digit for the saving index, default is 3

Returns:

dictionary {‘lab1’,’z1’,’y1’,’x1’,’lab2’,’z2’,’y2’,’x2’, ‘Count’, ‘dz’, ‘dy’, ‘dx’, ‘Count’,’vol1’,’rad1’,’area1’,’sph1’,’volfit1’,’U1’,’type1’,’Utype1’,’vol2’,’rad2’,’area2’,’sph2’’volfit2’,’U2’’type2’’Utype2’}

FoamQuant.Tracking.Save_Tracking(combined, namesave, dirsave, verbose=False, endsave='.csv')

Save the combined tracking dictionary as a table

Parameters:

  • combined (dict) – combined tracking dictionary

  • namesave (str) – save image name

  • dirsave (str) – save image directory

  • verbose (Bool) – if True, print progression

  • endread (str) – read RegionProperties file extension, default is ‘.csv’

T1

FoamQuant.T1.DetectT1_Batch(readdirnameall, readdirnamelost, readdirnamenew, namesave, dirsave, imrange, verbose=False, n0=3)

Batch detection of T1 events over a sequence of images.

T1 events are detected both from lost-to-new and new-to-lost contact transitions and saved as pickle files.

Parameters:

  • readdirnameall (tuple) – Directory of all contacts

  • readdirnamelost (tuple) – Directory of lost contacts

  • readdirnamenew (tuple) – Directory of new contacts

  • namesave (str) – Base name for output files

  • dirsave (str) – Output directory

  • imrange (list or array) – Image indices

  • verbose (bool) – Print progress information

  • n0 (int) – Zero-padding for image indices

Returns:

None

FoamQuant.T1.DetectT1_LostToNew(cont, lost, new, lcoord1, lcoord2, ncoord1, ncoord2)

Detect T1 events by linking lost contacts to newly formed contacts.

For each lost contact, neighbors are searched to identify newly created contacts consistent with a T1 transition.

Parameters:

  • cont (dict) – All contacts at time t

  • lost (list) – Lost contact label pairs

  • new (list) – New contact label pairs

  • lcoord1 (list) – Coordinates of first label of lost contacts

  • lcoord2 (list) – Coordinates of second label of lost contacts

  • ncoord1 (list) – Coordinates of first label of new contacts

  • ncoord2 (list) – Coordinates of second label of new contacts

Returns:

  • Lost contacts involved in T1

  • New contacts involved in T1

  • Coordinates of lost contacts

  • Coordinates of new contacts

  • Lost contacts not involved in T1

  • Coordinates of lost contacts not involved in T1

Return type:

tuple

FoamQuant.T1.DetectT1_NewToLost(cont, lost, new, lcoord1, lcoord2, ncoord1, ncoord2)

Detect T1 events by linking new contacts to previously lost contacts.

Parameters:

  • cont (dict) – All contacts at time t

  • lost (list) – Lost contact label pairs

  • new (list) – New contact label pairs

  • lcoord1 (list) – Coordinates of first label of lost contacts

  • lcoord2 (list) – Coordinates of second label of lost contacts

  • ncoord1 (list) – Coordinates of first label of new contacts

  • ncoord2 (list) – Coordinates of second label of new contacts

Returns:

  • Lost contacts involved in T1

  • New contacts involved in T1

  • Coordinates of lost contacts

  • Coordinates of new contacts

  • New contacts not involved in T1

  • Coordinates of new contacts not involved in T1

Return type:

tuple

FoamQuant.T1.LostContact(Pairs1, Pairs_tsl2, Reg1)

Detect lost contacts between two consecutive time steps.

A contact is considered lost if both labels still exist at t+1 but the pair itself no longer exists.

Parameters:

  • Pairs1 (dict) – Contact pairs at time t

  • Pairs_tsl2 (dict) – Contact pairs at time t+1 after tracking

  • Reg1 (dict) – Region properties at time t (labels and coordinates)

Returns:

Dictionary containing lost contact labels and coordinates

Return type:

dict - clab : list of [lab1, lab2] - cx : list of [x1, x2] - cy : list of [y1, y2] - cz : list of [z1, z2]

FoamQuant.T1.LostNewContact_Batch(pairsdirname, pairstrldirname, savedirnamelost, regdirname, savedirnamenew, imrange, verbose=True)

Batch computation of lost and new contacts over a sequence of images.

Results are written as TSV files for each image pair (t, t+1).

Parameters:

  • pairsdirname (tuple) – Directory info for original contact pairs

  • pairstrldirname (tuple) – Directory info for tracked contact pairs

  • savedirnamelost (tuple) – Output directory for lost contacts

  • regdirname (tuple) – Directory info for region properties

  • savedirnamenew (tuple) – Output directory for new contacts

  • imrange (list or array) – Image indices to process

  • verbose (bool) – Print progress information

Returns:

None

FoamQuant.T1.NewContact(Pairs1, Pairs_tsl2)

Detect new contacts appearing between two consecutive time steps.

A contact is considered new if both labels existed at time t but the contact pair did not.

Parameters:

  • Pairs1 (dict) – Contact pairs at time t

  • Pairs_tsl2 (dict) – Contact pairs at time t+1 after tracking (extended)

Returns:

Dictionary containing new contact labels and coordinates

Return type:

dict - clab : list of [lab1, lab2] - cx : list of [x1, x2] - cy : list of [y1, y2] - cz : list of [z1, z2]

FoamQuant.T1.ReadT1(readdirname, imrange, verbose=False, n0=3)

Read T1 event pickle files for a sequence of images.

Parameters:

  • readdirname (tuple) – Directory containing T1 pickle files

  • imrange (list or array) – Image indices

  • verbose (bool) – Print file paths while reading

  • n0 (int) – Zero-padding for image indices

Returns:

List containing New→Lost and Lost→New T1 events

Return type:

list

FoamQuant.T1.Read_lostnew(readdirname, imrange, verbose=True)

Read lost or new contact TSV files into Python dictionaries.

Parameters:

  • readdirname (tuple) – Directory information for TSV files

  • imrange (list or array) – Image indices

  • verbose (bool) – Print file paths while reading

Returns:

List of dictionaries containing contact labels and coordinates

Return type:

list of dict

VTK

FoamQuant.VTK.json_rand_dictionary(Ncolors, namecmap, dirsave='', first_color_black=True)

Save a json random colormap to be used with ParaView or Tomviz.

Parameters:

  • Ncolors (int) – Number of labels (size of colormap)

  • type (str) – ‘bright’ for strong colors, ‘soft’ for pastel colors

  • first_color_black (Bool) – Option to use first color as black, True or False

Returns:

None

FoamQuant.VTK.writeGlyphsVTK(coordinates, pointData, fileName='SavedGlyphs.vtk')

Slightly modified writeGlyphsVTK function from the SPAM package.

Write a plain text glyphs vtk.

Parameters:

  • coordinates ((N,3) array of float) – Coordinates of the centre of all n glyphs

  • pointData (dict {'field1name':field1,'field2name':field2, ...}) – (N,1) arrays for scalar values, (N,3) for vector values and (N,3) for tensor values

  • fileName (int) – Optional name of the output file. By default=’.vtk’

Returns:

str index

Passage

FoamQuant.Passage.Azimuth(X, Y)

Return the aziuthal angle of a point from its coordinates x and y

Parameters:

  • X (float) – coordinate x

  • Y (float) – coordinate y

Returns:

float, cylindrical azimuthal angle phi

FoamQuant.Passage.Cartesian2Cylindrical_Point(Coord_Cartesian, CoordAxis=[0, 1008, 1008], CylAxisZ=[1, 0, 0], CylAxisY=[0, 1, 0], CylAxisX=[0, 0, 1], deg=False)

Return unstructured cylindrical coordinates array (N,3) from unstructured cartesian coordinates (N,3)

Parameters:

  • Coord_Cartesian (numpy array) – unstructured cartesian coordinates, expressed in the image basis [z,y,x]

  • CoordAxis (numpy array) – Coordinates of the axis of rotation in the image basis [z,y,x]

  • CylAxisZ (numpy array) – Direction vector of the axis of rotation Z expressed in the image basis [z,y,x]

  • CylAxisY (numpy array) – Direction vector of the axis Y expressed in the image basis [z,y,x]

  • CylAxisX (numpy array) – Direction vector of the axis X expressed in the image basis [z,y,x]

Returns:

unstructured cylindrical coordinates (N,3), expressed in the cylindrical basis [r,phi,z]

FoamQuant.Passage.Cartesian2Cylindrical_Tensor(Coord_Cartesian, T_Cartesian, CoordAxis=[0, 1008, 1008], CylAxisZ=[1, 0, 0], CylAxisY=[0, 1, 0], CylAxisX=[0, 0, 1], deg=False)

Return unstructured cylindrical coordinates (N,3) and tensors (N,3,3) from unstructured cartesian coordinates (N,3) and tensors (N,3,3)

Parameters:

  • Coord_Cartesian (numpy array) – unstructured cartesian coordinates, expressed in the image basis [z,y,x]

  • CoordAxis (numpy array) – Coordinates of the axis of rotation in the image basis [z,y,x]

  • CylAxisZ (numpy array) – Direction vector of the axis of rotation Z expressed in the image basis [z,y,x]

  • CylAxisY (numpy array) – Direction vector of the axis Y expressed in the image basis [z,y,x]

  • CylAxisX (numpy array) – Direction vector of the axis X expressed in the image basis [z,y,x]

Returns:

unstructured cylindrical coordinates [0] and tensors [1], expressed in the cylindrical basis [r,phi,z]

FoamQuant.Passage.Cartesian2Cylindrical_Vector(Coord_Cartesian, V_Cartesian, CoordAxis=[0, 1008, 1008], CylAxisZ=[1, 0, 0], CylAxisY=[0, 1, 0], CylAxisX=[0, 0, 1], deg=False)

Return unstructured cylindrical coordinates (N,3) and vectors (N,3) from unstructured cartesian coordinates (N,3) and vectors (N,3)

Parameters:

  • Coord_Cartesian (numpy array) – unstructured cartesian coordinates, expressed in the image basis [z,y,x]

  • CoordAxis (numpy array) – Coordinates of the axis of rotation in the image basis [z,y,x]

  • CylAxisZ (numpy array) – Direction vector of the axis of rotation Z expressed in the image basis [z,y,x]

  • CylAxisY (numpy array) – Direction vector of the axis Y expressed in the image basis [z,y,x]

  • CylAxisX (numpy array) – Direction vector of the axis X expressed in the image basis [z,y,x]

Returns:

unstructured cylindrical coordinates [0] and vectors [1], expressed in the cylindrical basis [r,phi,z]

FoamQuant.Passage.Cartesian2Spherical_Point(Coord_Cartesian, CoordAxis=[0, 1008, 1008], CylAxisZ=[1, 0, 0], CylAxisY=[0, 1, 0], CylAxisX=[0, 0, 1])

Return unstructured spherical coordinates array (N,3) from unstructured cartesian coordinates (N,3)

Parameters:

  • Coord_Cartesian (numpy array) – unstructured cartesian coordinates, expressed in the image basis [z,y,x]

  • CoordAxis (numpy array) – Coordinates of the axis of rotation in the image basis [z,y,x]

  • CylAxisZ (numpy array) – Direction vector of the axis of rotation Z expressed in the image basis [z,y,x]

  • CylAxisY (numpy array) – Direction vector of the axis Y expressed in the image basis [z,y,x]

  • CylAxisX (numpy array) – Direction vector of the axis X expressed in the image basis [z,y,x]

Returns:

unstructured cylindrical coordinates (N,3), expressed in the cylindrical basis [r,phi,z]

FoamQuant.Passage.Cartesian2Spherical_Tensor(Coord_Cartesian, T_Cartesian, CoordAxis=[0, 1008, 1008], CylAxisZ=[1, 0, 0], CylAxisY=[0, 1, 0], CylAxisX=[0, 0, 1])

Return unstructured spherical coordinates (N,3) and tensors (N,3,3) from unstructured cartesian coordinates (N,3) and tensors (N,3,3)

Parameters:

  • Coord_Cartesian (numpy array) – unstructured cartesian coordinates, expressed in the image basis [z,y,x]

  • CoordAxis (numpy array) – Coordinates of the axis of rotation in the image basis [z,y,x]

  • CylAxisZ (numpy array) – Direction vector of the axis of rotation Z expressed in the image basis [z,y,x]

  • CylAxisY (numpy array) – Direction vector of the axis Y expressed in the image basis [z,y,x]

  • CylAxisX (numpy array) – Direction vector of the axis X expressed in the image basis [z,y,x]

Returns:

unstructured cylindrical coordinates [0] and tensors [1], expressed in the cylindrical basis [r,phi,z]

FoamQuant.Passage.Cartesian2Spherical_Vector(Coord_Cartesian, V_Cartesian, CoordAxis=[0, 1008, 1008], CylAxisZ=[1, 0, 0], CylAxisY=[0, 1, 0], CylAxisX=[0, 0, 1])

Return unstructured spherical coordinates (N,3) and vectors (N,3) from unstructured cartesian coordinates (N,3) and vectors (N,3)

Parameters:

  • Coord_Cartesian (numpy array) – unstructured cartesian coordinates, expressed in the image basis [z,y,x]

  • CoordAxis (numpy array) – Coordinates of the axis of rotation in the image basis [z,y,x]

  • CylAxisZ (numpy array) – Direction vector of the axis of rotation Z expressed in the image basis [z,y,x]

  • CylAxisY (numpy array) – Direction vector of the axis Y expressed in the image basis [z,y,x]

  • CylAxisX (numpy array) – Direction vector of the axis X expressed in the image basis [z,y,x]

Returns:

unstructured cylindrical coordinates [0] and vectors [1], expressed in the cylindrical basis [r,phi,z]

FoamQuant.Passage.CylCoord(Coord_Cartesian, CoordAxis=[0, 1008, 1008], CylAxisZ=[1, 0, 0], CylAxisY=[0, 1, 0], CylAxisX=[0, 0, 1])

Return the cylindrical coordinate of a point from its cartesian coordinates

Parameters:

  • Coord_Cartesian (numpy array) – cartesian coordinates in the image basis [z,y,x]

  • CoordAxis (numpy array) – Coordinates of the axis of rotation in the image basis [z,y,x]

  • CylAxisZ (numpy array) – Direction vector of the axis of rotation Z expressed in the image basis [z,y,x]

  • CylAxisY (numpy array) – Direction vector of the axis Y expressed in the image basis [z,y,x]

  • CylAxisX (numpy array) – Direction vector of the axis X expressed in the image basis [z,y,x]

Returns:

cylindrical coordinates [r,phi,z]

FoamQuant.Passage.CylR(X, Y)

Return the cylindrical radius r of a point from its coordinates x and y

Parameters:

  • X (float) – coordinate x

  • Y (float) – coordinate y

Returns:

float, cylindrical radius r

FoamQuant.Passage.Polar(Z, spheR)

Return the spherical polar angle of a point from its coordinates x, y and z

Parameters:

  • X (float) – coordinate x

  • Y (float) – coordinate y

  • Z (float) – coordinate z

Returns:

float, spherical radius r

FoamQuant.Passage.Pzyx2phithetar(Azi, Polar)

Return the spherical passage matrix, from the spherical aziuthal and polar angles Azi and Polar

Parameters:

  • Azi (float) – azimuthal angle Azi

  • Polar (float) – polar angle Polar

Returns:

Passage matrix from (z,y,x) to (phi,theta,r), (3,3) numpy array

FoamQuant.Passage.Pzyx2zphir(Azi)

Return the cylindrical passage matrix from the cylindrical aziuthal angle Azi

Parameters:

phi (float) – azimuthal angle Azi

Returns:

Passage matrix from (z,y,x) to (z,phi,r), (3,3) numpy array

FoamQuant.Passage.SpheCoord(Coord_Cartesian, CoordAxis=[0, 1008, 1008], CylAxisZ=[1, 0, 0], CylAxisY=[0, 1, 0], CylAxisX=[0, 0, 1])

Return the spherical coordinates of a point from its cartesian coordinates

Parameters:

  • Coord_Cartesian (numpy array) – cartesian coordinates in the image basis [z,y,x]

  • CoordAxis (numpy array) – Coordinates of the axis of rotation in the image basis [z,y,x]

  • CylAxisZ (numpy array) – Direction vector of the axis of rotation Z expressed in the image basis [z,y,x]

  • CylAxisY (numpy array) – Direction vector of the axis Y expressed in the image basis [z,y,x]

  • CylAxisX (numpy array) – Direction vector of the axis X expressed in the image basis [z,y,x]

Returns:

spherical coordinates [r,phi,z]

FoamQuant.Passage.SpheR(X, Y, Z)

Return the spherical radius of a point from its coordinates x, y and z

Parameters:

  • X (float) – coordinate x

  • Y (float) – coordinate y

  • Z (float) – coordinate z

Returns:

float, spherical radius r

Average

FoamQuant.Average.Grid_Pavg(Coord, P, Range, N, NanFill=True, verbose=False, structured=True)

Return averaged scalar field over a 3D grid

Parameters:

  • Coord (numpy array) – unstructured point coordinates (N,3)

  • P (numpy array) – unstructured scalar array (N,1)

  • Range (numpy array) – Averaging 3D ranges, such as [zmin,zmax,ymin,ymax,xmin,xmax]

  • N (numpy array) – Number of points along each dimension, such as [Nz,Ny,Nx]

  • NanFill (Bool) – If True fill with NaN when the Count is equal to 0 (else fill with zeros)

  • verbose (Bool) – If True, print the averaging Cartesian grid

  • structured (Bool) – If True, return a structured scalar averaged field (Nz,Ny,Nx,1), else return an unstructured field (Nz*Ny*Nx,1)

Returns:

[0] [grid0,grid1,grid2], [1] Grid coordinates, [2] Mean scalar field, [3] Std scalar field, [4] Count

FoamQuant.Average.Grid_Tavg(Coord, T, Range, N, NanFill=True, verbose=False, structured=True)

Return averaged tensor field over a 3D grid

Parameters:

  • Coord (numpy array) – unstructured point coordinates (N,3)

  • P (numpy array) – unstructured tensor array (N,3,3)

  • Range (numpy array) – Averaging 3D ranges, such as [zmin,zmax,ymin,ymax,xmin,xmax]

  • N (numpy array) – Number of points along each dimension, such as [Nz,Ny,Nx]

  • NanFill (Bool) – If True fill with NaN when the Count is equal to 0 (else fill with zeros)

  • verbose (Bool) – If True, print the averaging Cartesian grid

  • structured (Bool) – If True, return a structured tensor averaged field (Nz,Ny,Nx,3,3), else return an unstructured field (Nz*Ny*Nx,3,3)

Returns:

[0] [grid0,grid1,grid2], [1] Grid coordinates, [2] Mean tensor field, [3] Std tensor field, [4] Count

FoamQuant.Average.Grid_Vavg(Coord, V, Range, N, NanFill=True, verbose=False, structured=True)

Return averaged vector field over a 3D grid

Parameters:

  • Coord (numpy array) – unstructured point coordinates (N,3)

  • P (numpy array) – unstructured vector array (N,3)

  • Range (numpy array) – Averaging 3D ranges, such as [zmin,zmax,ymin,ymax,xmin,xmax]

  • N (numpy array) – Number of points along each dimension, such as [Nz,Ny,Nx]

  • NanFill (Bool) – If True fill with NaN when the Count is equal to 0 (else fill with zeros)

  • verbose (Bool) – If True, print the averaging Cartesian grid

  • structured (Bool) – If True, return a structured vector averaged field (Nz,Ny,Nx,1), else return an unstructured field (Nz*Ny*Nx,3)

Returns:

[0] [grid0,grid1,grid2], [1] Grid coordinates, [2] Mean vector field, [3] Std vector field, [4] Count

Figure

Movie

Helper

FoamQuant.Helper.RangeList(i1, i2, verbose=False)

Return an index range

Parameters:

  • i1 (int) – first index

  • i2 (int) – last index

  • verbose (Bool) – If True, print the range

Returns:

int numpy array

FoamQuant.Helper.strindex(i, n0)

Return str index written on n0 digit

Parameters:

  • i (int) – index

  • n0 (int) – number of 0 digit

Returns:

str index