feat(dicom): detect extension-less DICOM and open full series from one file

DICOM exports often have no extension (IM_0001) or a bare UID as the file
name, so they were not recognized and fell through to the mesh loader.
Detect DICOM by content (the Part 10 magic: a 128-byte preamble followed by
"DICM") instead of relying on the extension, and load a whole series from a
single clicked file.

- Add isDicomData() to @niivue/react and content-sniff payloads whose name
  matches no known format, routing matches through the DICOM loader.
- Handle multi-file input (uri: string[]) directly in loadVolume. An array
  URI previously threw before reaching the DICOM path, which also broke PWA
  folder drop. When dcm2niix returns more than one series, each opens on its
  own canvas.
- VS Code: expand a single opened DICOM file (by extension or content,
  including extension-less files opened via "NiiVue: Open") to every DICOM
  file in its folder so the full series loads together. Fix openDcmFolder,
  which sent a single URI string alongside the data array.

Tests: 17 new VS Code unit tests, isDicomData unit tests, and a PWA e2e
covering the multi-file array path through real dcm2niix.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: korbinian90

.changeset/detect-extensionless-dicom.md

@@ -0,0 +1,28 @@
+---
+'@niivue/react': minor
+'niivue': minor
+'@niivue/pwa': patch
+'@niivue/streamlit': patch
+'@niivue/jupyter': patch
+'@niivue/tauri': patch
+---
+
+Detect extension-less DICOM files and open a whole series from one click.
+
+DICOM exports often have no extension (IM_0001) or a bare UID as the file
+name (1.2.840.113619...). These are now detected by content (the DICOM
+Part 10 magic: a 128-byte preamble followed by "DICM") instead of relying
+on the extension, and a single clicked DICOM file loads its entire series.
+
+- New `isDicomData()` helper exported from `@niivue/react`.
+- `loadVolume` content-sniffs payloads whose name matches no known format
+  and routes matches through the DICOM loader. Multi-file input
+  (`uri: string[]`) is now handled directly; previously an array URI threw
+  before reaching the DICOM path, which also broke PWA folder drop.
+- When dcm2niix returns more than one series (a folder with multiple
+  acquisitions), each additional series opens on its own canvas.
+- The VS Code extension expands a single opened DICOM file (by extension or
+  by content, including extension-less files opened via "NiiVue: Open") to
+  every DICOM file in its folder, so the full series loads together. The
+  "Open DICOM Folder" path now sends a correct file array (it previously
+  passed a single URI string alongside the data array).

apps/pwa/tests/Dicom.spec.ts

@@ -46,6 +46,67 @@ test.describe('Loading DICOM images', () => {
     expect(bodyText).not.toContain('failed')
   })
 
