pumapy.utilities
pumapy.utilities.example_files
- pumapy.utilities.example_files.list_example_files()[source]
List all example files available inside the folder python/pumapy/data
- Returns
List of example file names
- Return type
list
- pumapy.utilities.example_files.path_to_example_file(example_filename)[source]
Path to example data that is installed with pumapy (used for testing and tutorial)
- Parameters
example_filename (str) – name of the example file (check python/pumapy/data for a list of example files)
- Returns
path to the example file, which can be used to import it
- Return type
str
- Example
>>> import pumapy as puma >>> ws_example = puma.import_3Dtiff(puma.path_to_example_file("200_fiberform.tif")) # import example file Importing ... >>> # puma.plot_slices(ws_example) # visualize example file
pumapy.utilities.generic_checks
- pumapy.utilities.generic_checks.estimate_max_memory(material_property, workspace_shape, solver_type='iterative', need_to_orient=False, mf=True, perm_fluid_vf=1.0)[source]
Compute an estimate of the extra maximum memory required to run a specified material property on a domain
- Parameters
material_property (string) – property to estimate, options: ‘anisotropic_conductivity’, ‘isotropic_conductivity’, ‘tortuosity’, ‘elasticity’, ‘permeability’
workspace_shape ((int, int, int)) – size of the domain to compute
solver_type (string) – type of solver, options: ‘direct’, ‘iterative’
need_to_orient (bool) – domain with orientation (needed for anisotropic conductivity and elasticity)
mf (bool) – using matrix-free construction of the system (needed for FE methods)
- Returns
number of Bytes
- Return type
int
- pumapy.utilities.generic_checks.set_random_seed(seed)[source]
Set random seed for scipy and numpy to make results reproducible. NB: if you want to generate the same material twice in the same process, you need to call it twice (see example)
- Parameters
seed (int) – random seed
- Example
>>> import pumapy as puma >>> puma.set_random_seed(1) >>> ws = puma.generate_random_spheres((100, 100, 100), 20, 0.5, allow_intersect=True, segmented=False) Approximately ... spheres to be generated... >>> # puma.render_volume(ws) # to visualize it >>> puma.set_random_seed(1) # need to call it again to get the same domain! >>> ws = puma.generate_random_spheres((100, 100, 100), 20, 0.5, allow_intersect=True, segmented=False) Approximately ... spheres to be generated... >>> # puma.render_volume(ws)
pumapy.utilities.isosurface
- class pumapy.utilities.isosurface.Isosurface(workspace, cutoff, flag_closed_edges, flag_gaussian)[source]
Bases:
object
- pumapy.utilities.isosurface.generate_isosurface(workspace, cutoff, flag_closed_edges=True, flag_gaussian=False)[source]
Generation of isosurface based on cutoff provided
- Parameters
workspace (pumapy.Workspace or numpy.ndarray) – domain
cutoff ((int, int)) – specify cutoff to binarize material
flag_closed_edges (bool) – close edges of surfaces on the boundaries
flag_gaussian (bool) – apply Gaussian filter before generating surface
- Returns
triangulated surface
- Return type
pumapy.utilities.logger
- class pumapy.utilities.logger.Colors[source]
Bases:
object
- BOLD = '\x1b[1m'
- ENDC = '\x1b[0m'
- FAIL = '\x1b[91m'
- HEADER = '\x1b[95m'
- OKBLUE = '\x1b[94m'
- OKCYAN = '\x1b[96m'
- OKGREEN = '\x1b[92m'
- UNDERLINE = '\x1b[4m'
- WARNING = '\x1b[93m'
pumapy.utilities.timer
pumapy.utilities.workspace
- class pumapy.utilities.workspace.Workspace(**kwargs)[source]
Bases:
object
- apply_mask(mask, apply_to_orientation=False)[source]
Apply mask of same size as the matrix by leaving the mask’s 1s unchanged and setting mask’s 0s to 0
- Parameters
mask (np.ndarray) – array of type bool with same size as matrix
apply_to_orientation (bool) – specifying whether the mask is to be applied to the orientation (if present)
- Returns
None
- Example
>>> import pumapy as puma >>> ws = puma.Workspace.from_shape_value_vector((10, 10, 10), 1, (0.4, 2, 5)) >>> mask = np.random.randint(255, size=(10, 10, 10)) > 100 >>> ws.apply_mask(mask, apply_to_orientation=True) >>> # puma.render_volume(ws, style='edges') # to visualize it
- binarize(threshold)[source]
Binarize the workspace according to threshold, inclusive for higher range set to 1, lower to 0
- Parameters
threshold (int) – grayscale value dividing the domain into 0s and 1s (threshold turns into 1)
- Returns
None
- Example
>>> import pumapy as puma >>> ws_fiberform = puma.import_3Dtiff(puma.path_to_example_file("200_fiberform.tif"), 1.3e-6) Importing ... >>> ws2 = ws_fiberform.copy() >>> ws2.binarize(100) >>> # puma.compare_slices(ws_fiberform, ws2) # to visualize it
- binarize_range(ones_cutoff)[source]
Binarize the workspace according to range within cutoff, inclusive for cutoff ints set to 1, rest to 0
- Parameters
ones_cutoff ((int, int)) – convert a range of grayscale values specified by the cutoff into 1s, rest into 0s
- Returns
None
- Example
>>> import pumapy as puma >>> ws_fiberform = puma.import_3Dtiff(puma.path_to_example_file("200_fiberform.tif"), 1.3e-6) Importing ... >>> ws2 = ws_fiberform.copy() >>> ws2.binarize_range((100, 255)) >>> # puma.compare_slices(ws_fiberform, ws2) # to visualize it
- copy()[source]
Create a copy of the workspace
- Returns
copy of workspace
- Return type
pumapy.Workspace
- create_orientation()[source]
Create orientation field of the same size as the matrix
- Returns
None
- Example
>>> import pumapy as puma >>> ws = puma.Workspace.from_shape((10, 10, 10)) >>> ws.create_orientation()
- classmethod from_array(nparray)[source]
Generate workspace matrix from numpy array.
- Parameters
nparray (np.ndarray) – array of shape (X,Y,Z) to be assigned to the matrix variable. NB: array is turned into type uint16
- Returns
new workspace
- Return type
pumapy.Workspace
- Example
>>> import pumapy as puma >>> array = np.random.randint(5, size=(10, 10, 10)) >>> ws = puma.Workspace.from_array(array) >>> # puma.render_volume(ws, style='edges') # to visualize it
- classmethod from_shape(shape, orientation=False)[source]
Generate workspace from shape, all matrix value set to zero.
- Parameters
shape ((int, int, int)) – shape of workspace to be created
orientation (bool) – specify if workspace contains orientation
- Returns
new workspace
- Return type
pumapy.Workspace
- Example
>>> import pumapy as puma >>> ws = puma.Workspace.from_shape((10, 11, 12)) >>> # puma.render_volume(ws, style='edges') # to visualize it
- classmethod from_shape_value(shape, value, orientation=False)[source]
Generate workspace from shape, all matrix values set to the value passed.
- Parameters
shape ((int, int, int)) – shape of workspace to be created
value (int) – value to be assigned to the matrix variable
orientation (bool) – specify if workspace contains orientation
- Returns
new workspace
- Return type
pumapy.Workspace
- Example
>>> import pumapy as puma >>> ws = puma.Workspace.from_shape_value((20, 31, 212), 1) >>> # puma.render_volume(ws, style='edges') # to visualize it
- classmethod from_shape_value_vector(shape, value, vector)[source]
Generate workspace from shape, all matrix and orientation set to the values passed.
- Parameters
shape ((int, int, int)) – shape of workspace to be created
value (int) – value to be assigned to the matrix variable
vector ((float, float, float)) – vector to be assigned to the orientation variable
- Returns
new workspace with orientation
- Return type
pumapy.Workspace
- Example
>>> import pumapy as puma >>> ws = puma.Workspace.from_shape_value_vector((5, 6, 2), 1, (0.4, 2, 5)) >>> # puma.render_orientation(ws) # to visualize it
- classmethod from_shape_vector(shape, vector)[source]
Generate workspace from shape, all orientation vectors set to the vector passed.
- Parameters
shape ((int, int, int)) – shape of workspace to be created
vector ((float, float, float)) – vector to be assigned to the orientation variable
- Returns
new workspace with orientation
- Return type
pumapy.Workspace
- Example
>>> import pumapy as puma >>> ws = puma.Workspace.from_shape_vector((5, 6, 2), (0.4, 2, 5)) >>> # puma.render_orientation(ws) # to visualize it
- get_shape()[source]
Return shape of domain
- Returns
shape of domain (matrix)
- Return type
(int, int, int)
- orientation_magnitude()[source]
Return orientation vector’s magnitude
- Returns
orientation field magnitude
- Return type
np.ndarray
- porosity(cutoff=(0, 0), display=False)[source]
Compute porosity of domain
- Parameters
cutoff ((int, int)) – void cutoff
display (bool) – print result
- Returns
volume fraction
- Return type
float
- Example
>>> import pumapy as puma >>> ws = puma.import_3Dtiff(puma.path_to_example_file("100_fiberform.tif"), 1.3e-6) Importing ... >>> ws.porosity(cutoff=(0, 89), display=True) Volume Fraction for cutoff (0, 89): ...
- rescale(scale, segmented, anti_aliasing=True, interpolation_order=1)[source]
Rescale both matrix and orientation (if present) by rescaling the content by a specified factor
- Parameters
scale (float) – specifying the scaling factor
segmented (bool) – specifying whether the domain is already segmented (True) or grayscales (False)
anti_aliasing (bool) – if aliasing is to be prevented applying a Gaussian filter to smooth before scaling. If domain is segmented, automatically set to False in order to preserve domain
interpolation_order (int) – order of the interpolation spline used. For segmented, it is enforced to be 0, which is ‘nearest neighbor’ to preserve the segmentation
- Returns
None
- Example
>>> import pumapy as puma >>> ws_fiberform = puma.import_3Dtiff(puma.path_to_example_file("200_fiberform.tif"), 1.3e-6) Importing ... >>> ws2 = ws_fiberform.copy() >>> ws2.rescale(0.5, segmented=False) Rescaled workspace size: (100, 100, 100) >>> # puma.compare_slices(ws_fiberform, ws2) # to visualize it, pay attention to the shape
- resize(shape, segmented, anti_aliasing=True, interpolation_order=1)[source]
Resize both matrix and orientation (if present) by rescaling the content to specified size
- Parameters
shape ((int, int, int)) – shape of workspace to be resized
segmented (bool) – specifying whether the domain is already segmented (True) or grayscales (False)
anti_aliasing (bool) – if aliasing is to be prevented applying a Gaussian filter to smooth before scaling. If domain is segmented, automatically set to False in order to preserve domain
interpolation_order (int) – order of the interpolation spline used. For segmented, it is enforced to be 0,which is ‘nearest neighbor’ to preserve the segmentation
- Returns
None
- Example
>>> import pumapy as puma >>> ws_fiberform = puma.import_3Dtiff(puma.path_to_example_file("200_fiberform.tif"), 1.3e-6) Importing ... >>> ws2 = ws_fiberform.copy() >>> ws2.resize((100, 200, 200), segmented=False) >>> # puma.compare_slices(ws_fiberform, ws2) # to visualize it
- resize_new_matrix(shape, value=None)[source]
Resize matrix numpy array
- Parameters
shape ((int, int, int)) – shape of workspace to be resized
value (int) – value to be assigned to the new resized matrix variable
- Example
>>> import pumapy as puma >>> ws = puma.Workspace() >>> ws.resize_new_matrix((10, 10, 10), value=3) >>> # puma.render_volume(ws, style='edges') # to visualize it
- resize_new_orientation(shape, orientation_value=None)[source]
Resize orientation numpy array
- Parameters
shape ((int, int, int)) – shape of workspace to be resized
orientation_value ((float, float, float)) – vector to be assigned to the new resized orientation variable
- Example
>>> import pumapy as puma >>> ws = puma.Workspace() >>> ws.resize_new_orientation((10, 10, 10), orientation_value=(1., 0., 0.)) >>> # puma.render_orientation(ws) # to visualize it
- rotate(degrees, around_axis, reshape=True, boundary_mode='reflect', apply_to_orientation=True)[source]
Rotate domain by specified degrees
- Parameters
degrees (float) – degrees to rotate domain
around_axis (string) – specify around what axis to perform the rotation. It can be ‘x’, ‘y’ or ‘z’
reshape (bool) – specify whether to reshape the domain (and therefore contain every voxel - reshape=True) or keep its original size (reshape=False)
boundary_mode (string) – specifying what to do with the boundaries. Options: ‘reflect’, ‘constant’, ‘nearest’, ‘mirror’, ‘wrap’
apply_to_orientation (bool) – specify whether to apply rotation to the orientation, if present
- Returns
None
- Example
>>> import pumapy as puma >>> ws_fiberform = puma.import_3Dtiff(puma.path_to_example_file("200_fiberform.tif"), 1.3e-6) Importing ... >>> ws_copy = ws_fiberform.copy() >>> ws_copy.rotate(45, 'z', reshape=False, boundary_mode='reflect') >>> # puma.compare_slices(ws_fiberform, ws_copy) # to visualize it >>> ws_copy = ws_fiberform.copy() >>> ws_copy.rotate(45, 'z', reshape=True, boundary_mode='constant') >>> # puma.compare_slices(ws_fiberform, ws_copy) # to visualize it >>> ws_copy = ws_fiberform.copy() >>> ws_copy.rotate(45, 'z', reshape=True, boundary_mode='reflect') >>> # puma.compare_slices(ws_fiberform, ws_copy) # to visualize it
- set(matrix_value=None, orientation_value=None)[source]
Set all elements in matrix equal to value (and orientation to vectorvalue is passed)
- Parameters
matrix_value (int) – value to fill to the matrix variable. NB this value will be turned into np.uint16
orientation_value (((float, float, float))) – vector to fill to the orientation variable
- Returns
None
- Example
>>> import pumapy as puma >>> ws = puma.Workspace.from_shape_value((10, 10, 10), 5) >>> ws.set(matrix_value=4)
- set_material_id(cutoff, value)[source]
Threshold the workspace according to cutoff (i.e. tuple with inclusive range to set)
- Parameters
cutoff ((int, int)) – convert a range of grayscale values specified by the cutoff into an single ID number
value (int) – ID number to assign to range
- Returns
None
- Example
>>> import pumapy as puma >>> ws_fiberform = puma.import_3Dtiff(puma.path_to_example_file("200_fiberform.tif"), 1.3e-6) Importing ... >>> ws2 = ws_fiberform.copy() >>> ws2.set_material_id((0, 100), 0) # NB the order of these operations is important! >>> ws2.set_material_id((100, 255), 1) # this is why binarize and binarize_range should be preferred >>> # puma.compare_slices(ws_fiberform, ws2) # to visualize it
- set_matrix(nparray)[source]
Set matrix with numpy array
- Parameters
nparray (np.ndarray) – array of shape (X,Y,Z) to be assigned to the matrix variable
- Returns
None
- Example
>>> import pumapy as puma >>> ws = puma.Workspace() >>> nparray = np.random.randint(5, size=(10, 10, 10)) >>> ws.set_matrix(nparray) # equivalent to ws.matrix = nparray.copy().astype(np.uint16) >>> # puma.render_volume(ws, style='edges') # to visualize it
- set_orientation(nparray)[source]
Set orientation with numpy array
- Parameters
nparray (np.ndarray) – array of shape (X,Y,Z, 3) to be assigned to the orientation variable
- Returns
None
- Example
>>> import pumapy as puma >>> ws = puma.Workspace() >>> ws.set_orientation(np.random.rand(10, 10, 10, 3)) >>> # puma.render_orientation(ws, solid_color=None) # to visualize it
- set_voxel_length(voxel_length)[source]
Set voxel size, which by default is set to 1e-6
- Parameters
voxel_length (float) – size of a voxel side
- Returns
None
- Example
>>> import pumapy as puma >>> array = np.random.randint(5, size=(10, 10, 10)) >>> ws = puma.Workspace.from_array(array) >>> ws.set_voxel_length(1) # equivalent to ws.voxel_length = 1 >>> # puma.render_volume(ws, style='edges') # to visualize it