Update documentation

ESDLMapEditorESSIM · Apr 14, 2022 · c8fbeb4 · c8fbeb4
1 parent aefd8d5
commit c8fbeb4
Show file tree

Hide file tree

Showing 40 changed files with 299 additions and 28 deletions.
diff --git a/docs/source/basic_tasks/adding_assets.rst b/docs/source/basic_tasks/adding_assets.rst
@@ -1,2 +1,143 @@
-Adding assets
-=============
+Adding assets, areas and potentials
+===================================
+
+Energy assets are the core components of an ESDL energy system description. Energy assets can be subdivided into 5 different
+types, the so called ESDL capabilities.
+
+.. image:: images/ESDL_capabilities.png
+   :width: 200
+   :alt: ESDL capabilities
+
+The following table shows some examples of each capability with its MapEditor icon:
+
++------------------+----------------------------------------------+------------------------------------------+
++ ESDL asset types + Example icons                                + ESDL asset examples                      +
++------------------+----------------------------------------------+------------------------------------------+
+| Producer         | |WindTurbine| |GeothermalSource| |Import|    | WindTurbine, GeothermalSource, Import    |
++------------------+----------------------------------------------+------------------------------------------+
+| Consumer         | |HeatingDemand| |Export| |ElectricityDemand| | HeatingDemand, Export, ElectricityDemand |
++------------------+----------------------------------------------+------------------------------------------+
+| Conversion       | |PowerPlant| |HeatPump| |GasHeater|          | PowerPlant, HeatPump, GasHeater          |
++------------------+----------------------------------------------+------------------------------------------+
+| Storage          | |Battery| |ATES| |WaterBuffer|               | Battery, ATES, WaterBuffer               |
++------------------+----------------------------------------------+------------------------------------------+
+| Transport        | |ElectricityCable| |Transformer| |Pipe|      | ElectricityCable, Transformer, Pipe      |
++------------------+----------------------------------------------+------------------------------------------+
+
+Areas and potentials can only be added using the asset draw select tool, but there are multiple ways to add assets to
+the map:
+
+* Via the asset draw select tool (nr 3. in :ref:`this picture<The ESDL MapEditor user interface>`)
+* Via the asset draw toolbar (nr. 15 in :ref:`this picture<The ESDL MapEditor user interface>`)
+* Using templated assets from the Energy Data Repository
+
+Adding assets, areas or potentials via the asset draw select tool
+-----------------------------------------------------------------
+Adding assets, areas or potentials is done via the asset draw select tool located in the middle of the top menu bar.
+Actually it is split into two separate select tools to speed up drawing pipes and cables.
+
+.. image:: images/adding_assets.png
+   :width: 400
+   :alt: Adding assets
+
+The left select tool (nr. 3 in :ref:`this picture<The ESDL MapEditor user interface>`) contains 7 groups:
+
+* a group for 'Non EnergyAssets', with Area, Building and AggregatedBuilding
+* 5 groups for Producer, Consumer, Storage, Transport and Conversion assets
+* a group with all 'Potentials'
+
+By selecting one of the options out of this list, the user starts drawing this on the map immediately.
+
+Another relevant UI part are the draw controls (nr. 12 in :ref:`this picture<The ESDL MapEditor user interface>`):
+
+.. image:: images/draw_controls.png
+   :width: 60
+   :alt: Draw controls
+
+From top to bottom they represent drawing a line, drawing a polygon, drawing a square and drawing a point (or marker).
+
+Each asset (and area and potentials too) has a default 'shape' on the map. At the moment these defaults are:
+
+* Polygon: Area, PVPark, WindPark
+* Line: Pipe, ElectricityCable
+* Point: everything else
+
+You can switch the shape using the draw controls on the left, before clicking on the map. So for example, if you select
+a Transformer asset from the list, by default the 'marker draw tool' is selected. If you first click on the 'polygon
+draw tool' and then start drawing on the map, a Transformer asset can get a polygon geometry where the space taken on
+the map by this transformer is represented in the ESDL data.
+
+.. image:: images/transformer_as_polygon.png
+   :width: 300
+   :alt: Transformer asset with a polygon geometry
+
+Drawing pipes and cables
+------------------------
+Pipes and cables can be drawn using the method above (by selecting Pipe of ElectricityCable in the long list of the
+left select tool). To speed up drawing pipes and cables, we've added a second select tool specifically for pipes and
+cables. If the user selects the 'line draw tool' from the draw controls on the left, the right part of the select tool
+(nr. 4 in :ref:`this picture<The ESDL MapEditor user interface>`) determines if a pipe or a cable is drawn.
+
+.. note::
+    ElectricityCables and Pipes can also be added as icons (with a point location) instead of lines. This can be useful
+    if your model requires to add properties of a cable or pipe (like capacity or diameter), but you don't know the
+    exact trajectory of the cable or pipe.
+
+Adding assets via the asset draw toolbar
+----------------------------------------
+Adding assets using the Asset draw toolbar is the most convenient way of doing this. It is fully user configurable and
+adding assets is just a matter of clicking once on the icon of the asset on the toolbar and then clicking on the map
+(once or as many times as you like). The default shape can again be changed before the actual drawing is started.
+
+In :ref:`this section<Asset Draw Toolbar>` the configuration options of the asset draw toolbar are described in more detail.
+
+Adding assets using the Energy Data Repository
+----------------------------------------------
+Adding templated assets from the Energy Data Repository (EDR), can be done by clicking on the 'EDR assets' button at
+the top (nr. 2 in :ref:`this picture<The ESDL MapEditor user interface>`). It's described in more detail
+:ref:`here<Adding assets from the Energy Data Repository>`
+
+.. |ATES| image:: images/ATES.png
+   :width: 30pt
+
+.. |Battery| image:: images/Battery.png
+   :width: 30pt
+
+.. |ElectricityCable| image:: images/ElectricityCable.png
+   :width: 30pt
+
+.. |ElectricityDemand| image:: images/ElectricityDemand.png
+   :width: 30pt
+
+.. |Export| image:: images/Export.png
+   :width: 30pt
+
+.. |GasHeater| image:: images/GasHeater.png
+   :width: 30pt
+
+.. |GeothermalSource| image:: images/GeothermalSource.png
+   :width: 30pt
+
+.. |HeatPump| image:: images/HeatPump.png
+   :width: 30pt
+
+.. |HeatingDemand| image:: images/HeatingDemand.png
+   :width: 30pt
+
+.. |Import| image:: images/Import.png
+   :width: 30pt
+
+.. |Pipe| image:: images/Pipe.png
+   :width: 30pt
+
+.. |PowerPlant| image:: images/PowerPlant.png
+   :width: 30pt
+
+.. |Transformer| image:: images/Transformer.png
+   :width: 30pt
+
+.. |WaterBuffer| image:: images/WaterBuffer.png
+   :width: 30pt
+
+.. |WindTurbine| image:: images/WindTurbine.png
+   :width: 30pt
diff --git a/docs/source/basic_tasks/adding_assets_from_the_edr.rst b/docs/source/basic_tasks/adding_assets_from_the_edr.rst
@@ -22,7 +22,8 @@ The following dialog appears:
 
 The dialog contains two drop down lists. The first one can be used to filter on a specific type of asset. The second
 drop down list actually determines which asset information is loaded from the EDR. Press the 'Select' button to start
