RSNA DICOM Anonymizer (V19)

en · de · es · fr

Other languages: Deutsch, Español, Français.

Version 19.0.10 is the current stable V19 release on the master branch and PyPI. Development pre-release 19.1.0.dev1 lives on the dev branch (uv pip install --pre rsna-anonymizer). Requires Python 3.12–3.14 with tkinter built in. Prefer 3.12 for the widest Tk/AI wheel coverage; avoid 3.14.1 (torchvision excludes that patch).

Install

You need three things: uv, a Python 3.12–3.14 environment that includes tkinter, and (on macOS, for AI Features) libomp.

1. Install uv

uv installs Python, creates the venv, and pulls large AI dependencies.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

Confirm uv is on your PATH:

uv --version

2. Install Python with tkinter, then the app

The desktop UI needs tkinter. Install a Python that ships with it, then create the venv and install 19.0.10:

Platform	Ensure tkinter is available
Windows	Install Python 3.12–3.14 from python.org with Add to PATH and tcl/tk and IDLE checked
macOS	Prefer uv python install 3.12 (Tk 9.x). Or Homebrew: brew install python@3.12 python-tk@3.12
Linux	sudo apt install python3.12 python3.12-tk python3.12-venv (or the matching packages for 3.13 / 3.14)

uv python install 3.12                     # or: 3.13 / 3.14
uv venv rsna-anonymizer --python 3.12      # or: --python 3.13 / 3.14
source rsna-anonymizer/bin/activate        # Windows: rsna-anonymizer\Scripts\activate

uv pip install rsna-anonymizer             # version 19.0.10

3. Verify the install

python --version          # 3.12.x–3.14.x
python -m tkinter         # a small Tk window must open — required for the UI
rsna-anonymizer --version # should report 19.0.10

If python -m tkinter fails, the venv’s Python was built without Tk: fix the platform step above, recreate the venv, and reinstall.

4. macOS only — OpenMP for AI Features

On macOS, AI Features that use TotalSegmentator / Harmonize contrast analysis need the C++ OpenMP runtime libomp. Install it once with Homebrew before you download or run those models:

brew install libomp

Without libomp, Harmonize contrast can crash (for example exit code 139 / XGBoost OpenMP errors). Face blur and other AI tools that depend on the same stack can be affected. Linux and Windows normally do not need this step.

5. Run

rsna-anonymizer

On first launch, use the Welcome screen AI Features button to download models and accept the face license when needed.

Run (modes)

rsna-anonymizer
rsna-anonymizer -c path/to/ProjectModel.json   # headless DICOM receive
rsna-anonymizer -c path/to/ProjectModel.json --ai-batch path/to/AiBatchConfig.json --ai-batch-run

Headless AI batch uses a companion AiBatchConfig.json (algorithms, modes, study selection, CT/MR resolution). OCR whitelists remain under the project whitelists/ directory.

Upgrade

source rsna-anonymizer/bin/activate
uv pip install --upgrade rsna-anonymizer

See CHANGELOG for release notes.

Documentation

Clinician user manual (MkDocs Material, English). Build locally: uv sync --group docs && uv run mkdocs serve. Maintainer notes: docs/README.md.

Development

git clone https://github.com/RSNA/anonymizer.git
cd anonymizer
git checkout master
uv sync --group dev
uv run pre-commit install
uv run rsna-anonymizer

For 19.1 development (pre-release), use git checkout dev instead of master.

macOS AI Features: brew install libomp (OpenMP runtime for Harmonize contrast / TotalSegmentator).

Hot-reload UI work: uv run python src/prototyping/dev_anonymizer.py (optional watchexec; falls back to watchfiles).

Experimental CLIs live under src/prototyping/.

Linting (Ruff)

Config: [tool.ruff] in pyproject.toml (scope: src/anonymizer/).

uv run ruff check ./src/anonymizer/
uv run ruff check ./src/anonymizer/ --fix   # safe auto-fixes; not used in CI
uv run pre-commit run ruff-check --all-files

Unit testing

Layout mirrors source: tests/controller/ → src/anonymizer/controller/. Prototyping tests: src/prototyping/*/tests/. See tests/README.md.

uv run pytest tests/controller/tseg -q
uv run pytest tests/controller tests/model -q   # CI suite (no view)
uv run pytest src/prototyping -q
uv run pytest -q                                # full local suite

Optional: tests/controller/.env with AWS_USERNAME / AWS_PASSWORD for S3 upload tests. Markers are documented in pyproject.toml and tests/README.md.

Translations

Languages: en_US, de, es, fr. Install gettext (brew install gettext, choco install gettext, or apt install gettext), then:

cd src/anonymizer/assets/locales/
./extract_translations.sh
./update_translations.sh

Software architecture

Class diagram

User manual (MkDocs)

uv sync --group docs
uv run mkdocs serve          # http://127.0.0.1:8000
uv run mkdocs build --strict

Community

• Code of Conduct
• Security policy
• License (Apache-2.0)