Configuration

Michael Martinez edited this page Jul 2, 2018 · 54 revisions

Basics

Papaya can be configured to launch images or turn on/off certain features via a script block. In the below example, an array of parameters called 'params' is created and referenced in the Papaya div as data-params="params".

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
    <head>
        <link rel="stylesheet" type="text/css" href="papaya.css" />
        <script type="text/javascript" src="papaya.js"></script>
        <title>Papaya Viewer</title>

        <script type="text/javascript">
            var params = [];
            params["images"] = ["data/myImage.nii.gz"];
        </script>
    </head>

    <body>
        <div class="papaya" data-params="params"></div>
    </body>
</html>

Images

Image URL references can be specified using the images parameter.

params["images"] = ["data/myBaseImage.nii.gz"];

More than one image can be loaded at at time.

params["images"] = ["data/myBaseImage.nii.gz", "data/myOverlay.nii.gz"];

If your image consists of multiple files (e.g., a DICOM series), group the files as an array.

params["images"] = [["data/series1image1", "data/series1image2"]];

Image data can be loaded as a Base64 encoded string. This may be especially useful when creating a build of Papaya that is to load locally. In this case, use the parameter encodedImages and reference a string of the variable name that contains the encoded data.

var myEncodedDataRef = someEncodedData;
params["encodedImages"] = ["myEncodedDataRef"];

Images can also be referenced as files or raw data (ArrayBuffer).

params["files"] = [myFile];

params["binaryImages"] = [myArrayBuffer]; // single file
params["binaryImages"] = [[mySeriesAb1, mySeriesAb2, mySeriesAb3]];  // a DICOM series

Image Options

Certain options can be applied to image instances. To specify an image, create a parameter of its name (without any path information) and pass in a JavaScript object containing the options.

params["myOverlayImage.nii.gz"] = {"min": 4, "max": 8, "lut": "Red Overlay"};
  • alpha: The overlay image alpha level (0 to 1).
  • icon: Image url to use as the toolbar icon (rescaled to 18x18).
  • interpolation: If true, image will have a smooth display (default true).
  • labels: For a series, an array of labels to be displayed in the viewer title.
  • lut: The color table name (built-in or custom).
  • negative_lut: The color table name (built-in or custom) used by the negative side of the parametric pair.
  • max: The display range maximum.
  • maxPercent: The display range maximum as a percentage of image max.
  • min: The display range minimum.
  • minPercent: The display range minimum as a percentage of image max.
  • rotation: An array of rotation degrees about each of the three axes (e.g., [0,0,45] = 45 degree rotation about Z axis)
  • rotationPoint: The point of rotation. Options are "center" (default), "origin", or "crosshairs".
  • parametric: If true, loads two views of the same image, one in the positive and one in the negative range. (Also see combineParametric.)
  • symmetric: If true, sets the negative range of a parametric pair to the same size as the positive range.

Color Tables

Papaya includes several color tables: "Grayscale", "Spectrum", "Overlay (Positives)", "Overlay (Negatives)", "Hot-and-Cold", "Gold", "Red Overlay", "Green Overlay", "Blue Overlay". To apply a color table to a specific image when the page loads, specify it in the lut parameter:

params["myImage.nii.gz"] = {lut: "Spectrum"};

Besides these included color tables, you can also create your own custom color tables.

Surfaces

Papaya can read GIFTI and Mango surface data. In order to load a surface, you must first load the associated image volume. To load one or more surfaces, use the surfaces parameter:

params["surfaces"] = ["data/mySurface.surf.gii"];

Surface data is drawn in grayscale unless the file contains color data. You can also specify a solid color as an [r, g, b] array and/or an alpha level:

params["mySurface.surf.gii"] = {color: [1, 0, 0], alpha: 0.5};  // red translucent surface

Other Options:

  • icon: Image url to use as the toolbar icon (rescaled to 18x18).

The surface data may or may not contain RGBA information, but it must contain vertices and triangle indices. The Mango surface viewer can export data in GIFTI or Mango format which is compatible with this feature. FreeSurfer GIFTI and FSL VTK data should also be compatible.

DTI

Papaya can render DTI data both as RGB and vector lines.

  • dti: true to indicate it should be rendered as DTI data (must be 3 series points).
  • dtiColors: true to display as RGB (default is true).
  • dtiLines: true to display as vector lines (default is false). If dtiColors is also true, colored lines will be displayed.
  • dtiMod: true to indicate this image is used to modulate a DTI image (see dtiRef).
  • dtiModAlphaFactor: 0 will essentially turn off the modulation, 1 applies it fully (default is 1).
  • dtiRef: used when dtiMod is true to select which DTI image it applies to.

