copper3d / Modules / Utils/segmentation/core/MaskVolume / MaskVolume

Class: MaskVolume ​

Utils/segmentation/core/MaskVolume.MaskVolume

Table of contents ​

Constructors ​

• constructor

Properties ​

• bytesPerSlice
• colorMap
• data
• dims
• numChannels

Methods ​

• buildRgbToChannelMap
• clear
• clearSlice
• clone
• getChannelColor
• getChannels
• getColorMap
• getDimensions
• getIndex
• getMemoryUsage
• getRawData
• getSliceDimensions
• getSliceImageData
• getSliceUint8
• getVoxel
• hasData
• renderBlended
• renderColoredMulti
• renderColoredSingle
• renderGrayscale
• renderLabelSliceInto
• resetChannelColors
• setChannelColor
• setRawData
• setSliceFromImageData
• setSliceLabelsFromImageData
• setSliceUint8
• setVoxel
• validateSliceIndex

Constructors ​

constructor ​

• new MaskVolume(width, height, depth, channels?, customColorMap?)

Create a new MaskVolume.

All voxels are initialised to 0.

Parameters ​

Throws

If any dimension or the channel count is < 1.

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:78

Properties ​

bytesPerSlice ​

• Private Readonly bytesPerSlice: number

Number of bytes in one complete z-slice. Equal to width × height × channels.

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:58

colorMap ​

• Private colorMap: ChannelColorMap

Per-channel color map used for colored rendering modes.

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:61

data ​

• Private data: Uint8Array

Contiguous backing buffer — layout [z][y][x][channel].

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:46

dims ​

• Private Readonly dims: Dimensions

Volume size in voxels.

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:49

numChannels ​

• Private Readonly numChannels: number

Number of value channels per voxel (≥ 1).

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:52

Methods ​

buildRgbToChannelMap ​

▸ Private buildRgbToChannelMap(): Map<number, number>

Build a Map from RGB packed integer to channel label for reverse lookup. Uses this instance's colorMap (channels 1-8, skips 0 = transparent).

Instance method ensures custom per-layer colors are correctly reverse-mapped.

Returns ​

Map<number, number>

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:592

clear ​

▸ clear(): void

Zero every voxel in the entire volume (all channels).

Returns ​

void

Example

vol.clear();
vol.getVoxel(256, 256, 50); // 0

vol.clear();
vol.getVoxel(256, 256, 50); // 0

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:820

clearSlice ​

▸ clearSlice(sliceIndex, axis?, channel?): void

Zero every voxel in a single slice along the given axis.

If channel is provided, only that channel is cleared; otherwise all channels in the slice are cleared.

Parameters ​

Returns ​

void

Throws

If sliceIndex is out of bounds.

Example

// Erase a single axial slice
vol.clearSlice(50, 'z');

// Erase only channel 1 of slice 50
vol.clearSlice(50, 'z', 1);

// Erase a single axial slice
vol.clearSlice(50, 'z');

// Erase only channel 1 of slice 50
vol.clearSlice(50, 'z', 1);

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:874

clone ​

▸ clone(): MaskVolume

Create an independent deep copy of this volume.

The clone has the same dimensions, channels, data, and color map but shares no references with the original.

Returns ​

MaskVolume

A new MaskVolume with identical content.

Example

// Undo support: snapshot before an operation
const snapshot = vol.clone();
performEdit(vol);
// Rollback: vol.setRawData(snapshot.getRawData());

// Undo support: snapshot before an operation
const snapshot = vol.clone();
performEdit(vol);
// Rollback: vol.setRawData(snapshot.getRawData());

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:794

getChannelColor ​

▸ getChannelColor(channel): RGBAColor

Get the current color for a channel.

Falls back to the background color (transparent) if no color is defined.

Parameters ​

Returns ​

RGBAColor

A copy of the RGBA color.

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:223

getChannels ​

▸ getChannels(): number

Return the number of channels per voxel.

Returns ​

number

Channel count (≥ 1).

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:713

getColorMap ​

▸ getColorMap(): ChannelColorMap

Get a shallow copy of the entire color map.

Returns ​

ChannelColorMap

A copy of the color map (safe to mutate).

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:251

getDimensions ​

▸ getDimensions(): Dimensions

Return a copy of the volume dimensions.

Returns ​

Dimensions

{ width, height, depth } — a fresh object (safe to mutate).

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:704

getIndex ​

▸ Private getIndex(x, y, z, channel?): number

Map 3D coordinates + channel to a flat 1D index.

Memory layout (slice-major):

