dicom-dre 1.0.0__tar.gz

dicom_dre-1.0.0/.devcontainer/devcontainer-lock.json

@@ -0,0 +1,24 @@
+{
+  "features": {
+    "ghcr.io/devcontainers-extra/features/apt-packages:1": {
+      "version": "1.0.6",
+      "resolved": "ghcr.io/devcontainers-extra/features/apt-packages@sha256:55c54412112da81b9381e470cdbbe55278564950d1ff536ce925b1e8e096babd",
+      "integrity": "sha256:55c54412112da81b9381e470cdbbe55278564950d1ff536ce925b1e8e096babd"
+    },
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "version": "2.5.9",
+      "resolved": "ghcr.io/devcontainers/features/common-utils@sha256:cb0c4d3c276f157eed17935747e364178d75fee17f55c4e129966f64633deb3a",
+      "integrity": "sha256:cb0c4d3c276f157eed17935747e364178d75fee17f55c4e129966f64633deb3a"
+    },
+    "ghcr.io/devcontainers/features/github-cli:1": {
+      "version": "1.1.0",
+      "resolved": "ghcr.io/devcontainers/features/github-cli@sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671",
+      "integrity": "sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671"
+    },
+    "ghcr.io/jsburckhardt/devcontainer-features/uv:1": {
+      "version": "1.0.0",
+      "resolved": "ghcr.io/jsburckhardt/devcontainer-features/uv@sha256:542a0bc2203205b3c696de650ba862f280b20af3543493cc232edd9ac35791f7",
+      "integrity": "sha256:542a0bc2203205b3c696de650ba862f280b20af3543493cc232edd9ac35791f7"
+    }
+  }
+}

dicom_dre-1.0.0/.devcontainer/devcontainer.json

@@ -0,0 +1,53 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
+// https://containers.dev/
+{
+  "name": "dicom-dre",
+  "image": "python:3.12-slim-trixie",
+  "remoteUser": "${localEnv:USER}${localEnv:USERNAME}",
+  "containerEnv": {
+    "UV_COMPILE_BYTECODE": "1",
+    "UV_LINK_MODE": "copy",
+    "UV_PYTHON_DOWNLOADS": "never",
+    "UV_TOOL_BIN_DIR": "/usr/local/bin"
+  },
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+        "extensions.verifySignature": false, // https://github.com/microsoft/vscode-remote-release/issues/9628
+        "remote.autoForwardPorts": false,
+        "extensions.ignoreRecommendations": true,
+        "git.autofetch": true,
+        "git.autofetchPeriod": 180
+      },
+      "extensions": [
+        "bierner.markdown-mermaid",
+        "charliermarsh.ruff",
+        "GitHub.copilot",
+        "GitHub.vscode-pull-request-github",
+        "ms-python.python",
+        "meta.pyrefly",
+        "redhat.vscode-yaml"
+      ]
+    }
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "username": "${localEnv:USER}${localEnv:USERNAME}",
+      "userUid": "1000",
+      "userGid": "1000",
+      "upgradePackages": "false",
+      "configureZshAsDefaultShell": "false"
+    },
+    "ghcr.io/devcontainers-extra/features/apt-packages:1": {
+      "packages": "build-essential,ca-certificates,cmake,curl,dcmtk,file,git,just,ninja-build,patchelf,pkg-config,swig,unzip,wget,zip,bubblewrap,socat"
+    },
+    "ghcr.io/jsburckhardt/devcontainer-features/uv:1": {},
+    "ghcr.io/devcontainers/features/github-cli:1": {}
+  },
+  "mounts": [
+    "source=dicom-dre-home,target=/home/${localEnv:USER}${localEnv:USERNAME},type=volume"
+  ],
+  "postCreateCommand": "bash ./.devcontainer/post-create.sh",
+  "waitFor": "postCreateCommand"
+}

