Skip to content

About

Native macOS MR/CT/RTSTRUCT metadata pseudonymization with UID remapping, optional MRI JSON sidecars, staged audits, and interruption recovery.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

DICOM Anonymizer

Project status: maintenance mode. Feature development is paused indefinitely. The repository receives only maintenance. The latest download is Preview 37 (app build 41). Open decisions and deferred work are listed in the roadmap; how to test and release is in Maintenance; every document is indexed in the documentation index.

Local DICOM metadata pseudonymization for imaging-data privacy.

DICOM Anonymizer combines a Python engine with a native macOS interface for preparing pseudonymized MR, CT, and RTSTRUCT batches. It replaces patient identity fields with numeric folder pseudonyms and consistently remaps patient-specific UIDs and nested references. Processing runs locally, keeps source files read-only, and rereads staged output for self-audit before publishing a new batch.

Use it when a research workflow calls for numeric patient pseudonyms and consistent references across a batch. Its metadata policy preserves image pixels and contour geometry; retained content still requires review before sharing.

Download the macOS preview · Try the Python engine · Data-handling policy · Report an issue

The standalone preview targets Apple silicon and macOS 13+ and includes Python and pydicom. The Python engine is also available separately. Project source is MIT-licensed.

Visual workflow

The app creates a new audited output tree; original DICOM files remain unchanged.

flowchart TB
  A["DICOM batch"] --> B["Validate batch"]
  B --> C["Pseudonymize"]
  C --> D["Remap UIDs"]
  B --> E["Optional JSON"]
  D --> F["Audit output"]
  E --> F
  F --> G["Publish report"]
Loading

Metadata pseudonymization has limits. Numeric folder identifiers remain in PatientName and PatientID and can remain linkable. Pixels, contours, selected free text, and demographic attributes are retained. The tool does not redact image text or faces and does not guarantee irreversible anonymity, certified DICOM confidentiality-profile conformance, or complete IOD validation. Review retained content before sharing output.

Current download: Preview 37 (app build 41) (tag v2.0.0-preview.37). Signed and notarized macOS arm64 app. What is new since Preview 36 (build 40):

  • Tighter de-identification (engine policy 2.0-build6). Identity-bearing elements (person-name, date, date-time, time and application-entity values) are now blanked by dictionary VR as well as by the VR a file declares, at top level and nested, so a file that declares a mismatched VR no longer keeps such a value. The self-audit flags survivors. This adds no new rejections.
  • Engine-only command-line tools. --explain gives a read-only explanation of how the policy treats one file, and --verify-output DIR is a read-only, source-free re-audit of a published output folder. The app does not expose either. See the engine interface reference and the engine guide.
  • Documentation and contracts. The engine interface reference now has contract tests, the output-permission contract is documented, and there are a synthetic performance benchmark, a canary retention survey, manual-only test and lint scripts, and a maintenance roadmap.

The native app executable and interface are unchanged from Preview 36 and were reused. Preview 36 received one live GUI acceptance pass on synthetic data (launch, wrong-root rejection, scan, a two-patient six-file batch, an evicted iCloud Drive file and a rename-replaced input; an independent pydicom audit of the output passed). Not observed: Dock and Finder icon presentation, the input-changed message, pipe swap, MRI sidecars, cancellation, recovery, large batches, other macOS versions and real data. See Runtime acceptance. --verify-output is not an independent conformance check; its limits are in the roadmap.

The batch workflow

Arrange the input as a batch folder whose immediate child folders are numeric patient pseudonyms, such as 00001 and 00002. Each identifier may be up to 64 characters, and its exact spelling—including leading zeros—becomes the output folder name and both PatientName and PatientID.

  1. Scan the batch. The engine checks supported inputs and cross-file identity and reference constraints.
  2. Process into a new destination. Internal filenames are generated independently of source names; patient-specific UIDs and nested references are consistently remapped within each patient.
  3. Review the report and retained content. Staged files are reread and self-audited before atomic publication. The completed batch includes anonymization-report.json with pseudonyms, aggregate counts, software/policy versions, and audit status, without an original-identity mapping.

