feat: ephys visualization

Author: dbirman

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

@@ -9,7 +9,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { parseTranslation, parseDeviceConfigCoords } from '../lib/coord-systems.js';
+import { parseTranslation, parseDeviceConfigCoords, computeProbeDirection } from '../lib/coord-systems.js';
 
 // ── Fixtures ────────────────────────────────────────────────────────────────
 
@@ -220,3 +220,114 @@ describe('parseDeviceConfigCoords', () => {
     expect(result.depth).toBeNull();
   });
 });
+
+// ── computeProbeDirection ───────────────────────────────────────────────────
+
+describe('computeProbeDirection', () => {
+  it('returns +Z unit vector when no transforms are given (probe points anterior)', () => {
+    const [x, y, z] = computeProbeDirection([]);
+    expect(x).toBeCloseTo(0);
+    expect(y).toBeCloseTo(0);
+    expect(z).toBeCloseTo(1);
+  });
+
+  it('returns +Z when only a zero rotation is given', () => {
+    const [x, y, z] = computeProbeDirection([
+      { object_type: 'Rotation', angles: [0, 0, 0] },
+    ]);
+    expect(x).toBeCloseTo(0);
+    expect(y).toBeCloseTo(0);
+    expect(z).toBeCloseTo(1);
+  });
+
+  it('ignores Translation objects (only rotations affect direction)', () => {
+    const [x, y, z] = computeProbeDirection([
+      { object_type: 'Translation', translation: [10, 20, 30] },
+    ]);
+    expect(x).toBeCloseTo(0);
+    expect(y).toBeCloseTo(0);
+    expect(z).toBeCloseTo(1);
+  });
+
+  it('Rx(90°) rotates +Z to -Y (ventral)', () => {
+    // Rx: y1 = cos(90)*z_y - sin(90)*z_z = 0 - 1 = -1, z1 = sin(90)*0 + cos(90)*1 = 0
+    const [x, y, z] = computeProbeDirection([
+      { object_type: 'Rotation', angles: [90, 0, 0] },
+    ]);
+    expect(x).toBeCloseTo(0);
+    expect(y).toBeCloseTo(-1);
+    expect(z).toBeCloseTo(0);
+  });
+
+  it('Rx(-90°) rotates +Z to +Y (dorsal)', () => {
+    // Rx(-90): y1 = cos(-90)*0 - sin(-90)*1 = 1, z1 = sin(-90)*0 + cos(-90)*1 = 0
+    const [x, y, z] = computeProbeDirection([
+      { object_type: 'Rotation', angles: [-90, 0, 0] },
+    ]);
+    expect(x).toBeCloseTo(0);
+    expect(y).toBeCloseTo(1);
+    expect(z).toBeCloseTo(0);
+  });
+
+  it('Ry(90°) rotates +Z to +X (right/ML)', () => {
+    // Ry: x2 = cos(90)*0 + sin(90)*1 = 1, z2 = -sin(90)*0 + cos(90)*1 = 0
+    const [x, y, z] = computeProbeDirection([
+      { object_type: 'Rotation', angles: [0, 90, 0] },
+    ]);
+    expect(x).toBeCloseTo(1);
+    expect(y).toBeCloseTo(0);
+    expect(z).toBeCloseTo(0);
+  });
+
+  it('Rz(90°) does not affect +Z (Rz only rotates the XY plane)', () => {
+    const [x, y, z] = computeProbeDirection([
+      { object_type: 'Rotation', angles: [0, 0, 90] },
+    ]);
+    expect(x).toBeCloseTo(0);
+    expect(y).toBeCloseTo(0);
+    expect(z).toBeCloseTo(1);
+  });
+
+  it('Rz(-90°) does not affect +Z', () => {
+    const [x, y, z] = computeProbeDirection([
+      { object_type: 'Rotation', angles: [0, 0, -90] },
+    ]);
+    expect(x).toBeCloseTo(0);
+    expect(y).toBeCloseTo(0);
+    expect(z).toBeCloseTo(1);
+  });
+
+  it('result is a unit vector', () => {
+    const dir = computeProbeDirection([
+      { object_type: 'Rotation', angles: [30, 45, -20] },
+    ]);
+    const len = Math.sqrt(dir[0] ** 2 + dir[1] ** 2 + dir[2] ** 2);
+    expect(len).toBeCloseTo(1, 6);
+  });
+
+  it('applies multiple rotations in sequence (extrinsic)', () => {
+    // Rx(-90) makes +Z → +Y (dorsal), then Ry(90) rotates +Y unchanged → +Y
+    // because Ry only rotates the XZ plane.
+    const [x, y, z] = computeProbeDirection([
+      { object_type: 'Rotation', angles: [-90, 0, 0] }, // +Z → +Y
+      { object_type: 'Rotation', angles: [0, 90, 0] },  // Ry on (0,1,0): Y unaffected
+    ]);
+    expect(x).toBeCloseTo(0);
+    expect(y).toBeCloseTo(1);
+    expect(z).toBeCloseTo(0);
+  });
+
+  it('handles null transforms array gracefully', () => {
+    const [x, y, z] = computeProbeDirection(null);
+    expect(x).toBeCloseTo(0);
+    expect(y).toBeCloseTo(0);
+    expect(z).toBeCloseTo(1);
+  });
+
+  it('handles missing angles array gracefully', () => {
+    const [x, y, z] = computeProbeDirection([
+      { object_type: 'Rotation' }, // no angles property — defaults to [0,0,0]
+    ]);
+    expect(z).toBeCloseTo(1); // unchanged
+  });
+});