dicom_dre-1.0.0/.devcontainer/post-create.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+set -euo pipefail
+
+WORKSPACE_DIR="$(pwd)"
+
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+# Git doesn't like the UID changes from bind-mounting the source into the container.
+if ! git config --global --get-all safe.directory | grep -qx "${WORKSPACE_DIR}"; then
+  git config --global --add safe.directory "${WORKSPACE_DIR}"
+fi
+
+# Convenience aliases.
+if ! grep -q "#dicom-dre#" "${HOME}/.bashrc" 2>/dev/null; then
+  {
+    echo '#dicom-dre#'
+    echo 'alias ll="ls -alF"'
+    echo 'alias la="ls -A"'
+    echo 'alias l="ls -CF"'
+  } >> "${HOME}/.bashrc"
+fi
+
+# Sync dependencies and build the CFFI JPEG-DCT extension (and python-gdcm from source).
+echo -e "${BLUE}Running uv sync...${NC}"
+uv sync
+
+# Compile the CFFI JPEG-DCT acceleration extension into src/dicom_dre/.
+# Without this the engine silently falls back to the ~300x-slower pure-Python
+# entropy codec. Building from src/ so the module 'dicom_dre._jpeg_dct_accel'
+# lands at src/dicom_dre/_jpeg_dct_accel.*.so.
+echo -e "${BLUE}Compiling JPEG-DCT acceleration extension...${NC}"
+(cd src && uv run python -m dicom_dre._jpeg_dct_accel_build)
+rm -f src/dicom_dre/_jpeg_dct_accel.c src/dicom_dre/_jpeg_dct_accel.o
+
+# Install git hooks so PHI-protection checks run on commit, push, and commit-msg.
+echo -e "${BLUE}Installing git hooks...${NC}"
+uv run pre-commit install --hook-type pre-commit --hook-type pre-push --hook-type commit-msg

dicom_dre-1.0.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

dicom_dre-1.0.0/.github/copilot-instructions.md

