Map

The map API gives you access to Qatium’s map environment, enabling you to create custom visualizations, move the camera, highlight assets and more.

Map Queries

getCamera()

Returns the current state of the map camera.

Method signature

getCamera(): Camera;

Returns

An object containing:

zoom: number Zoom level
pitch: number Angle towards the horizon measured in degrees with a range between 0 and 85
bearing: number The direction the camera is facing, measured clockwise as an angle from true north on a compass. This can also be called a heading. In Qatium, north is 0°, east is 90°, south is 180°, and west is 270°
center: {lng: number, lat: number} The longitude and latitude at which the camera is pointed

getSelectedElement()

Returns a SelectedElement object representing the currently selected element in the map, or undefined if nothing is selected. The SelectedElement object contains the element ID and the type of element.

Example

const selectedElement = sdk.map.getSelectedElement()
selectedElement.id // The element ID
selectedElement.type // Type in "Pipe", "Junction", "Valve", "Pump", "SupplySource" or "Tank"

Map Actions

setHighlights()

Highlights the network elements passed as parameter (assets or zones) in elementIds (an array of element IDs). If the elementIds array is empty, all highlights are cleared (equivalent to using clearHighlights()).

Method signature

setHighlights(elementIds: string[]) : void

Parameters

elementIds: string[]: an array of asset / zone IDs to be highlighted

Example

Highlights two tanks in Magnetic Island:

sdk.map.setHighlights(['Nellybay', 'Horseshoebay'])

clearHighlights()

Clears all the highlights in the map.

fitTo()

Centers the map viewport, while fitting a set of destination network elements or bounds, using the animation options set in the optional options parameter.

Method signature

fitTo(boundsOrIds: ElementId[] | Bounds, options?: FlightOptions) : Promise<void>

Parameters

boundsOrIds: ElementId[] | Bounds Accepts an asset / zone id or bounds as destination.
options: FlightOptions Optional Options object that accepts:
- padding: Bounds Optional Dimensions in pixels applied on each side of the viewport for shifting the vanishing point
- flightDuration: number Optional The animation’s duration, measured in milliseconds
- maxZoom: number Optional The max level of zoom allowed to perform the action

Returns

A promise with no value to allow async calls, resolved when the camera movement has finished.

Examples

Center the map to the Horseshoebay tank, using a slow animation (5 seconds), with a padding of 100 pixels on each side:

sdk.map.fitTo(['Horseshoebay'], {
  flightDuration: 5000,
  maxZoom: 20,
  padding: {
    top: 100,
    right: 100,
    bottom: 100,
    left: 100
  }
})

Fit a collection of assets in the viewport:

sdk.map.fitTo(['Horseshoebay', 'Nellybay', 'Cocklebay'], {
  flightDuration: 1000,
  padding: { top: 300, right: 300, bottom: 300, left: 300 }
})

Fitting to bounds:

sdk.map.fitTo({
  top: 100,
  right: 100,
  bottom: 100,
  left: 100
})

moveTo()

Method signature

Transitions the camera view, following a set of travel options.

moveTo(options: CameraOptions) : Promise<void>

Parameters

options: CameraOptions Transition object that accepts:

zoom: number Optional Target zoom level
pitch: number Optional Angle towards the horizon measured in degrees with a range between 0 and 85
transitionDuration: number Optional The animation’s duration, measured in milliseconds
latitude: number Optional Geographic latitude following the decimal degrees format, ranging from -90 to 90
longitude: number Optional Geographic longitude following the decimal degrees format, ranging from -180 to 180
bearing: number Optional The direction the camera is facing, measured clockwise as an angle from true north on a compass. This can also be called a heading. In Qatium, north is 0°, east is 90°, south is 180°, and west is 270°.
padding: Padding Optional Dimensions in pixels applied on each side of the viewport for shifting the vanishing point.

Returns

A promise with no value to allow async calls, it resolves when the camera movement has finished

Examples

Move the camera to Mandalay in Magnetic Island, AU:

sdk.map.moveTo({
  latitude: -19.157,
  longitude: 146.849
})

Do a tilted camera travel to the same location:

sdk.map.moveTo({
  zoom: 18,
  pitch: 45,
  transitionDuration: 2000,
  latitude: -19.157,
  longitude: 146.849
})

Animate the camera and rotate around the viewpoint:

await sdk.map.moveTo({
  zoom: 18,
  pitch: 45,
  transitionDuration: 2000,
  latitude: -19.157,
  longitude: 146.849
})

