feat(mri-scanner): add the MRI scanner explainer

explainers/mri-scanner/explainer.json

@@ -0,0 +1,12 @@
+{
+  "slug": "mri-scanner",
+  "tags": ["physics", "biology"],
+  "cover": "cover.webp",
+  "entry": "src/index.ts",
+  "chapters": "chapters.html",
+  "locales": ["en", "zh", "es", "uk", "pt", "fr", "de", "ja"],
+  "social": {
+    "image": "social/og-image.png",
+    "alt": "A cutaway MRI scanner with its nested magnet layers around the tunnel, beside a slice picture of a head and the title How an MRI scanner works"
+  }
+}

explainers/mri-scanner/src/ids.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import {
+  AXIS_CHOICE_IDS,
+  FOLLOW_SEQUENCE,
+  GRADIENT_AXIS_IDS,
+  MOMENT_IDS,
+  PART_IDS,
+  PHASE_IDS,
+  PRESET_IDS,
+} from './ids';
+
+describe('ids', () => {
+  it('names every part once', () => {
+    expect(PART_IDS).toHaveLength(27);
+    expect(new Set(PART_IDS).size).toBe(PART_IDS.length);
+  });
+
+  it('orders the steps of one repetition and the chapters', () => {
+    expect(PHASE_IDS).toEqual(['excite', 'encode', 'refocus', 'echo', 'recover']);
+    expect(MOMENT_IDS).toEqual(['pulse90', 'pulse180', 'echoPeak', 'repetitionEnd']);
+    expect(PRESET_IDS).toEqual([
+      'overview',
+      'magnet',
+      'spins',
+      'resonance',
+      'gradients',
+      'picture',
+    ]);
+  });
+
+  it('offers the three axes plus following the sequence', () => {
+    expect(AXIS_CHOICE_IDS).toEqual([...GRADIENT_AXIS_IDS, FOLLOW_SEQUENCE]);
+  });
+});

explainers/mri-scanner/src/ids.ts

@@ -0,0 +1,143 @@
+export const PART_IDS = [
+  'room',
+  'cover',
+  'vacuumVessel',
+  'radiationShield',
+  'heliumVessel',
+  'mainCoils',
+  'shieldCoils',
+  'shims',
+  'coldHead',
+  'quenchPipe',
+  'gradientX',
+  'gradientY',
+  'gradientZ',
+  'bodyCoil',
+  'bore',
+  'table',
+  'patient',
+  'headCoil',
+  'sliceSlab',
+  'spinArrows',
+  'netMagnet',
+  'mainField',
+  'rfWave',
+  'echoWave',
+  'fieldLinesGroup',
+  'fringeLine',
+  'screen',
+] as const;
+
+export type PartId = (typeof PART_IDS)[number];
+
+export const PHASE_IDS = ['excite', 'encode', 'refocus', 'echo', 'recover'] as const;
+
+export type PhaseId = (typeof PHASE_IDS)[number];
+
+export const MOMENT_IDS = ['pulse90', 'pulse180', 'echoPeak', 'repetitionEnd'] as const;
+
+export type MomentId = (typeof MOMENT_IDS)[number];
+
+export const PRESET_IDS = [
+  'overview',
+  'magnet',
+  'spins',
+  'resonance',
+  'gradients',
+  'picture',
+] as const;
+
+export type PresetId = (typeof PRESET_IDS)[number];
+
+export const FIELD_IDS = ['field15', 'field30'] as const;
+
+export type FieldId = (typeof FIELD_IDS)[number];
+
+export const WEIGHTING_IDS = ['t1', 't2'] as const;
+
+export type WeightingId = (typeof WEIGHTING_IDS)[number];
+
+export const TISSUE_IDS = ['fat', 'whiteMatter', 'greyMatter', 'fluid'] as const;
+
+export type TissueId = (typeof TISSUE_IDS)[number];
+
+export const GRADIENT_AXIS_IDS = ['x', 'y', 'z'] as const;
+
+export type GradientAxisId = (typeof GRADIENT_AXIS_IDS)[number];
+
+export const CHOICE_IDS = ['field', 'weighting'] as const;
+
+export type ChoiceId = (typeof CHOICE_IDS)[number];
+
+export const FOLLOW_SEQUENCE = 'sequence';
+
+export const AXIS_CHOICE_IDS = [...GRADIENT_AXIS_IDS, FOLLOW_SEQUENCE] as const;
+
+export type AxisChoiceId = (typeof AXIS_CHOICE_IDS)[number];
+
+export const LINE_CHOICE_IDS = ['8', '16', '32', '64'] as const;
+
+export type LineChoiceId = (typeof LINE_CHOICE_IDS)[number];
+
+export const CHAPTER_ACTION_IDS = [
+  'field',
+  'weighting',
+  'tissue',
+  'gradientAxis',
+  'moment',
+  'lines',
+] as const;
+
+export type ChapterActionId = (typeof CHAPTER_ACTION_IDS)[number];
+
+export type CameraView = 'room' | 'cryostat' | 'voxel' | 'coil' | 'gradient' | 'console';
+
+export type RegionId = 'room' | 'scanner' | 'layers' | 'voxel' | 'bore' | 'console';
+
+export type AnchorId = 'isocentre' | 'voxel' | 'headCoil' | 'screen' | 'coldHead';
+
+export type Point = readonly [x: number, y: number, z: number];
+
+export type RfPulse = 0 | 90 | 180;
+
+export interface Fringe {
+  along: number;
+  side: number;
+}
+
+export interface SequenceReading {
+  phase: number;
+  step: PhaseId;
+  rf: RfPulse | null;
+  gradient: GradientAxisId | null;
+  gradientLevel: number;
+  echo: number;
+}
+
+export interface SpinReading {
+  net: Point;
+  arrows: readonly Point[];
+  precession: number;
+}
+
+export interface ViewOptions {
+  cutaway: boolean;
+  fieldLines: boolean;
+  voxel: boolean;
+  labels: boolean;
+}
+
+export interface AssemblyState {
+  phase: number;
+  playing: boolean;
+  field: FieldId;
+  weighting: WeightingId;
+  sequence: SequenceReading;
+  spins: SpinReading;
+  tissue: TissueId;
+  gradientAxis: GradientAxisId | null;
+  picture: Float32Array;
+  pictureVersion: number;
+  fringe: Fringe;
+  view: ViewOptions;
+}