The supported modality labels are MR, CT, and RTSTRUCT. Conflicting patient identities, a study split across patient folders, or patient-relative frame-of-reference UIDs shared across patient folders stop the batch. Repeated references within one patient remain allowed. These checks do not establish complete validity of every MR/CT/RTSTRUCT object.

Download and install the macOS app

  1. Open Releases and download the standalone macOS arm64 preview ZIP.
  2. Expand it and copy DICOM Anonymizer 2.0.app to Applications.
  3. Open the app, choose the input batch and an output location, inspect the scan summary, and process the batch.

The Preview 37 release is app version 2.0.0, build 41. Its app is Developer ID signed and Apple notarized, with a stapled ticket. It includes CPython 3.13.16 and pydicom 3.0.2 and uses its bundled interpreter wherever the app is moved. No Homebrew, separate Python installation, launch-time runtime download, or package installation is needed.

Earlier focused runtime acceptance was performed on Apple silicon with macOS 27.2. Older deployment versions and Intel Macs were not exercised. The macOS 13 deployment target is not a claim of runtime acceptance on every newer OS release.

Recover from a problem

Preview 7 keeps long recovery messages scrollable while the affected path and recovery actions remain visible. Blocking problems hide stale completion details; report warnings preserve the completed result. The existing recovery behaviors from preview 6 remain:

Problem App behavior
Rejected or inaccessible input Clears the previous source and ready preview so another action cannot silently process an old batch. Choose a valid folder and check again.
Invalid or disconnected output location Offers Choose Location. A valid replacement preserves the scanned batch without rescanning. Directory-existence validation does not guarantee write permission.
Missing or unopenable report Keeps the completed-batch summary. Reveal Output locates the result; Dismiss returns to the completed state.
Cancellation or pending error Keeps action availability consistent while the worker stops, ignores late progress, and disables repeated cancellation.

See compact recovery presentation for the new focused evidence, error recovery for the preceding behavior, and workflow polish for earlier interface changes.

Try it with synthetic data

The engine requires Python 3.10+ and pydicom 3.0.2. Installing the dependency needs access to a package source; processing has no upload or network feature.

git clone https://github.com/jdotc1/dicom-anonymizer.git
cd dicom-anonymizer
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python examples/generate_batch.py --destination .synthetic/input
python engine/engine.py --source .synthetic/input --scan
python engine/engine.py --source .synthetic/input --destination .synthetic/output

The generator reads no patient files. It creates two fictional patients and six small MR/CT/RTSTRUCT objects, demonstrating metadata and references rather than clinical images or complete IOD validation fixtures. Both the generator and processing destination refuse an existing destination; choose a new path for another run.

Expected output has 00001 and 00002, three DICOM files per patient, and anonymization-report.json. Inspect the report's aggregate counts and self-audit status. The CLI emits JSON-line events; see the engine interface reference and engine guide.

What changes and what remains

Content Policy
PatientName and PatientID Replaced recursively with the exact numeric patient-folder identifier.
Patient-specific UIDs and nested references Consistently remapped. SOP-class, transfer-syntax, and explicit structural/coding identifiers remain.
Private tags, uninterpreted public UN elements, dates/times, and known identifying fields Cleared or removed; retired curve groups are removed. Required type-2 fields may remain present with empty values.
File metadata and preamble Rebuilt and synchronized; preambles are zeroed.
SeriesDescription, ProtocolName, SequenceName, ContrastBolusAgent, SoftwareVersions, and Manufacturer Retained. Free text can still identify people or institutions.
PatientSex, PatientAge, PatientSize, and PatientWeight Retained. These attributes can remain identifying in combination with other information.
Image pixels, contour geometry, public quantitative measurements, ROI names, and observation labels Retained. Visual identifiers and facial anatomy are not removed.

Removing private tags can remove vendor-specific quantitative information; clearing dates removes temporal information. An absent burned-in annotation flag does not establish that pixels contain no identifying content.

For RTSTRUCT-specific handling, retained labels, reference/geometry limits and the focused comparison with the Stanford scripts, see RTSTRUCT policy and coverage.

The independent staged-file header audit also has focused source coverage for the writer's existing preamble and file-meta guarantees; its delivery status and evidence scope are recorded separately.

