This repository provides utility functions for Hierarchical Phase-Contrast Tomography (HiP-CT) data preparation. Raw HiP-CT data are with 16-bit intensities (0–65535), jpeg2000, with values concentrated within a narrow range.
For training machine learning and deep learning models, this repository provides normalisation methods and masking.
$ git clone https://github.com/YangForever/hipct_helpers.git
$ cd hipct_helpers
$ uv sync
$ source .venv/bin/activate
$ uv pip install -e .
| Functions | |
|---|---|
| hipct_gen_voi_mask | Generate the circle mask for the HiP-CT VOI data (not complete organ) |
| hipct_gen_voi_mask | Apply masks to the HiP-CT data |
| hipct_slice_to_volume | Assemble all slices as a volume |
| hipct_volume_to_slice | Parse the volume in to slices |
| hipct_normalisation | Normalise HiP-CT data based on the percentile |
| hipct_clahe | Apply CLAHE to the HiP-CT |
| hipct_thresholding | Normalise HiP-CT data based on provided intensity values |
| hipct_binning | Bin (Downsample) HiP-CT data |
Example:
$ hipct_normalisation -h
options:
-h, --help show this help message and exit
--input_dir INPUT_DIR
Input directory containing images
--output_dir OUTPUT_DIR
Output directory for normalised images
--convert_to_8_bit Convert output to 8-bit (default: False)
--mask_dir MASK_DIR Directory containing mask images (optional)
--multiprocessing Enable multiprocessing (default: False)
--global_norm Use global normalisation instead of per-image (default: False)
--threshold THRESHOLD
Percentile threshold (default: 0.01)
--log_level {DEBUG,INFO,WARNING,ERROR}
Logging level (default: INFO)
This repository has supported several projects:
@article{zhou2026multiscale,
title={Multiscale segmentation using hierarchical phase-contrast tomography and deep learning},
author={Zhou, Yang and Aslani, Shahab and Javanmardi, Yousef and Brunet, Joseph and Stansby, David and Carroll, Saskia and Bellier, Alexandre and Ackermann, Maximilian and Tafforeau, Paul and Lee, Peter D and others},
journal={PLOS Computational Biology},
volume={22},
number={2},
pages={e1013923},
year={2026},
publisher={Public Library of Science San Francisco, CA USA}
}
@article{walsh2021imaging,
title={Imaging intact human organs with local resolution of cellular structures using hierarchical phase-contrast tomography},
author={Walsh, Claire L and Tafforeau, P and Wagner, WL and Jafree, DJ and Bellier, A and Werlein, C and K{\"u}hnel, MP and Boller, E and Walker-Samuel, S and Robertus, JL and others},
journal={Nature methods},
volume={18},
number={12},
pages={1532--1541},
year={2021},
publisher={Nature Publishing Group US New York}
}