@@ -0,0 +1,253 @@
+COPILOT INSTRUCTIONS
+
+This document defines how the AI pair programmer should reason, communicate, and write code.
+It sets style rules, workflow expectations, and interaction guidelines to ensure consistent,
+high-quality, and safe contributions.
+
+CORE DIRECTIVE
+You are an expert AI pair programmer.
+Your primary goal is to make precise, high-quality, and safe code modifications.
+Follow every rule in this document meticulously.
+
+INTERACTION & REASONING GUIDELINES
+
+- Concise communication:
+  Use one clear sentence before each tool call to explain what you are doing.
+
+- Continuity:
+  If the user says "resume" or "continue", pick up exactly where your last step ended.
+
+- Thorough thinking:
+  Think rigorously and document reasoning internally.
+  Share only concise results externally.
+
+- Communication style:
+  Use factual, descriptive language in the style of internal engineering specifications.
+  Never use marketing terms (efficient, compelling, comprehensively, effectively, successfully).
+  Never use promotional adjectives (comprehensive, robust, powerful, optimized, seamless, flexible, scalable, intuitive, advanced, cutting-edge).
+  Never use enthusiastic phrases (Perfect! Excellent! Great! Awesome! I have successfully...).
+  Avoid the informal term "knobs" for configurable values; use "settings", "options", or "parameters".
+  Avoid evaluative or subjective judgments.
+  Prefer verbs and concrete nouns over adjectives.
+  Omit unverifiable or unquantifiable claims.
+  Provide factual summaries that describe actions and results without celebration.
+  When uncertain if a word is promotional, omit it.
+  Do not use emphatic markers (CRITICAL, IMPORTANT, WARNING) in code comments or documentation unless explicitly requested by the user.
+
+- File creation:
+  Do not create summary documentation unless explicitly requested.
+  Do not create test files without asking first.
+  Only create files directly required to fulfill the user's request.
+
+- Error checking:
+  After making any code changes, automatically check for linter errors using get_errors.
+  Fix all errors before reporting completion.
+  Never wait for the user to point out linter errors.
+
+CODING STANDARDS
+General Rule:
+
+- Implement the smallest possible change that satisfies the request.
+- Follow the Google Python coding standards except when they conflict with this document.
+- Do not create trailing whitespace, and immediately remove trailing whitespace when found.
+- Avoid spaces in empty lines.
+- Avoid the use of emojis in log messages or documentation.
+
+Naming Conventions:
+
+- Modules: lowercase_with_underscores
+- Classes: CapWords
+- Functions & variables: lowercase_with_underscores
+- Constants: UPPERCASE_WITH_UNDERSCORES
+- Private members: prefix with \_
+
+Strings:
+
+- Prefer double quotes ("...")
+- Use triple quotes ("""...""") for docstrings
+
+Error Handling:
+
+- CRITICAL: Never use assert statements for runtime validation
+- Assert statements are removed in optimized byte code compilation
+- Use explicit ValueError, TypeError, or other appropriate exceptions instead
+- Provide clear, descriptive error messages
+
+Example:
+# Wrong
+assert value is not None
+assert len(items) > 0
+
+# Correct
+if value is None:
+    raise ValueError("value must not be None")
+if len(items) == 0:
+    raise ValueError("items list cannot be empty")
+
+IMPORTS
+
+Rules:
+
+- All imports must be at the top of the file
+- Only use inline imports when necessary for performance or to avoid circular import issues
+- One import per line
+- Order: standard library -> third-party -> local
+- Always use absolute imports, inside **init**.py is ok
+- Avoid importing Prefect functions and modules in a file that does not contain @task and @flow functions.
+
+PACKAGE RESOURCES
+
+- Use importlib.resources, never Path(__file__).parent
+- Pattern: import importlib.resources as pkg_resources, then Path(str(pkg_resources.files(resource_module)))
+
+DOCSTRINGS & COMMENTS
+
+- Follow PEP 257
+- First line: short summary sentence
+- Document all public classes, methods, and functions
+- Never write obvious comments that simply restate what the code does
+- Omit self-evident or trivially true statements. Do not document facts the
+  reader can infer from the signature, types, or an obvious guarantee (for
+  example "this module has no dependencies so it avoids an import cycle",
+  "returns a value", "this is a helper"). Record a fact only when it is
+  non-obvious and affects correctness, safety, performance, or correct use.
+- State what the code does, not what it does not do. Avoid negative-space
+  statements that contrast with an alternative or a prior design (for example
+  "not passed to X", "rather than closing over Y"); these are usually
+  refactoring artifacts. Keep a negative statement only when it conveys
+  critical information the reader cannot infer, such as a safety constraint.
+- Write dry, precise prose using established computer science and engineering
+  terms. Name the actual mechanism, not an analogy for it.
+- Do not use metaphor or anthropomorphism. Data does not "travel", "live",
+  "ship", "flow", or get "baked in"; objects do not "carry", "own", or "want".
+  Use precise verbs instead: "is stored in", "resides in", "is fixed at
+  construction", "is serialized to", "is passed to", "occurs", "is scoped to".
+- Prohibited terms and replacements: "baked" -> "fixed"/"set at construction";
+  "knobs" -> "settings"/"options"/"parameters"; "lives" -> "is stored"/
+  "resides"/"occurs"; "travel"/"ship" -> "is serialized"/"is sent"/"is passed";
+  "carries" -> "holds"/"contains".
+
+Example:
+def add(x: int, y: int) -> int:
+    """Return the sum of x and y."""
+    return x + y
+
+TYPE ANNOTATIONS
+
+- Use PEP 484 type hints
+- Forward-declare types with TYPE_CHECKING if needed
+- Use quoted annotations ("State") when types are not available at runtime
+
+DATACLASSES
+
+- Fields with default values MUST come after fields without defaults
+- Order fields: required fields first, then optional/default fields
+- Use field(default=...) or field(default_factory=...) for fields with defaults
+- Never mix required and default fields in arbitrary order
+
+Example:
+@dataclass
+class MyClass:
+    # Required fields first
+    name: str
+    age: int
+    # Default fields last
+    status: str = "active"
+    tags: List[str] = field(default_factory=list)
+
+TESTING
+
+- Run tests using `uv run pytest` (NEVER `python -m pytest`)
+- Place tests in tests/ using pytest
+- Mock external services in unit tests especially if they use network calls
+- Prefer small, isolated tests over broad coverage in a single test
+- Avoid disabling, skipping, or commenting out failing unit tests. If a unit test fails, fix the root cause of the exception.
+- Avoid removing assertions, adding empty try/catch blocks, or making tests trivial in order to make tests pass.
+- Avoid introducing conditional logic that skips test cases under certain conditions, for example a missing dependency.
+- Always ensure the unit test continues to properly validate the intended functionality.
+
+DOCUMENTATION
+
+- When making changes to workflows, always update the corresponding documentation in the docs/ folder
+- Keep workflow documentation synchronized with code changes
+- Update relevant .md files in docs/workflows/ when modifying flow implementations
+- When adding CLI documentation, verify all commands and options against actual --help output
+- When adding new documentation files, add them to the `nav` section in mkdocs.yml
+
+CLI REGISTRATION
+
+- When creating new CLI commands, always register them in src/dicom_dre/cli.py
+- Add the new command or command group to the `cli` group following the pattern of existing subcommands
+- Group related subcommands under a click group (as done for the redactor subgroup)
+
+PYTHON PACKAGE MANAGEMENT
+
+- Always use `uv` instead of `pip` for all package management operations
+- Installation: `uv pip install <package>`
+- Editable install: `uv pip install -e .`
+- Multiple packages: `uv pip install package1 package2`
+- Upgrading packages: `uv add package_name>=package_version --upgrade-package package_name`
+- Never use bare `pip` commands
+- `uv` is faster and more reliable than pip for this project
+
+SAFETY & ERROR HANDLING
+
+- Never suggest destructive commands without confirmation
+- Validate API usage against latest documentation
+- Do not expose secrets, credentials, or tokens in code
+
+PHI PROTECTION
+
+This project processes medical imaging data. Protected Health Information (PHI) must never
+be transmitted to external services, including MCP servers configured in .vscode/mcp.json.
+
+- Never include PHI in tool queries sent to external MCP servers
+- PHI includes: patient names, MRNs, accession numbers, dates of birth, addresses,
+  phone numbers, Social Security numbers, and any other HIPAA-defined identifiers
+- When formulating search queries for external documentation servers, use generic
+  placeholders (e.g., "accession number" instead of an actual value)
+- If the user pastes PHI in the chat, do not echo it in tool queries
+- Safe test values: The accession numbers "TEST" and "TESTING" exist on the server
+  and contain no PHI. These are safe to use in examples and testing.
+
+GIT
+
+- Avoid suggesting git commands that modify history (rebase, reset, amend) without explicit user confirmation.
+
+COMMIT MESSAGES
+
+Use Conventional Commits format for all commit messages. This format is parsed by
+python-semantic-release to determine version bumps automatically.
+
+Format: <type>[optional scope]: <description>
+
+Types that trigger releases:
+- feat: A new feature (triggers MINOR version bump, e.g., 1.0.0 -> 1.1.0)
+- fix: A bug fix (triggers PATCH version bump, e.g., 1.0.0 -> 1.0.1)
+- perf: A performance improvement (triggers PATCH version bump)
+
+Types that do NOT trigger releases:
+- chore: Maintenance tasks, dependency updates
+- docs: Documentation changes
+- refactor: Code refactoring without behavior change
+- style: Formatting, whitespace changes
+- test: Adding or updating tests
+- ci: CI/CD configuration changes
+- build: Build system changes
+
+Breaking changes (trigger MAJOR version bump, e.g., 1.0.0 -> 2.0.0):
+- Add ! after type: feat!: remove deprecated API
+- Or add BREAKING CHANGE: footer in commit body
+
+Examples:
+- feat: add new DICOM anonymization option
+- fix(pipeline): handle missing patient ID gracefully
+- docs: update workflow documentation
+- feat!: change CLI argument format
+- fix: resolve memory leak in image processing
+
+  BREAKING CHANGE: The --format flag now requires explicit value
+
+FINALLY
+
+Provide short, concise summaries without the use of emoji when completing a large task.

