User and developer guide

This guide explains how to display buildings and floors represented by Snap4City IoT devices with geometry data. Color, patterns and labels can use three independent metrics. The user guide explains the available dashboard features; the developer guide covers events, parameters, expected data and CSBL examples.

User guide

1. Preparing the visualization

Select a single device or a building model. To display a floor, select the corresponding floor device and floor number. Color rendering also requires an available color map for the selected metric.

Then select the color metric and the pattern metric. For example, capacity can determine the color, while its value can appear as a label over the shape; another variable, such as VILCD, can determine the pattern through its value. These names are examples: use metrics actually exposed by the devices and containing suitable values.

Visualization	What is displayed	When to use it
Colored shape only	Thematic fill with an outline.	To compare metric values across buildings using the corresponding color map.
Pattern only	Pattern overlay and outline.	To distinguish categories while keeping the base map readable.
Color and pattern	Pattern overlaid on color.	To represent two metrics using different visual encodings on the same building.

 

Adding or replacing layers

Additive mode keeps multiple representations: you can add the color first and then the pattern, including representations based on different metrics. The two layers can be removed separately. Multiple colored shapes and multiple patterns can also be overlaid. Colored shapes over the same building may blend because of their transparency.

To replace a view, remove the previous combination or all layers, then add the new view. Removal also invalidates pending loads, so their late responses do not redraw the removed layer.

The map widget also supports color and pattern combined in a single event (see Developer Guide). In that case, the combination is removed as a whole; if color and pattern were added as two separate layers, they can be removed independently.

The available controls depend on the dashboard interface. The features described here are provided by the map widget and can be configured through its parameters, even when a selector does not offer a dedicated option (see Developer Guide).

2. Pattern legend and zoom behaviour

The variable selected for the pattern must contain a code for each device. The code identifies the pattern design; the metric from which to read it is selected using bimPatternMetric (see Developer Guide), independently of the color metric. Code 0, missing data or an unrecognised code produces no pattern overlay. The standard mapping is shown below.

 

Pattern zoom

bimShapePatternZoomBehavior controls how the pattern scales with zoom (see Developer Guide). With "scaleWithMap", the widget default, the design grows or shrinks relative to the initial reference zoom. With "fixed", its dimensions remain constant on screen. The setting applies to all patterns in the same map; an explicit setting can override the default.

Popups and hover tooltips

Setting altViewMode to "BimShapePopup" enables the popup view, which opens device information when the shape is clicked; "BimShape" displays the shape without the BIM popup (see Developer Guide). The pattern overlay allows clicks to reach the underlying shape.

The hover tooltip identifies the building or device and can include the label content. When a fixed label is visible, the tooltip is normally hidden to avoid duplication; it becomes available again when the label is hidden because of zoom or overlap. When labels are disabled, bimShapeSuppressHoverTooltip can also suppress the tooltip (see Developer Guide).

 

3. Label text

Labels are fixed text placed at the centre of the bounding rectangle of the geometry. Their activation and content are controlled by bimShapeLabelsEnabled and bimShapeLabelContentMode (see Developer Guide). The four modes are metric name, metric value, device name, and device name with metric value.

Choosing the content

Content	Example	Behaviour
Metric name	capacity	Displays the name of the metric selected for the label.
Multiple names with additive layers	capacity - VILCD	In name mode, without an explicit label metric, joins distinct metric names from layers for the same building with " - ".
Metric value	42	Displays one value; the last metric registered for the label takes precedence.
Device name	Building A	Uses the available device name; does not invent an identifier if it is missing.
Device name and value	Building A - 42	Joins the name and the latest value of the metric selected for the label.

 

The label metric can differ from the color and pattern metrics: select it using bimShapeLabelMetric (see Developer Guide). Without an explicit selection, the metric name follows the current color metric or, if there is none, the pattern metric; modes that display a value first use any configured value metric. Device name only mode ignores the metric selection.

The order of aggregated names depends on load completion. Modes that display a value retain the value of the last registered metric; zero is valid. If data is missing, value only mode shows the metric name, while the combined mode shows whichever parts are available. Units and special numeric formatting are not added automatically.

Configuring label styles

Control	Practical use
Label font size and Label font	Size from 6 to 72 px; Arial, Calibri or Times New Roman.
Label font color and Label box	Text color and optional box. Without a box, the text has a contrasting outline.
Label min zoom	Displays the text from the selected zoom level onwards.
Avoid overlap	Hides overlapping labels; enabled by default.
Label activation	Text can be shown or hidden through the map configuration or bimShapeLabelsEnabled (see Developer Guide).

 

