Purpose

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

  • allows to navigate through a list of image files given by the user through an ASCII list file or assembled from the contents of a specified directory,
  • allows to filter the list by filename patterns, eventually using regular expressions, and
  • shows 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

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

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

Dir…

name: browseDir, type: Trigger

Opens a browse dialog for directories.

Read List

name: readFileList, type: Trigger

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

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

Clears the list of files.

List File Encoding

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

Allows specifying 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

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.

Auto parse

name: autoParseFileList, type: Bool, default: TRUE

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.

Skip parser

name: doNotParse, type: Bool, default: FALSE

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 enabled, the currently selected file is automatically loaded.

Auto select first file

name: autoSelectFirst, type: Bool, default: TRUE

If enabled, the first image file will be selected after parsing. If disabled, the Select File field is set to -1 and no file will be loaded.

Keep Invalid List Entries

name: keepInvalidListEntries, type: Bool, default: FALSE

Reserves an entry 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 disabled, each path beginning with ‘/’, ‘' or ‘[DriveLetter]:’ is assumed to be absolute and no root path is prepended.

File List

name: fileList, type: String

Shows the list of files.

|<

name: loadFirstFile, type: Trigger

Loads first file.

<

name: loadPrevFile, type: Trigger

Loads previous file.

>

name: loadNextFile, type: Trigger

Loads next file.

>|

name: loadLastFile, type: Trigger

Loads last file.

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

Select a file by index.

Index Mode

name: indexMode, type: Enum, default: OneBased

Allows to switch between 0- 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 this is checked, subdirectories of each directory entry are recursively included.

Maximum Depth

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

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 this is checked, paired image files (e.g. 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

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

Sets regular expressions for the include list.

Exclude

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

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

Sets regular expressions for the exclude list.

Ignore case

name: ignoreCase, type: Bool, default: TRUE

This option controls whether the include and exclude patterns are applied with or without regarding case.

Loop

name: loop, type: Bool, default: FALSE

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

&Close

name: close, type: Trigger

Closes the current file.

&Load

name: load, type: Trigger

Loads the current file.

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

Sets 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

Sets the planar configuration of values in raw data.

Values:

Title Name
Contiguous Contiguous
Separate Separate

Byte Order

name: byteOrder, type: Enum, default: LittleEndian

Sets 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

Start the automatic, timer controlled iteration through the list from the currently selected index.

Stop

name: stopIteration, type: Trigger

Stop the automatic, timer controlled iteration through the list.

Timer Delay

name: iterationDelay, type: Float, default: 1

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

Running

name: iterationRunning, type: Bool, persistent: no

Indicates 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

Resets the file.

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