aimio-py
Python bindings for the Numerics88 AimIO C++ library.
aimio-py provides a small Python API to read and write AIM files as NumPy arrays, read ISQ, SCV, and GOBJ files, inspect metadata, and work with processing logs.
Features
- Read AIM files into NumPy arrays
- Write AIM files from NumPy arrays
- Read ISQ files into NumPy arrays
- Read SCV scout-view files into NumPy arrays
- Read GOBJ contour masks into binary NumPy volumes
- Read AIM, ISQ, SCV, or GOBJ files with single
read_imageandimage_infodispatchers - Access AIM, ISQ, SCV, and GOBJ header metadata (
aim_info,isq_info,scv_info,gobj_info) - Convert processing logs between text and dictionary formats
- Optional density/HU conversion helpers
Installation
From PyPI (recommended):
pip install aimio-py
From source:
git clone https://github.com/wallematthias/aimio-py.git
cd aimio-py
git submodule update --init --recursive
pip install -e .
Quickstart
from py_aimio import image_info, read_image
array, meta = read_image("scan.AIM")
print(meta["origin"], meta["spacing"], meta["direction"])
isq_array, isq_meta = read_image("scan.ISQ", unit="hu")
scout_array, scout_meta = read_image("scout.SCV")
mask_array, mask_meta = read_image("mask.GOBJ", value=1, crop="tight")
scan_header = image_info("scan.ISQ")
mask_header = image_info("mask.GOBJ")
The matching metadata CLI uses the same format resolution:
aimio-info scan.AIM
aimio-info mask.GOBJ --format gobj
API
read_image(path, format="auto", **kwargs) -> (array, meta)image_info(path, format="auto") -> meta
Format-specific readers and metadata helpers are also available:
read_aim(path, density=False, hu=False) -> (array, meta)read_isq(path, unit="native") -> (array, meta)read_scv(path) -> (array, meta)read_gobj(path, value=127, crop="tight") -> (array, meta)aim_info(path),isq_info(path),scv_info(path),gobj_info(path)write_aim(path, array, meta=None, unit=None)get_aim_density_equation(processing_log)get_aim_hu_equation(processing_log)log_to_dict(log)dict_to_log(dct)
For ISQ files, unit="native" returns stored scanner values. unit="hu" and
unit="density"/unit="bmd" use calibration metadata from the ISQ extended
header when present.
Read metadata includes SimpleITK-style geometry keys for both AIM and ISQ:
origin, spacing, and direction. For AIM, spacing is copied from
element_size and origin follows the ITKIOScanco-compatible convention:
(position + offset) * spacing. The older vtkbone-style half-voxel-shifted
origin is also exposed as vtkbone_origin. For ISQ, spacing comes from the ISQ
header and origin defaults to (0.0, 0.0, 0.0). direction currently defaults
to the 3D identity direction, matching the practical behavior observed from
ITKIOScanco for ISQ files without explicit orientation metadata.
GOBJ files are read as contour masks. Additive contours are rasterized as
filled contours including their boundary. Subtractive contours, such as inner
cortical boundaries, remove only the strict contour interior so the contour
boundary remains part of the mask. crop="tight" returns the contour bounding
box, while crop="header" returns the full CTDATA header grid.
Development
Run tests:
pytest -q
Run tests with coverage:
pytest -q --cov=py_aimio --cov-report=term-missing --cov-report=xml:coverage.xml
Build local artifacts:
python -m build --wheel --sdist
Build documentation from docstrings:
pip install sphinx
make -C docs html
Generated HTML will be in docs/build/html/index.html.
Important build note
This project depends on the external/AimIO and external/n88util git submodules. If they are missing, extension builds will fail.
Attribution
py_aimio/calibration.pyis adapted from Bonelab/Bonelab.py_aimio/header_log.pyis by Matthias Walle.
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for aimio-py 0.1.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| aimio_py-0.1.8.tar.gz | 67.9 kB | Details |
Built distributions (wheels)
Total release size: 9.1 MB
Release files / aimio_py-0.1.8.tar.gz
| Download URL | aimio_py-0.1.8.tar.gz |
|---|---|
| Size | 67.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ace5e52a2398de7f67006d103df9f673232407cff4e526c4262c8283b23fba92
|
|
BLAKE2b-256 checksum How to use checksums |
7665aa5e28e7c62a531fce53f2f45492e85b5690e84021f5c135c9433fb7f907
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 10, 2026.
Transparency logRelease files / aimio_py-0.1.8-cp313-cp313-win_amd64.whl
| Download URL | aimio_py-0.1.8-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 322.8 kB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
45a5f95f9ace0a02a9576f47ecd3bab4672a012e6202da98ab5c03eff3c0c419
|
|
BLAKE2b-256 checksum How to use checksums |
5ba18023066561a8d8c1d6c7c9aa3e2ba8eb51ce4dd9de888a45666afdcdae05
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 10, 2026.
Transparency logRelease files / aimio_py-0.1.8-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | aimio_py-0.1.8-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.13 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
66a60b7fe08573a635a5c4df6ba0f161a676af8e82d7e242f38e30c680ecbd67
|
|
BLAKE2b-256 checksum How to use checksums |
682295de1b8c22cf1b7cd32b2cb19fbcba771846d4cb14fdd2bdf0f88742e6d8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 10, 2026.
Transparency logRelease files / aimio_py-0.1.8-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | aimio_py-0.1.8-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 133.0 kB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
c8eb6ab7520425f0dc6d0c9bff4b61ee9f05d03f1ac8c73318aae3112a78322b
|
|
BLAKE2b-256 checksum How to use checksums |
89d833011ff1b231e5f8e582c0e8e71e3f9a8c9840d37f4d0cd19998db939a3e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 10, 2026.
Transparency logRelease files / aimio_py-0.1.8-cp313-cp313-macosx_10_13_x86_64.whl
| Download URL | aimio_py-0.1.8-cp313-cp313-macosx_10_13_x86_64.whl |
|---|---|
| Size | 139.2 kB |
| Tags | CPython 3.13 macOS 10.13+ x86-64 |
|
SHA-256 checksum How to use checksums |
ce3a8c446e1a43fefaa15f11239351179bc61c62938d54e22017676dab1a365c
|
|
BLAKE2b-256 checksum How to use checksums |
b7251f691161e6498ea7479bedb0325f998bdfdbf1b4d5b8b8672c7a9d7eb4f7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 10, 2026.
Transparency logRelease files / aimio_py-0.1.8-cp312-cp312-win_amd64.whl
| Download URL | aimio_py-0.1.8-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 322.8 kB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
19c932ed52b7e79771342a85980e244a7b5f3350dbda4d1d9058e4582260a89c
|
|
BLAKE2b-256 checksum How to use checksums |
e006185ebd25e1ca4349c7a25b24dbcbeae6fa69cc0ad42f418f2d8908c51aa1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 10, 2026.
Transparency logRelease files / aimio_py-0.1.8-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | aimio_py-0.1.8-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.12 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
6710332613c2f009b18bb641f02913833ea117c42bdf818e749ab3ad6123b0a0
|
|
BLAKE2b-256 checksum How to use checksums |
51484d76e1033aa33dc47d96be8ecb38b6f79cbe8cf47e8f9defb8c1df7fb17c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 10, 2026.
Transparency logRelease files / aimio_py-0.1.8-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | aimio_py-0.1.8-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 132.9 kB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
696a03f42c613e9a9562e7e7e648d17c01e7c7ca6132787f5818d6a7a9ec110d
|
|
BLAKE2b-256 checksum How to use checksums |
d196dcd8d60423eefba5b0fd9d8484cfad6aca704ffd349897bd1ebdb34dc586
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 10, 2026.
Transparency logRelease files / aimio_py-0.1.8-cp312-cp312-macosx_10_13_x86_64.whl
| Download URL | aimio_py-0.1.8-cp312-cp312-macosx_10_13_x86_64.whl |
|---|---|
| Size | 139.2 kB |
| Tags | CPython 3.12 macOS 10.13+ x86-64 |
|
SHA-256 checksum How to use checksums |
131b8f02135dddaa00fac2befa19432a72df31ff327ae4eed63780ac0319de7d
|
|
BLAKE2b-256 checksum How to use checksums |
b9b88ada77e458996fcf7488caa40b4ac1d6587884cd79235e3546c636d5d431
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 10, 2026.
Transparency logRelease files / aimio_py-0.1.8-cp311-cp311-win_amd64.whl
| Download URL | aimio_py-0.1.8-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 320.2 kB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
d30b7e294a504333d3b0d7b9811aba54fa88e1cc5c9ac8688a0dbc48a1969616
|
|
BLAKE2b-256 checksum How to use checksums |
dc73b9de47215c41642c90494991063b4076ed3b4a27b35782dd278f7e47297a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 10, 2026.
Transparency logRelease files / aimio_py-0.1.8-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | aimio_py-0.1.8-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.11 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
fff8524fbf72e3295656516db6ff70b1dbf1a4ca8547da089b2c70e603aee09f
|
|
BLAKE2b-256 checksum How to use checksums |
92723bfd677e4182883e56b56eb09f16627b08343005a4e860b825110a93f646
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 10, 2026.
Transparency logRelease files / aimio_py-0.1.8-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | aimio_py-0.1.8-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 131.3 kB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
1df8b729aab768b0f09ce01bc95ab15d60ab80eaa1a5ccc9bdd22d075ba7b914
|
|
BLAKE2b-256 checksum How to use checksums |
c25feec825c35b569e70d3e2e4f5395df56ab736739bda3d788a2dc3ba263d9f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 10, 2026.
Transparency logRelease files / aimio_py-0.1.8-cp311-cp311-macosx_10_9_x86_64.whl
| Download URL | aimio_py-0.1.8-cp311-cp311-macosx_10_9_x86_64.whl |
|---|---|
| Size | 137.0 kB |
| Tags | CPython 3.11 macOS 10.9+ x86-64 |
|
SHA-256 checksum How to use checksums |
a4d62614706933c638a1dec6b5629c6fca11ebeb804715d5cd65e63d9a257329
|
|
BLAKE2b-256 checksum How to use checksums |
6feba1bdb179425f5ff6ce0003a7bbbba623fceff883dd57992cc69feecac599
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 10, 2026.
Transparency logRelease files / aimio_py-0.1.8-cp310-cp310-win_amd64.whl
| Download URL | aimio_py-0.1.8-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 319.5 kB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
b5ff5f341ba2e412524ec1d77457cb39b91422bd0d8973c360f28fac77b5fd18
|
|
BLAKE2b-256 checksum How to use checksums |
cc4a9318bcceec18b9caa2608f276a0f4815d0281663728416e21b00b48006c0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 10, 2026.
Transparency logRelease files / aimio_py-0.1.8-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | aimio_py-0.1.8-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.6 MB |
| Tags | CPython 3.10 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
037fb107a18db3065ee9ee5690f773c85646842ff11ab59d0a87334c9deba97d
|
|
BLAKE2b-256 checksum How to use checksums |
570df3f1b3af01648ee4ef19ca184fced527c33b0ad1d74d1ca0e9186c38abb1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 10, 2026.
Transparency logRelease files / aimio_py-0.1.8-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | aimio_py-0.1.8-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 129.9 kB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
7b9b33d86bb8114028ba4d8fcc859f2d7c450ad9a45755ffe86e5928648b0641
|
|
BLAKE2b-256 checksum How to use checksums |
6f6fabd0ce819df7c11af7bffa44ec4d045b90f113de7606e5833dbc64a2fdc8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 10, 2026.
Transparency logRelease files / aimio_py-0.1.8-cp310-cp310-macosx_10_9_x86_64.whl
| Download URL | aimio_py-0.1.8-cp310-cp310-macosx_10_9_x86_64.whl |
|---|---|
| Size | 135.5 kB |
| Tags | CPython 3.10 macOS 10.9+ x86-64 |
|
SHA-256 checksum How to use checksums |
4eb458cd7559fc536bd2793aeb2d47d96e385535fc2e0e2ee60ae7febe0ebfe0
|
|
BLAKE2b-256 checksum How to use checksums |
3a291b56864a0fef7be53cac844572e9e8c0a319cd655cbe350bb950b0eb7eaa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 10, 2026.
Transparency log
