Skip to content

WholeSlide Remote Specification

Jump to bottom Edit New page
Rich Stoner edited this page Jan 14, 2014 · 7 revisions

WholeSlide Remote Server Specification

Version 1.1.0

Last Update: Rich Stoner on 1/14/2014

This document describes the minimal server capabilities required for the WS2 application. Requirements are organized into two categories: browse and access.

For examples, assume the following: A virtual slide server is be online at http://SERVER.edu . On the server, there are two folders - "Research" and "Education". Within each folder, there are 2 images of varying sizes and names.

NOTE All invalid requests (incorrect url, unauthenticated, incorrect username) should return an empty json object or appropriate error code (404, 403, etc).

{}

0. Supported API commands

authenticate - authenticate this user

server - get information about the server

folders - get a list of all folders user has access to

slides - get a [paged] list of slides in a given folder

image - get image info from a specific image

thumb - get the thumbnail for the specific image

tile - get the tile specified at given location

1. Browse

1.1. Server Information

This provides the viewer application with a high-level view of the server being accessed.

1.1.1. Request (HTTP GET)

https://SERVER.edu/api/v1/server

Example curl

curl -h 'Content-Type: application/json' \
	-H 'User-Agent: WholeSlide;' \
	http://SERVER.edu/api/v1/server

1.1.2 Response (JSON)

{
	"description": "A short description of the server",
	"type": "mbf",
	"version": 1.0,
	"icon": "http://SERVER.edu/representative_icon.jpg (defaults to vendor default)",
	"metadata": {
		"key1":"value1",
		"key2":"value2"
	}
}

1.1.3. Field details

key contents format required
description A short description of the server String, <150 characters x
type short key of supported type key: mbf, aperio, zoomify, deepzoom x
version api version float (semantic versioning preferred) x
icon URL of icon to be used when displaying this server Publically accessible URL string for PNG or JPEG image.
Image size: minimum 100x100px, preferred 256x256, maximum 512x512		 Will default to server type default url
metadata a dictionary of non-essential metadata not included above. Can include contact information, image licenses, access policies, etc. key-value pairs

1.2. Authenticate

This endpoint handles user authentication and current logged-in status. This should be done over https to prevent snooping if security is a concern. Valid logins return a security token that expires after a server-defined duration.

1.2.1. Status request (HTTP GET)

https://SERVER.edu/api/v1/authenticate

Header data: token=RANDOMSECURITYTOKEN

If still logged in, server can return same token or generate new to extend the user's session

Still logged in response (JSON)

{
	"status":"success",
	"username":"username",
	"token": "RANDOMSECURITYTOKEN"
}

1.2.2. Login request (HTTP POST)

https://SERVER.edu/api/v1/authenticate

POST data: username, password

Valid login response (JSON)

{
	"status":"success",
	"username":"username",
	"token": "RANDOMSECURITYTOKEN"
}

1.2.3 Field details

key contents format required
status A short keyword of the query result String x
username Username as defined by the server provider. App provides no validation. String x
password Password as defined by the server provider. App provides no validation. String x
token An N-bit alphanumeric session token maintained by the server. String (N characters) x

1.3. Server Contents

This request queries the server for all available folders. Recall - 'research' and 'education' are folders on the server, but could easily be replaced by tags or categories. Nested folders are supported.

NOTE Folders are stored as a dictionary (no key order); slide lists are ordered arrays.

1.3.1 All folders request (HTTP GET)

https://SERVER.edu/api/v1/folders

Header data: token=RANDOMSECURITYTOKEN

Authenticated response (JSON)

{
    "status": "success",
    "folders": {
        "tracked": {
            "description": "",
            "metadata": {},
            "folders": {
                "GFP": {
                    "description": "",
                    "metadata": {},
                    "folders": {}
                    }
                }
            },
        "collection": {
            "folders": {
                "My Shared Images": {
                    "description": "",
                    "metadata": {},
                    "folders": {}
                },
                "Lab Shared Images": {
                    "description": "",
                    "metadata": {},
                    "folders": {}
                }
            }
        }
    }
}

