Annotations & Measurements

The DICOM Viewer includes a full annotation and measurement system that lets authorised users mark up images and take measurements directly in the browser.

---

How It Works

Annotations are drawn on top of the displayed DICOM image using three separate toolsets:

Each toolset has its own toolbar button. Opening one toolset does not affect the others.

---

Per-Slice Storage

Every annotation is tied to a specific slice (frame index) and series within the DICOM file. When you navigate to a different slice, annotations for that slice appear automatically.

Annotations are stored with the DICOM attachment in the WordPress Media Library, not with the page or post embedding the viewer. This means:

• Annotations appear in every viewer that embeds the same file.
• Deleting or moving a post does not delete the annotations.
• The Media Library shows a summary column: annotation count, number of annotated slices, and last save time.

---

Who Can Annotate

Annotation controls are only shown to users who have the WordPress Upload files capability (Editors and Administrators by default). Visitors and subscribers see the annotations but cannot add, edit, or delete them.

---

Style Controls

Both the annotation and measurement toolsets include:

• Color picker — 8 preset swatches plus a custom hex input field
• Line width slider — 1–20 px stroke width

Color and line width are remembered per toolset for the current session.

---

Annotation Tools

The annotation toolset lets you place visual markers and shapes on any slice. Open it by clicking the Annotation button in the viewer toolbar.

---

Arrow

Draw a directed line to point at a region of interest.

1. Click the Arrow tool.
2. Click to set the start of the arrow, then click again (or drag) to set the tip.

The arrowhead is drawn at the second point. Useful for indicating the exact location of a finding.

---

Text

Place a free-form text label on the image.

1. Click the Text tool.
2. Click on the image where you want the label to appear.
3. Type the label text in the prompt that appears and confirm.

The label renders with a semi-transparent background so it remains readable over bright or dark areas.

---

Point

Mark a named point on the image.

1. Click the Point tool.
2. Click the image to place the marker.

A small circle anchor is drawn at the click location. The default label is "Point". Use this when you want to mark a location without adding a full text annotation.

---

Circle

Draw a circular region of interest.

1. Click the Circle tool.
2. Click and drag to define the circle — drag from the centre outward.

The circle outline is drawn in the active annotation color. To measure the area or intensity of the enclosed region, switch to the Measurement or Intensity toolset.

---

Oval

Draw an elliptical region of interest.

1. Click the Oval tool.
2. Click and drag to define the bounding box of the ellipse.

The oval adjusts its semi-axes to fit the rectangle you drag. Useful for ROIs that are not perfectly round.

---

Polygon

Draw a multi-point closed shape.

1. Click the Polygon tool.
2. Click to place each vertex (minimum 3 points required).
3. Close the polygon by clicking near the first point, or double-click to finish.

The polygon outline closes automatically when completed. Suitable for tracing irregular anatomical boundaries.

---

Freehand

Draw a hand-drawn path.

1. Click the Freehand tool.
2. Click and drag to draw freely. Release to finish.

The path is automatically simplified to reduce the number of stored points while preserving the overall shape.

---

Style Controls

Both the annotation and measurement toolsets share the same style controls, maintained separately per toolset.

Color

Click the color swatch button in the annotation toolbar to open the color picker. Choose from 8 preset colors or type a custom hex code. The active color applies to all new annotations in that toolset until changed.

Line Width

Click the line width button to open the slider. Drag to set stroke width from 1 to 20 px.

---

Saving Annotations

Click the Save button in the annotation toolbar to persist all annotations for the current file. A brief Saved indicator confirms the operation. Annotations are stored in the WordPress Media Library against the DICOM attachment and load automatically on the next page visit.

Note: Navigating away without saving will discard unsaved changes.

---

Measurement Tools

The measurement toolset provides quantitative tools for educational and non-diagnostic review use. Open it by clicking the Measurement button in the viewer toolbar.

All measurements that require distance or area use the DICOM pixel spacing data embedded in the file. When pixel spacing is available, results are reported in real-world units (mm, mm²). When it is not available, an asterisk (*) is appended to indicate that the value is in relative units rather than calibrated millimetres.

---

Length

Measure the straight-line distance between two points.

1. Click the Length tool.
2. Click to place the first endpoint, then click again to place the second.

The measured distance is displayed in mm next to the line. If the image was captured without pixel spacing information, the result shows as a pixel-based estimate marked with *.

---

Angle

