The EyeWire structure

E2198

This part of the documentation is meant to describe some of the terms used in EyeWire and the API. If you are looking for more detailed information about how the dataset was obtained, feel free to check out the wiki pages.

The dataset is 4864 x 20992 x 13056 voxels large. A voxel is not a perfect cube, but has a size of 16.5 x 16.5 x 23 nm. All dimensions are based on EyeWires right-handed coordinate system (see image below)

xy-plane of the EyeWire dataset

Volume

The datasets consists of volumes. Each EyeWire volume for example is 256x256x256 voxels large and the overlapping region of two adjacent EyeWire volumes is 32 voxel rows large. Volumes are generated as necessary, i.e. a newly traced cell extends to a yet unexplored region.

Also note that the dataset is slightly tilted and some regions therefore don’t have any data/volumes.

Chunk

Each volume consists of smaller chunks (128^3 voxels). They don’t overlap.

Channel & Segmentation Images

There are two kinds of images in those subvolumes, depending on the volume type:

  • The EM-images, compressed to 8 bit greyscale .jpg files and
  • the 32 bit .png segmentation files

Colors in the segmentation images should be read as an unsigned integer value and refer to the segments ID.

Segment

All connected pixels of the same value are one segment. Note that even though volumes (and therefore segments) overlap, their segment ID is not necessarily the same!

Task

By choosing one or more identified segments in the overlapping regions of two volumes, it is possible to create a new task for players. A volume might contain many different tasks, sometimes even tasks of the very same neuron.

Validation

Finally, each player contributes his or her own solution for the given task. This validation is compared to those of other players. Segments traced by the majority of players form the consensus and are used to spawn new tasks.

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

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

Request

e.g. data.eyewire.org/volume/123456/chunk/0/0/1/0/tile/xz/16:18

Address:

  • $volumeID: integer, unique identifier for volume.
  • $mip: integer, MIP-level - must be 0.
  • $x, $y, $z: integer, the requested chunks position in the volume. For regular EyeWire volumes (256^3) it should be either 0 or 1 or higher for Omni cubes (see TIP below).
  • $slicing: string, the sectional plane, must be either xy, xz or zy.
  • $from: integer, first layer to be returned: [0 .. chunkDim)
  • $to: integer, first layer that is NOT returned: [from .. chunkDim]

The chunk size (chunkDim) for both EyeWire cubes and Omni cubes is 128.

TIP: It seems higher values for $x, $y, $z, $from and $to can be used to access areas outside the specified volume as long as the resulting coordinates stay within the dataset boundaries. Please use this “hack” with caution, as this behavior is neither really intended nor supported…

Response

In case of success, sends back a JSON array with information about the requested layers and the actual Base64 encoded .png (segmentation) or .jpg (channel) files:

Status: 200 OK [ { view: 2, bounds: { min: { x: 1586, y: 14306, z: 2674 }, max: { x: 1714, y: 14306, z: 2802 } }, data: "data:image\/png;base64,iVBOR..." }, { view: 2, bounds: { min: { x: 1586, y: 14307, z: 2674 }, max: { x: 1714, y: 14307, z: 2802 } }, data: "data:image\/png;base64,iVBOR..." } ]

  • view is just an integer representation for the requested sectional plane.
    • 1: XY_VIEW
    • 2: XZ_VIEW
    • 3: ZY_VIEW
  • bounds contains the position/bounding box dimensions of the layer in world space.
  • data contains the actual Base64 encoded image.

TIP: 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.

Errors

In case the $volumeID does not exist or $x, $y or $z are out of range, an empty response and HTML Code 500 (Internal Server Error) is returned.

Status: 500 Internal Server Error

An empty array might be returned if $mip != 0 or $to <= $from.

Status: 200 OK []

GET data.eyewire.org/volume/$volumeID/chunk/$mip/$x/$y/$z/mesh/$segmentID Get Mesh

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

Request

e.g. data.eyewire.org/volume/123456/chunk/0/1/0/0/mesh/12

Address:

  • $volumeID: integer, unique identifier for volume.
  • $mip: integer, MIP-level - must be 0.
  • $x, $y, $z: integer, the requested chunks position in the volume. For regular EyeWire volumes (256^3) it has to be either 0 or 1; or even higher for [Omni cubes][omni].
  • $segmentID: integer, the segment to load.

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.

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

  • All values are Little Endian, 4 Byte floats.
  • v1 is the first vertex position (x, y and z coordinate).
  • vn1 is the first vertex normal.
  • Vertex Coordinates are within the range [0.0 .. 1.0]
  • Vertex Normals are not necessarily 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].

GET data.eyewire.org/volume/$volumeID/segment/$segmentID Get Single Segment

This method allows users to retrieve basic information about a specified segment in the specified volume.

Request

e.g. data.eyewire.org/volume/123456/segment/12

