A comprehensive Python library for reading whole-slide images (WSI) in digital pathology with a unified API and extensive format support.

ASlide is an integrated whole-slide image (WSI) reading library designed for digital pathology applications. It provides a unified interface to read various proprietary and open-source WSI formats, eliminating the need to work with multiple vendor-specific SDKs.

• Unified API: Single interface for all supported formats
• Comprehensive Format Support: 16+ WSI formats from major vendors
• DeepZoom Support: Built-in tile server capabilities for web-based viewers
• Extensible Architecture: Easy to add new format support
• Pure Python Interface: Simple integration with existing Python workflows
• Performance Optimized: Efficient memory management for large WSI files

ASlide supports the following whole-slide image formats:

• Operating System: Linux (tested on Ubuntu 22.04 LTS)
• Python: 3.10 or higher
• System Libraries: OpenSlide library (for OpenSlide-based formats)

# Clone the repository
git clone https://github.com/MrPeterJin/ASlide.git
cd ASlide

# Install the package (dependencies will be installed automatically)
python setup.py install

The installation script will automatically:

• Install required Python packages (numpy, Pillow, openslide-python, qptifffile, tifffile, pyisyntax)
• Bundle OpenCV 3.4.2 and all dependencies
• Copy vendor-specific shared libraries to the appropriate locations
• Set up environment variables for library paths
• Create helper scripts for environment configuration

After installation, you may need to set up environment variables for shared libraries:

Option 1: Automatic (Recommended)

# Environment is set up automatically when importing
import Aslide

Option 2: Manual Shell Configuration

# Add to your ~/.bashrc or ~/.zshrc
export LD_LIBRARY_PATH=/path/to/site-packages/Aslide/sdpc/lib:/path/to/site-packages/Aslide/kfb/lib:/path/to/site-packages/Aslide/tmap/lib:$LD_LIBRARY_PATH

# Reload your shell configuration
source ~/.bashrc

Option 3: Use the Generated Setup Script

# Source the auto-generated setup script
source /path/to/site-packages/Aslide/setup_env.sh

from Aslide import Slide

# Open a whole-slide image
slide = Slide('path/to/your/slide.svs')

# Get slide properties
print(f"Dimensions: {slide.dimensions}")
print(f"Level count: {slide.level_count}")
print(f"Level dimensions: {slide.level_dimensions}")
print(f"Level downsamples: {slide.level_downsamples}")

# Read a region from the slide
region = slide.read_region((0, 0), 0, (1000, 1000))

# Get thumbnail
thumbnail = slide.get_thumbnail((500, 500))

# Close the slide
slide.close()

For more advanced usage examples, including:

• Multi-resolution image reading
• Tile extraction for deep learning
• DeepZoom tile server integration
• Batch processing workflows

Please refer to the example_test_case.py file in the repository.

The main class for reading whole-slide images.

Methods:

• __init__(filename): Open a slide file
• read_region(location, level, size): Read a region from the slide
• get_thumbnail(size): Get a thumbnail of the slide
• close(): Close the slide and free resources

Properties:

• dimensions: Slide dimensions at level 0 (width, height)
• level_count: Number of pyramid levels
• level_dimensions: Dimensions at each level
• level_downsamples: Downsample factor for each level
• properties: Dictionary of slide metadata

Error:

ImportError: *.so.0: cannot open shared object file: No such file or directory

Solution:

Check that the shared libraries are correctly installed:

# Find your installation path (example for conda)
ASLIDE_PATH=/home/<username>/anaconda3/lib/python3.x/site-packages/Aslide

# Verify library directories exist
ls $ASLIDE_PATH/sdpc/lib
ls $ASLIDE_PATH/tmap/lib
ls $ASLIDE_PATH/kfb/lib
ls $ASLIDE_PATH/mds/lib
ls $ASLIDE_PATH/tron/lib

If directories are missing, reinstall the package:

python setup.py install --force

If libraries are installed but not found at runtime, manually set LD_LIBRARY_PATH:

export LD_LIBRARY_PATH=$ASLIDE_PATH/sdpc/lib:$ASLIDE_PATH/kfb/lib:$ASLIDE_PATH/tmap/lib:$ASLIDE_PATH/mds/lib:$ASLIDE_PATH/tron/lib:$LD_LIBRARY_PATH

If you encounter permission errors during installation, try:

# Install with user permissions
python setup.py install --user

# Or use sudo (not recommended for conda environments)
sudo python setup.py install

The package has been tested on:

• Red Hat 9.6 with Python 3.10
• Ubuntu 24.04 LTS with Python 3.10
• Ubuntu 22.04 LTS with Python 3.13
• Ubuntu 22.04 LTS with Python 3.11
• Ubuntu 22.04 LTS with Python 3.10

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

• Smart-CCS - A Generalizable Cervical Cancer Screening System
• PrePATH - A Pre-processing Tool for Pathology Images

Using ASlide in your project? Add it here by submitting a pull request!

This project is licensed under the GPL 3.0 License - see the LICENSE file for details.

ASlide builds upon and integrates several excellent open-source projects:

• opencv - A computer vision library used for image processing
• OpenSlide - A C library for reading whole-slide images
• opensdpc - SDPC format support
• tct - TCT slide processing utilities
• WSI-SDK - Whole-slide image SDK
• Bio-Formats - Java library for reading life sciences image formats
• vsi2tif - VSI format conversion tools
• pyisyntax - Python library for reading Philips iSyntax images
• olefile - Python library for parsing OLE2 files

Many thanks to the authors and contributors of these projects for their invaluable work.

Author: MrPeterJin Email: petergamsing@gmail.com GitHub: @MrPeterJin

If you find ASlide useful, please consider giving it a star on GitHub!