Purpose

The ImageCache module encapsulates several caching methods under a common interface, simplifying switching the cache type (e.g. from file to memory) statically or at runtime.

Usage

Select any caching mode (except ‘NoCache’) via the field In Mode, then connect the module to an output image and press Update. Then you can invalidate/disconnect the input while the image at the module’s output remains valid. It will only be cleared once you press Clear.

Windows

Default Panel

../../../Projects/ImageCache/Modules/mhelp/Images/Screenshots/ImageCache._default.png

Input Fields

input0

name: input0, type: Image

Input image that will be cached.

Output Fields

output0

name: output0, type: Image

Output image, representing the cached image.

Parameter Fields

Field Index

[]: Trigger In Mode: Enum Use Automatic Filename: Bool
Cache Represents Input: Bool Last Update Time: Double  
Cached Image Extent: Vector6 On Input Change: Enum  
Cached Image File:: String Preserve Cache Files: Bool  
Cached Image Type: String progress: Float  
Clear: Trigger Status Code: Enum  
Custom Cache File Name: String Status Message: String  
Has Valid Output: Bool Update: Trigger  

Visible Fields

On Input Change

name: onInputChangeBehavior, type: Enum, default: UpdateIfInputValid, deprecated name: updateMode

Decides what happens when input image or input parameters of the module change.

Values:

Title Name Deprecated Name Description
Do Nothing DoNothing Off No reaction to changes.
Update Update AutoUpdate Automatic update of the cache on any input image or parameter change.
Clear Clear AutoClear Automatic clear of the cache on any input image or parameter change.
Update If Input Valid UpdateIfInputValid  

Automatic update of the cache on any input image or parameter change IF a valid input image is connected (i.e notifications are ignored as long as the input image is invalid).

This can be helpful when we want an image to persist until we loaded the next dataset, and then let it auto-update. It makes inconsistencies due to missing cache updates in the network easier to detect since there will never be a valid cache input with a valid cache output unless they belong to the same image.
Clear If Input Valid ClearIfInputValid  

Automatic clear of the cache on any input image or parameter change IF a valid input image is connected (i.e notifications are ignored as long as the input image is invalid).

This can be helpful when we want an image to persist until we loaded the next dataset but then want a manual rather than an automatic update. It makes inconsistencies due to missing cache updates in the network easier to detect since there will never be a valid cache input with a valid cache output unless they belong to the same image.
Update If Input Valid And Different UpdateIfInputValidAndDifferent  

Automatic update of the cache on any input image or parameter change IF a valid input image is connected and differs from the cached one in voxel values or image properties (i.e notifications are ignored as long as the input image is invalid or identical to the cached one).

This builds upon the UpdateIfInputValid mode and helps to further reduce unnecessary notifications and clears of the subsequent network.

Note that in order to determine if the input image differs from the cached one, it has to be completely computed.
Clear If Input Valid And Different ClearIfInputValidAndDifferent  

Automatic clear of the cache on any input image or parameter change IF a valid input image is connected and differs from the cached one in voxel values or image properties (i.e notifications are ignored as long as the input image is invalid or identical to the cached one).

This builds upon the ClearIfInputValid mode and helps to further reduce unnecessary notifications and clears of the subsequent network.

Note that in order to determine if the input image differs from the cached one, it has to be completely computed.

Update

name: update, type: Trigger

Initiates update of the cache. If successful, the cached image will be made available at the output. After an update (no matter if successful or not), the trigger [] will be toggled.

Clear

name: clear, type: Trigger

Clears all output field values to a clean initial state.

In Mode

name: inMode, type: Enum, default: PageCache

Caching mode

Values:

Title Name Description
No Caching NoCache Do not cache at all. In this mode, the module will act as an ImageClear module, and On Input Change == ‘DoNothing’ will be identical to ‘Clear’, since no caching can be performed. This can be useful to find out how the network would work without a cache module. NOTE: It is not clear if this mode remains available as it does not behave like the other modes!
Memory Caching (Pages) PageCache Cache the input image in memory internally using the PageCache module. That module requests the entire input image and then locks the ML image cache pages until Clear is pressed.
Memory Caching (Memory Image) MemoryCache Cache the input image in memory internally using the MemoryCache module. That module requests the entire input image and then stores it in a so-called MemoryImage (see also MemoryImage Concept), which in contrast to PageCache mode requires a free memory chunk of the entire image size.
File Cache (MLImageFormat LZ4) FileCache Cache the input image in memory internally using the MLImageFormatFileCache module. That module requests the entire input image and then stores it in a temporary file using fast LZ4 compression (if available on your system).

Use Automatic Filename

name: inFileCache_useAutoFilename, type: Bool, default: TRUE

If enabled, no cache file prefix or name has to be provided, the module automatically selects a non-existing one in your temp folder.

Custom Cache File Name

name: inFileCache_customFilenameBase, type: String, deprecated name: inFileCache\_filenameBase

FileCache mode only: Custom prefix (path + filename prefix) for the cache file (used if Use Automatic Filename is off). If you provide a path without any file prefix, you have to append a path separator (“/”) at the end to indicate that.

Preserve Cache Files

name: inFileCache_preserveCacheFile, type: Bool, default: FALSE

FileCache mode only: Prevents deletion of the cache file on Clear.

Cache Represents Input

name: outputIsConsistentWithInput, type: Bool, persistent: no

This flag indicates if the current output (i.e. the current cache content) represents the current input image. Note that the module will always assume that a input0 notification with a valid input image represents a new image (i.e. the module cannot tell if the same input image is connected once more that is already in the cache), so the state will be set to inconsistent until an update is performed.

Note that, an empty cache is regarded as consistent with an empty input.

Cached Image Extent

name: outCachedImageExtent, type: Vector6, persistent: no

Displays the image extent of the currently cached image.

Cached Image Type

name: outCachedImageType, type: String, persistent: no

Displays the voxel type of the currently cached image.

Cached Image File:

name: outFileCache_cachedImageFilename, type: String, persistent: no

File name of the cached image if in FileCache mode. If invalid, the value is “n/a”.

Status Code

name: statusCode, type: Enum, persistent: no

Reflects module’s status (successful or failed computations) as one of some predefined enumeration values.

Values:

Title Name
Ok Ok
Busy Busy
Invalid input image InvalidInputObject
Invalid input parameter InvalidInputParameter
Internal error InternalError

Last Update Time

name: updateTime_s, type: Double, persistent: no

Displays the time required for caching the input image (in seconds).

[]

name: updateDone, type: Trigger, persistent: no

Notifies that an update was performed (Check status interface fields to identify success or failure).

Status Message

name: statusMessage, type: String, persistent: no

Gives additional, detailed information about status code as human-readable message.

Has Valid Output

name: hasValidOutput, type: Bool, persistent: no

Indicates validity of output field values (success of computation).

Hidden Fields

progress

name: progress, type: Float, minimum: 0, maximum: 1, persistent: no

Progress of caching (between 0 and 1)