DWVv0.37.0
tests/image/rtStructFactory.test.jsjavascript
import {describe, test, assert, vi, afterEach} from 'vitest';
import {
  getElementsFromSimpleTagValues
} from '../../src/dicom/simpleTagValues.js';
import {getRTStructFromElements} from '../../src/dicom/dicomRTStruct.js';
import {
  getReferencedSeriesUIDFromRTStruct
} from '../../src/dicom/dicomImage.js';
import {RtStructFactory} from '../../src/image/rtStructFactory.js';
import {Image} from '../../src/image/image.js';
import {Geometry} from '../../src/image/geometry.js';
import {Size} from '../../src/image/size.js';
import {Spacing} from '../../src/image/spacing.js';
import {Point3D} from '../../src/math/point.js';
import * as loggerModule from '../../src/utils/logger.js';

import syntheticImgData from '/tests/data/synthetic-img.json';
import syntheticRtssData from '/tests/data/synthetic-rtss.json';

// test-img-00 (img) is used throughout as a reference image, alongside
// the RTSTRUCT entries under test.
const syntheticData = [...syntheticImgData, ...syntheticRtssData];

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

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

/**
 * Build a minimal reference Image matching test-img-00 geometry:
 * 32×32×1, unit spacing, identity orientation, origin at (0,0,0).
 *
 * @returns {Image} The reference image.
 */
function buildRefImage() {
  const config = syntheticData.find(c => c.name === 'test-img-00');
  const tags = config.tags;
  const geo = new Geometry(
    [new Point3D(0, 0, 0)],
    new Size([tags.Columns, tags.Rows, 1]),
    new Spacing([1, 1, 1])
  );
  const buffer = new Uint16Array(tags.Columns * tags.Rows);
  const image = new Image(geo, buffer, [tags.SOPInstanceUID]);
  image.setMeta({SeriesInstanceUID: tags.SeriesInstanceUID});
  return image;
}

/**
 * Parse synthetic RTSS config tags into DICOM data elements.
 *
 * @param {object} config A synthetic-data entry.
 * @returns {Record<string, object>} DICOM data elements.
 */
function configToElements(config) {
  return getElementsFromSimpleTagValues(structuredClone(config.tags));
}

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