Address:

  • $volumeID: integer, unique identifier for volume. However, the channel and segmentation volume ID will both return the same segment.
  • $segmentID: integer, the segment to load.

Response

Sends back a JSON wrapped object with information about position and size of the requested segment.

Status: 200 OK { $segmentID: { bounds: { min: { x: 1813, y: 14178, z: 2675 }, max: { x: 1819, y: 14186, z: 2678 } }, size: 105 } }

  • segmentID: integer, is the same specified in the request.
  • bounds: object, contains the position/bounding box dimensions of the segment in world space.
  • size: integer, is the size of the segment in voxel.

Errors

In case the $volumeID does not exist an empty response and HTML Code 500 (Internal Server Error) is returned.

Status: 500 Internal Server Error

An empty array (sic) is returned if $segmentID does not exist.

Status: 200 OK []

POST data.eyewire.org/volume/$volumeID/segment/enumerate_metadata Get Multiple Segments

This method allows users to retrieve basic information about multiple specified segments in the specified volume without combining them.

Request

e.g. data.eyewire.org/volume/$volumeID/segment/enumerate_metadata Body: segments[]=1&segments[]=20

Address:

  • $volumeID: integer, required, unique identifier for volume. However, the channel and segmentation volume ID will both return the same result.

Body:

  • segments: array of integer, required, the segment IDs to load.

Response

Sends back a JSON object, each key is one of the requested segment IDs and contains information about its position and size. If at least one segment can be found, the response will look like below and all not existing segments are simply dropped. See the Errors section at the bottom in case no segment IDs were found.

Status: 200 OK { "1": { "bounds": { "min": { "x": 1721, "y": 14163, "z": 2675 }, "max": { "x": 1747, "y": 14180, "z": 2683 } }, size: 1720 }, "20": { "bounds": { "min": { "x": 1729, "y": 14183, "z": 2675 }, "max": { "x": 1741, "y": 14200, "z": 2680 } }, size: 691 } }

  • The object keys are one of the specified segment IDs in the request.
  • bounds: object, contains the position/bounding box dimensions of the segment in world space.
  • size: integer, is the size of the segment in voxel.

Errors

In case the $volumeID does not exist an empty response and HTML Code 500 (Internal Server Error) is returned.

Status: 500 Internal Server Error

An empty array (sic) is returned if none of the $segmentIDs exist.

Status: 200 OK []

POST data.eyewire.org/volume/$volumeID/segment/merge_metadata Get Merged Segments

This method allows users to retrieve basic information about multiple specified segments in the specified volume by combining them.

Request

e.g. data.eyewire.org/volume/$volumeID/segment/merge_metadata Body: segments[]=1&segments[]=20

Address:

  • $volumeID: integer, required, unique identifier for volume. However, the channel and segmentation volume ID will both return the same result.

Body:

  • segments: array of integer, required, the segment IDs to load.

Response

Sends back a JSON object with information about position and size of the combined object of all specified segments.

Status: 200 OK { "bbox": { "min": { "x": 1721, "y": 14163, "z": 2675 }, "max": { "x": 1747, "y": 14200, "z": 2683 } }, "size": 2411 }

  • bbox: object contains the position/bounding box dimensions of the combined segments in the world space.
  • size: integer is the size of the combined segments in voxel.

Errors

In case the $volumeID does not exist an empty response and HTML Code 500 (Internal Server Error) is returned.

Status: 500 Internal Server Error

A dummy object is returned if none of the $segmentIDs exist:

Status: 200 OK { "bbox": { "min":{ "x":0, "y":0, "z":0 }, "max": { "x":0, "y":0, "z":0 } }, "size":0 }

NOTE: If only a few segments do not exist, they are just not added to the result. You won’t see a hint in the response. So be sure all segments exist before combining them.

GET eyewire.org/1.0/dataset Get Dataset List

This method lists all available datasets and general properties of each.

Request

eyewire.org/1.0/dataset

Response

Sends back a JSON array with basic information about all datasets:

Status: 200 OK [ { "id": 1, "name": "Eyewire", "description": "E2198 dataset in 256^3 volumes. Used for Eyewire.org", "overlap": 32, "min_overlap_volume": 262144, "created": "2013-11-21 18:08:39", "deleted": null, "completed": null, "lastmodified": null, "enable_comparisons": 0 }, { "id": 2, "name": "Omniwire", "description": "E2198 dataset in large volumes. Used for Omni.", "overlap": 127, "min_overlap_volume": 20971520, "created": "2014-02-04 15:33:42", "deleted": null, "completed": null, "lastmodified": null, "enable_comparisons": 1 } ]

  • id: integer, unique identifier for the dataset
  • overlap: integer, number of voxel rows the volumes in this dataset overlap.
  • min_overlap_volume: integer, overlapping volume of segments that is necessary to spawn a new task.
  • created: YYYY-MM-DD hh:mm:ss or null
  • deleted: YYYY-MM-DD hh:mm:ss or null
  • completed: YYYY-MM-DD hh:mm:ss or null
  • lastmodified: YYYY-MM-DD hh:mm:ss or null, last time these settings were updated.
  • enable_comparisons: integer, either 0 or 1. Comparison tasks are only generated in Omni.

