dicomforge 0.6.0__tar.gz

dicomforge-0.6.0/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep -E \"\\\\.\\(py|toml|txt|cfg|ini|md|yml|yaml\\)$|Makefile|^.*\\\\.github.*$\")",
+      "Bash(PYTHONPATH=src python3 -m unittest discover -v)",
+      "Bash(python3 -m compileall -q src tests)",
+      "Bash(PYTHONPATH=src python3 -W error::DeprecationWarning -m unittest)",
+      "Bash(PYTHONPATH=src python3 -m unittest)"
+    ]
+  }
+}

dicomforge-0.6.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        run: python -m pip install -e ".[dev]"
+      - name: Unit tests
+        run: PYTHONPATH=src python -m unittest
+      - name: Compile check
+        run: PYTHONPATH=src python -m compileall -q src tests

dicomforge-0.6.0/.gitignore

@@ -0,0 +1,17 @@
+.DS_Store
+.pycache/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+
+#documentation
+paper.md
+paper.bib
+citation.cff
+

dicomforge-0.6.0/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Changelog
+
+All notable changes to DicomForge are documented here.
+Versions follow [Semantic Versioning](https://semver.org/).
+
+## [0.6.0] — 2026-05-05
+
+### Added
+- `dicomforge.adapt` — adoption-layer integration adapters:
+  - `from_pydicom` / `to_pydicom` — bidirectional pydicom Dataset conversion
+  - `pixel_array` — numpy array from uncompressed PixelData with correct dtype
+  - `to_pil_image` — PIL Image with automatic VOI windowing and MONOCHROME1 inversion
+  - `to_json` / `from_json` — DICOM JSON Model round-trip
+  - `from_pynetdicom_event` — extract DicomDataset from a pynetdicom event
+- `dicomforge.api` — high-level convenience API:
+  - `DicomFile` — lazy-loading file wrapper with named property access for 30+ tags
+  - `quick_anonymize` — read → de-identify → write in one call
+  - `validate_dataset` — structural validation with human-readable issue list
+  - `batch_anonymize` — anonymize a file list; partial failures are isolated
+- 55 additional `Tag` keywords (SeriesNumber, BodyPartExamined, PixelSpacing,
+  ImagePositionPatient, Manufacturer, AttendingPhysicianName, and more)
+- 20+ additional `SopClassUID` constants (PET, NM, US, RT, SR, WSI, enhanced CT/MR)
+- 6 additional `TransferSyntaxUID` constants (JPEG 2000 lossy, JPEG-LS near-lossless,
+  HT-JPEG 2000 lossless and lossy)
+- 6 additional registered `TransferSyntax` entries
+- `network` and `all` optional dependency extras in `pyproject.toml`
+- `DicomDataset.copy()` and `DicomDataset.__repr__`
+- `Tag.__repr__` returns keyword name when available (e.g. `Tag.PatientName`)
+
+### Changed
+- `AnonymizationPlan.starter_profile` expanded from 27 to 48 de-identification rules,
+  adding patient weight/size/comments, ethnic group, smoking/pregnancy status,
+  attending/requesting physician, device serial number, and department name
+- `UidRemapper` is now thread-safe (internal cache protected by `threading.Lock`)
+- `UidRemapper` now also remaps `MediaStorageSOPInstanceUID` and `ReferencedSOPInstanceUID`
+- `default_registry()` now returns a cached singleton instead of a new instance per call
+- `io.write` prefers `pydicom.dcmwrite()` on pydicom ≥ 3.0 (avoids deprecation warning)
+- Network `_read_message` and `_write_message` now enforce a 30-second timeout and a
+  64 MiB maximum message size
+- All public pixel helper functions (`rescale_values`, `is_monochrome`, `voi_window_bounds`,
+  `apply_voi_window_from_dataset`, etc.) are now exported from `dicomforge` top level
+- `pyproject.toml` version bumped to 0.6.0; development status promoted to Beta
+
+### Fixed
+- `assert_pixel_data_length` incorrectly validated the last byte of even-length
+  pixel data as a padding byte, causing `PixelMetadataError` for any dataset
+  whose last pixel value was non-zero
+
+---
+
+## [0.5.0] — 2025-01-01
+
+### Added
+- `dicomforge.dicomweb` — dependency-free DICOMweb client:
+  - QIDO-RS query builder (`QidoQuery`)
+  - WADO-RS study/series/instance retrieval
+  - STOW-RS multipart upload
+  - DICOM JSON Model conversion (`dataset_from_dicom_json`, `dataset_to_dicom_json`)
+  - `parse_multipart_related` / `build_multipart_related`
+  - Injectable `DicomwebTransport` protocol with stdlib `UrllibDicomwebTransport`
+- `dicomforge.network` — async DIMSE-style services:
+  - `Association` client with C-ECHO, C-FIND, C-MOVE, C-STORE
+  - `DimseServer` SCP with backpressure-aware C-STORE queue
+  - `open_association` / `start_dimse_server` convenience helpers
+  - `AssociationRejectedError`, `AssociationClosedError`
+- DICOMweb integration: `dataset_to_message` / `dataset_from_message` with
+  base64-encoded binary and nested dataset support
+
+---
+
+## [0.4.0] — 2024-10-01
+
+### Added
+- `dicomforge.network` initial implementation (async association lifecycle,
+  C-ECHO, JSON framing)
+- `DimseStatus` with class-level constants (SUCCESS, PENDING, CANCEL, UNABLE_TO_PROCESS)
+- `AssociationRequest` frozen dataclass
+
+---
+
+## [0.3.0] — 2024-07-01
+
+### Added
+- `dicomforge.anonymize` — de-identification engine:
+  - `AnonymizationPlan` with `starter_profile()` and `basic_profile()` factory methods
+  - `UidRemapper` with SHA-256 deterministic remapping
+  - `AnonymizationReport` / `AnonymizationEvent` audit trail
+  - `PrivateTagAction` (REMOVE / KEEP)
+  - Recursive sequence processing
+
+---
+
+## [0.2.0] — 2024-04-01
+
+### Added
+- `dicomforge.pixels` — pixel metadata and safety layer:
+  - `FrameMetadata` with `from_dataset` and eager validation
+  - `check_pixel_capability` — metadata + codec pre-flight check
+  - `PixelCapability`, `VoiLut`
+  - `rescale_value`, `apply_voi_window`, photometric interpretation helpers
+- `dicomforge.io` — optional pydicom read/write backend
+
+---
+
+## [0.1.0] — 2024-01-01
+
+### Added
+- `dicomforge.tags` — `Tag` frozen dataclass with keyword registry and multi-format parser
+- `dicomforge.dataset` — `DicomDataset` (MutableMapping with tag normalization)
+- `dicomforge.transfer_syntax` — `TransferSyntax` registry with safe unknown defaults
+- `dicomforge.codecs` — `CodecRegistry` and `Codec` capability model
+- `dicomforge.errors` — `DicomForgeError` hierarchy
+- `dicomforge.uids` — `SopClassUID`, `TransferSyntaxUID`, `ImplementationUID`, `DimseStatusCode`
+- CI matrix: Python 3.9–3.13 on GitHub Actions
+- MIT license, CONTRIBUTING.md, SECURITY.md, architecture and conformance docs

dicomforge-0.6.0/CITATION.cff

@@ -0,0 +1,38 @@
+cff-version: 1.2.0
+message: "If you use DicomForge in your research, please cite it as below."
+type: software
+title: "DicomForge: A Lightweight Python Toolkit for Typed DICOM Processing and Medical Imaging Workflows"
+version: 0.6.0
+date-released: "2026-05-05"
+license: MIT
+repository-code: "https://github.com/dicomforge/dicomforge"
+url: "https://github.com/dicomforge/dicomforge"
+abstract: >-
+  DicomForge is a typed, dependency-free Python library for DICOM processing.
+  It provides tag normalization, transfer syntax classification, pixel metadata
+  validation, auditable de-identification with deterministic UID remapping,
+  DICOMweb client helpers, and an adoption layer for pydicom, NumPy, and Pillow
+  integration — designed for both hobby medical imaging projects and commercial
+  production software.
+keywords:
+  - DICOM
+  - medical imaging
+  - radiology
+  - de-identification
+  - DICOMweb
+  - healthcare
+  - Python
+authors:
+  - family-names: Merchant
+    given-names: Mustufa
+    affiliation: "Kub Technologies Inc."
+preferred-citation:
+  type: article
+  title: "DicomForge: A Lightweight Python Toolkit for Typed DICOM Processing and Medical Imaging Workflows"
+  authors:
+    - family-names: Merchant
+      given-names: Mustufa
+      affiliation: "Kub Technologies Inc."
+  journal: "Journal of Open Source Software"
+  year: 2026
+  url: "https://github.com/dicomforge/dicomforge"

dicomforge-0.6.0/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+Thank you for helping make DICOMForge safer and more useful.
+
+## Development Setup
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e ".[dev]"
+PYTHONPATH=src python -m unittest
+```
+
+## Project Rules
+
+- Keep the core package dependency-light.
+- Prefer explicit DICOM boundaries over claiming unsupported conformance.
+- Add tests for every user-visible behavior change.
+- Do not commit real patient data or DICOM files containing PHI.
+- Prefer small, focused modules over broad abstractions.
+
+## DICOM Changes
+
+When adding DICOM behavior, include one of:
+
+- a reference to the DICOM part/table used
+- a test that captures the expected behavior
+- documentation in `docs/conformance.md` explaining the current boundary
+
+Full clinical conformance work should also update the compatibility matrix and
+conformance notes.

dicomforge-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DICOMForge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dicomforge-0.6.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: dicomforge
+Version: 0.6.0
+Summary: A lightweight, typed Python DICOM processing toolkit for medical imaging.
+Project-URL: Homepage, https://github.com/dicomforge/dicomforge
+Project-URL: Repository, https://github.com/dicomforge/dicomforge
+Project-URL: Documentation, https://github.com/dicomforge/dicomforge/tree/main/docs
+Project-URL: Issues, https://github.com/dicomforge/dicomforge/issues
+Author: DICOMForge contributors
+License: MIT License
+        
+        Copyright (c) 2026 DICOMForge contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: dicom,healthcare,medical-imaging,pacs,radiology
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.9
+Provides-Extra: all
+Requires-Dist: numpy>=1.23; extra == 'all'
+Requires-Dist: pillow>=10; extra == 'all'
+Requires-Dist: pydicom>=2.4; extra == 'all'
+Requires-Dist: pynetdicom>=2.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: numpy>=1.23; extra == 'dev'
+Requires-Dist: pillow>=10; extra == 'dev'
+Requires-Dist: pydicom>=2.4; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: network
+Requires-Dist: pynetdicom>=2.0; extra == 'network'
+Provides-Extra: pixels
+Requires-Dist: numpy>=1.23; extra == 'pixels'
+Requires-Dist: pillow>=10; extra == 'pixels'
+Provides-Extra: pydicom
+Requires-Dist: pydicom>=2.4; extra == 'pydicom'
+Description-Content-Type: text/markdown
+
+# DICOMForge
+
+DICOMForge is a Python DICOM processing library for medical imaging
+applications. The goal is a lightweight core with typed, predictable APIs,
+explicit safety boundaries, and optional integrations for heavier work such as
+pixel codecs, wire-compatible networking, and DICOMweb.
+
+This repository is intentionally starting with a small, solid core:
+
+- typed tags and value access
+- transfer syntax classification
+- pluggable codec registry
+- de-identification profiles, deterministic UID remapping, and audit reports
+- pixel metadata and safety checks
+- VOI window, rescale, and photometric interpretation helpers
+- async networking primitives for association lifecycle and DIMSE-style commands
+- DICOMweb query, retrieval, upload, and multipart helpers
+- optional `pydicom` IO backend
+- standard-library tests
+
+## Why another DICOM library?
+
+The adoption target is not just feature count. The library should feel safe for
+production teams and approachable for new medical-imaging developers.
+
+Design priorities:
+
+- **Small import surface:** core imports should not pull in NumPy, Pillow, codec
+  wheels, or networking stacks.
+- **Typed access:** avoid stringly-typed dataset code where common attributes can
+  be accessed predictably.
+- **Explicit codec model:** make unsupported transfer syntaxes visible before a
+  transcoding job fails halfway through.
+- **Lazy IO:** support large studies and multi-frame objects without forcing
+  full pixel loading.
+- **Character-set correctness:** treat text encoding as a first-class concern.
+- **Concurrency-safe services:** design networking and DICOMweb APIs around
+  explicit lifecycle and backpressure.
+- **Good errors:** explain the DICOM concept, the offending tag, and the next
+  action where possible.
+
+See [docs/architecture.md](docs/architecture.md) and
+[docs/roadmap.md](docs/roadmap.md). Current implementation boundaries are
+tracked in [docs/conformance.md](docs/conformance.md). For repository naming
+and discoverability notes, see [docs/branding.md](docs/branding.md).
+
+## Commercial Readiness
+
+DICOMForge is MIT licensed and designed for commercial use as a developer
+library. It is not a medical device, diagnostic application, complete PS3.15
+de-identification engine, or wire-compatible DIMSE implementation. See
+[docs/safety.md](docs/safety.md), [docs/conformance.md](docs/conformance.md),
+and [docs/compatibility.md](docs/compatibility.md) before using it in regulated
+clinical workflows.
+
+## When To Use It
+
+Use DICOMForge when you need:
+
+- typed, dependency-light DICOM metadata handling
+- pixel metadata validation before decoding or processing
+- de-identification planning with deterministic UID remapping and audit reports
+- pydicom-backed file IO behind a smaller application API
+- DICOMweb URL/query, DICOM JSON, STOW multipart, and response parsing helpers
+- async lifecycle and backpressure primitives for DICOM-like service design
+
+Do not use DICOMForge as the only component for:
+
+- diagnostic interpretation or medical-device behavior
+- legal de-identification approval without site policy and human review
+- direct DIMSE/PACS interoperability over the DICOM Upper Layer
+- full-fidelity DICOM editing that requires every VR, character set, and IOD rule
+- replacing pydicom, pynetdicom, or integration-tested PACS/VNA validation
+
+## Architecture At A Glance
+
+```text
+dicomforge.tags            typed tag parsing and common keyword constants
+dicomforge.dataset         lightweight mutable dataset wrapper
+dicomforge.transfer_syntax transfer syntax classification
+dicomforge.codecs          codec capability registry
+dicomforge.pixels          pixel metadata safety checks and small value helpers
+dicomforge.anonymize       starter de-identification plans and audit reports
+dicomforge.io              optional pydicom read/write adapter
+dicomforge.network         async command lifecycle primitives, not DICOM UL PDUs
+dicomforge.dicomweb        QIDO/WADO/STOW helpers with injectable HTTP transport
+```
+
+## API Stability
+
+DICOMForge is pre-1.0. Public APIs are intended to be small and stable, but
+breaking changes may happen while the library moves toward a 1.0 adoption bar.
+Breaking changes should be documented in release notes and paired with migration
+guidance.
+
+## Quick Start
+
+```python
+from dicomforge import DicomDataset, Tag, TransferSyntax
+
+ds = DicomDataset()
+ds.set(Tag.PatientName, "Anonymous")
+ds.set(Tag.Modality, "CT")
+
+syntax = TransferSyntax.from_uid("1.2.840.10008.1.2.1")
+assert syntax.is_little_endian
+assert syntax.is_explicit_vr
+```
+
+Optional pydicom-backed reading:
+
+```python
+from dicomforge.io import read
+
+dataset = read("image.dcm", stop_before_pixels=True)
+print(dataset.get("PatientName"))
+```
+
+Basic de-identification:
+
+```python
+from dicomforge import AnonymizationPlan, DicomDataset, PrivateTagAction
+
+dataset = DicomDataset(
+    {
+        "PatientName": "Ada Lovelace",
+        "PatientID": "MRN-123",
+        "StudyInstanceUID": "1.2.826.0.1.3680043.8.498.1",
+        (0x0011, 0x1001): "private vendor value",
+    }
+)
+
+plan = AnonymizationPlan.starter_profile(
+    uid_salt="project-specific-secret",
+    private_tag_action=PrivateTagAction.REMOVE,
+)
+report = plan.apply_with_report(dataset)
+
+assert dataset.get("PatientName") == "Anonymous"
+assert dataset.get("PatientIdentityRemoved") == "YES"
+assert report.private_tags_removed == 1
+```
+
+Async networking:
+
+```python
+from dicomforge.network import DimseServer, open_association
+
+async with DimseServer(ae_title="LOCAL-SCP") as server:
+    async with await open_association(
+        "127.0.0.1",
+        server.bound_port,
+        called_ae_title="LOCAL-SCP",
+    ) as association:
+        status = await association.c_echo()
+        assert status.is_success
+```
+
+DICOMweb query building:
+
+```python
+from dicomforge.dicomweb import DicomwebClient, QidoQuery, UrllibDicomwebTransport
+
+client = DicomwebClient(
+    "https://pacs.example/dicomweb",
+    UrllibDicomwebTransport(timeout=10),
+)
+studies = client.search_studies(QidoQuery().patient_id("MRN-123").modality("CT"))
+```
+
+## De-identification Scope
+
+DICOMForge implements a practical, conservative subset of the DICOM PS3.15
+Basic Application Level Confidentiality Profile for non-pixel attributes:
+common patient, accession, date/time, institution, operator, and UID fields are
+removed, emptied, replaced, or deterministically remapped. Private tag handling
+is explicit and defaults to removal. `remove_private_tags` on `apply` and
+`apply_with_report` remains available as a per-call override for older callers.
+
+This is a software library, not a compliance certificate. Production use should
+pair it with site-specific policy, legal review, image pixel review, and a risk
+assessment for the data release context.
+
+## Development
+
+Run the standard-library test suite:
+
+```bash
+PYTHONPATH=src python3 -m unittest
+```
+
+Optional checks used by maintainers when development dependencies are installed:
+
+```bash
+python -m ruff check src tests
+python -m mypy src/dicomforge
+python -m compileall -q src tests
+```
+
+Examples live in [examples](examples).
+
+For a fuller commercial workflow, see
+[examples/end_to_end_workflow.py](examples/end_to_end_workflow.py).
+
+## License
+
+DICOMForge is distributed under the MIT License for personal and commercial
+use. See [LICENSE](LICENSE).