.. _dpac-plenary-hdb-2023:

.. role:: grey
.. role:: red
.. role:: green
.. role:: yellow
.. role:: orange
.. role:: blue
   
Video & scripting workshop (2023)
=================================

   .. hint:: This workshop is designed to be followed with Gaia Sky 3.4.0 or 3.4.1!

This page contains the workshop on the general usage of Gaia Sky given at the DPAC consortium meeting on in Heidelberg (March 13-17, 2023). The workshop session is scheduled for March 13 at 9:00 CET.

The main aim of this workshop is to provide a general understanding of the scripting system in Gaia Sky, and to train the participants in the creation of outreach videos.

The topics covered in this tutorial are the following:

- Gaia Sky introduction:

  - Dataset manager.
  - Controls, movement, selection.
  - User interface.
  - Camera, type visibility.
  - Render modes (3D, planetarium, 360, reprojection).
  - Visual settings.
  - External datasets (loading, filters, SAMP).

- Scripting:

  - The API (basic functions, etc.).
  - Writing Python scripts for Gaia Sky.
  - Running scripts on a Gaia Sky instance.
  - Advanced topics: camera and scene runnables.

- Camera paths:

  - Recording and playback.
  - Keyframe system.
  - Still frame output system.

- Creating videos from still frames with ``ffmpeg``.

*Estimated duration:* 3 hours

Before starting...
------------------

In order to follow the course it is strongly recommended to have a local installation of Gaia Sky 3.4.x so that you can explore and try out the teachings for yourself. In order to install Gaia Sky, follow the instructions for your operating system in :ref:`the installation section <installation>` of the Gaia Sky documentation.

Introduction
------------

When your start up Gaia Sky 3.4.x, you will be greeted with this view:

.. figure:: img/dpac-2023/2023_welcome.jpg
    :alt: Gaia Sky welcome UI
    :align: center
    :target: ../_images/2023_welcome.jpg

    Gaia Sky welcome UI


From here you can access the global preferences (cog wheel to the bottom right), fire up the **dataset manager**, or start Gaia Sky.

Dataset manager
~~~~~~~~~~~~~~~

The dataset manager is used to download, update and manage datasets. It consists of two tabs:

- **Available for download** --- contains datasets that are available to be downloaded and installed.  
- **Installed** --- contains the datasets currently installed locally.

The first time your start Gaia Sky you need to download at least the **Base data pack** (key ``default-data``) to even be able to start the program. The base data pack contains essential data like most of the Solar System, the Milky Way, grids, constellations and other objects.


.. figure:: img/dpac-2023/2023_dataset-manager.jpg
    :alt: The dataset manager
    :align: center
    :target: ../_images/2023_dataset-manager.jpg

    The dataset manager

You can explore the available datasets freely.

Basic controls
~~~~~~~~~~~~~~

When Gaia Sky is ready to go, you will be presented with this screen:

.. figure:: img/dpac-2021/ui-initial.jpg
    :alt: The scene
    :align: center
    :target: ../_images/ui-initial.jpg

    Gaia Sky default scene 

In it you can see a few things already. To the bottom right the :ref:`focus panel <focus-panel>` tells you that you are in focus mode, meaning that all our movement is relative to the focus object. The default focus of Gaia Sky is the Earth. You can also see in the **quick info bar** at the top that our focus is the :green:`Earth`, and that the closest object to our location is also the :blue:`Earth`. Additionally you see that your home object is again the :orange:`Earth`. Finally the **control panel** is collapsed at the top left. If you click on it, the panel opens. We will use it later.

Movement
^^^^^^^^

But right now let's try some movement. In **focus mode** the camera will by default orbit around the focus object. **Try clicking and dragging with your left mouse button**. The camera should orbit around the Earth showing parts of the surface which were previously hidden. You will notice that the whole scene rotates. Now **try scrolling with your mouse wheel**. The camera will move either farther away from (scroll down) or closer up to (scroll up) the Earth. Now, if you **click and drag with your right mouse button**, you can offset the focus object from the center, but your movement will still be relative to it.