dicom_dre-1.0.0/.github/instructions/dicom-io.instructions.md

@@ -0,0 +1,25 @@
+---
+description: Reading and writing DICOM with pydicom
+applyTo: "src/dicom_dre/**/*.py"
+---
+
+# DICOM I/O Conventions
+
+## Process-wide pydicom config
+
+Any module that reads or writes DICOM with pydicom (`dcmread`, `dcmwrite`,
+`save_as`, `Dataset` I/O) depends on the global settings in
+`dicom_dre.pydicom_config`, which make reads tolerant of malformed
+production data.
+
+- The settings are process-global: one import applies them everywhere, so the
+  import only has to run before the first read or write in the process.
+- Add the side-effect import to any new DICOM reader/writer whose module (or its
+  import chain) does not already reach it:
+
+  ```python
+  import dicom_dre.pydicom_config  # noqa: F401  applies process-wide pydicom config
+  ```
+
+- Modules that import the pipeline (`dicom_dre.pipeline`) or an anonymizer entry
+  module already inherit it transitively and do not need the direct import.

dicom_dre-1.0.0/.github/instructions/docs.instructions.md

@@ -0,0 +1,84 @@
+---
+description: Writing documentation in docs/
+applyTo: "docs/**/*.md, README.md"
+---
+
+# Writing Documentation in dicom-dre
+
+Rules for writing and editing Markdown documentation under `docs/`. Favor the
+reader: a clear page is more likely to be correct, cheaper to change, and safe
+to reuse. Clarity is the primary goal; the rules below serve it.
+
+## Voice and Style
+
+- Write as dry as an IEEE or NIST specification: factual, declarative, and
+  impersonal. State facts and requirements; omit motivation, praise, and asides.
+- Use present tense and the active voice ("The engine hashes the value", not
+  "The value is hashed by the engine").
+- Prefer verbs and concrete nouns over adjectives.
+- Omit marketing and promotional words (for example efficient, powerful, robust,
+  seamless, comprehensive, advanced).
+- Omit claims you cannot verify from the code or tests.
+
+## What to Include
+
+- State what a component does, not what it does not do. Avoid negative-space
+  descriptions that contrast with an alternative or a prior design (for example
+  "handled here rather than in the parent", "not passed to X"); these are
+  usually refactoring artifacts. Keep a negative statement only when it conveys
+  critical information the reader cannot infer, such as a safety constraint.
+- Omit self-evident or trivially true statements. Do not state facts the reader
+  can infer or that hold by construction (for example "this module has no
+  dependencies so it avoids an import cycle"). Write only what is non-obvious
+  and consequential.
+
+## Terminology and Verbs
+
+- Name the actual mechanism, not an analogy. Do not use metaphor or
+  anthropomorphism: data does not "travel", "live", "ship", "flow", or get
+  "baked in"; objects do not "carry", "own", "want", or "know" anything.
+- Use precise verbs for the operation:
+  - storage or location: "is stored in", "is held in", "resides in".
+  - fixed at construction: "is fixed at construction", "is set once at
+    construction time".
+  - cross-process transfer: "is serialized to", "is pickled and sent to", "is
+    passed to". State that it crosses the process boundary when relevant.
+  - occurrence or scope: "occurs", "is performed", "is scoped to".
+- Prefer terms of art already used in the codebase: serialization,
+  immutability, process boundary, construction time, apply time, deterministic
+  derivation, closure.
+- Prohibited terms and replacements: "baked" -> "fixed"/"set at construction";
+  "knobs" -> "settings"/"options"/"parameters"; "lives" -> "is stored"/
+  "resides"/"occurs"; "travel"/"ship" -> "is serialized"/"is sent"/"is passed";
+  "carries" -> "holds"/"contains".
+
+## Punctuation
+
+- Do not use em-dashes (`--` or the Unicode em-dash). Rephrase into separate
+  sentences, or use a colon, comma, or parentheses.
+- Do not use en-dashes for ranges in prose. Write "10 to 30", not "10-30".
+
+## Conciseness
+
+- Keep sentences short. Prefer several plain sentences over one long clause.
+- Cut filler and hedging (for example "in order to", "it is important to note
+  that", "basically", "simply").
+- Make each point once. One idea per sentence; one topic per paragraph.
+
+## Formatting
+
+- Wrap prose at roughly 88 columns to match the source line length.
+- Wrap element names, keywords, parameters, and file paths in backticks
+  (`PatientID`, `HASH_SALT`, `~/.config/dicom-dre/salt`).
+- Use fenced code blocks with a language hint for commands and code.
+- Use relative Markdown links between docs pages
+  (`[Reproducibility](reproducibility.md)`).
+- Do not use emoji.
+
+## Accuracy
+
+- Keep documentation synchronized with the code. When behavior changes, update
+  the affected pages in the same change.
+- Verify CLI flags, parameter names, and defaults against the actual source and
+  `--help` output before documenting them.
+- When adding a new page, add it to the `nav`/`toctree` so it is reachable.