GET eyewire.org/1.0/dataset/$datasetID Get Single Dataset

This method returns general properties of the specified dataset.

Request

e.g. eyewire.org/1.0/dataset/1

Address:

  • $datasetID, integer, required, the unique dataset identifier.

Response

Sends back a JSON object with basic information about the specified dataset:

Status: 200 OK { "id": 1, "name": "Eyewire", "description": "E2198 dataset in 256^3 volumes. Used for Eyewire.org", "overlap": 32, "min_overlap_volume": 262144, "created": "2013-11-21 18:08:39", "deleted": null, "completed": null, "lastmodified": null, "enable_comparisons": 0 }

  • id: integer, unique identifier for the dataset
  • overlap: integer, number of voxel rows the volumes in this dataset overlap.
  • min_overlap_volume: integer, overlapping volume of segments that is necessary to spawn a new task.
  • created: YYYY-MM-DD hh:mm:ss or null
  • deleted: YYYY-MM-DD hh:mm:ss or null
  • completed: YYYY-MM-DD hh:mm:ss or null
  • lastmodified: YYYY-MM-DD hh:mm:ss or null, last time these settings were updated.
  • enable_comparisons: integer, either 0 or 1. Comparison tasks are only generated in Omni.

GET eyewire.org/1.0/task Get Multiple Tasks Information

This method allows users to retrieve metadata of several tasks.

Request

e.g. eyewire.org/1.0/task?dataset=1&cell=533&max_weight=3

Address:

  • $taskID is the requested tasks unique ID.

Query:

  • dataset, integer, optional, the unique dataset identifier, if omitted: all datasets
    • 1: EyeWire
    • 2: Bomni
  • cell, integer, optional, the unique cell identifier, if omitted: all unfinished, visible cells
  • max_weight, float, optional, if specified, the maximum task weight

NOTE: Output is limited to the first 100 rows.

Response

Sends back an array with basic information about each matching task:

Status: 200 OK [ { "id": 420563, "weightsum": 3, "inspected_weight": 1, "segmentation_path": "\/usr\/local\/omni\/data\/omelette2\/x06\/y27\/x06y27z14_s1587_6323_3347_e1842_6578_3602.omni.files\/", "cell": 533, "depth": 1, "left_edge": 1244665, "right_edge": 1245330, "status": 0, "wiki_notes": "", "users": "Unclewilley,Nseraf,jamiexq,onechip,hhd6109", "parent": 420543, "allSize": null, "agreedSize": null }, ... ]

  • id: integer, the unique task identifier
  • weightsum: integer, not reliable…
  • inspected_weight: integer,
  • segmentation_path: string, path to the segmentation volume file on server
  • cell: integer, the unique ID of the cell this task belongs to
  • depth: integer, distance from root task
  • left_edge: integer, used for the internal B-tree structure.
  • right_edge: integer, used for the internal B-tree structure.
  • status: integer, one of the following:
    • 0: NORMAL
    • 3: TUTORIAL
    • 6: STASHED (does not appear in overview)
    • 10: FROZEN (not editable)
    • 11: DUPLICATE (all or part of this cube duplicates with another cube in a different cell)
  • wiki_notes: string, contains admin comments about this task. Not used in EyeWire.
  • users: string, comma separated list of player’s usernames who submitted this task.
  • parent: integer, the parent tasks ID that spawned this task.
  • allSize: null, currently not used
  • agreedSize: null, currently not used

GET eyewire.org/1.0/task/assign Get Random Task

This method assigns a random task from the available task pool to the authenticated player.

Request

e.g. eyewire.org/1.0/task/assign?cell=533

Query:

  • cell, integer, required, the unique cell identifier

Response

Sends back a JSON object with basic information about the assigned task:

Status: 200 OK { "id": 370013, "status": 11, "prior": { "segments": { "67": 1 }, "weight": 9.1999998092651 }, "segments": {}, "cell": 463, "data": { "channel": { "id": 2285, "metadata": { "uri": "\/usr\/local\/omni\/data\/omelette2\/x05\/y79\/x05y79z24_s1363_17971_5587_e1618_18226_5842.omni.files\/", "bounds": { "min": { "x": 1362, "y": 17970, "z": 5586 }, "max": { "x": 1618, "y": 18226, "z": 5842 } }, "resolution": { "x": 1, "y": 1, "z": 1 }, "type": 5, "chunkDims": { "x": 128, "y": 128, "z": 128 }, "vol_type": 1, "mipLevel": 0 } }, "segmentation": { "id": 17305, "metadata": { "uri": "\/usr\/local\/omni\/data\/omelette2\/x05\/y79\/x05y79z24_s1363_17971_5587_e1618_18226_5842.omni.files\/", "bounds": { "min": { "x": 1362, "y": 17970, "z": 5586 }, "max": { "x": 1618, "y": 18226, "z": 5842 } }, "resolution": { "x": 1, "y": 1, "z": 1 }, "type": 4, "chunkDims": { "x": 128, "y": 128, "z": 128 }, "vol_type": 2, "mipLevel": 0 } } }, "tutorial": { "instructions": null, "sequence": null, "difficulty": null, "train_max": null, "assist_max": null, "truth": null } }

  • id: integer, requested task ID
  • status: integer, one of the following:
    • 0: NORMAL
    • 3: TUTORIAL
    • 6: STASHED (does not appear in overview)
    • 10: FROZEN (not editable)
    • 11: DUPLICATE (all or part of this cube duplicates with another cube in a different cell)
  • prior: object
    • segments: object, contains a key-value pairs for all segments of this tasks seed piece. Key is the segmentID, value is ‘1’
    • weight: float, Combined weight of all validated players who submitted this task:
      • GrimReaper: 1,000,000.0
      • Scythes (using special power): 2.0
      • Regular players: 1.0
      • Demoted players: 0.1
  • segments: object, always empty
  • cell: integer, the unique ID of the cell this task belongs to
  • data: object,
    • channel / segmentation: object
      • id: integer, the unique ID of the volume this task belongs to
      • metadata: object
        • uri: string, path to file on server
      • bounds: object
        • min, max: object
          • x, y, z: integer, bounding box coordinates of the task.
            • resolution: object
        • x, y, z: integer, always 1 for each dimension.
          • type: integer
            • 1: INT8
            • 2: UINT8
            • 3: INT32
            • 4: UINT32 (used for .png segmentation images)
            • 5: FLOAT (used for .jpg channel images)
      • chunkDims: object
        • x, y, z: integer, always 128 for each dimension.
          • vol_type: integer
            • 1: CHANNEL
            • 2: SEGMENTATION
          • miplevel: integer, always 0
  • tutorial: object, all values always ‘null’ (even for tutorial cubes)

Errors

In case the cell parameter was omitted, or the specified cell does not exist / has no available tasks, an empty task object is returned:

Status: 200 OK { "id": null, "status": null, "prior": { "segments": null, "weight": null }, "segments": {}, "cell": null, "data": { "channel": { "id": null, "metadata": null }, "segmentation": { "id": null, "metadata": null } }, "tutorial": { "instructions": null, "sequence": null, "difficulty": null, "train_max": null, "assist_max": null, "truth": null } }

GET eyewire.org/1.0/task/$taskID Get Single Tasks Information

This method allows users to retrieve information about the specified task.

Request

e.g. eyewire.org/1.0/task/370013

Address:

  • $taskID is the requested tasks unique ID.

Response

Sends back a JSON object with basic information about the task:

Status: 200 OK { "id": 370013, "status": 11, "prior": { "segments": { "67": 1 }, "weight": 9.1999998092651 }, "segments": {}, "cell": 463, "data": { "channel": { "id": 2285, "metadata": { "uri": "\/usr\/local\/omni\/data\/omelette2\/x05\/y79\/x05y79z24_s1363_17971_5587_e1618_18226_5842.omni.files\/", "bounds": { "min": { "x": 1362, "y": 17970, "z": 5586 }, "max": { "x": 1618, "y": 18226, "z": 5842 } }, "resolution": { "x": 1, "y": 1, "z": 1 }, "type": 5, "chunkDims": { "x": 128, "y": 128, "z": 128 }, "vol_type": 1, "mipLevel": 0 } }, "segmentation": { "id": 17305, "metadata": { "uri": "\/usr\/local\/omni\/data\/omelette2\/x05\/y79\/x05y79z24_s1363_17971_5587_e1618_18226_5842.omni.files\/", "bounds": { "min": { "x": 1362, "y": 17970, "z": 5586 }, "max": { "x": 1618, "y": 18226, "z": 5842 } }, "resolution": { "x": 1, "y": 1, "z": 1 }, "type": 4, "chunkDims": { "x": 128, "y": 128, "z": 128 }, "vol_type": 2, "mipLevel": 0 } } }, "tutorial": { "instructions": null, "sequence": null, "difficulty": null, "train_max": null, "assist_max": null, "truth": null }, "weightsum": 9, "parent": 370004, "users": "ronin,nkem,lobusparietalis,blackblues,twister2,Andrearwen,MaraTara,mardim2,ginny,1sigor", "wiki_notes": "", "duplicates": [ { "task_id": 275114, "duplicate_segs": [ 3980 ] } ] }

  • id: integer, requested task ID
  • status: integer, one of the following:
    • 0: NORMAL
    • 3: TUTORIAL
    • 6: STASHED (does not appear in overview)
    • 10: FROZEN (not editable)
    • 11: DUPLICATE (all or part of this cube duplicates with another cube in a different cell)
  • prior: object
    • segments: object, contains a key-value pairs for all segments of this tasks seed piece. Key is the segmentID, value is ‘1’
    • weight: float, Combined weight of all validated players who submitted this task:
      • GrimReaper: 1,000,000.0
      • Scythes (using special power): 2.0
      • Regular players: 1.0
      • Demoted players: 0.1
  • segments: object, always empty
  • cell: integer, the unique ID of the cell this task belongs to
  • data: object,
    • channel / segmentation: object
      • id: integer, the unique ID of the volume this task belongs to
      • metadata: object
        • uri: string, path to file on server
      • bounds: object
        • min, max: object
          • x, y, z: integer, bounding box coordinates of the task.
            • resolution: object
        • x, y, z: integer, always 1 for each dimension.
          • type: integer
            • 1: INT8
            • 2: UINT8
            • 3: INT32
            • 4: UINT32 (used for .png segmentation images)
            • 5: FLOAT (used for .jpg channel images)
      • chunkDims: object
        • x, y, z: integer, always 128 for each dimension.
          • vol_type: integer
            • 1: CHANNEL
            • 2: SEGMENTATION
          • miplevel: integer, always 0
  • tutorial: object, all values always ‘null’ (even for tutorial cubes)
  • weightsum: integer, deprecated, use prior->weight instead
  • parent: integer, the parent tasks ID that spawned this task.
  • users: string, comma separated list of player’s usernames who submitted this task.
  • wiki_notes: string, contains admin comments about this task. Not used in EyeWire.
  • duplicates: array of objects, only visible with ADMIN privileges
    • task_id: integer, taskID of the duplicate
    • duplicate_segs: array of integer
      • segment ID(s) traced in both tasks

