cryomask#

cryocat.core.cryomask.add_gaussian(input_mask, sigma)#

Apply Gaussian filter to the input mask.

Parameters:

input_masknumpy.ndarray: 3D array with the input mask to be filtered.
sigmafloat: The standard deviation of the Gaussian filter. If sigma is 0, the input mask is returned as is.

Returns:

numpy.ndarray: 3D array with the filtered mask if sigma is not 0, otherwise the input mask itself.

cryocat.core.cryomask.compute_solidity(input_mask)#

Computes the solidity of a given input mask.

Parameters:

input_masknumpy.ndarray: The input mask to compute the solidity for specified as 3D array.

Returns:

float: The solidity value of the input mask.

cryocat.core.cryomask.cylindrical_mask(mask_size, radius=None, height=None, center=None, gaussian=0, gaussian_outwards=True, angles=None, output_path=None)#

Creates a cylindrical mask with the specified radius, height, center and box size. The values range from 0.0 to 1.0. Additionally, the mask can be blurred by applying Gaussian specified by its sigma value and/or rotated by specifying Euler angles in degrees in zxz convention.

Parameters:

mask_sizearray-like: Specifies the dimensions of the box for the mask. Type is int.
radiusint, optional: Defines the radius of the cylinder base in voxels. If not specified half of the smallest dimensions in (x,y) is used as the radius. Defaults to None.
heightint, optional: Defines the height of the cylinder in voxels. If not specified the dimension z is used as the height. Defaults to None.
centerarray-like, optional: Specify the center of the mask within the box. If not specified, the mask is placed in the center of the box (e.g. for box size of 64 the center will be at (32, 32, 32) when numbered from 0). Type is int. Defaults to None.
gaussianfloat, default=0.0: Defines the sigma of the Gaussian blur. If set to 0 no blur is applied. Defaults to 0.
gaussian_outwardsbool, default=True: Determines if the blur will be done outwards from the mask surface (True) or if it will be centered around the mask surface (False). The latter is consistent with Dynamo convention. Defaults to True.
anglesnumpy.ndarray, optional: 1D array defining the rotation of the mask specified as three Euler angles in degrees in zxz convention. If all angles are zero, no rotation is applied. Defaults to None.
output_pathstr, optional: Path to write out the created mask. If not specified, the mask is not written out. Defaults to None.

Returns:

numpy.ndarray: 3D array containing the cylindrical mask.

Warning

In the previous version, the default behavior was to smooth the mask centrally around its surface. To achive the same effect one has to set gaussian_outwards to False (default is True).

See also

cryocat.cryomask.get_correct_format(): For more information on formatting the inputs.

cryocat.core.cryomask.ellipsoid_shell_mask(mask_size, shell_thickness, radii, center=None, gaussian=0.0, angles=None, output_path=None)#

Generates a binary mask of an ellipsoid shell within a given mask size.

Parameters:

mask_sizearray_like: Size of the mask in each dimension (e.g., [x, y, z]).
shell_thicknessfloat: Thickness of the ellipsoid shell.
radiiarray_like: Radii of the ellipsoid in each dimension.
centerarray_like, optional: Center of the ellipsoid. If None, the ellipsoid is centered in the mask. Defaults to None.
gaussianfloat, default=0.0: Standard deviation of the Gaussian blur to apply to the shell mask. Defaults to 0.0 (no blur).
anglesarray_like, optional: Angles for rotating the ellipsoid around each axis (in degrees). Defaults to None.
output_pathstr, optional: If provided, the function will save the mask to a file with this name. Defaults to None.

Returns:

ndarray: A mask array of the same shape as mask_size, with a binary representation of an ellipsoid shell.

Notes

The function internally adjusts the radii for the inner and outer surfaces of the shell by adding and subtracting half the shell thickness, respectively. It then creates two ellipsoid masks and subtracts the inner mask from the outer mask to create the shell. Optional Gaussian blurring and rotation can be applied to the shell mask before returning.

cryocat.core.cryomask.fill_hollow_mask(input_mask, output_path=None, apply_opening_closing=True, footprint=None)#

Takes in a binary mask and returns the same mask with all holes filled in.

Parameters:

input_maskstr or numpy.ndarray: Input mask specified either by its path or already loaded as 3D numpy.ndarray.
output_pathstr, optional: Path to write out the created mask. If not specified, the mask is not written out. Defaults to None.
apply_opening_closingbool, default=True: If True the morphological operations of opening and closing will be applied as post-processing step. For closing very small regions, it should be set to False. Defaults to True.
footprintndarray or tuple, optional: The neighborhood for the opening operation, expressed as a 2-D array of 1s and 0s. Used only if apply_opening_closing is True. If footprint is None, uses footprint np.ones((2,2,2)). The footprint can also be provided as a sequence of smaller footprints as described on the scikit-image documentation. Default is None.