Device names and free text

The device name is read from the data. In combined mode, if the name is missing, only the value remains; if both are missing, no text is displayed. Direct free text is not currently supported; a string stored as the value of a metric can be used instead (see Developer Guide).

To update a layer that is already loaded, add the same combination again. The label is shared by layers for the same building: the last registered style takes precedence, and the label remains visible while other layers use it.

 

 

Developer guide

4. CSBL and basic calls

The CSBL communicates with the dashboard by emitting the jQuery event named addBimShape through the .trigger() method. The addBimShape listener in widgetMap accepts the event when event.target matches map.mapName. The widget retrieves geometries and values from the APIs.

const mapWidgetId = "EXACT_MAP_WIDGET_NAME";

const serviceUri = "http://www.disit.org/km4city/resource/"

  + "iot/orionUNIFI/DISIT/building_ACTUAL_ID";

const proxyApi = "../controllers/superservicemapProxy.php/api/v1/";

 

function emitBim(type, passedData) {

  parent.$("body").trigger({

    type: type,

    target: mapWidgetId,

    passedData: passedData

  });

}

 

const base = {

  query: proxyApi + "?serviceUri=" + serviceUri,

  queryType: "Default",

  modelInstance: "singleDevice",

  altViewMode: "BimShapePopup",

  desc: "Selected building",

  color1: "#ebb113", color2: "#eb8a13",

  targets: "",

  selectedMetrics: ["capacity", "occupancy", "VILCD"]

};

 

emitBim("addBimShape", Object.assign({}, base, {

  bubbleSelectedMetric: "capacity",

  bimPatternMetric: "VILCD"

}));

 

Replace the widget name, serviceUri and metrics with the appropriate values. The relative path is the one used in the CSBL examples and must be resolved in the dashboard context. Pass serviceUri as its original string value, without first applying encodeURI() or encodeURIComponent(). The example requires an iframe from the same origin with parent.$ available, as is typical for CSBL in widgetExternalContent. If the code runs in the JavaScript context of the dashboard main document, use $("body") instead.

Event	Effect	Payload
addBimShape	Loads and adds a representation.	passedData containing query and the relevant parameters (see the next table).
removeBimShape	Removes the shapes and/or patterns identified by the combination of query and metrics, including floorNumber when a floor is involved.	passedData with the same values used for display: query, bubbleSelectedMetric, bimPatternMetric and floorNumber, if applicable.
removeAllBimShapes	Removes all shape and pattern layers from the target map widget.	No specific field is required in passedData.
toggleAddMode	Changes the general mode (additive/exclusive). Existing layers are not changed immediately: the effect applies to subsequent additions.	addMode at the event level, not inside passedData.

 

 

5. Visualization parameters

All fields in the following table are properties of passedData except target, which belongs to the event itself.

Field	Type or values	Meaning
target	String at the event level	Exact name of the target widget, matching map.mapName.
query	String (URL)	With Default: serviceUri= for a device, or selection= and model= for an iot-search query.
queryType	String	Use "Default" for the examples in this guide. There are also branches for Sensor responses and other containers.
altViewMode	"BimShape" or "BimShapePopup"	The latter enables the BIM popup when the shape is clicked.
desc	String	Shape description; optional but recommended. It is NOT the label text.
bubbleSelectedMetric	Metric name or ""	Selects the color metric; empty for pattern only.
bimPatternMetric	Metric name or ""	Selects the metric containing pattern codes; empty for color only.
modelInstance	"singleDevice", "singleBuilding", "model" in the examples	The first two identify single-device use and centre the rendered geometry at zoom 18 using its bounds. "model" is used for multiple-device searches with iot-search.
floorNumber	Optional number	Omit for a whole building. 0 is valid. Floor searches also recognise M1, PT, P1, P2 and P3.
color1 and color2	Color strings	Interaction colors and metadata, for example "#ebb113". The thematic fill uses the metric color map.
targets	String	Comma-separated target widget IDs for interactions, trends or curves. Use "" if none are needed.
selectedMetrics	Array of strings	Metrics for popup information; does not select the color, pattern or label metric.
bimShapePatternZoomBehavior	"fixed" or "scaleWithMap"	Overrides the widget style. If absent, uses the style or scaleWithMap. The setting is shared by patterns in the same map.
bimShapeSuppressHoverTooltip	"yes" to suppress	Suppresses the tooltip when labels are disabled. With labels enabled, tooltip behaviour depends on label visibility.

 

 