await sdk.map.moveTo({ transitionDuration: 3000, bearing: 90 })
await sdk.map.moveTo({ transitionDuration: 3000, bearing: 180 })
await sdk.map.moveTo({ transitionDuration: 3000, bearing: 270 })
await sdk.map.moveTo({ transitionDuration: 3000, bearing: 0 })

addOverlay()

Adds a custom visual overlay on top of the map.

Method signature

addOverlay(layers: Layer[]): void

Parameters

layers: List of Layer List of layer objects containing all data and styling, from any of the supported layer types.

Where Layer is

export type Layer = {
  type: 'ScatterplotLayer' | 'PolygonLayer' | 'IconLayer' | 'HeatmapLayer' // ...
  id: string
  data: Feature[]
  tooltip?: GetTooltipData,
  popover?: GetTooltipData
  // ... properties specific to the layer type
}

Tooltips and Popovers

You can associate a tooltip and/or a popover with your layer. To do that you need to provide the optional tooltip and/or popover properties. Ensure each data feature has an id property for the tooltips and popovers to function correctly.

The main differences are that:

Popovers appear on click and are visible until they are closed or another popover is open.
Tooltips appear on hover and disappear on blur.
User can see 1 popover and 1 tooltip max at the same time.
Tooltips should be small and popovers may be a bit larger.

The property value must be a function that receives a MapItem and returns TooltipData.

export type GetTooltipData = (mapItem: MapItem) => TooltipData

export type MapItem = {
  source?: string
  id?: string
  ids?: string[]
  coordinates?: { lng: number; lat: number }
}

export type TooltipData = {
  title: string
  type: string
  icon: QatiumIcon | Base64Image
  sections: TooltipSection[]
}

export type TooltipSection = TooltipProperty[]

export type TooltipProperty = {
  label: string
  value: TooltipPropertyValue
  unit?: string
  reading?: TooltipPropertyReading
  warning?: TooltipPropertyWarning
}

You can also return a Promise for Section, TooltipProperty, TooltipProperty.value, TooltipProperty.reading, and TooltipProperty.warning

Examples

Highlight all hydrants in red:

Highlight all hydrants in red

const data = sdk.network.getJunctions((j) => j.group === JunctionGroups.Hydrant).map((j) => ({
  type: "Feature",
  geometry: j.geometry,
  properties: {}
}));

sdk.map.addOverlay([{
  id: 'hydrants',
  type: "ScatterplotLayer",
  data,
  stroked: true,
  getPosition: (d: Feature) => d.geometry.coordinates,
  getRadius: () => 2,
  getFillColor: [255, 0, 0],
  getLineColor: [0, 0, 0],
  getLineWidth: 2,
  radiusScale: 6
}})

Hydrants mean pressure density with a heatmap:

Hydrants mean pressure density

const data = sdk.network.getJunctions((j) => j.group === JunctionGroups.Hydrant).map((p) => ({
  type: "Feature",
  geometry: j.geometry,
  properties: { pressure: j.simulation.pressure }
}));

sdk.map.addOverlay([
  {
    id: "HeatmapLayer",
    type: "HeatmapLayer",
    data,
    visible: true,
    aggregation: "MEAN",
    radiusPixels: 25,
    opacity: 0.4,
    getPosition: (f) => f.geometry.coordinates,
    getWeight: (f) => f.properties.pressure,
  }
])

Arc layer showing source and target pressures at the connections of pipes

Arc layer

const data = sdk.network.getPipes().map((p) => ({
  type: "Feature",
  geometry: p.geometry,
  properties: {
    sourcePressure: sdk.network.getNeighborAssets(p.id)[0].simulation.pressure,
    targetPressure: sdk.network.getNeighborAssets(p.id)[1].simulation.pressure
  }
}));

sdk.map.addOverlay([{
  id: 'pressures',
  data,
  type: "ArcLayer",
  getSourcePosition: (d) => d.geometry.coordinates[0],
  getTargetPosition: (d) => d.geometry.coordinates[d.geometry.coordinates.length - 1],
  getSourceColor: (f) => [f.properties.sourcePressure * 2, 0, 255, 255],
  getTargetColor: (f) => [f.properties.targetPressure * 2, 0, 130, 255],
  getHeight: 1,
  getWidth: 4
}])

Show tank IDs on the map

Text layer

