ImageCache

MacroModule

genre	File
author	Jan-Martin Kuhnigk
package	FMEstable/ReleaseMeVis
definition	ImageCache.def
see also	PageCache, ImageFileCache, MLImageFormatFileCache, MemoryCache, Bypass
keywords	File, Image, Page, Memory, Cache, Buffer, Bypass

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

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
​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)