Isocenter

De-identify a DICOM cohort without touching the source files. Hand compliance a report that names anything the run could not do.

Isocenter is a Python library for indexing, de-identifying, and exporting DICOM datasets at cohort scale. It builds a SQLite metadata index and a pixel/waveform sidecar beside a read-only source tree. It applies your de-identification profile and pixel redaction rules to an in-memory object graph. It grades its own output and writes clean copies to a new directory, as DICOM or PhysioNet WFDB.

You have a cohort of studies and a protocol an IRB approved. You need to hand a de-identified copy to a collaborator, a registry, or a model. You also need to hand your compliance reviewer a record. The record shows what was removed, what stayed because the protocol allowed it, and anything the run lost on the way. Isocenter is the library your script imports to do that. There is no command-line tool: the Python API is the whole interface.

Documentation: https://kvnlng.github.io/Isocenter/

What it refuses to do

• Modify a source file. Ingest reads. Anonymize and redact change an in-memory graph. Until export(), the session writes only the store, isocenter.log and files you ask for (a configuration, a key, a report, a manifest or a cohort table). export() writes copies to a directory you name, so a crashed or abandoned run leaves the originals as they were. The store (<name>.db and <name>_pixels.bin) holds the original identifiers and pixels, so keep it where PHI may live.
• Grade a lossy export PASS. Every step that can lose data writes an audit row, and the compliance report reads those rows. A cohort that lost a file, a private tag, a waveform group, or a pixel frame grades REVIEW_REQUIRED and names the loss. An export that attempted instances and wrote none of them raises ExportError. A partial export returns what it wrote, with an ERROR row for each failure.
• Pass through pixels it could not decode. If a compressed frame cannot be decompressed, because of a missing codec or a stream the decoder rejects, the export fails on that instance. It does not copy bytes that it never inspected.
• Advertise a Python version it does not test. The suite runs on all four supported versions at every release, including the free-threaded 3.14t build. Versions 3.12 and 3.14t must pass before anything is uploaded. The PyPI classifiers list only those.

What it does

