Linux

In linux with Python 3.9 or newer:

Prerequisites:

• MongoDB must be installed and running.

• An appropriate version of Python must be installed.

HistomicsUI uses large_image sources to read different image file formats. You need to install appropriate sources for the files that will be used.

# install all sources from the main repo
pip install large-image[sources] --find-links https://girder.github.io/large_image_wheels

or

# install openslide and tiff sources
pip install large-image-source-tiff large-image-source-openslide --find-links https://girder.github.io/large_image_wheels

Now install the histomicsui package, have Girder build its UI, and start the Girder server. Note that at Girder may still require an old version of node (14.x) to build correctly – nvm can be used to manage multiple versions of node.

pip install histomicsui[analysis]
girder build
girder serve

Note that girder serve should only be used in development. In production, use a WSGI server such as gunicorn, e.g.:

.. code-block:: bash

gunicorn girder.wsgi:app –bind=localhost:8080 –workers=4 –preload

To use Girder Worker:

pip install girder_slicer_cli_web[worker]
GW_DIRECT_PATHS=true girder-worker -l info -Ofair --prefetch-multiplier=1

Girder Worker needs the rabbitmq message service to be running to communicate with Girder. Both Girder and Girder Worker should be run as a user that is a member of the docker group.

The first time you start HistomicsUI, you’ll also need to configure Girder with at least one user and one assetstore (see the Girder documentation). Additionally, it is recommended that you install the HistomicsTK algorithms. This can be done going to the Admin Console, Plugins, Slicer CLI Web settings. Set a default task upload folder, then import the dsarchive/histomicstk:latest docker image.

Reference Deployment

The standard deployment of HistomicsUI is the Digital Slide Archive. The associated repository has tools for readily installing via Docker, VirtualBox, or shell scripts on Ubuntu.

Development

The most convenient way to develop on HistomicsUI is in conjunction with the Digital Slide Archive. Once both repos have been cloned locally, mount your local HistomicsUI directory to the DSA docker container:

# /devops/ver5/docker-compose.local.yml
services:

  girder:
    volumes:
      - ../../../HistomicsUI:/opt/HistomicsUI

Then use the devops scripts from the Digital Slide Archive.

If you are making changes to the HistomicsUI frontend, you can have the Girder instance watch the local HistomicsUI source code and perform hot reloads on changes by running npm run build then npm run watch from histomicsui/web_client/. See the Girder docs for more information.

Metadata

Identifiers ending in ItemMetadata are loaded and then set as metadata on the associated item that contains the specified file. Conceptually, this is the same as calling the PUT item/{id}/metadata endpoint.

Annotations

Identifiers ending in AnnotationFile are loaded as annotations, associated with the item that contains the specified file. Conceptually, this is the same as uploaded the file via the annotation endpoints for the item associated with the specified fileId or itemId.

If the annotation file contains any annotations with elements that contain girderId values, the girderId values can be identifier values from files that were uploaded with a reference record that contains a matching uuid field. The uuid field is required for this, but is treated as an arbitrary string.