API

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)

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')

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 steps of the cleaning

  • 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.RemoveBackground_BatchHome(series, rawdir, prossdir, imrange, method='white_tophat', radius=5, weight=0.1, crop=None, bottom=None, verbose=False, Binning=None, n0rf=3, n0rs=3, n0w=3)
FoamQuant.Process.RemoveEdgeBubble(image, mask=None, rpercent=None, masktopbottom=None, returnmask=False, 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, maskcyl=False, rpercent=None, masktopbottom=None)

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, Mask=False, 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.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

FromContact

FoamQuant.FromContact.ReadContactTable(nameread, dirread, imrange, verbose=False, endread='.tsv', n0=3, maximumCoordinationNumber=20)

Read Contact tables and return a dictionary

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

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

Returns:

contact table dictionary {‘lab’,’lab_noedge’,’Z’, ‘z’,’y’,’x’, ‘labs’, ‘conts’}

FoamQuant.FromContact.Texture(Table, verbose=False)

From a contact table dictionary, compute the texture

Parameters:

  • Table (dict) – contact table dictionary

  • verbose (Bool) – if True, print progression

Returns:

lab withedge, lab withoutedge, centroid, radius, S1,S2,S3, S1z,S1y,S1x, S2z,S2y,S2x, S3z,S3y,S3x, U1,U2,U3, U, type

FoamQuant.FromContact.Texture_Batch(nameread, namesave, dirread, dirsave, imrange, verbose=False, endsave='.tsv', n0=3, field=False)

Run Texture 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

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)

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)

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’

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])

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])

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])

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

FoamQuant.Figure.Cut3D(image, zcut=False, ycut=False, xcut=False, showcuts=False, showaxes=False, cmap='gray', interpolation=None, figblocksize=5, returnfig=False, vmin=None, vmax=None, printminmax=False, colorbars=False)

Plot a 3x1 figure showing three orthogonal cross-sections of the 3D image.

Parameters:

  • image (int) – 3D numpy array

  • zcut (int or False) – Optional z cut value

  • ycut (int or False) – Optional y cut value

  • xcut (int or False) – Optional x cut value

  • showcuts (Bool) – Optional plot the orthogonal cuts

  • showaxes (Bool) – Optional plot the axes

  • cmap (str or cmap type) – Optional the color map used for the cuts, Default cmap = ‘gray’

  • interpolation (str or None) – Optional type of interpolation, Default interpolation = None

  • figblocksize (float) – Optional size of the subfigure, Default figblocksize = 5

  • returnfig (Bool) – Optional, if should return the figure, if not returns None

  • vmin (Bool) – Optional, min value for the color range

  • vmax (Bool) – Optional, max value for the color range

  • printminmax (Bool) – Optional, print min and max for the whole image and the three projections

Returns:

None or fig type

FoamQuant.Figure.Histogram(image, histtitle=False)

Plot a 1x1 grey value histogram.

Parameters:

image (numpy array) – 3D image.

Returns:

None

FoamQuant.Figure.LinCmap(vmin=0, vmax=10, first_color='b', last_color='r', verbose=True)

Creates a linear colormap for matplotlib.

Parameters:

  • vmin (float) – min value for the color-range

  • vmax (float) – max value for the color-range

  • first_color_black (str or matplotlib color) – first color

  • last_color_black (str or matplotlib color) – last color

  • verbose (Bool) – If True, prints the number of labels and shows the colormap.

Returns:

matplotlib colormap

FoamQuant.Figure.Proj3D(image, showaxes=False, cmap='gray', interpolation=None, figblocksize=5, returnfig=False, vmin=None, vmax=None, printminmax=False, colorbars=False)

Plot a 3x1 figure showing three orthogonal projections of the 3D image.

Parameters:

  • image (numpy array) – 3D image

  • showaxes (Bool) – Optional plot the axes

  • cmap (str or cmap type) – Optional the color map used for the projections, Default cmap = ‘gray’

  • interpolation (str or None) – Optional the type of interpolation, Default interpolation = None

  • figblocksize (float) – Optional size of the subfigure, Default figblocksize = 5

  • returnfig (Bool) – Optional if should return the figure, if not returns None

  • vmin (Bool) – Optional, min value for the color range

  • vmax (Bool) – Optional, max value for the color range

  • printminmax (Bool) – Optional, print min and max for the whole image and the three projections

Returns:

None or fig

FoamQuant.Figure.RandomCmap(nlabels, type='bright', first_color_black=True, last_color_black=False, verbose=True, GiveRange=None)

Creates a random colormap for matplotlib. Reference: copied from https://github.com/delestro/rand_cmap

Parameters:

  • nlabels (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

  • last_color_black (Bool) – Option to use last color as black, True or False

  • verbose (Bool) – Prints the number of labels and shows the colormap. True or False

Returns:

matplotlib colormap

FoamQuant.Figure.ellipse_plot(Fig, X, Y, Vect, Val, scale_factor=1, mirror=False)

Plot internal 2D structured strain field map.

Parameters:

  • Fig (figure type) – matplotlib.pyplot figure

  • X (numpy array) – structured (N,M) horyzontal positions

  • Y (numpy array) – structured (N,M) vertical positions

  • Vect (numpy array) – structured in-plane eigenvectors [U+x,U+y,U-x,U-y], (N,M,4)

  • Val (numpy array) – structured in-plane eigenvalues [U+,U-,Uphi], (N,M,3)

  • scale_factor (float) – Optional, by default 1

  • mirror (Bool) – Optional, if True the plot is horyzontally flipped

Returns:

None

Movie

VTK

FoamQuant.VTK.json_rand_dictionary(Ncolors, namecmap, 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='spam.vtk')

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

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