-with the process of adding the asset to a specific location. See the :ref:`Adding assets<Adding assets>` section for more information.
+with the process of adding the asset to a specific location. See the
+:ref:`Adding assets, areas and potentials<Adding assets, areas and potentials>` section for more information.
 
   .. image:: images/edr_assets_select_asset.png
     :alt: EDR assets select asset

diff --git a/docs/source/basic_tasks/connecting_assets.rst b/docs/source/basic_tasks/connecting_assets.rst
@@ -1,13 +1,14 @@
 Connecting assets
 =================
 
-ESDL knows the concept of ports and connections to connect assets. Ports exist in two types (by design, see LINK for
-more detailed information):
+ESDL knows the concept of ports and connections to connect assets. Ports exist in two types (by design, see
+`this article <https://energytransition.gitbook.io/esdl/esdl-concepts/energy-system-structure>`_ for more detailed
+information):
 
 * InPort: port that is mainly used for incoming flow, current or energy
 * OutPort: port that is mainly used for outgoing flow, current or energy
 
-An InPort is visualized as a blue square to the left on an asset, an OutPort is visualized as a red square to the
+An InPort is visualized as a gray square to the left on an asset, an OutPort is visualized as a black square to the
 right of an assets. InPorts can only be connected to OutPorts and the other way around.
 
 The amount and type of ports the MapEditor attaches to an asset when the user adds an asset to the map, depends on the
