#Eyewire Public API the api is available to try at https://beta-tasking.eyewire.org

Table of Contents

• Overview
• Defintions
• EyeWire Structure & Terminology
  • The Dataset
  • Playing Eyewire (interacting with the dataset)
  • Special things
• Oauth2
  • Registering an application
  • Getting access tokens
  • GET https://beta.eyewire.org/oauth2/1.0/auth
  • POST oauth2/1.0/exchange
• Tasks
  • POST 1.0/tasks/assign
  • POST 1.0/tasks/:id/save
• Data
• Response Objects
  • Volume Object
  • Bounds Object

Overview

EyeWire is a game to map the brain. Players from around the world collectively analyze the retina to determine the three dimensional structure of neurons. Players map neurons by solving 3D puzzles. They scroll through volumes of stacked microscope images and select 3D segments that extend a seed piece either to the other side of a cube or to a termination. Players decide which segment to add by "coloring inside the lines" on a 2D cross section of the volume.

The EyeWire REST API provides programmatic access to interact with EyeWire's data. The key api interactions are assigning tasks and submitting validations. Assignments and submissions must have an associated user account and application id. That information is passed to the api as an Oauth2 access token query parameter.

Definitions

• Oauth2 - open standard for authorization. We support only three-legged authentication. See our Oauth2 implementation for more details.
• access token - a string that identifies an EyeWire account and client application.

EyeWire Structure & Terminology

The Dataset

The EyeWire dataset comprises pairs of .jpg and .png images from which we can map a 3D volume. EyeWire calls the sets of .jpg images channels and the sets of .png images segmentations. The sets are grouped into chunks, which are then grouped into volumes.

• channel
  • a set of 8bpp greyscale .jpg files
  • the electron microscope images
• segmentation
  • a set of 24bpp RGB .png files for normal tasks
  • used to describe which pixels belong to which segment ID
  • The RGB color represents the segment ID: R + 256*G + 256^2 * B
• voxel
  • The highest precision of the dataset. Can be considered a 1x1x1 pixel cube.
• volume
  • a 256^3 voxel cube
  • each volume overlaps its adjacent volumes by 32 voxels
  • a volume is comprised of 2x2x2 voxel chunks
• chunk
  • a 128^3 voxel cube
  • a set of 2D images inside a volume
  • there are 8 chunks in each volume
  • each chunk contains two sets of data: channel images and segmentation images
  • a chunk contains 128 images for each of the three axis 'xy', 'yz', 'xz'

Playing EyeWire (interacting with the dataset)

When a user plays EyeWire they see the channel images and a 3D representation of a part of the current cell they are attempting to map. This part is located inside a specific volume and chunk (think of it like an address). The starting point of the part the user is mapping is called a seed. There may be multiple seeds when a user begins mapping.

Providing the user with seeds for a cell is called assigning the player a task. As the user maps, they select segments they believe are attached to the seeds. When the user is done mapping the task, the segments the user selected are added to the task and create a validation.

• task
  • a volume with seeds
  • associated with a cell
• cell
  • a neuron
  • a tree structure consisting of several tasks
  • the root task is usually part of the cell body
• seeds
  • the pre-highlighted segments visible when a player begins a task
  • players select segments to group them with the seeds
• segment:
  • a group of connected voxels that the EyeWire AI determined as belonging to a single branch of a cell
  • each segment has a unique identifier for its containing volume
• validation
  • a task with a list of additional segments
  • for example, a user starts playing EyeWire and receives a task. The user then highlights segments s/he believes are part of the cell that the initial seeds are part of. The resulting task is returned as a validation
• consensus
  • the current set of segments that are believed to belong to a task based on user submitted validations

Special things

• subspace
  • used for gathering cell overview meshes, which uses different subdivision
  • the size of a subspace depends on the user-specified MIP-level: 2 * 128^mip
  • Other than volumes they don't overlap

Oauth2

We use Oauth2 to allow EyeWire player's to share access to their account with your applications. To get an Oauth2 access token you must register an application.

Registering an application

An application requires a name and a redirection endpoint which is a url where you will receive auth codes and exchange them for access tokens. This process is necessary to configure your application, and only has to be performed once.

1. Register a personal EyeWire user account at beta.eyewire.org
2. Login to Beta EyeWire and visit https://beta-tasking.eyewire.org/oauth2/1.0/clients and click 'Create new client'
3. Enter an app name and a redirect uri and click save. All urls should begin with a protocol such as 'http://' or 'https://'.
4. You will be redirected to the client details screen containing the client id and secret along with the abilities to edit and delete the client.

Getting access tokens

To get an access token for a user, redirect them to https://beta.eyewire.org/oauth2/1.0/auth endpoint as detailed below.

After the user logs in and accepts your request, the user will be redirected to the redirection endpoint along with an auth code. You then use the oauth2/1.0/exchange endpoint to receive an access token.

GET https://beta.eyewire.org/oauth2/1.0/auth

Redirect the end user to this authentication request url to kick off the process of receiving an access token.

Request

Response:

User will be redirected to the endpoint specified by the redirect_uri with the auth code in the query parameter.

Error Responses:

In the 'error' query parameter.