explainers/mri-scanner/src/index.ts

@@ -0,0 +1,28 @@
+import './style.css';
+import { defineExplainer } from '@core/explainer';
+import { SCENE_OPTIONS, mountMriScannerScene } from './scene';
+import { PART_INFO } from './scene/partInfo';
+import { PRESETS, createMriScannerStore } from './state';
+import type { MriScannerStoreState } from './state';
+import { MRI_SCANNER_TIMELINE } from './timeline';
+import {
+  CHAPTER_ACTIONS,
+  MRI_SCANNER_CHOICES,
+  MRI_SCANNER_READOUTS,
+  VIEW_TOGGLES,
+  mountMriScannerUi,
+} from './ui';
+
+export default defineExplainer<MriScannerStoreState>({
+  id: 'mri-scanner',
+  timeline: MRI_SCANNER_TIMELINE,
+  presets: PRESETS,
+  parts: PART_INFO,
+  createStore: () => createMriScannerStore(),
+  dock: { choices: MRI_SCANNER_CHOICES, toggles: VIEW_TOGGLES },
+  readouts: MRI_SCANNER_READOUTS,
+  actions: CHAPTER_ACTIONS,
+  scene: SCENE_OPTIONS,
+  mountScene: mountMriScannerScene,
+  mountUi: mountMriScannerUi,
+});

explainers/mri-scanner/src/model/constants.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import {
+  BODY_K,
+  EARTH_UT,
+  GAMMA_MHZ_PER_T,
+  HELIUM_K,
+  KELVIN_AT_ZERO_CELSIUS,
+  MODEL_SIZE,
+  REAL_LINES,
+} from './constants';
+
+describe('constants', () => {
+  it('takes the gyromagnetic ratio of hydrogen from the facts sheet', () => {
+    expect(GAMMA_MHZ_PER_T).toBeCloseTo(42.58, 2);
+  });
+
+  it('puts the body at 37 °C and liquid helium at about −269 °C', () => {
+    expect(BODY_K - KELVIN_AT_ZERO_CELSIUS).toBeCloseTo(37, 9);
+    expect(HELIUM_K - KELVIN_AT_ZERO_CELSIUS).toBeCloseTo(-268.95, 2);
+  });
+
+  it('keeps the Earth field band and the picture sizes', () => {
+    expect(EARTH_UT).toEqual({ min: 25, typical: 50, max: 65 });
+    expect(REAL_LINES).toBe(256);
+    expect(MODEL_SIZE).toBe(64);
+  });
+});

explainers/mri-scanner/src/model/constants.ts