+  test('loads an extension-less DICOM file via magic-byte detection', async ({ page }) => {
+    // Scanner exports often have no extension (IM_0001) or a bare UID as the
+    // name. The viewer must detect DICOM content from the "DICM" magic bytes
+    // and route the file through the DICOM loader.
+    await page.goto(BASE_URL)
+
+    const dicomPath = path.join(__dirname, '..', 'test', 'assets', 'enh.dcm')
+    const dicomBuffer = fs.readFileSync(dicomPath)
+
+    const message = {
+      type: 'addImage',
+      body: {
+        data: Array.from(new Uint8Array(dicomBuffer)),
+        uri: 'IM_0001',
+      },
+    }
+
+    await page.evaluate((m) => window.postMessage(m, '*'), message)
+    await waitForImageLoad(page)
+
+    const canvases = await page.$$('canvas')
+    expect(canvases.length).toBeGreaterThanOrEqual(1)
+
+    await page.waitForTimeout(2000)
+
+    const bodyText = await page.textContent('body')
+    expect(bodyText).not.toContain('error')
+    expect(bodyText).not.toContain('failed')
+  })
+
+  test('loads a DICOM series passed as an array of files', async ({ page }) => {
+    // Multi-file series arrive as `uri: string[]` + `data: ArrayBuffer[]`
+    // (VS Code series expansion, PWA folder drop). This path previously threw
+    // because loadVolume called string methods on the array uri. dcm2niix
+    // assembles the array into one volume per series.
+    await page.goto(BASE_URL)
+
+    const dicomPath = path.join(__dirname, '..', 'test', 'assets', 'enh.dcm')
+    const dicomBuffer = fs.readFileSync(dicomPath)
+
+    const message = {
+      type: 'addImage',
+      body: {
+        data: [Array.from(new Uint8Array(dicomBuffer))],
+        uri: ['enh.dcm'],
+      },
+    }
+
+    await page.evaluate((m) => window.postMessage(m, '*'), message)
+    await waitForImageLoad(page)
+
+    const canvases = await page.$$('canvas')
+    expect(canvases.length).toBeGreaterThanOrEqual(1)
+
+    await page.waitForTimeout(2000)
+
+    const bodyText = await page.textContent('body')
+    expect(bodyText).not.toContain('error')
+    expect(bodyText).not.toContain('failed')
+  })
+
   test('loads DICOM from URL', async ({ page }) => {
     await page.goto(BASE_URL)
 

apps/vscode/src/editorProvider.ts

@@ -87,13 +87,7 @@ export class NiiVueEditorProvider implements vscode.CustomReadonlyEditorProvider
         if (e.type === 'ready' && !isImageSent) {
           isImageSent = true
           this.postInitSettings(panel)
-
-          if (uri.path.toLowerCase().endsWith('.mhd')) {
-            await NiiVueEditorProvider.sendMhdMessage(uri, panel.webview)
-          } else {
-            const body = await NiiVueEditorProvider.uriToImageBody(uri, panel.webview)
-            panel.webview.postMessage({ type: 'addImage', body })
-          }
+          await NiiVueEditorProvider.sendInitialImage(uri, panel.webview)
         }
       })
     })
@@ -203,18 +197,30 @@ export class NiiVueEditorProvider implements vscode.CustomReadonlyEditorProvider
   }
 
   public static async openDcmFolder(folderUri: vscode.Uri, panel: vscode.WebviewPanel) {
+    const series = await NiiVueEditorProvider.collectDicomFolder(folderUri)
+    if (series.uris.length > 0) {
+      panel.webview.postMessage({
+        type: 'addImage',
+        body: { uri: series.uris, data: series.datas },
+      })
+      return
+    }
+    // Fallback: nothing sniffed as DICOM (e.g. files that lack the Part 10
+    // preamble). Send every file in the folder and let the loader decide.
     const files = await vscode.workspace.fs.readDirectory(folderUri)
-    const fileUris = files.map((file) => vscode.Uri.joinPath(folderUri, file[0]))
+    const fileUris = files
+      .filter(([, fileType]) => (fileType & vscode.FileType.File) !== 0)
+      .map(([name]) => vscode.Uri.joinPath(folderUri, name))
     const data = await Promise.all(
       fileUris.map((uri) =>
-        vscode.workspace.fs.readFile(uri).then((data) => NiiVueEditorProvider.toArrayBuffer(data)),
+        vscode.workspace.fs.readFile(uri).then((d) => NiiVueEditorProvider.toArrayBuffer(d)),
       ),
     )
     panel.webview.postMessage({
       type: 'addImage',
       body: {
-        data: data,
-        uri: fileUris[0].toString(),
+        data,
+        uri: fileUris.map((u) => u.toString()),
       },
     })
   }
@@ -244,21 +250,58 @@ export class NiiVueEditorProvider implements vscode.CustomReadonlyEditorProvider
     webviewPanel.webview.onDidReceiveMessage(async (message) => {
       if (message.type === 'ready') {
         NiiVueEditorProvider.postInitSettings(webviewPanel)
-
-        if (document.uri.path.toLowerCase().endsWith('.mhd')) {
-          // MHD files have detached raw data; resolve the paired .raw file.
-          await NiiVueEditorProvider.sendMhdMessage(document.uri, webviewPanel.webview)
-        } else {
-          const body = await NiiVueEditorProvider.uriToImageBody(
-            document.uri,
-            webviewPanel.webview,
-          )
-          webviewPanel.webview.postMessage({ type: 'addImage', body })
-        }
+        await NiiVueEditorProvider.sendInitialImage(document.uri, webviewPanel.webview)
       }
     })
   }
 
