Map Layers Configuration

The map layers configuration describes the layers of assets rendered by the network map. It is a geo-view configuration item, represented in json format, that groups the assets in the vector tiles into named layers and groups of layers, and specifies how each of those layers/groups is drawn, labelled, ordered, and searched upon.

The keep level specification decides what ends up in the vector tiles; the map layers configuration decides how the features in the tiles get organised and drawn.

The configuration is set under the mapLayersConfig key of the geoView and publicGeoView config objects, and is served to the network map through the getGeoViewConfig and getPublicGeoViewConfig GraphQL queries. If it is not provided, a default configuration covering the standard EWB network map layers is used.

• Properties:
  • version: the version of the configuration format. This is the discriminator that selects how the rest of the object is interpreted, and is required. The only currently supported value is "1".
  • entries: the layers and groups of layers to render on the map, in the order they should be displayed in the layers panel.
  • enableOtherAssetsLayer: if true, assets in map tiles that are not matched by any of the provided layers will be included in an "Other assets" group.

{
    "version": "1",
    "entries": [ <CONFIG_ENTRY> ],
    "enableOtherAssetsLayer": <boolean>
}

Config Entry

A config entry is either a group or a layer, selected by its type property. All entries share the following properties:

• Properties:
  • type: how to interpret this entry. One of group, node, line, or polygon. A value of group makes the entry a group, and the other three values make it a layer.
  • name: the display name of this group or layer.
  • showInSearch: whether this group/layer should also be a filter option in the map search plugin.
  • cimClasses: a list of CIM classes this group/layer adds to the search filter, used when showInSearch is true.

Group

A group is a named collection of layers. Groups may only contain layers, they cannot be nested inside one another.

• Properties:
  • type: should always be "group" for a group.
  • name: see Config Entry.
  • showInSearch: see Config Entry.
  • cimClasses: see Config Entry.
  • layers: the layers to display within this group.

{
    "type": "group",
    "name": <string>,
    "showInSearch": <boolean>,
    "cimClasses": [ <string> ],
    "layers": [ <LAYER> ]
}

Layer

A layer is a set of assets rendered on the map. The type of a layer describes what shape of assets it draws, which affects how layout, paint, and capabilities are interpreted:

• node - point assets, drawn as icons.

• line - linear assets.

• polygon - area assets.

• Properties:

  • type: one of "node", "line", or "polygon".
  • name: see Config Entry.
  • showInSearch: see Config Entry.
  • cimClasses: see Config Entry.
  • sourceLayer: which layer within the map tiles these assets are on. See Source Layer for the possible values.
  • matchAssetsFilter: a Mapbox expression that picks out matching assets in map tiles.
  • minZoom: the minimum zoom level to display assets for this layer.
  • maxZoom: the maximum zoom level to display assets for this layer.
  • visibleByDefault: whether this layer is initially checked in the layers panel.
  • showLabelFilter: a Mapbox expression that determines when to show a label for the layer. Set it to false to give the layer no labels at all.
  • zIndex: the z-ordering of this layer. Higher values are placed on top of lower values.
  • iconExpression: a Mapbox expression selecting the icon to show on the map for this layer. node layers only.
  • iconSize: the size of icons for this layer, as a fixed number or a Mapbox expression. node layers only.
  • layout: adjust layer layout properties.
  • paint: adjust layer paint properties.
  • capabilities: a set of capabilities for this layer, that drive how its style could be modified dynamically by plugins to the network map.
  • labelText: a Mapbox expression that selects the label text to show for assets on this layer.
  • labelMinZoom: the minimum zoom level to display labels for this layer.
  • labelMaxZoom: the maximum zoom level to display labels for this layer.
  • labelLayout: adjust label text layout properties.
  • labelPaint: adjust label text paint properties.
  • labelZIndex: the z-ordering of this layer's labels. Higher values are placed on top of lower values.

Only type, name, showInSearch, sourceLayer, and matchAssetsFilter are required; every other property may be omitted, in which case the front-end will use some sensible default value.

