AmiraMesh¶

Amira Mesh I/O helper functions.

io.AmiraMesh.amiraLabels2bitmap(filename)¶

AMIRALABELS2BITMAP - Converts Amira Mesh Labels to bitmap matrix, for Amira ver. 5.2.2.

Syntax:

bitmap = io.AmiraMesh.amiraLabels2bitmap()
bitmap = io.AmiraMesh.amiraLabels2bitmap(filename)

Input Arguments:

filename - (optional) filename of Amira Mesh labels file; when omitted, a file selection dialog is started

Output Arguments:

bitmap - label image as [height, width, colors, depth]

io.AmiraMesh.amiraLandmarks2points(filename)¶

AMIRALANDMARKS2POINTS - Read Amira landmark coordinates.

Syntax:

points = io.AmiraMesh.amiraLandmarks2points()
points = io.AmiraMesh.amiraLandmarks2points(filename)

Input Arguments:

filename - (optional) filename of Amira landmark file; when omitted, a file selection dialog is started

Output Arguments:

points - [Nx3] array of landmark coordinates [x, y, z]

io.AmiraMesh.amiraMesh2bitmap(filename, options)¶

AMIRAMESH2BITMAP - Convert Amira Mesh file to bitmap matrix.

Syntax:

bitmap = io.AmiraMesh.amiraMesh2bitmap()
[bitmap, par] = io.AmiraMesh.amiraMesh2bitmap(filename)
[bitmap, par, status] = io.AmiraMesh.amiraMesh2bitmap(filename, options)

Input Arguments:

filename - (optional) filename of Amira Mesh file; when omitted, a file selection dialog is started
options - (optional) struct with fields:
- .hWaitbar - handle to an existing progress dialog
- .maxZ - [numeric] total number of z-slices (used to scale the waitbar)
- .depth_start - [numeric] first z-slice to load (default: 1)
- .depth_end - [numeric] last z-slice to load
- .depth_step - [numeric] z-step (default: 1, load every slice)
- .xy_step - [numeric] XY binning factor (default: 1, no binning)
- .resizeMethod - (char) resize method for XY binning
- .getMeta - [logical] acquire metadata (default: true)
- .verbose - [logical] print loaded-file message (default: true)

Output Arguments:

bitmap - dataset [height, width, colors, depth]
par - struct array with Amira Mesh header parameters
status - [logical] true on success, false on failure or cancel

io.AmiraMesh.bitmap2amiraLabels(filename, bitmap, format, voxel, color_list, modelMaterialNames, overwrite, showWaitbar, extraOptions)¶

BITMAP2AMIRALABELS - Convert matrix [1:height, 1:width, 1:no_stacks] to Amira Mesh Labels.

Syntax:

result = io.AmiraMesh.bitmap2amiraLabels(filename, bitmap)
result = io.AmiraMesh.bitmap2amiraLabels(filename, bitmap, format, voxel, color_list, modelMaterialNames, overwrite, showWaitbar, extraOptions)

Input Arguments:

filename - filename for Amira Mesh file
bitmap - the dataset [height, width, depth]
format - (optional) saving format: 'binaryRLE', 'ascii', or 'binary' (default: 'binary')
voxel - (optional) struct with voxel size:
- .x - physical width of a voxel
- .y - physical height of a voxel
- .z - physical thickness of a voxel
- .minx - minimal X coordinate of the bounding box
- .miny - minimal Y coordinate of the bounding box
- .minz - minimal Z coordinate of the bounding box
color_list - (optional) matrix with material colours as [materialId, Red, Green, Blue] in range 0-1; can be empty
modelMaterialNames - (optional) cell array with material name strings; can be empty
overwrite - (optional) 1 = do not check whether file already exists
showWaitbar - (optional) 1 = show the wait bar, 0 = hide it
extraOptions - (optional) struct with fields:
- .TransformationMatrix - (char) transformation matrix string
- .ParentFigure - handle to the main MIB UIFigure; when provided, progress bar is shown as a uiprogressdlg attached to that window; when absent, legacy waitbar is used

Output Arguments:

result - 1 = success, 0 = failure

Example 1 - standalone use (no GUI parent):

pixStr = dataset.pixSize;
pixStr.minx = boundingBox(1);
pixStr.miny = boundingBox(3);
pixStr.minz = boundingBox(5);
io.AmiraMesh.bitmap2amiraLabels('/output/Labels.am', labelsData, 'binary', pixStr, materialColors, materialNames, 1, false, struct());

