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.
Advanced Result Storage options
With the release of arivis Vision4D 3.4, the way voxel operations store and use the processed results has changed to allow more flexibility in pipeline creation. As mentioned in the introduction, by default, voxel processing operations and segment operations use the last state of the channel being used. This means that, for example, if a pipeline adds a denoising filter followed by a morphology filter, the morphology filter is based on the denoised image and any operation that comes after will use the result of the morphology operation. In 3.4 it is possible to enable advanced pipeline handling operations so that this is not necessarily the case and users can choose to run some operations on previous versions of the channel data, or even on the raw data if required.
Enabling extended channel selection
The option for advanced channel handling can be found in theAnalysis section of the Preferences. This can be accessed either through the Pipeline Management menu or from the Extras menu.
Once this option has been enabled, added options will be available for channel selection and result storage in the pipeline.
Using extended channel selection
With the extended channel selection enabled, three changes will occur.
First, each voxel operation will get its own output saving option. In the operation menu, users can select the Save Voxel Output... option and choose whether to save the result of this specific operation as a new document if needed. Additionally, by selecting Configure Output Channels, users can choose whether the output will be available as a new channel that can be used independently of the original.
Second, each operation will now have additional options in the channel input selection.
Users can then choose which version of that channel image to use for this operation. This is available for any pipeline operation that uses channel data (voxel operations, segment generation, region growing, etc.).
And finally, the Results Storage operation will also get more options in the manual channel selection.
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.