dicom-dre 1.1.0.dev2__tar.gz → 1.1.1.dev1__tar.gz

{dicom_dre-1.1.0.dev2 → dicom_dre-1.1.1.dev1}/.github/dependabot.yml

@@ -35,7 +35,7 @@ updates:
 
   # Dev container base image and features.
   - package-ecosystem: "devcontainers"
-    directory: "/.devcontainer"
+    directory: "/"
     target-branch: "development"
     schedule:
       interval: "weekly"

{dicom_dre-1.1.0.dev2 → dicom_dre-1.1.1.dev1}/.github/workflows/ci.yml

@@ -8,6 +8,9 @@ on:
   pull_request:
     types: [opened, edited, synchronize, reopened]
 
+permissions:
+  contents: read
+
 concurrency:
   group: ci-${{ github.ref }}
   cancel-in-progress: true

{dicom_dre-1.1.0.dev2 → dicom_dre-1.1.1.dev1}/.github/workflows/deploy.yml

@@ -24,6 +24,9 @@ on:
       - main
       - development
 
+permissions:
+  contents: read
+
 concurrency:
   group: deploy-${{ github.ref_name }}
   cancel-in-progress: false
@@ -161,7 +164,6 @@ jobs:
     if: needs.version.outputs.released == 'true'
     runs-on: ubuntu-latest
     permissions:
-      contents: write   # create tags, commits, and GitHub Releases
       id-token: write   # PyPI trusted publishing (OIDC)
     steps:
       - name: Checkout
@@ -190,6 +192,11 @@ jobs:
           github_token: ${{ steps.get_workflow_token.outputs.token }}
           git_committer_name: "github-actions"
           git_committer_email: "actions@users.noreply.github.com"
+          # Prerelease builds on `development` must not write CHANGELOG.md;
+          # only stable releases on `main` update the changelog. Combined with
+          # squash-merging `development` into `main`, this keeps prerelease tags
+          # off `main`'s history so each stable release section is populated.
+          changelog: ${{ github.ref_name == 'development' && 'false' || 'true' }}
 
       - name: Publish to PyPI
         # Uses PyPI Trusted Publishing (OIDC); configure a trusted publisher for
@@ -213,7 +220,9 @@ jobs:
 
       - name: Upload distributions to the GitHub Release
         # Uploads the wheels, sdist, and the Sigstore .sigstore.json bundles.
