Stories
########

Until now, we have considered the application as a tool to view layers in a scene. These scenes can be populated with
content such as text, images and videos, resulting in **"slides"**. Multiplle Slides together make up what is called a **“story”**.

Story settings
==============

This sidebar provides several story related options :
   •	**New Story** - Creates a new empty story with the blank default slide
   •	**Stories** - Shows the panel dedicated to the story exploration, also appearing on Vizlab startup 
   •	**Save Story** - A saved story is stored in the user account
   •	**Save a Copy** - Useful to create a copy of the story with a different name
   •	**Reset Story** - Clears all the unsaved progress done on a story, restoring the last saving
   •	**Publish/Unpublish Story** - A published story is visible and available to other users but only the owner of a story can publish or unpublish it.

.. figure:: ../images/3-1.png
   :width: 40%
   :align: center

   Story settings sidebar

Any user can browse public stories from the dedicated panel, while the other features require registration. Selecting a story opens it in the home page, to view or modify its content.

Leaving or reloading the page causes the loss of unsaved progress of the currently open story.
To avoid accidental loss, each option doesn't take effect immediately, instead, it's asked through a panel to confirm or cancel the operation.
Confirmation panels usually shows up for most of the core operations.

   .. figure:: ../images/3-2.png
      :width: 30%
      :align: center

      Reset story confirm panel

Stories rely their mechanism on **slides**. To better understand how stories work it can be helpful to know the feature and purposes of slides.

Slides
======

| Slides feature multimedial content, similarly to presentation-type documents, to complement layers and enrich the story.
| They can be populated with textual and visual information, with various types of items :
|   - **Title**
|   - **Paragraph**    
|   - **Image (Asset)**         | Uploaded from local device or personal Assets
|   - **Image (Url)**           | Embedded through a link to the image source
|   - **Image Overlay (Asset)** | Like asset image but placed directly on the globe
|   - **Image Overlay (Url)**   | Like url image but placed directly on the globe
|   - **Video**                 | Embedded through a link to the video source (at the moment only YouTube is supported)
|   - **Color table**           | Added from the application, must be related to a layer
|   - **Landmark**              | A labelled pinpoint placed on the globe, marking a location. Added by picking a point on the globe.

Slides content is visible and editable on the dedicated panel on the left of the viewer.
**Add Elements +** shows the item types that can be added. Slides can be **duplicated** with the "+" inside a double circle.
An item can be deleted by clicking its **trash bin** icon. 

.. figure:: ../images/3-3.jpg
   :width: 50%
   :align: center
      
   An example of slide with content

Landmarks and overlay images placed on the globe appear in their lists, visible in the slide content. They carry their own properties which can be set with the **pencil-shaped icon**.

For landmarks : 
   - **Title**
   - **Longitude and Latitude**
   - **Elevation**
   - **Camera distance**
   - **Marker icon**
   - **Marker color**

For overlay images :
   - **Longitude**
   - **Latitude**
   - **Size**
   - **Aspect**
   - **Rotation**


 .. figure:: ../images/3-4.png
   :width: 60%
   :align: center
   
   Landmark properties

You can move overlay images by holding alt while dragging with the center handle, change size and ratio with the corner handles, or rotate them with the curved arrows. The full list of commands :

   - **Left Alt + left click on handles --> move/resize/rotate**
   - **Left Alt + mouse wheel --> coarse uniform resize**
   - **Left Alt + right click + drag vertically --> fine uniform resize**
   - **Left Alt + middle click + drag vertically --> rotate**

Alternatively you can set the properties in the box for more precise values. The arrows in the images list allow to swap them and change their order.

- .. figure:: ../images/3-5.jpg
   :width: 60%
   :align: center
   
   Overlay image properties

Currently there is a limit of one of each item type per slide, except for 3D elements (landmarks and overlay images). There can be only one between Asset Image and Url Image.

Managing slides
---------------