Returns:

numpy.ndarray: 3D array with the input mask with the holes filled in.

cryocat.core.cryomask.generate_mask(mask_shape, mask_size=None, mask_expansion=4)#

Generates a mask array based on the specified geometric shape and dimensions.

Parameters:

mask_shapestr: A string that specifies the shape and dimensions of the mask. See cryocat.cryomask.parse_shape_string() for more information on correct formatting.
mask_sizeint, optional: The size of the mask array. If None, it is automatically determined based on the maximum dimension in specs plus an expansion factor. Defaults to None.
mask_expansion: int, default=4: If mask_size is not specified, the maximum dimension plus this expansion is used to define the mask size. Defaults to 4.

Returns:

maskndarray: An array where the mask has been applied, with dimensions specified by mask_size. The shape of the mask is determined by mask_shape.

Examples

>>> generate_mask("sphere_r5")
array([...])  # returns a spherical mask with radius 5

>>> generate_mask("cylinder_r3_h7", mask_size=10)
array([...])  # returns a cylindrical mask with radius 3, height 7, and mask size 10

cryocat.core.cryomask.get_bounding_box(input_mask)#

Get the bounding box indices of a given input mask.

Parameters:

input_maskstr or numpy.ndarray: Input mask specified either by its path or already loaded as 3D numpy.ndarray.

Returns:

start_idsnumpy.ndarray: 1D array with the starting coordinates of the bounding box with shape (3,) and type int.
end_idsnumpy.ndarray: 1D array with the starting coordinates of the bounding box with shape (3,) and type int.

cryocat.core.cryomask.get_correct_format(input_value, reference_size=None)#

Formats correctly the size of the mask, radius or coordinates of the mask centers. If the input size is specified, it will be converted to a numpy.ndarray of length 3. If the reference size is specified, it will be converted to a numpy.ndarray of length 3 and then divided by 2.

Parameters:

input_valueint or array-like: Specify the value either by one number, tuple, list or numpy.ndarray. In case of one number, it is assumed that the output should be the same for all three dimensions.
reference_sizeint, optional: If input_value is None, then the reference size can be used to compute the correct output. For example, getting the center coordinates based on the box size (reference_size) by dividing the box size by 2. Defaults to None.

Returns:

numpy.ndarray: An (3,) array with size/coordinates.

Raises:

ValueError: If the size is specified as a container with size different from 1 or 3.
ValueError: If both input_size and reference_size are None.

Notes

This function is mainly use internally to ensure correct format of the input values, such as mask and radius size or center coordinates.

cryocat.core.cryomask.get_mass_center(input_mask)#

Calculate the mass center of a given input mask.

Parameters:

input_maskstr or numpy.ndarray: Input mask specified either by its path or already loaded as 3D numpy.ndarray.

Returns:

numpy.ndarray: The mass center coordinates as an array of integers with shape (3,).

cryocat.core.cryomask.get_mass_dimensions(input_mask)#

Get the dimensions of the mass in the input mask.

Parameters:

input_maskstr or numpy.ndarray: Input mask specified either by its path or already loaded as 3D numpy.ndarray.

Returns:

numpy.ndarray: The dimensions of the mass in the format [width, height, depth].

cryocat.core.cryomask.intersection(mask_list, output_path=None)#

Calculate the intersection of multiple masks. The final values are clipped to 0.0 and 1.0.

Parameters:

mask_listlist: A list of masks (loaded or specified by their paths, or combination of both).
output_pathstr, optional: The name of the output file. If provided, the final mask is written out. Defaults to None.

Returns:

numpy.ndarray: 3D array with the final mask as a numpy array.

cryocat.core.cryomask.map_tight_mask(input_map, threshold=None, dilation_size=0, gaussian=0, gaussian_outwards=True, angles=None, n_regions=1, output_path=None)#

Creates a tight mask for the map coming from STA/SPA (i.e., with some noise around it). The mask is the same shape as the input map at given threshold. It has values from 0.0 to 1.0. Additionally, the mask can be blurred by applying Gaussian specified by its sigma value and/or rotated by specifying Euler angles in degrees in zxz convention.

Parameters:

input_mapstr or numpy.ndarray: Input map specified either by its path or already loaded as 3D numpy.ndarray.
thresholdfloat, optional: In case the threshold is negative, the values below this threshold will be included in the mask. In case of positive threshold, the values from the input map larger than this threshold will be included in the mask. If the value is None, the threshold is determined as 3 * standard deviation of the input map (or its negative value in case the median is larger than 0.0 which correspond to the densities being dark). Defaults to None.
dilation_sizeint, default=0: Determines the number of iterations for the dilation operation. If gaussian_outwards is True, the dilation_size can be 0 unless larger mask extension is wanted. Defaults to 0.
gaussianfloat, default=0.0: Defines the sigma of the Gaussian blur. If set to 0 no blur is applied. Defaults to 0.
gaussian_outwardsbool, default=True: Determines if the blur will be done outwards from the mask surface (True) or if it will be centered around the mask surface (False). Defaults to True.
anglesnumpy.ndarray, optional: Defines the rotation of the mask specified as three Euler angles in degrees in zxz convention. If all angles are zero, no rotation is applied. Defaults to None.
n_regionsint, default=1: Determines how many connected regions should be part of the mask. After the input map is thresholded, the connected regions are labeled and “n” largerst regions (in terms of number of voxels) are returned as the mask. Defaults to 1.
output_pathstr, optional: Path to write out the created mask. If not specified, the mask is not written out. Defaults to None.

Returns:

numpy.ndarray: 3D array with the tight mask for the provided map density.

Warning

In the previous version, the default behavior was to smooth the mask centrally around its surface. To achive the same effect one has to set gaussian_outwards to False (default is True).

cryocat.core.cryomask.mask_overlap(mask1, mask2, threshold=1.9)#

Calculate the overlap between two masks.

Parameters:

mask1numpy.ndarray: The first mask as 3D array.
mask2numpy.ndarray: The second mask as 3D array.
thresholdfloat: The threshold value for determining the overlap. Defaults to 1.9.

Returns:

int: The sum of the overlapping voxels between the two masks that have value larger than the threshold.

cryocat.core.cryomask.molmap_tight_mask(input_map, threshold=0.0, dilation_size=0, gaussian=0, gaussian_outwards=True, angles=None, output_path=None)#

Creates a tight mask for the density created with molmap function in Chimera(X). The mask is the same shape as the input map, but has values from 0.0 to 1.0. Additionally, the mask can be blurred by applying Gaussian specified by its sigma value and/or rotated by specifying Euler angles in degrees in zxz convention.

Parameters:

input_mapstr or numpy.ndarray: Input molmap specified either by its path or already loaded as 3D numpy.ndarray.
thresholdfloat, default=0.0: Values from the input map larger than this threshold will be included in the mask. This value is used inly if dilation_size is 0. Defaults to 0.0.
dilation_sizeint, default=0: Determines the number of iterations for the dilation operation. If gaussian_outwards is True, the dilation_size can be 0 unless larger mask extension is wanted. Defaults to 0.
gaussianfloat, default=0.0: Defines the sigma of the Gaussian blur. If set to 0 no blur is applied. Defaults to 0.
gaussian_outwardsbool, default=True: Determines if the blur will be done outwards from the mask surface (True) or if it will be centered around the mask surface (False). Defaults to True.
anglesnumpy.ndarray, optional: Defines the rotation of the mask specified as three Euler angles in degrees in zxz convention. If all angles are zero, no rotation is applied. Defaults to None.
output_pathstr, optional: Path to write out the created mask. If not specified, the mask is not written out. Defaults to None.

Returns:

numpy.array: A tight mask for the provided molmap density.

Warning

In the previous version, the default behavior was to smooth the mask centrally around its surface. To achive the same effect one has to set gaussian_outwards to False (default is True).

cryocat.core.cryomask.parse_shape_string(shape_string)#

Parses a string describing a geometric shape and its dimensions.

Parameters:

shape_stringstr: A string describing the shape and its dimensions. The format should match one of the following patterns: - “sphere_r{radius}” - “cylinder_r{radius}_h{height}” - “s_shell_r{radius}_s{thickness}” - “ellipsoid_rx{radius_x}_ry{radius_y}_rz{radius_z}” - “e_shell_rx{radius_x}_ry{radius_y}_rz{radius_z}_s{thickness}”

Returns:

tuple: A tuple containing the shape type as a string and a list of integers representing the dimensions.

Raises:

ValueError: If the input string does not match any of the known patterns.

Examples

