plugin_api.md

Plugin APIs

plugin migration guide

window.interactiveViewer

• metadata

  • selectedTemplateBSubject : BehaviourSubject that emits a TemplateDescriptor object whenever a template is selected. Emits null onInit.

  • selectedParcellationBSubject : BehaviourSubject that emits a ParcellationDescriptor object whenever a parcellation is selected. n.b. selecting a new template automatically select the first available parcellation. Emits null onInit.

  • selectedRegionsBSubject BehaviourSubject that emits an Array of RegionDescriptor objects whenever the list of selected regions changes. Emits empty array onInit.

  • loadedTemplates : Array of TemplateDescriptor objects. Loaded asynchronously onInit.

  • Deprecated regionsLabelIndexMap Map of labelIndex (used by neuroglancer and nehuba) to the corresponding RegionDescriptor object.

  • layersRegionLabelIndexMap Map of layer name to Map of labelIndex (used by neuroglancer and nehuba) to the corresponding RegionDescriptor object.

• viewerHandle

  • setNavigationLoc(coordinates,realspace?:boolean) Function that teleports the navigation state to coordinates : [x:number,y:number,z:number]. Optional arg determine if the set of coordinates is in realspace (default) or voxelspace.

  • moveToNavigationLoc(coordinates,realspace?:boolean) same as setNavigationLoc(coordinates,realspace?), except the action is carried out over 500ms.

  • setNavigationOri(ori) (not yet live) Function that sets the orientation state of the viewer.

  • moveToNavigationOri(ori) (not yet live) same as setNavigationOri, except the action is carried out over 500ms.

  • showSegment(labelIndex) Function that shows a specific segment. Will trigger selectedRegionsBSubject.

  • hideSegment(labelIndex) Function that hides a specific segment. Will trigger selectRegionsBSubject

  • showAllSegments() Function that shows all segments. Will trigger selectRegionsBSubject

  • hideAllSegments() Function that hides all segments. Will trigger selectRegionBSubject

  • Deprecated segmentColourMap : Map of labelIndex to an object with the shape of {red: number, green: number, blue: number}.

  • getLayersSegmentColourMap : Call to get Map of layer name to Map of label index to colour map

  • Deprecated applyColourMap(colourMap) Function that applies a custom colour map (Map of number to and object with the shape of {red: number , green: number , blue: number})

  • applyLayersColourMap Function that applies a custom colour map.

  • loadLayer(layerObject) Function that loads ManagedLayersWithSpecification directly to neuroglancer. Returns the values of the object successfully added. n.b. advanced feature, will likely break other functionalities. n.b. if the layer name is already taken, the layer will not be added.

  const obj = {
    'advanced layer' : {
      type : 'image',
      source : 'nifti://http://example.com/data/nifti.nii',
    },
    'advanced layer 2' : {
      type : 'mesh',
      source : 'vtk://http://example.com/data/vtk.vtk'
    }
  }
  const returnValue = window.interactiveViewer.viewerHandle.loadLayer(obj)
  /* loads two layers, an image nifti layer and a mesh vtk layer */
  
  console.log(returnValue)
  /* prints
  
  [{ 
    type : 'image', 
    source : 'nifti...' 
  },
  {
    type : 'mesh',
    source : 'vtk...'
  }] 
  */

  • removeLayer(layerObject) Function that removes ManagedLayersWithSpecification, returns an array of the names of the layers removed. n.b. advanced feature. may break other functionalities.

  const obj = {
    'name' : /^PMap/
  }
  const returnValue = window.interactiveViewer.viewerHandle.removeLayer(obj)
  
  console.log(returnValue)
  /* prints
  ['PMap 001','PMap 002']
  */

  • add3DLandmarks(landmarks) adds landmarks to both the perspective view and slice view.

  const landmarks = [{
    id : `fzj-xg-jugex-1`,
    position : [0,0,0]
  },{
    id : `fzj-xg-jugex-2`,
    position : [22,27,-1]
  }]
  window.interactiveViewer.viewerHandle.add3DLandmarks(landmarks)
  
  /* adds landmarks in perspective view and slice view */

  • remove3DLandmarks(IDs) removes the landmarks by their IDs

  window.interactiveViewer.viewerHandle
    .remove3DLandmarks(['fzj-xg-jugex-1', 'fzj-xg-jugex-2'])
  /* removes the landmarks added above */

  • setLayerVisibility(layerObject, visible) Function that sets the visibility of a layer. Returns the names of all the layers that are affected as an Array of string.

  const obj = {
    'type' : 'segmentation'
  }
  
  window.interactiveViewer.viewerHandle.setLayerVisibility(obj,false)
  
  /* turns off all the segmentation layers */

  • mouseEvent Subject that emits an object shaped { eventName : string, event: event } when a user triggers a mouse event on the viewer.

  • mouseOverNehuba BehaviourSubject that emits an object shaped { nehubaOutput : number | null, foundRegion : RegionDescriptor | null }