Measure the angle formed by three points.

1. Click the Angle tool.
2. Click to place the vertex (centre point), then click twice more for the two arms.

The angle between the two arms is displayed in degrees (°). The vertex is the point at which the angle is measured.

---

Two-Line Angle / Cobb Angle

Measure the angle between two independent lines (four points total).

1. Click the Two-Line Angle tool.
2. Click to place the two endpoints of the first line, then click twice more for the second line.

This tool can be used for Cobb angle-style measurements in spinal scoliosis assessment, while also supporting any general two-line angle measurement. The result is normalised to always be less than 90° — if the computed angle exceeds 90°, the supplement (180° − angle) is shown instead.

---

Area — Circle / Oval

Measure the area enclosed by a circle or oval.

In the Measurement toolset, the Circle and Oval tools report the area of the enclosed region in mm² (calculated as π × semi-axis-x × semi-axis-y).

1. Click Circle or Oval in the Measurement toolset.
2. Click and drag to define the shape.

The area label appears near the shape boundary.

---

Area — Polygon

Measure the area enclosed by an arbitrary polygon.

In the Measurement toolset, the Polygon tool reports the polygon area in mm² using the Shoelace formula.

1. Click Polygon in the Measurement toolset.
2. Click to place vertices (minimum 3). Close the polygon by clicking near the first point or double-clicking.

---

Intensity Tools

The Intensity toolset reads pixel values directly from the decoded DICOM data.

Probe

Read the pixel intensity at a single point.

1. Open the Intensity toolset.
2. Click the Probe tool.
3. Click anywhere on the image.

For CT images, the value is shown in Hounsfield Units (HU). For other monochrome modalities, the raw decoded pixel value is shown. Rescale slope and intercept (DICOM tags 0028,1052–1053) are applied automatically.

ROI Mean Intensity — Circle / Oval

Compute the mean pixel value inside a circle or oval.

1. Open the Intensity toolset.
2. Click Circle or Oval.
3. Draw the shape over the region of interest.

The mean HU (or raw intensity) value within the shape is displayed. The calculation uses adaptive sampling to balance accuracy and performance.

ROI Mean Intensity — Polygon

Compute the mean pixel value inside an arbitrary polygon.

1. Open the Intensity toolset.
2. Click Polygon and draw the region.

The mean value is calculated using a point-in-polygon test (ray-casting) for every sampled pixel inside the bounding box.

---

Measurement Mode Toggle

For Circle, Oval, and Polygon tools that appear in both the Measurement and Intensity toolsets, you can switch the displayed value between:

The toggle is available in the tool’s options when the shape is selected.

---

Managing Annotations

Saving Annotations

Annotations are not saved automatically. After adding or editing annotations, click the Save button in the annotation toolbar. A brief Saved status indicator appears to confirm that the changes have been written to the server.

Tip: Save before navigating away from the page. Unsaved annotations will be lost on reload.

---

Per-Slice Scope

Each annotation is associated with:

• A slice index — the specific frame within the series
• A series UID — the DICOM Series Instance UID

When you scroll to a different slice, only the annotations for that slice are displayed. Annotations on other slices remain stored and reappear when you return to those slices.

---

Storage Location

Annotations are stored in WordPress post meta (_dv_annotations) against the DICOM attachment in the Media Library — not against the page or post where the viewer is embedded. This means:

• Annotations are shared across all viewers that embed the same DICOM file.
• Deleting a post that contains a viewer does not delete the annotations.
• Annotations remain if the file is re-embedded in a different page.

---

Media Library Summary

In the WordPress Media Library, DICOM files with saved annotations show a summary in the attachment details panel:

• Annotation count — total number of annotations across all slices
• Annotated slices — how many distinct slices contain at least one annotation
• Last updated — date and time of the most recent save

---

Customising Style

The color and line width of annotations can be set before placing them, or changed by selecting an existing annotation:

• Color — click the color swatch in the toolbar to open the color picker. Choose from 8 preset swatches or enter a custom hex value.
• Line width — click the line width button to reveal a slider (1–20 px).

Color and line width are tracked separately for the Annotation toolset and the Measurement toolset.

---

Deleting Annotations

To delete an annotation:

1. Switch to the relevant toolset (Annotation or Measurement).
2. Click an existing annotation to select it.
3. Press Delete or Backspace, or use the delete button that appears when the annotation is selected.

Save after deleting to persist the change.

---