>>> parse_shape_string("sphere_r10")
('sphere', [10])
>>> parse_shape_string("cylinder_r5_h20")
('cylinder', [5, 20])

cryocat.core.cryomask.postprocess(input_mask, gaussian, angles, output_path)#

Applies set of postprocessing steps to the input_mask. It can smooth the mask by applying Gaussian blur, it can rotate it by Euler angles defined in degrees in zxz convention and write it out if output path is specified.

Parameters:

input_masknumpy.ndarray: 3D array with the mask to postprocess.
gaussianfloat: Sigma value of the Gaussian blur to be added. If set to 0.0, the Gaussian is not applied.
anglesnumpy.ndarray: Euler angles in degrees in zxz convention. If all angles are 0.0, the mask is not rotated.
output_pathstr: Name the output file to write the mask into. If None, the mask will not be written out.

Returns:

numpy.ndarray: 3D array with the post-processed mask.

Notes

This function is meant to be used mostly internally to apply a set of post-processing routines.

cryocat.core.cryomask.preprocess_params(radius, gaussian, gaussian_outwards)#

Determines a new radius or dilation in case of Gaussian blur that should be applied outwards from the mask surface. If the Gaussian is 0 or the blur should be applied centrally around the mask surface, the radius/dilation remains unchanged. Otherwise, it new radius/dilation is computed as radius + gaussian * blur_factor. The blur_factor was determined empirically and set to 5 (i.e., Gaussian with value 1 requires extension of radius by 5 voxels in order not to affect the core part of the mask by the blur).

Parameters:

radiusint: Defines radius to be recomputed in case Gaussian blur is not zero and gaussian_outwards is True.
gaussianfloat: Defines the sigma of the Gaussian blur.
gaussian_outwardsbool: Defines whether the Gaussian blur should be applied outwards form the surface (True) or centrally around the mask surface (False).

Returns:

int: The radius/dilation adapted based on the gaussian and gaussian_outwards parameters.

Notes

This function is meant to be used mostly internally to adapt the radius/dilation based on the Gaussian blur.

cryocat.core.cryomask.rotate(input_mask, angles)#

Rotates the input mask by the specified angles. The angles are specified in degrees and their order follows zxz Euler convention.

Parameters:

input_masknumpy.ndarray: 3D array with the input mask to be rotated.
anglesnumpy.ndarray: The angles (in degrees) by which the mask should be rotated. The angles should follow zxz Euler convention.

Returns:

numpy.ndarray: 3D array with the rotated mask. If all angles are zero, the input mask is returned as is.

cryocat.core.cryomask.shrink_full_mask(input_mask, shrink_factor, output_path=None)#

Takes in a 3D binary mask and shrinks it by the specified shrink factor. The function first fills in all of the holes within each slice of the mask, then shrinks it by removing the outermost layer of voxels from each slice. The function returns a new shrunken binary mask.

Parameters:

input_maskstr or numpy.ndarray: Input mask specified either by its path or already loaded as 3D numpy.ndarray.
shrink_factorint: Defines how much the mask should be shrunken (in voxels).
output_pathstr, optional: Path to write out the created mask. If not specified, the mask is not written out. Defaults to None.

Returns:

numpy.ndarray: 3D array with the mask shrunken by the specified factor.

cryocat.core.cryomask.spherical_mask(mask_size, radius=None, center=None, gaussian=0.0, gaussian_outwards=True, output_path=None)#

Creates a spherical mask with the specified radius, center and box size. The values range from 0.0 to 1.0. Additionally, the mask can be blurred by applying Gaussian specified by its sigma value.

Parameters:

mask_sizeint or array-like: Specifies the dimensions of the box for the mask. If single number is provided, the mask will be cubic.
radiusint, optional: Defines the radius of the sphere in voxels. If not specified half of the smallest dimensions is used as the radius. Defaults to None.
centerarray-like, optional: Specify the center of the mask within the box. If not specified, the mask is placed in the center of the box (e.g. for box size of 64 the center will be at (32, 32, 32) when numbered from 0). Type int. Defaults to None.
gaussianfloat, default=0.0: Defines the sigma of the Gaussian blur. If set to 0 no blur is applied. Defaults to 0.
gaussian_outwardsbool, default=True: Determines if the blur will be done outwards from the sphere surface (True) or if it will be centered around the sphere surface (False). The latter is consistent with Dynamo convention. Defaults to True.
output_pathstr, optional: Path to write out the created mask. If not specified, the mask is not written out. Defaults to None.

Returns:

numpy.ndarray: 3D array with the spherical mask.