const data = sdk.network.getTanks().map((p) => ({
  type: "Feature",
  geometry: p.geometry,
  properties: { id: p.id }
}));

sdk.map.addOverlay([{
  id: "TextLayer",
  type: "TextLayer",
  data,
  getPosition: (f) => f.geometry.coordinates,
  getText: (f) => f.properties.id,
  getSize: () => 24,
  getColor: () => [255, 255, 255, 255],
  fontFamily: "Arial"
} as OverlayLayer<"TextLayer">])

Tooltip:

export const PressuresTooltip = (mapItem: MapItem): TooltipData => {
  const { min, max, mean, total, avgHeight } = getJunctionPressures(mapItem.ids)
  const { pressure, elevation } = sdk.network.getUnits()

  return {
    title: `${total} Customer points`,
    icon: {
      media: 'image/svg+xml',
      charset: 'utf-8',
      data: btoa(
        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="white"><path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z"></path></svg>'
      )
    },
    type: 'Customer point pressure',

    sections: [
      [
        { label: 'Minimum', unit: pressure, value: min },
        { label: 'Mean',    unit: pressure, value: mean },
        { label: 'Maximum', unit: pressure, value: max }
      ],
      [
        { label: 'Average height', unit: elevation, value: avgHeight }
      ]
    ]
  }
}

Tooltip and the code that generates it with pointing arrows

Supported layers

You can refer to the DeckGL documentation to find a list of all available layers and how to declare them.

We support all available layer types except for BitmapLayer and GeohashLayer or custom layers.

For each layer, you’ll need to provide an object with a type parameter with the name of the type of layer and all the relevant parameters for that specific the type of layer.

hideOverlay()

Hides/removes all the layers of the overlay

Method signature

hideOverlay(): void

showOverlay()

Forces all the layers in the overlay to be shown.

showOverlay(): void

addStyles()

Method signature

Allows you to change the styles of elements on the map.

addStyles(styles: Styles) : Success | Failure

Parameters

styles: Styles Transition object that needs:

assetId: string;
Style properties:
- isShadowVisible?: boolean: Whether the feature halo is visible. Default: false
- shadowColor?: string: Color of the feature halo. Default: theme.colors.primary.light. Accepted values are tied to mapbox color specification
- outlineOpacity?: number: Value used to show an outline around features. Default: 0
- elementColor?: string. Color of the line and fills of polygon features. Defaults to theme.colors.grey.250 for lines and rgba(0,0,0,0) for fills. Accepted values are tied to CSS data type
- iconId?: string. Name of the icon to be used by the feature. Needs to be previously registered using registerIcon method

Examples

Highlight all tanks in yellow:

Highlight all tanks in yellow

sdk.map.addStyles({
  "Horseshoebay": {
    isShadowVisible: true,
    outlineOpacity: 1,
    shadowColor: "yellow"
  },
  "Nellybay": {
    isShadowVisible: true,
    outlineOpacity: 1,
    shadowColor: "yellow"
  }
})

removeStyles()

Method signature

Allows you to delete the styles applied with the addStyles method.

removeStyles() : void

sdk.map.removeStyles()

registerIcon()

Method signature

Async. Registers an SVG icon to the map instance. Follow icon guidelines to ensure a consistent look and behavior.

registerIcon(id: string, svg: string) : Promise<Success|Failure>

Returns

A promise with success or failure message to allow async calls, resolved when the icon has been registered to mapbox.

updateIcon()

Method signature

Allows you to change the icons of elements on the map. You need to register an icon before assigning it to any element

updateIcon(elements: string[], iconId: string) : Success | Failure

Examples

Change valves icon depending on their status:

Highlight all tanks in yellow