describe('RtStructFactory', () => {

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

  // -------------------------------------------------------------------------
  // Non-overlapping squares — test-rtss-00
  // Square 1: col=4..10, row=4..10 | Square 2: col=12..18, row=12..18
  // -------------------------------------------------------------------------

  test('create: non-overlapping squares, no overlap flag', () => {
    const config = syntheticData.find(c => c.name === 'test-rtss-00');
    const factory = new RtStructFactory();
    const image = factory.create(configToElements(config), buildRefImage());

    const meta = image.getMeta();
    const segments = meta.custom.segments;
    assert.equal(segments.length, 2, 'two segments created');
    assert.equal(segments[0].label, 'Square1', 'segment 1 name');
    assert.equal(segments[1].label, 'Square2', 'segment 2 name');
    assert.equal(image.getHasOverlap(), false, 'no overlap detected');
    const refConfig = syntheticData.find(c => c.name === 'test-img-00');
    assert.equal(
      image.getMaskReferencedSeriesUID(),
      refConfig.tags.SeriesInstanceUID,
      'referencedSeriesUID matches test-img-00'
    );
  });

  test('create: frame of reference UID', () => {
    const config = syntheticData.find(c => c.name === 'test-rtss-00');
    const forUid = config.tags.FrameOfReferenceUID;
    const factory = new RtStructFactory();

    // root Frame of Reference module
    const image0 = factory.create(configToElements(config), buildRefImage());
    assert.equal(image0.getMeta().FrameOfReferenceUID, forUid,
      'frame of reference UID from root');

    // no Frame of Reference module (optional in RT Structure Set IOD):
    // use ReferencedFrameOfReferenceSequence
    const tags1 = structuredClone(config.tags);
    delete tags1.FrameOfReferenceUID;
    const image1 = factory.create(
      getElementsFromSimpleTagValues(tags1), buildRefImage());
    assert.equal(image1.getMeta().FrameOfReferenceUID, forUid,
      'frame of reference UID from referenced sequence');

    // none
    const warnSpy = vi.spyOn(loggerModule.logger, 'warn')
      .mockImplementation(() => {});
    const tags2 = structuredClone(tags1);
    delete tags2.ReferencedFrameOfReferenceSequence.value[0]
      .FrameOfReferenceUID;
    const image2 = factory.create(
      getElementsFromSimpleTagValues(tags2), buildRefImage());
    assert.isUndefined(image2.getMeta().FrameOfReferenceUID,
      'no frame of reference UID');
    assert.ok(
      warnSpy.mock.calls.some(
        ([msg]) => msg === 'Loaded RT STRUCT has no FrameOfReferenceUID.'
      ),
      'no frame of reference UID warning logged'
    );
  });

  test(
    'create: non-overlapping squares pixel values in label map - ' +
    '#DWV-REQ-IO-06-002 Load DICOM RTSTRUCT',
    () => {
      const config = syntheticData.find(c => c.name === 'test-rtss-00');
      const factory = new RtStructFactory();
      const image = factory.create(configToElements(config), buildRefImage());

      const buf = image.getBuffer();
      const width = 32;
      // square 1 center at (col=7, row=7) → offset 7*32+7 = 231
      assert.equal(buf[7 * width + 7], 1, 'square 1 center is segment 1');
      // square 2 center at (col=15, row=15) → offset 15*32+15 = 495
      assert.equal(buf[15 * width + 15], 2, 'square 2 center is segment 2');
      // gap between the two squares
      assert.equal(buf[11 * width + 11], 0,
        'gap between squares is background');
    });

  test(
    'create: non-overlapping squares segment collection - ' +
    '#DWV-REQ-IO-06-002 Load DICOM RTSTRUCT',
    () => {
      const config = syntheticData.find(c => c.name === 'test-rtss-00');
      const factory = new RtStructFactory();
      const image = factory.create(configToElements(config), buildRefImage());

      const collection = image.getSegmentCollection();
      assert.ok(collection !== undefined, 'segment collection exists');

      const all = collection.getAll();
      assert.equal(all.size, 2, 'two per-segment entries');

      const width = 32;
      const seg1 = all.get(1)?.get(0);
      const seg2 = all.get(2)?.get(0);
      assert.ok(seg1 !== undefined, 'segment 1 slice 0 present');
      assert.ok(seg2 !== undefined, 'segment 2 slice 0 present');

      // segment 1 covers col=4..10, row=4..10
      assert.equal(seg1[7 * width + 7], 1, 'seg 1 buf: center pixel = 1');
      assert.equal(seg1[15 * width + 15], 0, 'seg 1 buf: sq 2 pixel = 0');

      // segment 2 covers col=12..18, row=12..18
      assert.equal(seg2[15 * width + 15], 2, 'seg 2 buf: center pixel = 2');
      assert.equal(seg2[7 * width + 7], 0, 'seg 2 buf: sq 1 pixel = 0');
    });

  test(
    'toDicom: non-overlapping squares round-trip - ' +
    '#DWV-REQ-IO-05-004 Write DICOM RTSTRUCT',
    () => {
      const config = syntheticData.find(c => c.name === 'test-rtss-00');
      const factory = new RtStructFactory();
      const refImage = buildRefImage();
      const image = factory.create(configToElements(config), refImage);
      const outElements = factory.toDicom(image, undefined, refImage);

      const refConfig = syntheticData.find(c => c.name === 'test-img-00');
      assert.equal(
        getReferencedSeriesUIDFromRTStruct(outElements),
        refConfig.tags.SeriesInstanceUID,
        'output referencedSeriesUID matches test-img-00'
      );

      const inRois = getRTStructFromElements(configToElements(config));
      const outRois = getRTStructFromElements(outElements);

      assert.equal(outRois.length, inRois.length, 'same ROI count');
      for (let i = 0; i < inRois.length; i++) {
        assert.equal(outRois[i].name, inRois[i].name, `ROI ${i + 1} name`);
        assert.equal(
          outRois[i].colour.r, inRois[i].colour.r, `ROI ${i + 1} red`
        );
        assert.equal(
          outRois[i].colour.g, inRois[i].colour.g, `ROI ${i + 1} green`
        );
        assert.equal(
          outRois[i].colour.b, inRois[i].colour.b, `ROI ${i + 1} blue`
        );
        assert.ok(outRois[i].contours.length > 0, `ROI ${i + 1} has contours`);
        for (const c of outRois[i].contours) {
          assert.ok(c.points3D.length >= 9, 'contour has at least 3 points');
          assert.equal(
            c.points3D.length % 3, 0, 'contour data length is multiple of 3'
          );
        }
      }
    });

  // -------------------------------------------------------------------------
  // Overlapping squares — test-rtss-01
  // Square 1: col=4..10, row=4..10 | Square 2: col=8..14, row=8..14
  // -------------------------------------------------------------------------

  test('create: overlapping squares, overlap flag detected', () => {
    const warnSpy = vi.spyOn(loggerModule.logger, 'warn')
      .mockImplementation(() => {});

    const config = syntheticData.find(c => c.name === 'test-rtss-01');
    const factory = new RtStructFactory();
    const image = factory.create(configToElements(config), buildRefImage());

    assert.ok(
      warnSpy.mock.calls.some(
        ([msg]) => msg === 'SegmentCollection: detected overlapping segments'
      ),
      'overlap warning logged during create'
    );

    const meta = image.getMeta();
    const segments = meta.custom.segments;
    assert.equal(segments.length, 2, 'two segments created');
    assert.equal(segments[0].label, 'Square1', 'segment 1 name');
    assert.equal(segments[1].label, 'Square2', 'segment 2 name');
    assert.equal(image.getHasOverlap(), true, 'overlap detected');
    const refConfig = syntheticData.find(c => c.name === 'test-img-00');
    assert.equal(
      image.getMaskReferencedSeriesUID(),
      refConfig.tags.SeriesInstanceUID,
      'referencedSeriesUID matches test-img-00'
    );
  });

  test('create: overlapping squares pixel values in label map', () => {
    // hide logging
    vi.spyOn(loggerModule.logger, 'warn').mockImplementation(() => {});

    const config = syntheticData.find(c => c.name === 'test-rtss-01');
    const factory = new RtStructFactory();
    const image = factory.create(configToElements(config), buildRefImage());

    const buf = image.getBuffer();
    const width = 32;
    // square 1 exclusive area center at (col=6, row=6)
    assert.equal(buf[6 * width + 6], 1, 'sq 1 exclusive area is seg 1');
    // square 2 exclusive area center at (col=12, row=12)
    assert.equal(buf[12 * width + 12], 2, 'sq 2 exclusive area is seg 2');
    // overlap center at (col=9, row=9) → offset 9*32+9 = 297; seg 1 wins
    assert.equal(buf[9 * width + 9], 1, 'overlap pixel retains first segment');
  });

  test('create: overlapping squares segment collection', () => {
    // hide logging
    vi.spyOn(loggerModule.logger, 'warn').mockImplementation(() => {});

    const config = syntheticData.find(c => c.name === 'test-rtss-01');
    const factory = new RtStructFactory();
    const image = factory.create(configToElements(config), buildRefImage());

    const collection = image.getSegmentCollection();
    assert.ok(collection !== undefined, 'segment collection exists');

    const all = collection.getAll();
    assert.equal(all.size, 2, 'two per-segment entries');

    const width = 32;
    const seg1 = all.get(1)?.get(0);
    const seg2 = all.get(2)?.get(0);
    assert.ok(seg1 !== undefined, 'segment 1 slice 0 present');
    assert.ok(seg2 !== undefined, 'segment 2 slice 0 present');

    // segment 1 covers col=4..10, row=4..10
    assert.equal(seg1[6 * width + 6], 1, 'seg 1 buf: exclusive pixel = 1');
    // segment 2 covers col=8..14, row=8..14
    assert.equal(seg2[12 * width + 12], 2, 'seg 2 buf: exclusive pixel = 2');

    // overlap zone at (col=9, row=9): each segment's own buffer has its value
    assert.equal(seg1[9 * width + 9], 1, 'seg 1 buf: overlap pixel = 1');
    assert.equal(seg2[9 * width + 9], 2, 'seg 2 buf: overlap pixel = 2');
    // label map collapses the overlap to first-segment value
    assert.equal(
      image.getBuffer()[9 * width + 9], 1,
      'label map: overlap pixel = 1 (first wins)'
    );
  });

  test('toDicom: overlapping squares round-trip', () => {
    // hide logging
    vi.spyOn(loggerModule.logger, 'warn').mockImplementation(() => {});

    const config = syntheticData.find(c => c.name === 'test-rtss-01');
    const factory = new RtStructFactory();
    const refImage = buildRefImage();
    const image = factory.create(configToElements(config), refImage);
    const outElements = factory.toDicom(image, undefined, refImage);

    const refConfig = syntheticData.find(c => c.name === 'test-img-00');
    assert.equal(
      getReferencedSeriesUIDFromRTStruct(outElements),
      refConfig.tags.SeriesInstanceUID,
      'output referencedSeriesUID matches test-img-00'
    );

    const inRois = getRTStructFromElements(configToElements(config));
    const outRois = getRTStructFromElements(outElements);

    assert.equal(outRois.length, inRois.length, 'same ROI count');
    for (let i = 0; i < inRois.length; i++) {
      assert.equal(outRois[i].name, inRois[i].name, `ROI ${i + 1} name`);
      assert.equal(
        outRois[i].colour.r, inRois[i].colour.r, `ROI ${i + 1} red`
      );
      assert.equal(
        outRois[i].colour.g, inRois[i].colour.g, `ROI ${i + 1} green`
      );
      assert.equal(
        outRois[i].colour.b, inRois[i].colour.b, `ROI ${i + 1} blue`
      );
      assert.ok(outRois[i].contours.length > 0, `ROI ${i + 1} has contours`);
      for (const c of outRois[i].contours) {
        assert.ok(c.points3D.length >= 9, 'contour has at least 3 points');
        assert.equal(
          c.points3D.length % 3, 0, 'contour data length is multiple of 3'
        );
      }
    }
  });

  // -------------------------------------------------------------------------
  // Square with a hole — test-rtss-02
  // Outer square: col=4..20, row=4..20 | Hole: col=10..14, row=10..14
  // -------------------------------------------------------------------------

  test(
    'create: square with hole punches out the hole - ' +
    '#DWV-REQ-IO-06-002 Load DICOM RTSTRUCT',
    () => {
      const config = syntheticData.find(c => c.name === 'test-rtss-02');
      const factory = new RtStructFactory();
      const image = factory.create(configToElements(config), buildRefImage());

      const buf = image.getBuffer();
      const width = 32;
      // outer, outside the hole
      assert.equal(buf[6 * width + 6], 1, 'outer area is segment 1');
      // inside the hole
      assert.equal(buf[12 * width + 12], 0, 'hole area is background');
      // fully outside the square
      assert.equal(buf[2 * width + 2], 0, 'outside square is background');
    });

  test(
    'toDicom: square with hole round-trip preserves the hole - ' +
    '#DWV-REQ-IO-05-004 Write DICOM RTSTRUCT',
    () => {
      const config = syntheticData.find(c => c.name === 'test-rtss-02');
      const factory = new RtStructFactory();
      const refImage = buildRefImage();
      const image = factory.create(configToElements(config), refImage);
      const outElements = factory.toDicom(image, undefined, refImage);

      const outRois = getRTStructFromElements(outElements);
      assert.equal(outRois.length, 1, 'one ROI');
      assert.equal(
        outRois[0].contours.length, 2,
        'outer boundary and hole are both written as contours'
      );
      for (const c of outRois[0].contours) {
        assert.equal(
          c.type, 'CLOSEDPLANAR_XOR',
          'hole-bearing contours are tagged CLOSEDPLANAR_XOR'
        );
      }

      // re-import the round-tripped RTSS and check the hole survived
      const roundTripImage = factory.create(outElements, refImage);
      const buf = roundTripImage.getBuffer();
      const width = 32;
      assert.equal(buf[6 * width + 6], 1, 'outer area is segment 1');
      assert.equal(buf[12 * width + 12], 0, 'hole area is background');
      assert.equal(buf[2 * width + 2], 0, 'outside square is background');
    });

  test('create: accepts CLOSEDPLANAR_XOR contours and punches out the hole',
    () => {
      const config = syntheticData.find(c => c.name === 'test-rtss-03');
      const factory = new RtStructFactory();
      const image = factory.create(configToElements(config), buildRefImage());

      const buf = image.getBuffer();
      const width = 32;
      assert.equal(buf[6 * width + 6], 1, 'outer area is segment 1');
      assert.equal(buf[12 * width + 12], 0, 'hole area is background');
      assert.equal(buf[2 * width + 2], 0, 'outside square is background');
    });

  test(
    'create: keyhole-style single contour with bridge produces correct hole',
    () => {
      const config = syntheticData.find(c => c.name === 'test-rtss-04');
      const factory = new RtStructFactory();
      const image = factory.create(configToElements(config), buildRefImage());

      const buf = image.getBuffer();
      const width = 32;
      assert.equal(buf[6 * width + 6], 1, 'outer area is segment 1');
      assert.equal(buf[12 * width + 12], 0, 'hole area is background');
      assert.equal(buf[2 * width + 2], 0, 'outside square is background');
      // bridge runs along row 12: pixels in the ring on that row must
      // still be filled (the zero-width bridge must not leak into the fill)
      assert.equal(
        buf[12 * width + 6], 1,
        'ring pixel on the bridge row is filled, not leaked into the hole'
      );
    });

});