How To Use Atlases

Building an Atlas into Papaya

The Papaya project comes with a Talairach/MNI brain atlas. See the releases folder for pre-built versions of Papaya that include this atlas. To create a custom build of Papaya which includes this atlas, specify the atlas parameter:

papaya-builder.sh -atlas

To use your own atlas in Papaya, first make sure it follows the FSL Atlas Specification, then specify it when building:

papaya-builder.sh -atlas myAtlas.xml

In the example above, the myAtlas.xml file will specify the relative location of the atlas NIFTI file. Both the XML and NIFTI file are needed to use the atlas in Papaya.

Atlas Usage

The included atlas has both Talairach and MNI spaces available. By default, the Talairach atlas will load. To load in MNI space instead, specify the following parameter:

params["atlas"] = "MNI (Nearest Grey Matter)";

Typically, papaya-builder.sh will embed the URL location of the atlas image inside papaya.js. However, if you want to place the atlas image at an alternative location, you can use:

params["atlasURL"] = "atlas/myAtlas.nii.gz";

Atlas Notes

• Only one <images> tag in an XML file will be recognized.
• For probabilistic atlases, only the <summaryimagefile> tag is currently supported.
• The following are considered delimiters in a label string . , / :

Atlas Spec Extensions

Papaya supports a few minor extensions to the FSL Atlas Specification.

• A maximum of 4 label parts can be displayed. If an atlas contains labels with more parts than this, use a <display> tag to specify which labels to use. For example, to specify that the first, second, fourth, and fifth parts are to be displayed:

<display>*.*. .*.*</display> 

• A <transform> tag can be used to transform the input coordinate. This tag should contain 16 space-delimited values.
• A <transformedname> tag can be used to differentiate between the transformed and non-transformed state.

If an atlas has a transformedname tag, you can load it by default using the parameter:

params["atlas"] = "myTransformedAtlasName";

How to Make a Custom Atlas

You can create a custom atlas that doesn't rely on external image or JSON data. To do so, implement getLabelAtCoordinate. It is passed six arguments: X, Y, Z of the world space coordinate and the X, Y, Z of the image index.

Instantiate the object and assign it to the global variable papaya.Container.atlas.

var myCustomAtlas = function() { };

myCustomAtlas.prototype.getLabelAtCoordinate = function (xWorld, yWorld, zWorld, xIndex, yIndex, zIndex) {
    if (xWorld < 0) {
        return ["Left"]
    } else {
        return ["Right"]
    }
};

papaya.Container.atlas = new myCustomAtlas();