API Documentation

class FlatMap()

Maps are not created directly but instead are created and loaded by LoadMap() of MapManager().

FlatMap.FlatMap
FlatMap.anatomicalIdentifiers

type: string|Array.<string>

The anatomical identifiers of features in the map.

FlatMap.biologicalSex

type: string

The biological sex identifier of the species described by the map.

FlatMap.bounds

The flatmap’s bounds.

FlatMap.created

type: string

The map’s creation time.

FlatMap.datasets

type: string|Array.<string>

Datasets associated with the map.

FlatMap.details

type: Object

The map’s index.json as returned from the map server.

FlatMap.has_flightpaths

Does the flatmap contain flightpath information?

FlatMap.id

type: string

The map’s id as specified at generation time.

FlatMap.provenance

type: Object

The map’s provenance as returned from the map server.

FlatMap.taxon

type: string

The taxon identifier of the species described by the map.

FlatMap.taxonIdentifiers

type: string|Array.<string>

The taxon identifiers of species which the map’s connectivity has been observed in.

FlatMap.uniqueId

type: string

A unique identifier for the map within the viewer.

FlatMap.url

type: string

The map’s URL on the map server.

FlatMap.uuid

type: string

The map’s unique universal identifier.

For published maps this is different to the map’s id; it might be the same as id for unpublished maps.

FlatMap.addAnnotationFeature(feature)

Add a drawn feature to the annotation drawing tool.

Arguments

  • feature (Object()) – The feature to add

  • feature.id (string()) – The feature’s id

  • feature.geometry (Object()) – The feature’s geometry as GeoJSON

FlatMap.addDatasetMarkers(datasets)

Add dataset markers to the map.

Arguments

  • datasets (Array.) – An array with an object for each dataset, specifying its identifier and an array of associated anatomical terms

FlatMap.addImage(anatomicalId, imageUrl)

Display an image on a given anatomical feature.

Arguments

  • anatomicalId (string()) – The anatomical identifier of the feature on which to place the image. The image is scaled to fit within the feature’s bounding box.

  • imageUrl (string()) – The URL of the image to display.

Returns

string|null – A identifying the image(s) added to the map. A map may have several features corresponding to a particular anatomical identifier, which will result in an image being placed on each feature. null is returned if there are no features with the given anatomicalId.

FlatMap.addMarker(anatomicalId, options)

Add a marker to the map.

Arguments

  • anatomicalId (string()) – The anatomical identifier of the feature on which to place the marker.

  • options (Object()) – Configurable options for the marker.

  • options.className (string()) – Space-separated CSS class names to add to marker element.

  • options.colour (string()) – Colour of the marker. Defaults to '#005974' (dark cyan).

  • options.element (string()) – The DOM element to use as a marker. The default is a dark blue droplet-shaped SVG marker.

  • options.location (string()) – The relative location (0.0 to 1.0) of the marker along a centreline in a centreline map.

Returns

integer – The identifier for the resulting marker. -1 is returned if the map doesn’t contain a feature with the given anatomical identifier

FlatMap.addMarkers(anatomicalId, options)

Add a list of markers to the map.

Arguments

  • anatomicalId (Array.) – Anatomical identifiers of features on which to place markers.

  • options (Object()) – Configurable options for the markers.

  • options.className (string()) – Space-separated CSS class names to add to marker elemens.

  • options.cluster (boolean()) – The markers will be clustered together with other geographically close markers. Defaults to true.

  • options.colour (string()) – Colour of the markers. Defaults to '#005974' (dark cyan).

  • options.element (string()) – The DOM element to use as a marker. The default is a dark blue droplet-shaped SVG marker.

Returns

array.<integer> – The identifiers of the resulting markers. -1 is returned if the map doesn’t contain a feature with the given anatomical identifier

FlatMap.annotation(geojsonId)

Get a feature’s annotations given its GeoJSON id.

Arguments

  • geojsonId (string|number()) – The features’s GeoJSON identifier

Returns

Object – The feature’s annotations

FlatMap.annotationById(annotationId)

Get a feature’s annotations given its external id.

Arguments

  • annotationId (string()) – The features’s external identifier

Returns

Object – The feature’s annotations

FlatMap.annotationEvent(eventType, feature)

Generate an annotation callback event when a drawn annotation has been created a modified.

Arguments

  • eventType (string()) – Either created, updated or deleted

  • feature (Object()) – A feature object with id, type, and geometry fields of a feature that has been created, updated or deleted.

FlatMap.changeAnnotationDrawMode(type)

Changes draw to another mode. The mode argument must be one of the following: simple_select, direct_select, draw_line_string, draw_polygon or draw_point. Options is accepted in first three modes. More details in mapbox-gl-draw github repository.