{
    "type": "<LAYER_TYPE>",
    "name": <string>,
    "showInSearch": <boolean>,
    "cimClasses": [ <string> ],
    "sourceLayer": "<SOURCE_LAYER>",
    "matchAssetsFilter": <MAPBOX_EXPRESSION>,
    "minZoom": <number>,
    "maxZoom": <number>,
    "visibleByDefault": <boolean>,
    "showLabelFilter": <MAPBOX_EXPRESSION | boolean>,
    "zIndex": <number>,
    "iconExpression": <MAPBOX_EXPRESSION>, // "node" layers only
    "iconSize": <MAPBOX_EXPRESSION | number>, // "node" layers only
    "layout": { <MAPBOX_LAYOUT_PROPERTIES> },
    "paint": { <MAPBOX_PAINT_PROPERTIES> },
    "capabilities": { <CAPABILITIES> },
    "labelText": <MAPBOX_EXPRESSION>,
    "labelMinZoom": <number>,
    "labelMaxZoom": <number>,
    "labelLayout": { <MAPBOX_LAYOUT_PROPERTIES> },
    "labelPaint": { <MAPBOX_PAINT_PROPERTIES> },
    "labelZIndex": <number>
}

Mapbox Expressions

The matchAssetsFilter, showLabelFilter, iconExpression, iconSize, and labelText properties, along with the contents of the layout, paint, labelLayout, and labelPaint objects, are Mapbox style expressions. Expressions are evaluated against the properties of the assets in the vector tiles, e.g. ["==", "class", "Fuse"] matches assets whose class property is Fuse, and ["get", "symbol"] reads an asset's symbol property.

The properties of the assets in the vector tiles are currently hard-coded inside the server, and are listed below. Which properties an asset carries depends on its CIM class, so they are grouped below by the source layer the asset lands on.

Common Properties on Map Tile Features

Common Properties

Every asset on every layer carries these, except for assets on the meterServiceLocations layer (see below).

PROPERTY	Type	Description
class	string	The simple name of the asset's CIM class, e.g. AcLineSegment, Fuse, PowerTransformer.
id	string	The mRID of the asset.
name	string	The name of the asset, or an empty string if it has none.
symbol	string	The diagram object style of the asset, taken from the first diagram object that has one. Falls back to DEFAULT.
source-<change set>	int	Written as 1 for each change set the asset appears in, one property per change set. The base network model is source-base, so an asset in the base model and a change set named csA carries both source-base and source-csA.
isVoltageLevelEhv	bool	Present, and true, if the asset is at the sub-transmission/super-high voltage level. Only when true.
isVoltageLevelHv	bool	Present, and true, if the asset is at the high/medium voltage level. Only when true.
isVoltageLevelLv	bool	Present, and true, if the asset is at the low voltage level. Only when true.
isVoltageLevelUnknown	bool	Present, and true, if no voltage level could be determined for the asset. Only when true.

Equipment Properties

Carried by assets on the conductors, busbars, nodes, and powerElectronicsUnit layers, in addition to the common properties.

PROPERTY	Type	Description
opresId1 … opresId<n>	string	The mRID of each operational restriction applied to this asset, numbered from 1.
opresCount	int	The number of operational restrictions applied to this asset.

Container Properties

Carried by assets on the conductors, busbars, nodes, and powerElectronicsUnit layers, describing the equipment containers the asset belongs to. The names and ids are comma-separated lists where the asset is in more than one container of that type, and each group of properties is only present when the asset is in at least one container of that type. Power electronics units take these from their power electronics connection where they have one.

