Skip to content

Latest commit

 

History

History
106 lines (87 loc) · 7.37 KB

README.md

File metadata and controls

106 lines (87 loc) · 7.37 KB
Raw

Getting started

Overview

CircleCI License: MIT

The brainsprite javascript library turns an image that includes a stack of brain slices in sagital plane, like this one:

into three brain slices in different planes (sagital, coronal, axial) that can be used to explore the brain interactively - click here for a basic live demo >:

A key feature of the brainsprite viewer is that it is fast to load, because it relies on .jpg images. The slice rendering is also generated with html5 canvas, enabling smooth animations between slices.

Sprites

For brainsprite to work, you will need to generate a sprite image (also known as mosaic) such as the one above, and specify the size of each slice (in pixel). The sagital slices are assumed to be in the same orientation as the MNI space (X: left to right, Y: posterior to anterior, Z: ventral to dorsal), and stacked from left to right row by row. The number of slices per row can be anything, but generating a sprite image that is roughly square will work best. A full example of sprite image (MNI space at 1 mm isotropic) can be found here.

Basic example

The first thing to do is to add a div in your html with an empty canvas as well as the sprite image, which will be hidden:

<div>
    <canvas id="3Dviewer">
    <img id="spriteImg" class="hidden" src="sprite.jpg">
</div>

Then you include the brainsprite minified library (and jquery for the $( window ).load(function() instruction below, although brainsprite itself does not use jquery):

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.6.1/jquery.min.js"></script>
<script type="text/javascript" src="../brainsprite.min.js"></script>

Finally, once the page is loaded, you call brainsprite to create a brainSlice object:

 <script>
  $( window ).load(function() {
    var brain = brainsprite({
      canvas: "3Dviewer",
      sprite: "spriteImg",
      nbSlice: { 'Y':233 , 'Z':189 }
    });
  });
  </script>

The three parameters are canvas: the ID of the canvas where the brain slices will be added; sprite: the ID of the sprite image; and, nbslice the size, along axis Y and Z, of each slice inside the sprite. The call to brainsprite will automatically generate the slices. Try clicking on the slices to navigate the volume.

You can check the full code of the demo here and check a live demo >.

API

Coordinates

The option flagCoordinates will turn on a display of each slice number at the bottom of the canvas:

      flagCoordinates: true,

You can check the full code of the demo here and check a live demo >.

It is also possible to specify a voxel size (isotropic, i.e. the same dimension in the X, Y and Z axis), as well as an origin, i.e. which voxel has coordinates 0, 0, 0. Note that no rotations/shears are supported, as the volume is assumed to be resampled in MNI space.

      flagCoordinates: true,
      origin: {X: 98, Y:134, Z:72},
      voxelSize: 1,

Here is a full example that reports MNI coordinates for the voxel associated with the click, along with a live demo >.

Click events

It is possible to attach a function that will be triggered when the user clicks on the brain viewer. The object passed to the function is called brain and contains all the info about the brain viewer, including the current slice coordinates. In this example, an alert is triggered that reports current coordinates:

      onclick: function showCoordinates(brain) {
        alert("Slice coordinates: x=" + brain.coordinatesSlice.X + " , y=" + brain.coordinatesSlice.Y + " ,z=" + brain.coordinatesSlice.Z);
      },

Here is a full example that pops up an alert with MNI coordinates for the voxel associated with the click, along with a live demo >.

Overlay

It is possible to add an overlay to a volume. The overlay is loaded as a sprite image and needs to be in the same space. The resolution of the background and overlay can differ by a constant factor. We first start by adding a second (hidden) sprite image in the page:

<div id="div_viewer">
    <canvas id="3Dviewer">
    <img id="spriteImg" class="hidden" src="sprite.jpg">
    <img id="overlayImg" class="hidden" src="dmnSprite.png">
</div>

Then, we add the description of the overlay (including the number of voxels in the Y and Z dimensions) to the call to brainsprite. Note that the sprite can have a different organization than the background, in terms of the number of rows and columns.

      overlay: {
        sprite: "overlayImg",
        nbSlice: {'Y':79 , 'Z':63 }
      },

Here is a full example adding a functional connectivity map to a structural MRI, along with a live demo >.

Colors

It is possible to tweak the color of the background that is applied behind the slices, as well as the color of the text being applied, using properties passed to brainSprite.

      colorBackground: "#FFFFFF",
      colorFont: "#000000"

Here is an example using a template with a white background, and black fonts, as well as the live demo >.