.. dea_docs documentation master file, created by sphinx-quickstart on Mon Jun 3 15:15:29 2024. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. ============================= Welcome to DEA documentation! ============================= What is DEA? ------------ DEA is a content creation platform that allows users to create interactive data stories without writing a line of code. .. image:: assets/cover.png :alt: DEA :align: center | Users can combine data from the DEA portfolio with their own assets to share engaging visualizations with the community in a simple way. With DEA, users can: * Explore and visualize datasets hosted on the platform, on global or local scale, such as time series, terrains and plots * Explore the public stories available on the service in addition to their own stories * Combine the datasets hosted on the platform with their own data, adding also text images and plots * Share their stories with the community .. image:: assets/features.png :alt: DEA Features :width: 80% :align: center | DEA Components -------------- DEA is made up of different components: * The **Story Browser** contains the list of the public and users' stories. The available stories are displayed on the globe as interactive placeholders that can be filtered by categories and other properties * The **Story Editor** allows users to explore, add and combine data on the 3D globe, both from their own storage and the one hosted on DEA. Here users can create stories enriching data with text and by grouping contents in slides * The **Story Viewer** contains the story details as an interactive slideshow with time dependent data. Here users can navigate the slides, explore their scenes by a direct interaction with the 3D map and read their content All these components are accessible through the DEA **Landing page**. .. image:: assets/components.png :alt: DEA Components :width: 80% :align: center | How to search stories ^^^^^^^^^^^^^^^^^^^^^ In the DEA **Story Browser**, the user can filter the stories by categories by selecting one or more items from the list as shown in the picture below. .. image:: assets/filter_by_cat.png :alt: Filter stories by categories :width: 80% :align: center | The user can also filter the stories by: * Title and description, by adding a text in the proper search bar * Creation date, by selecting a range date from the date picker * Ownership, by clicking on ``Public`` and/or ``Private`` buttons to display only public stories and/or user-own ones .. image:: assets/filter_by_other.png :alt: Filter stories by title, description, date, ownership :width: 80% :align: center | How to view stories ^^^^^^^^^^^^^^^^^^^ The user can access the **Story Viewer** in the following ways: * From the DEA **Landing page**, by clicking on a story from the gallery preview .. image:: assets/access_viewer_home.png :alt: Access the Story Viewer :width: 80% :align: center | * From the **Story Browser**, by clicking on the *show* icon that belongs to the story item or by clicking on the story placeholder on the map .. image:: assets/access_viewer.png :alt: Access the Story Viewer :width: 80% :align: center | Use the indications shown in the pictures below to interact with the DEA **Story Viewer**. .. image:: assets/viewer_details.png :alt: Story Viewer details :width: 80% :align: center | .. image:: assets/viewer_buttons.png :alt: Navigate the story :width: 80% :align: center | Stories sharing |new| ^^^^^^^^^^^^^^^^^^^^^ .. |new| image:: assets/new.png :height: 30px Since the DEA 1.5.0 release, all users registered to the DestinE Platform will be able to share their stories. For this reason, it is needed to accept our Terms of Service to: * Upload assets * Upload images and videos as story cover or slide background * Save stories Please click on the proper icon that belongs to the header (displayed on the **Landing page**, **Story Browser** and **Story Editor**) to visualize, read and accept our Terms of Service. An example is reported in the picture below. .. image:: assets/tos.png :alt: Show Terms of Service :width: 60% :align: center | .. image:: assets/tos_acceptance.png :alt: Accept Terms of Service :width: 85% :align: center | Please note that you must scroll the whole document before the ``Accept`` button appears to be enabled. This will allow the user to create his/her own stories with his/her assets, otherwise the following message will appear on the screen when trying to perform a temporarily disabled action. .. image:: assets/tos_toast.png :alt: Disabled action message :width: 40% :align: center | To increase the security and reliability of DEA, we use a third-party service to monitor the content provided by users. The contents subjected to this check are: * Any uploaded asset * Any added text This tool will notify the user of any content found inappropriate. In case any issue is found when uploading the content on our service, an e-mail can be sent with related info to dea-support@alia-space.com. How to create a story --------------------- The user can create stories exploring the DEA data portfolio with the DEA **Story Editor**, which includes an editing side on the left and the corresponding world map visualization in the middle of the screen. .. image:: assets/editor_new.png :alt: DEA Story Editor :width: 80% :align: center | First of all, it is possible to define: * A story title (mandatory) * A story description * A location, by clicking on the proper icon to the right of the text box and then selecting a point on the map * An author * A cover, choosing an image or a video from local computer [#f1]_, from User Assets or from an external URL [#f2]_ .. image:: assets/story_props_new.png :alt: Story properties :align: center :width: 50% | Add data from DEA portfolio ^^^^^^^^^^^^^^^^^^^^^^^^^^^ The user can start adding data to his/her story selecting them, for instance, from the DEA portfolio. The list of available data is shown by clicking on the ``Datasets`` button indicated in the picture below. .. image:: assets/add_datasets.png :alt: Add data from DEA portfolio :width: 80% :align: center | Clicking on an item, the corresponding data is applied to the map. Timeline autoplay and globe rotation |new| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Since the DEA 1.5.0 release, the user can enable the autoplay of the timeline to start the animation of the data automatically. It is also possible to set the timeline speed, depending on the time resolution of the selected data. .. image:: assets/timeline_options.png :alt: Set timeline autoplay and speed :width: 50% :align: center | To create more attractive stories, the user can enable the globe rotation from the DEA **Story Editor**, as indicated below. .. image:: assets/globe_rotation.png :alt: Enable globe rotation :width: 50% :align: center | Data comparison ^^^^^^^^^^^^^^^ To compare different data in the same view is possible by clicking on the dedicated icon, to the right of the slide title, and then moving the split line that appears on the screen. .. image:: assets/compare_new.png :alt: Compare data :width: 50% :align: center | Center the map according to the user's needs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The user can capture the slide view by clicking on the proper icon, to the right of the slide title, as shown in the picture below. .. image:: assets/capture_new.png :alt: Capture view :width: 50% :align: center | Set the slide layout |new| ^^^^^^^^^^^^^^^^^^^^^^^^^^ This new feature allows to change the text position in a slide by clicking on the proper icon, to the right of the slide title. It is also possible to set the text of the slide as: * Resizable * Transparent In case of transparent background, the text of the slide will not be resizable and the title of the slide will not be visible. .. image:: assets/layout.png :alt: Change layout :width: 50% :align: center | At this point, the story can be saved by clicking on the ``Save Story`` button at the bottom of the editing section. .. image:: assets/save_story.png :alt: Save the story :width: 35% :align: center | Once the story is saved, a resizable slide preview can be displayed directly in the DEA **Story Editor** to check if it looks as expected. .. image:: assets/slide_preview.png :alt: Slide Preview :width: 80% :align: center | Set images or videos as slide background |new| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This new feature allows to add an image or a video as slide background replacing the globe. The user can upload an image or a video from local computer [#f1]_, select an image or a video from User Assets or add an external URL [#f2]_. .. image:: assets/img_video_bg.png :alt: Image or Video as slide background :width: 50% :align: center | Story autoplay and loop |new| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In case of need to show the story as a video without loosing the interactive features of the DEA **Story Viewer**, it is possible to enable the story autoplay and the story loop from the DEA **Story Editor**. .. image:: assets/autoplay_loop.png :alt: Story Autoplay and Loop :width: 45% :align: center | The autoplay allows the automatic loading of the slides of a story, without the need to interact with the menu buttons. It is always possible to interrupt the autoplay by clicking on the *pause* icon of the viewer. .. image:: assets/stop_autoplay.png :alt: Stop Autoplay :width: 80% :align: center | The loop option allows to restart the story from the beginning when the last slide's time expires. Add new slides to the story ^^^^^^^^^^^^^^^^^^^^^^^^^^^ To add more slides to the story, it is needed to click on the ``+`` button, below the last slide preview of the story. .. image:: assets/add_slide.png :alt: Add new slide :width: 10% :align: center | To sort the slides in a different way the user can simply drag and drop them to the desired position. Add user-own assets ^^^^^^^^^^^^^^^^^^^ A user registered on the DestinE Platform is allowed to integrate the DEA data portfolio with his/her previously stored assets on the private 10GB workspace. Clicking on the ``User Assets`` button available in the DEA **Story Editor**, the list of uploaded files is shown. .. image:: assets/user_assets_new.png :alt: User Assets :width: 50% :align: center | The user can upload his/her assets by clicking on the ``+`` button of the *User Assets* panel and by following the instructions on screen. .. image:: assets/upload_assets.png :alt: Upload an asset :width: 35% :align: center | .. |info| image:: assets/info.png :height: 20px By clicking on the info icon |info| of the *User Assets* panel, the user can access the details and a preview of an already uploaded asset. .. image:: assets/assets_details.png :alt: Asset details :width: 80% :align: center | The types of supported assets, as shown in the filter section of the *User Assets* panel, are: * 3D models in |GLB| (Graphics Library Transmission Format Binary) format * Vector formats such as |GeoJSON|, |TopoJSON|, |KML| (Keyhole Markup Language) and |CZML| (Cesium Language) * Videos [#f3]_ in |MP4|, |QuickTime File Format| or |WebM| formats (please note that the videos will be uploaded on the 2D/3D map) * Cloud Optimized GeoTIFF (|COG|), with the compressions listed below [#f4]_ .. image:: assets/cog_supported_formats.png :alt: COG supported compression formats :width: 75% :align: center | Generate plots ^^^^^^^^^^^^^^ Measures evolve over time! Through DEA, the user can enable the plot feature by selecting the proper icon placed in the header of the **Story Editor**. Please note that it is needed to add on the map a measure of interest from the *Datasets* panel before asking for the corresponding plot generation. .. image:: assets/enable_plot.png :alt: Enable plots :align: center | Once the plot feature is enabled, the user can click on a location on the map to trigger the generation of the plot. .. image:: assets/enable_plot_feature.png :alt: Click on the map to show the plot :width: 40% :align: center | .. image:: assets/plots.png :alt: Generate plots :width: 80% :align: center | Please note that the time window available to achieve this is limited. If the time window expires, please click again on the plot icon to re-enable the feature. .. image:: assets/plot_expired.png :alt: Time window for plots expired :width: 40% :align: center | The plots can be added in the rich text editor to be displayed in the textual section of the story or, in case the user knows how to deal with KML, he/she can add them as markups on the map (click |here| to get an example of KML editor online). Get Climate Trends |new| ^^^^^^^^^^^^^^^^^^^^^^^^ With the new release 1.5.0 of DEA, we provided a fancy tool to support climate change stories with qualitative plots. By clicking on the ``Climate Trends`` button of the DEA **Story Editor**, the list of places for which this feature is available will appear. .. image:: assets/trends_places.png :alt: Show Trends places :width: 80% :align: center | For instance, by clicking on the ``Climate Trends > Countries`` button, the countries for which the climate trends are available are highlighted on the map. Then, a menu with the type of anomaly plots is shown by clicking on one of these countries. .. image:: assets/trends_types.png :alt: Types of Climate Trends :width: 80% :align: center | This feature allows to select select: * Spiral plots * Stripes plots * Bar plots For instance, by selecting the ``Spiral`` button, the Climate Spiral of the selected country is shown. Please note that the video option is available only for Climate Spiral plots. .. image:: assets/climate_spiral.png :alt: Climate Spiral :width: 80% :align: center | The parameters of the *Climate Trends* panel can be modified depending on the user's needs: * The "Variable", which can be *2 metre temperature* or *sea surface temperature* (the latter only for climate trends on global scale) * The "Reference", which can be *pre-industrial reference period (1850-1900)* or *near-past reference period (1991-2020)* * The "Data Origin", which can be *ERA5*, *DestinE* or a combination of them * The "Temporal Resolution", which can be *yearly* or *monthly* (the latter only for spiral plots) * The "Plot Type", which can be *Spiral*, *Stripe* or *Bar* .. image:: assets/bar.png :alt: Bar plot :width: 80% :align: center | .. |photo| image:: assets/photo.png :height: 20px The user can save the trends by clicking on this |photo| icon and use the image or video in his/her stories. By clicking outside the globe, the current selection of the places is reset. Share the story |new| --------------------- Since the DEA 1.5.0 release, any user can share the created story with the community by enabling the ``Share`` button in the DEA **Story Editor**. .. image:: assets/share_story.png :alt: Share the story :width: 50% :align: center | After the story saving, the user can click on the *share* icon to generate the QR code or to copy the link that can be shared on social media and used to access the current story in the **Story Viewer**. .. image:: assets/share.png :alt: Share with community :width: 50% :align: center | Users can reach a shared story upon authentication on the DestinE Platform. The links to share a story on the most popular social media are reported after the last slide of the **Story Viewer** for both shared and public stories. Here users can also find the possibility to rate the story. .. image:: assets/share_and_rate.png :alt: Share and rate a story :width: 50% :align: center | Edit existing stories --------------------- In case the user needs to edit his/her stories, it will be sufficient to click the *edit* icon displayed on the story item preview of the **Story Browser**. .. image:: assets/edit.png :alt: Edit existing story :width: 40% :align: center | .. image:: assets/feedback.png :alt: Questions or Feedback :align: center | .. rubric:: Footnotes .. [#f1] Local video duration must not exceed 60 seconds. .. [#f2] Please note that only YouTube video URLs are supported. URLs from other platforms are not allowed. .. [#f3] Please note there is a known issue related to the videos visualization on the Firefox Browser version 131.0 Windows 64 bit. .. [#f4] An example of how to generate a COG file suitable for DEA is available on |INSULA|. .. |INSULA| raw:: html INSULA .. |GLB| raw:: html GLB .. |GeoJSON| raw:: html GeoJSON .. |TopoJSON| raw:: html TopoJSON .. |KML| raw:: html KML .. |CZML| raw:: html CZML .. |COG| raw:: html COG .. |MP4| raw:: html MP4 .. |QuickTime File Format| raw:: html QuickTime File Format .. |WebM| raw:: html WebM .. |here| raw:: html here