To display DTI as vector lines with color:

var params = [];
params["images"] = ["../data/dti_V1.nii.gz"];
params["dti_V1.nii.gz"] = {dti:true, dtiLines:true, dtiColors:true};

To display DTI as color with FA:

var params = [];
params["images"] = ["../data/dti_V1.nii.gz", "../data/dti_FA.nii.gz"];
params["dti_V1.nii.gz"] = {dti:true};
params["dti_FA.nii.gz"] = {dtiMod:true, dtiRef:"dti_V1.nii.gz", dtiModAlphaFactor:0.75};

To overlay DTI with alpha on a T1:

var params = [];
params["images"] = ["../data/sample_image.nii.gz", "../data/dti_V1.nii.gz"];
params["dti_V1.nii.gz"] = {dti:true, alpha:0.5};

Display Parameters

The following parameters apply globally and do not pertain to specific image instances. For example:

var params = [];
params["showOrientation"] = true;
  • coordinate: The initial coordinate to navigate the viewer to (e.g., [0, 0, 0]). Type of coordinate depends on worldSpace.
  • ignoreNiftiTransforms: Some NIFTI images can only be displayed in "world space". To force it to display without use of the NIFTI world space transform, set this to true.
  • ignoreSync: If true, papaya.Container.syncViewers is ignored for this viewer.
  • radiological: If true, automatically use radiological display mode.
  • showOrientation: If true, automatically turn on orientation markers.
  • showRuler: If true, the ruler will automatically be displayed.
  • showSurfacePlanes: If true, planes corresponding to the orthogonal slice viewer will appear in the surface viewer.
  • smoothDisplay: If false (defaults true), no linear interpolation is used when displaying images.
  • surfaceBackground: Set to one of the following: "Black", "Dark Gray", "Gray" (default), "Light Gray", "White".
  • syncOverlaySeries: If true, will sync all overlays series to the same series point (default true).
  • worldSpace: If true, automatically use world space mode.

UI Parameters

The following parameters apply globally and affect UI features. For example:

var params = [];
params["kioskMode"] = true;
  • allowScroll: If false (defaults true), scrolling behavior will be disabled.
  • combineParametric: If true, parametric overlays will be combined into a single button/menu.
  • expandable: If true, an expand/collapse button will appear in the toolbar for nested viewers.
  • fullScreen: This is a shortcut for fullScreenPadding=false, kioskMode=true, showControlBar=false, and setting the page background to black.
  • fullScreenPadding: If true, the viewer is padded with whitespace (default to true).
  • kioskMode: If true, the toolbar will be hidden and stored view preferences will be ignored.
  • noNewFiles: If true (defaults false), Add (image) options will be hidden in "File" dropdown
  • mainView: The initial slice direction of the main view. Options: axial, coronal, sagittal, surface (default axial).
  • orthogonal: If false (defaults true), a single slice direction will be displayed (see mainView).
  • orthogonalTall: If true, orthogonal slices will be arranged in a portrait orientation.
  • showControls: If false (defaults true), increment/decrement and goto buttons will be hidden.
  • showControlBar: If true (and showControls not false), control buttons will be displayed as a bar beneath the viewer.
  • showImageButtons: If false (defaults true), buttons which represent loaded images will not be displayed.

Miscellaneous Parameters

  • atlasURL: If true, override the default location of the atlas image file.
  • canOpenInMango: If true, an 'Open in Mango' option will appear in each image button menu (experimental). If Mango is installed on the user's computer, selecting this option will open it in Mango.
  • contextManager: If defined, this object can be used to open a context menu when right-clicking (tap-and-hold on phones) and receive action messages when selections are made (experimental). Click here to learn more about context managers.
  • loadingComplete: If this callback function is defined, it will be called once all data has loaded in the viewer.
  • padAllImages: Pad images such that each dimension is the same size (cube shape), regardless of voxel size.
  • showEULA: If true, the EULA will be shown automatically on first use.

Global Options

These options are referenced globally and do not belong in the parameters block. For example:

papaya.Container.syncViewers = true;
  • papaya.Container.atlasWorldSpace: If false, an atlas will use image indices instead of world space coordinates (defaults to true).
  • papaya.Container.syncViewers: If true, sync current coordinate in all viewers based on image indices.
  • papaya.Container.syncViewersWorld: If true, sync current coordinate in all viewers based on world space location.
  • papaya.Container.ignorePatterns: Add regex patterns to this array that will be ignored when reading DICOM folders (default is to ignore dot files /^[.]/).
  • daikon.Series.useExplicitOrdering: True to ignore metadata-based ordering of DICOM images.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.