You can also use your keyboard arrows :guilabel:`←` :guilabel:`↑` :guilabel:`→` :guilabel:`↓` to orbit left or right around the focus object, or move closer to or away from it.

You can use :guilabel:`shift` with a **mouse drag** in order to roll the camera. 

More information on the controls is available in the :ref:`controls section <controls>` of the Gaia Sky user manual.

Selection
^^^^^^^^^

You can change the focus by simply **double clicking** on any object on the scene. You can also press :guilabel:`f` to bring up the **search** dialog where you can look up objects by name. Try it now. Press :guilabel:`f` and type in "mars", without the quotes, and hit :guilabel:`esc`. You should see that the camera now points in the direction of :red:`Mars`. To actually go to :red:`Mars` simply scroll up until you reach it, or click on the |goto| icon next to the name in the focus info panel. If you do so, Gaia Sky takes control of the camera and brings you to :red:`Mars`. 

If you want to move instantly to your current focus object, hit :guilabel:`ctrl` + :guilabel:`g`.

At any time you can use the :guilabel:`home` key in your keyboard to return back to Earth or whatever :orange:`home` object you have defined in the :ref:`configuration file <configuration-file>`.

.. |goto| image:: ../img/ui/go-to.png

The User Interface
~~~~~~~~~~~~~~~~~~

The user interface of Gaia Sky consists of basically two components: keyboard shortcuts and a graphical user interface in the form of the **control panel**.

.. figure:: img/dpac-2021/ui-all.jpg
    :alt: Gaia Sky User Unterface
    :align: center
    :target: ../_images/ui-all.jpg

    Gaia Sky user interface with the most useful functions

Control panel
^^^^^^^^^^^^^

.. hint:: The control panel is described in detail in :ref:`its own section <user-interface>` of the Gaia Sky user manual.

The control panel is made up of different panes: *Time*, *Camera*, *Type visibility*, *Visual settings*, *Datasets*, *Bookmarks* and *Music*. In this tutorial we will only explore the first six. Each pane can be **expanded** (with |caret-right|), **collapsed** (with |caret-bottom|) and **detached** (with |detach-icon|).

To the bottom of the control panel we can find a few buttons to perform special actions like:

- |minimap| Toggle the minimap
- |dsload| Load a dataset
- |prefsicon| Open the preferences window
- |logicon| Show the session log
- |helpicon| Show the help dialog
- |quiticon| Exit Gaia Sky

Quick info bar
^^^^^^^^^^^^^^

To the top of the screen you can see the **quick info bar** which provides information on the current time, the :green:`current focus` object (if any), the :blue:`current closest` object to our location and the :orange:`current home` object. The colors of these objects (:green:`green`, :blue:`blue`, :orange:`orange`) correspond to the colors of the crosshairs. The crosshairs can be enabled or disabled from the interface tab in the preferences window (use :guilabel:`p` to bring it up).

.. |minimap| image:: ../img/ui/map-icon.png
.. |dsload| image:: ../img/ui/open-icon.png
.. |prefsicon| image:: ../img/ui/prefs-icon.png
.. |logicon| image:: ../img/ui/log-icon.png
.. |helpicon| image:: ../img/ui/help-icon.png
.. |quiticon| image:: ../img/ui/quit-icon.png


.. |caret-bottom| image:: ../img/ui/iconic-caret-bottom.png
.. |caret-right| image:: ../img/ui/iconic-caret-right.png
.. |detach-icon| image:: ../img/ui/detach-icon.png


Debug panel
^^^^^^^^^^^

Gaia Sky has a built-in debug information panel that provides system information and is hidden by default. You can bring it up with :guilabel:`ctrl` + :guilabel:`d`, or by ticking the "*Show debug info*" check box in the system tab of the preferences window. By default, the debug panel is collapsed.

.. figure:: ../img/debug/debug-collapsed.jpg
    :alt: Collapsed debug panel
    :align: center
    :target: ../_images/debug-collapsed.jpg

    Collapsed debug panel

You can expand it with the ``+`` symbol to get additional information.

.. figure:: ../img/debug/debug-expanded.jpg
    :alt: Expanded debug panel
    :align: center
    :target: ../_images/debug-expanded.jpg

    Expanded debug panel