+        # Uses the application token (contents: write via the GitHub App) so the
+        # job's GITHUB_TOKEN can remain read-only.
         if: steps.release.outputs.released == 'true'
         env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ steps.get_workflow_token.outputs.token }}
         run: gh release upload "${{ steps.release.outputs.tag }}" dist/* --clobber

{dicom_dre-1.1.0.dev2 → dicom_dre-1.1.1.dev1}/.github/workflows/docs.yml

@@ -22,7 +22,7 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: write
+  contents: read
 
 # Serialize deployments so concurrent release tag pushes do not race when
 # reconstructing and publishing the shared gh-pages tree.
@@ -33,6 +33,8 @@ concurrency:
 jobs:
   deploy:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write   # push the assembled site to the gh-pages branch
     steps:
       - name: Checkout
         uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

dicom_dre-1.1.1.dev1/.github/workflows/fuzz.yml

@@ -0,0 +1,84 @@
+name: Fuzz
+
+# Using the Atheris fuzzing framework as oss-fuzz is Python 3.11 only.
+# Pull requests run a short regression budget; the nightly schedule
+# runs longer and persists the grown corpus via actions/cache.
+
+on:
+  pull_request:
+    paths:
+      - "src/**"
+      - "fuzz/**"
+      - ".github/workflows/fuzz.yml"
+  schedule:
+    - cron: "0 7 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  fuzz:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      UV_NO_GROUP: docs
+    strategy:
+      fail-fast: false
+      matrix:
+        harness:
+          - fuzz_text_redactor
+          - fuzz_jpeg_dct
+          - fuzz_catalog_match
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Install Atheris
+        run: uv pip install atheris
+
+      - name: Restore corpus
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: fuzz/corpus/${{ matrix.harness }}
+          key: fuzz-corpus-${{ matrix.harness }}-${{ github.run_id }}
+          restore-keys: |
+            fuzz-corpus-${{ matrix.harness }}-
+
+      - name: Fuzz ${{ matrix.harness }}
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            duration=120
+          else
+            duration=900
+          fi
+          mkdir -p "fuzz/corpus/${{ matrix.harness }}" crashes
+          # -timeout flags a single input exceeding 25s as a crash, catching
+          # catastrophic regex backtracking (ReDoS) in the redaction/catalog paths.
+          uv run python "fuzz/${{ matrix.harness }}.py" \
+            -max_total_time="$duration" \
+            -timeout=25 \
+            -rss_limit_mb=4096 \
+            -artifact_prefix=crashes/ \
+            "fuzz/corpus/${{ matrix.harness }}"
+
+      - name: Upload crashes
+        if: failure()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: fuzz-crashes-${{ matrix.harness }}
+          path: crashes/
+          if-no-files-found: ignore

dicom_dre-1.1.1.dev1/.github/workflows/scorecard-analysis.yml

@@ -0,0 +1,56 @@
+name: Scorecard analysis workflow
+on:
+  push:
+    # Only the default branch is supported.
+    branches:
+    - main
+  schedule:
+    # Weekly on Saturdays.
+    - cron:  '30 1 * * 6'
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      # Needed for Code scanning upload
+      security-events: write
+      # Needed for GitHub OIDC token if publish_results is true
+      id-token: write
+
+    steps:
+      - name: "Checkout code"
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: "Run analysis"
+        uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          # Scorecard team runs a weekly scan of public GitHub repos,
+          # see https://github.com/ossf/scorecard#public-data.
+          # Setting `publish_results: true` helps us scale by leveraging your workflow to
+          # extract the results instead of relying on our own infrastructure to run scans.
+          # And it's free for you!
+          publish_results: true
+
+      # Upload the results as artifacts (optional). Commenting out will disable
+      # uploads of run results in SARIF format to the repository Actions tab.
+      # https://docs.github.com/en/actions/advanced-guides/storing-workflow-data-as-artifacts
+      - name: "Upload artifact"
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      # Upload the results to GitHub's code scanning dashboard (optional).
+      # Commenting out will disable upload of results to your repo's Code Scanning dashboard
+      - name: "Upload to code-scanning"
+        uses: github/codeql-action/upload-sarif@f205ea1c3313d32999d8d6a48b4f6530d4437b38 # v4.37.4
+        with:
+          sarif_file: results.sarif

{dicom_dre-1.1.0.dev2 → dicom_dre-1.1.1.dev1}/.github/workflows/tests.yml

@@ -6,6 +6,9 @@ name: Tests
 on:
   workflow_call:
 
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -28,3 +31,12 @@ jobs:
 
       - name: Run tests
         run: uv run pytest
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@0565863a31f2c772f9f0395002a31e3f06189574 # v5.4.3
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: true
+          use_pypi: true
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

{dicom_dre-1.1.0.dev2 → dicom_dre-1.1.1.dev1}/.gitignore

@@ -68,3 +68,9 @@ db.sqlite3
 *.dicom
 *.ima
 *.DCM
+
+# Fuzzing crash artifacts
+crashes/
+
+# Hypothesis example database
+.hypothesis/

{dicom_dre-1.1.0.dev2 → dicom_dre-1.1.1.dev1}/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 <!-- version list -->
 
-## v1.1.0-dev.1 (2026-08-06)
+## v1.1.0 (2026-08-07)
 
 ### Features
 
@@ -10,6 +10,11 @@
   Profile (STAR-12623) ([#1](https://github.com/susom/dicom-dre/pull/1),
   [`257ac8d`](https://github.com/susom/dicom-dre/commit/257ac8db5a930b30e24e0030cb48ceba6ff48c31))
 
+### Bug Fixes
+
+- Upgrade gitpython to resolve known vulnerabilities
+  ([`313ec2a`](https://github.com/susom/dicom-dre/commit/313ec2aeffbb10fc6a8900055c9e6c6df5bfbebc))
+
 
 ## v1.0.1 (2026-07-31)
 

dicom_dre-1.1.1.dev1/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: dicom-dre
+Version: 1.1.1.dev1
+Summary: DICOM De-identification & Redaction Engine
+Project-URL: repository, https://github.com/susom/dicom-dre
+Author-email: Joseph Mesterhazy <jmesterh@stanford.edu>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <3.13,>=3.12
+Requires-Dist: cffi>=1.16
+Requires-Dist: click
+Requires-Dist: numpy>=2.4.1
+Requires-Dist: pydicom>=3.0
+Requires-Dist: pyjpegls>=1.5.1
+Requires-Dist: pylibjpeg-libjpeg>=2.1.0
+Requires-Dist: pylibjpeg-openjpeg>=2.5.0
+Requires-Dist: pylibjpeg-rle>=2.2.0
+Requires-Dist: pylibjpeg>=2.1.0
+Requires-Dist: python-gdcm==3.2.6
+Requires-Dist: readchar
+Description-Content-Type: text/markdown
+
+[![Python versions](https://img.shields.io/pypi/pyversions/dicom-dre)](https://pypi.org/project/dicom-dre/)
+[![License](https://img.shields.io/pypi/l/dicom-dre)](LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/dicom-dre)](https://pypi.org/project/dicom-dre/)
+[![CI](https://github.com/susom/dicom-dre/actions/workflows/ci.yml/badge.svg)](https://github.com/susom/dicom-dre/actions/workflows/ci.yml)
+[![Docs](https://github.com/susom/dicom-dre/actions/workflows/docs.yml/badge.svg)](https://susom.github.io/dicom-dre/)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/susom/dicom-dre/badge)](https://scorecard.dev/viewer/?uri=github.com/susom/dicom-dre)
+[![codecov](https://codecov.io/gh/susom/dicom-dre/branch/main/graph/badge.svg)](https://codecov.io/gh/susom/dicom-dre)
+
+# dicom-dre
+
+DICOM de-identification for both metadata and burned-in pixel text.
+
+Burned-in text is the more difficult case. The engine blanks it from rules you
+define rather than from OCR or heuristic text detection: you specify which
+scanner models burn text into which regions of the frame, and the engine blanks
+those regions. That rule set is the device catalog.
+
+- **Rule-based pixel blanking.** The device catalog identifies an instance by
+  its scanner and acquisition settings and blanks the fixed regions recorded for
+  it. Coverage is exactly what you put in the catalog: it only blanks devices
+  and regions you have mapped and validated, and unmatched devices pass through
+  untouched.
+
+- **Lossless redaction.** Editing a JPEG normally means decompressing it and
+  recompressing it, which slightly degrades the whole image. For JPEG Baseline
+  images the engine instead edits the compressed data directly and blanks only
+  the masked blocks, so every pixel outside those blocks stays bit-for-bit
+  identical.
+
+- **Deterministic and offline.** No lookups and no network calls. UIDs and
+  replacement identifiers are re-derived by hashing, so the same input plus the
+  same parameters always produces the same output.
+
+- **Simple, embeddable API.** Call it from your own DICOM pipeline in a few
+  lines, and supply your own identifiers (PatientID, AccessionNumber, date
+  jitter) or let it derive them for you.
+
+Metadata is handled alongside the pixels: description fields such as
+`SeriesDescription` and `StudyDescription` are redacted to remove likely PHI
+while preserving clinical meaning, and every attribute is scrubbed against a
+configurable de-identification profile.
+
+Tailoring the device catalog and allowlist to the scanners in your PACS and the
+vocabulary your site uses is the substantive work of adopting `dicom-dre`. Once
+that investment is made, the result is a repeatable, auditable pipeline you can
+trust to process DICOM at your site.
+
+> **Note:** Output is **not** de-identified under HIPAA Safe Harbor or Expert
+> Determination and must be validated by a qualified person before sharing. The
+> bundled catalog and allowlist were derived from a single PACS at one site and
+> are unlikely to be complete elsewhere. It also does not address
+> re-identification vectors in the image content itself, such as facial
+> reconstruction from volumetric imaging. Always treat output as retaining
+> residual PHI risk. See
+> [Limitations and portability](https://susom.github.io/dicom-dre/stable/about/limitations.html).
+
+## Install
+
+Requires Python 3.12.
+
+```bash
+uv pip install dicom-dre    # or: pip install dicom-dre
+```
+
+## Quick start
+
+```bash
+# De-identify a file or a directory tree into out/
+dicom-dre deidentify scan.dcm -o out/
+dicom-dre deidentify studies/ -o out/ -r
+
+# Choose a profile, set parameters, run in parallel (-j sets worker count)
+dicom-dre deidentify studies/ -o out/ \
+    --profile default -p PATIENT_ID=TEST -p ACCESSION_NUMBER=TESTING -j 8
+```
+
+Sources are read but never modified. The command exits non-zero if any instance
+is quarantined.
+
+```python
+from dicom_dre import DeidParameters, ProfileSpec, deidentify_paths
+
+for item in deidentify_paths(
+    sources=["studies/"],
+    output_dir="out/",
+    recursive=True,
+    profile_spec=ProfileSpec(name="default"),
+    parameters=DeidParameters(patient_id="TEST"),
+):
+    print(item.input_file, item.result.outcome)
+```
+
+## Outcomes
+
+Each instance resolves to exactly one outcome:
+
+| Outcome | Meaning |
+| --- | --- |
+| `DEIDENTIFIED` | Metadata scrubbed, pixels blanked as required, written to output. |
+| `FILTERED` | Matched a deny rule (e.g. unsupported modality/device); not emitted. |
+| `QUARANTINED` | Processing failed; not emitted. |
+
+## Profiles
+
+Each profile applies the DICOM PS3.15 Basic Application Confidentiality Profile
+(strict is allow-list based) plus a set of PS3.15 options, recorded in
+DeidentificationMethodCodeSequence `(0012,0064)`.
+
+| Profile | PS3.15 method | Options applied | Dates |
+| --- | --- | --- | --- |
+| `default` | `DICOM-PS3.15E-Basic` | Clean Structured Content (113104), Clean Descriptors (113105), Retain Patient Characteristics (113108) | Shifted per study by a derived jitter |
+| `lds` | `DICOM-PS3.15E-Basic-LDS` | Clean Descriptors (113105), Retain Patient Characteristics (113108) | Retained unchanged (limited data set) |
+| `lds-no-dob` | `DICOM-PS3.15E-Basic-LDS-No-DOB` | Clean Descriptors (113105), Retain Patient Characteristics (113108) | Retained unchanged except PatientBirthDate/Time, which are removed |
+| `strict` | Allow-list (Basic Profile not emitted) | Clean Graphics (113103), Clean Structured Content (113104) | Removed; a minimal set of technical time elements is retained |
+
+`default`, `lds`, and `lds-no-dob` re-derive UIDs by hashing; `strict` retains a
+fixed allow-list of elements and discards the rest.
+
+See [De-identification Profiles](https://susom.github.io/dicom-dre/stable/concepts/profiles.html).
+
+## Free-text redaction tools
+
+Description attributes such as `SeriesDescription` and `StudyDescription` are
+among the most useful fields for understanding what a study contains, yet
+because a technologist can type into them freely at the imaging device, they
+frequently pick up PHI. Redaction keeps the useful vocabulary while masking the
+rest, and it is driven by an allowlist you tailor to your site.
+
+Redaction works token by token. A token is a run of text between delimiters:
+each value is split at whitespace, punctuation, and letter/digit boundaries (so
+`MR512` becomes `MR` and `512`). Every token is compared case-insensitively
+against the allowlist; tokens on the list pass through, and the rest are masked
+character-for-character with `X`. Before tokenizing, a set of regular
+expressions masks structured identifiers regardless of the allowlist, including
+dates, times, phone numbers, SSNs, ZIP+4 codes, email addresses, URLs, and long
+hexadecimal strings, while bare 1 to 5 digit numbers are allowed through.
+
+Because the allowlist must match your site's vocabulary, the `redactor`
+subcommands exist to build and maintain it. Export every `SeriesDescription`,
+`StudyDescription`, and `ProtocolName` value from your PACS database to a CSV,
+then run these commands over that export to review the distinct tokens and
+decide which belong on the allowlist:
+
+```bash
+# Preview redactions and review flagged tokens, adding good ones to the allowlist
+dicom-dre redactor quality-check input.csv --interactive
+# List the distinct tokens in the export to curate the allowlist
+dicom-dre redactor show-tokens --input input.csv
+# Add one or more tokens to the allowlist directly
+dicom-dre redactor allow-token TERM1 TERM2
+# Redact every cell of a CSV against the current allowlist
+dicom-dre redactor redact --input input.csv --output output.csv
+```
+
+See the [redactor guide](https://susom.github.io/dicom-dre/stable/guides/redactor.html).
+
+## Documentation
+
+Full documentation: **https://susom.github.io/dicom-dre/**
+
+- [Installation](https://susom.github.io/dicom-dre/stable/getting-started/installation.html) and [Quickstart](https://susom.github.io/dicom-dre/stable/getting-started/quickstart.html)
+- [Architecture](https://susom.github.io/dicom-dre/stable/concepts/architecture.html), [Device Catalog](https://susom.github.io/dicom-dre/stable/concepts/device-catalog.html), [JPEG DCT scrubbing](https://susom.github.io/dicom-dre/stable/concepts/jpeg-dct.html)
+- [Profiles](https://susom.github.io/dicom-dre/stable/concepts/profiles.html), [Text redaction](https://susom.github.io/dicom-dre/stable/concepts/text-redaction.html), [Reproducibility](https://susom.github.io/dicom-dre/stable/concepts/reproducibility.html)
+- [CLI reference](https://susom.github.io/dicom-dre/stable/guides/cli.html), [Extending the catalog](https://susom.github.io/dicom-dre/stable/guides/extending-the-catalog.html), [Local validation](https://susom.github.io/dicom-dre/stable/guides/local-validation.html)
+- [API reference](https://susom.github.io/dicom-dre/stable/reference/api.html)
+
+## Development
+
+```bash
+uv run pytest
+```
+
+The JPEG DCT accelerator is an optional compiled C extension roughly 300x faster
+than the pure-Python fallback. Check its status with:
+
+```bash
+dicom-dre accelerator-status
+```
+
+Contributions are welcome via pull request. Changes to de-identification policy
+(catalog, scrub regions, profiles, or allowlist) require local evidence and
+regression fixtures.
+
+## License
+
+Apache-2.0; provided "AS IS" without warranty (see [LICENSE](LICENSE)). The JPEG
+DCT-domain scrubber is a port of the PixelMed JPEG Selective Block Redaction
+Codec, distributed under that codec's BSD license; see the source header in
+`src/dicom_dre/jpeg_dct_scrubber.py` and the [NOTICE](NOTICE) file.

dicom_dre-1.1.1.dev1/README.md

@@ -0,0 +1,189 @@
+[![Python versions](https://img.shields.io/pypi/pyversions/dicom-dre)](https://pypi.org/project/dicom-dre/)
+[![License](https://img.shields.io/pypi/l/dicom-dre)](LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/dicom-dre)](https://pypi.org/project/dicom-dre/)
+[![CI](https://github.com/susom/dicom-dre/actions/workflows/ci.yml/badge.svg)](https://github.com/susom/dicom-dre/actions/workflows/ci.yml)
+[![Docs](https://github.com/susom/dicom-dre/actions/workflows/docs.yml/badge.svg)](https://susom.github.io/dicom-dre/)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/susom/dicom-dre/badge)](https://scorecard.dev/viewer/?uri=github.com/susom/dicom-dre)
+[![codecov](https://codecov.io/gh/susom/dicom-dre/branch/main/graph/badge.svg)](https://codecov.io/gh/susom/dicom-dre)
+
+# dicom-dre
+
+DICOM de-identification for both metadata and burned-in pixel text.
+
+Burned-in text is the more difficult case. The engine blanks it from rules you
+define rather than from OCR or heuristic text detection: you specify which
+scanner models burn text into which regions of the frame, and the engine blanks
+those regions. That rule set is the device catalog.
+
+- **Rule-based pixel blanking.** The device catalog identifies an instance by
+  its scanner and acquisition settings and blanks the fixed regions recorded for
+  it. Coverage is exactly what you put in the catalog: it only blanks devices
+  and regions you have mapped and validated, and unmatched devices pass through
+  untouched.
+
+- **Lossless redaction.** Editing a JPEG normally means decompressing it and
+  recompressing it, which slightly degrades the whole image. For JPEG Baseline
+  images the engine instead edits the compressed data directly and blanks only
+  the masked blocks, so every pixel outside those blocks stays bit-for-bit
+  identical.
+
+- **Deterministic and offline.** No lookups and no network calls. UIDs and
+  replacement identifiers are re-derived by hashing, so the same input plus the
+  same parameters always produces the same output.
+
+- **Simple, embeddable API.** Call it from your own DICOM pipeline in a few
+  lines, and supply your own identifiers (PatientID, AccessionNumber, date
+  jitter) or let it derive them for you.
+
+Metadata is handled alongside the pixels: description fields such as
+`SeriesDescription` and `StudyDescription` are redacted to remove likely PHI
+while preserving clinical meaning, and every attribute is scrubbed against a
+configurable de-identification profile.
+
+Tailoring the device catalog and allowlist to the scanners in your PACS and the
+vocabulary your site uses is the substantive work of adopting `dicom-dre`. Once
+that investment is made, the result is a repeatable, auditable pipeline you can
+trust to process DICOM at your site.
+
+> **Note:** Output is **not** de-identified under HIPAA Safe Harbor or Expert
+> Determination and must be validated by a qualified person before sharing. The
+> bundled catalog and allowlist were derived from a single PACS at one site and
+> are unlikely to be complete elsewhere. It also does not address
+> re-identification vectors in the image content itself, such as facial
+> reconstruction from volumetric imaging. Always treat output as retaining
+> residual PHI risk. See
+> [Limitations and portability](https://susom.github.io/dicom-dre/stable/about/limitations.html).
+
+## Install
+
+Requires Python 3.12.
+
+```bash
+uv pip install dicom-dre    # or: pip install dicom-dre
+```
+
+## Quick start
+
+```bash
+# De-identify a file or a directory tree into out/
+dicom-dre deidentify scan.dcm -o out/
+dicom-dre deidentify studies/ -o out/ -r
+
+# Choose a profile, set parameters, run in parallel (-j sets worker count)
+dicom-dre deidentify studies/ -o out/ \
+    --profile default -p PATIENT_ID=TEST -p ACCESSION_NUMBER=TESTING -j 8
+```
+
+Sources are read but never modified. The command exits non-zero if any instance
+is quarantined.
+
+```python
+from dicom_dre import DeidParameters, ProfileSpec, deidentify_paths
+
+for item in deidentify_paths(
+    sources=["studies/"],
+    output_dir="out/",
+    recursive=True,
+    profile_spec=ProfileSpec(name="default"),
+    parameters=DeidParameters(patient_id="TEST"),
+):
+    print(item.input_file, item.result.outcome)
+```
+
+## Outcomes
+
+Each instance resolves to exactly one outcome:
+
+| Outcome | Meaning |
+| --- | --- |
+| `DEIDENTIFIED` | Metadata scrubbed, pixels blanked as required, written to output. |
+| `FILTERED` | Matched a deny rule (e.g. unsupported modality/device); not emitted. |
+| `QUARANTINED` | Processing failed; not emitted. |
+
+## Profiles
+
+Each profile applies the DICOM PS3.15 Basic Application Confidentiality Profile
+(strict is allow-list based) plus a set of PS3.15 options, recorded in
+DeidentificationMethodCodeSequence `(0012,0064)`.
+
+| Profile | PS3.15 method | Options applied | Dates |
+| --- | --- | --- | --- |
+| `default` | `DICOM-PS3.15E-Basic` | Clean Structured Content (113104), Clean Descriptors (113105), Retain Patient Characteristics (113108) | Shifted per study by a derived jitter |
+| `lds` | `DICOM-PS3.15E-Basic-LDS` | Clean Descriptors (113105), Retain Patient Characteristics (113108) | Retained unchanged (limited data set) |
+| `lds-no-dob` | `DICOM-PS3.15E-Basic-LDS-No-DOB` | Clean Descriptors (113105), Retain Patient Characteristics (113108) | Retained unchanged except PatientBirthDate/Time, which are removed |
+| `strict` | Allow-list (Basic Profile not emitted) | Clean Graphics (113103), Clean Structured Content (113104) | Removed; a minimal set of technical time elements is retained |
+
+`default`, `lds`, and `lds-no-dob` re-derive UIDs by hashing; `strict` retains a
+fixed allow-list of elements and discards the rest.
+
+See [De-identification Profiles](https://susom.github.io/dicom-dre/stable/concepts/profiles.html).
+
+## Free-text redaction tools
+
+Description attributes such as `SeriesDescription` and `StudyDescription` are
+among the most useful fields for understanding what a study contains, yet
+because a technologist can type into them freely at the imaging device, they
+frequently pick up PHI. Redaction keeps the useful vocabulary while masking the
+rest, and it is driven by an allowlist you tailor to your site.
+
+Redaction works token by token. A token is a run of text between delimiters:
+each value is split at whitespace, punctuation, and letter/digit boundaries (so
+`MR512` becomes `MR` and `512`). Every token is compared case-insensitively
+against the allowlist; tokens on the list pass through, and the rest are masked
+character-for-character with `X`. Before tokenizing, a set of regular
+expressions masks structured identifiers regardless of the allowlist, including
+dates, times, phone numbers, SSNs, ZIP+4 codes, email addresses, URLs, and long
+hexadecimal strings, while bare 1 to 5 digit numbers are allowed through.
+
+Because the allowlist must match your site's vocabulary, the `redactor`
+subcommands exist to build and maintain it. Export every `SeriesDescription`,
+`StudyDescription`, and `ProtocolName` value from your PACS database to a CSV,
+then run these commands over that export to review the distinct tokens and
+decide which belong on the allowlist:
+
+```bash
+# Preview redactions and review flagged tokens, adding good ones to the allowlist
+dicom-dre redactor quality-check input.csv --interactive
+# List the distinct tokens in the export to curate the allowlist
+dicom-dre redactor show-tokens --input input.csv
+# Add one or more tokens to the allowlist directly
+dicom-dre redactor allow-token TERM1 TERM2
+# Redact every cell of a CSV against the current allowlist
+dicom-dre redactor redact --input input.csv --output output.csv
+```
+
+See the [redactor guide](https://susom.github.io/dicom-dre/stable/guides/redactor.html).
+
+## Documentation
+
+Full documentation: **https://susom.github.io/dicom-dre/**
+
+- [Installation](https://susom.github.io/dicom-dre/stable/getting-started/installation.html) and [Quickstart](https://susom.github.io/dicom-dre/stable/getting-started/quickstart.html)
+- [Architecture](https://susom.github.io/dicom-dre/stable/concepts/architecture.html), [Device Catalog](https://susom.github.io/dicom-dre/stable/concepts/device-catalog.html), [JPEG DCT scrubbing](https://susom.github.io/dicom-dre/stable/concepts/jpeg-dct.html)
+- [Profiles](https://susom.github.io/dicom-dre/stable/concepts/profiles.html), [Text redaction](https://susom.github.io/dicom-dre/stable/concepts/text-redaction.html), [Reproducibility](https://susom.github.io/dicom-dre/stable/concepts/reproducibility.html)
+- [CLI reference](https://susom.github.io/dicom-dre/stable/guides/cli.html), [Extending the catalog](https://susom.github.io/dicom-dre/stable/guides/extending-the-catalog.html), [Local validation](https://susom.github.io/dicom-dre/stable/guides/local-validation.html)
+- [API reference](https://susom.github.io/dicom-dre/stable/reference/api.html)
+
+## Development
+
+```bash
+uv run pytest
+```
+
+The JPEG DCT accelerator is an optional compiled C extension roughly 300x faster
+than the pure-Python fallback. Check its status with:
+
+```bash
+dicom-dre accelerator-status
+```
+
+Contributions are welcome via pull request. Changes to de-identification policy
+(catalog, scrub regions, profiles, or allowlist) require local evidence and
+regression fixtures.
+
+## License
+
+Apache-2.0; provided "AS IS" without warranty (see [LICENSE](LICENSE)). The JPEG
+DCT-domain scrubber is a port of the PixelMed JPEG Selective Block Redaction
+Codec, distributed under that codec's BSD license; see the source header in
+`src/dicom_dre/jpeg_dct_scrubber.py` and the [NOTICE](NOTICE) file.