Annotation CSV reference

dcmview loads, edits, and exports rectangular ROI annotations in memory. It never modifies the input CSV or source DICOM files.

CSV columns

Column	Required	Meaning
anon_dicom_path	yes	Path of the DICOM object described by the row.
ROI_coords	yes	JSON array of [ymin, xmin, ymax, xmax] boxes.
num_ROI	no	Declared ROI count; when present, it must equal the coordinate count.
ROI_frames	no	JSON array with one zero-based frame-index list per ROI.

Extra input columns are ignored and are not preserved during export.

Coordinate and frame rules

ROI_coords contains image-pixel indices:

[
  [120, 340, 220, 430],
  [400, 510, 480, 590]
]

For each box:

• every coordinate must be a non-negative integer;
• ymin and xmin are inclusive upper-left indices; and
• ymax and xmax should be greater than ymin and xmin, and the box should lie inside the image rows and columns.

Loading checks only the first rule. A box that is empty, inverted, or outside the image is kept and exported as written, but the viewer refuses to save an edit to a file whose boxes break the last rule.

ROI_frames has one list for each coordinate box:

[
  [0, 1, 2],
  [5, 6]
]

Frame indices are zero-based and must be less than the DICOM object’s frame count. An omitted field, [], or an empty list for one ROI means that ROI applies to all frames.

A JSON-valued field that contains a comma must be quoted according to CSV rules. A value without one, such as [] or [[0]], needs no quotes, and export writes it unquoted.

embed_annotations.csv

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

Path matching

CSV paths are resolved from the directory where dcmview started and normalized to absolute keys, including . and .. components. Loaded DICOM files also receive a best-effort canonical alias, so relative, absolute, and symlinked forms can match when they resolve to the same object.

A row with no loaded path match is ignored without parsing its ROI JSON. This makes it practical to pass a dataset-level annotation CSV while opening a subset of its DICOM files.

Import transaction

The CSV header is validated during startup. Matching rows are parsed after DICOM discovery in one blocking streaming pass. Annotation reads and export wait for that pass to finish, while ordinary image viewing can continue.

If a matching row is invalid, no annotations from the input CSV are committed. Viewer edits made while import is running are never overwritten by the later import.

Validation failures include:

• missing anon_dicom_path or ROI_coords headers;
• invalid JSON in ROI_coords or ROI_frames;
• num_ROI differing from the coordinate count;
• different coordinate and frame-list counts;
• a negative or non-integer coordinate; and
• an out-of-range frame index.

Box bounds are not among them: they are checked when an edit is saved, not when the CSV loads. Invalid ROI values on rows that match no loaded file are ignored.

Export

The browser’s Export ROIs action downloads the complete current annotation store as dcmview-annotations.csv. If the export fails, the viewer shows a notice instead of navigating away. Export is the only built-in persistence path for edits; it writes a new file and does not modify the input CSV. The export keeps real file paths in a masked session (--mask) and never includes redaction boxes.

Source maintainers can find the private annotation payload and routes in the internal HTTP protocol documentation.