DWVv0.37.0
tests/image/annotation.test.jsjavascript
import {describe, test, assert, vi, afterEach} from 'vitest';
import {Annotation} from '../../src/image/annotation.js';
import {DicomCode} from '../../src/dicom/dicomCode.js';
import {Point, Point2D, Point3D} from '../../src/math/point.js';
import {Index} from '../../src/math/index.js';
import {Size} from '../../src/image/size.js';
import {Spacing} from '../../src/image/spacing.js';
import {Geometry} from '../../src/image/geometry.js';
import {Rectangle} from '../../src/math/rectangle.js';
import {Path} from '../../src/math/path.js';
import * as loggerModule from '../../src/utils/logger.js';

// ---------------------------------------------------------------------------
// Mock ViewController
// ---------------------------------------------------------------------------

/**
 * Minimal ViewController mock for annotation tests.
 * All methods return safe defaults; individual tests override as needed.
 */
class MockViewController {
  #uid;
  #modality;
  #acquisitionOrientation;
  #planeHelper;

  /**
   * @param {object} opts Configuration options.
   * @param {string} opts.uid Image SOP instance UID.
   * @param {string} [opts.modality] Modality string (default 'CT').
   * @param {boolean} [opts.acquisitionOrientation] Acquisition orientation
   *   flag.
   * @param {object} [opts.planeHelper] Plane helper mock.
   */
  constructor({
    uid = 'uid-test',
    modality = 'CT',
    acquisitionOrientation = true,
    planeHelper = {isAquisitionOrientation: () => true, getCosines: () => []}
  } = {}) {
    this.#uid = uid;
    this.#modality = modality;
    this.#acquisitionOrientation = acquisitionOrientation;
    this.#planeHelper = planeHelper;
  }

  /** @returns {{length: Function, get: Function}} Position-like object. */
  getCurrentPosition() {
    return {length: () => 3, get: () => undefined};
  }

  /** @returns {string} The SOP instance UID. */
  getCurrentImageUid() {
    return this.#uid;
  }

  /** @returns {string} SOP class UID. */
  getSopClassUid() {
    return '1.2.840.10008.5.1.4.1.1.2';
  }

  /**
   * @param {string} _uid The UID to look up.
   * @returns {Point3D} The plane origin.
   */
  getOriginForImageUid(_uid) {
    return new Point3D(0, 0, 0);
  }

  /** @returns {boolean} Whether in acquisition orientation. */
  isAquisitionOrientation() {
    return this.#acquisitionOrientation;
  }

  /**
   * @param {object} _position Current position.
   * @returns {Point3D[]} Plane points.
   */
  getPlanePoints(_position) {
    return [
      new Point3D(0, 0, 0),
      new Point3D(1, 0, 0),
      new Point3D(0, 1, 0)
    ];
  }

  /**
   * @param {string} uid UID to check.
   * @returns {boolean} True if this controller owns that UID.
   */
  includesImageUid(uid) {
    return uid === this.#uid;
  }

  /** @returns {object} The plane helper. */
  getPlaneHelper() {
    return this.#planeHelper;
  }

  /** @returns {string} The modality. */
  getModality() {
    return this.#modality;
  }
}

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

