# MedMask - Medical Image Mask Processing Library
[](https://python.org)
[](LICENSE)
A specialized library for efficient compression, storage, and processing of medical image segmentation masks. Designed to dramatically improve medical image analysis workflow through advanced compression and semantic design.
## 🚀 Key Benefits
- **Ultimate Compression**: 50+ compression ratio using Zstandard
- **File Management**: 117 files → 1 archive file
- **Performance**: 16x faster read operations
- **Semantic Mapping**: Built-in name-to-label conversion
- **Overlapping Masks**: Multi-granularity organ combinations
- **Lazy Loading**: Memory-efficient on-demand construction
## 📦 Installation
```bash
pip install medmask
```
**Dependencies**: Python 3.8+, numpy, spacetransformer, zstandard
## ⚡ Usage
### Basic Operations
```python
import numpy as np
from medmask import SegmentationMask, MaskArchive, save_mask, load_mask
from spacetransformer import Space
# Create spatial information
space = Space(shape=(64, 192, 192), spacing=(2.5, 1.0, 1.0))
# -----------------------------
# Create mask – two approaches
# -----------------------------
# 1. Complete initialization
liver_data = np.zeros((64, 192, 192), dtype=np.uint8) # (Z,Y,X)
liver_data[20:40, 50:150, 60:140] = 1
mask = SegmentationMask(liver_data, {"liver": 1}, space=space)
# 2. Lazy loading (multiple organs)
combined_mask = SegmentationMask.lazy_init(bit_depth=8, space=space)
combined_mask.add_label(liver_data > 0, label=1, name="liver")
combined_mask.add_label(spleen_data > 0, label=2, name="spleen")
# Query masks
liver_region = mask.get_binary_mask_by_names("liver")
multiple_organs = combined_mask.get_binary_mask_by_names(["liver", "spleen"])
```
### File Operations
```python
# Single mask files (.msk)
medmask.save_mask(mask, "liver.msk")
loaded_mask = medmask.load_mask("liver.msk")
# Equivalent
mask.save('liver.msk')
loaded_mask = SegmentationMask.load('liver.msk')
# Multi-mask archives (.mska) - for collections
archive = MaskArchive("organs.mska", mode="w", space=space)
archive.add_segmask(liver_mask, "liver")
archive.add_segmask(heart_mask, "heart")
# Read from archive
archive = MaskArchive("organs.mska", mode="r")
liver = archive.load_segmask("liver")
all_names = archive.all_names()
```
### Use Cases
**Single Masks**: Individual organ processing, simple storage
**Combined Masks**: Multiple organs in one mask, unified label management
**Archives**: Collections of related masks, overlapping hierarchies (e.g., individual ribs + combined rib groups)
## 📊 Performance Comparison
| Metric | Traditional | MedMask | Improvement |
|--------|-------------|---------|-------------|
| **File Count** | 117 .nii.gz files | 1 .mska file | 117:1 |
| **Storage Size** | 5.12 MB | 92 KB | 56.7:1 |
| **Read Time** | 1.869s | 0.117s | 16.0x |
| **File Management** | Complex | Simple | ✓ |
*Test results based on TotalSegmentator 117-organ segmentation data*
## 📁 Project Structure
```
medmask/
├── core/
│ ├── segmask.py # SegmentationMask class
│ └── mapping.py # LabelMapping class
├── storage/
│ ├── archivefile.py # MaskArchive class
│ └── maskfile.py # MaskFile class
├── compression/
│ └── zstd_codec.py # Compression implementation
└── utils/
└── utils.py # Utility functions
```
## 🧪 Testing
```bash
python -m pytest tests/
```
## 📝 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🤝 Contributing
Issues and Pull Requests are welcome! Please follow the standard GitHub workflow.
---
**MedMask** - Making medical image segmentation mask processing simpler and more efficient!
Raw data
{
"_id": null,
"home_page": null,
"name": "medmask",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "medical-imaging, segmentation, compression, mask-processing",
"author": null,
"author_email": "\"Fastdiag.ai\" <contact@fastdiag.ai>",
"download_url": "https://files.pythonhosted.org/packages/25/2e/bae4812e447721a2e8891462ae7e96c2b0793dd9360f96efbc155fe74e1e/medmask-0.1.3.tar.gz",
"platform": null,
"description": "# MedMask - Medical Image Mask Processing Library\n\n[](https://python.org)\n[](LICENSE)\n\nA specialized library for efficient compression, storage, and processing of medical image segmentation masks. Designed to dramatically improve medical image analysis workflow through advanced compression and semantic design.\n\n## \ud83d\ude80 Key Benefits\n\n- **Ultimate Compression**: 50+ compression ratio using Zstandard\n- **File Management**: 117 files \u2192 1 archive file\n- **Performance**: 16x faster read operations\n- **Semantic Mapping**: Built-in name-to-label conversion\n- **Overlapping Masks**: Multi-granularity organ combinations\n- **Lazy Loading**: Memory-efficient on-demand construction\n\n## \ud83d\udce6 Installation\n\n```bash\npip install medmask\n```\n\n**Dependencies**: Python 3.8+, numpy, spacetransformer, zstandard\n\n## \u26a1 Usage\n\n### Basic Operations\n\n```python\nimport numpy as np\nfrom medmask import SegmentationMask, MaskArchive, save_mask, load_mask\nfrom spacetransformer import Space\n\n# Create spatial information \nspace = Space(shape=(64, 192, 192), spacing=(2.5, 1.0, 1.0))\n\n# -----------------------------\n# Create mask \u2013 two approaches\n# -----------------------------\n# 1. Complete initialization\nliver_data = np.zeros((64, 192, 192), dtype=np.uint8) # (Z,Y,X)\nliver_data[20:40, 50:150, 60:140] = 1\nmask = SegmentationMask(liver_data, {\"liver\": 1}, space=space)\n\n# 2. Lazy loading (multiple organs)\ncombined_mask = SegmentationMask.lazy_init(bit_depth=8, space=space)\ncombined_mask.add_label(liver_data > 0, label=1, name=\"liver\")\ncombined_mask.add_label(spleen_data > 0, label=2, name=\"spleen\")\n\n# Query masks\nliver_region = mask.get_binary_mask_by_names(\"liver\")\nmultiple_organs = combined_mask.get_binary_mask_by_names([\"liver\", \"spleen\"])\n```\n\n### File Operations\n\n```python\n# Single mask files (.msk)\nmedmask.save_mask(mask, \"liver.msk\")\nloaded_mask = medmask.load_mask(\"liver.msk\")\n\n# Equivalent\nmask.save('liver.msk')\nloaded_mask = SegmentationMask.load('liver.msk')\n\n# Multi-mask archives (.mska) - for collections\narchive = MaskArchive(\"organs.mska\", mode=\"w\", space=space)\narchive.add_segmask(liver_mask, \"liver\")\narchive.add_segmask(heart_mask, \"heart\")\n\n# Read from archive\narchive = MaskArchive(\"organs.mska\", mode=\"r\")\nliver = archive.load_segmask(\"liver\")\nall_names = archive.all_names()\n```\n\n### Use Cases\n\n**Single Masks**: Individual organ processing, simple storage\n**Combined Masks**: Multiple organs in one mask, unified label management \n**Archives**: Collections of related masks, overlapping hierarchies (e.g., individual ribs + combined rib groups)\n\n## \ud83d\udcca Performance Comparison\n\n| Metric | Traditional | MedMask | Improvement |\n|--------|-------------|---------|-------------|\n| **File Count** | 117 .nii.gz files | 1 .mska file | 117:1 |\n| **Storage Size** | 5.12 MB | 92 KB | 56.7:1 |\n| **Read Time** | 1.869s | 0.117s | 16.0x |\n| **File Management** | Complex | Simple | \u2713 |\n\n*Test results based on TotalSegmentator 117-organ segmentation data*\n\n## \ud83d\udcc1 Project Structure\n\n```\nmedmask/\n\u251c\u2500\u2500 core/\n\u2502 \u251c\u2500\u2500 segmask.py # SegmentationMask class\n\u2502 \u2514\u2500\u2500 mapping.py # LabelMapping class\n\u251c\u2500\u2500 storage/\n\u2502 \u251c\u2500\u2500 archivefile.py # MaskArchive class\n\u2502 \u2514\u2500\u2500 maskfile.py # MaskFile class\n\u251c\u2500\u2500 compression/\n\u2502 \u2514\u2500\u2500 zstd_codec.py # Compression implementation\n\u2514\u2500\u2500 utils/\n \u2514\u2500\u2500 utils.py # Utility functions\n```\n\n## \ud83e\uddea Testing\n\n```bash\npython -m pytest tests/\n```\n\n## \ud83d\udcdd License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## \ud83e\udd1d Contributing\n\nIssues and Pull Requests are welcome! Please follow the standard GitHub workflow.\n\n---\n\n**MedMask** - Making medical image segmentation mask processing simpler and more efficient! \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Medical Image Mask Compression and Processing Library",
"version": "0.1.3",
"project_urls": null,
"split_keywords": [
"medical-imaging",
" segmentation",
" compression",
" mask-processing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8f6be3319b8ab32d5bbbe202bff4f2851cc6d205e7ace8d13ffb8230f354f42b",
"md5": "bcbf2f7debf6d1b13315862a7663fc19",
"sha256": "d7492fea07ce269e9e238bb4ea5f2fc86ed488112443caa507873e4d7daf1fec"
},
"downloads": -1,
"filename": "medmask-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bcbf2f7debf6d1b13315862a7663fc19",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 19103,
"upload_time": "2025-07-23T08:36:26",
"upload_time_iso_8601": "2025-07-23T08:36:26.313843Z",
"url": "https://files.pythonhosted.org/packages/8f/6b/e3319b8ab32d5bbbe202bff4f2851cc6d205e7ace8d13ffb8230f354f42b/medmask-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "252ebae4812e447721a2e8891462ae7e96c2b0793dd9360f96efbc155fe74e1e",
"md5": "314a53ed823620ea7ca26f119ad421c5",
"sha256": "b99c1f6b70ec0c19a290a2f7cf76d95d9612aee9725d174c6032476822c7af4a"
},
"downloads": -1,
"filename": "medmask-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "314a53ed823620ea7ca26f119ad421c5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 329685,
"upload_time": "2025-07-23T08:36:27",
"upload_time_iso_8601": "2025-07-23T08:36:27.519128Z",
"url": "https://files.pythonhosted.org/packages/25/2e/bae4812e447721a2e8891462ae7e96c2b0793dd9360f96efbc155fe74e1e/medmask-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 08:36:27",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "medmask"
}
JSON