Skip to content

Commit 4a6545c

Browse files
author
Jose Alonso Solis Lemus
committed
prep_release
1 parent 938b883 commit 4a6545c

3 files changed

Lines changed: 228 additions & 9 deletions

File tree

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Cardio Electro Mechanics Research Group
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,169 @@
11
# pycemrg
2+
3+
Core utilities for cardiac medical image analysis workflows.
4+
5+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6+
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
7+
8+
## Overview
9+
10+
`pycemrg` provides a stateless, configuration-driven foundation for building reproducible medical imaging pipelines. It handles common tasks like model versioning, anatomical label translation, path management, and safe command execution—letting you focus on scientific workflows rather than boilerplate.
11+
12+
**Design Philosophy:** Libraries provide stateless logic; orchestrators handle I/O. All paths are explicit, no magic configuration, no hidden state.
13+
14+
## Features
15+
16+
- **Model Management**: Download, cache, and version ML models with SHA256 integrity verification
17+
- **Label Management**: Translate between human-readable anatomical names and integer segmentation values
18+
- **Path Management**: Generate consistent output paths with configurable prefix/suffix patterns
19+
- **Command Execution**: Safely run external tools (meshtool, openCARP) with validation and error handling
20+
- **Configuration Scaffolding**: Generate template YAML configs via CLI or programmatic API
21+
- **CARPentry Integration**: Specialized runner for openCARP ecosystem with environment isolation
22+
23+
## Installation
24+
```bash
25+
pip install pycemrg
26+
```
27+
28+
## Quick Start
29+
30+
### Generate Configuration Templates
31+
```bash
32+
# Create a labels configuration template
33+
pycemrg init-labels --output config/labels.yaml --num-labels 10
34+
35+
# Create a models configuration template
36+
pycemrg init-models --output config/models.yaml
37+
```
38+
39+
### Manage Anatomical Labels
40+
```python
41+
from pycemrg.data import LabelManager
42+
43+
# Load your anatomical label definitions
44+
labels = LabelManager("config/labels.yaml")
45+
46+
# Translate between names and integer values
47+
lv_value = labels.get_value("LV_myo") # Returns: 2
48+
49+
# Resolve groups (including recursive definitions)
50+
chamber_values = labels.get_values_from_names(["ventricles", "atria"])
51+
# Returns: [2, 3, 4, 5] (sorted, deduplicated)
52+
53+
# Generate tag strings for command-line tools
54+
tags = labels.get_tags_string(["LV_myo", "RV_myo"]) # Returns: "2,3"
55+
```
56+
57+
**Example `labels.yaml`:**
58+
```yaml
59+
labels:
60+
LV_myo: 2
61+
RV_myo: 3
62+
LA_wall: 4
63+
RA_wall: 5
64+
65+
groups:
66+
ventricles:
67+
- LV_myo
68+
- RV_myo
69+
atria:
70+
- LA_wall
71+
- RA_wall
72+
```
73+
74+
### Manage ML Models
75+
```python
76+
from pycemrg.models import ModelManager
77+
78+
# Initialize with your models manifest
79+
models = ModelManager("config/models.yaml")
80+
81+
# Get path to model weights (downloads/caches automatically)
82+
model_path = models.get_model_path("segmentation_model")
83+
# First call: Downloads, verifies SHA256, extracts → ~/.cache/pycemrg/...
84+
# Subsequent calls: Returns cached path instantly
85+
86+
# Use specific version
87+
legacy_path = models.get_model_path("segmentation_model", version="v1.0")
88+
```
89+
90+
**Example `models.yaml`:**
91+
```yaml
92+
segmentation_model:
93+
default: v2.0
94+
versions:
95+
v2.0:
96+
url: "https://example.com/models/seg_v2.0.zip"
97+
sha256: "abc123..."
98+
unzipped_target_path: "checkpoints/model.pth"
99+
```
100+
101+
### Execute Commands Safely
102+
```python
103+
from pycemrg.system import CommandRunner
104+
105+
runner = CommandRunner()
106+
107+
# Run with output validation
108+
runner.run(
109+
cmd=['meshtool', 'extract', 'mesh', '-msh=heart'],
110+
expected_outputs=[Path('heart_epi.surf')]
111+
)
112+
113+
# Handle tools that write warnings to stderr
114+
runner.run(
115+
cmd=['legacy_tool', '--process', 'data.txt'],
116+
ignore_errors=["WARNING: deprecated flag"]
117+
)
118+
```
119+
120+
## Documentation
121+
122+
- [API Reference](docs/API_reference.md) - Complete API documentation
123+
- [Architecture Guidelines](docs/pycemrg_suite_guidelines.txt) - Design principles and patterns
124+
125+
## Related Packages
126+
127+
`pycemrg` is the stable core of a suite of cardiac imaging tools:
128+
129+
- **pycemrg-image-analysis**: Medical image processing workflows (segmentation, meshing)
130+
- **pycemrg-model-creation**: Cardiac mesh generation and UVC coordinate systems
131+
- **pycemrg-interpolation**: Functional autoencoder-based image interpolation
132+
133+
## Development
134+
135+
### Local Installation
136+
```bash
137+
# Clone and install in editable mode
138+
git clone https://github.com/YOUR-ORG/pycemrg.git
139+
cd pycemrg
140+
pip install -e ".[dev]"
141+
142+
# Run tests
143+
pytest tests/
144+
```
145+
146+
### Contributing
147+
148+
This library follows strict architectural principles:
149+
- **Stateless logic**: No hidden state, all dependencies injected
150+
- **Contract-driven**: Complex workflows use dataclass contracts
151+
- **Path-agnostic**: Libraries never derive paths; orchestrators provide them explicitly
152+
153+
See [Architecture Guidelines](docs/pycemrg_suite_guidelines.txt) for details.
154+
155+
## License
156+
157+
MIT License - See [LICENSE](LICENSE) file for details.
158+
159+
## Citation
160+
161+
If you use `pycemrg` in your research, please cite:
162+
```bibtex
163+
@software{pycemrg2025,
164+
title = {pycemrg: Core utilities for cardiac medical image analysis},
165+
author = {[Your Name]},
166+
year = {2025},
167+
url = {https://github.com/YOUR-ORG/pycemrg}
168+
}
169+
```