index = (z × height × width × channels)
      + (y × width × channels)
      + (x × channels)
      + channel

index = (z × height × width × channels)
      + (y × width × channels)
      + (x × channels)
      + channel

Parameters ​

Returns ​

number

Flat 1D index into this.data.

Throws

If any coordinate or channel is out of bounds.

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:138

getMemoryUsage ​

▸ getMemoryUsage(): number

Return total memory used by the backing buffer, in bytes.

Returns ​

number

width × height × depth × channels bytes.

Example

const vol = new MaskVolume(512, 512, 100);
vol.getMemoryUsage(); // 26_214_400 (~25 MB)

const vol = new MaskVolume(512, 512, 100);
vol.getMemoryUsage(); // 26_214_400 (~25 MB)

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:728

getRawData ​

▸ getRawData(): Uint8Array

Return a reference to the raw backing buffer.

Use this for direct read access (e.g. serialisation, GPU upload). Mutating the returned array mutates the volume.

Returns ​

Uint8Array

The underlying Uint8Array.

Example

// Serialise for network transfer
const bytes = vol.getRawData();
socket.send(bytes.buffer);

// Serialise for network transfer
const bytes = vol.getRawData();
socket.send(bytes.buffer);

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:749

getSliceDimensions ​

▸ Private getSliceDimensions(axis): [number, number]

Get the 2D slice dimensions for a given axis.

Parameters ​

Returns ​

[number, number]

[width, height] of the slice.

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:1042

getSliceImageData ​

▸ getSliceImageData(sliceIndex, axis?, options?): ImageData

Extract a 2D slice as an ImageData with color mapping.

Slice dimensions depend on the axis:

Parameters ​

Returns ​

ImageData

ImageData ready for ctx.putImageData().

Throws

If sliceIndex is out of bounds for the given axis.

Example

// Grayscale (default, backward compatible)
const gs = vol.getSliceImageData(50, 'z');

// Colored single-channel
const cs = vol.getSliceImageData(50, 'z', {
  mode: RenderMode.COLORED_SINGLE,
  channel: 0,
});

// Multi-channel priority
const mc = vol.getSliceImageData(50, 'z', {
  mode: RenderMode.COLORED_MULTI,
  visibleChannels: [false, true, true, true],
});

// Grayscale (default, backward compatible)
const gs = vol.getSliceImageData(50, 'z');

// Colored single-channel
const cs = vol.getSliceImageData(50, 'z', {
  mode: RenderMode.COLORED_SINGLE,
  channel: 0,
});

// Multi-channel priority
const mc = vol.getSliceImageData(50, 'z', {
  mode: RenderMode.COLORED_MULTI,
  visibleChannels: [false, true, true, true],
});

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:299

getSliceUint8 ​

▸ getSliceUint8(sliceIndex, axis?): Object

Extract a 2D slice as a flat Uint8Array (one byte per voxel per channel).

For a 1-channel volume the result is sliceWidth × sliceHeight bytes, each byte being the label value at that pixel. This is suitable for sending to a backend that expects raw label data (e.g. NIfTI slice replacement).

Parameters ​

Returns ​

Object

A copy of the slice data plus its dimensions.

Throws

If sliceIndex is out of bounds.

Example

const { data, width, height } = vol.getSliceUint8(50, 'z');
// data.length === width * height * channels

const { data, width, height } = vol.getSliceUint8(50, 'z');
// data.length === width * height * channels

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:944

getVoxel ​

▸ getVoxel(x, y, z, channel?): number

Read a single voxel value.

Parameters ​

Returns ​

number

The stored value (0 – 255).

Throws

If any coordinate is out of bounds.

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:172

hasData ​

▸ hasData(): boolean

Check if the volume contains any non-zero voxel data.

Returns true if at least one voxel has a non-zero value, false if all voxels are zero (empty mask).

This is useful for determining if a layer has actual mask annotations before saving or exporting.

Returns ​

boolean

True if any voxel is non-zero, false if all zeros.

Example

const vol = new MaskVolume(512, 512, 100);
vol.hasData(); // false (all zeros)

vol.setVoxel(256, 256, 50, 255);
vol.hasData(); // true

const vol = new MaskVolume(512, 512, 100);
vol.hasData(); // false (all zeros)

vol.setVoxel(256, 256, 50, 255);
vol.hasData(); // true

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:844

renderBlended ​

▸ Private renderBlended(pixels, width, height, sliceIndex, axis, colorMap, visibleChannels, opacity): void

Render all visible channels with additive blending.

Each channel contributes its color weighted by intensity × opacity. RGB values are clamped to 255.

