DWVv0.37.0
tests/annotation/annotation.test.jsjavascript
// @vitest-environment jsdom
import {describe, test, assert, vi, expect} from 'vitest';
import {DicomParser} from '../../src/dicom/dicomParser.js';
import {b64urlToArrayBuffer} from '../dicom/utils.js';
import {
  AnnotationGroupFactory
} from '../../src/image/annotationGroupFactory.js';
import {Circle} from '../../src/math/circle.js';
import {Ellipse} from '../../src/math/ellipse.js';
import {Line} from '../../src/math/line.js';
import {Point2D} from '../../src/math/point.js';
import {Protractor} from '../../src/math/protractor.js';
import {Rectangle} from '../../src/math/rectangle.js';
import {ROI} from '../../src/math/roi.js';
import {BidimensionalLine} from '../../src/math/bidimensionalLine.js';
import {
  getScoordFromShape,
  getShapeFromScoord
} from '../../src/dicom/dicomSpatialCoordinate.js';

/**
 * @import {AnnotationGroup} from '../../src/image/annotationGroup.js';
 */

import dwv034Arrow from './dwv034/sr-arrow.dcm?inline';
import dwv034Circle from './dwv034/sr-circle.dcm?inline';
import dwv034Ellipse from './dwv034/sr-ellipse.dcm?inline';
import dwv034Protractor from './dwv034/sr-protractor.dcm?inline';
import dwv034Rectangle from './dwv034/sr-rectangle.dcm?inline';
import dwv034Roi from './dwv034/sr-roi.dcm?inline';
import dwv034Ruler from './dwv034/sr-ruler.dcm?inline';

import tid1500v0Arrow from './tid1500-0/sr-arrow.dcm?inline';
import tid1500v0Circle from './tid1500-0/sr-circle.dcm?inline';
import tid1500v0Ellipse from './tid1500-0/sr-ellipse.dcm?inline';
import tid1500v0Protractor from './tid1500-0/sr-protractor.dcm?inline';
import tid1500v0Rectangle from './tid1500-0/sr-rectangle.dcm?inline';
import tid1500v0Roi from './tid1500-0/sr-roi.dcm?inline';
import tid1500v0Ruler from './tid1500-0/sr-ruler.dcm?inline';
import tid1500v0Bidimensional from './tid1500-0/sr-bidimensional.dcm?inline';

/**
 * Tests for the annotation I/O.
 */
/** @module tests/annotation */

