# CBCTScope

**A complete, local-first CBCT and 2D radiograph viewer, built by a
board-certified oral and maxillofacial radiologist. The first with native
AI-agent control.**

[![DOI: 10.5281/zenodo.21431452](docs/media/doi-badge.svg)](https://doi.org/10.5281/zenodo.21431452)

**[Run it](#run-it)** (three steps) · **[Open your own scan](#opening-your-own-scan)** ·
**[Reading guides](docs/reading-modes/)** · **[User manual](docs/manual/)** ·
**[For AI agents](#ai-agent-control-mcp)** · **[Cite it](#author)**

- **Clinicians and students:** read the CBCT exports already on your computer
  in eight purpose-built modes, free, with no account, no upload, and nothing
  leaving the machine. It starts on a built-in phantom, so the whole viewer can
  be learned with zero patient data.
- **Researchers:** one instrument that reads CBCT volumes and 2D radiographs
  under identical display settings, for multi-reader studies, with NIfTI, STL,
  and PNG slice-stack export and a citable DOI for every release.
- **Agent builders:** a built-in MCP server with fifteen navigation-only verbs,
  a one-click Claude Desktop bundle, and an Agent Skill. The agent moves the
  camera; the human reads.

![An AI agent driving CBCTScope over MCP on a real CBCT: slice navigation down to the dentition, window presets, a bone 3D render, then the multi-slice grid, curved panoramic with cross-sections, TMJ, reslice and virtual cephalogram](docs/media/cbctscope-demo.gif)

*Above: an agent driving the viewer. Slice navigation, the window presets,
every mode switch, and the closing view reset are MCP verbs sent by the agent;
the 3D orbit, the arch, the focal trough and the cephalogram contrast are the
viewer's own one-click tools. The volume is the same real CBCT as the stills
below: shown with written patient consent, de-identified before it was ever
opened, and rendered in bone only, never as a soft-tissue surface.*

CBCTScope opens the CBCT exports already on your computer and reads them in
eight purpose-built modes: MPR with 3D rendering, multi-slice grid, curved
panoramic with nerve tracing, TMJ, freehand reslice, virtual cephalogram,
region growing with airway analysis, and two-volume stitching. It reads 2D
radiographs (panoramic, intraoral, CR and DX) in the same instrument, under
the same display settings. It is free, open source, and local-first: no
account, no cloud, no upload, ever. No agent is required; CBCTScope is a
complete standalone viewer.

It is also, to our knowledge, the first CBCT viewer an AI agent can drive
natively: through a built-in [MCP](https://modelcontextprotocol.io) server, an
agent opens scans, switches reading modes, sets the window, moves through
slices, and takes snapshots. The agent moves the camera. The human reads.

> **Research use only. Not a medical device.** CBCTScope visualizes and
> navigates volumes. It never produces findings, measurements-as-conclusions,
> or diagnoses, in the UI or over MCP. Do not use it for clinical
> decision-making.

## The interface at a glance

| MPR + 3D | Multi-slice grid | Curved panoramic | TMJ condyles |
|---|---|---|---|
| [![MPR: axial, sagittal, coronal and a bone 3D render, crosshairs on a molar, HU windowing, slab and MIP controls](docs/media/thumb-mpr.png)](docs/media/thumb-mpr.png) | [![Grid: nine parallel axial slices through the dentition with a sagittal scout, spacing and thickness controls](docs/media/thumb-grid.png)](docs/media/thumb-grid.png) | [![Pano: arch spline on the axial, curved panoramic of the arch, perpendicular cross-sections](docs/media/thumb-pano.png)](docs/media/thumb-pano.png) | [![TMJ: both condyles in axis-corrected sagittal sections, five per side, with the axis line drawn per condyle on the axial scout](docs/media/thumb-tmj.png)](docs/media/thumb-tmj.png) |

*The four stills above are a real CBCT: a 16×16cm, 200 µm Planmeca ProMax
volume, shown with the written consent of the patient and de-identified before
it was ever opened.*

Click any thumbnail for full resolution. Each reading mode has its own guide,
written the way a reader actually moves through a volume:
[docs/reading-modes](docs/reading-modes/). The full user manual, from
installation to the keyboard reference, lives in [docs/manual](docs/manual/).

## Run it

Three steps, no technical background needed. CBCTScope is not an
installed app with an icon: it is a small local program you start once per
reading session, and your browser is the screen. Everything is undone by
deleting the folder.

**System requirements**

- **Node.js 22 or later**: the free runtime that runs the viewer, the way a
  browser runs a web page.
- **A current desktop browser** with WebGL2 (Chrome, Edge, Firefox, or
  Safari). The 3D render and all reformats are computed on this machine, so a
  recent computer with a working graphics driver is assumed; large volumes
  read more comfortably with more memory.
- **macOS, Windows, or Linux.**

1. **Install Node.js 22 or later** from [nodejs.org](https://nodejs.org):
   download the LTS installer, run it, accept the defaults.
2. **Get CBCTScope.** Click the green **Code** button at the top of this page,
   choose **Download ZIP**, and unzip it somewhere you can find again (Desktop
   is fine). If you use git, `git clone` works as usual.
3. **Start it.** In the unzipped folder, double-click **Start
   CBCTScope.command** on macOS or **Start CBCTScope.bat** on Windows. If the
   system shows a security prompt on this first open, the one-time answer for
   each system is under "If something goes wrong" below. The first start
   downloads the viewer's components once (about 130 MB downloaded, 600 MB on
   disk: ten to fifteen seconds on the author's Mac and connection, longer on
   a slow one); then your browser opens the viewer by itself. A built-in
   **synthetic phantom** loads immediately: jaws, dental arches, teeth with
   enamel and pulp, a metal crown, airway, sinuses, and TMJ condyles, all
   procedurally generated. The full viewer works with zero patient data, and
   the header says so until you open a scan of your own. **help** in the
   header opens the reading guide for the mode you are in.

To stop the viewer, close the starter's window or press Ctrl-C in it. Next
session, double-click again: startup is quick once installed.

**Prefer a terminal, or on Linux?** Open a terminal in the unzipped folder,
run `npm install` once, then `npm run dev`, and open http://localhost:3810.
The manual's [installation chapter](docs/manual/02-installation.md) spells
this path out step by step.

**Demo mode vs. normal mode.** `npm run demo` (any OS) starts the same viewer
but never remembers a previously opened scan, so a recording or screenshot
session can never accidentally surface a real case: it is a privacy
guarantee, not a reduced feature set. The double-click starters and
`npm run dev` start normal mode, which restores your last opened scan. On
first launch both modes show the phantom.

### If something goes wrong

- **macOS refuses to open Start CBCTScope.command** ("Apple could not
  verify" or "unidentified developer"): open **System Settings**, click
  **Privacy & Security**, scroll down, click **Open Anyway**, and confirm
  **Open** in the prompt that reappears. macOS asks once; afterwards a plain
  double-click works. On older macOS versions the same override is a
  right-click on the file and **Open**.
- **Windows shows a security warning for Start CBCTScope.bat** ("the
  publisher could not be verified", or a SmartScreen notice): choose **Run**
  (under SmartScreen, **More info**, then **Run anyway**). Windows asks this
  for files downloaded from the internet; the starter only installs and
  starts the viewer inside its own folder.
- **You cannot install Node.js on this computer** (no administrator rights, a
  managed clinic PC): nodejs.org also offers a standalone binary that needs no
  installer, and CBCTScope itself writes nothing outside its own folder and
  `~/.cbctscope`. Whether either may run on a managed computer is your IT
  department's call; ask them rather than working around a policy.
- **`npm: command not found`** (or `'npm' is not recognized`): Node.js is not
  installed yet, or the terminal was opened before the install finished.
  Install it, then open a new terminal window and retry.
- **The start command warns that port 3810 is in use**: the viewer is already
  running in another window. One is enough: just open http://localhost:3810,
  or stop the older one first.
- **"found N compressed DICOM file(s)"** when opening a scan: the viewer reads
  uncompressed DICOM only. Re-export from your scanner software with
  compression off.

## Opening your own scan

Click **open** in the viewer header and pick a CBCT export: a folder of DICOM
slices, a DICOMDIR tree, a single multiframe DICOM file, or one slice of a
series (the whole series opens). Any export your scanner software produces as
**uncompressed DICOM** works.

The scan is read **in place** from the folder you picked. Nothing is copied,
converted, or uploaded, and the full folder path never reaches the browser:
the header shows a short label built from the folder and file names, so name
your export folders the way you want to see them.

The file dialog is native on macOS and Windows out of the box. On Linux it
uses the desktop's standard dialog helper (zenity or kdialog; most
distributions ship one). If neither is installed, point the running viewer at
an export folder with one command in a second terminal (forward slashes work
in Windows paths):

```sh
curl -X POST http://localhost:3810/api/cbct/source -H "Content-Type: application/json" -d "{\"path\":\"C:/scans/patient-export\"}"
```

## Reading modes

| Mode | What it does |
|---|---|
| MPR | Orthogonal slices with crosshairs, oblique rotation, slab/MIP, measurements, 3D render with adjustable styles, clipping, and a render eraser |
| Grid | Many parallel slices of a rotatable stack on one screen |
| Pano | Draw the dental arch once, get a curved panoramic plus cross-sections, nerve tracing, and focal-trough control |
| TMJ | Both condyles side by side in axis-corrected sections |
| Reslice | A fresh slice stack along any drawn line or curve |
| Ceph | A virtual cephalogram, the volume projected flat like a film |
| Region | Region growing with HU presets, volume and density stats, airway analysis |
| Stitch | Rigid registration and fusion of two volumes of the same subject |

Per-mode reading guides live in [docs/reading-modes/](docs/reading-modes/).

### 2D radiographs

The viewer also opens single 2D radiographs (DICOM modality PX, DX, CR, or IO:
panoramic, digital and computed radiography, intraoral), uncompressed 16-bit files, the
same constraint as volumes. A radiograph gets a dedicated single-image view: window,
gamma, invert, cursor-centered zoom, pan, fit. Gray values are display-normalized to a
12-bit scale at load (radiographs carry no HU calibration), and MONOCHROME1 files are
flipped so bright is always radiopaque. The volumetric reading modes apply to volumes
only. This exists so multi-reader studies can read both image classes in one instrument
under identical display settings.

### Exporting

The volume header has an **export** menu with three client-side formats: a PNG slice
stack (a zip of one PNG per slice at the displayed window, plus a geometry `meta.json`),
a NIfTI volume (`.nii.gz`, HU values, for Slicer, ITK-SNAP, nibabel, MONAI), and an STL
surface mesh (marching cubes at a chosen HU threshold, honoring the 3D crop box, for
printing or CAD). Everything is computed in the browser and saved to this machine's
Downloads: nothing is uploaded, the same local-first constraint as reading.

## Privacy

The safe behavior is the only behavior the software has:

- Scans are read **in place** from the folder you pick. Nothing is copied or
  uploaded anywhere; there is no account, no telemetry, no hosted instance,
  and there never will be one.
- Everything, including the AI-agent connection, stays on this machine. In
  technical terms: the server binds to 127.0.0.1 and rejects any request whose
  Host or Origin is not loopback, so neither another device on your network
  nor a hostile web page in another tab (DNS rebinding, cross-site POSTs) can
  reach it.
- No absolute file paths reach the browser or the agent transcript. The UI
  shows a display label derived from the last folder and file names of what
  you opened, plus technical geometry only.
- The only writes are an app-data folder (`~/.cbctscope`) holding your
  annotation sidecars (labels, world-mm coordinates, HU statistics) and a
  pointer to the last source you opened, so the viewer can restore it. Never
  pixels. Demo mode writes neither.

## AI-agent control (MCP)

If you use an AI assistant that speaks MCP (Claude Code, Claude Desktop, and
others), it can drive the viewer for you: open a scan (or let you pick one in
the native dialog, so it never sees the path), switch reading modes, set the
window, step through slices, walk the panoramic arch, bookmark and restore
saved views, take snapshots to look at. It cannot do more than that, by
design: no tool returns a finding or an interpretation, and no tool executes
code, so the agent can never become the reader. A view the agent saves is
badged **agent** in the viewer, so a bookmark is never mistaken for yours.

Every verb declares what it does (read-only or not, never destructive), returns
structured state, and comes with read-only resources and four ready-made
reading choreographies as prompts; `docs/mcp.md` has the full contract. For
Claude Desktop, each release also carries a one-click `cbctscope-<version>.mcpb`
bundle of the server, and the repository ships an Agent Skill in
`skills/cbctscope-reading/`.

Start the viewer, open it in a browser, then register the MCP server with your agent host:

```json
{
  "mcpServers": {
    "cbctscope": {
      "command": "node",
      "args": ["/absolute/path/to/cbctscope/mcp/server.mjs"]
    }
  }
}
```

The agent gets fifteen verbs, all navigation or visualization: `open_scan`, `pick_scan`, `list_volumes`, `select_volume`, `viewer_state`, `set_view_mode`, `set_window_level`, `set_3d_style`, `navigate_slice`, `navigate_arch`, `list_views`, `goto_view`, `save_view`, `snapshot`, `reset_view`. Details and the full contract: [docs/mcp.md](docs/mcp.md).

CBCTScope is one of a pair of agent-native instruments built on the same principle (bounded verbs for the agent, commit rights for the human); the other is [Quoin](https://github.com/rezamotaghi/quoin), a text editor for macOS where any agent may edit the buffer and only the human holds the save button. Both at [rezamotaghi.com](https://rezamotaghi.com).

## Why this exists

To our knowledge, CBCTScope is the first CBCT viewer with native AI-agent control. Neighboring projects exist and deserve credit: [dicom-mcp](https://github.com/ChristianHinge/dicom-mcp) and the [Flux Inc. DICOM MCP server](https://github.com/fluxinc/dicom-mcp-server) query PACS metadata over MCP, [dicom-viewer-mcp-app](https://github.com/ThalesMMS/dicom-viewer-mcp-app) prototypes MCP-driven DICOM slice rendering, and [mcp-slicer](https://github.com/zhaoyouj/mcp-slicer) drives 3D Slicer through raw Python execution. None of them is a purpose-built CBCT reading environment, and none constrains the agent to a small set of clinical navigation verbs. CBCTScope does both: a dental and maxillofacial reading workflow, plus an agent surface that is deliberately navigation-only.

## Development

```sh
npm run dev          # dev server on :3810
npm run typecheck    # tsc
npm run lint         # eslint
npm test             # vitest: geometry, reformats, registration, region growing, HU windowing, phantom, manual + citation drift
npm run build        # production build
```

Built on [Cornerstone3D](https://www.cornerstonejs.org/) and Next.js. All rendering styles, reading workflows, and reconstruction math are original, from-scratch implementations informed by clinical reading practice; the project contains no vendor code, assets, or documentation.

## Author

Built by [Dr. Reza Motaghi](https://rezamotaghi.com/research), board-certified
oral and maxillofacial radiologist, 100,000+ studies reported, who trains
imaging models on his own reads and tests them on cases they have never seen.
CBCTScope is the viewer I read CBCT with. If you use it in research, please
cite it (see
[CITATION.cff](CITATION.cff)).

## License

[AGPL-3.0-or-later](LICENSE). Free to use, study, and modify. If you build a product or
service on this code, its source must be open under the same terms.

For uses the AGPL does not fit (closed-source products, commercial integration), a
separate commercial license is available: reach me through the contact page at
[rezamotaghi.com/contact](https://rezamotaghi.com/contact).