refactor: proper use of coordinate systems to interpret transforms

Author: dbirman

web/src/__tests__/coord-systems.test.js

@@ -0,0 +1,222 @@
+/**
+ * coord-systems.test.js — Unit tests for parseTranslation and parseDeviceConfigCoords.
+ *
+ * Canonical output conventions:
+ *   ap:    positive = anterior
+ *   ml:    positive = right
+ *   dv:    positive = dorsal (superior)
+ *   depth: positive = deeper from brain surface (always abs)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { parseTranslation, parseDeviceConfigCoords } from '../lib/coord-systems.js';
+
+// ── Fixtures ────────────────────────────────────────────────────────────────
+
+/**
+ * The BREGMA_ARID coordinate system as it appears in procedures.coordinate_system:
+ *   AP axis  → Posterior_to_anterior  (positive = anterior)
+ *   ML axis  → Left_to_right          (positive = right)
+ *   SI axis  → Superior_to_inferior   (positive = ventral, i.e. canonical DV flipped)
+ *   Depth    → depth-from-surface     (index 3, always abs)
+ */
+const BREGMA_ARID_COORD_SYS = {
+  object_type: 'Coordinate system',
+  name: 'BREGMA_ARID',
+  origin: 'Bregma',
+  axes: [
+    { object_type: 'Axis', name: 'AP', direction: 'Posterior_to_anterior' },
+    { object_type: 'Axis', name: 'ML', direction: 'Left_to_right' },
+    { object_type: 'Axis', name: 'SI', direction: 'Superior_to_inferior' },
+    { object_type: 'Axis', name: 'Depth', direction: 'Superior_to_inferior' }, // index 3 — ignored (depth always uses abs v[3])
+  ],
+  axis_unit: 'millimeter',
+};
+
+// ── parseTranslation ────────────────────────────────────────────────────────
+
+describe('parseTranslation', () => {
+  describe('BREGMA_ARID coordinate system', () => {
+    it('maps PA axis correctly: positive value → positive AP (anterior)', () => {
+      // v[0]=1.3 along Posterior_to_anterior → ap = +1.3
+      const result = parseTranslation(BREGMA_ARID_COORD_SYS, [1.3, 0, 0, 0]);
+      expect(result.ap).toBeCloseTo(1.3);
+    });
+
+    it('maps PA axis correctly: negative value → negative AP (posterior)', () => {
+      const result = parseTranslation(BREGMA_ARID_COORD_SYS, [-1.5, 0, 0, 0]);
+      expect(result.ap).toBeCloseTo(-1.5);
+    });
+
+    it('maps LR axis correctly: positive value → positive ML (right)', () => {
+      // v[1]=1.8 along Left_to_right → ml = +1.8
+      const result = parseTranslation(BREGMA_ARID_COORD_SYS, [0, 1.8, 0, 0]);
+      expect(result.ml).toBeCloseTo(1.8);
+    });
+
+    it('maps LR axis correctly: negative value → negative ML (left)', () => {
+      const result = parseTranslation(BREGMA_ARID_COORD_SYS, [0, -1.8, 0, 0]);
+      expect(result.ml).toBeCloseTo(-1.8);
+    });
+
+    it('maps SI axis correctly: positive value → negative DV (ventral)', () => {
+      // v[2]=1 along Superior_to_inferior → dv = -1 (ventral in canonical)
+      const result = parseTranslation(BREGMA_ARID_COORD_SYS, [0, 0, 1, 0]);
+      expect(result.dv).toBeCloseTo(-1);
+    });
+
+    it('maps SI axis correctly: negative value → positive DV (dorsal)', () => {
+      const result = parseTranslation(BREGMA_ARID_COORD_SYS, [0, 0, -1, 0]);
+      expect(result.dv).toBeCloseTo(1);
+    });
+
+    it('depth is always abs of v[3] regardless of sign', () => {
+      expect(parseTranslation(BREGMA_ARID_COORD_SYS, [0, 0, 0, 4.4]).depth).toBeCloseTo(4.4);
+      expect(parseTranslation(BREGMA_ARID_COORD_SYS, [0, 0, 0, -4.4]).depth).toBeCloseTo(4.4);
+    });
+
+    it('parses a complete realistic probe translation correctly', () => {
+      // [AP=1.3, ML=-1.8, SI=0, depth=4.4]
+      const result = parseTranslation(BREGMA_ARID_COORD_SYS, [1.3, -1.8, 0, 4.4]);
+      expect(result.ap).toBeCloseTo(1.3);
+      expect(result.ml).toBeCloseTo(-1.8);
+      expect(result.dv).toBeCloseTo(0);
+      expect(result.depth).toBeCloseTo(4.4);
+    });
+
+    it('parses a right-hemisphere probe correctly', () => {
+      // [AP=1.1, ML=1.8, SI=0, depth=4.4]
+      const result = parseTranslation(BREGMA_ARID_COORD_SYS, [1.1, 1.8, 0, 4.4]);
+      expect(result.ap).toBeCloseTo(1.1);
+      expect(result.ml).toBeCloseTo(1.8);
+      expect(result.depth).toBeCloseTo(4.4);
+    });
+
+    it('parses a posterior probe correctly', () => {
+      // [AP=-1.5, ML=3.0, SI=0, depth=3.9]
+      const result = parseTranslation(BREGMA_ARID_COORD_SYS, [-1.5, 3.0, 0, 3.9]);
+      expect(result.ap).toBeCloseTo(-1.5);
+      expect(result.ml).toBeCloseTo(3.0);
+      expect(result.depth).toBeCloseTo(3.9);
+    });
+  });
+
+  describe('axis direction sign conventions', () => {
+    it('Anterior_to_posterior: positive value → negative AP (posterior)', () => {
+      const cs = { axes: [{ direction: 'Anterior_to_posterior' }] };
+      expect(parseTranslation(cs, [2, 0, 0, 0]).ap).toBeCloseTo(-2);
+    });
+
+    it('Posterior_to_anterior: positive value → positive AP (anterior)', () => {
+      const cs = { axes: [{ direction: 'Posterior_to_anterior' }] };
+      expect(parseTranslation(cs, [2, 0, 0, 0]).ap).toBeCloseTo(2);
+    });
+
+    it('Left_to_right: positive value → positive ML (right)', () => {
+      const cs = { axes: [{ direction: 'Left_to_right' }] };
+      expect(parseTranslation(cs, [3, 0, 0, 0]).ml).toBeCloseTo(3);
+    });
+
+    it('Right_to_left: positive value → negative ML (left)', () => {
+      const cs = { axes: [{ direction: 'Right_to_left' }] };
+      expect(parseTranslation(cs, [3, 0, 0, 0]).ml).toBeCloseTo(-3);
+    });
+
+    it('Superior_to_inferior: positive value → negative DV (ventral)', () => {
+      const cs = { axes: [{ direction: 'Superior_to_inferior' }] };
+      expect(parseTranslation(cs, [1, 0, 0, 0]).dv).toBeCloseTo(-1);
+    });
+
+    it('Inferior_to_superior: positive value → positive DV (dorsal)', () => {
+      const cs = { axes: [{ direction: 'Inferior_to_superior' }] };
+      expect(parseTranslation(cs, [1, 0, 0, 0]).dv).toBeCloseTo(1);
+    });
+  });
+
+  describe('null/missing coordinate system fallback', () => {
+    it('null coordinate system uses BREGMA_ARID index order: v0=AP+, v1=ML+, v2=DV+', () => {
+      const result = parseTranslation(null, [1.3, -1.8, 0, 4.4]);
+      expect(result.ap).toBeCloseTo(1.3);
+      expect(result.ml).toBeCloseTo(-1.8);
+      expect(result.dv).toBeCloseTo(0);
+      expect(result.depth).toBeCloseTo(4.4);
+    });
+
+    it('missing axes array falls back to index order', () => {
+      const result = parseTranslation({ name: 'CUSTOM' }, [2.0, -1.0, 0, 3.0]);
+      expect(result.ap).toBeCloseTo(2.0);
+      expect(result.ml).toBeCloseTo(-1.0);
+      expect(result.depth).toBeCloseTo(3.0);
+    });
+
+    it('empty translation returns zeros with null depth', () => {
+      const result = parseTranslation(null, []);
+      expect(result.ap).toBe(0);
+      expect(result.ml).toBe(0);
+      expect(result.dv).toBeNull();
+      expect(result.depth).toBeNull();
+    });
+  });
+});
+
+// ── parseDeviceConfigCoords ──────────────────────────────────────────────────
+
+describe('parseDeviceConfigCoords', () => {
+  it('reads coordinate_system and first Translation from transform', () => {
+    const deviceConfig = {
+      coordinate_system: BREGMA_ARID_COORD_SYS,
+      transform: [
+        { object_type: 'Translation', translation: [1.3, -1.8, 0, 4.4] },
+      ],
+    };
+    const result = parseDeviceConfigCoords(deviceConfig);
+    expect(result.ap).toBeCloseTo(1.3);
+    expect(result.ml).toBeCloseTo(-1.8);
+    expect(result.depth).toBeCloseTo(4.4);
+  });
+
+  it('skips non-Translation transform entries to find Translation', () => {
+    const deviceConfig = {
+      coordinate_system: BREGMA_ARID_COORD_SYS,
+      transform: [
+        { object_type: 'Rotation', angles: [0, 0, 0] },
+        { object_type: 'Translation', translation: [1.1, 1.8, 0, -4.4] },
+      ],
+    };
+    const result = parseDeviceConfigCoords(deviceConfig);
+    expect(result.ap).toBeCloseTo(1.1);
+    expect(result.ml).toBeCloseTo(1.8);
+    expect(result.depth).toBeCloseTo(4.4);
+  });
+
+  it('falls back gracefully when no coordinate_system present', () => {
+    const deviceConfig = {
+      coordinate_system: null,
+      transform: [
+        { object_type: 'Translation', translation: [2.0, 1.0, 0, 3.5] },
+      ],
+    };
+    const result = parseDeviceConfigCoords(deviceConfig);
+    expect(result.ap).toBeCloseTo(2.0);
+    expect(result.ml).toBeCloseTo(1.0);
+    expect(result.depth).toBeCloseTo(3.5);
+  });
+
+  it('returns zeros when no transform present', () => {
+    const deviceConfig = {
+      coordinate_system: BREGMA_ARID_COORD_SYS,
+      transform: [],
+    };
+    const result = parseDeviceConfigCoords(deviceConfig);
+    expect(result.ap).toBe(0);
+    expect(result.ml).toBe(0);
+    expect(result.depth).toBeNull();
+  });
+
+  it('handles null deviceConfig gracefully', () => {
+    const result = parseDeviceConfigCoords(null);
+    expect(result.ap).toBe(0);
+    expect(result.ml).toBe(0);
+    expect(result.depth).toBeNull();
+  });
+});

