DWVv0.37.0
tests/image/positionHelper.test.jsjavascript
import {describe, test, assert, beforeEach} from 'vitest';
import {PositionHelper} from '../../src/image/positionHelper.js';
import {Size} from '../../src/image/size.js';
import {Spacing} from '../../src/image/spacing.js';
import {Geometry} from '../../src/image/geometry.js';
import {Index} from '../../src/math/index.js';
import {Point3D} from '../../src/math/point.js';

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

// ---------------------------------------------------------------------------
// Factory helpers
// ---------------------------------------------------------------------------

/**
 * Build a Geometry with unit spacing and identity orientation.
 *
 * @param {number[]} sizeArr Size values [nx, ny, nz].
 * @param {Point3D} [origin] World origin (default: 0,0,0).
 * @returns {Geometry} The constructed geometry.
 */
function makeGeometry(sizeArr, origin = new Point3D(0, 0, 0)) {
  return new Geometry(
    [origin],
    new Size(sizeArr),
    new Spacing(sizeArr.map(() => 1))
  );
}

/**
 * Build a mock view backed by a real Geometry.
 * `currentPosition` is stored in a shared closure so the helper's
 * position accessor and the geometry stay consistent.
 *
 * @param {number[]} sizeArr Geometry size values.
 * @param {number[]} initIndex Initial position as index values.
 * @param {number} [scrollDim] Scroll dimension (default: 2 / z).
 * @param {Point3D} [origin] World origin.
 * @returns {{helper: PositionHelper, geometry: Geometry}} The helper
 *   and the underlying geometry.
 */
function makeHelper(
  sizeArr, initIndex, scrollDim = 2, origin = new Point3D(0, 0, 0)
) {
  const geometry = makeGeometry(sizeArr, origin);
  let currentPosition = geometry.indexToWorld(new Index(initIndex));

  const view = {
    getImage: () => ({getGeometry: () => geometry}),
    getCurrentPosition: () => currentPosition,
    getScrollDimIndex: () => scrollDim,
    setCurrentPosition: (pos) => {
      currentPosition = pos;
      return true;
    }
  };

  return {helper: new PositionHelper(view), geometry};
}

/**
 * Build a position helper on an existing geometry.
 *
 * @param {Geometry} geometry The geometry.
 * @param {number[]} initIndex Initial position as index values.
 * @param {number} [scrollDim] Scroll dimension (default: 2 / z).
 * @returns {PositionHelper} The helper.
 */
function makeViewHelper(geometry, initIndex, scrollDim = 2) {
  let currentPosition = geometry.indexToWorld(new Index(initIndex));
  const view = {
    getImage: () => ({getGeometry: () => geometry}),
    getCurrentPosition: () => currentPosition,
    getScrollDimIndex: () => scrollDim,
    setCurrentPosition: (pos) => {
      currentPosition = pos;
      return true;
    }
  };
  return new PositionHelper(view);
}

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