6. Label parameters

The table lists label defaults, used when neither the event nor the saved map configuration supplies a value. "Available in More options" identifies settings exposed in the widgetMap interface; the others require an event, typically from CSBL.

Optional field	Values and defaults	Effect	Available in More options
bimShapeLabelsEnabled	"yes" / "no"; no	Enables or disables fixed labels.	Yes
bimShapeLabelContentMode	"name", "value", "deviceName", "deviceNameValue"; default name	Metric name, metric value, device name, or device name and value joined by " - ".	Only "name" and "value". Other modes: event only.
bimShapeLabelMetric	Metric name; absent	Explicit label metric in name, value and deviceNameValue. Ignored in deviceName.	No
bimShapeLabelValueMetric	Metric name; absent	For value and deviceNameValue if bimShapeLabelMetric is absent. Falls back to the color metric, then the pattern metric.	No
bimShapeLabelFontSize	Number 6–72; 12	Text size in pixels; out-of-range values are clamped.	Yes
bimShapeLabelFontFamily	Arial, Calibri, Times New Roman; Arial	Font; unsupported names fall back to Arial.	Yes
bimShapeLabelFontColor	Valid CSS color; black	For example "#123456".	Yes
bimShapeLabelBoxEnabled	"yes" / "no"; no	Label box; without a box, the text is given an outline.	Yes
bimShapeLabelMinZoom	Integer 0–22; 0	Minimum zoom. An explicit 0 overrides the widget style value.	Yes
bimShapeLabelAvoidOverlap	"yes" / "no"; yes	Hides overlapping labels.	Yes

Metric selection priority

In name mode: bimShapeLabelMetric, then bubbleSelectedMetric, then bimPatternMetric. In value and deviceNameValue modes: bimShapeLabelMetric, then bimShapeLabelValueMetric, then the color metric or the pattern metric. In deviceName mode, the explicit metric selection is ignored and no additional label metric request is made. A color or pattern metric is still required for this representation.

Content and defaults

If bimShapeLabelContentMode is omitted, the widget style applies; without a recognised choice, "name" is used. Explicit overrides take precedence. To enable specific content, pass bimShapeLabelsEnabled: "yes" and the desired mode. Selector options depend on its implementation.

Shared labels

In name mode, distinct metric names are aggregated. In value and deviceNameValue modes, only one value is retained, from the last registered metric. Labels are shared by layers for the same building; changing the mode rebuilds the shared content. Removing a layer preserves the label if other layers still use it.

 

7. APIs and color maps

The response must provide identifiable features, a building geometry and the requested metrics. This example shows a direct FeatureCollection for queryType Default; the same values may be included in Snap4City service responses.

{

  "type": "FeatureCollection",

  "features": [{

    "type": "Feature",

    "geometry": {"type": "Point", "coordinates": [8.60, 45.80]},

    "properties": {

      "serviceUri": "ACTUAL_DEVICE_URI",

      "deviceName": "Building A",

      "deviceModel": "buildingmodel1",

      "values": {

        "geometry": {

          "type": "Polygon",

          "coordinates": [[[8.60,45.80], [8.61,45.80],

            [8.61,45.81], [8.60,45.81], [8.60,45.80]]]

        },

        "capacity": 100, "occupancy": 23, "VILCD": 1

      }

    }

  }]

}

 

properties.values.geometry can be an object or a JSON string and replaces the location geometry. Use GeoJSON coordinates in longitude, latitude order and closed polygons. Rendering supports Polygon and MultiPolygon. In singleDevice and singleBuilding modes, automatic centering uses the center of the rendered layer bounds at zoom 18, without assuming a Polygon coordinate structure.

The main query metric is the color metric, if present, otherwise the pattern metric.

Required color map name

Context	Rule and example with occupancy
Standard building	colormapshape + exact metric name → colormapshapeoccupancy
Floor with floorNumber present	colormap + metric name with an uppercase initial + _floor → colormapOccupancy_floor
buildingModelEnergy15Min without floorNumber	colormap + metric name with an uppercase initial + _building → colormapOccupancy_building

 

The scale is requested from getColorMap.php through heatmapUrl; the legend image uses the same name in img/heatmapsGradientLegends. If the scale is missing or empty, loading the colored layer may stop. If a value falls outside the classes, grey is used as a fallback; intervals exclude the minimum and include the maximum. The colored fill has an opacity of 0.6.

 

 

8. Visualization examples and additive mode

The examples reuse emitBim and base from section 4. Run them after the complete initial loading of the dashboard.