describe('image', () => {

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

  // -------------------------------------------------------------------------
  // Constructor / default values
  // -------------------------------------------------------------------------

  /**
   * Tests for {@link Annotation} constructor defaults.
   *
   * @function module:tests/image~annotationConstructor
   */
  test('Annotation constructor sets unique non-empty ids and default values',
    () => {
      const a = new Annotation();

      assert.isString(a.trackingId, 'trackingId is a string');
      assert.isNotEmpty(a.trackingId, 'trackingId is not empty');
      assert.isString(a.trackingUid, 'trackingUid is a string');
      assert.isNotEmpty(a.trackingUid, 'trackingUid is not empty');

      // Default field values
      assert.equal(a.colour, '#ffff80', 'default colour');
      assert.equal(a.textExpr, '', 'default textExpr');
      assert.isUndefined(a.mathShape, 'mathShape starts undefined');
      assert.isUndefined(a.quantification, 'quantification starts undefined');
    }
  );

  /**
   * Tests that each Annotation instance receives unique ids.
   *
   * @function module:tests/image~annotationUniqueIds
   */
  test('Annotation instances have unique tracking ids', () => {
    const a = new Annotation();
    const b = new Annotation();
    assert.notEqual(a.trackingId, b.trackingId, 'trackingId differs');
    assert.notEqual(a.trackingUid, b.trackingUid, 'trackingUid differs');
  });

  // -------------------------------------------------------------------------
  // Meta data CRUD
  // -------------------------------------------------------------------------

  /**
   * Tests for {@link Annotation} meta data add/get/list operations.
   *
   * @function module:tests/image~annotationMetaAddGet
   */
  test('Annotation addMetaItem / getMetaItem / getMetaConceptIds', () => {
    const ann = new Annotation();

    // empty initially
    assert.deepEqual(ann.getMetaConceptIds(), []);
    assert.isUndefined(ann.getMetaItem('C0001'));

    // add one item
    const concept = new DicomCode('Finding');
    concept.value = 'C0001';
    const value = new DicomCode('Lesion');
    ann.addMetaItem(concept, value);

    assert.deepEqual(ann.getMetaConceptIds(), ['C0001']);
    const item = ann.getMetaItem('C0001');
    assert.equal(item.concept, concept, 'stored concept');
    assert.equal(item.value, value, 'stored value');

    // add a second item
    const concept2 = new DicomCode('Quality');
    concept2.value = 'C0002';
    ann.addMetaItem(concept2, 'good');
    assert.deepEqual(
      ann.getMetaConceptIds().sort(), ['C0001', 'C0002']
    );
  });

  /**
   * Tests that {@link Annotation#addMetaItem} warns when overwriting.
   *
   * @function module:tests/image~annotationMetaOverwrite
   */
  test('Annotation addMetaItem warns on duplicate concept id', () => {
    const warnSpy = vi.spyOn(loggerModule.logger, 'warn')
      .mockImplementation(() => {});
    const ann = new Annotation();
    const concept = new DicomCode('Finding');
    concept.value = 'C0001';

    ann.addMetaItem(concept, 'first');
    assert.equal(warnSpy.mock.calls.length, 0, 'no warning on first add');

    ann.addMetaItem(concept, 'second');
    assert.equal(warnSpy.mock.calls.length, 1, 'warning on overwrite');
    assert.ok(warnSpy.mock.calls[0][0].includes('C0001'),
      'warning mentions the concept id');
  });

  /**
   * Tests for {@link Annotation#removeMetaItem}.
   *
   * @function module:tests/image~annotationMetaRemove
   */
  test('Annotation removeMetaItem deletes an existing entry silently', () => {
    const ann = new Annotation();
    const concept = new DicomCode('Finding');
    concept.value = 'C0001';
    ann.addMetaItem(concept, 'val');

    ann.removeMetaItem('C0001');
    assert.isUndefined(ann.getMetaItem('C0001'));
    assert.deepEqual(ann.getMetaConceptIds(), []);

    // removing a non-existent id is a no-op
    assert.doesNotThrow(() => ann.removeMetaItem('no-such-id'));
  });

  // -------------------------------------------------------------------------
  // canView
  // -------------------------------------------------------------------------

  /**
   * Tests for {@link Annotation#canView} initial state.
   *
   * @function module:tests/image~annotationCanView
   */
  test('Annotation canView returns false before init', () => {
    const ann = new Annotation();
    assert.isFalse(ann.canView());
  });

  // -------------------------------------------------------------------------
  // getText
  // -------------------------------------------------------------------------

  /**
   * Tests for {@link Annotation#getText} with no quantification.
   *
   * @function module:tests/image~annotationGetTextPlain
   */
  test('Annotation getText returns plain textExpr when no quantification',
    () => {
      const ann = new Annotation();
      ann.textExpr = 'Hello world';
      assert.equal(ann.getText(), 'Hello world');
    });

  /**
   * Tests for {@link Annotation#getText} with flag substitution.
   *
   * @function module:tests/image~annotationGetTextFlags
   */
  test('Annotation getText replaces {flags} from quantification', () => {
    const ann = new Annotation();
    ann.textExpr = 'Area: {area} mm²';
    ann.quantification = {area: {value: 12.345, unit: 'mm²'}};
    const text = ann.getText();
    // replaceFlags uses toPrecision(4) → '12.35'
    assert.ok(text.includes('12.35'), `text includes formatted value: ${text}`);
  });

  /**
   * Tests for {@link Annotation#getText} with empty textExpr.
   *
   * @function module:tests/image~annotationGetTextEmpty
   */
  test('Annotation getText returns empty string for default textExpr', () => {
    const ann = new Annotation();
    assert.equal(ann.getText(), '');
  });

  // -------------------------------------------------------------------------
  // isCompatibleView
  // -------------------------------------------------------------------------

  /**
   * Tests for {@link Annotation#isCompatibleView} without planePoints.
   *
   * @function module:tests/image~annotationCompatibleViewNoPlane
   */
  test('Annotation isCompatibleView delegates to planeHelper ' +
    'when no planePoints',
  () => {
    const ann = new Annotation();
    assert.isUndefined(ann.planePoints);

    assert.isTrue(
      ann.isCompatibleView({isAquisitionOrientation: () => true}),
      'compatible with acquisition-orientation view'
    );
    assert.isFalse(
      ann.isCompatibleView({isAquisitionOrientation: () => false}),
      'incompatible with non-acquisition-orientation view'
    );
  }
  );

  /**
   * Tests for {@link Annotation#isCompatibleView} with planePoints set.
   *
   * @function module:tests/image~annotationCompatibleViewPlane
   */
  test('Annotation isCompatibleView compares cosines when planePoints set',
    () => {
      const ann = new Annotation();
      ann.planePoints = [
        new Point3D(0, 0, 0),
        new Point3D(1, 0, 0), // cosine row-direction
        new Point3D(0, 1, 0) // cosine column-direction
      ];

      const matchingHelper = {
        getCosines: () => [1, 0, 0, 0, 1, 0],
        getLegacyCosines: () => [1, 0, 0, 0, 1, 0]
      };
      assert.isTrue(ann.isCompatibleView(matchingHelper),
        'matches when cosines are equal');

      const nonMatchingHelper = {
        getCosines: () => [0, 1, 0, 0, 0, 1],
        getLegacyCosines: () => [0, 1, 0, 0, 0, 1]
      };
      assert.isFalse(ann.isCompatibleView(nonMatchingHelper),
        'does not match when cosines differ');

      const legacyHelper = {
        getCosines: () => [1, 0, 0, 0, -1, 0],
        getLegacyCosines: () => [1, 0, 0, 0, 1, 0]
      };
      assert.isTrue(ann.isCompatibleView(legacyHelper),
        'matches when legacy cosines are equal');
    }
  );

  // -------------------------------------------------------------------------
  // getOrientationName
  // -------------------------------------------------------------------------

  /**
   * Tests for {@link Annotation#getOrientationName} without planePoints.
   *
   * @function module:tests/image~annotationOrientationUndefined
   */
  test('Annotation getOrientationName returns undefined without planePoints',
    () => {
      const ann = new Annotation();
      assert.isUndefined(ann.getOrientationName());
    }
  );

  /**
   * Tests for {@link Annotation#getOrientationName} with axial planePoints.
   *
   * @function module:tests/image~annotationOrientationAxial
   */
  test('Annotation getOrientationName returns a string when planePoints set',
    () => {
      const ann = new Annotation();
      // Axial orientation cosines: row=[1,0,0] col=[0,1,0]
      ann.planePoints = [
        new Point3D(0, 0, 0),
        new Point3D(1, 0, 0),
        new Point3D(0, 1, 0)
      ];
      const name = ann.getOrientationName();
      assert.isString(name, 'returns a string');
      assert.isNotEmpty(name, 'name is not empty');
    }
  );

  // -------------------------------------------------------------------------
  // init
  // -------------------------------------------------------------------------

  /**
   * Tests for {@link Annotation#init} setting annotation fields.
   *
   * @function module:tests/image~annotationInit
   */
  test('Annotation init sets referencedSopInstanceUID and enables canView',
    () => {
      const ann = new Annotation();
      const vc = new MockViewController({uid: 'sop-001'});
      ann.init(vc);

      assert.equal(ann.referencedSopInstanceUID, 'sop-001');
      assert.isDefined(ann.referencedSopClassUID);
      assert.isTrue(ann.canView(), 'canView is true after init');
      assert.isUndefined(ann.referencedFrameNumber,
        'no frame number for 3D position');
    }
  );

  /**
   * Tests that {@link Annotation#init} sets a 1-based frame number
   * from the position time index.
   *
   * @function module:tests/image~annotationInitFrameNumber
   */
  test('Annotation init sets a 1-based referencedFrameNumber', () => {
    for (const timeIndex of [0, 2]) {
      const ann = new Annotation();
      const vc = new MockViewController({uid: 'sop-001'});
      // the position holds a volume id, the index the volume index
      vc.getCurrentPosition = () => ({
        length: () => 4,
        get: (i) => (i === 3 ? timeIndex * 500 : 0)
      });
      vc.getIndexFromPosition = (position) => ({
        get: (i) => (i === 3 ? position.get(3) / 500 : 0)
      });
      ann.init(vc);
      assert.equal(ann.referencedFrameNumber, timeIndex + 1,
        `frame number for time index ${timeIndex}`);
    }
  });

  /**
   * Tests that {@link Annotation#getCentroid} uses the volume id
   * of the referenced frame.
   *
   * @function module:tests/image~annotationCentroidVolumeId
   */
  test('Annotation getCentroid with volume ids', () => {
    // 2 slices, 3 volumes with ids 0, 500 and 1000
    const geometry = new Geometry(
      [new Point3D(0, 0, 0)], new Size([4, 4, 1]), new Spacing([1, 1, 1]),
      undefined, {id: {source: 'DiffusionBValue', value: 0}});
    geometry.appendOrigin(new Point3D(0, 0, 1), 1, 0);
    for (const value of [500, 1000]) {
      geometry.appendFrame(
        new Point3D(0, 0, 0), {id: {source: 'DiffusionBValue', value}});
      geometry.appendOrigin(new Point3D(0, 0, 1), 1, value);
    }

    let position = geometry.indexToWorld(new Index([0, 0, 0, 2]));
    const vc = new MockViewController({uid: 'sop-001'});
    vc.getCurrentPosition = () => position;
    vc.getCurrentIndex = () => geometry.worldToIndex(position);
    vc.getIndexFromPosition = (point) => geometry.worldToIndex(point);
    vc.getPositionFromIndex = (index) => geometry.indexToWorld(index);
    vc.getScrollDimIndex = () => 2;
    vc.getPositionFromPlanePoint = (point, k) =>
      new Point([point.getX(), point.getY(), k, position.get(3)]);

    const ann = new Annotation();
    ann.init(vc);
    assert.equal(ann.referencedFrameNumber, 3, 'frame number');

    ann.mathShape = new Rectangle(new Point2D(0, 0), new Point2D(2, 2));
    // move to the first volume: the centroid stays on the third
    position = geometry.indexToWorld(new Index([0, 0, 0, 0]));
    const centroid = ann.getCentroid();
    assert.deepEqual(
      centroid.getValues(), [1, 1, 0, 1000], 'centroid with volume id');
  });

  /**
   * Tests that a second {@link Annotation#init} call is a no-op.
   *
   * @function module:tests/image~annotationInitTwice
   */
  test('Annotation init is a no-op when called a second time', () => {
    const debugSpy = vi.spyOn(loggerModule.logger, 'debug')
      .mockImplementation(() => {});
    const ann = new Annotation();
    const vc = new MockViewController({uid: 'sop-001'});
    ann.init(vc);

    const vc2 = new MockViewController({uid: 'sop-002'});
    ann.init(vc2);

    // UID must stay from first init, debug must have been called
    assert.equal(ann.referencedSopInstanceUID, 'sop-001');
    assert.equal(debugSpy.mock.calls.length, 1);
  });

  /**
   * Tests that init stores planePoints for non-acquisition orientation.
   *
   * @function module:tests/image~annotationInitOriented
   */
  test('Annotation init stores planePoints for oblique orientation', () => {
    const ann = new Annotation();
    const vc = new MockViewController({acquisitionOrientation: false});
    ann.init(vc);

    assert.isDefined(ann.planePoints,
      'planePoints set for non-acquisition orientation');
    assert.equal(ann.planePoints.length, 3);
  });

  // -------------------------------------------------------------------------
  // setViewController
  // -------------------------------------------------------------------------

  /**
   * Tests that {@link Annotation#setViewController} warns on unknown UID.
   *
   * @function module:tests/image~annotationSetVcUnknownUid
   */
  test('Annotation setViewController warns when UID does not match', () => {
    const warnSpy = vi.spyOn(loggerModule.logger, 'warn')
      .mockImplementation(() => {});
    const ann = new Annotation();
    ann.referencedSopInstanceUID = 'sop-001';

    const vc = new MockViewController({uid: 'sop-999'});
    ann.setViewController(vc);

    assert.equal(warnSpy.mock.calls.length, 1, 'warning emitted');
    assert.isFalse(ann.canView(), 'canView still false');
  });

  /**
   * Tests that {@link Annotation#setViewController} is rejected for
   * incompatible views.
   *
   * @function module:tests/image~annotationSetVcIncompatible
   */
  test('Annotation setViewController is ignored for incompatible view', () => {
    const ann = new Annotation();
    ann.referencedSopInstanceUID = 'sop-001';
    // Set planePoints so isCompatibleView checks cosines
    ann.planePoints = [
      new Point3D(0, 0, 0),
      new Point3D(1, 0, 0),
      new Point3D(0, 1, 0)
    ];

    const incompatibleHelper = {
      getCosines: () => [0, 1, 0, 0, 0, 1],
      getLegacyCosines: () => [0, 1, 0, 0, 0, 1]
    };
    const vc = new MockViewController({
      uid: 'sop-001',
      planeHelper: incompatibleHelper
    });
    ann.setViewController(vc);

    assert.isFalse(ann.canView(), 'canView still false for incompatible view');
  });

  /**
   * Tests that {@link Annotation#setViewController} succeeds for
   * a compatible view.
   *
   * @function module:tests/image~annotationSetVcCompatible
   */
  test('Annotation setViewController enables canView for compatible view',
    () => {
      const ann = new Annotation();
      ann.referencedSopInstanceUID = 'sop-001';
      // No planePoints → compatible with any acquisition-orientation view
      const vc = new MockViewController({
        uid: 'sop-001',
        planeHelper: {isAquisitionOrientation: () => true}
      });
      ann.setViewController(vc);

      assert.isTrue(ann.canView());
    });

  /**
   * Tests that {@link Annotation#setViewController} replaces legacy
   * plane cosines.
   *
   * @function module:tests/image~annotationSetVcLegacyCosines
   */
  test('Annotation setViewController replaces legacy plane cosines',
    () => {
      const ann = new Annotation();
      ann.referencedSopInstanceUID = 'sop-001';
      const origin = new Point3D(1, 2, 3);
      ann.planePoints = [
        origin,
        new Point3D(1, 0, 0),
        new Point3D(0, 0, 1)
      ];
      const vc = new MockViewController({
        uid: 'sop-001',
        planeHelper: {
          getCosines: () => [1, 0, 0, 0, 0, -1],
          getLegacyCosines: () => [1, 0, 0, 0, 0, 1]
        }
      });
      ann.setViewController(vc);

      assert.isTrue(ann.canView());
      assert.equal(ann.planePoints[0], origin, 'same origin');
      assert.isTrue(ann.planePoints[1].equals(new Point3D(1, 0, 0)),
        'same first cosine');
      assert.isTrue(ann.planePoints[2].equals(new Point3D(0, 0, -1)),
        'replaced second cosine');
    });

  // -------------------------------------------------------------------------
  // setTextExpr
  // -------------------------------------------------------------------------

  /**
   * Tests for {@link Annotation#setTextExpr} without a view controller.
   *
   * @function module:tests/image~annotationSetTextNoVc
   */
  test('Annotation setTextExpr warns when no view controller is set', () => {
    const warnSpy = vi.spyOn(loggerModule.logger, 'warn')
      .mockImplementation(() => {});
    const ann = new Annotation();
    ann.setTextExpr({'*': 'fallback'});

    assert.equal(warnSpy.mock.calls.length, 1);
    assert.equal(ann.textExpr, '', 'textExpr unchanged');
  });

  /**
   * Tests for {@link Annotation#setTextExpr} using modality-specific text.
   *
   * @function module:tests/image~annotationSetTextModality
   */
  test('Annotation setTextExpr uses modality-specific text when available',
    () => {
      const ann = new Annotation();
      const vc = new MockViewController({uid: 'sop-001', modality: 'MR'});
      ann.init(vc);

      ann.setTextExpr({MR: 'MR label', CT: 'CT label', '*': 'default'});
      assert.equal(ann.textExpr, 'MR label');
    }
  );

  /**
   * Tests for {@link Annotation#setTextExpr} falling back to '*'.
   *
   * @function module:tests/image~annotationSetTextFallback
   */
  test('Annotation setTextExpr falls back to "*" key for unknown modality',
    () => {
      const ann = new Annotation();
      const vc = new MockViewController({uid: 'sop-001', modality: 'PT'});
      ann.init(vc);

      ann.setTextExpr({CT: 'CT label', '*': 'default label'});
      assert.equal(ann.textExpr, 'default label');
    }
  );

  // -------------------------------------------------------------------------
  // getFactory
  // -------------------------------------------------------------------------

  /**
   * Tests for {@link Annotation#getFactory} when no mathShape is set.
   *
   * @function module:tests/image~annotationGetFactoryNoShape
   */
  test('Annotation getFactory returns undefined when mathShape is not set',
    () => {
      const ann = new Annotation();
      assert.isUndefined(ann.getFactory());
    }
  );

  /**
   * Tests for {@link Annotation#getFactory} when no factory supports
   * the given shape.
   *
   * @function module:tests/image~annotationGetFactoryNoMatch
   */
  test('Annotation getFactory warns and returns undefined ' +
    'for unsupported shape',
  () => {
    const warnSpy = vi.spyOn(loggerModule.logger, 'warn')
      .mockImplementation(() => {});
    const ann = new Annotation();
    // Plain object — no registered factory will call supports() → true
    ann.mathShape = {};

    assert.isUndefined(ann.getFactory());
    assert.equal(warnSpy.mock.calls.length, 1, 'warning emitted');
    assert.ok(warnSpy.mock.calls[0][0].includes('factory'),
      'warning mentions factory');
  }
  );

});

describe('Annotation contains', () => {
  test('delegates to the math shape', () => {
    const annotation = new Annotation();
    annotation.mathShape = new Rectangle(new Point2D(0, 0), new Point2D(4, 4));
    assert.ok(annotation.contains(new Point2D(2, 2)), 'inside');
    assert.notOk(annotation.contains(new Point2D(6, 2)), 'outside');
    assert.ok(annotation.contains(new Point2D(6, 2), 2), 'within tolerance');
  });

  test('arrow uses the tip to tail segment', () => {
    const annotation = new Annotation();
    annotation.mathShape = new Point2D(0, 0);
    annotation.referencePoints = [new Point2D(10, 0)];
    assert.ok(annotation.contains(new Point2D(5, 1), 1), 'near the shaft');
    assert.notOk(annotation.contains(new Point2D(12, 0), 1), 'past the tail');
  });

  test('false without a math shape contains', () => {
    const annotation = new Annotation();
    assert.notOk(annotation.contains(new Point2D(0, 0)), 'no math shape');
    annotation.mathShape = new Path();
    assert.notOk(annotation.contains(new Point2D(0, 0)), 'path');
  });
});