Plugin APIs
======
[plugin migration guide](migrationGuide.md)
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.
```javascript
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.
```js
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.
```js
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
```js
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.
```js
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:
```javascript
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:
```javascript
const config = {
"title": "Title of the modal", // default: "Message"
"message":"Message to be seen by the user." // default: ""
}
```
- *getUserToSelectARegion(message)* returns a `Promise`
_input_
| input | type | desc |
| --- | --- | --- |
| message | `string` | human readable message displayed to the user |
_returns_
`Promise`, resolves to return `RegionSelectedByUser`, rejects with error object `{ userInitiated: boolean }`
Requests user to select a parcellation region, displaying the message. Resolving to the region selected by the user. Rejects if either user cancels by pressing `Esc` or `Cancel`, or by developer calling `cancelPromise`
- *cancelPromise(promise)* returns `void`
_input_
| input | type | desc |
| --- | --- | --- |
| promise | `Promise` | Reference to the __exact__ promise returned by `uiHnandle` methods |
Cancel the request to select a parcellation region.
_usage example_
```javascript
(() => {
const pr = interactive.uiHandle.getUserToSelectARegion(`webJuGEx would like you to select a region`)
pr.then(region => { })
.catch(console.warn)
/*
* do NOT do
*
* const pr = interactive.uiHandle.getUserToSelectARegion(`webJuGEx would like you to select a region`)
* .then(region => { })
* -catch(console.warn)
*
* the promise passed to `cancelPromise` must be the exact promise returned.
* by chaining then/catch, a new reference is returned
*/
setTimeout(() => {
try {
interactive.uiHandle.cancelPromise(pr)
} catch (e) {
// if the promise has been fulfilled (by resolving or user cancel), cancelPromise will throw
}
}, 5000)
})()
```
- 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.
```js
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.
```js
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