Purpose

The module ImageLoadMulti extends the ImageLoad functionality with the following features:

  • Allows navigation through a list of image files provided by the user via an ASCII list file or assembled from the contents of a specified directory.
  • Allows filtering of the list by filename patterns, optionally using regular expressions.
  • Displays a preview of the currently selected image.

Usage

First you have to fill in the field File List or Directory. There are three accepted kinds of entries:

  1. A list file (usually *.lst or *.txt).
  2. A directory.
  3. An image file.

at 1: A list file is given:

  • A file list can contain a number of image files and/or directories.
  • Each entry can be specified using absolute or relative path.
  • The entries are separated by newline commands.
  • After the list is parsed, the user can navigate through the parsed list by using the File Access panel in the middle part of the ImageLoadMulti panel, or by selecting a file by name from the Select From List tab.
  • Note that in Skip parser mode, the list can only hold image file names and must not contain directories. The list will not be parsed (though the relative path will still be expanded to the absolute one), which can save some time, especially when the files have to be accessed through a network.

at 2: A directory is given: Equivalent to a list containing a single directory.

at 3: A image file is given: Equivalent to a list containing this image file as sole entry.

Note that (in non- Skip parser mode) the file name pattern will also be applied to the name of a directory or a file given directly (without using a list). This may result in the effect that the parsed list is empty even though you specified an existing file or directory.

Interaction

Keyboard shortcuts are provided for navigation between datasets:

Key Function
<HOME> Goto first dataset
<END> Goto last dataset
<PgUp> Goto previous dataset
<PgDn> Goto next dataset.

When loading this module with a network, it will eventually start reading and parsing the given list immediately. Since this might take a while, it is sometimes useful to deactivate the Auto-Read feature. This way, the module will “respawn” in the same state it has been stored in. However, modifications on the source list (on the list file or on the content of a specified directory) will have no effect until the list is re-read.

There is a hidden trigger field named fileOpenCompleteTrigger that is notified when image loading is complete.

Windows

Default Panel

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

Output Fields

output0

name: output0, type: Image

The currently loaded image.

previewSelf (hidden)

name: previewSelf, type: SoNode

Hidden output showing the preview viewer’s scene.

Parameter Fields

Field Index

&Close: Trigger File List or Directory: String resetFile: Trigger
&Load: Trigger fileOpenCompleteTrigger: Trigger Running: Bool
<: Trigger format: String saveRawFileList: Trigger
>: Trigger Ignore case: Bool saveRawFileListAs: Trigger
>|: Trigger Include: String sizeC: Integer
|<: Trigger Include subdirectories: Bool sizeT: Integer
Auto load files: Bool Index Mode: Enum sizeU: Integer
Auto parse: Bool Join DICOM/TIFF image pairs: Bool sizeX: Integer
Auto read: Bool Keep Invalid List Entries: Bool sizeY: Integer
Auto select first file: Bool List File Encoding: Enum sizeZ: Integer
Byte Order: Enum Loop: Bool Skip parser: Bool
C: Integer Maximum Depth: Integer Start: Trigger
Clear List: Trigger maxValue: Double startSlice: Integer
comment: String minValue: Double Status: String
Current File: String newValue: Trigger Stop: Trigger
Data Offset: Integer of: Integer T: Integer
Data Type: Enum Parse List: Trigger Timer Delay: Float
dataType: String Planar Config: Enum Treat all paths as relative: Bool
Dir...: Trigger processingPossible: Bool U: Integer
Enable: Bool Read List: Trigger User-Defined Root Path: String
Exclude: String Regular expression (includeRegExp): Bool X: Integer
File Index: Integer Regular expression (excludeRegExp): Bool Y: Integer
File List: String Relative List Base Dir Mode: Enum Z: Integer

Visible Fields

User-Defined Root Path

name: rootPath, type: String

Sets a user-defined root path.

Current File

name: filename, type: String, persistent: no

Shows the name of currently selected file.

File List or Directory

name: fileListFileName, type: String

Sets a list file (.lst, .txt), a directory, or an image file.

Use the ‘File…’ or ‘Dir…’-buttons to the right to browse for a file (single image or list file) or a directory.

Dir…

name: browseDir, type: Trigger

When pressed, a browse dialog for directories is opened.

Read List

name: readFileList, type: Trigger

When pressed, the file list is read.

