pumapy.utilities

pumapy.utilities.example_files

pumapy.utilities.example_files.list_example_files()

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)

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.check_ws_cutoff(workspace, cutoff)

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)

Compute an estimate of the extra maximum memory required to run a specified material property on a domain

Parameters

material_property – property to estimate, options:

‘anisotropic_conductivity’, ‘isotropic_conductivity’, ‘tortuosity’, ‘elasticity’, ‘permeability’ :type material_property: string :param workspace_shape: size of the domain to compute :type workspace_shape: (int, int, int) :param solver_type: type of solver, options: ‘direct’, ‘iterative’ :type solver_type: string :param need_to_orient: domain with orientation (needed for anisotropic conductivity and elasticity) :type need_to_orient: bool :param mf: using matrix-free construction of the system (needed for FE methods) :type mf: bool :return: number of Bytes :rtype: int

pumapy.utilities.generic_checks.greater_than_exc(var, lim, var_name)

pumapy.utilities.generic_checks.greater_than_inc(var, lim, var_name)

pumapy.utilities.generic_checks.less_than_exc(var, lim, var_name)

pumapy.utilities.generic_checks.less_than_inc(var, lim, var_name)

pumapy.utilities.generic_checks.range_exc(var, var_range, var_name)

pumapy.utilities.generic_checks.range_inc(var, var_range, var_name)

pumapy.utilities.generic_checks.set_random_seed(seed)

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.generic_checks.size_check(size)

pumapy.utilities.isosurface

class pumapy.utilities.isosurface.Isosurface(workspace, cutoff, flag_closed_edges, flag_gaussian)

Bases: object

apply_gaussian()

buffer_matrix()

compute()

error_check()

flip_matrix()

log_input()

log_output()

class pumapy.utilities.isosurface.TriMesh

Bases: object

copy(other)

create_mesh()

save(filename, binary=True)

pumapy.utilities.isosurface.generate_isosurface(workspace, cutoff, flag_closed_edges=True, flag_gaussian=False)

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

TriMesh

pumapy.utilities.logger

class pumapy.utilities.logger.Colors

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'

class pumapy.utilities.logger.Logger

Bases: object

log_bool(var_name, val)

log_item(val)

log_line(val)

log_section(name)

log_value(var_name, val)

new_line()

print_error()

write_log()

pumapy.utilities.logger.print_warning(warning_text)

pumapy.utilities.timer

class pumapy.utilities.timer.Timer

Bases: object

current = 0

elapsed()

print_elapsed(msg='')

reset()

start()

pumapy.utilities.workspace

class pumapy.utilities.workspace.Workspace(**kwargs)

Bases: object

apply_mask(mask, apply_to_orientation=False)

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

average()

Return average of domain

Returns

grayscale average

Return type

float

binarize(threshold)

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)

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

Create a copy of the workspace

Returns

copy of workspace

Return type

pumapy.Workspace

create_orientation()

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)

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)

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)

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)

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)

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

Return shape of domain

Returns

shape of domain (matrix)

Return type

(int, int, int)

get_size()

Return size

Returns

number of voxels

Return type

int

len_x()

Return x dimension length

Returns

number of voxels in x dimension

Return type

int

len_y()

Return y dimension length

Returns

number of voxels in y dimension

Return type

int

len_z()

Return z dimension length

Returns

number of voxels in z dimension

Return type

int

max()

Return maximum of domain

Returns

maximum

Return type

int

min()

Return minimum of domain

Returns

minimum

Return type

int

orientation_magnitude()

Return orientation vector’s magnitude

Returns

orientation field magnitude

Return type

np.ndarray

porosity(cutoff=(0, 0), display=False)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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

show_matrix()

Print content of matrix domain’s variable

show_orientation(dec=1)

Print content of orientation domain’s variable

unique_values()

Return unique values in domain matrix variable

Returns

unique values

Return type

np.ndarray

unique_values_counts()

Return unique values and their counts in domain matrix variable

Returns

unique values and counts

Return type

(np.ndarray, int)