await sdk.map.registerIcon("open", `<svg width="44" height="44" viewBox="0 0 44 44" xmlns="http://www.w3.org/2000/svg">
<rect width="44" height="44" rx="10" fill="black" fill-opacity="0.3"/>
<rect x="2" y="2" width="40" height="40" rx="8" fill="#00C887"/>
<path d="M15.6415 16.6349C15.6396 16.7361 15.6129 16.8339 15.5651 16.9144C15.5174 16.995 15.4511 17.0541 15.3757 17.0834C15.3003 17.1126 15.2196 17.1106 15.1451 17.0775C15.0707 17.0444 15.0063 16.9819 14.9611 16.899C14.6533 16.304 14.2555 15.7946 13.7913 15.4013C13.2079 14.9035 12.5232 14.638 11.8229 14.638C11.1226 14.638 10.4379 14.9035 9.85452 15.4013C9.38847 15.7956 8.98921 16.3069 8.68067 16.9043C8.63546 16.9872 8.57104 17.0497 8.49659 17.0828C8.42214 17.1159 8.34145 17.1179 8.26604 17.0886C8.19062 17.0594 8.12432 17.0003 8.07659 16.9197C8.02886 16.8392 8.00213 16.7413 8.00021 16.6401C7.99177 15.6618 8.24261 14.7088 8.7115 13.9379C9.08228 13.3338 9.5548 12.8457 10.0935 12.51C10.6322 12.1744 11.2232 12 11.8219 12C12.4206 12 13.0115 12.1744 13.5503 12.51C14.089 12.8457 14.5615 13.3338 14.9323 13.9379C15.3984 14.7085 15.6483 15.6589 15.6415 16.6349ZM35.9999 16.6349C35.9979 16.7361 35.9712 16.8339 35.9235 16.9144C35.8757 16.995 35.8094 17.0541 35.734 17.0834C35.6586 17.1126 35.5779 17.1106 35.5035 17.0775C35.429 17.0444 35.3646 16.9819 35.3194 16.899C35.0118 16.3047 34.6148 15.7955 34.1517 15.4013C33.568 14.9033 32.8829 14.6377 32.1823 14.6377C31.4816 14.6377 30.7966 14.9033 30.2129 15.4013C29.7468 15.7956 29.3476 16.3069 29.039 16.9043C28.9938 16.9872 28.9294 17.0497 28.8549 17.0828C28.7805 17.1159 28.6998 17.1179 28.6244 17.0886C28.549 17.0594 28.4827 17.0003 28.4349 16.9197C28.3872 16.8392 28.3605 16.7413 28.3585 16.6401C28.3501 15.6618 28.601 14.7088 29.0698 13.9379C29.4406 13.3338 29.9131 12.8457 30.4519 12.51C30.9906 12.1744 31.5815 12 32.1802 12C32.7789 12 33.3699 12.1744 33.9086 12.51C34.4473 12.8457 34.9198 13.3338 35.2906 13.9379C35.7567 14.7085 36.0066 15.6589 35.9999 16.6349Z" fill="#222230"/>
</svg>`).then(() => sdk.map.updateIcon(['Nellybay_PSV', 'Arcadia_DMA_PRV', 'Picnic_Mainland_FCV'], "open"));

await sdk.map.registerIcon("closed", `<svg width="44" height="44" viewBox="0 0 44 44" xmlns="http://www.w3.org/2000/svg">
<rect width="44" height="44" rx="10" fill="black" fill-opacity="0.3"/>
<rect x="2" y="2" width="40" height="40" rx="8" fill="#FF7260"/>
<path d="M11.6563 16C10.9337 15.9992 10.2271 16.2127 9.62592 16.6136C9.02474 17.0145 8.556 17.5847 8.279 18.2521C8.002 18.9195 7.92921 19.654 8.06982 20.3628C8.21043 21.0716 8.55814 21.7227 9.06893 22.2338C9.57973 22.7449 10.2307 23.0929 10.9393 23.234C11.648 23.375 12.3826 23.3026 13.0502 23.026C13.7177 22.7494 14.2882 22.2809 14.6894 21.68C15.0906 21.0791 15.3046 20.3726 15.3042 19.65C15.3036 18.6825 14.9192 17.7547 14.2352 17.0704C13.5513 16.3861 12.6238 16.0011 11.6563 16ZM32.3584 16C31.6355 15.9979 30.9283 16.2104 30.3263 16.6106C29.7243 17.0107 29.2546 17.5805 28.9766 18.2477C28.6987 18.915 28.625 19.6497 28.7649 20.3589C28.9048 21.0681 29.252 21.7198 29.7625 22.2315C30.2731 22.7432 30.924 23.092 31.6329 23.2335C32.3417 23.375 33.0766 23.303 33.7445 23.0266C34.4124 22.7501 34.9833 22.2817 35.3848 21.6806C35.7863 21.0796 36.0004 20.3729 36 19.65C35.9995 18.6836 35.6159 17.7568 34.9333 17.0726C34.2507 16.3885 33.3248 16.0028 32.3584 16Z" fill="#222230"/>
</svg>`).then(() => sdk.map.updateIcon(['Nellybay_Bypass_PRV', 'Arcadia_backfeed3'], "closed"));