As you can see, the debug panel shows information on the current graphics device, system and graphics memory, the amount of objects loaded and on display, the octree (if a LOD dataset is in use) or the SAMP status.

Additional debug information can be obtained in the system tab of the help dialog (:guilabel:`?` or :guilabel:`h`).

Time controls
^^^^^^^^^^^^^

Gaia Sky can simulate time. Play and pause the simulation using the |play-icon|/|pause-icon| ``Play/Pause`` buttons in the time pane, or toggle using :guilabel:`Space`. You can also change the time warp, which is expressed as a scaling factor, using the provided **Warp factor** slider. Use :guilabel:`,` or |minus-icon| and :guilabel:`.` or |plus-icon| to divide by 2 and double the value of the time warp, respectively.

.. figure:: ../img/ui/warp-factor.jpg  
    :width: 45%                                  
    :align: center
    :target: ../_images/warp-factor.jpg
     
    Warp factor slider


.. |play-icon| image:: ../img/ui/play-icon.png
.. |pause-icon| image:: ../img/ui/pause-icon.png
.. |minus-icon| image:: ../img/ui/minus-icon.png
.. |plus-icon| image:: ../img/ui/plus-icon.png
.. |warp-factor| image:: ../img/ui/warp-factor.jpg


Now, go ahead and press :guilabel:`home`. This will bring us back to Earth. Now, start the time with |play-icon| or :guilabel:`space` and **drag the slider slightly to the right** to increase its speed. You will see that the Earth rotates faster and faster as you move the slider to the right. Now, **drag it to the left** until time is reversed and the Earth starts rotating in the opposite direction. Now time is going backwards!

If you set the time warp high enough you will notice that as the bodies in the Solar System start going crazy, the stars start to slightly move. That's right: Gaia Sky also simulates proper motions.

Camera modes
~~~~~~~~~~~~

We have already talked about the **focus camera mode**, but Gaia Sky provides many more :ref:`camera-modes`:

- :guilabel:`0` - **Free mode**: the camera is not locked to a focus object and can roam freely. The movement is achieved with the scroll wheel of your mouse, and the view is controlled by clicking and draggin the left and right mouse buttons
- :guilabel:`1` - **Focus mode**: the camera is locked to a focus object and its movement depends on it
- :guilabel:`2` - **Game mode**: similar to free mode but the camera is moved with :guilabel:`w`:guilabel:`a`:guilabel:`s`:guilabel:`d` and the view (pitch and yaw) is controlled with the mouse. This control system is commonly found in FPS (First-Person Shooter) games on PC
- :guilabel:`3` - **Gaia mode**: the camera can't be controlled, as it follows Gaia only
- :guilabel:`4` - **Spacecraft mode**: take control of a spacecraft (outside the scope of this tutorial)
- :guilabel:`5`, :guilabel:`6`, :guilabel:`7`  - **Fov modes**: project the fields of view of Gaia on the screen

The most interesting mode is **free mode** which lets us roam freely. Go ahead and press :guilabel:`0` to try it out. The controls are a little different from those of **focus mode**, but they should not be to hard to get used too. Basically, use your **left mouse button** to yaw and pitch the view, use :guilabel:`shift` to roll, and use the **right mouse button** to pan.

Special render modes
~~~~~~~~~~~~~~~~~~~~

There are three special render modes: :ref:`3D mode <3d-mode>`, :ref:`planetarium mode <planetarium-mode>`, :ref:`panorama mode <panorama-mode>` and :ref:`orthosphere view <orthosphere-mode>`. You can access these modes using the buttons at the bottom of the camera pane or the following shortcuts:

- |3d-icon| or :guilabel:`ctrl` + :guilabel:`s` - 3D mode
- |dome-icon| or :guilabel:`ctrl` + :guilabel:`p` - Planetarium mode
- |cubemap-icon| or :guilabel:`ctrl` + :guilabel:`k` - Panorama mode
- |orthosphere-icon| or :guilabel:`ctrl` + :guilabel:`j` - Orthosphere view