Example 2 - GUI use (attach progress dialog to MIB window):

pixStr = dataset.pixSize;
pixStr.minx = boundingBox(1);
pixStr.miny = boundingBox(3);
pixStr.minz = boundingBox(5);
extraOpts.ParentFigure = obj.mibModel.mibGUI;   % uiprogressdlg parent
io.AmiraMesh.bitmap2amiraLabels('/output/Labels.am', labelsData, 'binary', pixStr, materialColors, materialNames, 1, true, extraOpts);

io.AmiraMesh.bitmap2amiraLabels2(filename, bitmap, format, voxel, color_list, modelMaterialNames, overwrite, showWaitbar, extraOptions)¶

BITMAP2AMIRALABELS2 - Convert matrix [1:height, 1:width, 1:no_stacks] to Amira Mesh Labels.

Syntax:

result = io.AmiraMesh.bitmap2amiraLabels2(filename, bitmap)
result = io.AmiraMesh.bitmap2amiraLabels2(filename, bitmap, format, voxel, color_list, modelMaterialNames, overwrite, showWaitbar, extraOptions)

Drop-in replacement for io.AmiraMesh.bitmap2amiraLabels with a dramatically faster binaryRLE encoder. All three formats (binary, ascii, binaryRLE) are supported; the signature is identical.

KEY DIFFERENCES vs bitmap2amiraLabels¶

1. RLE ENCODER - vectorised, O(R) loop over runs instead of O(N) loop over bytes. For typical segmentation data R << N (often R < N/100), so the encoder is 100-1000× faster.

2. minRLE = 2 - the original used minRLE = 1, which encodes a single repeated byte as [count=1, value] (2 bytes) - actually EXPANDING the data vs leaving it in a literal block (1 byte). Break-even is at run length ≥ 2; anything shorter stays in a literal block.

3. NO in-place overwrite - the original wrote compressed output back into the input bitmap array. This version uses a separate pre-allocated output buffer, which is cleaner and avoids potential aliasing bugs.

4. ASCII encoder vectorised - fprintf(fid, ‘%dn’, data) is called on the entire array in one shot instead of per-element.

5. uint16/uint32 RLE warning - Amira’s HxByteRLE operates on raw bytes; for multi-byte label types the encoding is ambiguous. The function warns and falls back to uncompressed binary for uint16/uint32 when binaryRLE is requested.

ALGORITHM - binaryRLE (HxByteRLE format)¶

Amira’s HxByteRLE is a simple run-length encoding over a byte stream:

Compressed block - [N, V] where N < 0x80 (bit7=0): N copies of byte V

Literal block - [0x80|N, b1, b2, …, bN] where N ≤ 127: N literal bytes follow

Encoding strategy: 1. Detect all runs vectorially using diff() - O(N) vectorised, no loop. 2. Loop over runs (not bytes). For each run of length L and value V: L ≥ minRLE → compressed: emit ceil(L/127) × [chunk, V] pairs L < minRLE → literal: accumulate into a 127-byte literal buffer, flush when full or when a compressible run arrives. 3. Flush remaining literal bytes at the end.

COMPLEXITY Original: O(N) MATLAB loop iterations (N = total bytes) This version: O(N) vectorised + O(R) loop iterations (R = num runs) Typical speedup: 100-1000× on real segmentation data.

Input Arguments:

filename - output file path
bitmap - [H, W, D] label array (uint8 recommended)
format - (optional) saving format: 'binary', 'binaryRLE', or 'ascii' (default: 'binary')
voxel - (optional) struct with voxel size fields .x, .y, .z, .minx, .miny, .minz
color_list - (optional) [M×3] material RGB colours (0-1)
modelMaterialNames - (optional) cell array of material name strings
overwrite - (optional) 1 = overwrite without asking (default: 0)
showWaitbar - (optional) 1 = show progress bar (default: 1)
extraOptions - (optional) struct with fields:
- .TransformationMatrix - (char) transformation matrix string

Output Arguments:

result - 1 = success, 0 = failure/cancel

Example 1 - direct use:

pixStr = dataset.pixSize;
pixStr.minx = bb(1);  pixStr.miny = bb(3);  pixStr.minz = bb(5);
result = io.AmiraMesh.bitmap2amiraLabels2( ...
    '/output/Labels.am', uint8(labelVolume_hwd), 'binaryRLE', ...
    pixStr, materialColors, materialNames, 1, false, struct());