@@ -83,15 +84,14 @@ There are two ways to connect assets:
 
 Keyboard shortcuts
 ------------------
+There are a few keyboard shortcuts to speed up drawing cables and pipes:
 
-   * There are a few keyboard shortcuts to speed up drawing cables and pipes:
+* Press the Ctrl-key before clicking a port (Ctrl + click), will directly turn on pipe/cable drawing.
+* Press 'c' to draw a cable,
+* Press 'p' to draw a pipe,
+* Press 'a' to draw the last selected asset in the menu bar directly.
 
-     * Press the Ctrl-key before clicking a port (Ctrl + click), will directly turn on pipe/cable drawing.
-     * Press 'c' to draw a cable,
-     * Press 'p' to draw a pipe,
-     * Press 'a' to draw the last selected asset in the menu bar directly.
-
-     Make sure the map has focus to capture these shortcut keys, e.g. by clicking on the map itself first if that is not the case.
+Make sure the map has focus to capture these shortcut keys, e.g. by clicking on the map itself first if that is not the case.
 
 
 
diff --git a/docs/source/basic_tasks/creating_an_energy_system_description.rst b/docs/source/basic_tasks/creating_an_energy_system_description.rst
@@ -1,2 +1,24 @@
 Creating an energy system description
-=====================================
+=====================================
+
+When you log into the ESDL MapEditor for the first time, you start with an empty energy system description. You can
+then start drawing your energy system. At any moment in time you can choose 'New ESDL' from the 'File' menu to start
+with an empty energy system again.
+
+.. image:: images/new_energy_system.png
+   :width: 400
+   :alt: File --> New ESDL
+
+You are asked to fill in the following information:
+
+* Energy system name
+* Energy system description
+* Energy system instance name
+* Top-level area name
+
+After filling in those fields, an example structure like shown below will be created in memory. ESDL energy assets
+(or other sub areas) can then be added to the top-level area to model a certain use case.
+
+.. image:: images/energy_system_structure.png
+   :width: 250
+   :alt: Energy system structure
diff --git a/docs/source/basic_tasks/editing_asset_properties.rst b/docs/source/basic_tasks/editing_asset_properties.rst
@@ -0,0 +1,3 @@
+Editing asset properties
+========================
+
diff --git a/docs/source/basic_tasks/images/ATES.png b/docs/source/basic_tasks/images/ATES.png
diff --git a/docs/source/basic_tasks/images/Battery.png b/docs/source/basic_tasks/images/Battery.png
diff --git a/docs/source/basic_tasks/images/ESDL_capabilities.png b/docs/source/basic_tasks/images/ESDL_capabilities.png
diff --git a/docs/source/basic_tasks/images/ElectricityCable.png b/docs/source/basic_tasks/images/ElectricityCable.png
diff --git a/docs/source/basic_tasks/images/ElectricityDemand.png b/docs/source/basic_tasks/images/ElectricityDemand.png
diff --git a/docs/source/basic_tasks/images/Export.png b/docs/source/basic_tasks/images/Export.png
diff --git a/docs/source/basic_tasks/images/GasHeater.png b/docs/source/basic_tasks/images/GasHeater.png
diff --git a/docs/source/basic_tasks/images/GeothermalSource.png b/docs/source/basic_tasks/images/GeothermalSource.png
diff --git a/docs/source/basic_tasks/images/HeatPump.png b/docs/source/basic_tasks/images/HeatPump.png
diff --git a/docs/source/basic_tasks/images/HeatingDemand.png b/docs/source/basic_tasks/images/HeatingDemand.png
diff --git a/docs/source/basic_tasks/images/Import.png b/docs/source/basic_tasks/images/Import.png
diff --git a/docs/source/basic_tasks/images/Pipe.png b/docs/source/basic_tasks/images/Pipe.png
diff --git a/docs/source/basic_tasks/images/PowerPlant.png b/docs/source/basic_tasks/images/PowerPlant.png
diff --git a/docs/source/basic_tasks/images/Transformer.png b/docs/source/basic_tasks/images/Transformer.png
diff --git a/docs/source/basic_tasks/images/WaterBuffer.png b/docs/source/basic_tasks/images/WaterBuffer.png
diff --git a/docs/source/basic_tasks/images/WindTurbine.png b/docs/source/basic_tasks/images/WindTurbine.png
diff --git a/docs/source/basic_tasks/images/adding_assets.png b/docs/source/basic_tasks/images/adding_assets.png
diff --git a/docs/source/basic_tasks/images/changing_a_line.png b/docs/source/basic_tasks/images/changing_a_line.png
diff --git a/docs/source/basic_tasks/images/changing_a_polygon.png b/docs/source/basic_tasks/images/changing_a_polygon.png
diff --git a/docs/source/basic_tasks/images/delete_asset_context_menu.png b/docs/source/basic_tasks/images/delete_asset_context_menu.png
diff --git a/docs/source/basic_tasks/images/draw_controls.png b/docs/source/basic_tasks/images/draw_controls.png
diff --git a/docs/source/basic_tasks/images/edit_remove_controls.png b/docs/source/basic_tasks/images/edit_remove_controls.png
diff --git a/docs/source/basic_tasks/images/energy_system_structure.png b/docs/source/basic_tasks/images/energy_system_structure.png
diff --git a/docs/source/basic_tasks/images/new_energy_system.png b/docs/source/basic_tasks/images/new_energy_system.png
diff --git a/docs/source/basic_tasks/images/remove_connection_asset_properties_dialog.png b/docs/source/basic_tasks/images/remove_connection_asset_properties_dialog.png
diff --git a/docs/source/basic_tasks/images/remove_connection_context_menu.png b/docs/source/basic_tasks/images/remove_connection_context_menu.png
diff --git a/docs/source/basic_tasks/images/transformer_as_polygon.png b/docs/source/basic_tasks/images/transformer_as_polygon.png
diff --git a/docs/source/basic_tasks/index.rst b/docs/source/basic_tasks/index.rst
@@ -8,7 +8,8 @@ Basic tasks in the ESDL MapEditor
    creating_an_energy_system_description
    adding_assets
    adding_assets_from_the_edr
-   moving_assets
+   editing_asset_properties
+   moving_assets_and_changing_asset_shapes
    removing_assets
    connecting_assets
    removing_a_connection

diff --git a/docs/source/basic_tasks/moving_assets.rst b/docs/source/basic_tasks/moving_assets.rst
diff --git a/docs/source/basic_tasks/moving_assets_and_changing_asset_shapes.rst b/docs/source/basic_tasks/moving_assets_and_changing_asset_shapes.rst
@@ -0,0 +1,43 @@
+Moving assets and changing asset shapes
+=======================================
+Handling assets depends on its shape on the map. Assets represented as a marker, line or polygon
+can be moved or changed shape using the edit and remove controls at the left side of the map
+(nr. 13 in :ref:`this picture<The ESDL MapEditor user interface>`):
+
+.. image:: images/edit_remove_controls.png
+   :width: 60
+   :alt: Draw controls
+
+By clicking on the upper icon, you start the edit mode. All assets can then be moved. The edit mode must be
+confirmed by pressing the 'save' button.
+
+.. note::
+   Assets represented as a marker, with a point location can be moved by just dragging the icon to another location.
+
+Moving or changing a line
+-------------------------
+A line in edit mode, looks like this:
+
+.. image:: images/changing_a_line.png
+   :width: 200
+   :alt: Changing a line
+
+You know have three options:
+
+* By dragging the single gray handle, the line can be moved as a whole
+* By dragging the vertex handles, the line vertex can be moved
+* By dragging the handle in the middle of an edge, an extra vertex will be created
+
+Moving or changing a polygon
+----------------------------
+A polygon in edit mode, looks like this:
+
+.. image:: images/changing_a_polygon.png
+   :width: 350
+   :alt: Changing a polygon
+
+You know have three options:
+
+* By dragging the single gray handle, the polygon can be moved as a whole
+* By dragging the vertex handles, the polygon vertex can be moved
+* By dragging the handle in the middle of an edge, an extra vertex will be created
diff --git a/docs/source/basic_tasks/removing_a_connection.rst b/docs/source/basic_tasks/removing_a_connection.rst
@@ -1,3 +1,24 @@
 Removing a connection
 =====================
 