.. |3d-icon| image:: ../img/ui/3d-icon.png
.. |dome-icon| image:: ../img/ui/dome-icon.png
.. |cubemap-icon| image:: ../img/ui/cubemap-icon.png
.. |orthosphere-icon| image:: ../img/ui/orthosphere-icon.png

Component visibility
~~~~~~~~~~~~~~~~~~~~

The visibility of most graphical elements can be switched off and on using the buttons in the **type visibility pane** in the control panel.
For example you can hide the stars by clicking on the
``stars`` |stars| button. The object types available are the following:

-  |stars| -- Stars
-  |planets| -- Planets
-  |moons| -- Moons
-  |satellites| -- Satellites
-  |asteroids| -- Asteroids
-  |clusters| -- Star clusters
-  |milkyway| -- Milky Way
-  |galaxies| -- Galaxies
-  |nebulae| -- Nebulae
-  |meshes| -- Meshes
-  |equatorial| -- Equatorial grid
-  |ecliptic| -- Ecliptic grid
-  |galactic| -- Galactic grid
-  |labels| -- Labels
-  |titles| -- Titles
-  |orbits| -- Orbits
-  |locations| -- Locations
-  |cosmiclocations| -- Cosmic locations
-  |countries| -- Countries
-  |constellations| -- Constellations
-  |boundaries| -- Constellation boundaries
-  |ruler| -- Rulers
-  |effects| -- Particle effects
-  |atmospheres| -- Atmospheres
-  |clouds| -- Clouds
-  |axes| -- Axes
-  |arrows| -- Velocity vectors
-  |others| -- Others

.. |stars| image:: ../img/ui/ct/icon-elem-stars.png
.. |planets| image:: ../img/ui/ct/icon-elem-planets.png
.. |moons| image:: ../img/ui/ct/icon-elem-moons.png
.. |satellites| image:: ../img/ui/ct/icon-elem-satellites.png
.. |asteroids| image:: ../img/ui/ct/icon-elem-asteroids.png
.. |clusters| image:: ../img/ui/ct/icon-elem-clusters.png
.. |milkyway| image:: ../img/ui/ct/icon-elem-milkyway.png
.. |galaxies| image:: ../img/ui/ct/icon-elem-galaxies.png
.. |nebulae| image:: ../img/ui/ct/icon-elem-nebulae.png
.. |meshes| image:: ../img/ui/ct/icon-elem-meshes.png
.. |equatorial| image:: ../img/ui/ct/icon-elem-equatorial.png
.. |ecliptic| image:: ../img/ui/ct/icon-elem-ecliptic.png
.. |galactic| image:: ../img/ui/ct/icon-elem-galactic.png
.. |labels| image:: ../img/ui/ct/icon-elem-labels.png
.. |titles| image:: ../img/ui/ct/icon-elem-titles.png
.. |orbits| image:: ../img/ui/ct/icon-elem-orbits.png
.. |locations| image:: ../img/ui/ct/icon-elem-locations.png
.. |cosmiclocations| image:: ../img/ui/ct/icon-elem-cosmiclocations.png
.. |countries| image:: ../img/ui/ct/icon-elem-countries.png
.. |constellations| image:: ../img/ui/ct/icon-elem-constellations.png
.. |boundaries| image:: ../img/ui/ct/icon-elem-boundaries.png
.. |ruler| image:: ../img/ui/ct/icon-elem-ruler.png
.. |effects| image:: ../img/ui/ct/icon-elem-effects.png
.. |atmospheres| image:: ../img/ui/ct/icon-elem-atmospheres.png
.. |clouds| image:: ../img/ui/ct/icon-elem-clouds.png
.. |axes| image:: ../img/ui/ct/icon-elem-axes.png
.. |arrows| image:: ../img/ui/ct/icon-elem-arrows.png
.. |others| image:: ../img/ui/ct/icon-elem-others.png

Velocity vectors
^^^^^^^^^^^^^^^^

One of the elements, the **velocity vectors**, enable a few properties when selected. See the :ref:`velocity vectors section <velocityvectors>` in the Gaia Sky user manual for more information on that.