Slides can be organized in their list on the left side. The buttons to **add** and **remove** them are on top of the list, and they can be reordered through drag and drop clicking on the grid icon.
The list is found in the Slides/Layers panel, split into two columns, the left one for slides, the right one to manage layers contained in a single slide.

.. figure:: ../images/3-6.png
   :width: 60%
   :align: center

   Slides List

For the purpose of stories, slides have some settable properties available in the settings panel (they are detailed in the next paragraph) :
   - **Base map**
   - **Overlay boundaries**
   - **Start Date and End Date**
   - **Start Position**
   - **Camera Transition**
   - **Navigation type**
   - **Samples per Second**
   - **Time step**

.. figure:: ../images/3-7.png
   :width: 18%
   :align: center
      
   Slide settings


| Until now we covered the topics of data exploration and visualization, which can be experienced through individual slides, regardless their number in a story.
| It's when considering stories as a sequence of multiple slides, that the insights of Vizlab features take a step further. Slides are not just a way to enrich content of the view, but they are meant to automate the visualization of their content. This automatization system it's the core feature of Stories and takes the name of **Present Mode**.

Present Mode
============

**Present Mode** is a playback function to reproduce stories, integrated in the 3D viewer.
Its power lies in its capability to show content over time while preserving the navigation around the 3D globe,
allowing for a look at the geospatial phenomena from different perspectives while seeing their evolution over time.

Navigation on a slide depends on its **Navigation type** property :
   - **Free** allows free movement with no constraints
   - **Orbit target** sets the camera orbit with the specified object as center of rotation  
   - **Blocked** is the static view with no camera movement

.. figure:: ../images/3-8.jpg
   :width: 70%
   :align: center

   Present Mode

| While in present mode, most of the interface is hidden to make room for the 3D viewer and empower the experience.
| Similarly to videos, stories can be played or stopped at any time. During play, slides are sequentally reproduced following their order and according the slide settings.

| Each slide is played along its timeline from the set **Start Date** to the **End Date**, advancing by a time interval equal to **Time step**. Playback smoothness is determined by **Samples per Second**.

Time step can be :
      - Hourly
      - Daily
      - Weekly
      - Monthly
      - Yearly 

| When moving from a slide to the next one, the camera makes a transition to the **Start position** (Longitude, Latitude, Elevation) of the next slide.
| Additionally, slides can be jumped to back and forth with the arrows. Jumping to another slide automatically stops the playback.

There are two types of **Camera Transition** in the current version :
   - **None** with an instant change of position
   - **Fly to** where the camera gradually moves from the previous to the next position.

For each slide, Earth appearance can be changed by selecting the **Base map**, which is the image of the Earth wrapped around the 3D model.
Typically a base map is a view of the Earth taken from a satellite, or a geopolitical representation of territories. There are many base maps available from different sources.

.. figure:: ../images/3-9.png
   :width: 50%
   :align: center

   Base Map set to **Black Marble**, a nightime satellite view

**Overlay boundaries** determines which boundary lines are displayed, whether it's **Coastlines**, **Countries**, **None** or **Both** of them.

To distinguish from the "present mode", we can refer to the edit view as "edit mode". Camera transition works also when changing slide edit mode.
Base maps and overlay boundaries are visible either in edit or presentation mode.

To reduce performance overload, before entering the present mode the application warns about any unoptimized layers for playback (see ch. Home Page, p. Timeline). It's possible to hide them to improve performances.

.. figure:: ../images/3-10.png
   :width: 40%
   :align: center
   
   Performance warning

The X button on the top right corner closes the present mode, returning to the edit mode.
When publishing a story it's asked to choose the default display mode, and in case of presentation, whether enabling the autoplay.
Stories opened by their author are displayed by default in edit mode, even if published in Present mode.
Public stories in Present mode cannot be modified by users outside the creator, as they can only view what allowed by the author.

.. figure:: ../images/3-11.png
   :width: 30%
   :align: center
   
   Publish story confirm panel