DWVv0.37.0
tests/image/maskSegmentHelper.test.jsjavascript
import {describe, test, assert, vi, beforeEach, afterEach} from 'vitest';
import {MaskSegmentHelper} from '../../src/image/maskSegmentHelper.js';
import {MaskSegment} from '../../src/dicom/dicomSegment.js';
import {Size} from '../../src/image/size.js';
import {Spacing} from '../../src/image/spacing.js';
import {Geometry} from '../../src/image/geometry.js';
import {Matrix33} from '../../src/math/matrix.js';
import {Image} from '../../src/image/image.js';
import {Point3D} from '../../src/math/point.js';
import * as loggerModule from '../../src/utils/logger.js';

/**
 * Tests for the 'image/maskSegmentHelper.js' file.
 */

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

/**
 * Build a minimal mock mask image.
 * Only the methods required by MaskSegmentHelper are present;
 * `hasValues` and `updatePaletteColourMap` are Vitest spies so calls
 * can be inspected.
 *
 * @param {object} [meta] Optional initial meta object.
 * @returns {object} Mock mask image.
 */
function makeMockMask(meta = {}) {
  return {
    _meta: meta,
    getMeta() {
      return this._meta;
    },
    setMeta(m) {
      this._meta = m;
    },
    hasValues: vi.fn(() => []),
    updatePaletteColourMap: vi.fn()
  };
}

/**
 * Build a real single-component, single-slice Image for findOverlap tests.
 * Uses Uint8Array so segment numbers (0–255) fit without clamping.
 *
 * @param {number} width Number of columns.
 * @param {number} height Number of rows.
 * @param {number[]} values Pixel values in row-major order.
 * @param {Point3D} [origin] Optional world-space origin (defaults to 0,0,0).
 * @returns {Image} The constructed image.
 */
function makeRealMask(width, height, values, origin = new Point3D(0, 0, 0)) {
  const geometry = new Geometry(
    [origin],
    new Size([width, height, 1]),
    new Spacing([1, 1, 1])
  );
  const img = new Image(geometry, new Uint8Array(values));
  img.setMeta({custom: {segments: []}});
  return img;
}

/**
 * Build a MaskSegment with only number and label set.
 *
 * @param {number} number Segment number.
 * @param {string} [label] Optional label (defaults to `seg-<number>`).
 * @returns {MaskSegment} The constructed segment.
 */