Colored shape only

emitBim("removeAllBimShapes", {});

emitBim("addBimShape", Object.assign({}, base, {

  bubbleSelectedMetric: "capacity",

  bimPatternMetric: "",

  bimShapeLabelsEnabled: "no"

}));

 

Pattern only with fixed symbol dimensions on screen

emitBim("removeAllBimShapes", {});

emitBim("addBimShape", Object.assign({}, base, {

  bubbleSelectedMetric: "",

  bimPatternMetric: "VILCD",

  bimShapePatternZoomBehavior: "fixed",

  bimShapeLabelsEnabled: "no"

}));

 

Independent color and pattern layers

// toggleAddMode does not filter by target:

// it changes all listening maps in the dashboard.

parent.$("body").trigger({

  type: "toggleAddMode", addMode: "additive"

});

emitBim("addBimShape", Object.assign({}, base, {

  bubbleSelectedMetric: "capacity", bimPatternMetric: ""

}));

emitBim("addBimShape", Object.assign({}, base, {

  bubbleSelectedMetric: "", bimPatternMetric: "VILCD"

}));

 

For a single combination, set both metrics in the same event as in section 4. Patterns are drawn above the shapes.

 

9. Label examples and floor selection

Device name and value of an independent metric

emitBim("addBimShape", Object.assign({}, base, {

  bubbleSelectedMetric: "capacity",

  bimPatternMetric: "VILCD",

  bimShapeLabelsEnabled: "yes",

  bimShapeLabelContentMode: "deviceNameValue",

  bimShapeLabelMetric: "occupancy",

  bimShapeLabelFontSize: 16,

  bimShapeLabelFontFamily: "Calibri",

  bimShapeLabelFontColor: "#123456",

  bimShapeLabelBoxEnabled: "yes",

  bimShapeLabelMinZoom: 17,

  bimShapeLabelAvoidOverlap: "yes",

  bimShapePatternZoomBehavior: "scaleWithMap"

}));

 

With deviceName = "Building A" and occupancy = 23, the text is Building A - 23. For the value only, use bimShapeLabelContentMode: "value"; for the name only, use "deviceName". With "deviceNameValue", bimShapeLabelMetric: "VILCD" displays the name and pattern code. "name" displays the metric name instead; in additive mode, it can aggregate names from different layers.

Disabling labels and tooltips for a combination

emitBim("addBimShape", Object.assign({}, base, {

  bubbleSelectedMetric: "capacity", bimPatternMetric: "VILCD",

  bimShapeLabelsEnabled: "no",

  bimShapeSuppressHoverTooltip: "yes"

}));

 

This call replaces the same combination; labels shared with other layers may remain. The table in section 6 defines metric selection and priority.

Ground floor of a building

const floorUri = "http://www.disit.org/km4city/resource/"

  + "iot/orionUNIFI/DISIT/floor_ACTUAL_ID_PT";

const floorLayer = Object.assign({}, base, {

  query: proxyApi + "?serviceUri=" + floorUri,

  modelInstance: "singleDevice",

  floorNumber: 0,

  bubbleSelectedMetric: "occupancy",

  bimPatternMetric: "VILCD"

});

emitBim("addBimShape", floorLayer);

 

Use the serviceUri of the floor device, not the building device. For a single device, the selected resource determines the floor. In multiple-device searches, the filter compares floorNumber with properties.values.identifierName: M1 = -1, PT = 0, P1 = 1, P2 = 2, P3 = 3. The floor number also affects layer identity and the color map.

For multiple buildings or floors, use modelInstance: "model" and an iot-search query with selection= and model= for the actual model. The widget updates the selected area to the map bounds. For a single floor, identify the correct floor device through the building-to-floor relationships available in the data, checking that the match is unique.

 

10. Removal and integration checks

Removing the exact combination

// Single combination with color and pattern.

emitBim("removeBimShape", {

  query: base.query,

  bubbleSelectedMetric: "capacity",

  bimPatternMetric: "VILCD"

});

 

// Floor from section 9: preserve floorNumber = 0 as well.

emitBim("removeBimShape", {

  query: floorLayer.query,

  bubbleSelectedMetric: floorLayer.bubbleSelectedMetric,

  bimPatternMetric: floorLayer.bimPatternMetric,

  floorNumber: floorLayer.floorNumber

});

 

// All BIM layers in the target widget, with labels and legends.

emitBim("removeAllBimShapes", {});

 

To remove only a pattern that was added separately, use bubbleSelectedMetric: "" and its bimPatternMetric.