This guide describes how the result storage can be configured and the implications for the storage of images and objects in an analysis pipeline.
Configuring the result storage operator
Introduction
As part of an image analysis pipeline users will often use voxel operations. These operations modify the pixel intensities in some ways. This can be useful for a variety of reasons, both functional (allowing better segmentation) and esthetic (denoising to make the image look better). Since arivis Vision4D has been built to be RAM independent this means that instead of storing the results of such operations in the computer memory until such time as the user chooses to use them, the modified images must be stored on the hard disk and the Result Storage describes how the pipeline should store the images beyond the end of the pipeline, but also how segmented objects are kept relative to those images.
Central to the implementation of voxel processing in Vision4D is the concept of what we call lanes. That is, operations move the input along a lane to be used later and progress further as the pipeline progresses. Each channel has its own lane and those lanes run in parallel in the pipeline, with most operations typically moving one lane along at a time but with the possibility of processing multiple lanes simultaneously. Typically this means that once an image has been modified, it is the modified result that used for later operations that call on that specific channel. As of Vision4D 3.4, it is also possible to use the previous state of a channel rather than just the latest version along that lane and this is described in the Advanced Result Storage options section below. some operations, like channel math, can be used to create new lanes.
Another important point regarding image processing pipelines is that Vision4D will not overwrite the original image data unless the user specifically requests it. Instead, the default behavior is to store channel operation results in temporary documents that are used for the purposes of the pipeline and discarded once the pipeline execution is complete, though the results of the operations can be stored permanently if needed.
Default Result Storage targets
As mentioned above the default behavior for this operation is to store the processed images as a temporary document, with the following segment generating operations using these images to generate the objects but storing the resulting objects on the original image. There are two very important aspects to this:
- Temporary documents are stored on the hard disk and used for the segmentation but are automatically deleted when the pipeline is finished.
- Since the segmented objects are normally stored on the original image data it means that intensity measurements are made on the original data and not on the processed image.
So first, some notes on the temporary documents. The default location for temporary documents can be set in the Analysis preferences.
Note that for optimum performance it best to ensure that the location for temporary documents is on a fast local storage device. Avoid network drives or removable storage. It is also very important that there is ample free space in the selected destination to hold the temporary images. We typically recommend at least 5x as much free space and the size of the file being processed.
Changing the Result Storage options
To simplify pipeline creation, Result Storage is automatically added in the Collapsed view. In most cases, no change is needed and the modified images are used for segmentation but discarded when the pipeline completes. If the user preferes to keep the modified images permanently, the parameters can be changed by expanding the operation by clicking the Expand operation arrow in the title bar.
You can then change both the Voxel storage target and the Segments storage target.
Voxels Storage
To change the voxels storage, click the Edit... button. This opens a new window where users can select from any of the available options.
- Temporary Document - Processed images are stored in the analysis documents folder until the pipeline is completed and then discarded.
- New Document - Processed images are stored in the analysis documents folder until the Result Storage operation is run and then saved into a new SIS file as defined by the user below.
- New Image Set - Processed images are stored in the analysis documents folder until the Result Storage operation is run and then saved into a new image set in the current SIS file as defined by the user below.
- New Channel(s) - Processed images are stored in the analysis documents folder until the Result Storage operation is run and then saved as new channels within the current image set.
- Replace Original - Processed images are stored in the analysis documents folder until the Result Storage operation is run and then the original image data is overwritten by the processed images.
Segments Storage
To change the Segments storage, select from the available options in the droplist box directly in the Results Storage operation. The options are:
- Source Image Set
- This is the original unedited image data.
- Result Image Set
- This is the set generated during the Result Storage operation, whether that is a new document or image set.
Which option should I use, and when?
Using the default options has a few advantages (no unnecessary disk usage, intensity measurements on original data), but has some downsides (no record of the processed images after the analysis is finished unless the user creates screenshots during the pipeline execution). So what options should you use and when?
First, it's important to note that it is best not to store segments in the Result Image Set if you are using the Temporary Document voxel storage option since the objects will be deleted along with the temporary document once the pipeline finishes. Of course, the pipeline can still be used to export some of the segmentation results in one way or another (Excel spreadsheet of segment values, labelled image, or surfaces of the segmented objects), but it makes it very difficult to review the analysis results.
Second, the option to store the segments in the result image set will be unavailable if the voxels are stored as new channels or overwrite the original image.
Finally, storing the segments on the source image set means that any intensity measurement will be unaffected by the image processing unless the voxel storage is a new channel or replaces the original image data. This is important as many voxel operations have a dramatic effect on intensity values.
So the options become:
- Temporary Document - Source Image set: This is the default option. The original SIS file remains unmodified except for the objects now stored in it, saving hard disk space and allowing the measurement of intensities on unprocessed data. But as mentioned above there is no image record of the intermediate processing steps unless the user collects screen grabs during the analysis.
- New Document/Image Set - Source Image Set: The processed image is stored separately from the original image data but the objects are stored on the original image. This means that a permanent record of the fully processed image is kept (though not the intermediate steps), but the measurements of intensity are still made on the original data. This can be useful if the processed images are needed later (e.g. for further analysis or for visualisation/movie making), but the intensity measurements need to be made on the original data. Storing the images in a new set may be more convenient in terms of file handling (only one file to move/archive), but leads to a significant increase in file size since it will now contain both the original and processed data, along with any segmented objects.
- This option is also very useful if the pipeline isn't used to create objects but simply to improve the esthetics of the image for visualization (e.g. denoising, background correction, masking)
- New Document/Image Set - Result Image Set: As with the previous option, a permanent record of the processed image is made, with the same implications with regards to file handling, but intensity measurements are made on the processed image.
- New Channel - Both the original and processed images are visible simultaneously which can be useful to create comparison animations. Intensity measurements can be made and compared between both the original and processed image. Some analysis that requires both the unprocessed and processed image is possible (e.g. use autofluorescence signal to segment tissue but also use a background-corrected image to segment cells).
- Replace Original - Often not recommended since the original image information is discarded in favor of the processed image. This could make it difficult to interpret the results and reduces the traceability. As with the option to generate new documents or image sets it can be quite useful for pipelines that do not generate objects but simply enhance the image for visualization. Note that since images are typically imported from other formats, it is usually possible to re-import the original image if needed.
- Extended Channel Selection - Useful for operations where two different versions of the same channel need to be used. For example, a background-corrected version of the image might be useful to segment small features while a version with a wide blur can be used to segment the tissue. Or maybe need the original version of the image for seed detection and a modified version for region growing.