Arguments

  • type (Object()) – The object

  • type.mode (string()) – Either simple_select, direct_select, etc

  • type.options (Object()) – Feature id(s) object.

FlatMap.clearAnnotationFeature()

Clear all drawn annotations from current annotation layer.

FlatMap.clearDatasetMarkers()

Remove all dataset markers from the map.

FlatMap.clearMarkers()

Remove all markers from the map.

FlatMap.clearVisibilityFilter()

Clear any visibility filter on features and paths.

FlatMap.commitAnnotationEvent(event)

Mark a drawn/changed annotation as having been accepted by the user.

Arguments

  • event (Object()) – The object as received in an annotation callback

  • event.type (string()) – Either created, updated or deleted

  • event.feature (Object()) – A feature object.

FlatMap.controlEvent(eventType, control, value)

Generate a callback as a result of some event in a control.

Arguments

  • eventType (string()) – The event type

  • control (string()) – The name of the control

  • value (string()) – The value of the control

FlatMap.enableConnectivityByTaxonIds(taxonId(s), enable)

Show or hide connectivity features observed in particular species.

Arguments

  • taxonId(s) (string|Array.) – A single taxon identifier or an array of identifiers.

  • enable (boolean()) – Show or hide connectivity paths and features. Defaults to true (show)

FlatMap.enableFlightPaths(enable=true)

Show/hide flight path view.

Arguments

  • enable (boolean()) –

FlatMap.enableLayer(layerId, enable=true)
Arguments

  • layerId (string()) – The layer identifier to enable

  • enable (boolean()) – Show or hide the layer. Defaults to true (show)

FlatMap.enableNeuronPathsByNerve(nerveModels, enable=true)

Enable/disable the neuron paths associated with a nerve centreline.

Arguments

  • nerveModels (Array.<string>|string()) – Anatomical identifiers of nerve centrelines

  • enable (boolean()) –

FlatMap.enablePanZoomEvents(enabled=true)

Generate callbacks as a result of panning/zooming the map.

Arguments

  • enabled (boolean()) – Generate callbacks when true, otherwise disable them.

FlatMap.enablePath(pathType(s), enable)

Hide or show paths of a given type.

Arguments

  • pathType(s) (Array.<string>|string()) – The path type(s) to hide or show

  • enable (boolean()) – Show or hide paths of that type. Defaults to true (show)

FlatMap.enableSckanPath(sckanState, enable=true)

Hide or show all paths valid in SCKAN.

Arguments

  • sckanState (string()) – Either valid or invalid

  • enable (boolean()) – Show or hide paths with that SCKAN state. Defaults to true (show)

FlatMap.enableSystem(systemId, enable=true)
Arguments

  • systemId (string()) – The identifier of the system to enable

  • enable (boolean()) – Show or hide the system. Defaults to true (show)

FlatMap.featureEvent(eventType, properties)

Generate a callback as a result of some event with a flatmap feature.

Arguments

  • eventType (string()) – The event type

  • properties (Object()) – Properties associated with the feature

FlatMap.featureFilterRanges()

Get valid keys and their value ranges to use when filtering feature and path visibility.

Returns

Object – Value ranges are string arrays

FlatMap.featureProperties(featureId)

Return properties associated with a feature.

Arguments

  • featureId (number()) – The feature’s internal (GeoJSON) id

Returns

Object – Properties associated with the feature

FlatMap.getBackgroundColour()

Get the map’s current background colour.

Returns

string – The background colour.

FlatMap.getBackgroundOpacity()

Get the map’s current background opacity.

Returns

number – The background opacity.

FlatMap.getLayers()

Get a list of the flatmap’s layers.

Returns

Array.<{id: string, description: string, enabled: boolean}> – An array with layer details

FlatMap.getNerveDetails()

Get a details of the nerve centrelines in the map.

Returns

Array.<CentrelineDetails> –

FlatMap.getSystems()

Get a list of a FC flatmap’s systems.

Returns

Array.<{id: string, name: string, colour: string, enabled: boolean}> – An array with system details

FlatMap.getZoom()

Get the map’s zoom settings.

Returns

Object.<{minZoom: number, zoom: number, maxZoom: number}> – The map’s minimum, current, and maximum zoom levels.

FlatMap.markerEvent(eventType, markerId, properties)

Generate a callback as a result of some event with a marker.

Arguments

  • eventType (string()) – The event type

  • markerId (integer()) – The marker identifier

  • properties (Object()) – Properties associated with the marker

FlatMap.nodePathModels(pathId)

Get model terms of all paths connected to a node.

Arguments

  • pathId (number()) – The local (GeoJSON) identifier of a node

Returns

set.<string> – Model terms of all paths connected to the node

