Map Viewer
- PI Vision Widget -
Revision History
| Revision N. | Date | Author | Document ID | Description of changes |
|---|---|---|---|---|
| 9.2 | June 2025 | MDC | EW_MapViewer_v.9.2_en | Launch Configuration |
| 9.1 | June 2025 | MDC | EW_MapViewer_v.8.7_en | Added Google tiles |
| 9.0 | April 2025 | MDC | EW_MapViewer_v.8.7_en | PIVision 2024 compatibility |
| 8.7 | January 2025 | MDC | EW_MapViewer_v.8.7_en | Added Tooltip Attribute List UOM |
| 8.6 | December 2024 | MDC | EW_MapViewer_v.8.6_en | Added Tooltip formatter |
| 8.5 | November 2024 | MDC | EW_MapViewer_v.8.5_en | Bug Fix |
| 8.4 | October 2024 | MDC | EW_MapViewer_v.8.4_en | Added Asset remover |
| 8.3 | September 2024 | MDC | EW_MapViewer_v.8.3_en | Added KML e KMZ support |
| 8.2 | August 2024 | MDC | EW_MapViewer_v.8.2_en | Added ESRI Map Tiles Provider |
| 8.1 | July 2024 | MDC | EW_MapViewer_v.8.1_en | Manage Icons for Placeholder |
| 8.0 | June 2024 | AR | EW_MapViewer_v.8.0_en | User Manual |
Document References
| Document | Description |
|---|---|
| PI Vision Installation and administration Guide | PI Vision™ user manual from AVEVA ©. |
Introduction
Map widget allows to represent on a map data from AF database or available online. The map can have different layers, enabling the user to view different information on plants and processes in a geographical representation.
The map provider license is not included in the widget and is the responsibility of the customer.
The PI Vision of AVEVA is available from 2017 and allows viewing real-time data from PI Data Archive and data organized in assets from the AVEVA Asset Framework (PI-AF). In order to achieve PI Vision displays, simply access https://webServer/PIVision (indicating the correct name of the webserver machine).
The most recent versions of most HTML5 compatible browsers are supported on computers, tablets and phones running Android and iOS.
In PI Vision the configuration of the elements is quite intuitive and is characterized by a simple drag-and-drop of the control into the display.
Definitions, Acronyms and Abbreviations
Acronyms and definitions that are used in the current manual are listed below.
| Term | Definition |
|---|---|
| AF | Asset Framework |
Operating Principles and Use
To insert the Map in a display it is necessary to select firstly the icon relative to the control, then selecting the element to be displayed the user has to drag it on the display.
Once the mouse button is released a 2D map. Then, selecting the contextual menu, it is possible to access the widget configuration box.
The widget connects with the attribute's element that was used to launch the widget. It will search among itself and the descendants all the elements that match specific criteria (thoroughly explained in the next chapter). On the following image an example of a template with all the fundamentals attributes for the widget.
This is a list of all the configurable attributes loaded from the Map Widget. The ones that are required to have the Map Widget functioning are:
- Label, that will identify the name of the element on the map;
- Latitude;
- Longitude;
The other attributes will be explained in the next part of the manual.
Functionality and use
After a correct first configuration of the widget, the map will show all the placeholders on itself. It is possible to move freely around the map (with zoom in/out as well).
Figure 1 - Widget
The widget consists of a title, the legend, and the globe map. The map has 3 buttons at the top right that allow you to search for a geolocation, return to the initial position of the map, and switch the view between globe and 2D.
On the right side of the widget a legend allows the user to filter through the placeholders. Once you select a filter, only the elements containing it will be displayed.
Figure 2 - Widget’s Anatomy
Moving the mouse on a placeholder a tooltip will appear with some features that can be set on the configuration menu.
Figure 3 - Launch Configuration Using static values
Customization and configuration
The widget configuration allows to change the placeholders' appearance in terms of colours, text size and language visualization.
Modified settings are updated after the user saves the display with new settings and refreshes the web page.
Language
The section International allows users to choose the language with which the user visualizes labels and configuration parameters.
Figure 4 - International
Launch Configuration
The map's initial geographical positioning, which determines its default view, can be configured through distinct methods: either static initial values or dynamic. The constituent values for this positioning are latitude, longitude and altitude.
If configured as dynamic, these coordinates are programmatically derived from the attributes of the first asset defined within the system's configuration. It is imperative to note that in instances where multiple assets are present in the configuration, the system will issue an alert to the user, indicating potential ambiguity in the source of these dynamic coordinates. Conversely, if set to static, the precise numerical values for longitude, latitude, and altitude are directly utilized to establish the map's initial view.
Figure 5 - Launch Configuration Using static values
Figure 6 - Launch Configuration Using Root Element AF Attribute Values
Attribute Names
This section allows you to select the attributes on the AF Model that need to be displayed.
| Parameter | Description |
|---|---|
| Attribute Latitude | This attribute should contain the icon latitude in Double format. |
| Attribute Longitude | This attribute should contain the icon Longitude in Double format. |
| Attribute displayed Label | This attribute should contain the name to be below the icon in String format |
| Placeholder Color | This attribute should represent the color HTML friendly format (red, rgba(256,0,0,0), #FF0000). If no attribute is defined in the element, generic color defined in configuration is used. |
| Placeholder Attribute Name | This parameter refers to the SVG that has to be each element. If no one is given the widget used for selecting the SVG taken in configuration. This parameter is explained more thoroughly later. |
| Placeholder Attribute Link | This parameter should contain the link to be associated with the placeholder. If it is not configured, this parameter doesn't affect the widget. Otherwise, when you click on the element's icon it should redirect you to the page saved on the attribute. |
| Placeholder Category | This parameter defines the category of each attribute to be displayed on the tooltip. For each attribute with this category the name of the attribute and its values are represented on the tooltip. |
Figure 7 - Attribute Names
Map Configuration
In this section the user can decide which settings are displayed on the widget. Specifically:
- View legend flag, if activated, shows the legend on the right side of the map.
- View Home Button flag, if activated, shows the home button
- View Geo Coder flag, if activated, shows the search button
- View Scene Mode Picker flag, if activated, shows the view button
select different types of view for the map
Figure 8 - Map Configuration
Layer settings
In this section the user defines the directory where custom KML/KMZ files are stored.
If the user wants that all placeholders are filled with a specific SVG icon, then the user must insert it in the specific folder and specify the SVG name in the appropriate box.
Figure 9 - KML and KMZ Configuration
Elements
This section allows the user to configure the Request Hierarchy Flag. This flag allows retrieval of data from children and grandchildren elements of the one used to launch the widget. If not flagged it will show only the placeholder for the current element.
Figure 10 - Elements
Placeholder Configuration
This section allows the user to select the default svg to be shown for each element.
Figure 11 - Placeholder Configuration
Placeholder Icon Definition
This chapter is dedicated to summarize how it is possible to fix the icon on a placeholder.
- Leave empty the Placeholder Attribute Name, whilst configuring a default placeholder icon;
- Fill in the Placeholder Attribute with one of the names of the default svg;
- Add an svg to the specified folder and call it in the attribute by its filename.
Figure 12 - Placeholder Configuration
Provider Settings
This section allows the user to define the source of the map and as well the license token.
The map provider license is not included in the widget and is the responsibility of the customer.
Color can be defined for each of the following parameters.
Figure 13 - Provider Settings
Appearance Settings
In this section the user can set the text sizes of tile, text and tooltip's text.
Each time configuration parameters are associated with * character, it is necessary to save and reload the page to see the changes effectively executed.
Figure 14 - Appearance Settings
Contacts
Get Support button (read Get Support documentation)
Web link to e-matica.it
INSTALLATION
Following are the installation requirements and procedure.
Requirements
In order to install the product, minimum requirements are listed in the table below:
| Software | Version | Note |
|---|---|---|
| PI Vision | 2024(*) | Requirements are related to the correct functioning of the PI Vision |
(*) This widget is also compatible with PI Vision 2023, 2022, 2021, 2020 and 2019.
We suggest using Google Chrome for full compatibility with the widget.
Installation procedure
The installation procedure involves the copy of different folders and file in the predefined PI Vision path.
In particular it is necessary to copy the following files in the folder \\PIPC\\PIVision\\Scripts\\app\\editor\\symbols\\ext:
- sym-EWMapViewer-config.html
- sym-EWMapViewer-template.html
- sym-EWMapViewer.js
in the folder \PIPC\PIVision\Public\Libs:
- folder Cesium (entirely)
- EWClasses.js
in the folder \\PIPC\\PIVision\\Public\\images:
- folder Icons svg (entirely)
- EWMapViewer.png
Then, open the web.config file inside the PIVision folder (..\\PIPC\\PIVision) and check:
- that debug is set to "true"
- that the following parameters are present in the "appSettings" section
<add key="ScriptSrcPolicy" value="Disable" />
<add key="FrameSrcPolicy" value="*" />
- that the following parameters are present in the "fileExtensions" section (for using KMZ/KML files and Google as map provider)
<remove fileExtension=".kml" />
<remove fileExtension=".kmz" />
<remove fileExtension=".wasm" />
add fileExtension=".kml" allowed="true" />
<add fileExtension=".kmz" allowed="true" />
<add fileExtension=".wasm" allowed="true" />
- that the following parameters are present in the "staticContent" section (for using KMZ or KML files)
<mimeMap fileExtension=".kmz" mimeType="application/vnd.google-earth.kmz" />
<mimeMap fileExtension=".kml" mimeType="application/vnd.google-earth.kml+xml" />
Save the file and restart the IIS.
NOTES AND REFERENCES
For more information about PI Vision refer to documentation on the AVEVA portal.