• De-identification against the DICOM PS3.15 Annex E Basic Profile table, edition 2026c. A profile decides which tags go, are emptied, are replaced, or are date-shifted. A field your protocol permits stays. Nested sequences are scanned, not only the top level. The date shift is deterministic per patient within a project, so intervals survive. UIDs are replaced consistently, so references between exported files still resolve. A UID in a private tag is not replaced yet (#765).
• Machine-specific pixel redaction. Redaction zones are keyed by device, because the same model burns identifiers into the same place every time. An optional OCR pass finds where the text lands, and CTP DicomPixelAnonymizer.script rules import directly.
• Reversible anonymization, if you choose it. Original identities can be encrypted under a key into the Encrypted Attributes Sequence (0400,0500) before anonymization, and recovered later by whoever holds the key.
• A persistent session. A Patient → Study → Series → Instance graph over a SQLite index and a pixel sidecar. With it, a 10,000-instance cohort reopens without rescanning, and a job can be paused and resumed. Every action is written to an audit log.
• A compliance report with a PASS or REVIEW_REQUIRED grade, every exception listed, and a signature block for the reviewer.
• Waveforms. DICOM waveform IODs (ECG, hemodynamic) export as PhysioNet WFDB records, with an annotation bridge to Murmur Studio.

Install

Isocenter needs Python 3.12 or later on Linux or macOS. The storage layer's locks use fcntl, so Isocenter does not import on Windows. On Windows, use WSL or a Linux container.

pip install isocenter

Check which version you have:

python -c "import isocenter; print(isocenter.__version__)"

The OCR, text-detection and NLP extras, and what each needs, are on the installation page.

Example

Put some DICOM files in input/ and run:

from isocenter import Session

# Worker processes are started by spawn, so a script needs this guard.
if __name__ == "__main__":
    with Session("my_project.db") as session:   # the session store
        session.ingest("input")                  # reads; never writes the source
        report = session.audit()                 # findings under the default policy
        session.anonymize(report)                # in memory
        summary = session.export("export_clean")
        print(len(summary.written_uids), "files written")
        session.generate_report("compliance_report.md")

With no configuration loaded, the default policy is the Basic Profile table (649 tag rules), with these settings:

• Study Date is shifted.
• Patient's Sex and Age are kept.
• Private tags are removed.

export_clean/ holds one Subject_ANON_… folder per patient written.

The default lossless JPEG 2000 cannot hold an image with 32- or 64-bit integer samples exactly. Such an image is written uncompressed, Explicit VR Little Endian, with its samples exact. An INFO log line says so, and no audit row is written. The other images of the export are still compressed.

The Executive Summary of compliance_report.md opens with the grade. The Quick Start adds a configuration, redaction, reversible anonymization and a verify step. The tutorials run each step on files bundled with pydicom.

Burned-in text

Machines burn identifiers into the pixels, and the same model tends to burn them in the same place every time. Isocenter finds that text by OCR and blanks it with redaction zones you write per device. The OCR guide covers both.

5b. Zone Discovery

discover_redaction_zones() reads a random sample of one machine's instances with OCR. It returns a DiscoveryResult of where text was found. Use the result to write zones from what the data does, not from one screenshot. The scan needs the ocr extra (pip install "isocenter[ocr]") and the tesseract binary. Without either, it raises OcrUnavailableError, and the error names what is missing.

result = session.discover_redaction_zones("SN-12345", sample_size=50, min_confidence=80.0)

# Suggested zones, in the [y1, y2, x1, x2] form the redaction config takes.
for zone in result.to_zones(min_occurrence=0.25):
    print(zone["type"], zone["zone"], zone["examples"])

to_zones() clusters the candidates. It keeps only clusters seen in at least min_occurrence of the sampled instances: a name in one frame out of fifty is noise, one in forty is the overlay. Working on a DiscoveryResult needs no extra:

>>> from isocenter.discovery import DiscoveryCandidate, DiscoveryResult
>>> result = DiscoveryResult([
...     DiscoveryCandidate("SMITH^JOHN", 92.0, [10, 8, 60, 12], 0, "NAME_PATTERN"),
...     DiscoveryCandidate("MERCY GENERAL", 88.0, [200, 180, 50, 10], 1, "PROPER_NOUN"),
... ], n_sources=2)
>>> list(result.to_dataframe().columns)
['text', 'confidence', 'box', 'source_index', 'classification']
>>> result.get_density_matrix(bins=(2, 2))
[[1, 0], [0, 1]]
>>> result.to_zones(min_occurrence=0.5)
[{'zone': [8, 20, 10, 70], 'type': 'LIKELY_NAME', 'occurrence': 0.5, 'confidence': 92.0, 'examples': ['SMITH^JOHN']}, {'zone': [180, 190, 200, 250], 'type': 'PROPER_NOUN', 'occurrence': 0.5, 'confidence': 88.0, 'examples': ['MERCY GENERAL']}]

filter(), to_zones() and to_dataframe() are frozen for 1.x. get_density_matrix() is documented but internal (API stability). get_density_matrix() is not an image-space heatmap. It bins each box's centre into a grid. The grid is normalised by the largest box origin among the candidates, not by the image's Rows and Columns. So two scans are not comparable to each other or to the image. Take coordinates from to_zones() or from each candidate's box.

Writing the zones

Zones go in the configuration file, under the machine they belong to:

machines:
  - serial_number: "DEV12345"
    model_name: "UltraSound Pro"
    redaction_zones:
      - [0, 50, 0, 800] # [row_start, row_end, col_start, col_end]

Documentation

• Installation and Quick Start
• Tutorials: de-identify and read the grade, select part of a cohort, reversible anonymization, redaction, a custom export format
• Configuration, Analytics & Reporting and how the grade is decided
• What the export writes and Codec support
• Import CTP rules, for a CTP DicomPixelAnonymizer.script
• MIDI-B benchmark: the scores, and the configuration that reaches them
• API reference and API stability
• Architecture and Performance
• For institutions and the changelog

Citing Isocenter

If Isocenter's de-identification is part of how a dataset was prepared, it belongs in the methods section rather than the acknowledgements. Use GitHub's Cite this repository button, which reads CITATION.cff.

Each release is archived on Zenodo. Cite the concept DOI, 10.5281/zenodo.22104298. It always resolves to the latest version, so the citation follows the work. If you need to record the exact version used, name it in the text (Isocenter v1.0.0). Leave the DOI pointing at the concept record.

Isocenter is the upstream half of a pair: it builds and de-identifies the corpus that Murmur Studio (10.5281/zenodo.21077528) reviews. Work that used both should cite both.

License

Apache-2.0. See LICENSE and NOTICE.

Releases up to and including 0.9.2 were published under the GNU Affero General Public License v3.0 or later and remain available under it. The change is not retroactive.

Contact

Bug reports and questions about documented behaviour go to GitHub Issues. They are answered there, in public, for free. Never post patient data, or anything taken from it, in an issue. If an export still carries something it should have removed or replaced, report it privately. Do the same if an export lets someone recover an identity or a real date. The security policy describes how.

Help beyond bug reports and questions is available as paid consulting. Examples:

• configuring a de-identification profile for a protocol
• integrating Isocenter into a pipeline
• reviewing a run's report before it goes to a reviewer
• a feature your study needs sooner than the roadmap

Write to [email protected] with what you need. Use the same address for anything that should not be public.