Simmetric

A Python package for simulating and analyzing CT image artifacts.

Features

• Simulate various CT artifacts:
  • Metal artifacts
  • Streaking artifacts
  • Ring artifacts
  • Motion artifacts
  • And more...
• Calculate image quality metrics
• Visualize artifacts and their effects
• Support for both 2D and 3D images

Installation

Development Installation

1. Clone the repository:

git clone https://github.com/e040/simmetric.git
cd simmetric

2. Create and activate a virtual environment (recommended):

Windows: Make sure to have python 3.11 installed.

# Using venv (Python 3.11+)
python -m venv .venv
# To specify python version do:
py -3.11 -m venv .venv
# Activate environment
.venv\Scripts\Activate 

Ubuntu: Use this command to chek if python 3.11 is installed and install it if neccessary to create the virtual environment.

PYVER=3.11 && command -v python$PYVER >/dev/null || (sudo apt update && sudo apt install -y python$PYVER python$PYVER-venv) && python$PYVER -m venv .venv
source .venv/bin/activate # activate environment

3. Install the package in development mode with required dependencies:

pip install -e .

4. (Optional) Install additional development dependencies for testing:

pip install -e ".[test]"

Note: The [test] dependencies include pytest and pytest-cov for running tests and generating coverage reports. If you plan to run tests, you should install these additional dependencies.

Usage

Note: Works best if run on a local machine and not in a remote session due to visualization tools

Basic Usage

from simmetric.core.dataset import Dataset
from simmetric.core.transforms import Transforms

# Load an image
image = Dataset("path/to/image.nii.gz").load()

# Create a transformer
transformer = Transforms()

# Apply a transform
transformed_image = transformer.apply_transform('streaking', image, start_slice=50, end_slice=55)

# Visualize the results
transformer.visualize(source_image=image, transformed_image=transformed_image)

Available Transforms

• rotate: Rotate the image
• shift: Shift the image
• blur: Apply Gaussian blur
• noise: Add noise
• breathing: Add breathing artifacts
• ring: Add ring artifacts
• cupping: Add cupping artifacts
• aliasing: Add aliasing artifacts
• truncation: Add truncation artifacts
• motion: Add motion artifacts
• shading: Add shading artifacts
• streaking: Add streaking artifacts

Available Metrics

• MAE: Mean Absolute Error
• MSE: Mean Squared Error
• NRMSE: Normalized Root Mean Square Error
• PSNR: Peak Signal-to-Noise Ratio
• SSIM: Structural Similarity Index
• MS-SSIM: Multi-Scale Structural Similarity Index
• FSIM: Feature Similarity Index
• GMSD: Gradient Magnitude Similarity Deviation
• NMI: Normalized Mutual Information
• JSD: Jensen-Shannon Divergence
• VIF: Visual Information Fidelity
• NCC: Normalized Cross-Correlation

Development

Running Tests

Run all tests:

pytest

Run tests with coverage:

pytest --cov=simmetric

Code Style

The project follows PEP 8 style guidelines. You can check your code style using:

flake8 simmetric tests

Project Structure

simmetric/
├── datasets/
├── simmetric/
│   ├── core/
│   │   ├── transforms.py
│   │   ├── metrics.py
│   │   └── dataset.py
│   │   └── metalartifact_generation.py
│   ├── utils/
│   │   └── config.py
│   └── visualization/
├── tests/
│   ├── test_transforms.py
│   ├── test_metrics.py
│   └── test_dataset.py
├── examples/
│   └── artifact_generation.py
│   └── metric_visualization.py
├── .gitignore
├── .gitlab-ci.yml
├── LICENSE
├── pyproject.toml
└── README.md

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

This project is licensed under the DKFZ license.

Citation

If you use this software in your research, please cite:

@software{simmetric2025,
  author = {Cassandra Krause and Goran Stanic},
  title = {Simmetric: A Python Package for CT Image Artifact Simulation},
  year = {2025},
  url = {https://git.dkfz.de/e040/e0401ninjas/projects/simmetric}
}