Work with ROI annotations

Load an EMBED-style CSV, edit rectangular regions of interest in the viewer, and export a fresh CSV without modifying the input annotations or DICOM files.

Prepare the CSV

Each row needs anon_dicom_path and ROI_coords. num_ROI and ROI_frames are optional.

embed_annotations.csv

anon_dicom_path,num_ROI,ROI_coords,ROI_frames
/data/dbt_case.dcm,2,"[[120,340,220,430],[400,510,480,590]]","[[0,1,2],[5,6]]"
/data/ffdm_case.dcm,1,"[[80,150,190,260]]","[]"

Coordinates use [ymin, xmin, ymax, xmax] image-pixel indices. Frame indices are zero-based. An omitted ROI_frames, an empty outer array, or an empty list for one ROI means that ROI applies to every frame.

Paths are matched by normalized absolute equality. Relative CSV paths are resolved from the directory where dcmview starts; loaded DICOM paths also get a best-effort canonical alias for symlink matching.

Load the annotations

dcmview --annotations ./embed_annotations.csv ./study

The CSV header is checked at startup. After discovery, matching rows are parsed in one background streaming pass, so a large dataset-level CSV does not delay the first image. Rows whose path matches no loaded DICOM file are ignored without parsing their ROI payload.

Edit an ROI

1. Open the matching file and frame.
2. Press R or choose the ROI tool.
3. Drag to draw a rectangle.
4. Select an ROI to move, resize, or delete it.
5. Adjust its frame scope when the annotation should not appear on every frame.

Viewer changes replace the in-memory annotation payload for the current file. Edits made while CSV ingestion is still running are preserved and are not overwritten by the later import.

Export the current state

Choose Export ROIs. The viewer downloads dcmview-annotations.csv from the current in-memory store. Extra input columns are not preserved.

Export before stopping dcmview; unexported edits disappear with the temporary server.

Fix validation failures

A matching row fails when it has invalid JSON, mismatched ROI counts, different coordinate/frame list lengths, coordinates outside image bounds, or a frame index outside NumberOfFrames. If one matching row is invalid, the import commits no CSV annotations; image inspection continues, but annotation reads and export report the validation error.

See the exact annotation CSV reference and annotation troubleshooting.