describe('image', () => {

  // 3×4×5 grid, starting at index [1, 2, 3]
  let helper;
  let geometry;

  beforeEach(() => {
    ({helper, geometry} = makeHelper([3, 4, 5], [1, 2, 3]));
  });

  // -------------------------------------------------------------------------
  // Accessors
  // -------------------------------------------------------------------------

  /**
   * Tests that getGeometry returns the image geometry.
   *
   * @function module:tests/image~positionHelperGetGeometry
   */
  test('PositionHelper getGeometry returns the image geometry', () => {
    assert.equal(helper.getGeometry(), geometry);
  });

  /**
   * Tests that getScrollDimIndex returns the view scroll dim.
   *
   * @function module:tests/image~positionHelperGetScrollDim
   */
  test('PositionHelper getScrollDimIndex returns scroll dim from view', () => {
    assert.equal(helper.getScrollDimIndex(), 2);
  });

  /**
   * Tests getMaximumDimValue for each axis.
   *
   * @function module:tests/image~positionHelperGetMaxDimValue
   */
  test('PositionHelper getMaximumDimValue returns size - 1', () => {
    assert.equal(helper.getMaximumDimValue(0), 2, 'x: 3-1');
    assert.equal(helper.getMaximumDimValue(1), 3, 'y: 4-1');
    assert.equal(helper.getMaximumDimValue(2), 4, 'z: 5-1');
  });

  /**
   * Tests that getMaximumScrollValue returns the max along the scroll dim.
   *
   * @function module:tests/image~positionHelperGetMaxScrollValue
   */
  test('PositionHelper getMaximumScrollValue returns max scroll index', () => {
    assert.equal(helper.getMaximumScrollValue(), 4, 'z max = 5-1');
  });

  // -------------------------------------------------------------------------
  // Position / index accessors
  // -------------------------------------------------------------------------

  /**
   * Tests that getCurrentPosition matches the initial position.
   *
   * @function module:tests/image~positionHelperGetCurrentPosition
   */
  test('PositionHelper getCurrentPosition reflects initial index', () => {
    const pos = helper.getCurrentPosition();
    // index [1,2,3] with unit spacing and (0,0,0) origin → world [1,2,3]
    assert.equal(pos.get(0), 1, 'x = 1');
    assert.equal(pos.get(1), 2, 'y = 2');
    assert.equal(pos.get(2), 3, 'z = 3');
  });

  /**
   * Tests that getCurrentIndex matches the initial index.
   *
   * @function module:tests/image~positionHelperGetCurrentIndex
   */
  test('PositionHelper getCurrentIndex matches initial index', () => {
    const idx = helper.getCurrentIndex();
    assert.equal(idx.get(0), 1, 'i = 1');
    assert.equal(idx.get(1), 2, 'j = 2');
    assert.equal(idx.get(2), 3, 'k = 3');
  });

  /**
   * Tests getCurrentPositionDimValue for each axis.
   *
   * @function module:tests/image~positionHelperGetCurrentDimValue
   */
  test(
    'PositionHelper getCurrentPositionDimValue returns index per axis',
    () => {
      assert.equal(helper.getCurrentPositionDimValue(0), 1, 'dim 0 → 1');
      assert.equal(helper.getCurrentPositionDimValue(1), 2, 'dim 1 → 2');
      assert.equal(helper.getCurrentPositionDimValue(2), 3, 'dim 2 → 3');
    }
  );

  /**
   * Tests that getCurrentPositionScrollValue returns the scroll-axis index.
   *
   * @function module:tests/image~positionHelperGetCurrentScrollValue
   */
  test('PositionHelper getCurrentPositionScrollValue returns z index', () => {
    assert.equal(helper.getCurrentPositionScrollValue(), 3);
  });

  /**
   * Tests getCurrentPositionAtDimValue: modifies one dim, keeps others.
   *
   * @function module:tests/image~positionHelperGetCurrentAtDimValue
   */
  test(
    'PositionHelper getCurrentPositionAtDimValue replaces one axis',
    () => {
      const pos = helper.getCurrentPositionAtDimValue(2, 0);
      assert.equal(pos.get(0), 1, 'x unchanged');
      assert.equal(pos.get(1), 2, 'y unchanged');
      assert.equal(pos.get(2), 0, 'z replaced');
    }
  );

  /**
   * Tests getCurrentPositionAtScrollValue: modifies the scroll axis.
   *
   * @function module:tests/image~positionHelperGetCurrentAtScrollValue
   */
  test(
    'PositionHelper getCurrentPositionAtScrollValue replaces scroll axis',
    () => {
      const pos = helper.getCurrentPositionAtScrollValue(0);
      assert.equal(pos.get(2), 0, 'z replaced by scroll value');
    }
  );

  // -------------------------------------------------------------------------
  // setCurrentPosition
  // -------------------------------------------------------------------------

  /**
   * Tests that setCurrentPosition updates the current position.
   *
   * @function module:tests/image~positionHelperSetPosition
   */
  test('PositionHelper setCurrentPosition updates position', () => {
    const newPos = geometry.indexToWorld(new Index([0, 0, 0]));
    const res = helper.setCurrentPosition(newPos);
    assert.ok(res, 'returns true');
    assert.equal(helper.getCurrentPositionDimValue(2), 0, 'z updated to 0');
  });

  /**
   * Tests that setCurrentPosition with undefined returns false without update.
   *
   * @function module:tests/image~positionHelperSetPositionUndefined
   */
  test('PositionHelper setCurrentPosition with undefined returns false', () => {
    const res = helper.setCurrentPosition(undefined);
    assert.notOk(res, 'returns false');
    assert.equal(
      helper.getCurrentPositionDimValue(2), 3, 'position unchanged'
    );
  });

  // -------------------------------------------------------------------------
  // Bounds checking
  // -------------------------------------------------------------------------

  /**
   * Tests isPositionInBounds for positions inside and outside the geometry.
   *
   * @function module:tests/image~positionHelperInBounds
   */
  test('PositionHelper isPositionInBounds returns true/false correctly', () => {
    // isPositionInBounds only checks the scroll dim (z)
    const inBounds = geometry.indexToWorld(new Index([0, 0, 4]));
    const outOfBounds = geometry.indexToWorld(new Index([0, 0, 5]));
    assert.ok(helper.isPositionInBounds(inBounds), 'z=4 in bounds');
    assert.notOk(helper.isPositionInBounds(outOfBounds), 'z=5 out of bounds');
  });

  /**
   * Tests setCurrentPositionSafe rejects an out-of-bounds position.
   *
   * @function module:tests/image~positionHelperSetSafe
   */
  test('PositionHelper setCurrentPositionSafe rejects out-of-bounds', () => {
    const outOfBounds = geometry.indexToWorld(new Index([0, 0, 5]));
    const res = helper.setCurrentPositionSafe(outOfBounds);
    assert.notOk(res, 'returns false');
    assert.equal(
      helper.getCurrentPositionDimValue(2), 3, 'position unchanged'
    );
  });

  // -------------------------------------------------------------------------
  // Increment / decrement
  // -------------------------------------------------------------------------

  /**
   * Tests getIncrementPosition and getDecrementPosition return
   * the neighbouring world points without moving.
   *
   * @function module:tests/image~positionHelperGetIncDec
   */
  test(
    'PositionHelper getIncrementPosition and getDecrementPosition',
    () => {
      const inc = helper.getIncrementPosition(2);
      assert.equal(inc.get(2), 4, 'z incremented from 3 to 4');
      assert.equal(
        helper.getCurrentPositionDimValue(2), 3, 'position not moved'
      );

      const dec = helper.getDecrementPosition(2);
      assert.equal(dec.get(2), 2, 'z decremented from 3 to 2');
    }
  );

  /**
   * Tests that incrementPosition moves when in bounds and fails at the max.
   *
   * @function module:tests/image~positionHelperIncrement
   */
  test(
    'PositionHelper incrementPosition: moves in bounds, fails at max',
    () => {
      // Start at z=3, max z=4 → one more step available
      assert.ok(helper.incrementPosition(2), 'first increment ok (z→4)');
      assert.equal(helper.getCurrentPositionDimValue(2), 4, 'z = 4');
      // Now at z=4 (max), next step is out of bounds
      assert.notOk(helper.incrementPosition(2), 'second increment fails');
      assert.equal(helper.getCurrentPositionDimValue(2), 4, 'z still 4');
    }
  );

  /**
   * Tests that decrementPosition moves when in bounds and fails at zero.
   *
   * @function module:tests/image~positionHelperDecrement
   */
  test('PositionHelper decrementPosition: moves in bounds, fails at 0', () => {
    // Start at z=3 — three decrements possible
    assert.ok(helper.decrementPosition(2), 'decrement ok (z→2)');
    assert.ok(helper.decrementPosition(2), 'decrement ok (z→1)');
    assert.ok(helper.decrementPosition(2), 'decrement ok (z→0)');
    assert.equal(helper.getCurrentPositionDimValue(2), 0, 'z = 0');
    assert.notOk(helper.decrementPosition(2), 'decrement fails at 0');
    assert.equal(helper.getCurrentPositionDimValue(2), 0, 'z still 0');
  });

  /**
   * Tests incrementPositionAlongScroll and decrementPositionAlongScroll.
   *
   * @function module:tests/image~positionHelperScrollIncDec
   */
  test('PositionHelper increment/decrementPositionAlongScroll', () => {
    assert.ok(helper.incrementPositionAlongScroll(), 'increment scroll z→4');
    assert.equal(helper.getCurrentPositionScrollValue(), 4, 'z = 4');
    assert.ok(helper.decrementPositionAlongScroll(), 'decrement scroll z→3');
    assert.equal(helper.getCurrentPositionScrollValue(), 3, 'z = 3');
  });

  // -------------------------------------------------------------------------
  // merge
  // -------------------------------------------------------------------------

  /**
   * Tests that merge throws when the two helpers have different scroll dims.
   *
   * @function module:tests/image~positionHelperMergeIncompatible
   */
  test('PositionHelper merge throws on incompatible scroll dims', () => {
    const {helper: h1} = makeHelper([3, 3, 2], [0, 0, 0], 2);
    const {helper: h2} = makeHelper([3, 3, 2], [0, 0, 0], 0);
    assert.throws(() => h1.merge(h2), Error);
  });

  /**
   * Tests that merge extends the geometry along the scroll dimension.
   *
   * @function module:tests/image~positionHelperMergeCompatible
   */
  test('PositionHelper merge extends the scroll size', () => {
    // Two single-slice 3×3 geometries at adjacent z positions
    const {helper: h1} = makeHelper(
      [3, 3, 1], [0, 0, 0], 2, new Point3D(0, 0, 0)
    );
    const {helper: h2} = makeHelper(
      [3, 3, 1], [0, 0, 0], 2, new Point3D(0, 0, 1)
    );
    h1.merge(h2);
    assert.equal(
      h1.getMaximumScrollValue(), 1,
      'two slices merged → max scroll = 1'
    );
  });

  test(
    'PositionHelper merge scrolls a 4D underlay with a 3D overlay ' +
    'at volume > 0',
    () => {
      const info = {source: 'DiffusionBValue'};
      const origin0 = new Point3D(0, 0, 0);
      const origin1 = new Point3D(0, 0, 1);
      const underlayGeometry = new Geometry(
        [origin0], new Size([1, 1, 1]), new Spacing([1, 1, 1]),
        undefined, {id: {...info, value: 0}});
      underlayGeometry.appendOrigin(origin1, 1, 0);
      underlayGeometry.appendFrame(origin0, {id: {...info, value: 17}});
      underlayGeometry.appendOrigin(origin1, 1, 17);
      const overlayGeometry = new Geometry(
        [origin0, origin1],
        new Size([1, 1, 2]),
        new Spacing([1, 1, 1]));

      const underlay = makeViewHelper(underlayGeometry, [0, 0, 0, 1]);
      const overlay = makeViewHelper(overlayGeometry, [0, 0, 0]);
      underlay.merge(overlay);

      assert.equal(underlay.getCurrentIndex().get(3), 1, 'volume index');
      assert.ok(underlay.incrementPositionAlongScroll(), 'scroll slice');
      assert.equal(
        underlay.getCurrentPositionScrollValue(), 1, 'next slice');
      assert.equal(
        underlay.getCurrentIndex().get(3), 1, 'volume stays 1');
    }
  );

});