• uiHandle

  • getModalHandler() returns a modalHandler object, which has the following methods/properties:

    • hide() : Dynamically hides the modal
    • show() : Shows the modal
    • title : title of the modal (String)
    • body : body of the modal shown (String)
    • footer : footer of the modal (String)
    • dismissable : whether the modal is dismissable on click backdrop/esc key (Boolean) n.b. if true, users will not be able to interact with the viewer unless you specifically call handler.hide()

  • getToastHandler() returns a toastHandler objectm, which has the following methods/properties:

    • show() : Show the toast
    • hide() : Dynamically hides the toast
    • message : message on the toast
    • htmlMessage : HTML message. If used to display user content, beware of script injection. Angular strips style attribute, so use class and bootstrap for styling.
    • dismissable : allow user dismiss the toast via x
    • timeout : auto hide (in ms). set to 0 for not auto hide.

  • launchNewWidget(manifest) returns a Promise. expects a JSON object, with the same key value as a plugin manifest. the name key must be unique, or the promise will be rejected.

  • getUserInput(config) returns a Promise, resolves when user confirms, rejects when user cancels. expects config object object with the following structure:

  const config = {
    "title": "Title of the modal", // default: "Message"
    "message":"Message to be seen by the user.", // default: ""
    "placeholder": "Start typing here", // default: "Type your response here"
    "defaultValue": "42" // default: ""
    "iconClass":"fas fa-save" // default fas fa-save, set to falsy value to disable
  }

  • getUserConfirmation(config) returns a Promise, resolves when user confirms, rejects when user cancels. expects config object object with the following structure:

  const config = {
    "title": "Title of the modal", // default: "Message"
    "message":"Message to be seen by the user." // default: ""
  }

• pluginControl

  • loadExternalLibraries([LIBRARY_NAME_1,LIBRARY_NAME_2]) Function that loads external libraries. Pass the name of the libraries as an Array of string, and returns a Promise. When promise resolves, the libraries are loaded. n.b. while unlikely, there is a possibility that multiple requests to load external libraries in quick succession can cause the promise to resolve before the library is actually loaded.

  const currentlySupportedLibraries = ['jquery@2','jquery@3','webcomponentsLite@1.1.0','react@16','reactdom@16','vue@2.5.16']
  
  window.interactivewViewer.loadExternalLibraries(currentlySupportedLibraries)
    .then(() => {
      /* loaded */
    })
    .catch(e=>console.warn(e))
  

  • unloadExternalLibraries([LIBRARY_NAME_1,LIBRARY_NAME_2]) unloading the libraries (should be called on shutdown).

  • [PLUGINNAME] returns a plugin handler. This would be how to interface with the plugins.

    • blink() : Function that causes the floating widget to blink, attempt to grab user attention (silently fails if called on startup).
    • setProgressIndicator(val:number|null) : Set the progress of the plugin. Useful for giving user feedbacks on the progress of a long running process. Call the function with null to unset the progress.
    • shutdown() : Function that causes the widget to shutdown dynamically. (triggers onShutdown callback, silently fails if called on startup)
    • onShutdown(callback) : Attaches a callback function, which is called when the plugin is shutdown.
    • initState : passed from manifest.json. Useful for setting initial state of the plugin. Can be any JSON valid value (array, object, string).
    • initStateUrl : passed from manifest.json. Useful for setting initial state of the plugin. Can be any JSON valid value (array, object, string).
    • setInitManifestUrl(url|null) set/unset the url for a manifest json that will be fetched on atlas viewer startup. the argument should be a valid URL, has necessary CORS header, and returns a valid manifest json file. null will unset the search param. Useful for passing/preserving state. If called multiple times, the last one will take effect.

    const pluginHandler = window.interactiveViewer.pluginControl[PLUGINNAME]
    
    const subscription = window.interactiveViewer.metadata.selectedTemplateBSubject.subscribe(template=>console.log(template))
    
    fetch(`http://YOUR_BACKEND.com/API_ENDPOINT`)
      .then(data=>pluginHandler.blink(20))
    
    pluginHandler.onShutdown(()=>{
      subscription.unsubscribe()
    })

---

window.nehubaViewer

nehuba object, exposed if user would like to use it

---

window.viewer

neuroglancer object, exposed if user would like to use it