GET eyewire.org/1.0/task/$taskID/aggregate Get Task Aggregate

This method returns the current consensus for the specified task.

Access restricted to:

  • Admins
  • Scouts
  • Scythes

Request

e.g. eyewire.org/1.0/task/370013/aggregate

Address:

  • $taskID is the requested tasks unique ID.

Response

Sends back a JSON object with all segments that are considered to be correct and their confidence:

Status: 200 OK { "completed": 0, "segments": { "62": 0.8913043478613, "67": 1, "172": 0.8913043478613, ... }, "weight": 9.1999998092651 }

  • completed: integer, 1 if the task was marked complete by an admin, else 0.
  • segments: object
    • segmentID: float, the confidence for this segment ID; 1 means all players included the segment in their trace.
  • weight: float, Combined weight of all validated players who submitted this task:
    • GrimReaper: 1,000,000.0
    • Scythes (using special power): 2.0
    • Regular players: 1.0
    • Demoted players: 0.1

NOTE: This call will only return segments with a certain confidence value. This threshold is calculated based on the cell type and current weight:

  • Omni / Starburst cells: min(0.99, e^(-0.32 * weight) + 0.22)
  • Other cells: min(0.99, e^(-0.16 * weight) + 0.20)

min(0.99, e^(-0.32 * weight) + 0.22), min(0.99, e^(-0.16 * weight) + 0.20)

POST eyewire.org/1.0/task/$taskID/annotate Post Task Annotation

Add task annotations to this task (such as branch complete).

Access restricted to:

  • Admins
  • Scouts
  • Scythes

Request

e.g. eyewire.org/1.0/task/370013/annotate

Address:

  • $taskID is the requested tasks unique ID.

Body:

  • type: string, required, is the desired annotation
    • branch-complete (admins)
    • branch-scythe-complete (scythes and admins)
    • branch-incomplete (scythes and admins)
    • flag (scouts, scythes and admins)
  • descendants: boolean, optional, whether descendant cubes should be marked as well, default is ‘true’

NOTE: * Scythes cannot change tasks that were marked as complete by admins. * descendants is ignored when used in combination with flag

Response

Sends back a JSON array with a success message and (only when using ‘flag’) a score:

Status: 200 OK [ "success": true, "score": 50 ]

success: boolean, always true score: 50 for a previously not flagged cube, else 0.

Errors

If the user is not a scout, scythe or admin, an empty page is returned with status 403: Status: 403 Forbidden

If type is not recognized, an empty page is returned with status 401: Status: 401 Bad Request

If the method was not successful (e.g. a scythe trying to change admin completed branches), an empty page is returned with status 500: Status: 500 Internal Server Error

GET eyewire.org/1.0/task/$taskID/ancestors Get Task Ancestors

This method returns the ancestor tasks of the specified task.

Access restricted to:

  • Admins
  • Scouts
  • Scythes

Request

e.g. eyewire.org/1.0/task/370013/ancestors

Address:

  • $taskID is the requested tasks unique ID.

Response

Sends back an array with all ancestor tasks:

Status: 200 OK [369977,369978,369986,369995,370004]

  • array of integers: sorted task IDs of ancestors. First entry is the root of the cell.

