Use image cards to display images and to associate data items with hotspot areas on the image.
The structure of the image card schema is as follows:
For the dashboard schema, see the Dashboard JSON reference topic.
An image card is defined in a cards array.
Example:
{
"cards": [{
"id": "sensor-readings-image",
"size": "LARGE",
"title": "Sensor Readings",
"type": "IMAGE",
"content": {
"alt": "Sensor Readings",
"zoomMax": 5,
"id": "world_map",
"hotspots": [{
"icon": "carbon-icon",
"color": "'#0F0",
"content": {
"title": "Sensor readings",
"description": "Image card for Sensor readings",
"attributes": [{
"dataSourceId": "temp_last",
"label": "Temperature",
"unit": "F"
}]
},
"type": "fixed",
"locations": [{
"x": "22.85",
"y": "33.183"
}],
"thresholds": [{
"dataSourceId": "temp_last",
"comparison": ">=",
"value": 100,
"color": "red",
"icon": "Close filled"
}]
}]
},
"dataSource": {
"attributes": [{
"aggregator": "last",
"attribute": "temp",
"id": "temp_last"
},
{
"aggregator": "last",
"attribute": "humidity",
"id": "humidity_last"
},
{
"aggregator": "last",
"attribute": "wind",
"id": "wind_last"
},
{
"aggregator": "last",
"attribute": "conditions",
"id": "conditions_last"
}
],
"range": {
"type": "rolling",
"count": -1,
"interval": "day"
}
}
}],
"title": "Example"
}
Table 1. Cards
Parameter | Description | Type | Required |
---|---|---|---|
id |
The id identifies the card in the JSON file. The ID must be unique per dashboard. |
string | yes |
size |
The size of the card. Valid values are MEDIUM ,MEDIUMWIDE , LARGE , and LARGEWIDE . Migrate your card size accordingly. |
string | yes |
title |
The title to display on the card. | string | yes |
type |
The type of card. Use IMAGE . |
string | yes |
content |
A definition of the content to display on the card. | object | yes |
dataSource |
Information about the source of each data item that is displayed on the card or that is used in thresholding. | object | yes |
timeRange |
The relative time range to select by default for the card. Valid values are last24Hours , last7Days , lastMonth , lastQuarter , lastYear , thisWeek , thisMonth ,
thisQuater and thisYear . |
string | no |
In cards.content
, specify the image to display. If you include hotspots, specify the information to display in the hotspot.
Example:
{
"content": {
"alt": "Sensor Readings",
"zoomMax": 5,
"id": "world_map",
"hotspots": [{
"icon": "carbon-icon",
"color": "'#0F0",
"content": {
"title": "Sensor readings",
"description": "Image card for Sensor readings",
"attributes": [{
"dataSourceId": "temp_last",
"label": "Temperature",
"unit": "F"
}]
},
"type": "fixed",
"locations": [{
"x": "22.85",
"y": "33.183"
}],
"thresholds": [{
"dataSourceId": "temp_last",
"comparison": ">=",
"value": 100,
"color": "red",
"icon": "Close filled"
}]
}]
}
}
Table 2. Content
Parameter | Description | Type | Required |
---|---|---|---|
hideMinimap |
Hide the minimap on the image. The minimap helps to orient you when you zoom in on the image. The default value is true . |
BOOLEAN | no |
hideHotspots |
Hide hotspots on the image. The default value is tfalse . |
BOOLEAN | no |
hideZoomControls |
Hide the zoom controls on the image. The default value is true . |
BOOLEAN | no |
zoomMax |
The maximum zoom level on the image. With zoomMax , you can zoom in beyond the 1:1 resolution of an image. Set zoomMax if you want to differentiate hotspots that are close together. |
integer | no |
alt |
Alternative text for the image. | string | no |
id |
The ID of the image. The ID must match an ID in the database. Note: When you add an image, you can associate multiple entities with a single image ID. You can associate different image files with each device. In a device dashboard, the image that is associated with that instance is displayed. If no image is found for the instance, the device image is displayed, if available. | string | yes |
hotspot |
A collection of hotspot objects. Each hotspot object in the array provides a definition of the hotspot. The hotspot definition might apply to a single location on the image or multiple locations. If you want to include a simple image on a card, omit the hotspot configuration. | array | no |
In cards.content.hotspots
, define the appearance of the hotspot, the content to display and the icon to use.
Example:
{
"hotspots": [{
"icon": "Information filled",
"color": "'#0F0",
"content": {
"title": "Sensor readings",
"description": "Image card for Sensor readings",
"attributes": [{
"dataSourceId": "temp_last",
"label": "Temperature",
"unit": "F"
}]
},
"type": "fixed",
"locations": [{
"x": "22.85",
"y": "33.183"
}],
"thresholds": [{
"dataSourceId": "temp_last",
"comparison": ">=",
"value": 100,
"color": "red",
"icon": "Close filled"
}]
}]
}
Table 3. Hotspots
Parameter | Description | Type | Required |
---|---|---|---|
icon |
The name of the hotspot icon. Specify an icon from the UI icons library in the Carbon Design System. Use the icon name from the design system. For example, to assign
an Information filled icon, enter "icon": "Information filled" . If no icon is specified, the hotspot is rendered as a semi-transparent circle. For more information about specifying an icon, see the Icons section
of Dashboard features. |
string | no |
color |
Defines the color of the hotspot icon. Specify the color using its hex code or its name. The hex code must start with # and be 7 characters long. If you specify the name of the color, the name must be in lower case, for example, purple . |
string | no |
content |
Define the information to display in each hotspot. | object | yes |
locations |
Define the location of the hotspot on the image card. | array | yes |
thresholds |
Define alerts to apply to the hotspot. | array | no |
borderWidth |
Define the width of the hotspot border. | string | no |
backgroundOpacity |
Level of opacity in the bakground. Use a value between 0 and 100. | string | no |
fontSize |
Font size for the hotspot text. | string | no |
type |
Defines the type of hotspot. Set to fixed to define the location of the hotspot by using x and y coordinates. Set to dynamic , to specify the location using data items. Set to text to display the hotspot as a label that this always visible. |
string | yes |
fontSize |
Font size for the hotspot text. | string | no |
fontSize |
Font size for the hotspot text. | string | no |
fontColor |
If setting a label, use to set the font color. | string | no |
backgroundColor |
If setting a label, use to set the background color of the label. | string | no |
borderColor |
If setting a label, use to set the border color of the label. | string | no |
In cards.content.hotspots.content
, specify a title to display on each hotspot and specify the data items to display in each hotspot location.
Example:
{
"content": {
"title": "Sensor readings for {deviceid} ",
"description": "Image card for Sensor readings",
"attributes": [{
"dataSourceId": "temp_last",
"label": "Temperature",
"unit": "F"
}]
}
}
Table 4. Hotspots content
Parameter | Description | Type | Required |
---|---|---|---|
title |
The title to display on the hotspot. You can add {deviceid} to the title to display the ID of the associated device. | string | yes |
description |
A description of the hotspot content. | string | no |
attributes |
Defines the data items to display in each hotspot. | object | yes |
In cards.content.hotspots.content.attributes
, specify the data items to display in each hotspot. The same data items are displayed in each hotspot on a card.
Example:
{
"attributes": [{
"dataSourceId": "temp_last",
"label": "Temperature",
"unit": "F"
}]
}
Table 5. Attributes
Parameter | Description | Type | Required |
---|---|---|---|
dataSourceId |
A unique ID for the data item whose value is displayed. The data item must also be defined in the dataSource object. |
string | yes |
Label |
The label to use for the data item. | string | yes |
unit |
Specify the unit that the data item is measured in, for example, % . |
string | no |
In cards.content.hotspots.locations
, specify each hotspot location using a location object.
Examples:
The following is an example of specifying the location by using x
and y
coordinates. You must use this approach for labels.
{
"locations": [{
"x": 65,
"y": 65.5
}]
}
In the following example, the x
and y
coordinates are specified using data items.
{
"locations": [{
"xDataSourceId": "x",
"yDataSourceId": "y"
}]
}
Table 6. Locations
Parameter | Description | Type | Required |
---|---|---|---|
x |
Percentage placement from the left of the image card. The valid range is 0 to 100%. For 10%, enter a value of 10. For help with defining the x value, see Defining the location of hotspots |
string | no |
y |
Percentage placement from the top of the image card. The valid range is 0 to 100%. For 10%, enter a value of 10. For help with defining the y value, see Defining the location of hotspots |
string | no |
xDataSourceId |
Represents the percentage placement from the left of the image card. Enter x . Specify the actual value in a data item named x in the data lake. |
string | no |
yDataSourceId |
Represents the percentage placement from the top of the image card. Enter y . Specify the actual value in a data item named y in the data lake. |
string | no |
In cards.content.hotspots.thresholds
, define alerts.
Example:
{
"thresholds": [{
"dataSourceId": "temp_last",
"comparison": ">=",
"value": 100,
"color": "red",
"icon": "Close filled"
}]
}
Table 8. Thresholds
Parameter | Description | Type | Required |
---|---|---|---|
color |
The color of the alert. Specify the color using its hex code or its name. The hex code must start with # and be 7 characters long. If you specify the name of the color, the name must be in lower case, for example, purple . |
string | no |
comparision |
The comparison operator to apply to the threshold value. Valid values are > , < , or = . |
string | no |
icon |
The icon to display if an alert is generated. Specify an icon from the UI icons library in the Carbon Design System. Use the icon name from the design system. For
example, to assign an Warning filled icon, enter "icon": "Warning filled" . For more information about specifying an icon, see the Icons section of Dashboard features. |
string | no |
value |
The threshold value. | string | no |
In cards.dataSource
, connect the information that is displayed on a hotspot on a card or that is used in alerts to data items in the data lake.
Example:
{
"dataSource": {
"attributes": [{
"aggregator": "last",
"attribute": "temp",
"id": "temp_last"
},
{
"aggregator": "last",
"attribute": "humidity",
"id": "humidity_last"
},
{
"aggregator": "last",
"attribute": "wind",
"id": "wind_last"
},
{
"aggregator": "last",
"attribute": "conditions",
"id": "conditions_last"
}
],
"range": {
"type": "rolling",
"count": -1,
"interval": "day"
}
}
}
Table 9. dataSource
Parameter | Description | Type | Required |
---|---|---|---|
attributes |
A definition of the source of the data that is used in hotspot and in alerts. | array | yes |
range |
Specifies a time range for the data items. | array | no |
In cards.dataSource.attributes
, specify the aggregation method to apply to each attribute or data item.
Example:
{
"attributes": [{
"aggregator": "last",
"attribute": "temp",
"id": "temp_last"
},
{
"aggregator": "last",
"attribute": "humidity",
"id": "humidity_last"
},
{
"aggregator": "last",
"attribute": "wind",
"id": "wind_last"
},
{
"aggregator": "last",
"attribute": "conditions",
"id": "conditions_last"
},
{
"attribute": "y",
"id": "x"
},
{
"attribute": "y",
"id": "y"
}
]
}
Table 10. dataSource attributes
Parameter | Description | Type | Required |
---|---|---|---|
aggregator |
An aggregation method to apply to the data item at the dashboard level. Valid values min , max , mean , first , count , std , sum , last . If you do
not specify an aggreator, a value of last is used. |
string | yes |
attribute |
The data item name. Corresponds to a name in the data lake. | string | yes |
id |
An ID for the data item. The ID corresponds to the dataSourceId . |
string | yes |
In cards.dataSource.range
, you specify the time range for all data items that are displayed on the card or are used in threshold definitions.
Example:
{
"range": {
"type": "rolling",
"count": -1,
"interval": "day"
}
}
Table 11. Range
Parameter | Description | Type | Required |
---|---|---|---|
type |
Valid values are rolling or periodToDate. Rolling period rolls to the current date whereas periodToDate ends on the first day of each calendar month. If you select periodToDate , and you set to the range to
the last 2 months, on Dec 2, the date range is up until the 1st of December (the first day of the current calendar month). |
string | yes |
count |
A negative number representing the number of interval units to subtract from the dashboard end date. For example, if the dashboard end date is today and the time interval is "day", enter -1 to display the last 24 hours of
data in the card. |
string | yes |
interval |
Time interval. Valid values are hour , day , week , month , quarter , year . |
string | yes |