Parameters ​

Returns ​

void

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:1267

renderColoredMulti ​

▸ Private renderColoredMulti(pixels, width, height, sliceIndex, axis, colorMap, visibleChannels, opacity): void

Render all visible channels with distinct colors.

The highest-index non-zero visible channel wins (priority-based).

Parameters ​

Returns ​

void

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:1193

renderColoredSingle ​

▸ Private renderColoredSingle(pixels, width, height, sliceIndex, axis, channel, colorMap, opacity): void

Render a single channel with its predefined color.

Alpha is modulated by the voxel intensity and the opacity multiplier.

Parameters ​

Returns ​

void

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:1132

renderGrayscale ​

▸ Private renderGrayscale(pixels, width, height, sliceIndex, axis, channel): void

Render a single channel as grayscale (original behaviour).

Non-zero voxels are fully opaque (A = 255), zero voxels are transparent (A = 0).

Parameters ​

Returns ​

void

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:1079

renderLabelSliceInto ​

▸ renderLabelSliceInto(sliceIndex, axis?, target, channelVisible?, opacity?): void

Render a 1-channel label slice into a pre-allocated RGBA ImageData buffer.

Each voxel stores a label value (0-8). Label 0 = transparent. Labels 1-8 are mapped to colors via MASK_CHANNEL_COLORS, filtered by the channelVisible array.

Parameters ​

Returns ​

void

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:620

resetChannelColors ​

▸ resetChannelColors(channel?): void

Reset the color map for one or all labels to defaults.

Parameters ​

Returns ​

void

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:233

setChannelColor ​

▸ setChannelColor(channel, color): void

Update the color for a specific label/channel in the color map.

For label-based volumes (1-channel), the channel parameter refers to the label value (0-8), not the storage channel index.

Parameters ​

Returns ​

void

Throws

If channel is outside valid label range [0, 8].

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:206

setRawData ​

▸ setRawData(newData): void

Replace the entire backing buffer.

The provided array must have exactly the same length as the current buffer (width × height × depth × channels).

Parameters ​

Returns ​

void

Throws

If the length does not match.

Example

// Restore from a saved snapshot
const saved = new Uint8Array(savedBuffer);
vol.setRawData(saved);

// Restore from a saved snapshot
const saved = new Uint8Array(savedBuffer);
vol.setRawData(saved);

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:769

setSliceFromImageData ​

▸ setSliceFromImageData(sliceIndex, imageData, axis?, channel?): void

Write a 2D ImageData back into the volume for the given axis/slice.

When the volume has 4 channels, all RGBA components are stored (ch0=R, ch1=G, ch2=B, ch3=A) for lossless round-trip. Otherwise, the R channel of each pixel is used as grayscale.

Parameters ​

Returns ​

void

Throws

If sliceIndex is out of bounds.

Throws

If imageData dimensions don't match.

Example

const imgData = ctx.getImageData(0, 0, 512, 512);
vol.setSliceFromImageData(50, imgData, 'z');

const imgData = ctx.getImageData(0, 0, 512, 512);
vol.setSliceFromImageData(50, imgData, 'z');

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:363

setSliceLabelsFromImageData ​

▸ setSliceLabelsFromImageData(sliceIndex, imageData, axis?, activeChannel?, channelVisible?): void

/**

• Store label data from canvas RGBA ImageData into a 1-channel volume.
• For each pixel: matches the RGB color against MASK_CHANNEL_COLORS to
• determine which channel label to store. If no match is found, falls
• back to activeChannel. Transparent pixels (alpha === 0) are stored as 0.
• This is the write counterpart to renderLabelSliceInto.

Parameters ​

Returns ​

void

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:474

setSliceUint8 ​

▸ setSliceUint8(sliceIndex, data, axis?): void

Write a 2D slice from a flat Uint8Array back into the volume.

This is the inverse of getSliceUint8. The data array must have exactly sliceWidth × sliceHeight × channels bytes.

Parameters ​

Returns ​

void

Throws

If sliceIndex is out of bounds.

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:997

setVoxel ​

▸ setVoxel(x, y, z, value, channel?): void

Write a single voxel value.

Values are clamped to the Uint8 range [0, 255] by the typed array.

Parameters ​

Returns ​

void

Throws

If any coordinate is out of bounds.

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:189

validateSliceIndex ​

▸ Private validateSliceIndex(sliceIndex, axis): void

Validate that a slice index is within bounds for the given axis.

Parameters ​

Returns ​

void

Throws

If out of bounds.

Defined in ​

src/Utils/segmentation/core/MaskVolume.ts:1058