See Bounded recovery messages for the delivered change that limits accumulated notice text while retaining recovery records and uncertainty from omitted details.

Symbolic links, nonregular patient-file entries, unsupported modalities, duplicate instance UIDs, invalid required UIDs, declared burned-in annotations, and overlays stop processing. Non-DICOM sidecars, including recognized AppleDouble companions, are excluded and counted. Malformed DICOM files stop the batch; not every malformed-stream or resource-exhaustion case is covered. Common atlas-space workflows are not an approved exception to cross-patient frame-of-reference checks.

A disk-space preflight estimates required capacity. The pre-publication audit checks identity, date, private-tag, UN, clear/remove, and UID invariants, including metadata after Pixel Data. Some policy lists are shared with the cleaner, so the self-audit is not an independent conformance oracle. Failures and handled cancellation remove staging; abrupt process death or power loss can leave hidden staging. The data-handling policy is the detailed contract.

Build the macOS interface from source

The native target is arm64 with macOS 13+. Building requires full Xcode, Apple Swift 6.4 in Swift 6 language mode, and a local Python 3.12+ environment with the pinned pydicom dependency. Warnings are treated as errors. toolchain.sh uses the selected Xcode installation or DEVELOPER_DIR.

bash build.sh

The result is build/DICOM Anonymizer 2.0.app, ad-hoc signed for local development. The first build downloads the pinned standalone Python archive; unchanged cached archives reuse their digest-bound acquisition receipt. These are build-time requirements. The resulting app includes the interpreter, pydicom, runtime licenses, and dependency notices.

The bundle identifier is io.github.jdotc1.dicom-anonymizer. Source contains no Developer ID certificate, notarization credential, signing key, or custom artwork. The downloadable app includes the project-selected icon. For a local build with externally supplied compiled icon resources, set APP_ICON_RESOURCES to a folder containing Assets.car and AppIcon.icns; the build copies them and sets the icon plist keys before signing. Intel and other operating systems are not claimed as native-app targets; the Python engine remains available separately.

Development and acceptance evidence

Unit tests use synthetic temporary data. The optional native integration test uses only the example generator and a separate preferences identifier, writing under .synthetic/.

scripts/run_tests.sh            # unit tests with a private temp root
bash test_drop.sh
scripts/lint.sh                 # optional, non-gating lint counts (--strict to gate)

scripts/run_tests.sh forwards extra arguments to python -B -m unittest discover (for example -k sidecar). Several test modules read DICOM_TEST_TMPDIR: if it is set to an existing directory the runner uses it and never removes it; otherwise the runner creates a private directory under ${TMPDIR:-/tmp}, prints it, and removes only that directory on exit. Set DICOM_TEST_TIMEOUT_SCALE (for example 3) to stretch subprocess timeouts on a slow machine. Running python -m unittest discover -s tests directly also works when DICOM_TEST_TMPDIR is exported first.

Runtime acceptance, error recovery, and release review distinguish focused checks from reused engine, self-audit, native processing, runtime, and dependency evidence. Bundled runtime checks include scan/completion with external Python locations denied and the missing-runtime error without external fallback. These are recorded checks, not a claim that every preview reruns all suites or covers all native gestures.

The engine policy is 2.0-build6, separately versioned from the app's release/build number. It changed from 2.0-build5 in Preview 37 because identity-bearing elements are now cleared by dictionary VR as well as declared VR. CI is manual-only, requires explicit acknowledgment, and has read-only repository permissions. Use the linked records for actual command, environment, and acceptance scope.

Contributing, reporting, and license

Use minimal synthetic examples in issues and pull requests. Do not post patient files, original filenames, identifiers, or unredacted logs. Follow CONTRIBUTING.md; security-sensitive reports use the private reporting route in SECURITY.md.

Project source is MIT-licensed. Dependencies retain their own terms. Preserve the complete notices in THIRD_PARTY_NOTICES.md when redistributing them.

Documentation

The documentation index lists every document by topic. Starting points:

About

Native macOS MR/CT/RTSTRUCT metadata pseudonymization with UID remapping, optional MRI JSON sidecars, staged audits, and interruption recovery.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages