.. _quick-start-guide:

.. |start| image:: ../img/ui/iconic-play-circle.png
   :class: filter-invert
.. |download| image:: ../img/ui/iconic-data-transfer-download.png
   :class: filter-invert
.. |prefsicon| image:: ../img/ui/prefs-icon.png
   :class: filter-invert
.. |helpicon| image:: ../img/ui/help-icon.png
   :class: filter-invert
.. |docs| image:: ../img/ui/iconic-book.png
   :class: filter-invert
.. |exit| image:: ../img/ui/quit-icon.png
   :class: filter-invert

Quick start guide
=================

.. tip:: This guide is designed for the latest version of Gaia Sky. Ensure your software is up to date to follow along seamlessly!

The main objective of this guide is to provide a concise "on-ramp" to the Gaia Sky platform, covering its core operations and most common features.

**Gaia Sky crash course:** For a visual introduction, check out the `companion web presentation <https://gaia.ari.uni-heidelberg.de/gaiasky/presentation/gaiasky-crash-course/>`__.

Guide overview:
---------------

- **Introduction to Gaia Sky:**
    - :ref:`qs-dataset-manager`.
    - :ref:`Controls <qs-controls>`, :ref:`movement <qs-movement>`, and :ref:`selection <qs-selection>`.
    - :ref:`User interface <qs-user-interface>` overview.
    - :ref:`Camera operation and modes <qs-camera>`.
    - :ref:`Render modes <qs-render-modes>` (3D, Planetarium, 360, Re-projection).
    - :ref:`Object and type visibility <qs-type-visibility>`.
    - :ref:`Visual settings <qs-visual-settings>`.
    - :ref:`Managing datasets <qs-datasets>` (loading, filters, and SAMP).

- **Scripting:**
    - :ref:`Scripting basics <qs-scripting-basics>`.
    - :ref:`The API <qs-api>`.
    - :ref:`Showcase scripts <qs-showcase-scripts>`.
    - :ref:`Hands-on session <qs-handson>`.

- **Camera paths:**
    - :ref:`Recording and playback <qs-record-playback>`.
    - :ref:`Keyframe system <qs-keyframes>`.

- **Output and video:**
    - :ref:`Still frame output mode <qs-frame-output>`.
    - :ref:`Creating video from still frames <qs-ffmpeg>` with ``ffmpeg``.

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

To follow this guide effectively, you should have Gaia Sky installed locally. If you haven't installed it yet, please follow the instructions for your operating system in the |docs| :ref:`installation section <installation>`.

The welcome window
------------------

When you launch Gaia Sky for the first time, you are greeted by the onboarding screen:

.. figure:: ../img/welcome/welcome-screen-onboarding.jpg
    :alt: Gaia Sky onboarding screen.
    :align: center
    :target: _images/welcome-screen-onboarding.jpg

    The onboarding screen offers a choice between a quick-start recommended setup or a fully customized experience.

From this window, you can access global **Preferences** (|prefsicon|), the **Help** window (|helpicon|), or **Exit** the program (|exit|) using the icons in the bottom-right corner.

There are two primary ways to begin:

- |start| :guilabel:`Start with recommended datasets` — Automatically downloads a curated selection of essential datasets and launches Gaia Sky immediately.
- |download| :guilabel:`Customize datasets` — Opens the dataset manager, allowing you to manually pick and choose which data to download and enable.

If you choose the **recommended** option, a progress window will appear. Once the download is complete, Gaia Sky will launch automatically.

If you choose to **customize** your setup, you will see the following view:

.. figure:: ../img/welcome/welcome-screen-nods.jpg
    :alt: Gaia Sky welcome screen with no datasets.
    :align: center
    :target: _images/welcome-screen-nods.jpg

    The welcome screen displayed when no local datasets are detected.

From here, you can return to the previous screen by clicking **Back**, or click |download| :guilabel:`Dataset manager` to begin your manual selection. This process is covered in detail in the next section.

.. toctree::
   :caption: Gaia Sky Introduction
   :hidden:

   Qs-dsmanager
   Qs-controls-movement
   Qs-user-interface
   Qs-camera-modes
   Qs-special-modes
   Qs-types
   Qs-visual-settings
   Qs-external-datasets
   Qs-external-info

.. toctree::
   :caption: Scripting and more
   :hidden:

   Qs-scripting
   Qs-camera-paths
   Qs-video