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.

Run it (three steps) · Open your own scan · Reading guides · User manual · For AI agents · Cite it

• 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.

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 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

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. The full user manual, from installation to the keyboard reference, lives in docs/manual.

Related MCP server: MedVision MCP

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: 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 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):

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

Reading modes

Per-mode reading guides live in 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:

{
  "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.

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, a text editor for macOS where any agent may edit the buffer and only the human holds the save button. Both at 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 and the Flux Inc. DICOM MCP server query PACS metadata over MCP, dicom-viewer-mcp-app prototypes MCP-driven DICOM slice rendering, and 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

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 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, 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).

License

AGPL-3.0-or-later. 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.