• access_denied - if the user denies giving your app permission.

Example Request

https://beta.eyewire.org/oauth2/1.0/auth?response_type=code&redirect_uri=http://website.com&client_id=141

Example Response

http://website.com/?code=f9u12m12e9we

Example Access Denied Response

http://website.com/?error=access_denied

POST oauth2/1.0/exchange

Returns an access code given an auth code. One time use, the auth code is invalidated.

Request

Response 200

Error Responses

• 400 - invalid_client, the client application information is invalid
• 400 - invalid_grant, the auth code is invalid, possibly already used.
• 400 - unsupported_grant_type, the grant_type is not authorization_code

Example Request

$ curl --data 'auth_code=f9u12m12e9we&secret=1234&redirect_uri=http://website.com&client_id=1&grant_type=authorization_code' https://beta-tasking.eyewire.org/oauth2/1.0/exchange

Example Response

{
  "access_token": "78q3ja8y",
  "token_type": "bearer"
}

Tasks

The task API is the one you'll be interacting with the most. It's used to assign tasks and submit player evaluations of them called validations. Each task consists of a set of image data and a seed piece. Each validation consists of the seed piece plus any segments the player selects. We aggregate submitted validations to form a consensus opinion of the actual structure of the cell.

POST 1.0/tasks/assign

Assigns a task to a user. You may optionally request that the task belongs to a specific cell.

Request

Response 200

The response contains volume objects that contain ids and bounds which are used to access tile and mesh data.

Error Responses

• 404 - no tasks available that fulfill the request, try with a different cell_id or lack of one.

Example Request

$ curl --data 'cell_id=450' https://beta-tasking.eyewire.org/1.0/tasks/assign?access_token=78q3ja8y

Example Response

{
  "id": 17444,
  "seeds": [245, 5025, 6500],
  "cell": 10,
  "channel_id": 63200,
  "segmentation_id": 63201,
  "bounds": {
    "min": {
      "x": 2930,
      "y": 4082,
      "z": 6482
    },
    "max": {
      "x": 3186,
      "y": 4338,
      "z": 6738
    }
  },
  "startingTile" : 5
}

POST 1.0/tasks/:id/submit

Submit a validation for a task. The validation is used to calculate a consensus of the segments that belong to the task. The validation will be analyzed for accuracy and given a suggested score.

Request

Response 200

Error Responses

Example request

$ curl --data 'status=finished&segments=1407,1880,3898,4506,4722,5028,5075,5444,3614,3888,4072,1540' https://beta-tasking.eyewire.org/1.0/tasks/563914/submit?access_token=d14fa82ab

Example Response

{
  "id": 40,
  "score": 60,
  "accuracy": 0.5983492834,
  "type": "normal"
}

Data

GET data.eyewire.org/volume/$volumeID/chunk/0/$x/$y/$z/tile/$slicing/$from:$to

This method allows users to retrieve a set of 128x128 sized images (tiles) of the specified chunk in the specified volume.

Request

Response 200

An array of

Example Request

http://data.eyewire.org/volume/63200/chunk/0/0/0/0/tile/xy/10:30

Example Response

[
  {
    "data": "data:image/jpeg;base64,/9j/4A...",
    "view": 1,
    "bounds": {
      "min": {
        "x": 2930,
        "y": 4082,
        "z": 6482
      },
      "max": {
        "x": 3186,
        "y": 4338,
        "z": 6738
      }
    }
  },
  ...
]

Notes:

• The returned Base64 strings contain line breaks (see RFC 2045). If your decoder has problems with those, you might want to strip them before decoding.

GET data.eyewire.org/volume/$volumeID/chunk/0/$x/$y/$z/mesh/$segmentID

This method allows users to retrieve the 3D model of a specified segment in the specified EyeWire chunk.

Request

Response

Sends back a pure binary representation of a degenerated triangle strip containing interleaved vertex positions and vertex normals. Degenerated triangle strip because some triangles collapse to lines on purpose, since it is impossible to describe some meshs with only one triangle strip.

If the mesh does not exist, the response is just empty.

Example Request

http://data.eyewire.org/volume/17096/chunk/0/1/1/0/mesh/2060

Example Response

0x0000: v1 vn1
0x0018: v2 vn2
0x0030: v3 vn3	# first triangle (1, 2, 3) complete
0x0048: v4 vn4	# second triangle (2, 3, 4) complete
0x0060: v5 vn5  # third triangle (3, 4, 5) complete
.
.
.

• All values are Little Endian, 4 Byte floats.

• v1 is the first vertex coordinate.

• vn1 is the first vertex normal.

• A vertex consists of three floats representing its X,Y,Z coordinates, in the given order.

• Vertex Coordinates are within the range [0 .. 1]

• Vertex Normals are normalized.

• TIP: There were reported cases of corrupt meshes, appearing to be invisible. You can identify them by looking for meshes where all vertex coordinates have values [0 .. 0.001].

Response Objects

Bounds Object

Contains a min and a max three dimensional coordinate. Represents a three dimensional block of space.

Example

"min": {
  "x": 2930,
  "y": 4082,
  "z": 6482
},
"max": {
  "x": 3186,
  "y": 4338,
  "z": 6738
}