PROPERTY	Type	Description
substations	string	The names of the substations containing this asset. Only when set.
substationIds	string	The mRIDs of the substations containing this asset. Only when set.
circuits	string	The names of the circuits containing this asset. Only when set.
circuitIds	string	The mRIDs of the circuits containing this asset. Only when set.
feeders	string	The names of the feeders containing this asset. Where the asset is in an LV feeder, this is the LV feeder's energising feeders. Only when set.
feederIds	string	The mRIDs of those feeders. Only when set.
lvFeeders	string	The names of the LV feeders containing this asset. Only when set.
lvFeederIds	string	The mRIDs of the LV feeders containing this asset. Only when set.
pen	int	A colour index from 0 to 13, derived from the asset's containers, used to give assets in the same container a consistent colour. Substations always use 13.
isAbnormalFeeder	bool	Present, and true, if the asset's current feeders differ from its normal feeders. Current state tiles only. Only when true.
isAbnormalLvFeeder	bool	Present, and true, if the asset's current LV feeders differ from its normal LV feeders. Current state tiles only. Only when true.

Conducting Equipment Properties

Carried by assets on the conductors, busbars, and nodes layers, in addition to the common, equipment, and container properties.

PROPERTY	Type	Description
voltage	int	The base voltage of the asset in volts. Power transformers instead report their primary voltage, or 0 if it is unknown.
isSwer	bool	Whether the asset is part of a SWER section of the network.
nominalPhases	string	The phase code of the asset's terminal with the most phases, e.g. ABCN, AN, NONE.
offSupply	bool	Present, and true, if every phase of every terminal is de-energised. Only when true.
partiallyOffSupply	bool	Present, and true, if some but not all phases are de-energised. Only when true.

Whether these are evaluated against the normal or current state of the network depends on which state the tiles were requested for.

conductors

Conductors carry the common, equipment, container, and conducting equipment properties, plus:

PROPERTY	Type	Description
isUnderground	bool	Whether the conductor is underground.
impedance	double	The magnitude of the conductor's per length sequence impedance. Only set on AC line segments that have a per length sequence impedance with at least one of r/x set.
nullImpedance	bool	Present, and true, if the conductor has a per length sequence impedance but both its r and x are null. Only when true.
arrowDirection	string	The name of the direction arrow symbol to draw along the conductor, based on the feeder direction of its terminals. One of the configured arrow symbols (DIRECTION-ARROW-RIGHT, DIRECTION-ARROW-LEFT, DIRECTION-ARROW-LOOP by default), or none.
lineDirection	string	Deprecated, prefer arrowDirection. The raw feeder direction along the conductor: normal, reverse, loop, or none.
displayName	string	The conductor's name, or, where the name is just the mRID, the first of its lvFeeders, feeders, circuits, or substations.

busbars

Busbar sections carry the common, equipment, container, and conducting equipment properties, plus:

PROPERTY	Type	Description
displayName	string	The busbar section's name.

nodes

Every conducting equipment that is not a conductor or busbar section lands here. All of them carry the common, equipment, container, and conducting equipment properties, plus:

PROPERTY	Type	Description
open	bool	True if the asset is a switch that is open, or if the asset is out of service. Equipment that cannot be opened is therefore still open while it is out of service.
rotation	double	The rotation of the asset's diagram object in degrees, or 0 if it has none.
zPriority	int	A drawing priority from 1 to 8, derived from the asset's class and, for power transformers, its function. Used by the default config to sort overlapping icons.
isSwitch	bool	Whether the asset is a switch.

Switches additionally carry:

PROPERTY	Type	Description
displayName	string	The switch name extracted by the switchNamePattern geo view config option. Only set when a pattern is configured and it matches the switch's name.
isAbnormalState	bool	Present, and true, if the switch's current open state differs from its normal open state. Current state tiles only. Only when true.

Power transformers additionally carry:

PROPERTY	Type	Description
displayName	string	The transformer's name with a trailing " TRANS" removed.
function	string	The transformer's function, e.g. powerTransformer, distributionTransformer, isolationTransformer, voltageRegulator, autotransformer, secondaryTransformer, other, UNKNOWN.

powerElectronicsUnit

Power electronics units carry the common, equipment, and container properties. They are not conducting equipment, so they carry none of the conducting equipment properties, and no properties of their own.