function makeSeg(number, label = `seg-${number}`) {
  return new MaskSegment(number, label, 'MANUAL');
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

describe('image', () => {

  // -------------------------------------------------------------------------
  // Constructor
  // -------------------------------------------------------------------------

  /**
   * Tests that the constructor reads segments from an existing meta object.
   *
   * @function module:tests/image~maskSegmentHelperConstructorExisting
   */
  test('MaskSegmentHelper constructor reads pre-existing segments', () => {
    const seg = makeSeg(1);
    const mask = makeMockMask({custom: {segments: [seg]}});
    const helper = new MaskSegmentHelper(mask);
    assert.equal(helper.getNumberOfSegments(), 1, 'one pre-existing segment');
    assert.equal(helper.getSegment(1), seg, 'segment retrieved correctly');
  });

  /**
   * Tests that the constructor initialises meta.custom when absent.
   *
   * @function module:tests/image~maskSegmentHelperConstructorNoCustom
   */
  test(
    'MaskSegmentHelper constructor initialises meta.custom when absent',
    () => {
      const mask = makeMockMask({});
      new MaskSegmentHelper(mask);
      assert.ok(
        typeof mask.getMeta().custom !== 'undefined', 'custom created'
      );
      assert.deepEqual(
        mask.getMeta().custom.segments, [], 'segments array created'
      );
    }
  );

  /**
   * Tests that the constructor adds a segments array when meta.custom exists
   * but has no segments property.
   *
   * @function module:tests/image~maskSegmentHelperConstructorNoSegments
   */
  test(
    'MaskSegmentHelper constructor adds segments array when missing',
    () => {
      const mask = makeMockMask({custom: {}});
      new MaskSegmentHelper(mask);
      assert.deepEqual(
        mask.getMeta().custom.segments, [], 'segments array added'
      );
    }
  );

  // -------------------------------------------------------------------------
  // getMask
  // -------------------------------------------------------------------------

  /**
   * Tests that getMask returns the mask passed to the constructor.
   *
   * @function module:tests/image~maskSegmentHelperGetMask
   */
  test('MaskSegmentHelper getMask returns the mask image', () => {
    const mask = makeMockMask();
    const helper = new MaskSegmentHelper(mask);
    assert.equal(helper.getMask(), mask);
  });

  // -------------------------------------------------------------------------
  // hasSegment / getSegment / getNumberOfSegments
  // -------------------------------------------------------------------------

  let helper;

  beforeEach(() => {
    helper = new MaskSegmentHelper(makeMockMask());
  });

  afterEach(() => {
    vi.restoreAllMocks();
  });

  /**
   * Tests hasSegment and getSegment for present and absent segments.
   *
   * @function module:tests/image~maskSegmentHelperHasGetSegment
   */
  test('MaskSegmentHelper hasSegment and getSegment', () => {
    const seg = makeSeg(3);
    helper.addSegment(seg);

    assert.ok(helper.hasSegment(3), 'hasSegment true after add');
    assert.notOk(helper.hasSegment(99), 'hasSegment false for unknown');
    assert.equal(helper.getSegment(3), seg, 'getSegment returns segment');
    assert.equal(
      helper.getSegment(99), undefined, 'getSegment returns undefined'
    );
  });

  /**
   * Tests that getNumberOfSegments tracks additions and removals.
   *
   * @function module:tests/image~maskSegmentHelperCount
   */
  test('MaskSegmentHelper getNumberOfSegments tracks add/remove', () => {
    assert.equal(helper.getNumberOfSegments(), 0, 'starts empty');
    helper.addSegment(makeSeg(1));
    helper.addSegment(makeSeg(2));
    assert.equal(helper.getNumberOfSegments(), 2, 'after two adds');
    helper.removeSegment(1);
    assert.equal(helper.getNumberOfSegments(), 1, 'after one remove');
  });

  // -------------------------------------------------------------------------
  // addSegment
  // -------------------------------------------------------------------------

  /**
   * Tests that addSegment calls updatePaletteColourMap when displayRGBValue
   * is set.
   *
   * @function module:tests/image~maskSegmentHelperAddRgb
   */
  test('MaskSegmentHelper addSegment calls updatePaletteColourMap', () => {
    const mask = makeMockMask();
    const h = new MaskSegmentHelper(mask);
    const seg = makeSeg(1);
    seg.displayRGBValue = {r: 255, g: 0, b: 0};

    h.addSegment(seg);

    assert.equal(
      mask.updatePaletteColourMap.mock.calls.length, 1, 'called once'
    );
    assert.equal(
      mask.updatePaletteColourMap.mock.calls[0][0], 1, 'index = segment number'
    );
    assert.deepEqual(
      mask.updatePaletteColourMap.mock.calls[0][1],
      {r: 255, g: 0, b: 0},
      'colour passed through'
    );
  });

  /**
   * Tests that addSegment does not add a segment with a duplicate number.
   *
   * @function module:tests/image~maskSegmentHelperAddDuplicate
   */
  test('MaskSegmentHelper addSegment ignores duplicate segment number', () => {
    const warnSpy = vi.spyOn(loggerModule.logger, 'warn')
      .mockImplementation(() => {});

    helper.addSegment(makeSeg(1));
    helper.addSegment(makeSeg(1)); // duplicate
    assert.equal(
      helper.getNumberOfSegments(), 1, 'still one segment after duplicate add'
    );

    assert.equal(warnSpy.mock.calls.length, 1, 'warning on addSegment');
    assert.ok(warnSpy.mock.calls[0][0].includes('1'),
      'warning mentions the segment number');
  });

  // -------------------------------------------------------------------------
  // removeSegment
  // -------------------------------------------------------------------------

  /**
   * Tests that removeSegment removes an existing segment.
   *
   * @function module:tests/image~maskSegmentHelperRemove
   */
  test('MaskSegmentHelper removeSegment removes the correct segment', () => {
    helper.addSegment(makeSeg(1));
    helper.addSegment(makeSeg(2));
    helper.removeSegment(1);
    assert.notOk(helper.hasSegment(1), 'segment 1 removed');
    assert.ok(helper.hasSegment(2), 'segment 2 still present');
  });

  /**
   * Tests that removeSegment is a no-op for an unknown segment number.
   *
   * @function module:tests/image~maskSegmentHelperRemoveUnknown
   */
  test('MaskSegmentHelper removeSegment is a no-op for unknown number', () => {
    const warnSpy = vi.spyOn(loggerModule.logger, 'warn')
      .mockImplementation(() => {});

    helper.addSegment(makeSeg(1));
    helper.removeSegment(99); // no-op
    assert.equal(helper.getNumberOfSegments(), 1, 'count unchanged');

    assert.equal(warnSpy.mock.calls.length, 1, 'warning on removeSegment');
    assert.ok(warnSpy.mock.calls[0][0].includes('99'),
      'warning mentions the segment number');
  });

  // -------------------------------------------------------------------------
  // updateSegment
  // -------------------------------------------------------------------------

  /**
   * Tests that updateSegment replaces an existing segment in-place.
   *
   * @function module:tests/image~maskSegmentHelperUpdate
   */
  test('MaskSegmentHelper updateSegment replaces an existing segment', () => {
    const original = makeSeg(1, 'original');
    const updated = makeSeg(1, 'updated');
    helper.addSegment(original);
    helper.updateSegment(updated);
    assert.equal(helper.getSegment(1).label, 'updated', 'label replaced');
  });

  /**
   * Tests that updateSegment is a no-op for an unknown segment number.
   *
   * @function module:tests/image~maskSegmentHelperUpdateUnknown
   */
  test('MaskSegmentHelper updateSegment is a no-op for unknown number', () => {
    const warnSpy = vi.spyOn(loggerModule.logger, 'warn')
      .mockImplementation(() => {});

    helper.addSegment(makeSeg(1));
    helper.updateSegment(makeSeg(99)); // no-op
    assert.equal(helper.getNumberOfSegments(), 1, 'count unchanged');

    assert.equal(warnSpy.mock.calls.length, 1, 'warning on updateSegment');
    assert.ok(warnSpy.mock.calls[0][0].includes('99'),
      'warning mentions the segment number');
  });

  // -------------------------------------------------------------------------
  // maskHasSegments
  // -------------------------------------------------------------------------

  /**
   * Tests that maskHasSegments passes displayValue to hasValues.
   *
   * @function module:tests/image~maskSegmentHelperMaskHasSegmentsDisplay
   */
  test(
    'MaskSegmentHelper maskHasSegments uses displayValue when available',
    () => {
      const mask = makeMockMask();
      mask.hasValues.mockReturnValue([true, false]);
      const h = new MaskSegmentHelper(mask);

      const seg1 = makeSeg(1);
      seg1.displayValue = 10;
      const seg2 = makeSeg(2);
      seg2.displayValue = 20;
      h.addSegment(seg1);
      h.addSegment(seg2);

      const result = h.maskHasSegments([1, 2]);

      assert.deepEqual(
        mask.hasValues.mock.calls[0][0], [10, 20], 'displayValues forwarded'
      );
      assert.deepEqual(result, [true, false], 'result from hasValues');
    }
  );

  /**
   * Tests that maskHasSegments falls back to segment.number when displayValue
   * is absent.
   *
   * @function module:tests/image~maskSegmentHelperMaskHasSegmentsNumber
   */
  test(
    'MaskSegmentHelper maskHasSegments falls back to segment.number',
    () => {
      const mask = makeMockMask();
      mask.hasValues.mockReturnValue([true]);
      const h = new MaskSegmentHelper(mask);
      h.addSegment(makeSeg(5)); // no displayValue

      h.maskHasSegments([5]);

      assert.deepEqual(
        mask.hasValues.mock.calls[0][0], [5], 'number used as fallback'
      );
    }
  );

  /**
   * Tests that maskHasSegments inserts false for unknown segment numbers.
   *
   * @function module:tests/image~maskSegmentHelperMaskHasSegmentsUnknown
   */
  test(
    'MaskSegmentHelper maskHasSegments returns false for unknown segments',
    () => {
      const warnSpy = vi.spyOn(loggerModule.logger, 'warn')
        .mockImplementation(() => {});

      const mask = makeMockMask();
      mask.hasValues.mockReturnValue([true]);
      const h = new MaskSegmentHelper(mask);
      h.addSegment(makeSeg(1));

      // numbers[0]=99 (unknown), numbers[1]=1 (known)
      const result = h.maskHasSegments([99, 1]);

      assert.equal(result[0], false, 'unknown segment → false');
      assert.equal(result[1], true, 'known segment → forwarded from hasValues');

      assert.equal(warnSpy.mock.calls.length, 1, 'warning on maskHasSegments');
      assert.ok(warnSpy.mock.calls[0][0].includes('99'),
        'warning mentions the segment number');
    }
  );

  // -------------------------------------------------------------------------
  // findOverlap
  // -------------------------------------------------------------------------

  /**
   * Tests that findOverlap returns empty when neither mask has labelled voxels.
   *
   * @function module:tests/image~maskSegmentHelperFindOverlapEmpty
   */
  test('MaskSegmentHelper findOverlap returns empty for blank masks', () => {
    const mask1 = makeRealMask(3, 1, [0, 0, 0]);
    const mask2 = makeRealMask(3, 1, [0, 0, 0]);
    const h1 = new MaskSegmentHelper(mask1);
    const h2 = new MaskSegmentHelper(mask2);
    assert.deepEqual(h1.findOverlap(h2), {}, 'empty overlap map');
  });

  /**
   * Tests findOverlap when two masks share the same geometry and identical
   * pixel values — every labelled voxel overlaps 100%.
   *
   * @function module:tests/image~maskSegmentHelperFindOverlapIdentical
   */
  test(
    'MaskSegmentHelper findOverlap: identical masks give 100% overlap',
    () => {
      // mask: [1, 1, 2]  — segment 1 covers 2 voxels, segment 2 covers 1
      const mask1 = makeRealMask(3, 1, [1, 1, 2]);
      const mask2 = makeRealMask(3, 1, [1, 1, 2]);
      const seg1 = makeSeg(1, 'bone');
      const seg2 = makeSeg(2, 'muscle');
      const h1 = new MaskSegmentHelper(mask1);
      const h2 = new MaskSegmentHelper(mask2);
      h1.addSegment(seg1);
      h1.addSegment(seg2);
      h2.addSegment(seg1);
      h2.addSegment(seg2);

      const result = h1.findOverlap(h2);

      assert.equal(result[1].count, 2, 'seg1 total voxel count');
      assert.equal(result[1].label, 'bone', 'seg1 label');
      assert.equal(
        result[1].overlap[1].count, 2, 'seg1 vs seg1 overlap count'
      );
      assert.equal(
        result[1].overlap[1].percentage, 100, 'seg1 vs seg1 percentage'
      );
      assert.equal(
        result[2].overlap[2].percentage, 100, 'seg2 fully overlaps'
      );
    }
  );

  /**
   * Tests findOverlap when the two masks have no overlapping labelled voxels.
   *
   * @function module:tests/image~maskSegmentHelperFindOverlapNone
   */
  test('MaskSegmentHelper findOverlap: non-overlapping masks', () => {
    // mask1: seg 1 at pixel 0; mask2: seg 2 at pixel 1 (no shared voxels)
    const mask1 = makeRealMask(3, 1, [1, 0, 0]);
    const mask2 = makeRealMask(3, 1, [0, 2, 0]);
    const h1 = new MaskSegmentHelper(mask1);
    const h2 = new MaskSegmentHelper(mask2);
    h1.addSegment(makeSeg(1));
    h2.addSegment(makeSeg(2));

    const result = h1.findOverlap(h2);

    assert.equal(result[1].count, 1, 'seg1 voxel count');
    assert.deepEqual(result[1].overlap, {}, 'no overlap entries');
  });

  /**
   * Tests findOverlap with partial overlap between segments.
   *
   * @function module:tests/image~maskSegmentHelperFindOverlapPartial
   */
  test('MaskSegmentHelper findOverlap: partial overlap gives correct %', () => {
    // mask1: seg 1 at pixels 0,1,2 (3 voxels)
    // mask2: seg 2 at pixels 1,2   (overlaps 2 of the 3 voxels)
    const mask1 = makeRealMask(3, 1, [1, 1, 1]);
    const mask2 = makeRealMask(3, 1, [0, 2, 2]);
    const h1 = new MaskSegmentHelper(mask1);
    const h2 = new MaskSegmentHelper(mask2);
    h1.addSegment(makeSeg(1));
    h2.addSegment(makeSeg(2));

    const result = h1.findOverlap(h2);

    assert.equal(result[1].count, 3, 'seg1 total voxels');
    assert.equal(
      result[1].overlap[2].count, 2, 'two voxels overlap with seg2'
    );
    assert.closeTo(
      result[1].overlap[2].percentage,
      66.67,
      0.01,
      'overlap percentage ≈ 66.67%'
    );
  });

  /**
   * Tests for {@link MaskSegmentHelper} findOverlap.
   *
   * @function module:tests/image~maskSegmentHelperFindOverlap
   */
  test('MaskSegmentHelper findOverlap', () => {
    const imgOrigins = [new Point3D(0, 0, 0)];
    const imgSpacing = new Spacing([1, 1, 1]);
    const imgSize = new Size([4, 4, 2]);
    /* eslint-disable @stylistic/js/array-element-newline */
    const o = [
      1, 0, 0,
      0, 0, 1,
      0, 1, 0,
    ];
    /* eslint-enable @stylistic/js/array-element-newline */
    const imgOrientation = new Matrix33(o);
    const imgGeometry =
      new Geometry(
        imgOrigins,
        imgSize,
        imgSpacing,
        imgOrientation
      );
    /* eslint-disable @stylistic/js/array-element-newline */
    const imgBuffer0 = new Uint8Array([
      1, 1, 0, 0,
      1, 1, 0, 0,
      0, 0, 2, 2,
      0, 0, 2, 2,

      1, 1, 0, 0,
      1, 1, 0, 0,
      0, 0, 0, 3,
      0, 0, 3, 3
    ]);
    /* eslint-enable @stylistic/js/array-element-newline */
    const image0 = new Image(imgGeometry, imgBuffer0);
    image0.setMeta({
      custom: {
        segments: [
          {
            number: 1,
            label: 'label1'
          },
          {
            number: 2,
            label: 'label2'
          },
          {
            number: 3,
            label: 'label3'
          }
        ]
      }
    });
    const segmentHelper0 = new MaskSegmentHelper(image0);

    /* eslint-disable @stylistic/js/array-element-newline */
    const imgBuffer1 = new Uint8Array([
      2, 2, 3, 3,
      2, 1, 1, 3,
      4, 1, 1, 2,
      4, 4, 2, 2,

      2, 2, 3, 3,
      2, 1, 1, 3,
      4, 1, 1, 2,
      4, 4, 2, 2
    ]);
    /* eslint-enable @stylistic/js/array-element-newline */
    const image1 = new Image(imgGeometry, imgBuffer1);
    image1.setMeta({
      custom: {
        segments: [
          {
            number: 1,
            label: 'label1'
          },
          {
            number: 2,
            label: 'label2'
          },
          {
            number: 3,
            label: 'label3'
          },
          {
            number: 4,
            label: 'label4'
          }
        ]
      }
    });
    const segmentHelper1 = new MaskSegmentHelper(image1);

    const overlap1 = segmentHelper1.findOverlap(segmentHelper0);

    // Undefined tests

    assert.notStrictEqual(
      typeof overlap1,
      'undefined',
      'Expected overlaps returned for find overlap'
    );

    assert.notStrictEqual(
      typeof overlap1[1],
      'undefined',
      'Expected overlaps on label 1 returned for find overlap'
    );
    assert.notStrictEqual(
      typeof overlap1[2],
      'undefined',
      'Expected overlaps on label 2 returned for find overlap'
    );
    assert.notStrictEqual(
      typeof overlap1[3],
      'undefined',
      'Expected overlaps on label 3 returned for find overlap'
    );
    assert.notStrictEqual(
      typeof overlap1[4],
      'undefined',
      'Expected overlaps on label 4 returned for find overlap'
    );

    assert.notStrictEqual(
      typeof overlap1[1].overlap[1],
      'undefined',
      'Expected overlaps on label 1 for label 1 returned for find overlap'
    );
    assert.notStrictEqual(
      typeof overlap1[1].overlap[2],
      'undefined',
      'Expected overlaps on label 1 for label 2 returned for find overlap'
    );
    assert.strictEqual(
      typeof overlap1[1].overlap[3],
      'undefined',
      'Expected no overlaps on label 1 for label 3 returned for find overlap'
    );

    assert.notStrictEqual(
      typeof overlap1[2].overlap[1],
      'undefined',
      'Expected overlaps on label 2 for label 1 returned for find overlap'
    );
    assert.notStrictEqual(
      typeof overlap1[2].overlap[2],
      'undefined',
      'Expected overlaps on label 2 for label 2 returned for find overlap'
    );
    assert.notStrictEqual(
      typeof overlap1[2].overlap[3],
      'undefined',
      'Expected overlaps on label 2 for label 3 returned for find overlap'
    );

    assert.equal(
      Object.keys(overlap1[3].overlap).length,
      0,
      'Expected no overlaps on label 3 returned for find overlap'
    );
    assert.equal(
      Object.keys(overlap1[4].overlap).length,
      0,
      'Expected no overlaps on label 4 returned for find overlap'
    );

    // Total count tests

    assert.equal(
      overlap1[1].count,
      8,
      'Expected count on label 1'
    );

    assert.equal(
      overlap1[2].count,
      12,
      'Expected count on label 2'
    );

    assert.equal(
      overlap1[3].count,
      6,
      'Expected count on label 3'
    );

    assert.equal(
      overlap1[4].count,
      6,
      'Expected count on label 4'
    );

    // Overlap count tests

    assert.equal(
      overlap1[1].overlap[1].count,
      2,
      'Expected count on label 1 for label 1 for find overlap'
    );
    assert.equal(
      overlap1[1].overlap[2].count,
      1,
      'Expected count on label 1 for label 2 for find overlap'
    );

    assert.equal(
      overlap1[2].overlap[1].count,
      6,
      'Expected count on label 2 for label 1 for find overlap'
    );
    assert.equal(
      overlap1[2].overlap[2].count,
      3,
      'Expected count on label 2 for label 2 for find overlap'
    );
    assert.equal(
      overlap1[2].overlap[3].count,
      3,
      'Expected count on label 2 for label 3 for find overlap'
    );

    // Overlap percentage tests

    assert.equal(
      overlap1[1].overlap[1].percentage,
      25,
      'Expected percentage on label 1 for label 1 for find overlap'
    );
    assert.equal(
      overlap1[1].overlap[2].percentage,
      12.5,
      'Expected percentage on label 1 for label 2 for find overlap'
    );

    assert.equal(
      overlap1[2].overlap[1].percentage,
      50,
      'Expected percentage on label 2 for label 1 for find overlap'
    );
    assert.equal(
      overlap1[2].overlap[2].percentage,
      25,
      'Expected percentage on label 2 for label 2 for find overlap'
    );
    assert.equal(
      overlap1[2].overlap[3].percentage,
      25,
      'Expected percentage on label 2 for label 3 for find overlap'
    );

  });

});