Canvases, Layers and Data Sources ################################# A **Show** is the root of the hierarchy tree of a 3D scene, consisting of Canvases, Layers, and Data Sources, as shown in the following diagram : .. figure:: ../images/5/1.png :width: 30% :align: center Tree composition of a Show | The Show may contain one or more Canvases, each Canvas can include multiple Layers, and each Layer can incorporate one or more Data Sources. | A Layer represents the actual geometry used to render the data provided by its own Data Sources. | A Data Source is composed of all the information needed to request the actual data to be rendered by the Layer it is attached to. | All data retrieved from any Data Source must adhere to the EPSG:4326 projection (WGS84). Canvases ======== | Currently, three types of Canvas are defined: Ellipsoidal Canvas, Planar Canvas, and Overlay Canvas. | The primary purpose of a Canvas is to dictate the geometry and georeferencing of a Layer. | If a Layer is applied to an **Ellipsoidal Canvas**, the geometry will conform to an ellipsoidal shape, with all geo-references being relative to that ellipsoidal shape. | Similarly, for the **Planar Canvas**, the geometry will adhere to a flat plane shape. A special case is the **Overlay Canvas**, which operates similarly to a Planar Canvas but is always oriented perpendicular to the viewer's direction. All objects related to the Overlay Canvas are anchored to the viewer's point of view. The Overlay Canvas can only be created or selected when the user adds an overlay image or label Data Source to a 3D Objects Layer. It does not apply to other types of Layers and Data Sources. More details about the Overlay Canvas are described in This chapter > "Layers" > "3D objects layer". .. figure:: ../images/5/2.png :width: 80% :align: center Surface Layer with the static image of the Earth mapped on an Ellipsoidal Canvas (the Default Canvas) .. figure:: ../images/5/3.png :width: 80% :align: center Simple Surface Layer with the static image of the Earth mapped on a Planar Canvas Layers ====== **Layers** hold the data that are meant to be represented in the 3D view. Every layer is responsible for a specific data type. This sub-chapter provides detailed information about each the layer type. Surface Layer ------------- | A **Surface Layer** is capable of rendering geo-referenced surface data mapped on either an Ellipsoidal Canvas or a Planar Canvas. | This section explains how to add and configure a Surface Layer. Add Surface Layer ~~~~~~~~~~~~~~~~~ To **add a Surface Layer** to the current Show, choose Layer > Add Layer > Surface option from the Menu Bar. .. figure:: ../images/5/3.png :width: 30% :align: center How to add a Surface Layer A modal window opens to configure the Surface Layer to create and set its Data Sources. .. figure:: ../images/5/4.png :width: 30% :align: center Modal window to add and configure a Surface Layer User can select the name of the Surface Layer to be added and specify which Canvas add it to, as explained in 3.1 Add Layer Sub-Menu. Additionally, user can manually specify the bounding box of an Area of Interest (AOI) through the Min/Max Lat/Lon edit text fields. | Two shortcut buttons are provided: - The **Global button** sets the AOI to the global extent of the Earth when pressed - The **Recompute button** sets the AOI to the union of the bounding boxes of all the Data Sources added to the Surface Layer when pressed | Please refer to the next section for instructions on adding or removing Data Sources to the Surface Layer being created. Add Data Sources to Surface Layer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ User can add or remove Data Sources to the list of sources that are going to create the Surface Layer, as in the modal window. .. figure:: ../images/5/6.png :width: 50% :align: center Buttons to add Data Sources It is possible to add a surface layer from different data sources (see This chapter > "Data Sources" for more information regarding Data Sources): 1. Images or videos from local storage or remote URL 2. From WMS 3. From JSON local file To remove an inserted Data Source, select it from the list and press the “-“ button at the bottom right of the list, as shown in the next figure. .. figure:: ../images/5/7.png :width: 50% :align: center Select the Data Source from the list and press “-“ button remove it The Surface Layer can blend **up to 5 Data Sources**. User can confirm the creation of the Surface Layer by pressing the OK button or abort the operation by clicking on the Cancel button. Surface Layer Inspector Panel ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When the user selects the Surface Layer by clicking on the respective item in the Hierarchy Panel or by selecting it from the 3D view, the Surface Layer UI card will be displayed in the Inspector Panel. .. figure:: ../images/5/8.png :width: 30% :align: center Selection of a Surface Layer in Hierarchy Panel The Surface Layer UI card is made of a list of collapsible sub-panels, one for each Data Source of the Layer. .. figure:: ../images/5/9.png :width: 80% :align: center Surface Layer UI card in Inspector Panel For each Data Source user can change: - The **blending factor**: lower value of the slider for Data Source transparency, higher values for Data Source opacity - The **crop latitude slider** - The **crop longitude slider** .. figure:: ../images/5/10.png :width: 80% :align: center Four blended Data Sources on a Surface Layer Geometry: Global Earth Image, gecho_bathy.5400x2700_float32, Daniel SWH and osmgray:ne_10m_admin_0_boundary_lines_land.png | It's possible to crop a Surface Layer's Data Source directly from the 3D view by enabling the **Show Bounding Boxes checkbox** and clicking on the desired Data Source to select it. | Once selected, four draggable handles will appear on the bounding box borders, allowing for cropping. .. figure:: ../images/5/11.png :width: 80% :align: center Handles to crop Data Sources of a Surface Layer Users can select a Data Source to serve as a Digital Elevation Model (DEM), enabling vertex displacement from the surface based on the data value. The DEM dropdown menu displays all available Data Sources. If a Data Source is chosen as a DEM, additional widgets will be revealed in the Surface Layer UI card: - **DEM Displacement Factor**: to increase/decrease displacement of DEM from the surface - **DEM Bump Strength**: to increase/decrease bump mapping effect (simulates surface texture by altering lighting based on height information) - **DEM Lighting**: to enable or disable bump mapping effect .. figure:: ../images/5/12.png :width: 80% :align: center DEM Parameters .. figure:: ../images/5/13.png :width: 80% :align: center Digital Elevation Model for SWH Data Source, with low bump strength and low displacement .. figure:: ../images/5/14.png :width: 80% :align: center Digital Elevation Model for SWH Data Source, with higher bump strength and low displacement .. figure:: ../images/5/15.png :width: 80% :align: center Digital Elevation Model for SWH Data Source, with high bump strength and high displacement | It’s possible to toggle Data Source rendering from the Surface Layer through the checkbox next to the Data Source name in the collapsible sub-panel. The effect of a disabled Data Source is the equivalent of having it enabled with the blending factor set to 0. .. figure:: ../images/5/16.png :width: 80% :align: center Example of disabled Data Sources and null blending factor: The Global Earth Image Data Source blending factor is set to 0, making it appear as if it were disabled and not rendered. | Volume Layer ------------ **Volume layers** enable the visualization of variables collected at different pressure levels over a specific geographic area. The data is represented as a three-dimensional cube that can be sliced and filtered to have a better understanding of complex phenomena like storms and hurricanes. Add Volume Layer ~~~~~~~~~~~~~~~~ To add a volume layer, go to "Add Layer" > "Volume". Then select a data source from local storage or from an external source. Refer to This Chapter > Data Sources for details. .. figure:: ../images/5/17.png :width: 20% :align: center Add volume layer | You can enable multiresolution ("Multires"). This feature is experimental, and may produce some artifacts when zooming close to the 3D visualization of the layer. | The last option, "Tile Size" allows to override the default tile size used for the layer data requests. .. figure:: ../images/5/18.png :width: 50% :align: center The "volume layer add" dialog Add Data Sources to Volume Layer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | You can choose the data source locally, by browsing a local JSON file or remotely, through and url. If the latter, you can set multiple parameters for the layer. Volume Layer Inspector Panel UI ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Using the timeline, user can navigate the dataset in time. Clicking on the layer card in the hierarchy tree shows the layer settings in the inspecor on the right. .. figure:: ../images/5/19.png :width: 80% :align: center Sample volume layer visualization The following settings are available : - **Render mode** allows to switch between different volume rendering modes. They are all based on the raymarch rendering technique, that computes an intensity value for each pixel, through the combination of the raw values collected by sampling rays originating from the camera position and crossing the volume. | o **Direct Volume Rendering** (the default option) applies a color map to the final intensity value computed on the previous step. | o **Maximum intensity projection** will draw only the maximum value encountered for each ray, with an opacity proportional to such value. | o **Isosurface Rendering** draw the data as isosurface. - **Data Min** and **Data Max** allow to define how the dataset raw values are mapped to the output colour scale. That is the “Data Min” is mapped to the colour scale first value, the “Data Max” is mapped to the colour scale last value and all intermediate values are linearly mapped to the other scale colours. All values beyond the limits are discarded. By default, they are initialized to the dataset minimum and maximum values. - **Visible Value Range** allows to dynamically filter out values (normalized based on the Min/Max values set in the “Data Min” and “Data Max” inputs) outside the define thresholds. - **Lighting** applies lighting to the volume pixel values. This allows to better highlight the volume iso-surfaces. - **Back-to-Front Direct volume Rendering** and **Early Ray Termination** parameters used internally by the ray sampler code. Exposed because changing them can reduce artifacts in some conditions. - **Cubic interpolation** Improves visualization quality at the expense of rendering performance. - **Max num steps** sets the number of samples used by the raymarching algorithm. Lower it to improve rendering performance. - **Longitude Range**, **Latitude Range** and **Altitude Range** allow to slice the volume cube by moving the planes orthogonal to the Longitude, Latitude and Altitude dimensions. - **The color map**, editable with the **Colormap Picker**. .. figure:: ../images/5/20.png :width: 25% :align: center Volume layer visualization settings | Volume can also be sliced directly in 3D by manipulating its bounding box. To enable the bounding box, check the relative checkbox above the layer hierarchy panel and click on the volume layer on the map. | Drag the handles to adjust the size. .. figure:: ../images/5/21.png :width: 80% :align: center Volume layer slicing 3D Objects Layer ---------------- A **3D Objects Layer** may contain these type of Data Sources: - **Georeferenced 3D Model**; - **Label**: | o Georeferenced Label; | o Georeferenced Billboard Label; | o Label Overlay; - **Image**: | o Georeferenced Image; | o Georeferenced Billboard Image; | o Image Overlay. | A 3D Objects Layer can be created by selecting Layer > Add Layer > 3D Objects. .. figure:: ../images/5/22.png :width: 40% :align: center 3D Objects Layer menu item Add 3D Objects Layer ~~~~~~~~~~~~~~~~~~~~ If 3D Objects menu item is selected, a popup appear in order to let the user choose the canvas type and the specific 3D Object data source that will be added to the layer. .. figure:: ../images/5/23.png :width: 40% :align: center 3D Objects Layer popup If **New Ellipsoidal Canvas or New Planar Canvas** is selected, three 3D Object data source types can be created: - Model; - Label (billboard or not) - Image (billboard or not) Selecting **Model** exposes the following parameters: - Name: the name of the 3D model - Load Model from Uri: the 3D model uri - Load Model from File: by clicking on the Folder icon, a popup appear for navigating inside the OS and selecting the 3D model file - Latitude, Longitude, Elevation: the 3D model coordinates - Rotation X, Rotation Y, Rotation Z: the 3D model orientation - Scale X, Scale Y, Scale Z : the scale values .. figure:: ../images/5/24.png :width: 40% :align: center 3D Objects Model data source popup Selecting **Label** shows the following parameters: - Label Name: the name of the 3D model - Label Text: the 3D label text - IsBillboard: if the checkbox is checked, the label will behave as a billboard (the label keeps itself oriented towards the camera), otherwise the label orientation will be static - Font Size: the 3D label font size - Wrapping: if the checkbox is checked, the label text will be splitted in one or more lines, otherwise it will be allocated on single line - Latitude, Longitude, Elevation: the 3D model coordinates - Rotation X, Rotation Y, Rotation Z: the 3D model orientation - Scale X, Scale Y, Scale Z : the scale values .. figure:: ../images/5/25.png :width: 40% :align: center 3D Objects Label data source popup Selecting **Image** allows to set the following parameters: - Name: the name of the image - IsBillboard: if the checkbox is checked, the image will become a billboard (the image keeps itself oriented towards the camera), otherwise the image orientation will be static - Uri: by clicking on the Folder icon, a popup appear for navigating inside the OS and select the image file - Latitude, Longitude, Elevation: the 3D model coordinates - Rotation X, Rotation Y, Rotation Z: the 3D model orientation - Scale X, Scale Y, Scale Z : the scale values .. figure:: ../images/5/26.png :width: 40% :align: center 3D Objects Image data source popup If in the 3D Objects Layer popup New Overlay Canvas type is selected, two type of 3D Object can be created: - Label Overlay - Image Overlay With **Label Overlay** selected, the following parameters are available : - Label Name: the name of the label overlay data source - Label Text: the label text - Font Size: the label font size - PosX, PosY: the label overlay 2D screen position - PosZ: the label position on the Z axis; the label is inside the 3D scene, so PosZ can be used in order to change the label depth value - Rect Width, Rect Height: the size of the 2D rectangle containing the label .. figure:: ../images/5/27.png :width: 40% :align: center 3D Objects Label Overlay data source popup If **Image Overlay** is selected, user is able to set the image following parameters: - Image Name: the name of the image - Load Image from Uri: by clicking on the Folder icon, a popup appear for navigating inside the OS and select the image file - Scale: the scale value - PosX, PosY: the image overlay 2D screen position - PosZ: the image position on the Z axis; the image is inside the 3D scene, so PosZ can be used in order to change the label depth value - Rect Width, Rect Height: the size of the 2D rectangle containing the image .. figure:: ../images/5/28.png :width: 40% :align: center 3D Objects Image Overlay data source popup Add Data Sources to 3D Objects Layer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | One or more 3D object data sources may be added to a 3D Objects Layer after its creation. | By selecting a created 3D Objects Layer inside left Hierarchy Panel, inside right Inspector Panel the relative UI card is opened: by clicking on ADD DATA SOURCE button, a popup appears for choosing the new data source to add. .. figure:: ../images/5/29.png :width: 80% :align: center 3D Objects Layer Inspector card for add Data Source In the popup user can to select the 3D object type, depending on the layer canvas type: - If Layer belongs to an Ellipsoidal Canvas or a Planar Canvas, the options are: | o Model | o Label | o Image - If Layer belongs to an Overlay Canvas, the options are: | o Label Overlay | o Image Overlay 3D Objects Layer Inspector Panel UI ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 3D Objects in the application can be Models, Labels or Images. Depending on the 3D object type, data card inside the Inspector Panel can be slightly different. | Model object type exposes the following parameters in the Inspector Panel, and all can be updated at runtime: - Time Of Interest - Name - Latitude, Longitude, Elevation - RotationX, RotationY, RotationZ - ScaleX, ScaleY, ScaleZ .. figure:: ../images/5/30.png :width: 80% :align: center Example of 3D models : Red Pin placed on Athens coordinates with Athens .. figure:: ../images/5/31.png :width: 30% :align: center 3D Model Inspector Panel Label object type displays these properties in the Inspector Panel : - Time Of Interest - Label Name - Label Text - Font - Font Color - Font Size - Wrapping - IsBillboard - Latitude, Longitude, Elevation - RotationX, RotationY, RotationZ - ScaleX, ScaleY, ScaleZ .. figure:: ../images/5/32.png :width: 30% :align: center Label Inspector Panel Image type data sources holds these parameters in the Inspector Panel, which can be updated at runtime: - IsBillboard checkbox - Latitude, Longitude, Elevation - RotationX, RotationY, RotationZ - ScaleX, ScaleY, ScaleZ .. figure:: ../images/5/33.png :width: 80% :align: center Image Inspector Panel By selecting a data source of type Label Overlay (ShowTitle in the Figure below), the Inspector Panel parameters that can be updated at runtime are: - Label Text: the label text - Font Size: the label font size - PosX, PosY: the label overlay 2D screen position - PosZ: the label position on the Z axis; the label is inside the 3D scene, so PosZ can be used in order to change the label depth value - Rect Width, Rect Height: the size of the 2D rectangle containing the label .. figure:: ../images/5/34.png :width: 80% :align: center Label Overlay Inspector Panel If Image Overlay is selected, the user is able to set the image following parameters: - Scale: the scale value - PosX, PosY: the image overlay 2D screen position - PosZ: the image position on the Z axis; the image is inside the 3D scene, so PosZ can be used in order to change the label depth value - Rect Width, Rect Height: the size of the 2D rectangle containing the image .. figure:: ../images/5/35.png :width: 80% :align: center Image Overlay Inspector Panel In every 3D Object data sources right Inspector Panel card there is a DELETE button: by pressing on it, the data source will be removed from the 3D scene and all its UI card and widget will be removed too. Power Network Layer ------------------- **Power network layers** are designed to provide 3D visualization of graph data related to power networks, encompassing node production/demand and power flowing between nodes. Add Power Network Layer ~~~~~~~~~~~~~~~~~~~~~~~ To add a power network layer, select “Power network” from the “Add Layer” menu. A popup like the one shown in Figure 4-45 is opened. To proceed the user must select a data source from the local file system. Once the data source it’s selected, the addition can be confirmed with the “Ok” button. .. figure:: ../images/5/36.png :width: 40% :align: center Power network layer add dialog Power Network Layer Inspector Panel UI ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A power network layer displays a set of vertical bars for each of the nodes of the network, representing the value of the selected node variables (e.g. wind power generation, power demand etc) for the currently selected timestamp. The links between the nodes are animated and coloured basing on the power flowing between the nodes. .. figure:: ../images/5/37.png :width: 80% :align: center Sample power network layer visualization To add a power network layer: "Layer" > "Add Layer" > "Power Network" .. figure:: ../images/5/38.png :width: 20% :align: center Add power network layer Clicking on a node opens a panel in 3D space at its side, showing the values of the variables for the selected node at the currently selected timestamp. .. figure:: ../images/5/39.png :width: 80% :align: center Power network node info panel | Clicking a second time on the same node will show the trend of the selected variable for the latest time steps in the form of an animated chart, still rendered on a 3D panel. (see Figure 60). | Multiple node info/series can be enabled at the same time to compare the trends on different locations. .. figure:: ../images/5/40.png :width: 80% :align: center Power network node time series As per other layers, when the network item is selected in the hierarchy tree, the visualization settings panel will appear in the right side of the user interface. The following settings are available to tweak the layer appearance: | • **Vertical scale**: Increase/decrease the height scale factor applied to the node bars. | • **Bar radius**: Increase/decrease the radius of the node bars | • **Link width**: Increase/decrease the line width used to display node links | • **Global scale**: A global scale factor that applies to all of the above scale settings | • **Show nodes**, “Show links”: Enable/Disable the visualization of the network nodes/links | • **Show power generation**, **Show power demand**, **Show power capacity**, **Show power diff**: Select the variables to display in the node bars representation. | • **Chart type**: Select the type of chart used for node series visualization. Available options are “Bar chart” and “Line chart” | • **Chart variable**: Select the variable to display in the series chart. Available options are “Production”, “Capacity”, “Demand” and “Difference” .. figure:: ../images/5/41.png :width: 20% :align: center Power network layer settings Viewpoint Layer --------------- | The purpose of **Viewpoint Layers** is to hold camera positions in the form of points in 3D space, called viewpoints. When a camera is attached to a viewpoint, it inherits the position and rotation, and the time instant where it’s placed. A viewpoint exists only in a single instant therefore it can be visible only when its time is aligned with the set current time. | Viewpoints are visible as spheres when gizmos are enabled. .. figure:: ../images/5/42.png :width: 80% :align: center A Viewpoint Layer with three viewpoints visible in the scene Add Viewpoint Layer ~~~~~~~~~~~~~~~~~~~ Clicking on the Viewpoint option opens the Viewpoint Layer panel. Here, beside the usual canvas and layer properties, user can set the name of the layer, the position and the orientation of the point, and the time instant. .. figure:: ../images/5/43.png :width: 25% :align: center Add Viewpoint Layer .. figure:: ../images/5/44.png :width: 40% :align: center Add Viewpoint Panel Viewpoint Hierarchy Panel ~~~~~~~~~~~~~~~~~~~~~~~~~ A viewpoint in the scene displays a special button in the hierarchy, the GO TO button which sets the camera position in correspondence of the position and rotation of the viewpoint, and setting the current time to the viewpoint time. .. figure:: ../images/5/45.png :width: 30% :align: center Viewpoint GO TO button in hierarchy panel Viewpoint Inspector Panel ~~~~~~~~~~~~~~~~~~~~~~~~~ The Viewpoint Layer Inspector Panel provides the options to add a viewpoint, through the Add Data Source Button, which opens up the relative panel, and to delete it with the Delete button. .. figure:: ../images/5/46.png :width: 30% :align: center Viewpoint Layer Inspector Panel The Viewpoint Inspector Panel allows to delete the viewpoint with the specific button and it shows the same editable properties found in the popup panel. Changes can be discarded or confirmed with Cancel and Apply. .. figure:: ../images/5/47.png :width: 30% :align: center Viewpoint Inspector Panel Data Sources ============ These are the existing types of **Data Sources** : - Images or Videos from local storage - WMS - User-defined JSON file from local storage Image/Video Data Source ----------------------- | To select an image or video as a Data Source, the user can interact with the corresponding UI, accessible when creating the appropriate Layer. | Supported image types include PNG, JPG, or GeoTIFF with floating-point values. | Supported video types include .mp4, .avi, and .mov. | While the format (RGB/RGBA or RAW) is indicated by the URI, users can configure other common parameters for images or videos, such as: | - Time Of Interest: optional, only if Time dependent checkbox is enabled | - Area Of Interest: default bounding box is set to the entire Earth | - Resolution: is 0 degrees (not specified) for any type of image or video .. figure:: ../images/5/48.png :width: 40% :align: center RGB Image Data Source insertion .. figure:: ../images/5/49.png :width: 40% :align: center Video Data Source insertion | Further information has to be provided for GeoTIFF images: | - Min Value and Max Value: clamp data to min and max values | - Colormap: colormap to apply to the rendered data .. figure:: ../images/5/50.png :width: 40% :align: center GeoTIFF Data Source insertion Image/Video Data Source Inspector Panel ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | The Inspector Panel for the Image/Video Data Source remains consistent regardless of the type of image or video. It features the following options: | - Bilinear Filter checkbox | - Format (RGB/RGBA or RAW) of the image or video | - Advance options (for RGB image only) | - Colormap Picker (for GeoTIFF only) | - AOI and TOI settings (if configured) .. figure:: ../images/5/51.png :width: 30% :align: center RGB Image Data Source Inspector Panel .. figure:: ../images/5/52.png :width: 30% :align: center GeoTiff Data Source Inspector Panel .. figure:: ../images/5/53.png :width: 30% :align: center Video Data Source Inspector Panel WMS Data Source --------------- To select WMS as a Data Source, the user can interact with the corresponding UI, which is available when creating the appropriate Layer. The WMS Data Source UI is exemplified in the following figure: .. figure:: ../images/5/54.png :width: 40% :align: center WMS Data Source insertion | When entering the WMS address in the URI text field and pressing the Get button, the other fields of the UI are automatically populated, although they can still be manually modified. | The exceptions are fields that must be configured by the user, such as the layer of the WMS to render via the Layer dropdown menu and whether it is time-dependent, which is indicated by the Time dependent checkbox. | The user can specify additional options to append to the WMS GetMap request, similar to URL parameters, for example: | &STYLES=default;colorrange=(230,340) | Additionally, users can change the order of the min/max latitude/longitude in the request when the WMS service does not precisely match the standard.  WMS Data Source Inspector Panel UI ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The WMS Data Source Inspector Panel appears like this : .. figure:: ../images/5/55.png :width: 30% :align: center WMS Data Source UI in Inspector Panel All the WMS parameters are exposed to the user, although only Options, BBox Order and Time format can be changed, other than the Time Of Interest and the Area Of Interest. Data Sources from JSON local file --------------------------------- You can save and load Data Sources locally as JSON files. You could potentially change manually or write a JSON file from scratch before uploading it, but this can be time consuming and prone to errors so it's not recommended.