Python scripts and tools for prepping various image format files for access via the Cantaloupe IIIF image server and Seadragon.
This method uses uv and installs all external tools into the virtual environment.
- Python 3.11+
- Java 17+
- macOS:
brew install openjdk@17 - RHEL/Fedora:
dnf install java-17-openjdk - Ubuntu/Debian:
apt install openjdk-17-jdk
- macOS:
- libvips (image processing library)
- macOS:
brew install vips - RHEL/Fedora:
dnf install vips vips-devel - Ubuntu/Debian:
apt install libvips-dev
- macOS:
- uv (Python package manager): https://docs.astral.sh/uv/getting-started/installation/
git clone https://github.com/informatics-isi-edu/imagetools.git
cd imagetools
# Create and activate virtual environment
uv venv
source .venv/bin/activate
# Install Python package and dependencies
uv pip install -e .
# Install external tools (bioformats2raw, raw2ometiff, bftools)
./setup_prerequisites.shAll tools (bioformats2raw, raw2ometiff, showinf, bfconvert, etc.) are now available when the venv is active.
bioformats2raw --version
raw2ometiff --version
showinf -version
extract_scenes --helpThis package depends on external Java-based tools that are installed by setup_prerequisites.sh:
- bioformats2raw - Converts Bio-Formats images to zarr
- raw2ometiff - Converts zarr to OME-TIFF
- bftools - Bio-Formats command line tools
# Enable EPEL and CodeReady Builder repositories
subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms
dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
# Install Python 3.11+ (RHEL 9 ships with 3.9 by default)
dnf install -y python3.11 python3.11-pip python3.11-devel
# Install required packages
dnf install -y java-17-openjdk vips vips-develgit clone https://github.com/informatics-isi-edu/imagetools.git
cd imagetools
# Create and activate virtual environment with Python 3.11
python3.11 -m venv .venv
source .venv/bin/activate
# Install package
pip install -e .
# Install external tools
./setup_prerequisites.shRun the extract_scenes script:
extract_scenes --help
usage: extract_scenes [-h] [--jpeg_quality JPEG_QUALITY] [--compression COMPRESSION] [--tile_size TILE_SIZE] [--force_rgb FORCE_RGB] [--processing_dir PROCESSING_DIR] [--projection_type PROJECTION_TYPE] [--pixel_type PIXEL_TYPE] [--depth_conversion {equalize,rescale,percentile}] [--rotation {0,90,180,270}] imagefile
Tool to extract scenes from an image.
positional arguments:
imagefile The image file to extract scenes from.
options:
-h, --help show this help message and exit
--jpeg_quality JPEG_QUALITY
The compression quality (default: 80)
--compression COMPRESSION
The compression algorithm to use (default: jpeg)
--tile_size TILE_SIZE
The size of the generated tiles (default: 1024)
--force_rgb FORCE_RGB
Force generating the RGB channels
--convert2ome CONVERT2OME
Convert to standard OME-TIFF format
--projection_type PROJECTION_TYPE
Generate Z projection. Valid values: min, max, mean
--processing_dir PROCESSING_DIR
The temporary directory for the image processing
--pixel_type PIXEL_TYPE
The output pixel type (uint8 or uint16)
--depth_conversion {equalize,rescale,percentile}
Method for 16-bit to 8-bit conversion (default: rescale)
--rotation {0,90,180,270}
Rotate output image by specified degrees (default: 0)When converting 16-bit source images to 8-bit output (required for JPEG compression or when --pixel_type uint8 is specified), you can control the conversion method:
- rescale (default): Linear rescaling - divides 16-bit values by 256. Preserves relative intensities between channels.
- equalize: Histogram equalization - redistributes pixel intensities for maximum contrast. May cause washed-out appearance in some channels.
- percentile: Clips values to the 1st-99th percentile range, then rescales to 0-255. Good for images with outliers or hot pixels.
The --rotation option allows rotating the output image by 0, 90, 180, or 270 degrees. This is useful when the source image orientation doesn't match the desired display orientation.
extract_scenes --rotation 180 image.tiffFrom the directory where the image file resides:
extract_scenes <imagefile>The script generates a folder with the <imagefile> name (without extension) containing *.companion.ome, *.ome.tif, *.ome.xml, *.json files and a *.zarr directory.
With optional parameters:
extract_scenes image.tif --processing_dir=/var/scratch/transcoding/tmp
extract_scenes --projection_type min --pixel_type uint8 --tile_size 512 image.oir
extract_scenes --pixel_type uint8 --depth_conversion rescale image.liffrom imagetools import extract_scenes
extract_scenes.run("image.oir")
extract_scenes.run("image.oir", projection_type="max", pixel_type="uint8")
extract_scenes.run("image.oir", pixel_type="uint8", depth_conversion="rescale")
extract_scenes.run("image.oir", rotation=180)The extract_scenes.run function signature:
def run(
imagefile: str,
jpeg_quality: int = 80,
compression: str = 'jpeg',
tile_size: int = 1024,
force_rgb: bool = False,
processing_dir: Optional[str] = None,
projection_type: Optional[str] = None, # 'min', 'max', or 'mean'
pixel_type: Optional[str] = None, # 'uint8' or 'uint16'
convert2ome: bool = False,
depth_conversion: str = 'rescale', # 'rescale', 'equalize', or 'percentile'
rotation: int = 0 # 0, 90, 180, or 270
) -> int:Additional CLI tools are available:
# Consolidate companion OME-TIFF files into a single file
consolidate_companion image.companion.ome
# Convert TIFF to pyramid format
convert_pyramid image.tif
# Extract SVG annotations from QuPath
qupath_svg annotations.geojsonThe examples/ directory contains sample files for testing:
testimage.oir- Sample Olympus OIR microscopy image
Apache 2.0