poles

Poles carry the common properties plus:

PROPERTY	Type	Description
displayName	string	The pole's name.
classification	string	The pole's classification, e.g. lv, lv/hv, sub-transmission. Only set when the pole has a non-blank classification.

meters

Meters carry the common properties plus:

PROPERTY	Type	Description
displayName	string	The meter's name.

meterServiceLocations

Service locations carry only the following:

PROPERTY	Type	Description
id	string	The mRID of the meter's service location, or <meter mRID>-service-location if the meter has no service location.
name	string	The name of the service location, falling back to the meter's name.
displayName	string	The same value as name.
isVoltageLevelEhv / isVoltageLevelHv / isVoltageLevelLv / isVoltageLevelUnknown	bool	As per the common properties. Only when true.

operationalRestrictions

Operational restrictions carry the common properties plus:

PROPERTY	Type	Description
title	string	The restriction's title. Only when set.
authorName	string	The name of the author of the restriction. Only when set.
createdDateTime	string	When the restriction was created, as an ISO-8601 instant. Only when set.
type	string	The type of the restriction. Only when set.
status	string	The status of the restriction. Only when set.
comment	string	The comment on the restriction. Only when set.
equipmentId1 … equipmentId<n>	string	The mRID of each piece of equipment the restriction applies to, numbered from 1.
equipmentName1 … equipmentName<n>	string	The name of each of those pieces of equipment. Only set for equipment that has a name.
equipmentCount	int	The number of pieces of equipment the restriction applies to.

Where the restriction has no diagram object style, its symbol falls back to the value of its type, rather than to DEFAULT. If the type is also unset, the symbol will be DEFAULT.

equipmentContainers and boundingBoxes

Equipment containers are rendered on both layers with the same properties — the common properties plus:

PROPERTY	Type	Description
displayName	string	The container's name.
isUnderground	bool	Whether the majority of the container's conductors are underground, by total length where lengths are known, otherwise by count.
offSupply	bool	Present, and true, if every conducting equipment in the container is off supply. Only when true.
pen	int	A colour index from 0 to 13, derived from the container's name. Substations always use 13.

Public Geo View Tiles

Tiles served from the publicGeoView config carry a deliberately reduced set of properties, so a mapLayersConfig under publicGeoView can only match on these:

Layer	PROPERTY	Type	Description
conductors	isUnderground	bool	Whether the conductor is underground.
conductors	voltage	int	The base voltage of the conductor in volts.
conductors	pen	int	A colour index from 0 to 13, derived from the conductor's containers.
equipmentContainers, boundingBoxes	type	string	The simple name of the container's CIM class. Note this is type, not class as on the standard tiles.
equipmentContainers, boundingBoxes	isUnderground	bool	Whether the majority of the container's conductors are underground.
equipmentContainers, boundingBoxes	pen	int	A colour index from 0 to 13, derived from the container's name.

Assets of any other class carry no properties at all on the public geo view.

Capabilities

The capabilities of a layer describe how plugins may dynamically restyle the layer:

CAPABILITY	Description
voltageFiltering	How the layer participates in voltage filtering. One of respect-voltage-levels, any-level, or none.
enableDirectionArrows	Whether direction arrows may be drawn along the assets of this layer.
hasOffSupplyVariant	Whether the layer has a distinct style for assets that are off supply.
hasPartiallyOffSupplyVariant	Whether the layer has a distinct style for assets that are partially off supply.
enableRecolouring	Whether plugins may recolour the assets of this layer (generally, colouring AC Line Segments by voltage, container or phase).
enableFilteringByNetworkHierarchy	Whether the assets of this layer may be filtered by the network hierarchy.

Reference Config

The default configuration used for the geoView config, covering the standard EWB network map layers, is reproduced in full in the reference map layers configuration. It is what the server falls back to when no mapLayersConfig is provided, and it is a good idea to start from it and make modifications as needed, rather than writing a configuration from scratch.