Release Notes: pycemrg v1.0.0
The initial release of pycemrg establishes a standardized, configuration-driven foundation for cardiac medical image analysis workflows. This library provides the core utilities necessary for building reproducible imaging pipelines, prioritizing stateless logic and explicit path management.
Core Functionality
Model Management and Integrity
pycemrg automates the lifecycle of machine learning models within research pipelines.
- Automated Retrieval: Handles the downloading and local caching of model weights.
- Integrity Verification: Uses SHA256 checksums to ensure data consistency and prevent the use of corrupted artifacts.
- Versioning: Supports a versioned manifest system, allowing researchers to switch between model iterations without modifying source code.
Anatomical Label Management
The LabelManager provides a centralized interface for mapping anatomical structures to their respective integer values in segmentation masks.
- Translation: Facilitates bidirectional mapping between human-readable strings and numerical data.
- Hierarchical Grouping: Supports recursive definitions (e.g., grouping "LV_myo" and "RV_myo" under "ventricles") to simplify multi-label operations.
- CLI Compatibility: Generates formatted tag strings for seamless integration with external command-line tools.
Validated Command Execution
The library includes a specialized CommandRunner designed to wrap external scientific software, such as openCARP and meshtool.
- Post-Execution Validation: Verifies the existence of expected output files, raising exceptions immediately upon failure.
- Error Filtering: Allows for the definition of ignorable stderr patterns, such as deprecation warnings, to prevent false-positive failures in legacy environments.
Configuration Scaffolding
To encourage standardization, the package includes a CLI tool for generating template YAML configurations for both labels and model manifests.
Design Philosophy and Architecture
This release adheres to a strict set of architectural principles to ensure long-term maintainability:
- Stateless Logic: Internal modules do not maintain hidden state; all dependencies and configurations are injected at runtime.
- Explicit Path Management: The library avoids "magic" or relative path resolution. All input and output paths must be explicitly provided by the orchestrating workflow.
- Contract-Driven Development: Complex data structures are managed via formal dataclass contracts, ensuring interface stability across the
pycemrgsuite.
Ecosystem Integration
pycemrg serves as the foundational dependency for the broader cardiac imaging ecosystem, including:
- pycemrg-image-analysis: Segmentation and meshing workflows.
- pycemrg-model-creation: Coordinate systems and mesh generation.
- pycemrg-interpolation: Functional autoencoder utilities.
Installation and Documentation
The package is available for Python 3.8+ and can be installed via pip:
pip install pycemrg
For comprehensive implementation details, please refer to the API Reference and the Architecture Guidelines.