+A connection can be removed in two ways:
+
+* By hovering with your mouse over a connection (the connection is then changing from a dotted to a straight line),
+  then right clicking on this connection and then selecting 'Delete connection' from the context menu
+
+  .. image:: images/remove_connection_context_menu.png
+     :width: 600
+     :alt: Remove a connection via the context menu
+
+* By using the asset properties dialog
+
+  .. image:: images/remove_connection_asset_properties_dialog.png
+     :width: 400
+     :alt: Remove a connection via the asset properties dialog
+
+  The following steps must be taken:
+
+  * Click on an asset to open the asset properties dialog
+  * Open de Ports sections (1)
+  * Find the port and expand the conncetions list (3) by clicking on the plus sign (2)
+  * Remove the connection by clicking on the bin icon (4) behind the connection
diff --git a/docs/source/basic_tasks/removing_assets.rst b/docs/source/basic_tasks/removing_assets.rst
@@ -1,2 +1,19 @@
 Removing assets
 ===============
+
+Assets can be removed in multiple ways:
+
+* Using the edit and remove controls (nr. 13 in :ref:`this picture<The ESDL MapEditor user interface>`):
+
+  .. image:: images/edit_remove_controls.png
+     :width: 60
+     :alt: Draw controls
+
+  By clicking on the lower icon, you start the remove mode. All assets can then be removed by clicking them. The remove
+  mode must be confirmed by pressing the 'save' button.
+
+* By right clicking on an asset icon (or on the line) and selecting 'Delete' from the context menu
+
+  .. image:: images/delete_asset_context_menu.png
+     :width: 300
+     :alt: Delete assets via the context menu
diff --git a/docs/source/user_interface/menus.rst b/docs/source/user_interface/menus.rst
@@ -14,14 +14,6 @@ File menu
     "Load from ESDL drive", "Load or import an ESDL file from the ESDL drive (ESDL cloud storage)."
     "Save to ESDL drive", "Save an ESDL to the ESDL drive."
 
-Only for Mondaine project partners (the Mondaine Hub was the predecessor of the ESDL drive):
-
-.. csv-table::
-    :header: "Menu item", "Description"
-
-    "Load ESDL from Mondaine Hub", "Load or import an ESDL file from the Mondaine Hub"
-    "Save ESDL to Mondaine Hub", "Save an ESDL file to the Mondaine Hub"
-
 .. note::
     When you press 'Save ESDL' in the ESDL MapEditor, the behaviour is determined by your local browser settings. Most
     browsers by default save files in the Downloads folder (on Windows at least). In your browser settings you can
@@ -33,10 +25,13 @@ Edit menu
 .. csv-table::
     :header: "Menu item", "Description"
 
-    "ESDL browser", ""
-    "Energy carriers", ""
-    "Sectors", ""
+    "ESDL table editor", "Opens the ESDL table editor, allows to edit attributes of multiple assets of same type"
+    "ESDL browser", "Opens the ESDL browser, a low level ESDL editor (advised for advanced users only)"
+    "Energy carriers", "Allows to add, edit, remove carrier information"
+    "Sectors", "Allows to add sectors"
+    "Environmental profiles", "Allows to add all kind of environmental profiles (outside temperature, pressure, soil temperature, ...)"
     "Shapefile converter", ""
+    "Search assets", "Allows to search for assets based on ID, name and let map zoom into this assets"
 
 Services menu
 *************
@@ -58,8 +53,20 @@ View menu
 .. csv-table::
     :header: "Menu item", "Description"
 
+    "Refresh view", "Force the MapEditor UI to refresh"
     "WMS layers", "Allows to visualize WMS layers in the MapEditor"
     "Show/hide animation toolbar", "Show or hide the animation toolbar - for controlling the load animation"
     "Show/hide asset draw toolbar", "Show or hide the asset draw toolbar - for quickly adding certain assets"
+    "Show/hide services toolbar", "Show or hide the services toolbar - for quickly calling certain services"
     "Show/hide KPIs", "Show or hide KPI window"
+    "Clear simulation results", "Removes all kind of results from the UI (simulation results, validator feedback"
     "Settings", "Settings for the MapEditor and its plugins"
+
+Help menu
+*********
+
+.. csv-table::
+    :header: "Menu item", "Description"
+
+    "Documentation", "Opens this documentation website"
+    "About", "Shows the version of the ESDL MapEditor and some links for installing it"
diff --git a/images/energy_system_structure.png b/images/energy_system_structure.png