describe('annotation', () => {
  /**
   * Get an annotation group from a buffer string.
   *
   * @param {string} bufferStr The buffer string.
   * @returns {AnnotationGroup} The annotation group.
   */
  function getAnnotationGroup(bufferStr) {
    const dicomParser = new DicomParser();
    dicomParser.parse(b64urlToArrayBuffer(bufferStr));
    const tags = dicomParser.getDicomElements();
    const fac = new AnnotationGroupFactory();
    let group;
    if (typeof fac.checkElements(tags) === 'undefined') {
      group = fac.create(tags);
    }
    return group;
  }

  /**
   * Get a dwv v0.34 annotation group from a buffer string.
   *
   * @param {string} bufferStr The buffer string.
   * @returns {AnnotationGroup} The annotation group.
   */
  function get034AnnotationGroup(bufferStr) {
    // console warn spy
    const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
    // run test
    const res = getAnnotationGroup(bufferStr);
    // expect warn call
    expect(consoleSpy).toHaveBeenCalledWith('DWV v0.34 annotation');
    // reset spy
    consoleSpy.mockReset();

    return res;
  }

  /**
   * Check common properties of an annotation group.
   *
   * @param {AnnotationGroup} annotationGroup The group to check.
   * @param {string} prefix A message prefix.
   */
  function checkGroupCommonProperties(annotationGroup, prefix) {
    const annotations = annotationGroup.getList();

    const colours = ['#ffff80', '#ffa348', '#ed333b'];

    assert.ok(annotationGroup.getLength() === 3,
      `${prefix} annotationGroup length`);
    assert.ok(annotations.length === 3,
      `${prefix} annotations length`);

    for (let i = 0; i < annotations.length; ++i) {
      const annotation = annotations[i];
      assert.ok(typeof annotation.trackingId !== 'undefined',
        `${prefix} annotation ${i} trackingId`);
      assert.ok(typeof annotation.trackingUid !== 'undefined',
        `${prefix} annotation ${i} trackingUid`);
      assert.ok(typeof annotation.referencedSopClassUID !== 'undefined',
        `${prefix} annotation ${i} referencedSopClassUID`);
      assert.ok(typeof annotation.referencedSopInstanceUID !== 'undefined',
        `${prefix} annotation ${i} referencedSopInstanceUID`);

      assert.ok(typeof annotation.colour !== 'undefined',
        `${prefix} annotation ${i} colour`);
      assert.equal(annotation.colour, colours[i],
        `${prefix} annotation ${i} good colour`);

      assert.ok(typeof annotation.textExpr !== 'undefined',
        `${prefix} annotation ${i} textExpr`);
      if (i === 2) {
        assert.ok(typeof annotation.labelPosition !== 'undefined',
          `${prefix} annotation ${i} labelPosition`);
      }
    }
  }

  /**
   * Check a quantification.
   *
   * @param {object} quantification The quantification to check.
   * @param {string} prefix A message prefix.
   */
  function checkQuantification(quantification, prefix) {
    assert.ok(typeof quantification.min !== 'undefined',
      `${prefix} quantification.min`);
    assert.ok(typeof quantification.max !== 'undefined',
      `${prefix} quantification.max`);
    assert.ok(typeof quantification.mean !== 'undefined',
      `${prefix} quantification.mean`);
    assert.ok(typeof quantification.surface !== 'undefined',
      `${prefix} quantification.surface`);
  }

  /**
   * Check an arrow annotation group.
   *
   * @param {AnnotationGroup} annotationGroup The group to check.
   */
  function checkArrowGroup(annotationGroup) {
    const annotations = annotationGroup.getList();
    for (let i = 0; i < annotations.length; ++i) {
      const annotation = annotations[i];
      const prefix = `arrow annotation ${i}`;
      assert.ok(annotation.mathShape instanceof Point2D,
        `${prefix} mathShape`);
      assert.ok(typeof annotation.quantification === 'undefined',
        `${prefix} quantification`);
      if (i !== 0) {
        assert.equal(annotation.textExpr, 'label',
          `${prefix} annotation ${i} good textExpr`);
      }
    }
  }

  /**
   * Check a circle annotation group.
   *
   * @param {AnnotationGroup} annotationGroup The group to check.
   */
  function checkCircleGroup(annotationGroup) {
    const annotations = annotationGroup.getList();
    for (let i = 0; i < annotations.length; ++i) {
      const annotation = annotations[i];
      const prefix = `circle annotation ${i}`;
      assert.ok(annotation.mathShape instanceof Circle,
        `${prefix} mathShape`);
      assert.equal(annotation.textExpr, '{surface}',
        `${prefix} annotation ${i} good textExpr`);

      assert.ok(typeof annotation.quantification.radius !== 'undefined',
        `${prefix} quantification.radius`);
      const radius = Math.round(
        parseFloat(annotation.quantification.radius.value));
      assert.equal(radius, 2, `${prefix} radius is ~2`);
      assert.equal(annotation.quantification.radius.unit, 'unit.mm',
        `${prefix} radius unit`);
      checkQuantification(annotation.quantification, assert, prefix);
    }
  }

  /**
   * Check an ellipse annotation group.
   *
   * @param {AnnotationGroup} annotationGroup The group to check.
   */
  function checkEllipseGroup(annotationGroup) {
    const annotations = annotationGroup.getList();
    for (let i = 0; i < annotations.length; ++i) {
      const annotation = annotations[i];
      const prefix = `ellipse annotation ${i}`;
      assert.ok(annotation.mathShape instanceof Ellipse,
        `${prefix} mathShape`);
      assert.equal(annotation.textExpr, '{surface}',
        `${prefix} annotation ${i} good textExpr`);

      assert.ok(typeof annotation.quantification.longAxis !== 'undefined',
        `${prefix} quantification.a`);
      assert.ok(typeof annotation.quantification.shortAxis !== 'undefined',
        `${prefix} quantification.b`);
      const longAxis = Math.round(parseFloat(
        annotation.quantification.longAxis.value));
      assert.equal(longAxis, 3, `${prefix} longAxis is ~3`);
      assert.equal(annotation.quantification.longAxis.unit, 'unit.mm',
        `${prefix} longAxis unit`);
      const shortAxis = Math.round(parseFloat(
        annotation.quantification.shortAxis.value));
      assert.equal(shortAxis, 2, `${prefix} shortAxis is ~2`);
      assert.equal(annotation.quantification.shortAxis.unit, 'unit.mm',
        `${prefix} shortAxis unit`);
      checkQuantification(annotation.quantification, assert, prefix);
    }
  }

  /**
   * Check a protractor annotation group.
   *
   * @param {AnnotationGroup} annotationGroup The group to check.
   */
  function checkProtractorGroup(annotationGroup) {
    const annotations = annotationGroup.getList();
    for (let i = 0; i < annotations.length; ++i) {
      const annotation = annotations[i];
      const prefix = `protractor annotation ${i}`;
      assert.ok(annotation.mathShape instanceof Protractor,
        `${prefix} mathShape`);
      assert.equal(annotation.textExpr, '{angle}',
        `${prefix} annotation ${i} good textExpr`);

      assert.ok(typeof annotation.quantification.angle !== 'undefined',
        `${prefix} quantification.angle`);
      const angle = Math.round(parseFloat(
        annotation.quantification.angle.value));
      assert.equal(angle, 90, `${prefix} angle is ~90`);
      assert.equal(annotation.quantification.angle.unit, 'unit.degree',
        `${prefix} angle unit`);
    }
  }

  /**
   * Check a rectangle annotation group.
   *
   * @param {AnnotationGroup} annotationGroup The group to check.
   */
  function checkRectangleGroup(annotationGroup) {
    const annotations = annotationGroup.getList();
    for (let i = 0; i < annotations.length; ++i) {
      const annotation = annotations[i];
      const prefix = `rectangle annotation ${i}`;
      assert.ok(annotation.mathShape instanceof Rectangle,
        `${prefix} mathShape`);
      assert.equal(annotation.textExpr, '{surface}',
        `${prefix} annotation ${i} good textExpr`);

      assert.ok(typeof annotation.quantification.width !== 'undefined',
        `${prefix} quantification.width`);
      assert.ok(typeof annotation.quantification.height !== 'undefined',
        `${prefix} quantification.height`);
      const width = Math.round(parseFloat(
        annotation.quantification.width.value));
      assert.equal(width, 6, `${prefix} width is ~6`);
      assert.equal(annotation.quantification.width.unit, 'unit.mm',
        `${prefix} width unit`);
      const height = Math.round(parseFloat(
        annotation.quantification.height.value));
      assert.equal(height, 4, `${prefix} height is ~4`);
      assert.equal(annotation.quantification.height.unit, 'unit.mm',
        `${prefix} height unit`);
      checkQuantification(annotation.quantification, assert, prefix);
    }
  }

  /**
   * Check a roi annotation group.
   *
   * @param {AnnotationGroup} annotationGroup The group to check.
   */
  function checkRoiGroup(annotationGroup) {
    const annotations = annotationGroup.getList();
    for (let i = 0; i < annotations.length; ++i) {
      const annotation = annotations[i];
      const prefix = `roi annotation ${i}`;
      assert.ok(annotation.mathShape instanceof ROI,
        `${prefix} mathShape`);
      if (i !== 0) {
        assert.equal(annotation.textExpr, 'label',
          `${prefix} annotation ${i} good textExpr`);
      }

      assert.ok(typeof annotation.quantification === 'undefined',
        `${prefix} quantification`);
    }
  }

  /**
   * Check a ruler annotation group.
   *
   * @param {AnnotationGroup} annotationGroup The group to check.
   */
  function checkRulerGroup(annotationGroup) {
    const annotations = annotationGroup.getList();
    for (let i = 0; i < annotations.length; ++i) {
      const annotation = annotations[i];
      const prefix = `ruler annotation ${i}`;
      assert.ok(annotation.mathShape instanceof Line,
        `${prefix} mathShape`);
      assert.equal(annotation.textExpr, '{length}',
        `${prefix} annotation ${i} good textExpr`);

      assert.ok(typeof annotation.quantification.length !== 'undefined',
        `${prefix} quantification.length`);
      const length = Math.round(
        parseInt(annotation.quantification.length.value, 10));
      assert.equal(length, 4, `${prefix} length is ~4`);
      assert.equal(annotation.quantification.length.unit, 'unit.mm',
        `${prefix} length unit`);
    }
  }

  /**
   * Check a bidimensional annotation group.
   *
   * @param {AnnotationGroup} annotationGroup The group to check.
   */
  function checkBidimensionalGroup(annotationGroup) {
    const annotations = annotationGroup.getList();
    for (let i = 0; i < annotations.length; ++i) {
      const annotation = annotations[i];
      const prefix = `bidimensional annotation ${i}`;
      assert.ok(annotation.mathShape instanceof BidimensionalLine,
        `${prefix} mathShape`);
      assert.ok(
        annotation.textExpr === '{longAxis} x {shortAxis}' ||
        annotation.textExpr === '{longAxis}',
        `${prefix} annotation ${i} good textExpr (${
          annotation.textExpr })`
      );
      assert.ok(typeof annotation.quantification.longAxis !== 'undefined',
        `${prefix} quantification.longAxis`);
      assert.ok(typeof annotation.quantification.shortAxis !== 'undefined',
        `${prefix} quantification.shortAxis`);
    }
  }

  //----------------------------------------------------
  // dwv 0.34
  //----------------------------------------------------

  /**
   * Tests for {@link Annotation} from dwv034 containing an arrow.
   *
   * @function module:tests/annotation~readDwv034Arrow
   */
  test('Read dwv034 arrow', () => {
    const annotationGroup = get034AnnotationGroup(dwv034Arrow);
    checkGroupCommonProperties(annotationGroup, 'arrow');
    checkArrowGroup(annotationGroup);
  });

  /**
   * Tests for {@link Annotation} from dwv034 containing a circle.
   *
   * @function module:tests/annotation~readDwv034Circle
   */
  test('Read dwv034 circle', () => {
    const annotationGroup = get034AnnotationGroup(dwv034Circle);
    checkGroupCommonProperties(annotationGroup, 'circle');
    checkCircleGroup(annotationGroup);
  });

  /**
   * Tests for {@link Annotation} from dwv034 containing a ellipse.
   *
   * @function module:tests/annotation~readDwv034Ellipse
   */
  test('Read dwv034 ellipse', () => {
    const annotationGroup = get034AnnotationGroup(dwv034Ellipse);
    checkGroupCommonProperties(annotationGroup, 'ellipse');
    checkEllipseGroup(annotationGroup);
  });

  /**
   * Tests for {@link Annotation} from dwv034 containing a protractor.
   *
   * @function module:tests/annotation~readDwv034Protractor
   */
  test('Read dwv034 protractor', () => {
    const annotationGroup = get034AnnotationGroup(dwv034Protractor);
    checkGroupCommonProperties(annotationGroup, 'protractor');
    checkProtractorGroup(annotationGroup);
  });

  /**
   * Tests for {@link Annotation} from dwv034 containing a rectangle.
   *
   * @function module:tests/annotation~readDwv034Rectangle
   */
  test('Read dwv034 rectangle', () => {
    const annotationGroup = get034AnnotationGroup(dwv034Rectangle);
    checkGroupCommonProperties(annotationGroup, 'rectangle');
    checkRectangleGroup(annotationGroup);
  });

  /**
   * Tests for {@link Annotation} from dwv034 containing a ROI.
   *
   * @function module:tests/annotation~readDwv034Roi
   */
  test('Read dwv034 roi', () => {
    const annotationGroup = get034AnnotationGroup(dwv034Roi);
    checkGroupCommonProperties(annotationGroup, 'roi');
    checkRoiGroup(annotationGroup);
  });

  /**
   * Tests for {@link Annotation} from dwv034 containing a ruler.
   *
   * @function module:tests/annotation~readDwv034Ruler
   */
  test('Read dwv034 ruler', () => {
    const annotationGroup = get034AnnotationGroup(dwv034Ruler);
    checkGroupCommonProperties(annotationGroup, 'ruler');
    checkRulerGroup(annotationGroup);
  });

  //----------------------------------------------------
  // TID 1500 v0
  //----------------------------------------------------

  /**
   * Tests for {@link Annotation} from tid1500 v0 containing an arrow.
   *
   * @function module:tests/annotation~readTid1500V0Arrow
   */
  test(
    'Read tid1500 v0 arrow - #DWV-REQ-IO-06-003 Load DICOM SR annotations',
    () => {
      const annotationGroup = getAnnotationGroup(tid1500v0Arrow);
      checkGroupCommonProperties(annotationGroup, 'arrow');
      checkArrowGroup(annotationGroup);
    });

  /**
   * Tests for {@link Annotation} from tid1500 v0 containing a circle.
   *
   * @function module:tests/annotation~readTid1500V0Circle
   */
  test(
    'Read tid1500 v0 circle - #DWV-REQ-IO-06-003 Load DICOM SR annotations',
    () => {
      const annotationGroup = getAnnotationGroup(tid1500v0Circle);
      checkGroupCommonProperties(annotationGroup, 'circle');
      checkCircleGroup(annotationGroup);
    });

  /**
   * Tests for {@link Annotation} from tid1500 v0 containing an ellipse.
   *
   * @function module:tests/annotation~readTid1500V0Ellipse
   */
  test(
    'Read tid1500 v0 ellipse - #DWV-REQ-IO-06-003 Load DICOM SR annotations',
    () => {
      const annotationGroup = getAnnotationGroup(tid1500v0Ellipse);
      checkGroupCommonProperties(annotationGroup, 'ellipse');
      checkEllipseGroup(annotationGroup);
    });

  /**
   * Tests for {@link Annotation} from tid1500 v0 containing a protractor.
   *
   * @function module:tests/annotation~readTid1500V0Protractor
   */
  test(
    'Read tid1500 v0 protractor - #DWV-REQ-IO-06-003 Load DICOM SR annotations',
    () => {
      const annotationGroup = getAnnotationGroup(tid1500v0Protractor);
      checkGroupCommonProperties(annotationGroup, 'protractor');
      checkProtractorGroup(annotationGroup);
    });

  /**
   * Tests for {@link Annotation} from tid1500 v0 containing a rectangle.
   *
   * @function module:tests/annotation~readTid1500V0Rectangle
   */
  test(
    'Read tid1500 v0 rectangle - #DWV-REQ-IO-06-003 Load DICOM SR annotations',
    () => {
      const annotationGroup = getAnnotationGroup(tid1500v0Rectangle);
      checkGroupCommonProperties(annotationGroup, 'rectangle');
      checkRectangleGroup(annotationGroup);
    });

  /**
   * Tests for {@link Annotation} from tid1500 v0 containing a roi.
   *
   * @function module:tests/annotation~readTid1500V0Roi
   */
  test(
    'Read tid1500 v0 roi - #DWV-REQ-IO-06-003 Load DICOM SR annotations',
    () => {
      const annotationGroup = getAnnotationGroup(tid1500v0Roi);
      checkGroupCommonProperties(annotationGroup, 'roi');
      checkRoiGroup(annotationGroup);
    });

  /**
   * Tests for {@link Annotation} from tid1500 v0 containing a ruler.
   *
   * @function module:tests/annotation~readTid1500V0Ruler
   */
  test(
    'Read tid1500 v0 ruler - #DWV-REQ-IO-06-003 Load DICOM SR annotations',
    () => {
      const annotationGroup = getAnnotationGroup(tid1500v0Ruler);
      checkGroupCommonProperties(annotationGroup, 'ruler');
      checkRulerGroup(annotationGroup);
    });

  /**
   * Test BidimensionalLine DICOM SR import/export roundtrip.
   */
  test('BidimensionalLine DICOM SR import/export roundtrip', () => {
    // Create a BidimensionalLine with all properties
    const p1 = new Point2D(10, 20);
    const p2 = new Point2D(30, 40);
    const b = new BidimensionalLine(p1, p2);
    b.shortAxisLength = 12;
    b.shortAxisT = 0.6;
    b.shortAxisL1 = 7;
    b.shortAxisL2 = 5;
    // Set shortAxisCenter for export
    b.shortAxisCenter = new Point2D(22, 32);

    // Export to DICOM SR (SCOORD)
    const scoord = getScoordFromShape(b);
    // Import back to BidimensionalLine
    const b2 = getShapeFromScoord(scoord);

    // Check type and main axis
    assert.ok(
      b2 instanceof BidimensionalLine,
      'Imported shape is BidimensionalLine'
    );
    assert.equal(b2.getBegin().getX(), b.getBegin().getX(), 'Begin X matches');
    assert.equal(b2.getBegin().getY(), b.getBegin().getY(), 'Begin Y matches');
    assert.equal(b2.getEnd().getX(), b.getEnd().getX(), 'End X matches');
    assert.equal(b2.getEnd().getY(), b.getEnd().getY(), 'End Y matches');

    // Check short axis properties
    assert.closeTo(
      b2.shortAxisLength,
      b.shortAxisLength,
      1e-6,
      'shortAxisLength matches'
    );
    // L1 and L2 may be swapped or recalculated, but their sum should match
    assert.closeTo(
      b2.shortAxisL1 + b2.shortAxisL2,
      b.shortAxisLength,
      1e-6,
      'shortAxisL1 + shortAxisL2 matches shortAxisLength'
    );
    assert.ok(
      b2.shortAxisL1 > 0 && b2.shortAxisL2 > 0,
      'shortAxisL1 and L2 positive'
    );
    assert.closeTo(b2.shortAxisT, b.shortAxisT, 1e-2, 'shortAxisT matches');
    // Center is recalculated, but should be close
    assert.closeTo(
      b2.shortAxisCenter.getX(),
      b.shortAxisCenter.getX(),
      1,
      'shortAxisCenter X close'
    );
    assert.closeTo(
      b2.shortAxisCenter.getY(),
      b.shortAxisCenter.getY(),
      1,
      'shortAxisCenter Y close'
    );
  });

  /**
   * Tests for the referenced frame number of an {@link Annotation}:
   * 1-based, 0-based for data written by dwv up to v0.37.0-beta.17.
   *
   * @function module:tests/annotation~readReferencedFrameNumber
   */
  test('Read referenced frame number', () => {
    /**
     * Add a referenced frame number to the image references.
     *
     * @param {object} elements The data elements.
     * @param {string} frameNumber The frame number.
     */
    function addFrameNumber(elements, frameNumber) {
      for (const element of Object.values(elements)) {
        if (element.vr === 'SQ') {
          for (const item of element.value) {
            if (typeof item['00081199'] !== 'undefined') {
              item['00081160'] = {vr: 'IS', value: [frameNumber]};
            }
            addFrameNumber(item, frameNumber);
          }
        }
      }
    }

    const dwvUidPrefix = '1.2.826.0.1.3680043.9.7278.1';
    const cases = [
      // fixture class uid: dwv v0.35.0-beta.21
      {name: 'old dwv', classUid: undefined, frameNumber: '2'},
      {
        name: 'last 0-based dwv',
        classUid: `${dwvUidPrefix}.0.37.0.99.17`,
        frameNumber: '2'
      },
      {
        name: 'new dwv',
        classUid: `${dwvUidPrefix}.0.37.0.99.18`,
        frameNumber: '3'
      },
      {name: 'non dwv', classUid: '1.2.3.4', frameNumber: '3'}
    ];
    for (const testCase of cases) {
      const dicomParser = new DicomParser();
      dicomParser.parse(b64urlToArrayBuffer(tid1500v0Ruler));
      const tags = dicomParser.getDicomElements();
      if (typeof testCase.classUid !== 'undefined') {
        tags['00020012'].value = [testCase.classUid];
      }
      addFrameNumber(tags, testCase.frameNumber);
      const group = new AnnotationGroupFactory().create(tags);
      for (const annotation of group.getList()) {
        assert.equal(annotation.referencedFrameNumber, 3, testCase.name);
      }
    }
  });

  /**
   * Tests for {@link Annotation} from tid1500 v0 containing a
   * BidimensionalLine.
   *
   * @function module:tests/annotation~readTid1500V0Bidimensional
   */
  test(
    'Read tid1500 v0 bidimensional - ' +
    '#DWV-REQ-IO-06-003 Load DICOM SR annotations',
    () => {
      const annotationGroup = getAnnotationGroup(tid1500v0Bidimensional);
      checkGroupCommonProperties(annotationGroup, 'bidimensional');
      checkBidimensionalGroup(annotationGroup);
    });

});