GET eyewire.org/1.0/task/$taskID/descendents Get Task Descendents

This method returns the descendent tasks of the specified task.

Access restricted to:

  • Admins
  • Scouts
  • Scythes

Request

e.g. eyewire.org/1.0/task/370013/descendents

Address:

  • $taskID is the requested tasks unique ID.

Response

Sends back an array with all descendent tasks:

Status: 200 OK [376274,376317]

  • array of integers: sorted task IDs of descendents. First entry is the oldest child of the specified task.

GET eyewire.org/1.0/task/$taskID/hierarchy Get Task Hierarchy

This method returns a combination of ancestor and descendent tasks of the specified task.

Access restricted to:

  • Admins
  • Scouts
  • Scythes

Request

e.g. eyewire.org/1.0/task/370013/hierarchy?depth=2

Address:

  • $taskID is the requested tasks unique ID.

Query:

  • depth, integer, optional, the desired depth in both directions, default is 9000000 (or unlimited)

Response

Sends back a JSON object with two arrays with all ancestor and descendent tasks:

Status: 200 OK { "ancestors": [369995,370004], "descendents":[376274,376317] }

  • ancestors, array of integers, sorted task IDs of ancestors, limited to depth
  • descendents, array of integers, sorted task IDs of descendents, limited to depth

NOTE: descendents might of course have more than depth entries, if one of the descendent tasks had more than one child.

GET eyewire.org/1.0/task/$taskID/neighbors Get Task Neighbors

This method returns information about existing neighboring volumes of the specified tasks volume.

Access restricted to:

  • Admins
  • Scouts
  • Scythes

Request

e.g. eyewire.org/1.0/task/420878/neighbors

Address:

  • $taskID is the requested tasks unique ID.

Response

Sends back an array of up to 6 objects, one for each existing neighboring volume:

Status: 200 OK [ { "x": 1, "y": 0, "z": 0 }, { "x": 0, "y": 1, "z": 0 }, { "x": 0, "y": 0, "z": 1 }, { "x": 0, "y": 0, "z":-1 }, { "x": 0, "y":-1, "z": 0 } ]

  • array of objects x, y, z**: integer, the position of an existing neighbor relative to the specified task

NOTE: * The only missing neighbor in this example is { "x": -1, "y": 0, "z": 0 }, so there is a volume missing “below” this task. * Volumes are added only when needed. Therefore, not all tasks with a missing neighbor have to be at the dataset boundary.

GET eyewire.org/1.0/task/$taskID/duplicates Get Task Duplicates

This method returns information about possible cross-cell duplicates of the specified task.

Access restricted to:

  • Admins

Request

e.g. eyewire.org/1.0/task/437356/duplicates

Address:

  • $taskID is the requested tasks unique ID.

Response

Sends back an array of all tasks that contain at least one shared segment (and it’s ID):

Status: 200 OK [ { "task_id": 347861, "duplicate_segs": [631,...] }, ... ]

  • array of objects task_id: integer, the unique identifier of a task that shares at least one segment with the specified task. duplicate_segs: array of integer, the segment ID that is shared between both tasks.

Errors

If the user is not authenticated an empty page is returned and status 404: Status: 404 Not Found

If the user is authenticated, but not an admin, an empty page is returned and status 403: Status: 403 Forbidden

If none of the above, an empty page is returned and status 401: Status: 401 Bad Request

PUT eyewire.org/1.0/task/$taskID/notes Put Task Notes

This method adds a text note to the specified task.

Access restricted to:

  • Admins

Request

e.g. eyewire.org/1.0/task/305018/notes

Address:

  • $taskID is the requested tasks unique ID.

Response

Sends back plain text, if a note was found:

Status: 200 OK dj: Merger at 2382 9278 3944. Others maybe at 2404 10562 3410 and 3085 10257 3579. Not sure what's up at 2389 9525 3083.

Errors

If the user is not authenticated or no note was found an empty page is returned and status 404: Status: 404 Not Found

If the user is authenticated, but not an admin, an empty page is returned and status 403: Status: 403 Forbidden

If none of the above, an empty page is returned and status 401: Status: 401 Bad Request

GET eyewire.org/1.0/task/$taskID/notes Get Task Notes

This method returns text notes about the specified task.

Access restricted to:

  • Authenticated Users

Request

e.g. eyewire.org/1.0/task/305018/notes

Address:

  • $taskID is the requested tasks unique ID.

Response

Sends back plain text, if a note was found:

Status: 200 OK dj: Merger at 2382 9278 3944. Others maybe at 2404 10562 3410 and 3085 10257 3579. Not sure what's up at 2389 9525 3083.

Errors

If the user is not authenticated or no note was found an empty page is returned and status 404: Status: 404 Not Found

If none of the above, an empty page is returned and status 401: Status: 401 Bad Request

GET eyewire.org/1.0/cell Get Active Cell List

