Installation

HistomicsTK can be used both as a pure Python toolkit for algorithm development and as server-side Girder plugin for web-based analysis. Here, we describe how to install HistomicsTK for both these scenarios.

Installing HistomicsTK as a Python toolkit

On Linux, HistomicsTK can be installed via pip. You can specify the --find-links option to get prebuilt libraries for reading some common image formats. The installation command is:

$ pip install histomicstk --find-links https://girder.github.io/large_image_wheels

For non-Linux systems, or to use system libraries for reading image formats, please see the Github repo of large_image to find out how to install it as a Python toolkit/package. Once large_image is installed as a python package, HistomicsTK can be installed as follows:

$ git clone https://github.com/DigitalSlideArchive/HistomicsTK.git
$ cd HistomicsTK
$ pip install -e .

If you want the keras/tensorflow based functions of HistomicsTK to take advantage of the GPU, then you will have to install the GPU version of tensorflow (tensorflow-gpu) after installing HistomicsTK. See tensorflow installation instructions here.

Installing HistomicsTK as a server-side Girder plugin

When HistomicsTK is used as a server-side Girder plugin for web-based analysis, the following three Girder plugins need to be installed:

  • girder_worker: A Girder plugin for distributed task execution.

  • large_image: A Girder plugin to create/serve/display large multi-resolution images produced by whole-slide imaging systems and a stand-alone Python package to read/write these images.

  • slicer_cli_web: A Girder plugin for providing web-based RESTFul access to image analysis pipelines developed as slicer execution model CLIs and containerized using Docker.

There are several methods that can be used to install HistomicsTK. Each of these results in a fully deployed system. Docker is often the easiest deployment. Vagrant is the easiest development environment.

Installing Slicer CLI Docker Images for Analysis

One of the primary uses of HistomicsTK as a Girder plugin is to analyze images. Analyses are configured using Docker images conforming to the Slicer execution model. Different analysis Docker images can be installed by a system administrator using the Web API (the link is on the bottom of the Girder web page).

Selecting the Web API will show a list of API endpoints for Girder. In the PUT /HistomicsTK/HistomicsTK/docker_image endpoint, you can add a list of Docker images, such as ["dsarchive/histomicstk:latest"], and then click “Try it out”. This will pull the specified Docker image and make it available to the HistomicsTK interface. You could also use a specific tag (version) from Docker instead of the latest tag. Multiple versions and multiple images can be installed so that they can be compared against each other.

For an example of how to make a Docker image with a Slicer CLI-compatible interface, see here.