Installation

Note

CuBATS currently requires Python 3.10 to 3.11.

Pip Install

Note

We suggest installing CuBATS and its prerequisites inside a virtual environment to avoid conflicts with other packages. On macOS and Linux, we recommend using the venv module. For Windows, we recommend using Conda.

CuBATS can be downloaded from PyPI as the cubats package using the pip command. However, CuBATS also requires several system-level packages which need to be installed as well (see Prerequisites below). Once the prerequisites are installed, CuBATS can be installed via pip, ideally inside a previously created virtual environment as shown below:

On macOS and Linux:

$ python3 -m venv cubats-env
$ source cubats-env/bin/activate
$ pip install cubats

On Windows:

$ conda create -n cubats-env python=3.10
$ conda activate cubats-env
$ pip install cubats

Or install CuBATS directly from GitHub:

$ pip install git+https://github.com/hnu-digihealth/CuBATS.git

Prerequisites

CuBATS relies on a few system level packages that need to be installed beforehand. Most importantly, VALIS, OpenSlide Python, pyvips and scikit-image. Depending on the image format, VALIS may require additional tools for registration: While OpenSlide is sufficient for the image formats .vmu, .mrxs, and .svslide, for many other image formats the Java library Bio-Formats is additionally needed.

pyvips

macOS

Install pyvips using Homebrew:

$ brew install vips python pkg-config
$ pip install pyvips

Ubuntu/Debian

Install pyvips using apt:

$ sudo apt-get update
$ sudo apt-get install libvips
$ pip install pyvips

Windows

Download and install the precompiled binaries for libvips and follow the instructions for Windows on the official website: https://www.libvips.org/install.html. Alternatively, you can install pyvips using vcpkg:

$ git clone https://github.com/Microsoft/vcpkg.git
$ cd vcpkg
$ ./bootstrap-vcpkg.sh
$ ./vcpkg integrate install
$ ./vcpkg install vips
$ pip install pyvips

OpenSlide Python

Note

that OpenSlide Python is a Python wrapper for OpenSlide. OpenSlide is a C library that must to be installed separately.

macOS

Install OpenSlide and OpenSlide Python using Homebrew:

$ brew install openslide
$ pip install openslide-python

Note

If you encounter issues with the OpenSlide library not being found, you may need to set the DYLD_FALLBACK_LIBRARY_PATH environment variable to point to the OpenSlide library directory. You can do this dynamically in your Python script or in your shell configuration file (e.g., .bash_profile, .zshrc, etc.):

import os
path = os.environ.get('DYLD_FALLBACK_LIBRARY_PATH', '')
path += (':' if path else '') + '/opt/homebrew/lib'
os.environ['DYLD_FALLBACK_LIBRARY_PATH'] = path
import openslide

Alternatively, you can set the DYLD_LIBRARY_PATH environment variable to point to the OpenSlide library directory:

export DYLD_FALLBACK_LIBRARY_PATH="/opt/homebrew/lib:${DYLD_FALLBACK_LIBRARY_PATH}"

After adding this line, reload your shell configuration:

$ source ~/.bash_profile
# or
$ source ~/.zshrc

Ubuntu/Debian

Install OpenSlide and OpenSlide Python using apt:

$ sudo apt-get update
$ sudo apt-get install openslide-tools
$ pip install openslide-python

Windows

Download and install OpenSlide binaries from the official website. Then import OpenSlide as follows [1]:

OPENSLIDE_PATH = "path/to/openslide/bin"

import os
if hasattr(os, 'add_dll_directory'):
    with os.add_dll_directory(OPENSLIDE_PATH)
        import openslide
else:
    import openslide

VALIS

After having installed the previous prerequisites (optionally Bio-Formats), requirements for VALIS are met and the framework can be installed via pip:

$ pip install valis-wsi

scikit-image

scikit-image can be installed via pip:

$ pip install scikit-image

or via conda:

$ conda install scikit-image

Bio-Formats (Optional)

Bio-Formats requires the Java Development Kit (JDK) and Maven. Install them as follows:

macOS

Install JDK and Maven using Homebrew:

$ brew install openjdk maven

After installation, you may need to set the JAVA_HOME environment variable:

export JAVA_HOME=$(/usr/libexec/java_home)

Ubuntu/Debian

Install JDK and Maven using apt:

$ sudo apt-get update
$ sudo apt-get install openjdk-11-jdk maven

After installation, you may need to set the JAVA_HOME environment variable:

export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64

Windows

Download and install the JDK from the official website: https://www.oracle.com/java/technologies/javase-jdk11-downloads.html

Download and install Maven from the official website: https://maven.apache.org/download.cgi

After installation, you need to set the JAVA_HOME environment variable. For detailed instructions, refer to this guide: https://www.baeldung.com/java-home-on-windows-7-8-10