src/image/segmentCollection.jsjavascript
import {ImageContour} from './imageContour.js';
import {logger} from '../utils/logger.js';
/**
* @import {Geometry} from './geometry.js';
* @import {Size} from './size.js';
* @import {MaskSegment} from '../dicom/dicomSegment.js';
* @import {MaskSegmentViewHelper} from './maskSegmentViewHelper.js';
*/
/**
* Create ROI slice buffers.
*
* @param {Uint8Array} imageBuffer The mask image buffer.
* @param {number[]} segmentNumbers The mask segment numbers.
* @param {number} sliceSize The size of a slice.
* @param {number} sliceOffset The slice offset.
* @returns {Record<number, Uint8Array>} The ROI slice image buffers,
* indexed by segment index (segment.number - 1).
*/
function createRoiSliceBuffers(
imageBuffer,
segmentNumbers,
sliceSize,
sliceOffset
) {
// create binary mask buffers
/** @type {Record<number, Uint8Array>} */
const buffers = {};
for (let o = 0; o < sliceSize; ++o) {
const pixelValue = imageBuffer[sliceOffset + o];
for (const segmentNumber of segmentNumbers) {
if (pixelValue === segmentNumber) {
const segmentIndex = segmentNumber - 1;
if (buffers[segmentIndex] === undefined) {
buffers[segmentIndex] = new Uint8Array(sliceSize);
}
buffers[segmentIndex][o] = 1;
}
}
}
return buffers;
}
/**
* Create ROI buffers.
*
* @param {Uint8Array} imageBuffer The mask image buffer.
* @param {Geometry} geometry The mask geometry.
* @param {number[]} segmentNumbers The mask segment numbers.
* @returns {Record<string, Record<number, Uint8Array>>} The ROI buffers,
* indexed by segment index (segment.number - 1) and slice index.
*/
function createRoiBuffers(imageBuffer, geometry, segmentNumbers) {
const size = geometry.getSize();
// image buffer to multi frame
const sliceSize = size.getDimSize(2);
/** @type {Record<string, Record<number, Uint8Array>>} */
const roiBuffers = {};
for (let k = 0; k < size.get(2); ++k) {
const sliceOffset = k * sliceSize;
// create slice buffers
const buffers = createRoiSliceBuffers(
imageBuffer, segmentNumbers, sliceSize, sliceOffset);
// store slice buffers
const keys0 = Object.keys(buffers);
for (const key0 of keys0) {
if (roiBuffers[key0] === undefined) {
roiBuffers[key0] = {};
}
// ordering by slice index (follows posPat)
roiBuffers[key0][k] = buffers[key0];
}
}
return roiBuffers;
}
/**
* Collection of mask segments: stores per-segment, per-slice pixel data
* and segment metadata. Builds the combined label map on demand.
* TODO: check if mergeable with MaskSegmentHelper.
*/
export class SegmentCollection {
/**
* @type {Geometry}
*/
#geometry;
/**
* Per-segment pixel data: only slices that carry actual frame data.
* Type: Map<segNumber, Map<sliceIndex, Uint8Array>>.
*
* @type {Map<number, Map<number, Uint8Array>>}
*/
#segments = new Map();
/**
* Flag set to true when two segments share at least one voxel.
*
* @type {boolean}
*/
#hasOverlap = false;
/**
* Lazy cached combined label map.
*
* @type {Uint8Array|undefined}
*/
#labelMap;
/**
* @param {Geometry} geometry The mask geometry, used to size the label map.
*/
constructor(geometry) {
this.#geometry = geometry;
}
/**
* Get all the segments.
*
* @returns {Map<number, Map<number, Uint8Array>>} The segment buffers,
* indexed by segment number and slice index.
*/
getAll() {
return this.#segments;
}
/**
* Set the label map directly.
* Used when the buffer already exists, for brush-painted masks.
*
* @param {Uint8Array} buffer The label map buffer.
*/
setLabelMap(buffer) {
this.#labelMap = buffer;
}
/**
* Add pixel data for one DICOM frame to the appropriate segment and slice.
* Allocates a Uint8Array(sliceSize) on first use for each
* (segNumber, sliceIndex) pair; merges if the same pair appears again.
*
* @param {number} segNumber The segment number.
* @param {Uint8Array} pixelBuffer The raw DICOM pixel buffer.
* @param {number} frameOffset Offset of this frame within pixelBuffer.
* @param {number} sliceIndex The slice index in the full label map geometry.
* @param {number} sliceSize Number of pixels per slice (ncols * nrows).
* @param {number} value The value to write for non-zero pixels.
*/
addFrame(segNumber, pixelBuffer, frameOffset, sliceIndex, sliceSize, value) {
if (!this.#segments.has(segNumber)) {
this.#segments.set(segNumber, new Map());
}
const sliceMap = this.#segments.get(segNumber);
if (!sliceMap.has(sliceIndex)) {
sliceMap.set(sliceIndex, new Uint8Array(sliceSize));
}
const sliceBuf = sliceMap.get(sliceIndex);
for (let l = 0; l < sliceSize; ++l) {
if (pixelBuffer[frameOffset + l] !== 0) {
sliceBuf[l] = value;
}
}
}
/**
* Build and return the combined label map (lazy cached).
* Iterates segments in insertion order so lower segment numbers win
* at overlapping positions. Sets the hasOverlap flag if any voxel
* already carries a different segment's value.
*
* @returns {Uint8Array} The full-volume label map.
*/
getLabelMap() {
if (typeof this.#labelMap !== 'undefined') {
return this.#labelMap;
}
const sliceSize = this.#geometry.getSize().getDimSize(2);
const totalSize = this.#geometry.getSize().getTotalSize();
const labelMap = new Uint8Array(totalSize);
for (const [, sliceMap] of this.#segments) {
for (const [sliceIndex, sliceBuf] of sliceMap) {
const offset = sliceIndex * sliceSize;
for (let l = 0; l < sliceSize; ++l) {
if (sliceBuf[l] !== 0) {
if (labelMap[offset + l] !== 0 &&
labelMap[offset + l] !== sliceBuf[l]) {
this.#hasOverlap = true;
}
if (labelMap[offset + l] === 0) {
labelMap[offset + l] = sliceBuf[l];
}
}
}
}
}
if (this.#hasOverlap) {
logger.warn('SegmentCollection: detected overlapping segments');
}
this.#labelMap = labelMap;
return labelMap;
}
/**
* Split a flat label map offset into its slice index and the local
* (within-slice) offset used to index a per-segment slice buffer.
*
* @param {number} offset The offset in the label map.
* @returns {{sliceIndex: number, localOffset: number}} The split offset.
*/
#splitOffset(offset) {
const sliceSize = this.#geometry.getSize().getDimSize(2);
const sliceIndex = Math.floor(offset / sliceSize);
return {
sliceIndex,
localOffset: offset - (sliceIndex * sliceSize)
};
}
/**
* Update the per-segment, per-slice buffers after a direct edit to the
* shared label map (for example brush painting on a mask loaded from
* DICOM, where the label map and the per-segment buffers are otherwise
* two separate structures). No-op when this collection has no
* per-segment data (brush-created masks), since the label map is
* already the source of truth in that case.
*
* @param {number} offset The offset in the label map that changed.
* @param {number} previousValue The segment number previously at offset.
* @param {number} newValue The segment number now at offset.
*/
updateAtOffset(offset, previousValue, newValue) {
if (this.#segments.size === 0 || previousValue === newValue) {
return;
}
const sliceSize = this.#geometry.getSize().getDimSize(2);
const {sliceIndex, localOffset} = this.#splitOffset(offset);
if (previousValue !== 0) {
const sliceBuf = this.#segments.get(previousValue)?.get(sliceIndex);
if (typeof sliceBuf !== 'undefined') {
sliceBuf[localOffset] = 0;
}
}
if (newValue !== 0) {
if (!this.#segments.has(newValue)) {
this.#segments.set(newValue, new Map());
}
const sliceMap = this.#segments.get(newValue);
if (!sliceMap.has(sliceIndex)) {
sliceMap.set(sliceIndex, new Uint8Array(sliceSize));
}
sliceMap.get(sliceIndex)[localOffset] = newValue;
}
}
/**
* Re-index the per-segment, per-slice buffers after a slice insertion
* (from Image#appendSlice) that shifted existing slice
* content to make room for new slices. Unlike the shared label map
* (which aliases the image buffer, so the raw byte-level shift already
* covers it for free), `#segments` is keyed by slice index rather than
* buffer offset, so an insertion before an existing slice leaves its
* entries silently pointing at the wrong (pre-shift) slice index unless
* they are explicitly re-keyed here.
*
* @param {number} sliceIndexThreshold Slices at or after this index
* (numbering as it was *before* the insertion) are shifted.
* @param {number} numberOfSlices Number of slices inserted.
*/
shiftSlices(sliceIndexThreshold, numberOfSlices) {
if (this.#segments.size === 0 || numberOfSlices === 0) {
return;
}
for (const sliceMap of this.#segments.values()) {
const toShift = [...sliceMap.keys()]
.filter(sliceIndex => sliceIndex >= sliceIndexThreshold);
for (const sliceIndex of toShift) {
const sliceBuf = sliceMap.get(sliceIndex);
sliceMap.delete(sliceIndex);
sliceMap.set(sliceIndex + numberOfSlices, sliceBuf);
}
}
// the label map cache itself needs no update (it aliases the already
// shifted image buffer), but the union contour cache is keyed by
// segment content and would otherwise stay stale after a shift
this.#unionContour = undefined;
this.#unionContourKey = '';
}
/**
* Get the value that a different, non-excluded segment holds at a given
* label map offset. Used when deleting a segment to restore a voxel that
* also belonged to another (overlapping) segment instead of losing that
* other segment's presence there. Segments are checked in insertion
* order, consistent with the first-wins policy used by {@link
* SegmentCollection#getLabelMap}.
*
* @param {number} offset The offset in the label map.
* @param {number} excludeSegmentNumber The segment number to ignore.
* @returns {number} The other segment's stored value at that offset,
* or 0 if no other segment covers it.
*/
getOtherValueAtOffset(offset, excludeSegmentNumber) {
if (this.#segments.size === 0) {
return 0;
}
const {sliceIndex, localOffset} = this.#splitOffset(offset);
for (const [segNumber, sliceMap] of this.#segments) {
if (segNumber === excludeSegmentNumber) {
continue;
}
const sliceBuf = sliceMap.get(sliceIndex);
if (typeof sliceBuf !== 'undefined' && sliceBuf[localOffset] !== 0) {
return sliceBuf[localOffset];
}
}
return 0;
}
/**
* Create a deep copy of this collection: per-segment/per-slice buffers
* and the overlap flag are copied, the lazily-built label map and union
* contour caches are left unset (they rebuild on demand from the copied
* per-segment data, same as a freshly constructed collection).
*
* @returns {SegmentCollection} The copy.
*/
clone() {
const copy = new SegmentCollection(this.#geometry);
for (const [segNumber, sliceMap] of this.#segments) {
const copiedSliceMap = new Map();
for (const [sliceIndex, sliceBuf] of sliceMap) {
copiedSliceMap.set(sliceIndex, sliceBuf.slice());
}
copy.#segments.set(segNumber, copiedSliceMap);
}
copy.#hasOverlap = this.#hasOverlap;
return copy;
}
/**
* Check whether any two segments share at least one voxel.
*
* @returns {boolean} True if overlap was detected.
*/
getHasOverlap() {
// ensure label map is built and hasOverlap flag is set
this.getLabelMap();
return this.#hasOverlap;
}
/**
* Get the segment buffers. Using input image and segments since they
* could have been modified (for example by brush).
*
* When per-segment data is available (MaskFactory path), builds ROI buffers
* directly from #segments so that overlap pixels for every segment are
* included. Falls back to label-map reconstruction for masks created via
* setupSegmentCollection (brush path), where #segments is empty and the
* label map is the only source of truth.
*
* @param {MaskSegment[]} segments The mask segments.
* @returns {Record<string, Record<number, Uint8Array>>} The segment buffers,
* indexed by segment index (segment.number - 1) and slice index.
*/
getSegmentBuffers(segments) {
if (this.#segments.size === 0) {
// brush path: no per-segment data, reconstruct from label map;
// when segments metadata is absent, discover numbers from the buffer
let segNumbers = segments.map(segment => segment.number);
if (segNumbers.length === 0 && typeof this.#labelMap !== 'undefined') {
const found = new Set();
for (let i = 0; i < this.#labelMap.length; ++i) {
if (this.#labelMap[i] !== 0) {
found.add(this.#labelMap[i]);
}
}
segNumbers = Array.from(found);
}
return createRoiBuffers(this.#labelMap, this.#geometry, segNumbers);
}
// MaskFactory path: use per-segment per-slice buffers directly so that
// pixels in overlap zones are present for every segment, not just the
// first one stored in the label map
/** @type {Record<string, Record<number, Uint8Array>>} */
const roiBuffers = {};
for (const segment of segments) {
const segmentIndex = segment.number - 1;
const sliceMap = this.#segments.get(segment.number);
if (typeof sliceMap === 'undefined') {
continue;
}
for (const [sliceIndex, sliceBuf] of sliceMap) {
const binarySlice = new Uint8Array(sliceBuf.length);
let isEmpty = true;
for (let l = 0; l < sliceBuf.length; ++l) {
if (sliceBuf[l] !== 0) {
binarySlice[l] = 1;
isEmpty = false;
}
}
// skip slices emptied by edits (for example brush erase),
// consistent with the label map path
if (isEmpty) {
continue;
}
if (roiBuffers[segmentIndex] === undefined) {
roiBuffers[segmentIndex] = {};
}
roiBuffers[segmentIndex][sliceIndex] = binarySlice;
}
}
return roiBuffers;
}
/**
* Cached union contour (distance-to-border for visible segments union).
*
* @type {ImageContour|undefined}
*/
#unionContour;
/**
* Visibility key for the cached union contour.
* Sorted hidden segment numbers joined by comma.
*
* @type {string}
*/
#unionContourKey = '';
/**
* Get the union ImageContour for the current visibility state,
* building it if the set of hidden segments has changed.
*
* @param {MaskSegmentViewHelper|undefined} segmentViewHelper
* Hidden-segment tracker.
* @param {Size} imageSize The image size.
* @returns {ImageContour} The union ImageContour.
*/
getOrBuildUnionContour(segmentViewHelper, imageSize) {
const hidden = [];
for (const [segNum] of this.#segments) {
if (segmentViewHelper?.isHidden(segNum)) {
hidden.push(segNum);
}
}
const key = hidden.sort().join(',');
if (typeof this.#unionContour !== 'undefined' &&
key === this.#unionContourKey) {
return this.#unionContour;
}
const sliceSize = imageSize.getDimSize(2);
const unionBuffer = new Uint8Array(imageSize.getTotalSize());
for (const [segNum, sliceMap] of this.#segments) {
if (segmentViewHelper?.isHidden(segNum)) {
continue;
}
for (const [sliceIndex, sliceBuf] of sliceMap) {
const offset = sliceIndex * sliceSize;
for (let l = 0; l < sliceSize; ++l) {
if (sliceBuf[l] !== 0) {
unionBuffer[offset + l] = 1;
}
}
}
}
this.#unionContour = new ImageContour();
this.#unionContour.initialize(unionBuffer, imageSize);
this.#unionContourKey = key;
return this.#unionContour;
}
}