‎pyproject.toml‎

Lines changed: 39 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,28 +6,58 @@ build-backend = "setuptools.build_meta"
66
name = "pycemrg"
77
version = "0.1.0"
88
authors = [
9-
{ name="Your Name", email="your.email@example.com" },
9+
{ name="Jose Alonso Solis-Lemus", email="j.solis-lemus@imperial.ac.uk" },
1010
]
11-
description = "Core ML and file management utilities for medical imaging research."
11+
description = "Core utilities for cardiac medical image analysis workflows"
1212
readme = "README.md"
1313
license = { file="LICENSE" }
1414
requires-python = ">=3.8"
15+
16+
keywords = [
17+
"cardiac",
18+
"medical-imaging",
19+
"cardiac-mri",
20+
"image-analysis",
21+
"mesh-generation",
22+
"research-tools",
23+
]
24+
1525
classifiers = [
26+
"Development Status :: 4 - Beta",
27+
"Intended Audience :: Science/Research",
28+
"Intended Audience :: Healthcare Industry",
29+
"Topic :: Scientific/Engineering :: Medical Science Apps.",
30+
"Topic :: Scientific/Engineering :: Image Processing",
1631
"Programming Language :: Python :: 3",
32+
"Programming Language :: Python :: 3.8",
33+
"Programming Language :: Python :: 3.9",
34+
"Programming Language :: Python :: 3.10",
35+
"Programming Language :: Python :: 3.11",
1736
"License :: OSI Approved :: MIT License",
1837
"Operating System :: OS Independent",
1938
]
39+
2040
dependencies = [
21-
"pyyaml>=6.0",
22-
"requests>=2.28",
23-
"tqdm>=4.64",
24-
"click>=8.0",
25-
'importlib-resources; python_version < "3.9"'
41+
"pyyaml>=6.0,<7.0",
42+
"click>=8.0,<9.0",
43+
"tqdm>=4.64,<5.0",
44+
'importlib-resources>=5.0,<6.0; python_version < "3.9"',
45+
]
46+
47+
[project.optional-dependencies]
48+
dev = [
49+
"pytest>=7.0",
50+
"pytest-cov>=4.0",
51+
"build>=0.10",
52+
"twine>=4.0",
2653
]
2754

2855
[project.urls]
29-
Homepage = "https://github.com/your-org/pycemrg"
30-
"Bug Tracker" = "https://github.com/your-org/pycemrg/issues"
56+
Homepage = "[Keep your GitHub URL from current file]"
57+
Documentation = "[Your GitHub URL]/blob/main/docs/API_reference.md"
58+
Repository = "[Keep your GitHub URL from current file]"
59+
"Bug Tracker" = "[Your GitHub URL]/issues"
60+
Changelog = "[Your GitHub URL]/releases"
3161

3262
[tool.setuptools.packages.find]
3363
where = ["src"]

0 commit comments

Comments
 (0)