1.3.2 Field details

key contents format required
status A short keyword of the query result String x
description A short description of the folder or slide image String, <150 characters x
metadata a dictionary of non-essential metadata not included above. Can include contact information, image licenses, access policies, etc. key-value pairs

1.4 Folder Contents

This request queries the server for all available folders. Recall - 'research' and 'education' are folders on the server, but could easily be replaced by tags or categories. Nested folders are supported.

NOTE Folders are stored as a dictionary (no key order); slide lists are ordered arrays.

1.4.1 List folders request (HTTP GET)

https://SERVER.edu/api/v1/{start_index}/{slide_count}/{folder_name}/{folder_name}

Header data: token=RANDOMSECURITYTOKEN
  • {start_index} - the first slide in a range to query (default : 0)
  • {slide_count} - the total number of slides to return (default: 50)
  • {folder_name} - one or more folders containing images to view

Authenticated response (JSON)

{
    "status": "success",
    "slides": [
        {
            "description": "a short description of the image",
            "title": "education_slide_1",
            "slide_id": "321",
            "height": 20003,
            "width": 30020,
        },
        {
            "description": "a short description of the image",
            "title": "education_slide_2",
            "slide_id": "322",
            "height": 20003,
            "width": 40050,
        }
    ]
}

1.4.2 Field details

key contents format required
url The base URL under which all tiles are contained String x
width Slide dimensions in pixels Integer x
height Slide dimensions in pixels Integer x
thumbnail URL of the thumbnail image to be used when displaying this slide for selection Publically accessible URL string for PNG or JPEG image.
Image size: minimum 100x100px, preferred 256x256, maximum 512x512		 Will default to image format default (e.g. 0-0-0.jpg for zoomify images)

2. Access

2.1. Get slide details

This request pulls all necessary information for the tile renderer to show the image on the screen. It is analagous to Zoomify's ImageProperties.xml, DeepZoom's DZI, Aperio's INFO3, etc.

Example DeepZoom dzi (xml)

<Image xmlns="http://schemas.microsoft.com/deepzoom/2008" TileSize="256" Overlap="0" Format="jpg">
	<Size Width="122880" Height="98304"/>
</Image>

Example zoomify ImageProperties.xml (xml)

<IMAGE_PROPERTIES WIDTH="5728" HEIGHT="7072" NUMTILES="871" NUMIMAGES="1" VERSION="1.8" TILESIZE="256" />

2.1.1 Slide data request (HTTP GET)

https://SERVER.edu/api/v1/image/{slide_id}

Header data: token=RANDOMSECURITYTOKEN

Slide data response (JSON)

{
	"status":"success",
	'description":"A short virtual slide description",
	'notes":"some other notes",
    'tags":["tag1", "tag2", "tag3"],
	"height":20003,
	"width":"30020",
	"slide_id":"321",
	"thumbnail:"thumb.jpg",
	"tile_x":256,
	"tile_y":256,
	"format":"mbf",
	"max_zoom": 8,
	"objecive":20.0,
	"mpp": 0.50,
	"focal_planes":50,
	"focal_spacing":0.5,
	"zoom_map": [0,1,2,4,6,8],
	"metadata":{
		"key1":"value1",
		"key2":"value2"
	}
}

2.1.2 Field details