+  /**
+   * Extensions the webview can route on its own (mirrors the customEditors
+   * selector in package.json plus formats handled by dedicated code paths).
+   * Files matching none of these get content-sniffed for DICOM, since DICOM
+   * exports often have no extension or a bare UID as the file name.
+   */
+  private static readonly knownExtensions = [
+    '.dcm',
+    '.ima',
+    '.nii',
+    '.nii.gz',
+    '.mih',
+    '.mif',
+    '.mif.gz',
+    '.nhdr',
+    '.nrrd',
+    '.mhd',
+    '.mha',
+    '.mgh',
+    '.mgz',
+    '.v',
+    '.v16',
+    '.vmr',
+    '.mz3',
+    '.gii',
+    '.mnc',
+    '.mnc.gz',
+    '.npy',
+    '.npz',
+    '.raw',
+  ]
+
+  static hasKnownExtension(lowerCasePath: string): boolean {
+    return NiiVueEditorProvider.knownExtensions.some((ext) => lowerCasePath.endsWith(ext))
+  }
+
+  /** DICOM Part 10 magic: a 128-byte preamble followed by "DICM". */
+  static isDicomData(data: Uint8Array): boolean {
+    return (
+      data.byteLength >= 132 &&
+      data[128] === 0x44 && // D
+      data[129] === 0x49 && // I
+      data[130] === 0x43 && // C
+      data[131] === 0x4d // M
+    )
+  }
+
   /**
    * Build the message body for an `addImage`/overlay payload.  Prefers a
    * webview URI (so NiiVue can stream large volumes) but falls back to reading
@@ -267,6 +310,10 @@ export class NiiVueEditorProvider implements vscode.CustomReadonlyEditorProvider
    * `localResourceRoots`, or formats that NiiVue can only ingest as bytes
    * (`.dcm`, `.mnc`).
    *
+   * Files without a recognized extension are read and sniffed for the DICOM
+   * magic bytes; matches are shipped as binary so the webview routes them
+   * through the DICOM loader.
+   *
    * MHD files are handled separately by `sendMhdMessage` because they need
    * the paired `.raw` voxel file resolved alongside the header.
    */
@@ -286,9 +333,138 @@ export class NiiVueEditorProvider implements vscode.CustomReadonlyEditorProvider
         uri: uri.toString(),
       }
     }
+    if (!NiiVueEditorProvider.hasKnownExtension(lowerCasePath)) {
+      const data = await vscode.workspace.fs.readFile(uri)
+      if (NiiVueEditorProvider.isDicomData(data)) {
+        return {
+          data: NiiVueEditorProvider.toArrayBuffer(data),
+          uri: uri.toString(),
+        }
+      }
+    }
     return { uri: webview.asWebviewUri(uri).toString() }
   }
 