@@ -0,0 +1,19 @@
+export const GAMMA_MHZ_PER_T = 42.577478;
+export const PLANCK = 6.62607015e-34;
+export const BOLTZMANN = 1.380649e-23;
+export const BODY_K = 310.15;
+export const EARTH_UT = { min: 25, typical: 50, max: 65 } as const;
+export const HELIUM_K = 4.2;
+export const HYDROGEN_PER_MM3 = 6.7e19;
+export const GRADIENT_MT_PER_M = 45;
+export const SLEW_T_PER_M_S = 200;
+export const HEAD_HALF_FOV_M = 0.12;
+export const REAL_LINES = 256;
+export const MODEL_SIZE = 64;
+export const DISPLAY_TURNS_PER_S = 0.5;
+
+export const HZ_PER_MHZ = 1e6;
+export const TESLA_PER_UT = 1e-6;
+export const MS_PER_S = 1000;
+export const SECONDS_PER_MINUTE = 60;
+export const KELVIN_AT_ZERO_CELSIUS = 273.15;

explainers/mri-scanner/src/model/field.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { FIELDS, earthMultiple, larmorMHz, slowdown, spinSurplus, surplusPerMm3 } from './field';
+
+describe('main field', () => {
+  it('compares a 1.5 T and a 3 T magnet with their 0.5 mT lines', () => {
+    expect(FIELDS.field15).toEqual({ tesla: 1.5, fringe: { along: 4.0, side: 2.5 } });
+    expect(FIELDS.field30).toEqual({ tesla: 3, fringe: { along: 5.2, side: 2.8 } });
+  });
+
+  it('makes hydrogen precess at 63.87 MHz and 127.73 MHz', () => {
+    expect(larmorMHz('field15')).toBeCloseTo(63.87, 2);
+    expect(larmorMHz('field30')).toBeCloseTo(127.73, 2);
+  });
+
+  it('leans about 4.9 and 9.9 spins in a million the field way', () => {
+    expect(spinSurplus('field15') * 1e6).toBeCloseTo(4.9, 1);
+    expect(spinSurplus('field30') * 1e6).toBeCloseTo(9.9, 1);
+  });
+
+  it('still adds to about 3 × 10¹⁴ spare spins per cubic millimetre at 1.5 T', () => {
+    expect(surplusPerMm3('field15')).toBeGreaterThan(3e14);
+    expect(surplusPerMm3('field15')).toBeLessThan(3.5e14);
+    expect(surplusPerMm3('field30')).toBeCloseTo(2 * surplusPerMm3('field15'), -10);
+  });
+
+  it('is tens of thousands of times the Earth field', () => {
+    const times = earthMultiple('field15');
+    expect(times.min).toBeCloseTo(23077, 0);
+    expect(times.typical).toBeCloseTo(30000, 6);
+    expect(times.max).toBeCloseTo(60000, 6);
+    expect(earthMultiple('field30').typical).toBeCloseTo(60000, 6);
+  });
+
+  it('draws the precession about 128 million times slower than real at 1.5 T', () => {
+    expect(slowdown('field15') / 1e6).toBeCloseTo(127.7, 1);
+    expect(slowdown('field30') / 1e6).toBeCloseTo(255.5, 1);
+  });
+});

explainers/mri-scanner/src/model/field.ts

@@ -0,0 +1,53 @@
+import type { FieldId, Fringe } from '../ids';
+import {
+  BODY_K,
+  BOLTZMANN,
+  DISPLAY_TURNS_PER_S,
+  EARTH_UT,
+  GAMMA_MHZ_PER_T,
+  HYDROGEN_PER_MM3,
+  HZ_PER_MHZ,
+  PLANCK,
+  TESLA_PER_UT,
+} from './constants';
+
+export interface FieldSpec {
+  tesla: number;
+  fringe: Fringe;
+}
+
+export interface EarthMultiple {
+  min: number;
+  typical: number;
+  max: number;
+}
+
+export const FIELDS: Readonly<Record<FieldId, FieldSpec>> = {
+  field15: { tesla: 1.5, fringe: { along: 4.0, side: 2.5 } },
+  field30: { tesla: 3, fringe: { along: 5.2, side: 2.8 } },
+};
+
+export function larmorMHz(field: FieldId): number {
+  return GAMMA_MHZ_PER_T * FIELDS[field].tesla;
+}
+
+export function larmorHz(field: FieldId): number {
+  return larmorMHz(field) * HZ_PER_MHZ;
+}
+
+export function spinSurplus(field: FieldId): number {
+  return (PLANCK * larmorHz(field)) / (2 * BOLTZMANN * BODY_K);
+}
+
+export function surplusPerMm3(field: FieldId): number {
+  return HYDROGEN_PER_MM3 * spinSurplus(field);
+}
+
+export function earthMultiple(field: FieldId): EarthMultiple {
+  const times = (microtesla: number): number => FIELDS[field].tesla / (microtesla * TESLA_PER_UT);
+  return { min: times(EARTH_UT.max), typical: times(EARTH_UT.typical), max: times(EARTH_UT.min) };
+}
+
+export function slowdown(field: FieldId): number {
+  return larmorHz(field) / DISPLAY_TURNS_PER_S;
+}