web/src/lib/coord-systems.js

@@ -0,0 +1,111 @@
+/**
+ * coord-systems.js — Coordinate system parsing for AIND procedure metadata.
+ *
+ * Converts a `coordinate_system` object (from a device_config or procedure) plus
+ * a `translation` array into canonical brain coordinates:
+ *
+ *   ap    — mm from bregma, positive = anterior
+ *   ml    — mm from bregma, positive = right
+ *   dv    — mm from bregma, positive = dorsal (up)
+ *   depth — mm from brain surface, always positive
+ *
+ * The translation array has up to 4 values: [v0, v1, v2, v3].
+ *   v0..v2 correspond to coordinate_system.axes[0..2] in order.
+ *   v3 is always depth-from-surface (axis-independent, sign is ignored).
+ *
+ * If no coordinate_system is provided, falls back to the BREGMA_ARID convention:
+ *   v0 = AP (positive anterior), v1 = ML (positive right), v2 = DV, v3 = depth.
+ */
+
+/**
+ * Map an axis direction string to a canonical dimension and the sign
+ * needed to convert from "positive in named direction" to "positive in
+ * canonical direction" (anterior, right, dorsal).
+ *
+ * Supported directions (case-insensitive):
+ *   ML: "Left_to_right", "Right_to_left"
+ *   AP: "Anterior_to_posterior", "Posterior_to_anterior"
+ *   DV: "Inferior_to_superior", "Superior_to_inferior"
+ *
+ * Returns { dim: 'ap'|'ml'|'dv', sign: 1|-1 } or null if unrecognised.
+ */
+function _directionToCanonical(direction) {
+  if (!direction) return null;
+  const dir = direction.toLowerCase().trim();
+
+  // ── ML (canonical: right = positive) ──────────────────────────────
+  if (dir === 'left_to_right') return { dim: 'ml', sign: 1 };
+  if (dir === 'right_to_left') return { dim: 'ml', sign: -1 };
+
+  // ── AP (canonical: anterior = positive) ───────────────────────────
+  if (dir === 'anterior_to_posterior') return { dim: 'ap', sign: -1 }; // positive direction is posterior → flip
+  if (dir === 'posterior_to_anterior') return { dim: 'ap', sign: 1 };  // positive direction is anterior ✓
+
+  // ── DV (canonical: dorsal = positive) ─────────────────────────────
+  if (dir === 'superior_to_inferior') return { dim: 'dv', sign: -1 }; // positive direction is ventral → flip
+  if (dir === 'inferior_to_superior') return { dim: 'dv', sign: 1 };  // positive direction is dorsal ✓
+
+  console.warn('[coord-systems] Unrecognised axis direction:', direction);
+  return null;
+}
+
+/**
+ * Parse a coordinate_system object and a translation array into canonical
+ * brain coordinates.
+ *
+ * @param {object|null} coordinateSystem - The coordinate_system object from metadata,
+ *   or null to use the BREGMA_ARID fallback (v0=AP, v1=ML, v2=DV, v3=depth).
+ * @param {number[]} translation - Array of up to 4 numeric values.
+ * @returns {{ ap: number, ml: number, dv: number|null, depth: number|null }}
+ *   All values in millimetres, canonical sign conventions.
+ */
+export function parseTranslation(coordinateSystem, translation) {
+  const v = Array.isArray(translation) ? translation : [];
+  const safeNum = (x) => (x != null && isFinite(Number(x)) ? Number(x) : null);
+
+  // Always read depth from index 3 regardless of coordinate system
+  const depth = v.length > 3 ? Math.abs(safeNum(v[3]) ?? 0) : null;
+
+  // Fallback: BREGMA_ARID convention (v0=AP anterior+, v1=ML right+, v2=DV dorsal+)
+  if (!coordinateSystem || !Array.isArray(coordinateSystem.axes)) {
+    return {
+      ap:    safeNum(v[0]) ?? 0,
+      ml:    safeNum(v[1]) ?? 0,
+      dv:    safeNum(v[2]),
+      depth,
+    };
+  }
+
+  const result = { ap: 0, ml: 0, dv: null, depth };
+
+  coordinateSystem.axes.forEach((axis, i) => {
+    if (i >= 3) return; // only first 3 axis components
+    const val = safeNum(v[i]);
+    if (val == null) return;
+    const mapping = _directionToCanonical(axis?.direction);
+    if (!mapping) return;
+    result[mapping.dim] = val * mapping.sign;
+  });
+
+  return result;
+}
+
+/**
+ * Convenience wrapper: extract canonical coords from a device_config object.
+ * Reads device_config.coordinate_system and the first Translation in
+ * device_config.transform.
+ *
+ * @param {object} deviceConfig
+ * @returns {{ ap: number, ml: number, dv: number|null, depth: number|null }}
+ */
+export function parseDeviceConfigCoords(deviceConfig) {
+  const coordSys = deviceConfig?.coordinate_system ?? null;
+  let translation = null;
+  for (const t of (deviceConfig?.transform ?? [])) {
+    if (t?.object_type === 'Translation') {
+      translation = t.translation;
+      break;
+    }
+  }
+  return parseTranslation(coordSys, translation ?? []);
+}