feat(image-redactor): redact all frames of multi-frame DICOM images

[Dashtid]

Change Description

DicomImageRedactorEngine previously detected and redacted PII on only the first frame of a multi-frame DICOM instance, and raised ValueError: Too many dimensions: 3 > 2 when redacting multi-frame (e.g. XA) grayscale instances, because the pixel array was passed to Image.fromarray with the frame axis still present.

This makes redaction frame-aware:

• Frame count is read from NumberOfFrames (0028,0008); single-frame behavior is unchanged.
• PII detection runs per frame. Multi-frame instances can carry burned-in PHI on any frame, and not necessarily in the same location (as raised in Image Redactor - Support Multiframe Image Redaction #1737), so each frame is scanned and redacted independently.
• _add_redact_box decodes the pixel data once, applies each frame's boxes to that frame, and writes it back as a single block (this also removes a fragile re-decode that relied on pixel_array caching in the previous in-place mutation).
• Per-frame rescaling preserves per-frame contrast.
• The DICOM verify engine visualizes a representative frame for multi-frame inputs instead of raising.

This also resolves the Too many dimensions: 3 > 2 crash (#1731).

Prior art

#1735 was an earlier attempt at the #1731 crash and was closed without merging. That approach stopped the exception by processing only the first frame; it was confirmed in-thread that the other frames were still not redacted. This PR instead scans and redacts every frame, which is the behavior requested in #1737.

Tests

Added tests/test_dicom_multiframe_redaction.py:

• _get_number_of_frames (multi-frame, single-frame, missing element)
• per-frame rescaling returns a stacked uint8 array
• _add_redact_box redacts every frame for greyscale and color multi-frame instances, and leaves single-frame behavior unchanged
• end-to-end redact() applies redaction to every frame
• regression test for the Image Redactor - XA modality - ValueError: Too many dimensions: 3 > 2. #1731 crash

The image-redactor unit suite (200 tests) and ruff pass locally. Integration tests that require a Tesseract binary were not run locally and are left to CI.

Issue reference

Fixes #1737
Fixes #1731

Open questions

• Detection runs OCR per frame, which is faithful to Image Redactor - Support Multiframe Image Redaction #1737 but is N x OCR for large cine loops. Would you prefer an optional frame-deduplication step (skip re-OCR on identical frames) or an opt-out for very large series?
• For multi-frame inputs the verify engine currently visualizes the first frame rather than returning per-frame results. Is that acceptable, or would per-frame verification output be preferable?

Checklist

• I have reviewed the contribution guidelines
• I have signed the CLA (if required)
• My code includes unit tests
• All unit tests and lint checks pass locally
• My PR contains documentation updates / additions if required

[Copilot]

Pull request overview

This PR updates the Presidio image-redactor DICOM pipeline to correctly handle multi-frame DICOM instances by running detection and redaction per frame (instead of only the first frame), preventing the ValueError: Too many dimensions: 3 > 2 failure on multi-frame grayscale XA-like inputs.

Changes:

• Added frame-aware detection/redaction in DicomImageRedactorEngine, including per-frame bbox handling and per-frame rescaling.
• Updated the DICOM verify engine to visualize a representative frame for multi-frame inputs instead of raising.
• Added a focused unit test suite covering multi-frame behavior and the #1731 regression, and documented the change in the changelog.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
presidio-image-redactor/tests/test_dicom_multiframe_redaction.py	New unit tests validating multi-frame frame-by-frame rescaling, bbox application, and end-to-end redaction + regression coverage.
presidio-image-redactor/presidio_image_redactor/dicom_image_redactor_engine.py	Core implementation: frame-aware detection, per-frame rescaling, bbox normalization, and single-pass pixel data mutation for multi-frame DICOM redaction.
presidio-image-redactor/presidio_image_redactor/dicom_image_pii_verify_engine.py	Adjust verification to select a representative frame for multi-frame inputs.
CHANGELOG.md	Documented the new multi-frame DICOM redaction support and referenced the fixed issues.

[Dashtid]

Rebased onto current main to pick up the CI fixes from #2091/#2092.

Also addressed the two automated review points:

• _normalize_bboxes_per_frame now accepts the per-frame format ([[...]]) for single-frame instances as the docstring states; previously a nested list passed for a single-frame instance would have failed downstream in _add_redact_box.
• _add_redact_box now reuses the already-decoded frame for box-color selection instead of re-decoding instance.pixel_array, so the pixel data is genuinely decoded once.

Added a unit test for the single-frame per-frame-format case. Full image-redactor unit suite (201 tests) and ruff pass locally.

[Dashtid]

This is rebased onto current main and CI is green across the matrix. Scope stays limited to DicomImageRedactorEngine: per-frame detection and redaction for multi-frame instances (fixes #1737 and the #1731 Too many dimensions: 3 > 2 crash), with unit tests built on synthetic multi-frame fixtures.

Two design points from the description are open to your preference whenever someone picks this up:

1. Detection runs OCR per frame, which is faithful to Image Redactor - Support Multiframe Image Redaction #1737 but is N× on large cine loops. Would an optional frame-deduplication step (skip re-OCR on identical frames) or an opt-out be worth adding, or is per-frame the right default for now?
2. For multi-frame inputs the verify engine visualizes a representative frame rather than returning per-frame results. Is that acceptable, or would per-frame verification output be preferable?

Happy to adjust either way.