web/src/__tests__/ephys-view.test.js

@@ -0,0 +1,231 @@
+/**
+ * ephys-view.test.js — Unit tests for ephys-related pure helpers in details.js.
+ *
+ * Tests hasEphysAssemblies and buildEphysProbeCard, which are Node-safe (no DOM/Three.js).
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+
+// Mock Three.js and OBJLoader so the ephys-viz-3d import doesn't fail in Node
+vi.mock('three', () => ({ default: {} }));
+vi.mock('three/addons/loaders/OBJLoader.js', () => ({ OBJLoader: class {} }));
+
+// Mock brain-viz-3d exports needed by ephys-viz-3d
+vi.mock('../subject/brain-viz-3d.js', () => ({
+  STRUCTURE_COLORS: {},
+  TARGET_X: 0, TARGET_Y: -3.668, TARGET_Z: -1.2,
+  makeCCFMatrix: () => ({}),
+  cssHexToThree: (h) => parseInt(h.replace('#', ''), 16),
+  surfaceY: () => null,
+  loadBrainMesh: () => {},
+  createBrainViz3D: () => document.createElement('div'),
+}));
+
+// Mock brain-viz for ITEM_COLORS
+vi.mock('../subject/brain-viz.js', () => ({
+  ITEM_COLORS: ['#FF6B6B', '#4ECDC4', '#45B7D1'],
+  createBrainVizCanvas: () => ({ canvas: document.createElement('canvas') }),
+}));
+
+// Mock assets/view.js
+vi.mock('../assets/view.js', () => ({
+  buildQcLink: () => null,
+  buildMetadataLink: () => null,
+  buildCoLink: () => null,
+  buildS3ConsoleUrl: () => null,
+}));
+
+import { hasEphysAssemblies, buildEphysProbeCard } from '../subject/details.js';
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const EPHYS_CONFIG = {
+  object_type: 'Ephys assembly config',
+  device_name: 'Ephys Assembly 46121',
+  modules: [
+    { object_type: 'MIS module config', arc_angle: -10, module_angle: -15, angle_unit: 'degrees' },
+  ],
+  probes: [
+    {
+      device_name: '46121',
+      dye: 'DiD',
+      notes: 'Some notes here.',
+      primary_targeted_structure: { acronym: 'PAL', id: '803', name: 'Pallidum' },
+      other_targeted_structure: null,
+      coordinate_system: {
+        name: 'PROBE_RUFD',
+        origin: 'Tip',
+        axis_unit: 'micrometer',
+        axes: [
+          { direction: 'Left_to_right', name: 'X' },
+          { direction: 'Down_to_up', name: 'Y' },
+          { direction: 'Back_to_front', name: 'Z' },
+          { direction: 'Up_to_down', name: 'Depth' },
+        ],
+      },
+      transform: [
+        { object_type: 'Rotation', angles: [90, 0, -90], angles_unit: 'degrees' },
+        { object_type: 'Translation', translation: [3.96, -12.10, -4.04, 3.611] },
+      ],
+    },
+  ],
+};
+
+const ACQUISITION_WITH_EPHYS = {
+  data_streams: [
+    {
+      object_type: 'Data stream',
+      configurations: [EPHYS_CONFIG],
+    },
+  ],
+};
+
+const ACQUISITION_WITHOUT_EPHYS = {
+  data_streams: [
+    {
+      object_type: 'Data stream',
+      configurations: [
+        { object_type: 'Camera config', device_name: 'Camera 1' },
+      ],
+    },
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// hasEphysAssemblies
+// ---------------------------------------------------------------------------
+
+describe('hasEphysAssemblies', () => {
+  it('returns true when acquisition has at least one Ephys assembly config', () => {
+    expect(hasEphysAssemblies(ACQUISITION_WITH_EPHYS)).toBe(true);
+  });
+
+  it('returns false when no Ephys assembly config exists', () => {
+    expect(hasEphysAssemblies(ACQUISITION_WITHOUT_EPHYS)).toBe(false);
+  });
+
+  it('returns false for empty data_streams', () => {
+    expect(hasEphysAssemblies({ data_streams: [] })).toBe(false);
+  });
+
+  it('returns false for null input', () => {
+    expect(hasEphysAssemblies(null)).toBe(false);
+  });
+
+  it('returns false for undefined input', () => {
+    expect(hasEphysAssemblies(undefined)).toBe(false);
+  });
+
+  it('finds ephys config nested inside a stream with mixed configs', () => {
+    const mixed = {
+      data_streams: [
+        {
+          configurations: [
+            { object_type: 'Camera config' },
+            { object_type: 'Ephys assembly config', probes: [] },
+          ],
+        },
+      ],
+    };
+    expect(hasEphysAssemblies(mixed)).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildEphysProbeCard
+// ---------------------------------------------------------------------------
+
+describe('buildEphysProbeCard', () => {
+  const probe = {
+    name: '46121',
+    dye: 'DiD',
+    notes: 'Probe notes.',
+    ap: -4.04,
+    ml: 3.96,
+    depth: 3.611,
+    probeDir: [-0.258, 0.070, 0.964],
+    modules: [{ arc_angle: -10, module_angle: -15 }],
+    primaryStructure: { acronym: 'PAL', id: '803', name: 'Pallidum' },
+    otherStructures: [],
+    structureIds: ['803'],
+  };
+
+  it('renders the probe name in a heading', () => {
+    const html = buildEphysProbeCard(probe, 0);
+    expect(html).toContain('46121');
+  });
+
+  it('renders the primary targeted structure', () => {
+    const html = buildEphysProbeCard(probe, 0);
+    expect(html).toContain('Pallidum');
+    expect(html).toContain('PAL');
+  });
+
+  it('renders the dye', () => {
+    const html = buildEphysProbeCard(probe, 0);
+    expect(html).toContain('DiD');
+  });
+
+  it('renders module angles', () => {
+    const html = buildEphysProbeCard(probe, 0);
+    expect(html).toContain('arc -10');
+    expect(html).toContain('module -15');
+  });
+
+  it('renders position and depth', () => {
+    const html = buildEphysProbeCard(probe, 0);
+    expect(html).toContain('-4.04');
+    expect(html).toContain('3.96');
+    expect(html).toContain('3.61');
+  });
+
+  it('renders notes', () => {
+    const html = buildEphysProbeCard(probe, 0);
+    expect(html).toContain('Probe notes.');
+  });
+
+  it('does not render other targets section when otherStructures is empty', () => {
+    const html = buildEphysProbeCard(probe, 0);
+    expect(html).not.toContain('Other targets');
+  });
+
+  it('renders other targeted structures when present', () => {
+    const p2 = {
+      ...probe,
+      otherStructures: [{ acronym: 'MD', id: '362', name: 'Mediodorsal nucleus of thalamus' }],
+    };
+    const html = buildEphysProbeCard(p2, 0);
+    expect(html).toContain('Mediodorsal nucleus of thalamus');
+    expect(html).toContain('Other targets');
+  });
+
+  it('omits dye row when dye is null', () => {
+    const p2 = { ...probe, dye: null };
+    const html = buildEphysProbeCard(p2, 0);
+    expect(html).not.toContain('DiD');
+  });
+
+  it('omits notes row when notes is null', () => {
+    const p2 = { ...probe, notes: null };
+    const html = buildEphysProbeCard(p2, 1);
+    expect(html).not.toContain('Probe notes.');
+  });
+
+  it('handles probe with no modules gracefully', () => {
+    const p2 = { ...probe, modules: [] };
+    const html = buildEphysProbeCard(p2, 0);
+    expect(html).not.toContain('Module angles');
+  });
+
+  it('shows "Probe N:" prefix using 1-based index', () => {
+    const html = buildEphysProbeCard(probe, 0);
+    expect(html).toContain('Probe 1:');
+  });
+
+  it('index 2 shows "Probe 3:"', () => {
+    const html = buildEphysProbeCard(probe, 2);
+    expect(html).toContain('Probe 3:');
+  });
+});