In Skip Parser Mode, reading of the list is sufficient to use it. The list will not be parsed, but relative paths will be expanded to the absolute ones. If Skip Parser is disabled, and Auto-Parse is enabled, the list will be parsed subsequently. Otherwise, you have to press Parse List yourself to use the list.

Parse List

name: parseFileList, type: Trigger

When pressed, the file file is parsed.

If Skip Parser is deactivated, the list has to be parsed to access the files. In this case, parsing means, that directories are expanded, image pairs can be joint and file- and directory names are filtered using the Filename Patterns. You can either activate Auto-Parse, in which case the parsing will happen when the File List or Directory-entry is modified, or press the Parse-button instead.

Clear List

name: resetImgLoadMulti, type: Trigger

When pressed, the list of files is cleared.

List File Encoding

name: listFileEncoding, type: Enum, default: utf_8, deprecated name: listEncoding

Defines the encoding of the list file used when decoding it during reading.

Values:

Title Name
ASCII ascii
Latin 1 latin_1
UTF-8 utf_8
UTF-16 utf_16
UTF-32 utf_32

Auto read

name: autoReadFileList, type: Bool, default: TRUE

If checked, the file list is read automatically on modification.

See Read List for more information.

Auto parse

name: autoParseFileList, type: Bool, default: TRUE

If checked, the file list is parsed automatically on modification.

See Read List for more information.

Skip parser

name: doNotParse, type: Bool, default: FALSE

If checked, the file list is not parsed.

In Skip Parser Mode, the list can only hold image file names and must not contain directories. The list will not be parsed (though the relative path will still be expanded to the absolute one), which can save some time, especially when the files have to be accessed through a network.

Auto load files

name: autoLoadFiles, type: Bool, default: TRUE

If checked, the currently selected file is loaded automatically.

Auto select first file

name: autoSelectFirst, type: Bool, default: TRUE

If checked, the first image file will be selected after parsing.

Otherwise, the Select File field is set to -1 and no file will be loaded.

Keep Invalid List Entries

name: keepInvalidListEntries, type: Bool, default: FALSE

If checked, an entry is reserved in the parsed list even if the source list entry yielded no files during parsing.

This can be useful if the index association between source and parsed list shall be maintained even in case of missing files.

Relative List Base Dir Mode

name: relativeListBaseDirMode, type: Enum, default: RelativeToListPath

Defines the mode to determine the relative base directory.

Values:

Title Name Deprecated Name
List Path RelativeToListPath Relative to List Path
Default Data Path RelativeToDefaultDataPath Relative to Default Data Path

Treat all paths as relative

name: treatAllPathsAsRelative, type: Bool, default: FALSE

If unchecked, each path beginning with ‘/’, ‘', or ‘<DriveLetter>:’ is assumed to be absolute, and no root path is added.

File List

name: fileList, type: String

Shows the list of files.

|<

name: loadFirstFile, type: Trigger

When pressed, the first file is loaded.

<

name: loadPrevFile, type: Trigger

When pressed, the previous file is loaded.

>

name: loadNextFile, type: Trigger

When pressed, the next file is loaded.

>|

name: loadLastFile, type: Trigger

When pressed, the last file is loaded.

of

name: noFilesInList, type: Integer, persistent: no

Shows the total number of files in the file list.

File Index

name: setCurrentFileByIndex, type: Integer, default: -1, minimum: -1, maximum: FileIterator.maxIndex

Sets an index to select a file.

If -1 is set, no file is selected.

Index Mode

name: indexMode, type: Enum, default: OneBased

Defines the base of indexing, allowing for switching between 0-based and 1-based indexing.

Values:

Title Name Description
0-based ZeroBased Minimum index is 0, maximum index is of-1.
1-based OneBased Minimum index is 1, maximum index is of.

Include subdirectories

name: recursive, type: Bool, default: FALSE

If checked, subdirectories of each directory entry are included recursively.

Maximum Depth

name: maxRecursionDepth, type: Integer, default: -1

Sets the maximum subdirectory depth for the subdirectory inclusion.

For unlimited depth, select a negative value, e.g., -1.

Join DICOM/TIFF image pairs

name: joinImagePairs, type: Bool, default: TRUE

If checked, paired image files (for example, DICOM/TIFF pairs) are treated as a single file.

Include

name: include, type: String, default: .*\.di?co?m .*\.dic .*\.tiff? .*\.hdr .*\.img .*\.ima .*\.raw .*\.p[gpn]m .*\.mlimage

Sets include patterns.

If include patterns (separated by spaces) are specified, only entries matching at least one of these patterns are included in the list.

