# SpaceTransformer
A Python library for elegant 3D medical image geometric transformations.
## Why SpaceTransformer?
Traditional medical image processing suffers from fragmented coordinate concepts:
- **Frame**: Only captures position/orientation, missing crucial **shape** information
- **NIfTI Affine**: A 4x4 matrix that's hard to interpret - what does each element mean?
- **Manual bookkeeping**: Keeping track of transformations across multiple processing steps
SpaceTransformer introduces the **Space** concept - a complete description of 3D image geometry.
## Key Advantages
### 1. Complete Geometric Description
Unlike traditional "frame" concepts, `Space` fully describes the image sampling grid:
```python
space = Space(
shape=(512, 512, 100), # Complete voxel dimensions
origin=(0.0, 0.0, 0.0), # Physical position
spacing=(0.5, 0.5, 2.0), # Voxel size in mm
x_orientation=(1, 0, 0), # Explicit direction vectors
y_orientation=(0, 1, 0), # No ambiguous matrix interpretation
z_orientation=(0, 0, 1)
)
```
### 2. Expressive Spatial Operations
Describe complex transformations explicitly:
```python
# Chain operations elegantly
transformed_space = (space
.apply_flip(axis=2)
.apply_shape((256, 256, 50))
.apply_bbox(bbox))
```
### 3. Transparent Matrix Interpretation
No more guessing what a 4x4 affine matrix means - direction vectors are explicit.
## Elegant Image Processing
### 1. Worry-Free Multi-Step Pipelines
```python
# Traditional approach: careful bookkeeping required
# crop -> resize -> segmentation -> resize back -> pad back
# SpaceTransformer approach: fully reversible by design
target_space = original_space.apply_bbox(bbox).apply_shape(target_size)
warped_img = warp_image(original_img,
original_space,
target_space,
mode='trilinear',
pad_value=-1000)
# ... process in target_space ...
segment_result = segmodel(warped_img) # hxwxl, int
keypoint_result = keypmodel(warped_img) # nx3, [i,j,k], index coord
# Automatic optimal path back to original_space
original_segment_result = warp_image(segment_result,
target_space,
original_space,
mode='nearest',
pad_value = 0)
original_keypoint_result = warp_point(keypoint_result,
target_space,
original_space) # nx3, index coord
world_keypoint_result = target_space.to_world_transform(keypoint_result) # nx3, [x,y,z], mm
```
### 2. Abstract-Then-Execute Pattern
```python
# Plan transformations (fast, no actual image processing)
target_space = source_space.apply_flip(0).apply_rotate(1, 30, unit="degree").apply_bbox(bbox).apply_shape((256, 256, 128))
# Execute once with optimal path (GPU-accelerated)
result = warp_image(image, source_space, target_space, cuda_device="cuda:0")
```
### 3. GPU-Accelerated & Deep Learning Ready
- PyTorch backend with automatic optimal transformation paths
- No `align_corners` confusion - transformations are mathematically guaranteed reversible
- Seamless integration with deep learning workflows
## Architecture
- **spacetransformer-core**: Pure NumPy implementation for geometric computations
- **spacetransformer-torch**: GPU-accelerated image resampling with PyTorch
## Quick Start
**[View Example Notebook](example/example.ipynb)** - See a practical demonstration of the library's capabilities
```python
import numpy as np
from spacetransformer.core import Space
from spacetransformer.torch import warp_image
# Create image space
space = Space(
shape=(512, 512, 100),
spacing=(1.0, 1.0, 2.0),
origin=(0, 0, 0)
)
# Define target transformation
target_space = space.apply_flip(axis=2).apply_shape((256, 256, 50))
# Apply to image (GPU-accelerated)
transformed_image = warp_image(
image, space, target_space,
pad_value=0, cuda_device="cuda:0"
)
```
## Format Support
- **NIfTI**: `Space.from_nifti(nifti_image)`
- **SimpleITK**: `Space.from_sitk(sitk_image)`
## Installation
```bash
pip install spacetransformer-core # Core functionality
pip install spacetransformer-torch # GPU acceleration
```
## Requirements
- **Core**: Python ≥3.8, NumPy ≥1.20
- **Torch**: PyTorch ≥1.12 (spacetransformer-torch)
---
*SpaceTransformer: Making 3D medical image transformations as elegant as they should be.*
Raw data
{
"_id": null,
"home_page": null,
"name": "spacetransformer-core",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "medical-imaging, geometry, transform, numpy",
"author": null,
"author_email": "Your Name <you@example.com>",
"download_url": "https://files.pythonhosted.org/packages/0e/a4/5fe1d073a39a5389538d8ac79b3805b122cb51eb420f0267d47eabdf08b3/spacetransformer_core-0.2.5.tar.gz",
"platform": null,
"description": "# SpaceTransformer\n\nA Python library for elegant 3D medical image geometric transformations.\n\n\n## Why SpaceTransformer?\n\nTraditional medical image processing suffers from fragmented coordinate concepts:\n\n- **Frame**: Only captures position/orientation, missing crucial **shape** information\n- **NIfTI Affine**: A 4x4 matrix that's hard to interpret - what does each element mean?\n- **Manual bookkeeping**: Keeping track of transformations across multiple processing steps\n\nSpaceTransformer introduces the **Space** concept - a complete description of 3D image geometry.\n\n\n## Key Advantages\n\n### 1. Complete Geometric Description\nUnlike traditional \"frame\" concepts, `Space` fully describes the image sampling grid:\n```python\nspace = Space(\n shape=(512, 512, 100), # Complete voxel dimensions\n origin=(0.0, 0.0, 0.0), # Physical position\n spacing=(0.5, 0.5, 2.0), # Voxel size in mm\n x_orientation=(1, 0, 0), # Explicit direction vectors\n y_orientation=(0, 1, 0), # No ambiguous matrix interpretation\n z_orientation=(0, 0, 1)\n)\n```\n\n### 2. Expressive Spatial Operations\nDescribe complex transformations explicitly:\n```python\n# Chain operations elegantly\ntransformed_space = (space\n .apply_flip(axis=2)\n .apply_shape((256, 256, 50))\n .apply_bbox(bbox))\n```\n\n### 3. Transparent Matrix Interpretation\nNo more guessing what a 4x4 affine matrix means - direction vectors are explicit.\n\n## Elegant Image Processing\n\n### 1. Worry-Free Multi-Step Pipelines\n```python\n# Traditional approach: careful bookkeeping required\n# crop -> resize -> segmentation -> resize back -> pad back\n\n# SpaceTransformer approach: fully reversible by design\ntarget_space = original_space.apply_bbox(bbox).apply_shape(target_size)\nwarped_img = warp_image(original_img, \n original_space, \n target_space, \n mode='trilinear', \n pad_value=-1000)\n# ... process in target_space ...\nsegment_result = segmodel(warped_img) # hxwxl, int\nkeypoint_result = keypmodel(warped_img) # nx3, [i,j,k], index coord\n# Automatic optimal path back to original_space\noriginal_segment_result = warp_image(segment_result, \n target_space, \n original_space, \n mode='nearest', \n pad_value = 0)\noriginal_keypoint_result = warp_point(keypoint_result, \n target_space, \n original_space) # nx3, index coord \nworld_keypoint_result = target_space.to_world_transform(keypoint_result) # nx3, [x,y,z], mm\n```\n\n### 2. Abstract-Then-Execute Pattern\n```python\n# Plan transformations (fast, no actual image processing)\ntarget_space = source_space.apply_flip(0).apply_rotate(1, 30, unit=\"degree\").apply_bbox(bbox).apply_shape((256, 256, 128))\n\n# Execute once with optimal path (GPU-accelerated)\nresult = warp_image(image, source_space, target_space, cuda_device=\"cuda:0\")\n```\n\n### 3. GPU-Accelerated & Deep Learning Ready\n- PyTorch backend with automatic optimal transformation paths\n- No `align_corners` confusion - transformations are mathematically guaranteed reversible\n- Seamless integration with deep learning workflows\n\n## Architecture\n\n- **spacetransformer-core**: Pure NumPy implementation for geometric computations\n- **spacetransformer-torch**: GPU-accelerated image resampling with PyTorch\n\n## Quick Start\n\n**[View Example Notebook](example/example.ipynb)** - See a practical demonstration of the library's capabilities\n\n```python\nimport numpy as np\nfrom spacetransformer.core import Space\nfrom spacetransformer.torch import warp_image\n\n# Create image space\nspace = Space(\n shape=(512, 512, 100),\n spacing=(1.0, 1.0, 2.0),\n origin=(0, 0, 0)\n)\n\n# Define target transformation\ntarget_space = space.apply_flip(axis=2).apply_shape((256, 256, 50))\n\n# Apply to image (GPU-accelerated)\ntransformed_image = warp_image(\n image, space, target_space, \n pad_value=0, cuda_device=\"cuda:0\"\n)\n```\n\n## Format Support\n\n- **NIfTI**: `Space.from_nifti(nifti_image)`\n- **SimpleITK**: `Space.from_sitk(sitk_image)`\n\n## Installation\n\n```bash\npip install spacetransformer-core # Core functionality\npip install spacetransformer-torch # GPU acceleration\n```\n\n## Requirements\n\n- **Core**: Python \u22653.8, NumPy \u22651.20\n- **Torch**: PyTorch \u22651.12 (spacetransformer-torch)\n\n---\n\n*SpaceTransformer: Making 3D medical image transformations as elegant as they should be.* \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Pure numpy core implementation of Space Transformer for geometric computations.",
"version": "0.2.5",
"project_urls": null,
"split_keywords": [
"medical-imaging",
" geometry",
" transform",
" numpy"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0c408c424815081d7e333e6d86095d4fa1c1b441587518213b1a0c52293023b9",
"md5": "cda24701f296d46871787a6133aa5bc4",
"sha256": "b06ddb396ed7714744266700e893c3c3ae5e87e092384ddbd7f7ba55d1293967"
},
"downloads": -1,
"filename": "spacetransformer_core-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cda24701f296d46871787a6133aa5bc4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 29443,
"upload_time": "2025-08-15T10:57:24",
"upload_time_iso_8601": "2025-08-15T10:57:24.677838Z",
"url": "https://files.pythonhosted.org/packages/0c/40/8c424815081d7e333e6d86095d4fa1c1b441587518213b1a0c52293023b9/spacetransformer_core-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0ea45fe1d073a39a5389538d8ac79b3805b122cb51eb420f0267d47eabdf08b3",
"md5": "726dbbace9a02cd6088342ba2360d84e",
"sha256": "68ca301c3ce4ad766a5b92c237268ac25a1fcf27b0d58eddf43c4c8ad62562f6"
},
"downloads": -1,
"filename": "spacetransformer_core-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "726dbbace9a02cd6088342ba2360d84e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 3304472,
"upload_time": "2025-08-15T10:57:26",
"upload_time_iso_8601": "2025-08-15T10:57:26.156954Z",
"url": "https://files.pythonhosted.org/packages/0e/a4/5fe1d073a39a5389538d8ac79b3805b122cb51eb420f0267d47eabdf08b3/spacetransformer_core-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-15 10:57:26",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "spacetransformer-core"
}
JSON