xmipp3.protocols.protocol_preprocess.protocol_create_mask2d module
- class xmipp3.protocols.protocol_preprocess.protocol_create_mask2d.XmippProtCreateMask2D(**kwargs)[source]
Bases:
ProtCreateMask2D,XmippGeometricalMask2DCreate a 2D mask. The mask can be created with a given geometrical shape (Circle, Rectangle, Crown…) or it can be obtained from operating on a 2d image or a previuous mask.
AI Generated
## Overview
The Create 2D Mask protocol generates a two-dimensional mask from a selected geometrical shape.
Masks are frequently used in cryo-EM image processing to restrict operations to a region of interest and to suppress background. A 2D mask can be useful for particle images, class averages, projections, or other two-dimensional image-processing steps.
This protocol creates a mask directly from geometry. The user defines the mask size, sampling rate, shape, and shape-specific parameters such as radius, box size, inner and outer radii, Gaussian sigma, or border decay.
The main output is a Scipion mask object.
## Inputs and General Workflow
The protocol does not require an input image.
It creates an empty 2D image of the requested size and then applies the selected geometrical mask using the Xmipp mask transformation program. The result is saved as mask.xmp.
Finally, the protocol registers this file as the output mask and assigns the sampling rate selected by the user.
## Sampling Rate
The Sampling Rate parameter defines the pixel size of the output mask, in angstroms per pixel.
This value does not change the shape of the mask in pixels. Instead, it defines the physical scale associated with the mask when it is used in later protocols.
The sampling rate should match the images to which the mask will be applied.
## Mask Size
The Mask size parameter defines the dimensions of the output mask in pixels.
The output mask is a square image of size:
- [
ext{size} imes ext{size}
]
For example, a value of 256 creates a 256 × 256 pixel mask.
The mask size should match the box size of the images that will use the mask.
## Mask Type
The Mask type parameter selects the geometrical shape of the mask.
The available 2D mask types are:
Circular;
Box;
Crown;
Gaussian;
Raised cosine;
Raised crown.
Each type exposes its own parameters. For example, circular masks use a radius, box masks use a box size, crown-like masks use inner and outer radii, and Gaussian masks use sigma.
## Circular Mask
A Circular mask creates a disk-shaped region centered in the image, unless a center shift is requested.
The Radius parameter defines the disk radius in pixels. If the radius is set to -1, the protocol uses half the mask size.
Circular masks are useful when the object of interest is approximately centered and roughly round in projection.
## Box Mask
A Box mask creates a rectangular or square region.
The Box size parameter defines the size of the box in pixels. If it is set to -1, the protocol uses half the mask size.
Box masks are useful when the region of interest is rectangular or when the user wants to keep a central square area.
## Crown Mask
A Crown mask creates an annular region between an inner and an outer radius.
The relevant parameters are:
Inner radius;
Outer radius.
If the outer radius is set to -1, the protocol uses half the mask size.
Crown masks are useful when the user wants to select a ring-like region while excluding the central area.
## Gaussian Mask
A Gaussian mask creates a smooth Gaussian weighting function.
The Sigma parameter defines the Gaussian width in pixels. If sigma is set to -1, the protocol uses one sixth of the mask size.
Gaussian masks are useful when the user wants a smooth weighting rather than a hard binary mask.
## Raised Cosine Mask
A Raised cosine mask creates a smooth radial transition between an inner and an outer radius.
The relevant parameters are:
Inner radius;
Outer radius.
This mask is useful when a smooth falloff is desired, reducing sharp-edge artifacts that can appear with hard masks.
## Raised Crown Mask
A Raised crown mask creates a crown-like mask with smooth transitions at the borders.
The relevant parameters are:
Inner radius;
Outer radius;
Border decay.
The border decay controls the falloff of the two crown borders.
This mask is useful for ring-shaped regions where smooth edges are important.
## Shift Center
The Shift Center option allows the user to move the center of the mask away from the image center.
When enabled, the user provides:
X center offset;
Y center offset.
This is useful when the region of interest is not centered in the image.
The shift is expressed in pixels.
## Output Mask
The main output is outputMask.
This output points to the generated mask.xmp file and stores the sampling rate selected by the user.
The mask can be used in later Scipion protocols that accept 2D masks.
## Interpreting the Output
The output should be interpreted as a geometrical 2D mask.
Depending on the selected type, the mask may be binary, smoothly weighted, or radially tapered. The protocol does not derive the mask from image content; it creates it entirely from user-defined geometry.
Therefore, the correctness of the mask depends on choosing a size, shape, center, and radii that match the images where the mask will be applied.
## Practical Recommendations
Set the mask size equal to the box size of the images that will use it.
Set the sampling rate equal to the sampling rate of those images.
Use a circular mask for centered particles or projections.
Use raised cosine or raised crown masks when smooth edges are important.
Use center shifting only when the region of interest is known to be off-center.
Inspect the generated mask before using it in downstream processing.
Avoid masks that are too tight, because they may remove real signal. Avoid masks that are too loose, because they may include unnecessary background.
## Final Perspective
Create 2D Mask is a simple geometrical mask-generation protocol.
For biological users, its value is practical: it creates a reproducible 2D mask with known size, sampling rate, shape, and center. Such masks can be used to focus later image-processing steps on the relevant particle or projection region while reducing the influence of background.