CanIonSynth: Synthetic CT Volumetric Data Generator for Aerosol Cans and Ionization Chambers.

CanIonSynth creates synthetic industrial CT phantoms, segmentation masks, and optional reconstruction artifacts for metrology and reconstruction studies focused on aerosol cans and ionization chambers. The main workflows are implemented in Julia, with Python helper scripts for visualization, DICOM-SEG conversion, and approximate Radon or inverse-Radon processing.

• Generates can phantoms with configurable wall thickness, rounded or flat bottoms, one or two fluids, meniscus effects, and optional internal objects.
• Generates ionic chamber phantoms with layered multi-material geometry and multiple head shapes.
• Saves the main outputs as NIfTI volumes and component masks.
• Optionally creates DICOM and DICOM-SEG outputs when the required external tooling is installed.
• Optionally runs a projection and reconstruction pass for reconstruction-oriented experiments.
• Supports reproducible runs from JSON configuration files and a validated automated test suite.
• All CLI output is timestamped in [YYYY-MM-DD HH:MM:SS] [INFO] format.

The most predictable local setup today is Python 3.10 plus Julia 1.11 with an activated virtual environment before running tests/setup_env.jl. The checked-in Manifest.toml was generated with Julia 1.11.4.

py -3.10 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
julia --project=. tests/setup_env.jl

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt
julia --project=. tests/setup_env.jl

tests/setup_env.jl instantiates the Julia environment and rebuilds PyCall against the active virtual environment when VIRTUAL_ENV is set.

Run the test suite with deterministic UUIDs:

$env:FIXED_UUIDS = "1"
julia --project=. tests/run_tests.jl

export FIXED_UUIDS=1
julia --project=. tests/run_tests.jl

Build the documentation site with:

julia --project=docs docs/make.jl

Run the main generators from the repository root.

julia --project=. in_docker_organized/main_create_phantom_can.jl 64x64x64 false false run-can-001 false false 0.0

julia --project=. in_docker_organized/main_create_phantom_can.jl 64x64x64 false false run-can-json false false 0.0 tests/configs/can_phantom.json

julia --project=. in_docker_organized/main_create_phantom_ionic_chamber.jl 64x64x64 false false run-ionic-001 false false 0.0

julia --project=. in_docker_organized/main_create_phantom_ionic_chamber.jl 64x64x64 false false run-ionic-json false false 0.0 tests/configs/ionic_chamber_square.json

The generators always keep output locally and print the output directory and zip archive path.

• Julia dependencies are pinned in Project.toml and Manifest.toml.
• Python dependencies are listed in requirements.txt.
• JSON fixtures in tests/configs/ provide reproducible reference parameter sets.
• FIXED_UUIDS=1 makes test output naming deterministic.
• SAVE_OUTPUTS_TO=<path> preserves generated test artifacts before cleanup.

• nii2dcm: required only if you want DICOM slice export from generated NIfTI files.

This repository ships with:

• Dockerfile for a self-contained environment.
• .devcontainer/devcontainer.json for VS Code Dev Containers.

Build the image with:

docker build -t canionsynth .

Open a shell in the container with:

docker run -it --rm canionsynth

• in_docker_organized/: Julia generators and Python helper scripts.
• tests/: automated tests, JSON fixtures, and comparison helpers.
• docs/: user documentation, workflow notes, verification guides, and architecture notes.
• scripts/: utility scripts for visualization and manual test generation.
• examples/: convenience scripts and orchestration examples.
• packages/: vendored dependencies, including the patched ImagePhantoms.jl copy used by this project.

• User Guide
• Workflow Summary
• System Architecture
• Phantom Types
• Functions Reference
• Volume Calculation
• Manual Testing and Visualization
• Manual Verification Guide
• SoftwareX Submission Notes

• Citation metadata is provided in CITATION.cff.
• Archive metadata is provided in .zenodo.json.
• The repository is licensed under the MIT License. See LICENSE.

GitHub Actions workflows are defined in .github/workflows/ci.yml and .github/workflows/docs.yml.