Example 2 - via saver (preferred):

opts.Format    = 'Amira mesh binary RLE compression SLOW (``*.am``)';
opts.layerType = 'labels';
opts.silent    = true;
opts.overwrite = true;
dataset.save('labels', '/output/Labels.am', opts);

See also

io.AmiraMesh.bitmap2amiraLabels (original, slower version), io.savers.AmiraMeshSaver

io.AmiraMesh.bitmap2amiraMesh(filename, bitmap, img_info, options)¶

BITMAP2AMIRAMESH - Convert bitmap matrix to Amira Mesh binary format.

Syntax:

result = io.AmiraMesh.bitmap2amiraMesh(filename, bitmap)
result = io.AmiraMesh.bitmap2amiraMesh(filename, bitmap, img_info, options)

Input Arguments:

filename - filename for Amira Mesh file
bitmap - dataset in MIB3 native order [H, W, D, C, T] (height, width, depth/slices, colour channels, time points); only the first time point (T=1) is written
img_info - (optional) metadata dictionary (MATLAB dictionary, string → cell); pass [] to use defaults. Recognised keys:
- 'pixSize' - pixSize struct with fields .x, .y, .z, .units
- 'BoundingBox' - [1×6] [xmin xmax ymin ymax zmin zmax]
- 'colorType' - 'grayscale' or 'multichannel'
- 'lutColors' - [C×3] colour matrix (0-1)
- 'ImageDescription' - (char) optional description string
- 'TransformationMatrix' - optional transform (char or numeric)
options - (optional) struct with fields:
- .overwrite - 1 = do not check whether file already exists
- .showWaitbar - 1 = show the progress bar
- .ParentFigure - (optional) handle to the main MIB UIFigure; when provided, the progress bar is shown as a uiprogressdlg attached to that window; when absent or empty, the legacy waitbar is used as a fallback
- .colors - (optional) [C×3] colour matrix (0-1) for multichannel; overrides img_info 'lutColors'
- .Saving3d - 'multi' = save all z-slices in a single file (default); 'sequence' = save one file per z-slice
- .SliceName - (optional) cell array with per-slice filenames (no path)
- .verbose - (optional) [logical] (default: true)

Output Arguments:

result - 1 = success, 0 = failure

Example 1 - standalone use (no GUI parent):

opts.overwrite   = 1;
opts.showWaitbar = false;
opts.Saving3d    = 'multi';
opts.colors      = lutColors;
io.AmiraMesh.bitmap2amiraMesh('/output/stack.am', data_hwdct, imgInfoDict, opts);

Example 2 - GUI use (attach progress dialog to MIB window):

opts.overwrite    = 1;
opts.showWaitbar  = true;
opts.Saving3d     = 'multi';
opts.colors       = lutColors;
opts.ParentFigure = obj.mibModel.mibGUI;
io.AmiraMesh.bitmap2amiraMesh('/output/stack.am', data_hwdct, imgInfoDict, opts);

io.AmiraMesh.getAmiraMeshHeader(filename)¶

GETAMIRAMESHHEADER - Get header of Amira Mesh file.

Syntax:

[par, img_info, dim_xyczt] = io.AmiraMesh.getAmiraMeshHeader()
[par, img_info, dim_xyczt, materialNames, materialColors] = io.AmiraMesh.getAmiraMeshHeader(filename)

Input Arguments:

filename - (optional) filename of Amira Mesh file; when omitted, a file selection dialog is started

Output Arguments:

par - struct array with header parameters; each element has fields:
- .Name - parameter name string
- .Value - parameter value
img_info - MATLAB dictionary (configureDictionary("string","cell")); access values with {} indexing
dim_xyczt - [1×5] dataset dimensions [width, height, colors, depth, time]
materialNames - cell array of detected material names (Exterior excluded)
materialColors - [Nx3] RGB material colours (0-1); Exterior excluded

io.AmiraMesh.graph2amiraSpatialGraph(filename, G, options)¶

GRAPH2AMIRASPATIALGRAPH - generate Amira Spatial Graph Ascii file.

Syntax:

res = io.AmiraMesh.graph2amiraSpatialGraph(filename, G)
res = io.AmiraMesh.graph2amiraSpatialGraph(filename, G, options)

Input Arguments:

filename - filename to save data
G - a standard MATLAB graph object with the following properties:
- .Nodes - a table with columns:
  - .XData - x coordinate of the node
  - .YData - y coordinate of the node
  - .ZData - z coordinate of the node
  - .PointsXYZ - (alternative to XData/YData/ZData) matrix [nodeId][x,y,z]
  - .Values - (optional) values for the nodes
- .Edges - a table with columns:
  - .EndNodes - connectivity matrix for nodes (0-based indexing)
  - .Points - (optional) cell array of edge point coordinates; at least 2 per edge; {edgeId}[pointId, x y z]
  - .Thickness - (optional) cell array of per-point thickness; {edgeId}[pointId, thickness]
options - a structure with additional options:
- .overwrite - 1 = automatically overwrite existing files
- .format - (char) 'binary' or 'ascii'
- .NodeFieldName - (cell, max 2 elements) field names in .Nodes to export (replaces .Values)
- .EdgeFieldName - (cell) field name in .Edges to export (replaces .Thickness)

Output Arguments:

res - 1 = success, 0 = failure

Example 1 - save a graph with node coordinates, values, and edge thickness:

G = graph([1 2 4],[2 3 5]);
G.Nodes.XData = [1 2 3 4 5]';
G.Nodes.YData = [5 4 3 2 5]';
G.Nodes.ZData = [1 3 4 2 5]';
G.Nodes.Values = [1 2 4 2 5]';
G.Nodes.Values2 = [5 4 3 2 1]';
G.Edges.Thickness = ones([size(G.Edges,1) 1]);
figure(1);
p = plot(G);
p.XData = G.Nodes.XData;
p.YData = G.Nodes.YData;
p.ZData = G.Nodes.ZData;
options.NodeFieldName = [{'Values'}, {'Values2'}];
options.EdgeFieldName = {'Thickness'};
res = graph2amiraSpatialGraph('test.am', G, options);

io.AmiraMesh.points2amiraLandmarks(filename, points, options)¶

POINTS2AMIRALANDMARKS - Generate Amira Hypersurface ASCII landmark file.

Syntax:

res = io.AmiraMesh.points2amiraLandmarks(filename, points)
res = io.AmiraMesh.points2amiraLandmarks(filename, points, options)

Input Arguments:

filename - filename to save data
points - matrix with points [pointId, x, y, z]
options - (optional) struct with fields:
- .overwrite - 1 = automatically overwrite existing files
- .format - (char) 'binary' or 'ascii' (default: 'ascii')

Output Arguments:

res - 1 = success, 0 = failure

io.AmiraMesh.points2psi(filename, points, pntLabels, pntValues, options)¶

POINTS2PSI - generate PSI file for Amira.

Syntax:

res = io.AmiraMesh.points2psi(filename, points)
res = io.AmiraMesh.points2psi(filename, points, pntLabels, pntValues, options)

the file contains cloud of points, their labels and values

Input Arguments:

filename - filename to save data
points - a matrix with points [point number, x, y, z]
pntLabels - a cell array with labels for each point; can be empty (default: " "); note: spaces will be replaced with underscores
pntValues - an array of values for each point; can be empty (default: 1)
options - a structure with additional options:
- .overwrite - 1 = automatically overwrite existing files
- .format - (char) 'binary' or 'ascii'

Output Arguments:

res - 1 = success, 0 = failure

Note

Data saved in PSI format can be opened in Amira, but saving from Amira crashes it (internal Amira bug; tested in version 6.4.0).

io.AmiraMesh.skipQuotedGroup(fid)¶

SKIPQUOTEDGROUP - Consume an AmiraMesh header group whose opening brace was already read.

Syntax:

io.AmiraMesh.skipQuotedGroup(fid)

Reads lines from fid until the brace opened on the current line is closed again, counting only braces that are outside double-quoted strings.

This exists because Amira’s HistoryLogHead group cannot be skipped by the line-by-line brace counting used for the rest of the header: its ModuleState entries are multi-line quoted strings that contain unbalanced braces and even the keyword Lattice. Counting those braces drifts the nesting level, and the Lattice occurrence terminates the Parameters loop early - which left the parameter list completely empty for files exported by Amira’s Extract Subvolume.

The quote state is deliberately carried across lines, because such a string may span many of them; a backslash escapes the character that follows it.

Input Arguments:

fid - [numeric] file identifier positioned just after the group’s {

Output Arguments:

(none) - fid is left positioned just after the group’s matching }