Regular expression (includeRegExp)

name: includeRegExp, type: Bool, default: TRUE

If checked, entries in the Include list are evaluated as regular expressions.

Exclude

name: exclude, type: String, default: result* *slices

Sets exclude patterns.

If exclude patterns (separated by spaces) are specified, only entries not matching any of these patterns are included in the list.

Regular expression (excludeRegExp)

name: excludeRegExp, type: Bool, default: FALSE

If checked, entries in the Exclude list are evaluated as regular expressions.

Ignore case

name: ignoreCase, type: Bool, default: TRUE

If checked, the include and exclude patterns are applied case-insensitively

Loop

name: loop, type: Bool, default: FALSE

If checked, the list is treated as if it were cyclic.

&Close

name: close, type: Trigger

When pressed, the current file is closed.

&Load

name: load, type: Trigger

When pressed, the current file is loaded.

Status

name: status, type: String, persistent: no

Shows the current status.

Enable

name: readRaw, type: Bool, default: FALSE

If checked, the reading of raw data is enabled.

X

name: rawX, type: Integer, default: 512, deprecated name: XRaw

Sets the x-extent of raw data.

Y

name: rawY, type: Integer, default: 512, deprecated name: YRaw

Sets the y-extent of raw data.

Z

name: rawZ, type: Integer, default: 1, deprecated name: ZRaw

Sets the z-extent of raw data.

C

name: rawC, type: Integer, default: 1, deprecated name: CRaw

Sets the c-extent of raw data.

T

name: rawT, type: Integer, default: 1, deprecated name: TRaw

Sets the t-extent of raw data.

U

name: rawU, type: Integer, default: 1, deprecated name: URaw

Sets the u-extent of raw data.

Data Type

name: dataTypeRaw, type: Enum, default: unsigned int8

Defines the data type for raw data.

Values:

Title Name Deprecated Name
unsigned int8 unsigned int8 UInt8
int8 int8 Int8
unsigned int16 unsigned int16 UInt16
int16 int16 Int16
unsigned int32 unsigned int32 UInt32
int32 int32 Int32
float float Float
double double  
unsigned int64 unsigned int64  
int64 int64  

Planar Config

name: planarConfig, type: Enum, default: Contiguous

Defines the planar configuration of values in raw data.

Values:

Title Name
Contiguous Contiguous
Separate Separate

Byte Order

name: byteOrder, type: Enum, default: LittleEndian

Defines the byte order of values in raw data.

Values:

Title Name Deprecated Name
Little Endian LittleEndian Little endian
Big Endian BigEndian Big endian
Native Native  

Data Offset

name: dataOffset, type: Integer, default: 0

Sets an offset value for reading raw data. Use this to skip header bytes.

Start

name: startIteration, type: Trigger

When pressed, the automatic, timer controlled iteration through the list from the currently selected index is started.

Stop

name: stopIteration, type: Trigger

When pressed, the automatic, timer controlled iteration through the list is stopped.

Timer Delay

name: iterationDelay, type: Float, default: 1

Sets the delay (in seconds) before proceeding to the next.

Running

name: iterationRunning, type: Bool, persistent: no

Shows whether automatic iteration is currently active.

Hidden Fields

saveRawFileList

name: saveRawFileList, type: Trigger

saveRawFileListAs

name: saveRawFileListAs, type: Trigger

newValue

name: newValue, type: Trigger

processingPossible

name: processingPossible, type: Bool, persistent: no

resetFile

name: resetFile, type: Trigger

When pressed, the file is reset.

sizeX

name: sizeX, type: Integer, persistent: no, deprecated name: X

sizeY

name: sizeY, type: Integer, persistent: no, deprecated name: Y

sizeZ

name: sizeZ, type: Integer, persistent: no, deprecated name: Z

sizeC

name: sizeC, type: Integer, persistent: no, deprecated name: C

sizeT

name: sizeT, type: Integer, persistent: no, deprecated name: T

sizeU

name: sizeU, type: Integer, persistent: no, deprecated name: U

dataType

name: dataType, type: String, persistent: no

minValue

name: minValue, type: Double, persistent: no

maxValue

name: maxValue, type: Double, persistent: no

format

name: format, type: String, persistent: no

comment

name: comment, type: String, persistent: no

startSlice

name: startSlice, type: Integer, default: 0, minimum: 0, maximum: view.maxSlice

fileOpenCompleteTrigger

name: fileOpenCompleteTrigger, type: Trigger