FlatMap.panZoomEvent(type, origin, size)

Generate a callback as a result of panning/zooming the map.

Arguments

  • type (string()) – The event type, pan or zoom.

  • origin (Array.) – The map’s normalised top-left corner

  • size (Array.) – The map’s normalised size

FlatMap.panZoomTo(origin, size)

Pan/zoom the map to a new view

Arguments

  • origin (Array.) – The map’s normalised top-left corner

  • size (Array.) – The map’s normalised size

FlatMap.pathModelNodes(pathId)

Get GeoJSON feature ids of all nodes of a path model.

Arguments

  • pathId (string()) – The path model identifier

Returns

Array.<string> – GeoJSON identifiers of features on the path

FlatMap.pathTypes()
Returns

Array.<{type: string, label: string, colour: string}> – an array of objects giving the path types present in the map along with their descriptions and colours

FlatMap.queryKnowledge(entity)

Get knowledge about an entity from the flatmap’s server’s knowledge store.

Arguments

  • entity (string()) – The URI of an entity.

Returns

Object – JSON describing the entity.

FlatMap.queryLabels(entities)

Get labels for entities from the flatmap’s server’s knowledge store.

Arguments

  • entities (Array.<string>|string()) – Anatomical identifiers of entities.

Returns

Array.<EntityLabel> – An EntityLabel array.

FlatMap.queryPublications(entity)

Get publications about an entity from the flatmap’s server’s knowledge store.

Arguments

  • entity (string()) – The URI of an entity.

Returns

Array.<string> – A list of publication URIs.

FlatMap.refreshAnnotationFeatureGeometry(feature)

Return the feature as it is currently drawn. This is so the correct geometry can be saved with a feature should a user make changes before submitting dialog provided by an external annotator.

Arguments

  • feature (Object()) – The drawn feature to refresh.

Returns

Object|null – The feature with currently geometry or null if the feature has been deleted.

FlatMap.removeAnnotationFeature()

Delete the selected drawn feature

FlatMap.removeDatasetMarker(datasetId)

Remove markers for a dataset from the map.

Arguments

  • datasetId (integer()) – The a dataset marker identifier as passed to addDatasetMarkers()

FlatMap.removeImage(mapImageId)

Remove images for an anatomical features.

Arguments

  • mapImageId (string()) – An image identifier previously returned by addImage().

FlatMap.removeMarker(markerId)

Remove a marker from the map.

Arguments

  • markerId (integer()) – The identifier of the marker, as returned by addMarker()

FlatMap.resetMap()

Reset a map to its initial state.

FlatMap.rollbackAnnotationEvent(event)

Mark a drawn/changed annotation as having been rejected by the user.

Arguments

  • event (Object()) – The object as received in an annotation callback

  • event.type (string()) – Either created, updated or deleted

  • event.feature (Object()) – A feature object.

FlatMap.search(text, auto=false)

Find features with labels or terms matching text.

Arguments

  • text (string()) – The text to search

  • auto (boolean()) – If true return suggestions of text to search for.

Returns