This method returns the list of all active cells.

Request

e.g. eyewire.org/1.0/cell?dataset=1

Query:

  • dataset, integer, optional, the unique dataset identifier, if omitted: 0 (undefined)
    • 1: EyeWire
    • 2: Bomni

Response

Sends back an array with basic information about each currently active cell of the specified dataset:

Status: 200 OK [ { "name": "Mystery #234", "difficulty": 1, "celltype": null, "description": "A mystery cell whose type should be found as the tracing progresses.", "target": 1500, "completed": null, "cell": 524, "count": 454, "underconfident": 282, "weight": 100, "growth": 141, "avail": 346 }, ... ]

  • name: string, the cell name
  • difficulty: integer, used to check if a player is qualified to play the cell
    • 1: Regular/Mystery Cell, passing the first EyeWire tutorial is required.
    • 2: Starburst/Lightning Cell, passing the Starburst / Lightning Challenge is required.
    • 3: Bomni Cell, only used for the exhibitioned cell “Bipolar Cell”.
  • celltype: string, not necessarily a real cell type, kinda deprecated because of the difficulty setting above:
    • NULL / any: a Regular/Mystery Cell
    • sac: used to label Starburst Amacrine Cells
    • omni: cells that are traced at HQ in Omni
    • evil: used to identify cells for Evil Cubes competitions.
  • description: string, the small info text in the EyeWire cell overview.
  • target: integer, poor estimate for the total number of tasks.
  • completed: YYYY-MM-DD or NULL, date when cell was completed (or NULL if not yet finished)
  • cell: integer, The unique cell ID.
  • count: integer, The current number of tasks in this cell.
  • underconfident: integer, The current number of tasks in this cell with weigth < 2.5
  • weight: integer, Priority/Likeliness of this cell being assigned to new players.
  • growth: integer, Number of newly spawned cubes within the last 24 hours. (Counts stashed tasks/duplicates as well)
  • avail: integer, Remaining number of playable tasks. If authenticated, it will also substract authenticated users submitted tasks.

GET eyewire.org/1.0/cell/$cellID Get Single Cell

This method returns metadata for a given cell ID.

Request

e.g. eyewire.org/1.0/cell/533

Address:

  • $cellID, integer, required, the unique cell identifier.

Response

Sends back an object with basic information about the specified cell:

Status: 200 OK { "id": 533, "name": "Mystery #243", "description": "A mystery cell whose type should be found as the tracing progresses.", "created": "2014-09-29 11:59:52", "completed": null, "target": 1500, "celltype": null, "dataset_id": 1, "size": 1383 }

  • id: integer, the unique cell identifier
  • name: string, the cell name
  • description: string, the small info text in the EyeWire cell overview.
  • created: YYYY-MM-DD hh:mm:ss, the time this cell was uploaded.
  • completed: YYYY-MM-DD or NULL, date when cell was completed (or NULL if not yet finished)
  • target: integer, poor estimate for the total number of tasks.
  • celltype: string, not necessarily a real cell type, kinda deprecated because of the difficulty setting above:
    • NULL / any: a Regular/Mystery Cell
    • sac: used to label Starburst Amacrine Cells
    • omni: cells that are traced at HQ in Omni
    • evil: used to identify cells for Evil Cubes competitions.
  • dataset_id: integer, the dataset this cell belongs to.
  • size: integer, The current number of tasks in this cell.

GET eyewire.org/1.0/cell/$cellID/tasks Get Cell Tasks

This method returns the all the necessary task information for displaying a cell in the EyeWire overview.

Request

e.g. eyewire.org/1.0/cell/11/tasks

Address:

  • $cellID, integer, required, the unique cell identifier.

Response

Sends back an object with information about all tasks of the specified cell:

Status: 200 OK { "root": { "min": { "x": 1362, "y": 9906, "z": 4690 }, "max": { "x": 1618, "y": 10162, "z": 4946 } }, "world": { "min": { "x":0, "y":0, "z":0 }, "max": { "x":4864, "y":20992, "z":13056 } }, "tasks": [ { "id":10532, "status":0, "confidence":1, "uconfidence":0.24005100131035, "weight":24, "created":0.99999981517896, "lastmodified":"2014-10-07 17:54:26", "bounds": { "min": { "x":1362, "y":9906, "z":4690 }, "max": { "x":1618, "y":10162, "z":4946 } } }, ... ] }

  • root: object
    • min, max: object
      • x, y, z: integer, bounding box coordinates of the root cube of this task.
  • world: object
    • min, max: object
      • x, y, z: integer, bounding box coordinates of the world this cell belongs to (E2198).
  • tasks: array of objects
    • id: integer, the tasks unique identifier
    • status: integer, one of the following:
      • 0: NORMAL
      • 3: TUTORIAL
      • 6: STASHED (does not appear in overview)
      • 10: FROZEN (not editable)
      • 11: DUPLICATE (all or part of this cube duplicates with another cube in a different cell)
    • confidence: float
    • uconfidence: float
    • weight: integer
    • created: float
    • lastmodified: YYYY-MM-DD hh:mm:ss
    • bounds: object
      • min, max: object
        • x, y, z: integer, bounding box coordinates of the task.