*  **Number factor** -- control how many velocity vectors are rendered. The stars are sorted by magnitude (ascending) so the brightest stars will get velocity vectors first
*  **Length factor** -- length factor to scale the velocity vectors
*  **Color mode** -- choose the color scheme for the velocity vectors
*  **Show arrowheads** -- Whether to show the vectors with arrow caps or not

.. hint:: Control the width of the velocity vectors with the **line width** slider in the **visual settings** pane.

.. figure:: ../img/screenshots/velocity-vectors.jpg
    :alt: Velocity vectors in Gaia Sky
    :align: center
    :target: ../_images/velocity-vectors.jpg

    Velocity vectors in Gaia Sky

Visual settings
~~~~~~~~~~~~~~~

The **visual settings** pane contains a few options to control the shading of stars and other elements:

-  **Star brightness** -- control the brightness of stars
-  **Magnitude multiplier** -- exponent of power function that controls the brightness of stars. Makes bright stars brighter and faint stars fainter
-  **Star glow factor** -- close-by star size
-  **Point size** -- size of point-like stars and other objects
-  **Base star level** -- the minimum brightness level for all stars
-  **Ambient light** -- control the amount of ambient light. This only
   affects the models such as the planets or satellites
-  **Line width** -- control the width of all lines in Gaia Sky (orbits, velocity vectors, etc.)
-  **Label size** -- control the size of the labels
-  **Elevation multiplier** -- scale the height representation for planets with elevation maps

.. figure:: ../img/ui/visual-settings-2.jpg
    :alt: Visual settings
    :align: center
    :target: ../_images/visual-settings-2.jpg

    The visual settings pane

External datasets
~~~~~~~~~~~~~~~~~

Gaia Sky supports the loading of external datasets at runtime. Right now, ``VOTable``, ``csv`` and ``FITS`` formats are supported. Gaia Sky needs some metadata in the form of UCDs or column names in order to parse the dataset columns correctly. Refer to the :ref:`stil-data-provider` section of the Gaia Sky user manual for more information on how to prepare your dataset for Gaia Sky.

The datasets loaded in Gaia Sky at a certain moment can be found in the :ref:`datasets <datasets>` pane of the control panel.

.. figure:: img/dpac-2021/ds-1.jpg
    :alt: Datasets pane
    :align: center
    :target: ../_images/ds-1.jpg

    Datasets pane of Gaia Sky


There are three main ways to load new datasets into Gaia Sky:

* Directly from the UI, using the |dsload| button or pressing :guilabel:`ctrl` + :guilabel:`o`
* Through SAMP, via a connection to another astronomy software package such as Topcat or Aladin
* Via a script (addressed later on in the workshop if time allows)

**Loading a dataset from the UI** -- Go ahead and remove the current star catalog (either eDR3 or hipparcos) by clicking on the |binicon| icon in the datasets pane. Now, download a raw `Hipparcos dataset VOTable <https://gaia.ari.uni-heidelberg.de/gaiasky/files/catalogs/hip/hipparcos.vot>`__, click on the |dsload| icon (or press :guilabel:`ctrl` + :guilabel:`o`) and select the file. In the next dialog just click :guilabel:`Ok` to start loading the catalog. In a few moments the Hipparcos new reduction dataset should be loaded into Gaia Sky.

**Loading a dataset via SAMP** -- This section presupposes that Topcat is installed on the machine and that the user knows how to use it to connect to the VO to get some data. The following video demonstrates how to do this (`Odysee mirror <https://odysee.com/@GaiaSky:8/gaia-sky-loading-data-with-topcat:9>`__, `YouTube mirror <https://youtu.be/sc0q-VbeoPE>`__):

.. figure:: img/dpac-2020/samp.jpg
	:width: 500px
	:align: center
	:target: https://gaia.ari.uni-heidelberg.de/gaiasky/files/temp/scripts/202303_dpacworkshop/tap-load-topcat.mkv

	Loading a dataset from Topcat through SAMP (click for video)

**Loading a dataset via scripting** -- Wait for the scripting section of this course.

Working with datasets
^^^^^^^^^^^^^^^^^^^^^

All datasets loaded are displayed in the datasets pane in the control panel.
A few useful tips for working with datasets:

-  The visibility of individual datasets can be switched on and off by clicking on the |eye-s-on| button
-  Remove datasets with the |binicon| button
-  You can **highlight a dataset** by clicking on the |highlight-s-off| button. The highlight color is defined by the color selector right on top of it. Additionally, we can map an attribute to the highlight color using a color map. Let's try it out:
  
    1.  Click on the color box in the Hipparcos dataset we have just loaded from Topcat via SAMP
    2.  Select the radio button "Color map"
    3.  Select the *rainbow* color map
    4.  Choose your attriubte. In this case, we will use the number of transits, *ntr*
    5.  Click :guilabel:`Ok`
    6.  Click on the highlight dataset |highlight-s-off| icon to apply the color map

-  You can **define basic filters** on the objects of the dataset using their attributes from the dataset preferences window |prefs-s-icon|. For example, we can filter out all stars with :math:`\delta > 50^{\circ}`:

    1.  Click on the dataset preferences button |prefs-s-icon|
    2.  Click on :guilabel:`Add filter`
    3.  Select your attribute (declination :math:`\delta`)
    4.  Select your comparator (:math:`<`)
    5.  Enter your value, in this case 50
    6.  Click :guilabel:`Ok`
    7.  The stars with a declination greater than 50 degrees should be filtered out

Multiple filters can be combined with the **AND** and **OR** operators

.. |binicon| image:: ../img/ui/bin-icon.png
.. |eye-s-on| image:: ../img/ui/eye-s-on.png
.. |prefs-s-icon| image:: ../img/ui/prefs-s-icon.png
.. |highlight-s-off| image:: ../img/ui/highlight-s-off.png

External information
~~~~~~~~~~~~~~~~~~~~

Gaia Sky offers three ways to display external information on the current focus object: **Wikipedia**, **Gaia archive** and **Simbad**.

.. figure:: img/dpac-2021/external-info.jpg
    :align: center
    :alt: External information
    :target: ../_images/external-info.jpg

    Wikipedia, Gaia archive and Simbad connections

-  When the :guilabel:`+Info` button appears in the focus info pane, it means that there is a Wikipedia article on this object ready to be pulled and displayed in Gaia Sky
-  When the :guilabel:`Archive` button appears in the focus info pane, it means that the full table information of selected star can be pulled from the Gaia archive
-  When the ``Simbad`` link appears in the focus info pane, it means that the objects has been found on Simbad, and you can click the link to open it in your web browser


Scripting
---------

This section includes a **hands-on session** where we work on some scripts (`full file listing <https://gaia.ari.uni-heidelberg.de/gaiasky/files/temp/scripts/202303_dpacworkshop/>`__) and write new ones to later run them on Gaia Sky. The scripts are:

- `hyades-tidal-tails.py <https://gaia.ari.uni-heidelberg.de/gaiasky/files/temp/scripts/202303_dpacworkshop/hyades-tidal-tails.py>`__ --- a simple sequential script which exemplifies some of the most common API calls, and can be used to capture a video. The script requires the following data files to run (save them in the same directory as the script):

    - `Aldebaran.vot <https://gaia.ari.uni-heidelberg.de/gaiasky/files/temp/scripts/202303_dpacworkshop/Aldebaran.vot>`__
    - `Hyades_stars.csv <https://gaia.ari.uni-heidelberg.de/gaiasky/files/temp/scripts/202303_dpacworkshop/Hyades_stars.csv>`__
    - `distSDR3_N.csv <https://gaia.ari.uni-heidelberg.de/gaiasky/files/temp/scripts/202303_dpacworkshop/distSDR3_N.csv>`__

- `line-objects-update.py <https://gaia.ari.uni-heidelberg.de/gaiasky/files/temp/scripts/202303_dpacworkshop/line-objects-update.py>`__ --- a script showcasing the feature to run scripting code within the Gaia Sky main loop, so that it runs every frame. This is used to run update operations every single frame. In our test script, we create a line between the Earth and the Moon, start the time simulation, and update the position of the line every frame so that it stays in sync with the scene.

More information on the scripting system can be found in the :ref:`scripting section <scripting>` of the Gaia Sky user manual.