key contents format required
status A short keyword of the query result String x
description A short description of the folder or slide image String, <150 characters x
notes Less formal description or comment String, < 500 characters
tabs Keywords used for cataloging image types An array of short keywords ( < 50 characters per) x
url The base URL under which all tiles are contained String x
width Slide dimensions in pixels Integer x
height Slide dimensions in pixels Integer x
thumbnail URL of the thumbnail image to be used when displaying this slide for selection Publically accessible URL string for PNG or JPEG image.
Image size: minimum 100x100px, preferred 256x256, maximum 512x512		 Will default to image format default (e.g. 0-0-0.jpg for zoomify images)
tile_x Tile size (Width) dimensions in pixels Integer x
tile_y Tile size (Height) dimensions in pixels Integer Will default to tile_x if undefined
format A short keyword of the base image format key: zoomify, aperio, deepzoom, mbfstd, tms, etc Will default to server type default (e.g. mbf type -> mbfstd)
max_zoom Maximum number of tiers in image pyramid (zero-indexed) Integer Will default to zoomify calculation if not provided
objective Apparent magnification the base image was captured at Float Will default to calculated magnification from Microns/pixel value
mpp Microns per pixel value for base image Float x
focal_planes 0-indexed count of available focal planes for each image. Access to each image plane is index based: [0 to focal_planes] are valid arguments. Integer total = focal_planes + 1
focal_spacing Microns between each focal plane Float
zoom_map A sorted list of available layers in the tile pyramid Array of ints, Will use linear table by default.
metadata a dictionary of non-essential metadata not included above. Can include contact information, image licenses, access policies, etc. key-value pairs

3. Single tiles

Tile URL generation

From the response, the application will produce mappings similar to :

Single tile urls will be appended to the Tile url base

The single tile URL schema will vary on tile source and a combination of the following parameters

  • absolute zoom (float)
  • rounded absolute zoom (integer)
  • relative scale (float)
  • tier coordinates (integer x,y)
  • native coordinates (float x,y)

Different formats will assemble these parameters to uniquely identify each tile.

e.g. Zoomify -> TileGroup#/RoundedAbsoluteZoom-Tier.Row-Tier.Col.jpg

NOTE Several schemas specify subfolders to keep individual file counts small. Zoomify, for instance, will create a new tile group for every 256 tiles created. The respective tile group is therefore a secondary calculation required for each tile request.

3.1 MBF Tile specification

3.1.1 Thumbnail request (HTTP GET)

https://SERVER/api/v1/thumb/{slide_id}

Header data: token=RANDOMSECURITYTOKEN
  • {slide_id} - the tile unique identifier

Image response (jpeg compressed file)

A single image (jpeg) is returned with 180 x 135 pixels, requested location.

3.1.2 Default tile request (HTTP GET)

https://SERVER.edu/api/v1/tile/{slide_id}/

Header data: token=RANDOMSECURITYTOKEN
  • {slide_id} - the tile unique identifier

Image response (jpeg compressed file)

A single image (jpeg) is returned as a preview image, no greater than 2k x 2k pixels in size. This image is used as the base image for the tiled renderer and can be heavily compressed (0.5q for jpg).

3.1.3 Single tile request (HTTP GET)

https://SERVER.edu/api/v1/tile/{slide_id}/{z}-{x}-{y}

Header data: token=RANDOMSECURITYTOKEN
  • {slide_id} - the tile unique identifier
  • {z} - pyramid level (zoomify notation, where 0 is lowest magnification)
  • {x},{y} - row and column indices

Image response (jpeg compressed file)

A single image (jpeg) is returned with tile_x x tile_y dimensions corresponding to the requested location. Default tile size not yet defined.

3.1.4 Tile request with focal plane (HTTP GET)

https://SERVER.edu/api/v1/tile/{slide_id}/{z}-{x}-{y}-{f}

Header data: token=RANDOMSECURITYTOKEN
  • {slide_id} - the tile unique identifier
  • {z} - pyramid level (zoomify notation, where 0 is lowest magnification)
  • {x},{y} - row and column indices
  • {f} - focal plane of image to select

Image response (jpeg compressed file)

A single image (jpeg) is returned with tile_x x tile_y dimensions corresponding to the requested location. Default tile size not yet defined.

3.1.5 Annotation request

https://SERVER.edu/api/v1/tile/{slide_id}/annotation

Header data: token=RANDOMSECURITYTOKEN

XML response

    A Biolucida annotation file (format to be defined).
Add a custom footer
Add a custom sidebar
Clone this wiki locally