# SIQ: Super-Resolution Image Quantification
[](https://badge.fury.io/py/siq)
[](httpss://github.com/your-repo/siq)
[](https://opensource.org/licenses/MIT)
**SIQ** is a powerful and flexible Python library for deep learning-based image super-resolution, with a focus on medical imaging applications. It provides a comprehensive toolkit for every stage of the super-resolution workflow, from data generation and model training to robust inference and evaluation.
The library is built on `TensorFlow/Keras` and `ANTSpy` and is designed to handle complex, real-world challenges such as **anisotropic super-resolution** (where different upsampling factors are needed for each axis) and **multi-task learning** (e.g., simultaneously upsampling an image and its segmentation mask).
---
## Key Features
SIQ is more than just an inference tool; it's a complete framework that facilitates:
* **Flexible Data Generation:** Automatically create paired low-resolution and high-resolution patches for training with `siq.image_generator`. Includes support for multi-channel data (e.g., image + segmentation) via `siq.seg_generator`.
* **Advanced Model Architectures:** Easily instantiate powerful Deep Back-Projection Networks (DBPN) for 2D and 3D with `siq.default_dbpn`, customized for any upsampling factor and multi-task outputs.
* **Perceptual Loss Training:** Go beyond simple Mean Squared Error. SIQ includes tools for using pre-trained feature extractors (`siq.get_grader_feature_network`, `siq.pseudo_3d_vgg_features_unbiased`) to optimize for perceptual quality.
* **Intelligent Loss Weighting:** Automatically balance complex, multi-component loss functions (e.g., MSE + Perceptual + Dice) with a single command (`siq.auto_weight_loss`, `siq.auto_weight_loss_seg`) to ensure stable training.
* **End-to-End Training Pipelines:** Train models from start to finish with the high-level `siq.train` and `siq.train_seg` functions, which handle data generation, validation, and model saving.
* **Robust Inference:** Apply your trained models to new images with `siq.inference`, including specialized logic for region-wise and blended super-resolution when guided by a segmentation mask.
* **Comprehensive Evaluation:** Systematically benchmark and compare model performance with `siq.compare_models`, which calculates PSNR, SSIM, and Dice metrics against baseline methods.
---
## Installation
You can install the official release directly from PyPI:
```bash
pip install siq
```
To install the latest development version from this repository:
```bash
git clone https://github.com/stnava/siq.git
cd siq
pip install .
```
---
## Quick Start: A 5-Minute Example
The examples demonstrate the core workflow: training a model on publicly available data and using it for inference.
```bash
tests/test.py
tests/test_seg.py
```
## Pre-trained Models and Compatibility
We provide a collection of pre-trained models to get you started without requiring you to train from scratch.
* **[Download Pre-trained Models from Figshare](https://figshare.com/articles/software/SIQ_reference_super_resolution_models/27079987)**
### Important Note on Keras/TensorFlow Versions
The deep learning ecosystem evolves quickly. Models saved with older versions of TensorFlow/Keras (as `.h5` files) may have trouble loading in newer versions (TF >= 2.16) due to the transition to the `.keras` format.
If you encounter issues loading a legacy `.h5` model, we provide a robust conversion script. This utility will convert your old `.h5` files into the modern `.keras` format.
**Usage:**
```python
import siq
# Define the directory containing your old .h5 models
source_dir = "~/.antspymm/" # Or wherever you downloaded the models
output_dir = "./converted_keras_models"
# Convert the models
siq.convert_h5_to_keras_format(
search_directory=source_dir,
output_directory=output_dir,
exclude_patterns=["*weights.h5"] # Skips files that are just weights
)
```
After running this, you can load the converted models from the `converted_keras_models` directory using `siq.read_srmodel` or `tf.keras.models.load_model`.
---
## For Developers
### Setting Up the Environment
This package is tested with Python 3.11 and TensorFlow 2.17. For optimal CPU performance, especially on Linux, you may want to set these environment variables:
```bash
export TF_ENABLE_ONEDNN_OPTS=1
export ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS=8
export TF_NUM_INTRAOP_THREADS=8
export TF_NUM_INTEROP_THREADS=8
```
### Publishing a New Release
To publish a new version of `siq` to PyPI:
```bash
# Ensure build and twine are installed
python3 -m pip install build twine
# Clean previous builds
rm -rf build/ siq.egg-info/ dist/
# Build the package
python3 -m build .
# Upload to PyPI
python3 -m twine upload --repository siq dist/*
```
Raw data
{
"_id": null,
"home_page": null,
"name": "siq",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "super-resolution, deep learning, ants, resampling, neuroimaging",
"author": null,
"author_email": "\"Avants, Gosselin, Tustison, Reardon\" <stnava@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/0c/e3/0491e518edc22af52a85a9e3d206e566c6e8070b61ec8f9f8d78b5275d5b/siq-0.4.1.tar.gz",
"platform": null,
"description": "# SIQ: Super-Resolution Image Quantification\n\n[](https://badge.fury.io/py/siq)\n[](httpss://github.com/your-repo/siq)\n[](https://opensource.org/licenses/MIT)\n\n**SIQ** is a powerful and flexible Python library for deep learning-based image super-resolution, with a focus on medical imaging applications. It provides a comprehensive toolkit for every stage of the super-resolution workflow, from data generation and model training to robust inference and evaluation.\n\nThe library is built on `TensorFlow/Keras` and `ANTSpy` and is designed to handle complex, real-world challenges such as **anisotropic super-resolution** (where different upsampling factors are needed for each axis) and **multi-task learning** (e.g., simultaneously upsampling an image and its segmentation mask).\n\n---\n\n## Key Features\n\nSIQ is more than just an inference tool; it's a complete framework that facilitates:\n\n* **Flexible Data Generation:** Automatically create paired low-resolution and high-resolution patches for training with `siq.image_generator`. Includes support for multi-channel data (e.g., image + segmentation) via `siq.seg_generator`.\n* **Advanced Model Architectures:** Easily instantiate powerful Deep Back-Projection Networks (DBPN) for 2D and 3D with `siq.default_dbpn`, customized for any upsampling factor and multi-task outputs.\n* **Perceptual Loss Training:** Go beyond simple Mean Squared Error. SIQ includes tools for using pre-trained feature extractors (`siq.get_grader_feature_network`, `siq.pseudo_3d_vgg_features_unbiased`) to optimize for perceptual quality.\n* **Intelligent Loss Weighting:** Automatically balance complex, multi-component loss functions (e.g., MSE + Perceptual + Dice) with a single command (`siq.auto_weight_loss`, `siq.auto_weight_loss_seg`) to ensure stable training.\n* **End-to-End Training Pipelines:** Train models from start to finish with the high-level `siq.train` and `siq.train_seg` functions, which handle data generation, validation, and model saving.\n* **Robust Inference:** Apply your trained models to new images with `siq.inference`, including specialized logic for region-wise and blended super-resolution when guided by a segmentation mask.\n* **Comprehensive Evaluation:** Systematically benchmark and compare model performance with `siq.compare_models`, which calculates PSNR, SSIM, and Dice metrics against baseline methods.\n\n---\n\n## Installation\n\nYou can install the official release directly from PyPI:\n\n```bash\npip install siq\n```\n\nTo install the latest development version from this repository:\n\n```bash\ngit clone https://github.com/stnava/siq.git\ncd siq\npip install .\n```\n\n---\n\n## Quick Start: A 5-Minute Example\n\nThe examples demonstrate the core workflow: training a model on publicly available data and using it for inference.\n\n```bash\ntests/test.py\ntests/test_seg.py\n```\n\n## Pre-trained Models and Compatibility\n\nWe provide a collection of pre-trained models to get you started without requiring you to train from scratch.\n\n* **[Download Pre-trained Models from Figshare](https://figshare.com/articles/software/SIQ_reference_super_resolution_models/27079987)**\n\n### Important Note on Keras/TensorFlow Versions\n\nThe deep learning ecosystem evolves quickly. Models saved with older versions of TensorFlow/Keras (as `.h5` files) may have trouble loading in newer versions (TF >= 2.16) due to the transition to the `.keras` format.\n\nIf you encounter issues loading a legacy `.h5` model, we provide a robust conversion script. This utility will convert your old `.h5` files into the modern `.keras` format.\n\n**Usage:**\n\n```python\nimport siq\n\n# Define the directory containing your old .h5 models\nsource_dir = \"~/.antspymm/\" # Or wherever you downloaded the models\noutput_dir = \"./converted_keras_models\"\n\n# Convert the models\nsiq.convert_h5_to_keras_format(\n search_directory=source_dir,\n output_directory=output_dir,\n exclude_patterns=[\"*weights.h5\"] # Skips files that are just weights\n)\n```\n\nAfter running this, you can load the converted models from the `converted_keras_models` directory using `siq.read_srmodel` or `tf.keras.models.load_model`.\n\n---\n\n## For Developers\n\n### Setting Up the Environment\n\nThis package is tested with Python 3.11 and TensorFlow 2.17. For optimal CPU performance, especially on Linux, you may want to set these environment variables:\n\n```bash\nexport TF_ENABLE_ONEDNN_OPTS=1\nexport ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS=8\nexport TF_NUM_INTRAOP_THREADS=8\nexport TF_NUM_INTEROP_THREADS=8\n```\n\n### Publishing a New Release\n\nTo publish a new version of `siq` to PyPI:\n\n```bash\n# Ensure build and twine are installed\npython3 -m pip install build twine\n\n# Clean previous builds\nrm -rf build/ siq.egg-info/ dist/\n\n# Build the package\npython3 -m build .\n\n# Upload to PyPI\npython3 -m twine upload --repository siq dist/*\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "deep perceptual resampling and super resolution with antspyx",
"version": "0.4.1",
"project_urls": {
"Homepage": "https://github.com/stnava/siq"
},
"split_keywords": [
"super-resolution",
" deep learning",
" ants",
" resampling",
" neuroimaging"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b170273a7477ab444788462f298b1b97602cd11c8ad04313e7b9534ace3c9a9c",
"md5": "3d4438f6f48769d14dfcb608508dcb59",
"sha256": "986815b5f2776c5b458ceec26831c315f90d4024ac5ba6c3c7df9102ec50c0df"
},
"downloads": -1,
"filename": "siq-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d4438f6f48769d14dfcb608508dcb59",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 26176,
"upload_time": "2025-07-11T15:29:07",
"upload_time_iso_8601": "2025-07-11T15:29:07.894397Z",
"url": "https://files.pythonhosted.org/packages/b1/70/273a7477ab444788462f298b1b97602cd11c8ad04313e7b9534ace3c9a9c/siq-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0ce30491e518edc22af52a85a9e3d206e566c6e8070b61ec8f9f8d78b5275d5b",
"md5": "029d4cc73f755c18af68f5c96a413693",
"sha256": "83f7c2ec3d0f1eec359a22f9cf670391ab9ad964a4a0b488ccf01c0154012690"
},
"downloads": -1,
"filename": "siq-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "029d4cc73f755c18af68f5c96a413693",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 31848,
"upload_time": "2025-07-11T15:29:08",
"upload_time_iso_8601": "2025-07-11T15:29:08.877108Z",
"url": "https://files.pythonhosted.org/packages/0c/e3/0491e518edc22af52a85a9e3d206e566c6e8070b61ec8f9f8d78b5275d5b/siq-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 15:29:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stnava",
"github_project": "siq",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "h5py",
"specs": [
[
">=",
"2.10.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.19.4"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.0.1"
]
]
},
{
"name": "antspyx",
"specs": [
[
">=",
"0.2.7"
]
]
},
{
"name": "antspynet",
"specs": [
[
">=",
"0.0"
]
]
},
{
"name": "antspyt1w",
"specs": [
[
">=",
"0.2.3"
]
]
},
{
"name": "tensorflow",
"specs": [
[
">=",
"2.2"
]
]
},
{
"name": "pathlib",
"specs": []
}
],
"lcname": "siq"
}
JSON
