diff --git a/docs/user-guide/annotations.md b/docs/user-guide/annotations.md index d1129f653ad..dd0d1574c29 100644 --- a/docs/user-guide/annotations.md +++ b/docs/user-guide/annotations.md @@ -1,23 +1,17 @@ # Annotations -[Mapstore](https://mapstore.geosolutionsgroup.com/mapstore/#/) lets you enrich the map with special features which expose additional information, mark particular position on the map and so on. -Those features make up the so called **Annotations** layers. +[MapStore](https://mapstore.geosolutionsgroup.com/mapstore/#/) lets you enrich the map with special features which expose additional information, mark particular position on the map and so on. +Those features make up the so-called **Annotations** layers. -Starting from a new map or an already existing one, the editor can access the **Annotations** button from the [TOC](toc.md) panel on the top-left corner of the map viewer. +Within the map viewer, the editor can access the **Annotations** tool button from the [TOC](toc.md) panel on the top-left corner of the map viewer. - The annotation panel will open: + The annotation panel will open and the editor can insert a **Title** (required) and a **Description** (optional). -## Add new Annotation - -To begin, from the annotation panel, the editor can open the new annotation panel by selecting the button. - - - -From here the editor can insert a **Title** (required), a **Description** (optional) and choose between five different types of **Geometries**: +From the *Geometries* tab, the editor can choose between five different types of **Geometries**: * **Marker** * **Line** @@ -25,11 +19,13 @@ From here the editor can insert a **Title** (required), a **Description** (optio * **Text** * **Circle** + + After selecting a geometry type, the editor can: * Draw a *Geometry* on the map. - + * Enter the vertices of the geometry or modify the existing ones through the **Coordinates editor** using `Decimal` or `Aeronautical` formats. @@ -40,105 +36,147 @@ After selecting a geometry type, the editor can: !!! note - If the vertices are invalid, they are notified with a red exclamation point. + If the vertices are invalid, they are notified with a red exclamation point and the geometry field is outlined in red. - In this case, it is not possible to add new geometry or save the annotation until a valid value is entered. It is still possible to interact with the geometries already present in the annotation, by zooming in on it or deleting it, as follows: + In this case, it is not possible to save the annotation, as follows: * Customize the **Style** of the annotation, as explained in the following paragraph. -Once the geometry has been saved through the **Save** button, for each geometry created, the editor can perform the following operations: +For each geometry created, the editor can perform the following operations: -* **Zoom** to the geometry annotation on map through the button +* **Zoom** to the annotation geometry on map through the button -* **Delete** the geometry annotation through the button +* **Delete** the geometry annotation through the button -Once all the *Geometries* have been created, the editor can save the annotation through the **Save** button that will be visible in the annotation list: +Once all the geometries are created, the user can go back to the [TOC](toc.md) by clicking the button. A new annotation layer will appear here. - + -Then, if not present, a new **Annotations** layer will be created and added to the [TOC](toc.md) +From the [TOC](toc.md), the *Annotations toolbar* allows the user to: - + + +* **Delete** the annotation through the button + +* Enable the [**Compare tool**](toc.md#toolbar-options) through the button + +* **Edit** the annotation through the button + +* **Download** the annotation through the button ## Styling Annotations -Based on which type of annotation was chosen, [MapStore](https://mapstore.geosolutionsgroup.com/mapstore/#/) allows you to customize the annotation style through a powerful editor. It is accessible from the *Style* tab of the annotation viewer. During the style editing a preview placed on top of the styler form shows a preview of the edited style. +Based on which type of annotation is chosen, [MapStore](https://mapstore.geosolutionsgroup.com/mapstore/#/) allows to customize the annotation style through a powerful style editor. It is accessible from the *Style* tab of the annotation viewer. +!!! note + For each style symbolizer there are many 3D style options available, as shown in the [Styling on 3D](annotations.md#styling-on-3d) section below. + ***Marker*** -MapStore provides two types of *Marker* annotations, so you have to choose what type do you prefer using the *Type* combo box (*Marker* is the default): +MapStore provides different *Marker* annotation style: + +* The *Mark* type: clicking on the button, the Mark symbolizer panel opens. -* *Marker* types can be customized through the following editor: +The Mark can have different `Shape`, `Fill color` and `Stroke` with different, `Stroke color`, `Width`, `Stoke style` and customizable `Radius` and `Rotation`. Take a look at the following example. -Choose the `Shape`, `Color` and `Icon` that best fit your needs. +* The *Icon* type: clicking on the button, the Icon symbolizer panel opens. +The icon can have different `Image`. Clicking on it, the user can choose a *Marker* and a *Glyph*, as follows: + + -* *Symbol* types can have different `Shape` and `Size`, a `Fill color` with a customizable `Opacity` level (%), a `Stroke` of different types (continuous, dashed, etc) and customizable `Color`, `Opacity` and `Width`. Only few symbols are provided by default in MapStore but a custom list of symbols can be configured. +The icon is also customizable with different `Opacity`, `Size`, `Rotation` and `Anchor point`. - +!!! note + For Marker annotation, in 3D Navigation, the *3D model* symbolizer type is also available, as shown in the [Styling on 3D](annotations.md#styling-on-3d) section below. -***Polyline*** +***Line*** -*Polyline* annotations can be styled using the following editor: +The *Line* annotation has a dedicated styling panel with a customizable `Stroke` with different `Color`, `Width` and `Style` and different `Line cap` (*Butt*, *Round*, *Square*) and the `Line join` (*Bevel*, *Round*, *Miter*). Take a look at the following image. -You can customize the `Stroke` in order to consider the `Line/Dash` type (continuous, dashed, dotted, etc), `Color`, `Opacity` and `Width`. You can also have styled *Start*/*End Points*: enable the StartPoint *Style*/*EndPoint Style* panel using the corresponding check box, the editor will be the same used for *Marker*/*Symbol annotations*. +The line annotation is also customizable adding a Mark symbolizer by clicking on the button or the Icon one with the button and choose *Start Point*, *Center* or *End Point* from the `Geometry transformation` option. + + ***Polygon*** -With polygonal annotations changing the style means choose the `Shape` and the size the `Size` of the polygon, its `Fill color` (with custom `Opacity`), the type of the `Stroke` (continuous, dashed, dotted, etc), its `Color`, `Opacity` and `Width`. -See the example below to better understand these options. +The *Polygon* annotation can have different `Fill` color and `Outline` with different `Color`, `Width` and `Style`. Take a look at the following example. +Also for the polygon itis possible to add a *Mark* or an *Icon* symbolizer in the same way as for Line annotations. + ***Text*** -*Text* annotations are a bit different from the geometric ones. They display a formatted text on a given point of the map. -The style editor allows you to customize the text `Font` (`Family`, `Size`, `Style`, `Weight`), the `Alignment` (`left`, `center` or `right`) and `Rotation`. -You can also choose the text `Fill color` and its `Opacity`, the `Stroke` type, its `Color`, `Opacity` and `Width`. Take a look at the following example. +Defining a point geometry with an associated text, the *Text* annotation allows to customize label trough many options such as: `Font Family` (*DejaVu Sans*, *Serif*, etc), the font `Color`, `Size`, `Style` (*Normal* or *Italic*) and `Halo weight` (*Normal* or *Bold*) and it allows also to select the desired `Anchor point`(*Center*, *Bottom left*, etc), `Halo color` and `Halo weight`. It is also possible to choose the text `Rotation` and `Offset` (*x* and *y*). En example can be the following one. ***Circle*** -Circle annotations can have custom `Fill color` (with custom `Opacity`), `Stroke` type (continuous, dashed, dotted, etc) with custom `Color`, `Opacity` and `Width`. The *Center* can be also customized through the same editor described for *Marker* annotations. -See the example below. +The *Circle* annotation has its own symbolizer panel to customize the `Color` and the `Outline` with different `Color`, `Width` and `Style`. Take a look at the following example. -Click on to apply the style. +The *Center* of a *Circle* annotation can be also customized by adding a *Mark* or an *Icon* symbolizer in the same way as Line and polygon annotations. + +## Settings Annotations + +Once all the annotation *Geometries* are created, the user can customize the usual **Visibility limits** by clicking on the *Settings* tab. + + + +The **Visibility limits** allow the annotation to be displayed only within certain scale limits. The user can set the *Max value* and the *Min value* and select the *Limits type* choosing between `Scale` or `Resolution`. + +## Annotations on the 3D navigation + +[MapStore](https://mapstore.geosolutionsgroup.com/mapstore/#/) allows the visualization of the *Annotations* also for the [3D Navigation](navigation-toolbar.md#3d-navigation). + + + +### Geometries on 3D + +On the [3D Navigation](navigation-toolbar.md#3d-navigation), after selecting a geometry type and drawing the geometry on the map, the user can also modify the geometry **Height** for each coordinate. + + + +### Styling on 3D + +For *Marker* annotations, on the [3D Navigation](navigation-toolbar.md#3d-navigation) the **3D model** symbolizer type is also available. +From the *Style* tab, by clicking on button, the 3D model option opens to allow adding a 3D model (based on [glTF](https://github.com/KhronosGroup/glTF), GLB is also allowed) as an external graphic by specifying its *URL* (see also the [Cesium documentation](https://cesium.com/learn/cesiumjs/ref-doc/ModelGraphics.html?classFilter=Model)). Furthermore, it is possible to customize the 3D model `Scale`, `Rotation` and `Color`. Take a look at the following example. -## Managing Annotations + -Once annotations are added to the [TOC](toc.md), the editor can **Manage** them by clicking to button from the TOC toolbar and the *Main Annotations panel* will be open. +Furthermore, for the [3D Navigation](navigation-toolbar.md#3d-navigation), [MapStore](https://mapstore.geosolutionsgroup.com/mapstore/#/) adds some additional styling options such as: - +* **Bring to front** (available for Point and Text geometries) to bring in front and so to make visible (if set to *true*) the annotation covered by 3D Tile layers and the Terrain layer (for this last case when the *depth test against terrain* option is enabled in Global Settings). -From it, the editor is allowed to: + -* **Download** a file with all the existing annotations by clicking on button +* **Height reference from ground** (available for Point and Text geometries) to indicate the reference for the point height between `None` (to the absolute zero of the ground), `Relative` (to the terrain layer level) or `Clamp` (the annotation is clamped to the Terrain, if present, or to the ground). It is also possible to finely configure the **Height** value of the point. -* **Upload** annotations from a valid `json` file by clicking on button + -* **Zoom** an annotation on map by clicking on button +* **Leader line** (available for Point and Text geometries) to add a line to connect the point symbol with the Terrain/Ground to have a more clear reference of the effective point position when the camera orientation change. The editor can choose the **Width** of the line and the **Color** through the usual *color picker*. -* **Show/Hide** an annotation on the map by clicking on button + -From the *Main Annotations Panel*, by selecting an annotation from the list, the editor is returned to the *Annotation Viewer* where the annotation can be edited. +* **Clamp to ground** to enable/disable the boolean property specifying whether the line or polygon should be clamped to the ground (this option is available for Line and Polygon geometries). - + -In particular, the editor can: +* **Clamp to ground reference** to choose whether the drape effect, should affect `3D Tiles`, `Terrain` or `Both`. This option is available for Line, Polygon and Circle geometries and it is only enabled when the *Clamp to ground* option is set to `True`. -* Change the *Coordinates* and the *Style* by clicking a geometry from list of geometries. + - +* **Extrusion Height** (available for Line and Fill geometries) to configure the height value of the feature to be extruded. It is also possible to enable/disable the **Extrusion relative to geometry** (from the highest point of the feature geometry) and, only for the *Line* geometries, the user can customize the **Extrusion color** and the **Extrusion type**, choosing between `Wall`, `Circle` and `Square` options, for the extruded features. -* **Download** the annotation in `json` format and reused in other maps by clicking on button + diff --git a/docs/user-guide/img/annotations/3d_annotations.jpg b/docs/user-guide/img/annotations/3d_annotations.jpg new file mode 100644 index 00000000000..b657489acea Binary files /dev/null and b/docs/user-guide/img/annotations/3d_annotations.jpg differ diff --git a/docs/user-guide/img/annotations/3d_model_type.jpg b/docs/user-guide/img/annotations/3d_model_type.jpg new file mode 100644 index 00000000000..e10e2c4a0c1 Binary files /dev/null and b/docs/user-guide/img/annotations/3d_model_type.jpg differ diff --git a/docs/user-guide/img/annotations/add_vertex_button.mp4 b/docs/user-guide/img/annotations/add_vertex_button.mp4 index 33fca4d9126..ae1d5dd19d6 100644 Binary files a/docs/user-guide/img/annotations/add_vertex_button.mp4 and b/docs/user-guide/img/annotations/add_vertex_button.mp4 differ diff --git a/docs/user-guide/img/annotations/annotation2.jpg b/docs/user-guide/img/annotations/annotation2.jpg index c6bc44286b8..ab9332c02a2 100644 Binary files a/docs/user-guide/img/annotations/annotation2.jpg and b/docs/user-guide/img/annotations/annotation2.jpg differ diff --git a/docs/user-guide/img/annotations/annotation3.jpg b/docs/user-guide/img/annotations/annotation3.jpg new file mode 100644 index 00000000000..70a50251a70 Binary files /dev/null and b/docs/user-guide/img/annotations/annotation3.jpg differ diff --git a/docs/user-guide/img/annotations/annotation_tool.jpg b/docs/user-guide/img/annotations/annotation_tool.jpg index 5610bdd71bc..3a12bf9f4f2 100644 Binary files a/docs/user-guide/img/annotations/annotation_tool.jpg and b/docs/user-guide/img/annotations/annotation_tool.jpg differ diff --git a/docs/user-guide/img/annotations/annotations_on_toc.jpg b/docs/user-guide/img/annotations/annotations_on_toc.jpg index 8bf2b825fa5..a3d805df193 100644 Binary files a/docs/user-guide/img/annotations/annotations_on_toc.jpg and b/docs/user-guide/img/annotations/annotations_on_toc.jpg differ diff --git a/docs/user-guide/img/annotations/annotations_toolbar.jpg b/docs/user-guide/img/annotations/annotations_toolbar.jpg index 6621c53a3a8..28a613d8173 100644 Binary files a/docs/user-guide/img/annotations/annotations_toolbar.jpg and b/docs/user-guide/img/annotations/annotations_toolbar.jpg differ diff --git a/docs/user-guide/img/annotations/bring-to-front.jpg b/docs/user-guide/img/annotations/bring-to-front.jpg new file mode 100644 index 00000000000..82d1f6adb81 Binary files /dev/null and b/docs/user-guide/img/annotations/bring-to-front.jpg differ diff --git a/docs/user-guide/img/annotations/circle_style_editor.jpg b/docs/user-guide/img/annotations/circle_style_editor.jpg index dfd7ee22d1a..f5fc55075f7 100644 Binary files a/docs/user-guide/img/annotations/circle_style_editor.jpg and b/docs/user-guide/img/annotations/circle_style_editor.jpg differ diff --git a/docs/user-guide/img/annotations/clamp-to-ground.jpg b/docs/user-guide/img/annotations/clamp-to-ground.jpg new file mode 100644 index 00000000000..c37c0a4a1a8 Binary files /dev/null and b/docs/user-guide/img/annotations/clamp-to-ground.jpg differ diff --git a/docs/user-guide/img/annotations/coordinates_format_switcher.mp4 b/docs/user-guide/img/annotations/coordinates_format_switcher.mp4 index 2f70e8651b5..dca4738bafe 100644 Binary files a/docs/user-guide/img/annotations/coordinates_format_switcher.mp4 and b/docs/user-guide/img/annotations/coordinates_format_switcher.mp4 differ diff --git a/docs/user-guide/img/annotations/extrusion-geometry.jpg b/docs/user-guide/img/annotations/extrusion-geometry.jpg new file mode 100644 index 00000000000..94c89205292 Binary files /dev/null and b/docs/user-guide/img/annotations/extrusion-geometry.jpg differ diff --git a/docs/user-guide/img/annotations/geometries-tab.jpg b/docs/user-guide/img/annotations/geometries-tab.jpg new file mode 100644 index 00000000000..f6f1c222cb4 Binary files /dev/null and b/docs/user-guide/img/annotations/geometries-tab.jpg differ diff --git a/docs/user-guide/img/annotations/height-reference.jpg b/docs/user-guide/img/annotations/height-reference.jpg new file mode 100644 index 00000000000..596fdba7c02 Binary files /dev/null and b/docs/user-guide/img/annotations/height-reference.jpg differ diff --git a/docs/user-guide/img/annotations/height_switcher.mp4 b/docs/user-guide/img/annotations/height_switcher.mp4 new file mode 100644 index 00000000000..896e95c1ab1 Binary files /dev/null and b/docs/user-guide/img/annotations/height_switcher.mp4 differ diff --git a/docs/user-guide/img/annotations/icon_style_editor.mp4 b/docs/user-guide/img/annotations/icon_style_editor.mp4 new file mode 100644 index 00000000000..f5ee5fddac0 Binary files /dev/null and b/docs/user-guide/img/annotations/icon_style_editor.mp4 differ diff --git a/docs/user-guide/img/annotations/invalid_vertex.jpg b/docs/user-guide/img/annotations/invalid_vertex.jpg index 2d0c5f79324..f11eca510f9 100644 Binary files a/docs/user-guide/img/annotations/invalid_vertex.jpg and b/docs/user-guide/img/annotations/invalid_vertex.jpg differ diff --git a/docs/user-guide/img/annotations/invalid_vertex2.mp4.mp4 b/docs/user-guide/img/annotations/invalid_vertex2.mp4.mp4 new file mode 100644 index 00000000000..5db7e797175 Binary files /dev/null and b/docs/user-guide/img/annotations/invalid_vertex2.mp4.mp4 differ diff --git a/docs/user-guide/img/annotations/leader-line.jpg b/docs/user-guide/img/annotations/leader-line.jpg new file mode 100644 index 00000000000..4d03e1ed2b6 Binary files /dev/null and b/docs/user-guide/img/annotations/leader-line.jpg differ diff --git a/docs/user-guide/img/annotations/line_annotation_drawing.mp4 b/docs/user-guide/img/annotations/line_annotation_drawing.mp4 new file mode 100644 index 00000000000..1cb94efa6cc Binary files /dev/null and b/docs/user-guide/img/annotations/line_annotation_drawing.mp4 differ diff --git a/docs/user-guide/img/annotations/marker_style_editor.jpg b/docs/user-guide/img/annotations/marker_style_editor.jpg index 02da91c6fe6..7636e30c45f 100644 Binary files a/docs/user-guide/img/annotations/marker_style_editor.jpg and b/docs/user-guide/img/annotations/marker_style_editor.jpg differ diff --git a/docs/user-guide/img/annotations/marker_type_selection.jpg b/docs/user-guide/img/annotations/marker_type_selection.jpg index bae3c159f6d..8a4cda38e08 100644 Binary files a/docs/user-guide/img/annotations/marker_type_selection.jpg and b/docs/user-guide/img/annotations/marker_type_selection.jpg differ diff --git a/docs/user-guide/img/annotations/polygon-type.jpg b/docs/user-guide/img/annotations/polygon-type.jpg new file mode 100644 index 00000000000..77cc629244b Binary files /dev/null and b/docs/user-guide/img/annotations/polygon-type.jpg differ diff --git a/docs/user-guide/img/annotations/polygon_style_editor.jpg b/docs/user-guide/img/annotations/polygon_style_editor.jpg index 8ac9101a65c..b1a7298f1c8 100644 Binary files a/docs/user-guide/img/annotations/polygon_style_editor.jpg and b/docs/user-guide/img/annotations/polygon_style_editor.jpg differ diff --git a/docs/user-guide/img/annotations/polyline_style_editor.jpg b/docs/user-guide/img/annotations/polyline_style_editor.jpg index 196b1cb1774..34b96db047b 100644 Binary files a/docs/user-guide/img/annotations/polyline_style_editor.jpg and b/docs/user-guide/img/annotations/polyline_style_editor.jpg differ diff --git a/docs/user-guide/img/annotations/settings_tab.jpg b/docs/user-guide/img/annotations/settings_tab.jpg new file mode 100644 index 00000000000..caff8ba9cdc Binary files /dev/null and b/docs/user-guide/img/annotations/settings_tab.jpg differ diff --git a/docs/user-guide/img/annotations/start_point_option.mp4 b/docs/user-guide/img/annotations/start_point_option.mp4 new file mode 100644 index 00000000000..4eb36a0d44d Binary files /dev/null and b/docs/user-guide/img/annotations/start_point_option.mp4 differ diff --git a/docs/user-guide/img/annotations/text_annotation_editor.jpg b/docs/user-guide/img/annotations/text_annotation_editor.jpg index c7cbf3943ff..ea4f7ab7ef5 100644 Binary files a/docs/user-guide/img/annotations/text_annotation_editor.jpg and b/docs/user-guide/img/annotations/text_annotation_editor.jpg differ diff --git a/docs/user-guide/img/button/annotations2.jpg b/docs/user-guide/img/button/annotations2.jpg index c40376ad330..91553989430 100644 Binary files a/docs/user-guide/img/button/annotations2.jpg and b/docs/user-guide/img/button/annotations2.jpg differ diff --git a/docs/user-guide/img/button/download_annotation_button.jpg b/docs/user-guide/img/button/download_annotation_button.jpg index 59fab40f98d..05762916a70 100644 Binary files a/docs/user-guide/img/button/download_annotation_button.jpg and b/docs/user-guide/img/button/download_annotation_button.jpg differ