- Scripting **API specification**:

    - `API Gaia Sky master (development branch) <https://codeberg.org/gaiasky/gaiasky/src/branch/master/core/src/gaiasky/script/IScriptingInterface.java>`__
    - `API Gaia Sky 3.4.1 <https://gaia.ari.uni-heidelberg.de/gaiasky/docs/javadoc/3.4.1/gaiasky/script/IScriptingInterface.html>`__

- Interesting **showcase scripts** can be found `here <https://codeberg.org/gaiasky/gaiasky/src/branch/master/assets/scripts/showcases>`__.
- Basic **testing scripts** can be found `here <https://codeberg.org/gaiasky/gaiasky/src/branch/master/assets/scripts/tests>`__.


Camera paths
-------------

Gaia Sky includes a feature to record and play back camera paths. This comes in handy if you want to showcase a certain itinerary through a dataset, for example.

**Recording a camera path** --- The system will capture the camera state at every frame and save it into a ``.gsc`` (for Gaia Sky camera) file. You can start a recording by clicking on the |rec| icon in the camera pane of the control panel. Once the recording mode is active, the icon will turn red |recred|. Click on it again in order to stop recording and save the camera file to disk with an auto-generated file name (default location is ``$GS_DATA/camera`` (see the :ref:`folders <folders>` section in the Gaia Sky documentation).

**Playing a camera path** --- In order to playback a previously recorded ``.gsc`` camera file, click on the |play| icon and select the desired camera path. The recording will start immediately.

.. hint:: **Mind the FPS!** The camera recording system stores the position of the camera for every frame! It is important that recording and playback are done with the same (stable) frame rate. To set the target recording frame rate, edit the "Target FPS" field in the camcorder settings of the preferences window. That will make sure the camera path is using the right frame rate. In order to play back the camera file at the right frame rate, you can edit the "Maximum frame rate" input in the graphics settings of the preferences window.

.. figure:: img/dpac-2021/camerapaths.jpg
    :alt: Camrecorder
    :align: center
    :target: ../_images/camerapaths.jpg

    Location of the controls of the camcorder in Gaia Sky

.. |rec| image:: ../img/ui/rec-icon-gray.png
.. |recred| image:: ../img/ui/rec-icon-red.png
.. |play| image:: ../img/ui/play-icon.png

More information on camera paths in Gaia Sky can be found in :ref:`the camera paths section <camera-paths>` of the Gaia Sky user manual.

Keyframe system
~~~~~~~~~~~~~~~

The camera path system offers an additional way to define camera paths based on keyframes. Essentially, the user defines the position and orientation of the camera at certain times and the system generates the camera path from these definitions. Gaia Sky incorporates a whole keyframe definition system which is outside the scope of this tutorial.

As a very short preview, in order to bring up the keyframes window to start defining a camera path, click on the icon |keyframes|. 

.. |keyframes| image:: ../img/ui/rec-key-icon-gray.png

More information on the keyframe system can be found in the :ref:`keyframe system subsection <keyframe-system>` of the Gaia Sky user manual.

Frame output system
~~~~~~~~~~~~~~~~~~~

In order to create high-quality videos, Gaia Sky offers the possibility to export every single still frame to an image file. The resolution of these still frames can be set independently of the current screen resolution.

You can start the frame output system by pressing :guilabel:`F6`. Once active, the frame rate will go down (each frame is being saved to disk). The save location of the still frame images is, by default, ``$GS_DATA/frames/[prefix]_[num].jpg``, where ``[prefix]`` is an arbitrary string that can be defined in the preferences. The save location, mode (simple or advanced), and the resolution can also be defined in the preferences.

.. figure:: img/dpac-2023/2023_frame-output-prefs.jpg
    :alt: Frame output
    :align: center
    :target: ../_images/2023_frame-output-prefs.jpg

    The configuration screen for the frame output system

Once we have the still frame images, we can convert them to a video using ``ffmpeg`` or any other encoding software. Additional information on how to convert the still frames to a video can be found in the :ref:`capturing videos section <capture-videos>` of the Gaia Sky user manual.

Videos with ffmpeg
------------------

Please see :ref:`the capturing videos section <capture-videos>`.