Internal HTTP API
The embedded browser uses a local HTTP API. It is intended for dcmview debugging, smoke tests, and local automation—not as a stable third-party integration contract.
Endpoint registry
Section titled “Endpoint registry”All paths below are under /api.
| Method | Path | Success type | Purpose |
|---|---|---|---|
| GET | /health |
JSON | Ready state, viewer build identity, current file count, and start time. |
| GET | /files |
JSON | Progressive file registry, discovery ledger and counters, and tunnel state. |
| GET | /series |
JSON | Study/Series-owned logical stacks and source-frame mappings. |
| GET | /file/:index/info |
JSON | One file’s frame, geometry, syntax, object kind, support, and default window data. |
| GET | /file/:index/references |
JSON | Typed declared relationships and resolved local file/frame targets. |
| GET | /file/:index/semantic-context |
JSON | SEG, Parametric Map, or RT Dose declared context; otherwise not-applicable context. |
| GET | /file/:index/frame/:frame/wsi-context |
JSON | Selected WSI tile positioning, optical/focal context, companions, and warnings. |
| GET | /file/:index/frame/:frame/segmentation-overlay |
image/png |
Transparent, source-sized SEG mask after validated source and geometry mapping. |
| GET | /file/:index/frame/:frame |
image/png |
Server-rendered display frame. |
| GET | /file/:index/frame/:frame/raw |
application/octet-stream |
Decoded sample bytes and rendering headers. |
| GET | /file/:index/tags |
JSON | Lazy preview tag tree. |
| GET | /file/:index/tags/select |
JSON | Direct tag-path retrieval and sequence pagination. |
| GET | /file/:index/annotations |
JSON | Current in-memory ROI payload. |
| PUT | /file/:index/annotations |
JSON | Replace one file’s complete ROI payload. |
| GET | /annotations/export.csv |
CSV | Export every current annotation row. |
Static frontend assets are served outside /api at / and /assets/*.
Progressive registry
Section titled “Progressive registry”GET /api/files returns files, discovery, tunnelled, tunnel_host, server_start_ms, scan_complete, scanned, skipped, and filtered.
The files array can grow while scan_complete is false. Automation that needs a complete result should poll until completion. The memory-only discovery ledger contains at most the 256 most recent normalized-path entries; exact aggregate totals remain in the counters.
Each file reports its stable index, path and label, patient/study/series/instance identifiers, SOP Class and object kind, support state/reason, pixel and frame geometry, effective pixel aspect ratio, transfer syntax, and optional default window.
Logical series and references
Section titled “Logical series and references”GET /api/series groups only objects with both Study and Series Instance UIDs. Each logical stack includes ordered FrameRef records that map a virtual index to the source file index and source frame.
Geometry ordering can report warning codes including missing_positions, duplicate_positions, nonuniform_spacing, inconsistent_orientation, and gantry_tilt. Enhanced concatenations and WSI pyramid levels keep their own typed stack identity.
Reference targets retain declared one-based frame numbers. Resolved matches contain validated zero-based frame_indices suitable for viewer navigation. Empty matches mean a declaration was understood but no target was found in the current registry snapshot.
Segmentation overlays
Section titled “Segmentation overlays”GET /api/file/:index/frame/:frame/segmentation-overlay accepts a zero-based SEG frame. It uses the mapping evidence from semantic context: explicit derivation sources take precedence, followed by declared-source patient-geometry resolution.
After one compatible local source frame is validated, binary masks are treated as present/absent samples and fractional masks are normalized by Maximum Fractional Value. The service nearest-neighbor resamples the mask through patient coordinates and returns a transparent PNG with the source frame’s dimensions. X-Cache describes the decoded SEG-frame cache result.
An absent, ambiguous, or incompatible mapping returns HTTP 422 with semantic_mapping_unavailable. A non-SEG object returns 400, and an out-of-range SEG frame returns 404.
Display-frame query
Section titled “Display-frame query”GET /api/file/:index/frame/:frame accepts:
| Query | Accepted value |
|---|---|
wc |
Finite window center; use with ww. |
ww |
Positive finite window width; use with wc. |
mode |
default or full_dynamic. |
Successful responses are PNG and include X-Cache: HIT or X-Cache: MISS. The cache key includes file, frame, window center/width, and mode.
Window resolution order is full dynamic, explicit query pair, DICOM default, then current-frame percentile fallback.
Raw-frame headers
Section titled “Raw-frame headers”Successful raw responses include X-Cache plus these required headers:
| Header | Meaning |
|---|---|
X-Frame-Rows |
Frame row count. |
X-Frame-Columns |
Frame column count. |
X-Frame-Bits-Allocated |
DICOM bits allocated. |
X-Frame-Pixel-Representation |
0 unsigned or 1 signed. |
X-Frame-Samples-Per-Pixel |
Samples per response pixel. |
X-Frame-Photometric-Interpretation |
Renderer photometric interpretation. |
X-Frame-Rescale-Slope |
DICOM rescale slope. |
X-Frame-Rescale-Intercept |
DICOM rescale intercept. |
X-Frame-Default-Wc and X-Frame-Default-Ww are optional. One-bit samples are expanded to one byte each, but Bits Allocated remains 1 because the header describes the DICOM sample type. Integer and floating responses use little-endian sample bytes.
The raw cache key is only file and source frame; window parameters do not change decoded sample bytes.
Tag selection
Section titled “Tag selection”GET /api/file/:index/tags/select requires path. A selector alternates DICOM tags and zero-based sequence item indices:
(0008,2218)/69/(0008,0100)For a selected sequence, offset defaults to the beginning and limit must be from 1 through 256. Direct selection opens the object and traverses the requested path, so it is not constrained by the preview tag tree’s depth and item caps.
Binary VRs are represented by length. A value-level serialization failure appears as a typed error value so the rest of the tree can still render.
Annotation update and export
Section titled “Annotation update and export”The update request uses Content-Type: application/json and the payload defined in the annotation CSV reference. A successful export uses text/csv; charset=utf-8 and Content-Disposition: attachment; filename="dcmview-annotations.csv".
Error envelope
Section titled “Error envelope”Every API failure, including path, query, JSON extraction, unknown route, and wrong-method rejections, uses JSON:
{ "code": "not_found", "error": "file index out of range"}Clients may branch on the stable code. The human-readable error text provides context and is not a stable programmatic value.
| Status | Typical cause |
|---|---|
| 400 | Malformed path/query, incomplete window pair, or invalid annotation values. |
| 404 | Unknown route or file, missing pixel data, or frame out of range. |
| 405 | Unsupported method on a known route. |
| 422 | Structurally invalid JSON, unsupported syntax/layout, or unavailable semantic mapping. |
| 500 | Decode, filesystem, tag task, semantic/WSI read, or export failure. |
Request failures do not stop the server.
Cross-origin debugging
Section titled “Cross-origin debugging”Normal builds do not enable browser access from another origin. Source developers can build with the debug-api Cargo feature:
DCMVIEW_SKIP_FRONTEND_BUILD=1 cargo run --features debug-api -- ./studyThe feature enables permissive CORS and prints a build warning. Do not enable it for normal research inspection or a public bind.