Minerva is a microscopy imaging software platform which allows visualizing, analyzing and storing high-dimensional microscopy image data. Minerva is designed to be cloud-native, taking full advantage of cloud features such as object storage and serverless computing. It is composed of several integrated applications:

Minerva Cloud is a system where image data can be imported and stored in repositories. The images can be served either as raw image tile data or as composited colorized tiled images.

Minerva Author is a web tool to build narrated stories around images via selection of specific channel groupings and image views.

Minerva Story is a web based narrated story based on an image or a set of images. It is the end-product of Minerva Author.

Minerva Analysis TBD

Minerva Atlas TBD

Minerva API uses Amazon Cognito for authentication. Clients must authenticate using username and password to obtain an id token for the user. It’s recommended to use a Cognito client library, such as amazon-cognito-identity-js.

Id token must be included in HTTP request headers with each request to Minerva API. Authorization: Bearer ID_TOKEN

Example (Javascript)

import {
  CognitoUserPool,
  AuthenticationDetails,
  CognitoUser
} from 'amazon-cognito-identity-js';

const minervaUserPool = new CognitoUserPool({
    UserPoolId: 'USER_POOL_ID',
    ClientId: 'CLIENT_ID'
});

const cognitoUser = new CognitoUser({
    Username: 'USER_NAME',
    Pool: minervaUserPool
});

const authenticationDetails = new AuthenticationDetails({
    Username: 'USER_NAME',
    Password: 'PASSWORD'
});

cognitoUser.authenticateUser(authenticationDetails, {
    onSuccess: result => success(result),
    onFailure: err => fail(err)
});

Response

{
    "AuthenticationResult": {
        "AccessToken":"ACCESS_TOKEN",
        "ExpiresIn":36000,
        "IdToken":"ID_TOKEN",
        "RefreshToken":"REFRESH_TOKEN",
        "TokenType":"Bearer"
    },
    "ChallengeParameters":{}
}

Success

Successful request will return Status: 200 OK

If a new resource is created as a result of the request, the response may be Status: 201 Created

Error

In case of error, the response will contain an object with a detailed error message.

Status: 403 Forbidden

{
    error: 'Unauthorized operation',
}

Status codes

Minerva Command Line Interface

Minerva CLI can be used to import images into Minerva Cloud from the command line. Images can also be exported from Minerva Cloud into local disk.

Install Minerva CLI

# Use Python >= 3.7
pip install minerva-cli
minerva configure

Importing

Import a directory into Minerva Cloud. All images within the directory will be imported. The given repository will be created if it does not exist already. By default the image will be processed server side.

minerva import -r repository_name -d /home/user/images

Optionally when importing OME-TIFF files, the image can be processed client side by passing the argument –local. Local import can be faster when importing just a single or few files.

minerva import --local -r repository_name -f /home/user/images/single_image.ome.tif

Check importing process status.

minerva status

Exporting

Export an image from Minerva Cloud into local disk. Image uuid has to be given with argument –id.

minerva export --id 123e4567-e89b-12d3-a456-426614174000

Minerva CLI code is available from GitHub

About importing images

This section describes the low-level mechanics of image importing. The easiest way to import images is to use either Minerva Cloud web interface or Minerva CLI.

Multichannel microscopy images tend to be large, a typical image might be in the range of 10-200 GBs. Importing them takes several minutes to one hour. AWS Lambda timeout is not enough and therefore the image importing process is run in a background AWS Batch job. The import process generates a tiled image pyramid (or uses an existing pyramid) and stores it in S3 as OME-ZARR, a highly scalable tile structure. The original image file is either discarded or it can be archived in low-cost S3 Glacier.

Import steps

1. Create a repository

Create a new repository to put the image in. You can skip this step when using an existing repository.

curl -X POST -H "Content-Type: application/json" -d '{"name": "Repository 1", "raw_storage": "Destroy"}' https://$BASE_URL/repository

The response will contain a repository uuid which must be used in the next step.

2. Create an import

First we need a new import object which will be used for tracking the progress.

curl -X POST -H "Content-Type: application/json" -d '{"name": "Import 1", "repository_uuid": "123e4567-e89b-12d3-a456-426614174000"}' https://$BASE_URL/import

The response will contain an import uuid which must be used in the next step.

3. Get S3 credentials for the import key

Next we must request temporary AWS credentials to obtain upload access to Minerva’s S3 bucket.

curl -X GET https://$BASE_URL/import/{import_uuid}/credentials

The response will contain AWS credentials, S3 bucket name and key to upload the import into.

4. Upload the image to the S3 bucket/key

Upload the image to the given S3 bucket and key, using the provided AWS temporary credentials (NOT the user’s credentials). You can use e.g. AWS CLI or any programmatic client like boto3 for Python.

import boto3

# Replace values of AccessKeyId, SecretAccessKey, SessionToken, Bucket, Key with values obtained from the previous step.

s3 = boto3.client("s3", aws_access_key_id="AccessKeyId",
                    aws_secret_access_key="SecretAccessKey",
                    aws_session_token="SessionToken",
                    region_name="us-east-1")

s3.upload_file("/images/image1.ome.tif", "Bucket", "Key/Image_Name.ome.tif")

5. After the upload has finished, mark the import complete

Marking the import complete will trigger the AWS Batch Job, so it must be done only after uploading has finished.

curl -X PUT -H "Content-Type: application/json" -d '{"complete": true }' https://$BASE_URL/import/{import_uuid}

6. Wait for the import Batch Job to finish

The import Batch Job may take around 10-60 mins, depending on image size and EC2 instance availability. The status of the import can be checked with:

curl -X GET https://$BASE_URL/import/{import_uuid}/filesets

Repository object describes an image repository, which is a collection of images.

Repository

Image object describes a single image. Does not contain pixel data (which is stored in S3 object storage).

Image