Image Overlay

The Image Overlay Block allows you to display a series of overlays atop a background image of your choosing. This allows for creating visualizations of your physical systems in a SCADA-style display.

Image Overlay Block

Block Configuration

The block’s configuration is broken up into three sections:

Image Background

First, define the background against which your overlays will be displayed using the following properties:

Image Overlay Background

  • Image Background: Provide a URL to one of your Application Files or to a publicly accessible URL. The field supports string templates, so you can dynamically change the image based on dashboard context.
  • Background Color: Choose a color to display behind the image. By default this is transparent, which will show the background of the dashboard block. That color changes depending on your current dashboard theme.
  • Default Zoom: By default, the image background will display at its natural size. Use this slider to zoom in or out when the block first loads. Users may change the image’s zoom within the block after its initial display.
  • Disallow user zoom in/out: When checked, the zoom controls will not appear on the block and users viewing the block will not be able to alter the zoom level.


Next, define a set of data queries whose resolved values will be used to back the overlays you apply to the block. While these are optional, in almost all cases you will build at least one query when configuring an Image Overlay Block.

Image Overlay Queries

Click the “Add Query” button to add a new query to the block. You may also clone a query by clicking the “Clone” icon in its header, and queries can also be removed from the block by clicking the “Delete” icon in the query header.

Each query takes the following properties:

  • Query Name: You will use this to reference the returned result of the query within your overlay configuration. The query name may only contain uppercase and lowercase letters; numbers; and underscores (_) and hyphens (-). Query names must be unique within the block.
  • Device IDs / Tags: Specify a device query targeting the devices whose values you would like to include in the query.
  • Attribute: Choose which attribute from your chosen device(s) whose value should be returned in the query.
  • Duration: Choose if this query should return the last received data point, or a value aggregated over a time period.
  • Aggregation: If necessary, choose an aggregation method for the query. This field is optional and only displays if:

    • The query involves one or more devices.
    • The query involves at least one device tag.
    • The query involves a duration other than “Last received data point.”


Finally, create a set of overlays to display within the block. There are multiple types of overlays, each with some unique configuration properties as outlined below.

Image Overlay Add Overlay

To add an overlay to the block, click the “Add Overlay” button and choose the type to add from the menu.

Regardless of type, each overlay takes the following common properties:

Image Overlay Common Properties

  • Position: This is the x,y location of the overlay atop your chosen image, where 0,0 is the image’s top left corner and positive numbers travel right and down respectively. While it is possible to manually enter a location for the overlay, you may also drag the overlays to their desired position within the block preview to set this value.
  • Size: Choose whether to display a Small, Medium (default), or Large overlay. Depending on the overlay type, this option manifests in different ways.
  • Popup Template: Optionally, each overlay can display a popup when clicked. The content is rendered as Markdown, and the following variables are available within the field:

    • {{QUERY_NAME.value}}: The returned result from one of your defined queries
    • {{QUERY_NAME.time}}: The time associated with the query’s value
    • {{ctx.VARIABLE_NAME}}: The current value of any of your dashboard’s context variables
    • {{block.width}}: The rendered width of the block in pixels
    • {{block.height}}: The rendered height of the block in pixels
    • {{block.theme}}: The current dashboard theme (“light” or “dark”)

There are multiple types of overlays, each of which takes a unique set of configuration properties and which displays differently within the block. Some of these properties can be changed conditionally.

Indicators display a simple icon with a color of your choosing.

Image Overlay Indicator

The overlay takes two properties that can be changed conditionally:

  • Shape: Whether the indicator should render as a circle, square, upwards-pointing triangle, downwards-pointing triangle, or octagon
  • Color: The fill color of the chosen indicator shape

Values display a rendered query value against a background color of your choosing. The text color automatically switches between light and dark depending on the overlay’s background.

Image Overlay Value

In addition to its conditional properties, the overlay requires one additional setting:

Conditionally, the following properties can also change:

  • Label: An optional string template to display beneath the rendered value
  • Color: The background color against which the value and label defined above is displayed

Bars display a simple bar graph atop your background image. The bar’s fill level can then increase or decrease as its rendered value changes.

Image Overlay Bar

The overlay requires the following additional properties:

  • Value: A string template for rendering the bar’s fill level. This value should always resolve to a number, or the bar will fail to fill.
  • Min: Combined with a max value, this string template is used to calculate the bar’s fill level from its defined value. This must resolve to a number less than the overlay’s “Max”.
  • Max: Combined with a min value, this string template is used to calculate the bar’s fill level from its defined value. This must resolve to a number greater than the overlay’s “Min”.
  • Bar Length: Independent of the overlay’s size, this can be used to lengthen or shorten the bar.
  • Orientation: This changes whether the bar fills vertically or horizontally (default).
  • Background: This is the color that displays within the unfilled portion of the bar (default is white).

Only one bar property can be changed conditionally:

  • Color: The fill color of the bar

Images display a graphic from your Application Files, from a data URL, or from a publicly accessible URL.

Image Overlay Image

The overlay only takes one conditional property:

  • Image URL: The URL of the image to display

Labels render a string of text directly on your image overlay.

Image Overlay Label

The overlay takes two conditional properties:

  • Label: A string template for the text to place atop the overlay
  • Color: The color of the rendered text

Overlay Conditions

Each overlay type has specific properties that can be changed given a series of expressions you define. To add a condition, click the “Add Condition” button within the overlay to which you would like to add it. A condition can be deleted by clicking the “Delete” icon within its header.

Image Overlay Conditions

The conditions can be rearranged by via drag-and-drop. The order of the conditions is extremely important as the first condition whose expression returns true will have its display properties applied to the overlay.

Block Examples

An Image Overlay Block is best used for two different purposes, though it can certainly be applied to other application scenarios.

Smart Environment

In the example within this page, the block is being used to visualize the properties of a smart environment. There are overlays to indicate:

  • Occupancy status of conference rooms
  • Availability of seating on the main office floor (assuming a “hot desk” setup)
  • Number of spots available in the building’s parking garage
  • Temperature of specific areas of the environment
  • Amount of foot traffic the environment has seen today

Image Overlay Block

By overlaying these values atop a blueprint of the physical environment, a building administrator can very quickly and easily gain insight into the environment and address any immediate needs.

SCADA Visualization

SCADA charts (Supervisory Control And Data Acquisition) are often used in industrial settings to get a realtime view into the status of a system. These charts often have:

  • Indicators to tell whether valves are open, power is provided to a machine, or systems are in a healthy state
  • Values representing numerical data such as water temperature, pipe pressure, or the count of items to come through a manufacturing line
  • Bars indicating the fill level of tanks against their maximum volume

Was this page helpful?

Still looking for help? You can also search the Losant Forums or submit your question there.