Either a Searchresults object with fields of featureIds and results, where results has featureId, score, terms and text fields, or a Suggestion object containing suggested matches (see https://lucaong.github.io/minisearch/modules/_minisearch_.html#suggestion).

FlatMap.selectFeatures(externalIds)

Select features on the map.

Arguments

  • externalIds (Array.) – An array of anaotomical terms identifing features to select

FlatMap.selectGeoJSONFeatures(geojsonIds)

Select features on the map.

Arguments

  • geojsonIds (string|Array.) – A single GeoJSON feature identifiers or an array of identifiers.

FlatMap.setBackgroundColour(colour)

Sets the map’s background colour.

Arguments

  • colour (string()) – The colour

FlatMap.setBackgroundOpacity(opacity)

Sets the map’s background opacity.

Arguments

  • opacity (number()) – The opacity

FlatMap.setFeatureAnnotated(featureId)

Flag the feature as having external annotation.

Arguments

  • featureId (string()) – The feature’s external identifier

FlatMap.setVisibilityFilter(filterExpression=true)

Sets a visibility filter for features and paths

Arguments

  • filterExpression (PropertiesFilterExpression()) – The filter specification

FlatMap.showAnnotator(visible=true)

Show or hide a tool for drawing regions to annotate on the map.

Arguments

  • visible (boolean()) –

FlatMap.showMarkerPopup(markerId, content, options)

Shows a popup at a marker.

This method should only be called in response to a mouseenter event passed to the map’s callback function otherwise a popup won’t be shown.

Arguments

  • markerId (integer()) – The identifier of the marker

  • content (string|DOMElement()) – The popup’s content

  • options (Object()) –

Returns

boolean – Return true if the popup is shown The resulting popup is given a class name of flatmap-tooltip-popup.

FlatMap.showMinimap(show)

Show and hide the minimap.

Arguments

  • show (boolean()) – Set false to hide minimap

FlatMap.taxonFeatureIds(taxonId)

Get GeoJSON feature ids of all features identified with a taxon.

Arguments

  • taxonId (string()) – The taxon identifier

Returns

Array.<string> – GeoJSON identifiers of features on the path

FlatMap.unselectGeoJSONFeatures()

Unselect all features on the map.

FlatMap.visibleMarkerAnatomicalIds()

Return the set of anatomical identifiers visible in the current map view.

Returns

Array.<string> – A list of identifiers

FlatMap.zoomIn()

Zoom the map in.

FlatMap.zoomOut()

Zoom the map out.

FlatMap.zoomToFeatures(featureIds, options)

Select features and zoom the map to them.

Arguments

  • featureIds (Array.) – An array of feature identifiers

  • options (Object()) –

  • options.zoomIn (boolean()) – Zoom in the map (always zoom out as necessary)

FlatMap.zoomToGeoJSONFeatures(geojsonIds, options=null)

Select features and zoom the map to them.

Arguments

  • geojsonIds (string|Array.) – A single GeoJSON feature identifiers or an array of identifiers.

  • options (Object()) –

  • options.zoomIn (boolean()) – Zoom in the map (always zoom out as necessary)

class MapManager()

A manager for FlatMaps.

Examples:

const mapManager = new MapManger('https://mapcore-demo.org/flatmaps/');
MapManager.MapManager

Examples:

const mapManager = new MapManger('https://mapcore-demo.org/flatmaps/');
MapManager.version

The released version of the viewer

MapManager.loadMap(identifier, container, callback, options)

Load and display a FlatMap.

Arguments

  • identifier (string|Object()) – A string or object identifying the map to load. If a string its value can be either the map’s uuid, assigned at generation time, or taxon and biological sex identifiers of the species that the map represents. The latest version of a map is loaded unless it has been identified using a uuid (see below).

  • identifier.taxon (string()) – The taxon identifier of the species represented by the map. This is specified as metadata in the map’s source file.)

  • identifier.biologicalSex (string()) – The biological sex of the species represented by the map. This is specified as metadata in the map’s source file.)

  • identifier.uuid (string()) – The unique uuid the flatmap. If given then this exact map will be loaded, overriding taxon and biologicalSex.

  • container (string()) – The id of the HTML container in which to display the map.

  • callback (function()) – A callback function, invoked when events occur with the map. The first parameter gives the type of event, the second provides details about the event.

  • options (Object()) – Configurable options for the map.

  • options.background (string()) – Background colour of flatmap. Defaults to white.

  • options.debug (boolean()) – Enable debugging mode.

  • options.flightPaths (boolean()) – Enable flight path (3D) view of neuron paths

  • options.fullscreenControl (boolean()) – Add a Show full screen button to the map.

  • options.layerOptions (Object()) – Options to control colour and outlines of features

  • options.layerOptions.colour (boolean()) – Use colour fill (if available) for features. Defaults to true.

  • options.layerOptions.outline (boolean()) – Show the border of features. Defaults to true.

  • options.layerOptions.sckan (string()) – Show neuron paths known to SCKAN: values are valid (default), invalid, all or none.

  • options.minimap (boolean|Object()) – Display a MiniMap of the flatmap. Defaults to false.

  • options.minimap.position (string()) – The minimap’s position: bottom-left (default), bottom-right, top-left or top-right.

  • options.minimap.width (number|string()) – The width of the minimap. Defaults to 320px. Can also be given as a percentage of the flatmap’s width, e.g. 10%. The minimap’s height is determined from its width using the flatmap’s aspect ratio.

  • options.maxZoom (number()) – The maximum zoom level of the map.

  • options.minZoom (number()) – The minimum zoom level of the map.

  • options.navigationControl (boolean()) – Add navigation controls (zoom buttons) to the map.

  • options.showPosition (boolean()) – Show position of tooltip.

  • options.standalone (boolean()) – Viewer is running standalone, as opposed to integrated into another application so show a number of controls. Defaults to false.

  • options.tooltipDelay (number()) – The number of milliseconds to delay the tooltip showing.

Examples:

const humanMap1 = mapManager.loadMap('humanV1', 'div-1');

const humanMap2 = mapManager.loadMap('NCBITaxon:9606', 'div-2');

const humanMap3 = mapManager.loadMap({taxon: 'NCBITaxon:9606'}, 'div-3');

const humanMap4 = mapManager.loadMap(
                    {uuid: 'a563be90-9225-51c1-a84d-00ed2d03b7dc'},
                    'div-4');