NOTE: * If a task was never modified (newly created), lastmodified will show 0000-00-00 00:00:00. Be sure to catch those before trying to convert the string into a DateTime.

GET eyewire.org/1.0/cell/welcome Get Cell List - Welcome

Specialized function that fetches the cells that players get when they first load EyeWire.

Request

eyewire.org/1.0/cell/welcome

Response

Sends back an array with basic information about each cell available for new players:

Status: 200 OK [ { "name": "Mystery #234", "difficulty": 1, "celltype": null, "description": "A mystery cell whose type should be found as the tracing progresses.", "target": 1500, "completed": null, "cell": 524, "count": 454, "underconfident": 282, "weight": 100, "growth": 141, "avail": 346 }, ... ]

  • name: string, the cell name
  • difficulty: integer, used to check if a player is qualified to play the cell
    • 1: Regular/Mystery Cell, passing the first EyeWire tutorial is required.
    • 2: Starburst/Lightning Cell, passing the Starburst / Lightning Challenge is required.
    • 3: Bomni Cell, only used for the exhibitioned cell “Bipolar Cell”.
  • celltype: string, not necessarily a real cell type, kinda deprecated because of the difficulty setting above:
    • NULL / any: a Regular/Mystery Cell
    • sac: used to label Starburst Amacrine Cells
    • omni: cells that are traced at HQ in Omni
    • evil: used to identify cells for Evil Cubes competitions.
  • description: string, the small info text in the EyeWire cell overview.
  • target: integer, poor estimate for the total number of tasks.
  • completed: YYYY-MM-DD or NULL, date when cell was completed (or NULL if not yet finished)
  • cell: integer, The unique cell ID.
  • count: integer, The current number of tasks in this cell.
  • underconfident: integer, The current number of tasks in this cell with weigth < 2.5
  • weight: integer, Priority/Likeliness of this cell being assigned to new players.
  • growth: integer, Number of newly spawned cubes within the last 24 hours. (Counts stashed tasks/duplicates as well)
  • avail: integer, Remaining number of playable tasks.

NOTE: * Unlike Get Active Cell List, this call seems to count cubes and cells marked as ‘complete’ as “available”… * Cells are sorted by weight (descending) and growth (ascending)

GET eyewire.org/1.0/cell/$cellID/heatmap/scythe Get Cell Scythemap

This method returns information about tasks for creating the Scythe/Admin heatmap.

Access restricted to:

  • Admins
  • Scouts
  • Scythes

Request

e.g. eyewire.org/1.0/cell/11/heatmap/scythe

Address:

  • $cellID, integer, required, the unique cell identifier.

Response

Sends back an object with task IDs for specially marked cubes:

Status: 200 OK { "scythed": [294157,294156,...,10576], "review": [11025], "reaped": [177605,87613,...,10576], "complete":[10826,11136,...,75887], "scythecomplete":[], "frozen":[10531,10537,...,206451], "duplicate":[12489] }

  • scythed: array of integer, task IDs where scythes modified consensus (weight 2.0).
  • review: array of integer, task IDs where scouts flagged a cube.
  • reaped: array of integer, task IDs where admins modified consensus (weight 1,000,000.0).
  • complete: array of integer, task IDs marked as complete by admins (can’t be assigned to players).
  • scythecomplete: array of integer, task IDs marked as complete by scythes.
  • frozen: array of integer, task IDs frozen by admins (can’t be assigned to players, won’t spawn new cubes).
  • duplicate: array of integer, task IDs that share at least one segment with a different cell.

POST eyewire.org/internal/account/authenticate/standard Authentication - Standard

Provides authentication via username/password.

Request

eyewire.org/internal/account/authenticate/standard

Body:

  • username, string, required, can also be the users email address
  • password, string, required

Response

Status: 200 OK { "success": true, "user": { "rank":1, "id":69071 } }

  • rank: integer, 1 for regular user, 9 for admin
  • id: integer, the user ID

Cookie:

  • authentication-token=$userid%$token;
    • $userid: integer, the user ID,
    • $token: string, the authentication token, used for connecting to the websocket.

NOTE: Some API calls need this cookie to return (additional) information based on authenticated users rank or roles.

Errors

Status: 200 OK { "error": { "username": "zero-length", "password": "zero-length" }, "success": false, "user": null }

  • error: object
    • username: string
      • zero-length if no username/email address was provided
      • available-username if username is unknown
      • available-email if email address is unknown
    • password: string
      • zero-length if no password was provided
      • invalid if username known, but password doesn’t match.

NOTE: if the email address is known, but the password is incorrect, the error object appears to be empty.