Save Images saves image or movie files.
Because CellProfiler usually performs many image analysis steps on many groups of images, it does
not save any of the resulting images to the hard drive unless you specifically choose to do so with the
SaveImages module. You can save any of the processed images created by CellProfiler during the analysis using this module.
You can choose from many different image formats for saving your files. This allows you to use the module as a file format converter, by loading files in their original format and then saving them in an alternate format.
Note that saving images in 12-bit format is not supported, and 16-bit format is supported for TIFF only.
See also NamesAndTypes, ConserveMemory.
Settings:
Select the type of image to save
The following types of images can be saved as a file on the hard drive:
- Image: Any of the images produced upstream of SaveImages can be selected for saving.
Outlines created by Identify modules can also be saved with this option, but you must
select "Retain outlines..." of identified objects within the Identify module. You might
also want to use the OverlayOutlines module prior to saving images.
- Mask: Relevant only if the Crop module is used. The Crop module
creates a mask of the pixels of interest in the image. Saving the mask will produce a
binary image in which the pixels of interest are set to 1; all other pixels are
set to 0.
- Cropping: Relevant only if the Crop module is used. The Crop
module also creates a cropping image which is typically the same size as the original
image. However, since the Crop permits removal of the rows and columns that are left
blank, the cropping can be of a different size than the mask.
- Movie: A sequence of images can be saved as a movie file. Currently only AVIs can be written.
Each image becomes a frame of the movie.
- Objects: Objects can be saved as an image. The image
is saved as grayscale unless you select a color map other than
gray. Background pixels appear as black and
each object is assigned an intensity level corresponding to
its object number. The resulting image can be loaded as objects
by the NamesAndTypes module. Objects are best saved as TIF
files. SaveImages will use an 8-bit TIF file if there
are fewer than 256 objects and will use a 16-bit TIF otherwise.
Results may be unpredictable if you save using PNG and there
are more than 255 objects or if you save using one of the other
file formats.
Select the image to save
(Used only if "Image", "Mask" or "Cropping" are selected to save)
Select the image you want to save.
Select the objects to save
(Used only if saving "Objects")
Select the objects that you want to save.
Select the module display window to save
(Used only if saving "Module window")
Enter the module number/name for which you want to
save the module display window.
Select method for constructing file names
(Used only if saving non-movie files)
Several choices are available for constructing the image file name:
- From image filename: The filename will be constructed based
on the original filename of an input image specified in NamesAndTypes.
You will have the opportunity to prefix or append
additional text.
If you have metadata associated with your images, you can append an text
to the image filename using a metadata tag. This is especially useful if you
want your output given a unique label according to the metadata corresponding
to an image group. The name of the metadata to substitute can be provided for
each image for each cycle using the Metadata module.
You can insert a previously defined metadata tag by either using:
- The insert key
- A right mouse button click inside the control
- In Windows, the Context menu key, which is between the Windows key and Ctrl key
The inserted metadata tag will appear in green. To change a previously inserted metadata tag,
navigate the cursor to just before the tag and either:
- Use the up and down arrows to cycle through possible values.
- Right-click on the tag to display and select the available values.
Please see the Metadata module for more details on metadata collection and usage.
- Sequential numbers: Same as above, but in addition, each filename
will have a number appended to the end that corresponds to
the image cycle number (starting at 1).
- Single name: A single name will be given to the
file. Since the filename is fixed, this file will be overwritten with each cycle.
In this case, you would probably want to save the image on the last cycle
(see the Select how often to save setting). The exception to this is to
use a metadata tag to provide a unique label, as mentioned
in the From image filename option.
Select image name for file prefix
(Used only when "From image filename" is selected for contructing the filename)
Select an image loaded using NamesAndTypes. The original filename will be
used as the prefix for the output filename.
Enter single file name
(Used only when "Sequential numbers" or "Single name" are selected for contructing the filename)
Specify the filename text here. If you have metadata
associated with your images, enter the filename text with the metadata tags.
You can insert a previously defined metadata tag by either using:
- The insert key
- A right mouse button click inside the control
- In Windows, the Context menu key, which is between the Windows key and Ctrl key
The inserted metadata tag will appear in green. To change a previously inserted metadata tag,
navigate the cursor to just before the tag and either:
- Use the up and down arrows to cycle through possible values.
- Right-click on the tag to display and select the available values.
Do not enter the file extension in this setting; it will be appended automatically.
Number of digits
(Used only when "Sequential numbers" is selected for contructing the filename)
Specify the number of digits to be used for the sequential numbering. Zeros will be
used to left-pad the digits. If the number specified here is less than that needed to
contain the number of image sets, the latter will override the value entered.
Append a suffix to the image file name?
Select Yes to add a suffix to the image's file name.
Select No to use the image name as-is.
Text to append to the image name
(Used only when constructing the filename from the image filename)
Enter the text that should be appended to the filename specified above.
Saved file format
(Used only when saving non-movie files)
Select the image or movie format to save the image(s). Most common
image formats are available; MAT-files are readable by MATLAB.
Output file location
(Used only when saving non-movie files)
This setting lets you choose the folder for the output
files.
You can choose among the following options which are common to all file input/output
modules:
- Default Input Folder: Use the default input folder.
- Default Output Folder: Use from the default output folder.
- Elsewhere...: Use a particular folder you specify.
- Default input directory sub-folder: Enter the name of a subfolder of
the default input folder or a path that starts from the default input folder.
- Default output directory sub-folder: Enter the name of a subfolder of
the default output folder or a path that starts from the default output folder.
Elsewhere and the two sub-folder options all require you to enter an additional
path name. You can use an absolute path (such as "C:\imagedir\image.tif" on a PC) or a
relative path to specify the file location relative to a directory):
- Use one period to represent the current directory. For example, if you choose
Default Input Folder sub-folder, you can enter "./MyFiles" to look in a
folder called "MyFiles" that is contained within the Default Input Folder.
- Use two periods ".." to move up one folder level. For example, if you choose
Default Input Folder sub-folder, you can enter "../MyFolder" to look in a
folder called "MyFolder" at the same level as the Default Input Folder.
An additional option is the following:
- Same folder as image: Place the output file in the same folder
that the source image is located.
For Elsewhere..., Default Input Folder sub-folder and
Default Output Folder sub-folder, if you have metadata associated with your
images via Metadata module, you can name the folder using metadata
tags.
You can insert a previously defined metadata tag by either using:
- The insert key
- A right mouse button click inside the control
- In Windows, the Context menu key, which is between the Windows key and Ctrl key
The inserted metadata tag will appear in green. To change a previously inserted metadata tag,
navigate the cursor to just before the tag and either:
- Use the up and down arrows to cycle through possible values.
- Right-click on the tag to display and select the available values.
.
For instance, if you have a metadata tag named
"Plate", you can create a per-plate folder by selecting one the subfolder options
and then specifying the subfolder name as "\g<Plate>". The module will
substitute the metadata values for the current image set for any metadata tags in the
folder name.Please see the
Metadata module for more details on metadata collection and usage.
If the subfolder does not exist when the pipeline is run, CellProfiler will
create it.
If you are creating nested subfolders using the sub-folder options, you can
specify the additional folders separated with slashes. For example, "Outlines/Plate1" will create
a "Plate1" folder in the "Outlines" folder, which in turn is under the Default
Input/Output Folder. The use of a forward slash ("/") as a folder separator will
avoid ambiguity between the various operating systems.
Image bit depth
(Used only when saving files in a non-MAT format)
Select the bit-depth at which you want to save the images.
16-bit images are supported only for TIF formats.
Currently, saving images in 12-bit is not supported.
Overwrite existing files without warning?
Select
Yes to automatically overwrite a file if it already exists.
Select
No to be prompted for confirmation first.
If you are running the pipeline on a computing cluster,
select Yes since you will not be able to intervene and answer the confirmation prompt.
When to save
(Used only when saving non-movie files)
Specify at what point during pipeline execution to save file(s).
- Every cycle: Useful for when the image of interest is created every cycle and is
not dependent on results from a prior cycle.
- First cycle: Useful for when you are saving an aggregate image created
on the first cycle, e.g., CorrectIlluminationCalculate with the All
setting used on images obtained directly from NamesAndTypes.
- Last cycle Useful for when you are saving an aggregate image completed
on the last cycle, e.g., CorrectIlluminationCalculate with the All
setting used on intermediate images generated during each cycle.
Rescale the images?
(Used only when saving non-MAT file images)
Select
Yes if you want the image to occupy the full dynamic range of the bit
depth you have chosen. For example, if you save an image to an 8-bit file, the
smallest grayscale value will be mapped to 0 and the largest value will be mapped
to 2
8-1 = 255.
This will increase the contrast of the output image but will also effectively
stretch the image data, which may not be desirable in some
circumstances. See RescaleIntensity for other rescaling options.
Save as grayscale or color image?
(Used only when saving "Objects")
You can save objects as a grayscale image or as a color image.
- Grayscale: Use the pixel's object number
(label) for the grayscale intensity. Background pixels are
colored black. Grayscale images are more
suitable if you are going to load the image as objects using
NamesAndTypes or some other program that will be used to
relate object measurements to the pixels in the image.
You should save grayscale images using the .TIF or .MAT formats
if possible; otherwise you may have problems saving files
with more than 255 objects.
- Color: Assigns different colors to different
objects.
Select colormap
(Used only when saving non-MAT file images)
This affects how images color intensities are displayed. All available colormaps can be seen
here.
Record the file and path information to the saved image?
Select
Yesto store filename and pathname data for each of the new files created
via this module as a per-image measurement.
Instances in which this information may be useful include:
- Exporting measurements to a database, allowing
access to the saved image. If you are using the machine-learning tools or image
viewer in CellProfiler Analyst, for example, you will want to enable this setting if you want
the saved images to be displayed along with the original images.
- Allowing downstream modules (e.g., CreateWebPage) to access
the newly saved files.
Create subfolders in the output folder?
Select Yes to create subfolders to match the input image folder structure.
Base image folder
Used only if creating subfolders in the output folder
In subfolder mode, SaveImages determines the folder for
an image file by examining the path of the matching input file.
The path that SaveImages uses is relative to the image folder
chosen using this setting. As an example, input images might be stored
in a folder structure of "images\experiment-name\
date\plate-name". If the image folder is
"images", SaveImages will store images in the subfolder,
"experiment-name\date\plate-name".
If the image folder is "images\experiment-name",
SaveImages will store images in the subfolder,
date\plate-name".
Saved movie format
(Used only when saving movie files)
Select the movie format to use when saving movies. AVI and MOV
store images from successive image sets as movie frames. TIF
stores each image as an image plane in a TIF stack.