Digitising channel damages ========================== Channel damages are managed through the view ``tww_app.vw_tww_damage_channel``. This view calculates the damage geometry from: * the geometry of the channel referenced by the examination; * the recorded channel distance; and * the direction travelled by the examination camera. When a damage is digitised manually, the point geometry selected in QGIS is discarded when the feature is saved. The geometry is then recalculated from the examination and the recorded channel distance. Prerequisites ------------- To create a georeferenced channel damage, a corresponding examination must exist. Examinations can be created using ``tww_app.vw_tww_maintenance_event``. The examination must have: * a valid link to a channel; and * a valid link to a reach point that is either at the start or the end of that channel and is referenced by the uppermost/lowermost reach of the channel. The wastewater network geometry used to position a damage is obtained from the materialized view ``tww_app.mvw_tww_channel``. .. warning:: ``tww_app.mvw_tww_channel`` is a materialized view and may be out of date. If a channel was recently created, modified, reconnected or assigned to different reaches, refresh the materialized view before digitising damages. Otherwise, the channel may be missing or its geometry and topology may no longer correspond to the current network data. How the damage position is calculated ------------------------------------- A channel damage is stored as an attribute-based location along a channel. The point geometry shown in QGIS is generated by ``tww_app.vw_tww_damage_channel``. The view determines: * the examination associated with the damage; * the reach point from which the examination was carried out; * the wastewater structure associated with the examination; * the corresponding channel in ``tww_app.mvw_tww_channel``; * the inspection direction, based on the examination reach point; and * the relative position along the channel. The inspection direction is derived as follows: ``downstream`` The examination reach point corresponds to the ``fk_reach_point_from`` of the uppermost reach linked to the channel. ``upstream`` The examination reach point corresponds to the ``fk_reach_point_to`` of the lowermost reach linked to the channel. ``unknown`` The examination reach point matches neither of the above. The relative position is calculated by dividing ``channel_distance`` by the length of the channel geometry. Values greater than the channel length are limited to the end of the channel. For downstream inspections, the distance is measured from the beginning of the channel geometry. For upstream inspections, it is measured from the end of the channel geometry. .. note:: Only examinations with recording type ``channel_TV`` are included in ``tww_app.vw_tww_damage_channel``. The corresponding code is ``3686``. Creating a channel damage ------------------------- Select ``tww_app.vw_tww_damage_channel`` in the QGIS Layers panel and enable editing. Use the QGIS feature creation tool configured for the channel damage layer. The position clicked on the map is not the authoritative location of the damage. The final ``situation2d_geometry`` is calculated by the database from the damage attributes. Place a temporary point and enter the required attributes. After saving and refreshing the layer, the calculated position replaces the temporary point. New values are written to both: * ``tww_od.damage``; and * ``tww_od.damage_channel``. Values entered in fields that are not stored in these tables are not persisted. Such fields are calculated by the view, primarily from the examination referenced by ``fk_examination``. Selecting the examination ~~~~~~~~~~~~~~~~~~~~~~~~~ The examination assigned through ``fk_examination`` must: * represent the relevant inspected channel; * have recording type ``channel_TV`` with code ``3686``; * be connected to the correct wastewater structure; and * have a valid examination reach point. The examination reach point must correspond to either ``fk_reach_point_from`` or ``fk_reach_point_to`` of the most upstream/downstream reach of the channel. Entering the channel distance ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The value for ``channel_distance`` is usually obtained from the TV inspection recording or inspection report and must be entered manually. The value represents the distance travelled by the inspection camera in meters, starting at the examination reach point. Saving and checking the damage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Save the new feature and refresh ``tww_app.vw_tww_damage_channel``. Verify that: * the damage point lies on the expected channel; * ``direction`` is either ``upstream`` or ``downstream``; * ``ws_identifier`` identifies the inspected wastewater structure; and * the point is located at the expected distance from the inspection start. If ``direction`` is ``unknown``, correct the examination or network relationships before continuing. .. note:: The fields ``situation2d_geometry``, ``direction``, ``ws_identifier`` and ``tww_is_primary`` are calculated by the view and should not be edited manually. Adding pictures or videos ------------------------- Damage pictures and examination videos can be managed through ``tww_app.vw_file``. The channel damage view displays up to two associated pictures in: * ``picture_1``; and * ``picture_2``. It also displays the associated examination video in ``video``. Pictures are linked directly to the channel damage. Videos are linked to the examination associated with the damage. The picture and video fields are calculated from active file records. They are display fields and should not be edited directly in the channel damage view. The channel damage view ignores outdated files when displaying pictures and videos. It also ignores outdated examinations when selecting videos. .. note:: The current database query does not define an explicit ordering for the picture aggregation. If more than two pictures are attached, it is not guaranteed which files appear as ``picture_1`` and ``picture_2``. Creating a new file record ~~~~~~~~~~~~~~~~~~~~~~~~~~ Create a new record in ``tww_app.vw_file`` and set at least the following fields: ``object`` The ``obj_id`` of the object to which the file is linked. For a damage picture, this is the ``obj_id`` of the channel damage. For an examination video, this is the ``obj_id`` of the examination. ``kind`` The file kind. Damage pictures must use ``picture`` with code ``3772``. Examination videos must use one of the video kinds supported by the damage view, ``video`` with code ``3775`` or ``digital_video`` with code ``9146``. ``classname`` The class name of the object referenced by ``object``. ``_url`` The complete path to the picture or video file. Complete ``identifier``, ``dataowner``, ``provider`` and ``remark`` where required. .. important:: The file path entered in ``_url`` must start with a repository path configured in ``tww_od.data_media``. When the file record is saved, the database selects the longest matching repository path. It stores the corresponding data-media object in ``fk_data_media`` and the remaining part of the URL in ``path_relative``. If no matching repository is found, the file record is not inserted and the database raises a warning. Outdated files ~~~~~~~~~~~~~~ The file selection used by the channel damage view excludes records for which ``tww_outdated`` is ``TRUE``. However, ``tww_outdated`` is not exposed by the supplied definition of ``tww_app.vw_file``. A file therefore can only be marked as outdated through ``tww_od.file``. Refreshing the displayed media ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ After adding or modifying a picture or video: #. Save the file record. #. Refresh ``tww_app.vw_tww_damage_channel``. #. Verify that the file appears in ``picture_1``, ``picture_2`` or ``video``. #. Verify that the generated path can be opened from QGIS. If a picture does not appear, check that: * ``object`` contains the channel damage's ``obj_id``; * ``kind`` is ``picture`` with code ``3772``; * ``tww_outdated`` is not ``TRUE``; * the URL uses a path configured in ``tww_od.data_media``; and * the channel damage layer has been refreshed. If a video does not appear, check that: * ``object`` contains the examination's ``obj_id``; * the video kind has code ``3775`` or ``9146``; * neither the file nor the examination is marked as outdated; and * the examination is linked to the channel damage.