+  /**
+   * Send the initial image(s) for a freshly opened panel.
+   *
+   * - MHD resolves its detached `.raw` voxel file.
+   * - A DICOM file (recognized by extension or by sniffing the file's
+   *   content) expands to every DICOM file in the same folder, so a single
+   *   clicked slice loads its whole series. dcm2niix groups the slices and
+   *   splits a multi-series folder into one volume per series.
+   * - Everything else loads as a single image.
+   */
+  static async sendInitialImage(uri: vscode.Uri, webview: vscode.Webview): Promise<void> {
+    if (uri.path.toLowerCase().endsWith('.mhd')) {
+      await NiiVueEditorProvider.sendMhdMessage(uri, webview)
+      return
+    }
+    const name = uri.path.split('/').pop() ?? ''
+    if (NiiVueEditorProvider.isDicomCandidateName(name)) {
+      try {
+        const series = await NiiVueEditorProvider.collectDicomFolderImages(uri)
+        if (series) {
+          webview.postMessage({
+            type: 'addImage',
+            body: { uri: series.uris, data: series.datas },
+          })
+          return
+        }
+      } catch {
+        // Fall through to a single-file load if directory scanning fails.
+      }
+    }
+    const body = await NiiVueEditorProvider.uriToImageBody(uri, webview)
+    webview.postMessage({ type: 'addImage', body })
+  }
+
+  /**
+   * Cheap name-based pre-filter for DICOM files, used to avoid reading every
+   * sibling in a directory. Matches `.dcm`/`.ima`, extension-less names
+   * (`IM_0001`), and DICOM UID-style names (digits and dots). Actual content
+   * is still verified with `isDicomData` before a file is treated as DICOM.
+   */
+  static isDicomCandidateName(name: string): boolean {
+    const base = (name.split('/').pop() ?? name).toLowerCase()
+    if (base.endsWith('.dcm') || base.endsWith('.ima')) {
+      return true
+    }
+    return !base.includes('.') || /^[\d.]+$/.test(base)
+  }
+
+  /** The parent directory of a file URI. */
+  private static parentDir(uri: vscode.Uri): vscode.Uri {
+    const slashIndex = uri.path.lastIndexOf('/')
+    const parentPath = slashIndex >= 0 ? uri.path.substring(0, slashIndex) : ''
+    return uri.with({ path: parentPath || '/' })
+  }
+
+  /**
+   * Read every DICOM file in a directory (name pre-filtered, content
+   * verified) and return their URIs and bytes, sorted by URI for a stable
+   * slice order.
+   */
+  static async collectDicomFolder(
+    dirUri: vscode.Uri,
+  ): Promise<{ uris: string[]; datas: ArrayBuffer[] }> {
+    let entries: [string, vscode.FileType][]
+    try {
+      entries = await vscode.workspace.fs.readDirectory(dirUri)
+    } catch {
+      return { uris: [], datas: [] }
+    }
+    const collected: { uri: string; data: ArrayBuffer }[] = []
+    for (const [name, fileType] of entries) {
+      if ((fileType & vscode.FileType.File) === 0) {
+        continue
+      }
+      if (!NiiVueEditorProvider.isDicomCandidateName(name)) {
+        continue
+      }
+      const fileUri = vscode.Uri.joinPath(dirUri, name)
+      let bytes: Uint8Array
+      try {
+        bytes = await vscode.workspace.fs.readFile(fileUri)
+      } catch {
+        continue
+      }
+      if (!NiiVueEditorProvider.isDicomData(bytes)) {
+        continue
+      }
+      collected.push({ uri: fileUri.toString(), data: NiiVueEditorProvider.toArrayBuffer(bytes) })
+    }
+    collected.sort((a, b) => (a.uri < b.uri ? -1 : a.uri > b.uri ? 1 : 0))
+    return { uris: collected.map((c) => c.uri), datas: collected.map((c) => c.data) }
+  }
+
+  /**
+   * If `fileUri` is a DICOM file, return every DICOM file in its directory so
+   * the whole series loads together. Returns null when the file is not DICOM,
+   * so the caller falls back to a single-file load.
+   */
+  static async collectDicomFolderImages(
+    fileUri: vscode.Uri,
+  ): Promise<{ uris: string[]; datas: ArrayBuffer[] } | null> {
+    let clicked: Uint8Array
+    try {
+      clicked = await vscode.workspace.fs.readFile(fileUri)
+    } catch {
+      return null
+    }
+    if (!NiiVueEditorProvider.isDicomData(clicked)) {
+      return null
+    }
+    const series = await NiiVueEditorProvider.collectDicomFolder(
+      NiiVueEditorProvider.parentDir(fileUri),
+    )
+    if (series.uris.length === 0) {
+      // Directory listing failed; load just the clicked file.
+      return { uris: [fileUri.toString()], datas: [NiiVueEditorProvider.toArrayBuffer(clicked)] }
+    }
+    return series
+  }
+
   /**
    * Whether `uri` can be served through the webview resource proxy.  Requires
    * the same scheme *and* authority as one of the workspace folders so that a