Command-line Interface

The dicom-dre deidentify command de-identifies one or more DICOM files or directories. It is a command-line wrapper over the batch engine (dicom_dre.deidentify_paths). Beyond forwarding the per-patient parameters, the CLI resolves the identifier-hash salt (from --hash-salt, the DICOM_DRE_HASH_SALT environment variable, or a generated per-user salt file) and the build-time configuration (--uid-root, --allowlist-csv, --hash-salt); the engine performs the identifier and UID hashing, date jitter, and free-text redaction.

Usage

dicom-dre deidentify [OPTIONS] SOURCES...

SOURCES is one or more files and/or directories. The command reads every source but never modifies it. It mirrors directory trees under the output directory; explicitly listed files are written directly into the output directory. It prints one line per processed file, followed by a summary.

Options

  • -o, --output-dir DIRECTORY: Directory to write de-identified files into, created if needed. Required.

  • -r, --recursive: Recurse into subdirectories of directory sources.

  • --glob PATTERN: Filename pattern for directory scans. Repeatable and case-insensitive. Default: *.dcm, *.dicom.

  • --profile [default|lds|lds-no-dob|strict]: De-identification profile to apply. Default: default. See De-identification Profiles.

  • -p, --param KEY=VALUE: A per-patient de-identification parameter, repeatable, for example -p PATIENT_ID=TEST. Accepts only the per-patient identity keys (PATIENT_ID, PATIENT_NAME, ACCESSION_NUMBER, STUDY_ID, SERIES_DESCRIPTION, STUDY_DESCRIPTION, PROTOCOL_NAME, JITTER); any other key is rejected. Build-time settings use their own flags below. A non-zero JITTER applies only to date-shifting profiles; combining a non-zero JITTER with a non-date-shifting profile (lds and lds-no-dob, which preserve dates, and strict, which removes them) is a usage error. JITTER=0 requests no shift and is accepted by any profile.

  • --study-id VALUE: Study identifier scoping the identifier and UID hashes (the STUDY_ID parameter). Default: unset.

  • --uid-root VALUE: UID root prefix under which re-derived UIDs are hashed. Default: 1.2.840.4267.32..

  • --allowlist-csv VALUE: Free-text redaction allowlist filename or absolute path. Default: default.csv.

  • --hash-salt VALUE: Salt applied when hashing PatientID, PatientName, and AccessionNumber. When omitted, the salt is resolved in order: the DICOM_DRE_HASH_SALT environment variable, then the per-user salt file at $XDG_CONFIG_HOME/dicom-dre/salt (default ~/.config/dicom-dre/salt). If none exists, a memorable passphrase is generated, saved with 0600 permissions, and reported on stderr. Keep that file secret and back it up: the same salt is required to reproduce the same pseudonyms on later runs. For scripted or CI use, supply the salt explicitly (via --hash-salt or DICOM_DRE_HASH_SALT) so runs stay deterministic.

  • --generate-salt / --no-generate-salt: Whether to generate and persist a salt when none is supplied. With --no-generate-salt the command errors instead of generating, keeping scripted runs deterministic. Default: --generate-salt.

  • -q, --quiet: Suppress informational notices on stderr, such as the salt generation notice. Does not affect the per-file result lines or summary on stdout.

  • -v, --verbose: Enable debug logging, including tracebacks for quarantined files. Quarantine reasons are always reported on the QUARANTINED: line; this flag adds the underlying traceback for diagnosis. Python warnings raised by dependencies (for example pydicom VR mismatches) are routed through logging and shown only under this flag; otherwise they are suppressed.

  • --decompress / --no-decompress: Decompress encapsulated pixel data on output. Default: --no-decompress.

  • --rename-to-sop-uid / --no-rename-to-sop-uid: Rename each output file to its new SOP Instance UID. Default: --rename-to-sop-uid.

  • --highlight-blanked-pixels: Fill scrubbed pixel regions with a visible color.

  • -j, --workers N: Number of worker processes; 1 runs sequentially in-process. Default: number of CPUs.

  • --help: Show the message and exit.

Output filenames

Output filenames are the new SOP Instance UID by default. With --no-rename-to-sop-uid, the command keeps the input basename and fails before writing anything if two inputs would resolve to the same output path.

Parallel processing

With --workers greater than 1, the command processes files across worker processes and prints lines as each file completes rather than in discovery order.

Outcomes and exit status

Each instance resolves to one terminal outcome:

  • DEIDENTIFIED: metadata scrubbed, pixel regions blanked as required, and the instance written to the output directory.

  • FILTERED: the instance matched a deny rule, so the command did not emit it.

  • QUARANTINED: processing failed, so the command did not emit the instance.

The command exits with status 1 when any file was QUARANTINED. FILTERED files are a normal outcome and do not affect the exit code.

Examples

De-identify a single file:

dicom-dre deidentify scan.dcm -o out/

Recurse a directory tree, mirrored under the output directory:

dicom-dre deidentify studies/ -o out/ -r

Mix files and directories in one run:

dicom-dre deidentify a.dcm b.dcm dir/ -o out/

Apply a profile with replacement parameters and parallel workers:

dicom-dre deidentify studies/ -o out/ -r \
    --profile default \
    -p PATIENT_ID=TEST -p ACCESSION_NUMBER=TESTING \
    -j 8

Checking the JPEG DCT accelerator

JPEG DCT-domain blanking uses an optional compiled C extension (_jpeg_dct_accel) that is roughly 300x faster than the pure-Python fallback. The dicom-dre accelerator-status command reports whether that extension is active, so operators can confirm the fast path in CI and health checks.

dicom-dre accelerator-status

It prints one line and sets the exit code:

  • JPEG DCT C accelerator: ACTIVE, exit code 0.

  • JPEG DCT C accelerator: NOT AVAILABLE (using pure-Python fallback, ~300x slower), exit code 1.

The same state is available from Python through dicom_dre.jpeg_dct_accelerator_available:

from dicom_dre import jpeg_dct_accelerator_available

if not jpeg_dct_accelerator_available():
    raise SystemExit("JPEG DCT C accelerator is not compiled")