API reference
This section contains the API reference and usage information for ciclope.
ciclope core modules
Voxel Finite Elements
Ciclope module for voxel Finite Element model generation
- ciclope.core.voxelFE.matpropdictionary(proplist)
Compose dictionary of material properties and property mapping GV ranges.
Parameters
- proplist
List of material property files followed by the corresponding Gray Value range for material mapping.
Returns
- matpropdict
Dictionary of material properties for material property mapping: matprop = {
“file”: [“prop.inp”, “property_temp_bone.inp”, …], “range”: [[250, 255], [0, 250], …],
}
- ciclope.core.voxelFE.mesh2voxelfe(mesh, templatefile, fileout, matprop=None, keywords=['NSET', 'ELSET'], eltype='C3D8', matpropbits=8, refnode=None, verbose=False)
Generate ABAQUS voxel Finite Element (FE) input file from 3D Unstructured Grid mesh data. The file written is an input file (.INP) in ABAQUS syntax that can be solved using ABAQUS or CALCULIX. The user can define a material mapping strategy for the conversion of local GVs to local material properties in the FE model. Material mapping laws are defined in separate template file(s) (see “prop.inp” and “property_temp_bone.inp” for examples). Boundary conditions, analysis type and output requests are defined in a separate template file (see “tmp.inp” for an example). Info on analysis definition at: https://abaqus-docs.mit.edu/2017/English/SIMACAECAERefMap/simacae-m-Sim-sb.htm#simacae-m-Sim-sb
Parameters
- meshmeshio
Unstructured grid mesh.
- templatefilestr
Analysis template file.
- fileoutstr
Output .INP file.
- matpropdict
Dictionary of material properties for material property mapping: matprop = {
“file”: [“prop.inp”, “property_temp_bone.inp”, …], “range”: [[250, 255], [0, 250], …],
}
- keywordsstr
SUPPORTED ABAQUS KEYWORDS:
For a list of all Abaqus keywords and their description visit: https://abaqus-docs.mit.edu/2017/English/SIMACAECAERefMap/simacae-c-gen-kwbrowser.htm#simacae-c-gen-kwbrowser__simacae-gen-xsl-U
- ‘NSET’:
Create boundary node sets. (Default = ON) If ‘NSET’ is specified, the following node sets are created:
NODES_X0: Nodes on WEST (X-) surface of 3D model.
NODES_X1: Nodes on EAST (X+) surface of 3D model.
NODES_Y0: Nodes on SOUTH (Y-) surface of 3D model.
NODES_Y1: Nodes on NORTH (Y+) surface of 3D model.
NODES_Z0: Nodes on BOTTOM (Z-) surface of 3D model.
NODES_Z1: Nodes on TOP (Z+) surface of 3D model.
NODES_X0Y0Z0: 2 nodes on (0,0,0) model corner.
NODES_X0Y0Z1: 2 nodes on (0,0,1) model corner.
These node sets are available for boundary conditions definition.
- ‘ELSET’:
Create boundary element sets. (Default = ON) If ‘ELSET’ is specified, the following element sets are created:
ELEMS_X0: Elements of WEST (X-) surface of 3D model.
ELEMS_X1: Elements of EAST (X+) surface of 3D model.
ELEMS_Y0: Elements of SOUTH (Y-) surface of 3D model.
ELEMS_Y1: Elements of NORTH (Y+) surface of 3D model.
ELEMS_Z0: Elements of BOTTOM (Z-) surface of 3D model.
ELEMS_Z1: Elements of TOP (Z+) surface of 3D model.
- ‘PROPERTY’:
Define an external material mapping law from template file. (Default = None) Use in combination with ‘matprop’ dictionary of material property files and corresponding GV ranges for the material mapping.
- eltypestr
FE element type. The default is eight-node brick element (C3D8 and F3D8). See CalculiX node convention (Par. 6.2.1) at: http://www.dhondt.de/ccx_2.15.pdf
- matpropbitsint
Bit depth for material mapping.
- refnode
Reference node coordinates [REF_NODE_x, REF_NODE_y, REF_NODE_z] for kinematic coupling.
- verbosebool
Activate verbose output.
- ciclope.core.voxelFE.vol2h5ParOSol(voldata, fileout, topDisplacement, voxelsize=1, poisson_ratio=0.3, young_modulus=18000.0, topHorizontaFixedlDisplacement=True, locking_strategy='plane', plane_lock_num=1, node_level_lock_num=1, verbose=False)
Generate ParOSol HDF5 (.h5) input file from 3D volume data. Before to generate ParOSol HDF5 file, the Bounding BOX (bbox class) limits the input binary image. Info on HDF5 file type for ParOSol solver at: https://github.com/reox/parosol-tu-wien/blob/master/doc/file_format.md
Parameters
- voldatandarray
3D voxel data.
- fileoutstr
Path to output .h5 file.
- topDisplacementfloat
Displacement magnitude applied on top boundary (Z1).
- voxelsizefloat or array
3D model voxelsize.
- poisson_ratiofloat
Poisson’s ratio for material.
- young_modulusfloat
Young’s modulus [MPa] to scale voxel values.
- topHorizontaFixedlDisplacementbool
If True, fix X and Y displacements at top; else fix only Z.
- locking_strategystr
“plane”: fix nodes in first/last plane_lock_num layers of voxels. “exact”: fix nodes exactly at bottom/top node_level_lock_num layers.
- plane_lock_numint
Number of voxel planes for “plane” strategy where boundary conditions (BCs) are applied.
- node_level_lock_numint
Number of node levels for “exact” strategy where boundary conditions (BCs) are applied.
- verbosebool
Enable detailed logging.
- ciclope.core.voxelFE.vol2ugrid(voldata, voxelsize=[1, 1, 1], GVmin=0, plane_lock_num=1, node_level_lock_num=1, locking_strategy='plane', refnodes=False, verbose=False)
Generate unstructured grid mesh from 3D volume data.
Parameters
- voldatandarray
3D voxel data.
- voxelsizelist or array
3D model voxelsize.
- GVminint or float
Minimum Grey Value considered for meshing. By default, GVmin=0: all zeroes are considered background.
- plane_lock_numint
Number of volume slices to consider for locking in “plane” mode.
- node_level_lock_numint
Number of node levels to consider for locking in “exact” mode.
- locking_strategystr
- Strategy for node locking:
“plane” locks the entire strip of cells (default),
“exact” locks nodes exactly at specific levels.
- refnodesbool
Return dictionary of reference nodes on the model boundaries. Even if this option is not activated, the returned mesh will contain the following nodes and elements sets:
NODES_X0: Nodes on WEST (X-) surface of 3D model.
NODES_X1: Nodes on EAST (X+) surface of 3D model.
NODES_Y0: Nodes on SOUTH (Y-) surface of 3D model.
NODES_Y1: Nodes on NORTH (Y+) surface of 3D model.
NODES_Z0: Nodes on BOTTOM (Z-) surface of 3D model.
NODES_Z1: Nodes on TOP (Z+) surface of 3D model.
NODES_X0Y0Z0: 2 nodes on (0,0,0) model corner.
NODES_X0Y0Z1: 2 nodes on (0,0,1) model corner.
ELEMS_X0: Elements of WEST (X-) surface of 3D model.
ELEMS_X1: Elements of EAST (X+) surface of 3D model.
ELEMS_Y0: Elements of SOUTH (Y-) surface of 3D model.
ELEMS_Y1: Elements of NORTH (Y+) surface of 3D model.
ELEMS_Z0: Elements of BOTTOM (Z-) surface of 3D model.
ELEMS_Z1: Elements of TOP (Z+) surface of 3D model.
- verbosebool
Activate verbose output.
Returns
- meshmeshio.Mesh
Unstructured grid mesh.
- refnodes_dictdict (optional)
centroids on the model boundaries (X0, X1, Y0, Y1, Z0, Z1) if refnodes is True.
Tetrahedra Finite Elements
Ciclope module for tetrahedra Finite Element model generation
- ciclope.core.tetraFE.add_midpoints_to_mesh(mesh, sorted_edges)
Add midpoints of edges to the mesh and update edge-to-midpoint mapping.
This function computes the midpoints of the given edges, adds these midpoints to the mesh’s points, and updates a dictionary that maps each edge to its corresponding midpoint index in the mesh.
Parameters
- meshMesh
The mesh object containing points and cells.
- sorted_edgeslist of tuple of int
A list of sorted edges, where each edge is represented as a tuple containing two vertex indices (sorted in ascending order).
Returns
- edge_to_midpointdict of tuple of int to int
A dictionary mapping each edge (represented as a tuple of two vertex indices) to the index of its midpoint in the mesh’s points array.
- ciclope.core.tetraFE.cgal_mesh(bwimage, voxelsize, meshtype='both', max_facet_distance=0.0, max_cell_circumradius=0.0)
Generate mesh of from binary volume data using CGAL. The mesh is generated using the PyGalmesh module. For more info visit: https://github.com/nschloe/pygalmesh#volume-meshes-from-surface-meshes The pygalmesh.generate_from_array method returns a mesh containing both a cells set of tetrahedra (volume mesh) and a cells set of triangles (shell mesh). The parameter ‘meshtype’ is used to control which type of mesh is returned.
Parameters
- bwimage
Binary image.
- voxelsizefloat
Image voxelsize.
- meshtypestr
‘triangle’: Outer mesh (shell) of triangles. ‘tetra’: Volume mesh of tetrahedra. ‘both’: Both shell and volume cells sets.
- max_facet_distancefloat
CGAL parameter.
- max_cell_circumradiusfloat
CGAL parameter.
Returns
- meshmeshio
Mesh data.
- ciclope.core.tetraFE.check_cgal_params(max_facet_distance, max_cell_circumradius, voxelsize)
Check CGAL mesher parameters. # https://github.com/nschloe/pygalmesh#volume-meshes-from-surface-meshes
Parameters
max_facet_distance max_cell_circumradius
- voxelsizefloat
Image voxel size.
Returns
max_facet_distance : float max_cell_circumradius : float
- ciclope.core.tetraFE.create_new_cells(mesh, edge_to_midpoint)
Create a new list of tetrahedral cells with midpoint nodes.
This function generates new cells for the mesh by adding midpoint nodes to the edges of existing tetrahedral cells. Each new cell includes the original vertices and the additional midpoint nodes, resulting in a 10-node tetrahedral element (tetra10).
Parameters
- meshMesh
The mesh object containing cells and points.
- edge_to_midpointdict of tuple of int to int
A dictionary mapping each edge (represented as a tuple of two vertex indices) to the index of its corresponding midpoint in the mesh’s points array.
Returns
- new_cellslist of meshio.CellBlock
A list containing the new cells with the added midpoint nodes. Each cell is represented as a meshio.CellBlock object with ‘tetra10’ type, and the data attribute contains a list of vertex indices, including the midpoints.
- ciclope.core.tetraFE.find_unique_edges(mesh)
Find unique edges in a tetrahedral mesh.
This function iterates through all the tetrahedral cells in the mesh and extracts unique edges by considering each pair of vertices in the tetrahedra. Each edge is represented as a tuple of two sorted vertex indices.
Parameters
- meshMesh
A mesh object that contains cells, where each cell represents a tetrahedron.
Returns
- unique_edgesset of tuple of int
A set containing unique edges, where each edge is represented as a tuple of two vertex indices (sorted in ascending order). Each tuple represents an undirected edge between two vertices in the mesh.
- ciclope.core.tetraFE.mesh2tetrafe(meshdata, templatefile, fileout, keywords=['NSET', 'ELSET'], float_fmt='.6e', bound_tol=None, inclined=False, plane_norm=None, plane_bottom_origin=None, plane_top_origin=None, verbose=False)
Generate an ABAQUS tetrahedral Finite Element (FE) input file from a 3D mesh, supporting both straight and inclined samples.
This function converts a 3D mesh (typically created with meshio) into an ABAQUS input file (.inp), suitable for simulations with ABAQUS or CalculiX. It identifies boundary node sets (NSET) and, optionally, boundary element sets (ELSET) based on geometric criteria. The function also appends analysis definitions and boundary condition specifications to the output file by copying from a user-provided template.
- The function supports two use cases:
Default (straight): boundary identification is based on Cartesian limits (X0/X1, Y0/Y1, Z0/Z1).
Inclined: boundary identification is performed relative to two user-defined planes (bottom and top).
Parameters
- meshdatameshio.Mesh
Mesh data including node coordinates, element connectivity, and optionally cell data (e.g., region labels). Typically obtained by reading a mesh file with meshio.
- templatefilestr
Path to the ABAQUS template file containing analysis definitions (e.g., simulation steps, boundary conditions). This content is appended to the end of the generated .inp file.
- fileoutstr
Path to the output file (.inp) where the ABAQUS mesh and boundary sets will be written.
- keywordslist of str, optional
- Specifies which boundary sets to generate. Supported values:
- ‘NSET’: Create node sets for model boundaries.
For straight samples: NODES_X0, NODES_X1, NODES_Y0, NODES_Y1, NODES_Z0, NODES_Z1
For inclined samples: NODES_Z0 (near bottom plane), NODES_Z1 (near top plane)
In both cases: example corner node sets NODES_X0Y0Z0 and NODES_X0Y0Z1 are included.
‘ELSET’: Create element sets corresponding to the node sets, plus additional sets based on medit:ref if available.
- float_fmtstr, optional
Format string for floating-point numbers when writing the ABAQUS file (default: ‘.6e’).
- verbosebool, optional
If True, enables detailed logging output during execution (default: False).
- bound_tolfloat, list of float, or np.array, optional
- Tolerance used to determine if a node is located on a boundary.
If None (default), tolerance is set to 1% of the model’s extent in each direction.
If a float, the same tolerance is applied to all directions.
If a list or array of 3 values, each value applies to the corresponding axis.
- inclinedbool, optional
If True, boundary detection is based on two inclined planes defined by the user (default: False). If False, boundaries are determined based on axis-aligned min/max bounds.
- plane_normnp.array, shape (3,), optional
Normal vector of the planes used when inclined=True.
- plane_bottom_originnp.array, shape (3,), optional
A point lying on the bottom reference plane when inclined=True.
- plane_top_originnp.array, shape (3,), optional
A point lying on the top reference plane when inclined=True.
Returns
- None
The function writes the ABAQUS .inp file to the location specified by fileout. No value is returned.
Notes
- The resulting ABAQUS input file consists of two main parts:
The mesh definition section: nodes, elements, and boundary sets written in ABAQUS format.
The analysis definition section: copied from the provided template file and appended to the end.
Example
# Straight sample: mesh2tetrafe(mesh, “template.inp”, “output.inp”)
# Inclined sample: mesh2tetrafe(mesh, “template.inp”, “output.inp”, inclined=True,
plane_norm=np.array([0, 0, 1]), plane_bottom_origin=np.array([0, 0, 0]), plane_top_origin=np.array([0, 0, 10]))
- ciclope.core.tetraFE.shell_mesh(bwimage, method='pymcubes', voxelsize=[1.0, 1.0, 1.0], max_facet_distance=0.0, max_cell_circumradius=0.0)
Generate outer shell mesh of triangles from binary volume data. The mesh is generated using the PyMCubes module and the smooth function contained in it: https://github.com/pmneila/PyMCubes
Alternatively, the marching cube algorithm from the scikit-image python module can be used: https://scikit-image.org/docs/dev/api/skimage.measure.html?highlight=marching#skimage.measure.marching_cubes
Parameters
- bwimage
Binary image.
- methodstr
‘pymcubes’: PyMCubes module. ‘marching_cubes’: scikit-image’s marching cube algorithm. ‘pygalmesh’: pygalmesh module (CGAL).
- voxelsizefloat
Image voxelsize.
- max_facet_distancefloat
CGAL parameter.
- max_cell_circumradiusfloat
CGAL parameter.
Returns
- vertices
Mesh vertices.
- triangles
Mesh triangles.
- shellmeshmeshio
Mesh data.
ciclope utilities
Data pre-processing
Ciclope image preprocessing module
- ciclope.utils.preprocess.add_cap(I, cap_thickness, cap_val)
Add caps to 3D image. Caps are added on both ends along the Z-direction (first dataset dimension). The thickness and color (Grey Value) of the added caps can be specified.
Parameters
- I
3D data. Zeroes as background.
- cap_thicknessint
Cap thickness in pixels.
- cap_valfloat
Cap grey value.
Returns
- I_cap
Image with caps added.
- ciclope.utils.preprocess.centerofmass(bwimage)
Center Of Mass (COM) of binary image.
Parameters
- bwimage: bool
Binary image. Can be 2D and 3D.
Returns
- cmassx_array
X-coordinate array of the COM. If input is 3D, an array of the slicewise COMs is returned.
- cmassy_array
Y-coordinate array of the COM.
- ciclope.utils.preprocess.convert_bmp_to_tiff(input_folder, tiff_folder)
Convert BMP images to TIFF format and save them.
Parameters: - input_folder (str): The path to the input folder containing BMP images. - tiff_folder (str): The path to the output folder where TIFF images will be saved.
Returns: - str: The path to the folder where TIFF images are saved.
- ciclope.utils.preprocess.crop_and_resize_images(input_folder, output_folder, diameter, pixel_spacing_mm=0.0195, res_X=257, res_Y=257)
Crop and resize images based on a provided diameter.
Parameters: - input_folder (str): The path to the input folder containing the images. - output_folder (str): The path to the output folder where cropped and resized images will be saved. - diameter (float): The diameter in millimeters for cropping and resizing. - pixel_spacing_mm (float, optional): The pixel spacing in millimeters, used to convert the diameter into pixels. - res_X (int, optional): The target width in pixels for resizing. - res_Y (int, optional): The target height in pixels for resizing.
Returns: None
- ciclope.utils.preprocess.crop_images(input_folder, output_folder, diameter, pixel_spacing_mm=0.0195)
Crop images based on a provided diameter.
Parameters: - input_folder (str): The path to the input folder containing the images. - output_folder (str): The path to the output folder where cropped images will be saved. - diameter (float): The diameter in millimeters for cropping. - pixel_spacing_mm (float, optional): The pixel spacing in millimeters, used to convert the diameter into pixels. Default is 0.0195 mm.
Returns: None
- ciclope.utils.preprocess.embed(I, embed_depth, embed_dir, embed_val=None, pad=0, makecopy=False)
Add embedding to 3D image. Direction and depth of the embedded region should be given. Zeroes in the input image is considered to be background.
Parameters
- I
3D data. Zeroes as background.
- embed_depthint
Embedding depth in pixels.
- embed_dirstr
Embedding direction. Can be “-x”, “+x”, “-y”, “+y”, “-z”, or “+z”.
- embed_valfloat
Embedding grey value.
- pad = int
Padding around bounding box of embedded area.
- makecopybool
Make copy of the input image.
Returns
- I
Embedded image. Same size as the input one.
- BW_embedding
BW mask of the embedding area.
- ciclope.utils.preprocess.fill_voids(I, fill_val=None, makecopy=False)
Fill voids within color image with given value.
Parameters
- I
Input color image.
- fill_val
Filling value.
- makecopybool
Make copy of input image.
Returns
- I_filled
Filled image.
- ciclope.utils.preprocess.invert_images(input_folder, output_folder)
Invert pixel values in images and save them.
Parameters: - input_folder (str): The path to the input folder containing the images. - output_folder (str): The path to the output folder where inverted images will be saved.
Returns: None
- ciclope.utils.preprocess.periosteummask(bwimage, closepixels=10, closevoxels=0, remove_objects_smaller_than=None, removeunconn=True, verbose=False)
Binary mask of periosteum (whole bone).
Parameters
- bwimagebool
Binary image. Can be 2D or 3D.
- closepixelsint
Radius of DISK structuring element for 2D image closing.
- closevoxelsint
Radius of CUBE structuring element for final 3D image closing.
- remove_objects_smaller_thanint
Remove objects smaller than given size before periosteum mask calculation.
- removeunconnbool
Remove unconnected clusters of pixels/voxels from the calculated mask.
- verbosebool
Activate verbose output.
Returns
- perimaskbool
Binary mask of the whole bone (periosteum mask).
- ciclope.utils.preprocess.remove_largest(bwimage)
Remove largest cluster of voxels in binary image.
Parameters
- bwimage
Binary image.
Returns
- bwcluster
Binary image in which the largest cluster of voxels is removed.
- ciclope.utils.preprocess.remove_unconnected(bwimage)
Remove all unconnected voxels. Returns a binary of the largest connected cluster.
Parameters
- bwimage
Binary image.
Returns
- bwcluster
Binary image of the largest connected cluster of voxels.
- ciclope.utils.preprocess.replace_ElType_ref(filename, old_word, new_word)
Replace element type word in a .inp file for correct input to Calculix.
This function reads a .inp file, replaces all instances of the specified old element type word with a new word, and writes the updated content back to the same file. This is useful for modifying finite element models for compatibility with Calculix or other finite element software.
Parameters
- filenamestr
The path to the .inp file that needs modification. This should include the full file name and path.
- old_wordstr
The word (typically an element type identifier) that is to be replaced in the file.
- new_wordstr
The word to replace the old word with. This should be the new element type or identifier that is compatible with Calculix or the desired software.
Returns
None
MicroCT reconstruction utilities
MicroCT image processing utilities.
- ciclope.utils.recon_utils.bbox(bw, pad=0, dsize=None, verbose=None)
Bounding BOX limits of input binary image.
Parameters
- bwbool
Binary image.
- padint
Add padding of given number of pixels to the BBOX limits.
- dsizeint
perform image close with disk structuring element of radius ‘dsize’ before calculating the BBOX.
- verbose
Activate verbose graphical output
Returns
- bbox_origin: int
Origin [row col (slice)] of the BBOX inscribing True values in input image bw.
- bbox_size: int
BBOX size [s_row s_col (s_slice)].
- ciclope.utils.recon_utils.crop(data_3D, crop_origin, crop_size)
Crop 3D image given crop origin and size.
Parameters
- data_3D
Input data.
- crop_origin[int, int, int]
Crop origin [Z,Y,X].
- crop_size[int, int, int]
Crop size [Z,Y,X].
Returns
- output
Cropped data.
- ciclope.utils.recon_utils.plot_midplanes(data_3D, slice_x=-1, slice_y=-1, slice_z=-1)
Plot orthogonal cross-sections through 3D dataset.
Parameters
- data_3D
Input 3D image data.
- slice_xint
X-slice number.
- slice_yint
Y-slice number.
- slice_zint
Z-slice number.
- ciclope.utils.recon_utils.plot_projections(data_3D, projection='max')
Plot orthogonal projections of 3D dataset.
Parameters
- data_3D
Input 3D image data.
- projectionstr
Projection method. Available choices are ‘max’, ‘min’.
- ciclope.utils.recon_utils.read_tiff_stack(filename, range=None, zfill=4)
Read stack of tiff files. Searches all files in parent folder and opens them as a stack of images.
Parameters
- filename
One of the stack images.
- range[int, int]
Control load slices range.
- zfillint
Number of leading zeros in file names.
TO DO:
check that folder contains only .TIFF files; skip the rest
- ciclope.utils.recon_utils.to01(data_3D)
Normalize data to 0-1 range.
Parameters
- data_3D
Input data.
Returns
- data_3Dfloat32
Normalized data.
- ciclope.utils.recon_utils.touint8(data_3D, range=None, quantiles=None, numexpr=True)
Normalize and convert data to uint8.
Parameters
- data_3D
Input data.
- range[float, float]
Control range for data normalization.
- quantiles[float, float]
Define range for data normalization through input data quantiles. If range is given this input is ignored.
- numexprbool
Use fast numerical expression evaluator for NumPy (memory expensive).
Returns
- outputuint8
Normalized data.
- ciclope.utils.recon_utils.writemidplanes(data_3D, fileout, slice_x=-1, slice_y=-1, slice_z=-1)
Plot orthogonal mid-planes through 3D dataset and save them as images. Uses pypng for writing .PNG files.
Parameters
- data
Input 3D image data.
- fileoutstr
Output .PNG image file name.
- slice_xint
X-slice number.
- slice_yint
Y-slice number.
- slice_zint
Z-slice number.
Post-processing of FE results
Ciclope postprocessing module
- ciclope.utils.postprocess.calculate_total_force(filename_dat)
Calculate the total force from a data file.
Parameters: - filename_dat (str): The path to the data file containing force components.
Returns: - float or None: The total force calculated from the data file, or None if an error occurs.
- ciclope.utils.postprocess.circular_masks_BVTV(L, diameter, pixel_spacing_mm)
Create circular masks and calculate BVTV.
Parameters
- Llist of numpy.ndarray
List of input slices.
- diameterfloat
Diameter of the circle.
- pixel_spacing_mmfloat
Pixel spacing in millimeters.
Returns
- circular_maskslist of numpy.ndarray
List of circular masks.
- BVTVfloat
Bone volume-to-total volume ratio.
- ciclope.utils.postprocess.count_fixed_displacements(file_path, slice_level)
Count the number of nodes fixed (bottom region) and nodes fixed with top_displacement (top region), based on voxel coordinates only.
Parameters
- file_pathstr
Path to the HDF5 file.
- slice_level: int
Number of planes locked at the top (just the nodes on the base of the voxels, not all nodes of the voxel planes)
Returns
- tuple of int
nodes_z0_count, nodes_z1_count
- ciclope.utils.postprocess.cyl_binary_mask2bvtv(mask: ndarray, voxel_size: float, radius: float, height: float) float
Calculates the BV/TV (Bone Volume/Total Volume) ratio of a trabecular bone sample.
- Parameters:
mask (np.ndarray): Binarized (3D) mask with 1 = bone, 0 = empty. voxel_size (float): Size of the voxel in mm. radius (float): Radius of the sample cylinder in mm. height (float): Height of the sample in mm.
- returns:
float: BV/TV expressed as a percentage.
- ciclope.utils.postprocess.paraview_plot(filein, fileout=None, slicenormal='XYZ', RepresentationType='Surface', Crinkle=False, ColorBy='S_Mises', Roll=0, ImageResolution=[1280, 960], TransparentBackground=True, ColorMap='Viridis (matplotlib)')
Plot field data using ParaView. ParaView must be installed and a link to its python library must be added to your system path.
Parameters
- fileinstr
Input data (VTK or other 3D ParaView file).
- fileoutstr
Output image file name.
- slicenormalstr
Any combination of ‘X’, ‘Y’, and ‘Z’. Default=’XYZ’.
- RepresentationTypestr
‘Surface’, ‘SurfaceWithEdges’, ‘Volume’, ‘Points’, ‘Feature Edges’, or ‘3D Glyphs’. Default=’Surface’.
- Crinklebool
Crinkle the slice. Default=False.
- ColorBystr
Field name for coloring. Default=’S_Mises’
- Rollint
View roll angle. Default=0.
- ImageResolutionint
Output image resolution [X, Y] in pixels. Default=[1280, 960].
- TransparentBackgroundbool
Transparent background. Default=True.
- Colormapstr
Default = Viridis.
- ciclope.utils.postprocess.plot_slice(renderView1, slice1Display, fileout, RepresentationType, colorby, Roll, ImageResolution, TransparentBackground, ColorMap)
Save plots using Paraview.
Parameters
renderView1 slice1Display fileout RepresentationType colorby Roll ImageResolution TransparentBackground ColorMap
- ciclope.utils.postprocess.reaction_forces(file_path, slice_level)
Compute reaction forces and mesh information from an HDF5 file, considering a region of nodes within a specified range of slices defined by slice_level.
The function identifies the nodes whose Z-coordinate falls within the range corresponding to the last slice_level slices at the top of the voxel grid, sums their nodal forces, and returns related quantities.
Parameters
- file_pathstr
Path to the HDF5 file containing mesh and solution data.
- slice_levelint
Number of voxel levels (just the nodes on the base of the voxels, not all nodes of the voxel planes) used to define the locked region for boundary conditions. The reaction forces are computed for all nodes within this region.
Returns
- dict
Dictionary containing: - ‘Z_min’ : float
Lower Z limit of the locked region.
- ‘Z_max’float
Upper Z limit of the locked region.
- ‘total_force’ndarray of shape (3,)
Total reaction force vector [Fx, Fy, Fz].
- ‘F_tot’float
Norm of the total reaction force.
- ‘num_nodes’int
Total number of nodes in the mesh.
- ‘num_elements’int
Total number of elements in the mesh.
- ‘vs’float
Voxel size.
- ‘nodes_z0_count’int
Number of nodes constrained at Z = 0.
- ‘nodes_z1_count’int
Number of nodes constrained at Z = Z_max.
- ciclope.utils.postprocess.sample_height(input_folder, vs)
Calculate the height of the sample in millimeters based on the number of .tif slices.
Parameters
- input_folderstr
The path to the folder containing the .tif slices.
- voxel_sizefloat
The size of a voxel in millimeters.
Returns
- float
The height of the sample in millimeters.