Commit 8c041080 authored by langurmonkey's avatar langurmonkey

Migrating to rst

parent bcbf22f1
This section describes the controls of the Gaia Sky.
## Keyboard controls
To check the most up-to-date controls go to the `Controls` tab in the preferences window.
Here are the default keyboard controls.
Key(s) | Action
:----------------------- | :----------------------------------------------------
`NUMPAD 0` | Free camera
`NUMPAD 1` | Focus camera
`NUMPAD 2` | Gaia FoV 1 camera
`NUMPAD 3` | Gaia FoV 2 camera
`NUMPAD 4` | Gaia FoV 1 and 2 camera
`SPACE` | Toggle simulation play/pause
`F5` | Take screenshot
`F6` | Start/stop frame output mode
`F11` | Toggle fullscreen/windowed mode
`L-CTRL` + `F` | Search dialog
`ESCAPE` | Quit application
`-` | Decrease limiting magnitude
`+` | Increase limiting magnitude
`,` | Divide time warp by two
`.` | Double time warp
`*` | Reset limiting magnitude
`B` | Toggle constellation boundaries
`C` | Toggle constellation lines
`E` | Toggle ecliptic grid
`G` | Toggle galactic grid
`L` | Toggle labels
`M` | Toggle moons
`O` | Toggle orbits
`P` | Toggle planets
`Q` | Toggle equatorial grid
`S` | Toggle stars
`T` | Toggle satellites
`U` | Expand/collapse controls window
`L-CTRL` + `U` | Toggle UI completely (hide/show user interface)
`L-CTRL` + `D` | Toggle debug info
`L-CTRL` + `S` | Toggle stereoscopic mode
`L-CTRL` + `L-SHIFT` + `S` | Switch between stereoscopic profiles
## Mouse controls
Here are the default mouse controls.
Mouse + keys | Action
:-------------------------- | :----------------------------------------------------
`L-MOUSE DOUBLE CLICK` | Select object as focus
`L-MOUSE` + `DRAG` | Pitch and yaw (FREE mode) or rotate around foucs (FOCUS mode)
`L-SHIFT` + `L-MOUSE` + `DRAG` | Camera roll
`R-MOUSE` + `DRAG` | Deviate camera line of sight from focus
`M-MOUSE` + `DRAG` or `WHEEL` | Forward/backward movement
## Gamepad controls
As of version `0.704b` the Gaia Sandbox supports basic gamepad/controller input.
By default, only the **Xbox 360 controller** is supported, so you may want to map your gamepad differently using software like [`jstest-gtk`](http://pingus.seul.org/~grumbel/jstest-gtk/) on Linux or the [`Universal Joystick Remapper`](https://github.com/evilC/AHK-Universal-Joystick-Remapper) for Windows. You can also opt for a Joystick-to-keyboard solution such as [`xpadder`](http://www.xpadder.com/), even though this has not been tested with Gaia Sky.
![Xbox 360 controller button configuration](img/360controller.png)
The actions mapped to each button or axis depend on the current camera mode (focus, free, spacecraft):
### Focus mode
Axis/button | Action
:------------------------------| :----------------------------------------------------
`Left bumper` | Hold to apply `0.5` factor to speed
`Right bumper` | Hold to apply `0.1` factor to speed
`Left trigger` | Move away from focus
`Right trigger` | Move towards focus
`Left stick horizontal` | Horizontal rotation around focus
`Left stick vertical` | Vertical rotation around focus
`Right stick horizontal` | Roll right and left
`Right stick vertical` | Move towards or away from focus
`D-pad` | None
`A` | None
`B` | None
`X` | None
`Y` | None
### Free camera mode
Axis/button | Action
:------------------------------| :----------------------------------------------------
`Left bumper` | Hold to apply `0.5` factor to speed
`Right bumper` | Hold to apply `0.1` factor to speed
`Left trigger` | Move away from focus
`Right trigger` | Move towards focus
`Left stick horizontal` | Yaw right and left
`Left stick vertical` | Pitch up and down
`Right stick horizontal` | Move sideways
`Right stick vertical` | Move forward and backward
`D-pad` | None
`A` | None
`B` | None
`X` | None
`Y` | None
### Spacecraft mode
Axis/button | Action
:------------------------------| :----------------------------------------------------
`Left bumper` | Stabilise spacecraft rotations
`Right bumper` | Stop spacecraft
`Left trigger` | Apply backward thrust
`Right trigger` | Apply forward thrust
`Left stick horizontal` | Yaw right and left
`Left stick vertical` | Pitch up and down
`Right stick horizontal` | Roll right and left
`Right stick vertical` | None
`D-pad` | None
`A` | Decrease engine power
`B` | None
`X` | Increase engine power
`Y` | None
## Touch controls
No mobile version yet.
This diff is collapsed.
The Gaia Sandbox offers the possibility to record camera paths out of the box in real time and later play them. These camera paths go to a `text` file in the `temp` folder of your system.
### Camera path file format
The format of the file is pretty straightforward. It consists of a `csv` file with white spaces as delimiters, each row containing the **state** of the camera and the **time**. The state of the camera consists of 9 double-precision floating point numbers, 3 for the **position** and 3 for the **direction** vector and 3 for the **up** vector.
The reference system used is explained in the [[Reference system|Internal-reference-system]] section. The units are `1e-9 * m`.
The format of each row is as follows:
- `long` - Time as defined by the `getTime()` function of [`java.util.Date`](https://docs.oracle.com/javase/8/docs/api/java/util/Date.html#getTime--).
- `double x3` - Position of the camera.
- `double x3` - Direction vector of the camera.
- `double x3` - Up vector of the camera.
### Recording camera paths
In order to **start recording** the camera path, click on the `REC` button next to the Camera section title in the GUI Controls window. The `REC` button will turn red, which indicates the camera is being recorded.
In order to **stop the recording** and write the file, click again on the red `REC` button. The button will turn grey and a notification will pop up indicating the location of the camera file.
Camera files are by default saved in the `$USERHOME/.gaiasky/camera` directory.
### Playing camera paths
In order to play a camera file, click on the folder icon next to the `REC` icon. This will prompt a list of available camera files in the `$USERHOME/.gaiasky/camera` folder.
Recording and playing camera paths
**********************************
The Gaia Sky offers the possibility to record camera paths out of the
box in real time and later play them. These camera paths go to a
``text`` file in the ``temp`` folder of your system.
Camera path file format
=======================
The format of the file is pretty straightforward. It consists of a
``csv`` file with white spaces as delimiters, each row containing the
**state** of the camera and the **time**. The state of the camera
consists of 9 double-precision floating point numbers, 3 for the
**position** and 3 for the **direction** vector and 3 for the **up**
vector.
The reference system used is explained in the [[Reference
system\|Internal-reference-system]] section. The units are ``1e-9 * m``.
The format of each row is as follows:
- ``long`` - Time as defined by the ``getTime()`` function of
```java.util.Date`` <https://docs.oracle.com/javase/8/docs/api/java/util/Date.html#getTime-->`__.
- ``double x3`` - Position of the camera.
- ``double x3`` - Direction vector of the camera.
- ``double x3`` - Up vector of the camera.
Recording camera paths
======================
In order to **start recording** the camera path, click on the ``REC``
button next to the Camera section title in the GUI Controls window. The
``REC`` button will turn red, which indicates the camera is being
recorded.
In order to **stop the recording** and write the file, click again on
the red ``REC`` button. The button will turn grey and a notification
will pop up indicating the location of the camera file. Camera files are
by default saved in the ``$USERHOME/.gaiasky/camera`` directory.
Playing camera paths
====================
In order to play a camera file, click on the folder icon next to the
``REC`` icon. This will prompt a list of available camera files in the
``$USERHOME/.gaiasky/camera`` folder.
The Gaia Sandbox includes a [stereoscopic mode](http://en.wikipedia.org/wiki/Stereoscopy) or 3D mode which outputs two images each intended for each eye, creating the illusion of depth.
In order to activate the stereoscopic mode press `LEFT_CTRL` + `S`.
### Stereoscopic profiles
Usually, as the images are placed side by side (even though most 3DTVs also support up and down), the right image is intended for the right eye and the left image is intended for the left eye. This works with 3DTVs and VR head sets (such as the [Oculus Rift](https://www.oculus.com/), [Google cardboard](https://www.google.com/get/cardboard/), etc.). In 3DTVs, however, the image is distorted because each half of the TV will be stretched back to the whole TV area when the 3D mode is on.
Additionally, there is a technique called cross-eye 3D (you can find some examples [here](http://digital-photography-school.com/9-crazy-cross-eye-3d-photography-images-and-how-to-make-them/), and [here](https://www.youtube.com/watch?v=zBa-bCxsZDk) is a very nice video teaching the concept and how to achieve it) which works without any extra equipment and consists on trying to focus your eyes some distance before the actual image so that each eye receives the correct image. In this case the right images goes to the left eye and the left image goes to the right eye.
In order to manage all these parameters, we have created 3 stereoscopic profiles which can be selected by the user and are described below.
- **`VR_HEADSET`** - The **left** image goes to the **left** eye. No distortion is applied.
- **`Crosseye`** - The **left** image goes to the **right** eye. No distortion is applied.
- **`3DTV`** - The **left** image goes to the **left** eye. Distortion is applied.
In order to switch between the three modes, use `LEFT_CTRL` + `LEFT_SHIFT` + `S`.
Profile | Image
---------------------------|------------------------------------
VR_HEADSET | [[http://www.zah.uni-heidelberg.de/fileadmin/user_upload/gaia/gaiasandbox/img/stereo/stereo_VR.png | height=360px]]
Crosseye | [[http://www.zah.uni-heidelberg.de/fileadmin/user_upload/gaia/gaiasandbox/img/stereo/stereo_CROSSEYE.png | height=360px]]
3DTV | [[http://www.zah.uni-heidelberg.de/fileadmin/user_upload/gaia/gaiasandbox/img/stereo/stereo_3DTV.png | height=360px]]
\ No newline at end of file
Stereoscopic (3D) mode
**********************
The Gaia Sandbox includes a `stereoscopic
mode <http://en.wikipedia.org/wiki/Stereoscopy>`__ or 3D mode which
outputs two images each intended for each eye, creating the illusion of
depth.
In order to activate the stereoscopic mode press ``LEFT_CTRL`` + ``S``.
Stereoscopic profiles
=====================
Usually, as the images are placed side by side (even though most 3DTVs
also support up and down), the right image is intended for the right eye
and the left image is intended for the left eye. This works with 3DTVs
and VR head sets (such as the `Oculus Rift <https://www.oculus.com/>`__,
`Google cardboard <https://www.google.com/get/cardboard/>`__, etc.). In
3DTVs, however, the image is distorted because each half of the TV will
be stretched back to the whole TV area when the 3D mode is on.
Additionally, there is a technique called cross-eye 3D (you can find
some examples
`here <http://digital-photography-school.com/9-crazy-cross-eye-3d-photography-images-and-how-to-make-them/>`__,
and `here <https://www.youtube.com/watch?v=zBa-bCxsZDk>`__ is a very
nice video teaching the concept and how to achieve it) which works
without any extra equipment and consists on trying to focus your eyes
some distance before the actual image so that each eye receives the
correct image. In this case the right images goes to the left eye and
the left image goes to the right eye.
In order to manage all these parameters, we have created 3 stereoscopic
profiles which can be selected by the user and are described below.
- **``VR_HEADSET``** - The **left** image goes to the **left** eye. No
distortion is applied.
- **``Crosseye``** - The **left** image goes to the **right** eye. No
distortion is applied.
- **``3DTV``** - The **left** image goes to the **left** eye.
Distortion is applied.
In order to switch between the three modes, use ``LEFT_CTRL`` +
``LEFT_SHIFT`` + ``S``.
+---------------+--------------------------------------------------------------------------------------------------------------------------------+
| Profile | Image |
+===============+================================================================================================================================+
| VR\_HEADSET | [[http://www.zah.uni-heidelberg.de/fileadmin/user\_upload/gaia/gaiasandbox/img/stereo/stereo\_VR.png \| height=360px]] |
+---------------+--------------------------------------------------------------------------------------------------------------------------------+
| Crosseye | [[http://www.zah.uni-heidelberg.de/fileadmin/user\_upload/gaia/gaiasandbox/img/stereo/stereo\_CROSSEYE.png \| height=360px]] |
+---------------+--------------------------------------------------------------------------------------------------------------------------------+
| 3DTV | [[http://www.zah.uni-heidelberg.de/fileadmin/user\_upload/gaia/gaiasandbox/img/stereo/stereo\_3DTV.png \| height=360px]] |
+---------------+--------------------------------------------------------------------------------------------------------------------------------+
## GUI window ##
The Gaia Sky application has an on-screen user interface designed to be
easy to use. It is divided into five sections, [Time](#time), [Camera](#camera), [Objects](#objects), [Type visibility](#type-visibility), [Lighting](#lighting) and [Gaia scan](#gaia-scan).
### Time
You can play and pause the simulation using the `PLAY/PAUSE` button in the
`Controls` window to the left. You can also use `SPACE` to play and pause the time.
You can also change time warp, which is expressed as a factor. Use `,` and `.` to divide by 2 and double
the value of the time warp.
### Camera
In the camera options pane on the left you can select the type of camera.
This can also be done by using the `NUMPAD 0-4` keys.
There are four camera modes:
* `Free mode`, where the camera is not linked
to any object and its velocity is exponential with respect to the distance
to the origin (Sun).
* `Focus mode`, where the camera is linked to a focus
object and it rotates and rolls with respect to it.
* `Gaia FOV`, where the
camera simulates either of the fields of view of Gaia, or both.
* `Spacecraft`, where you take control of a spacecraft and navigate
around at will.
Additionally, there are a number of sliders for you to control
different parameters of the camera:
- **Field of view**: Controls the field of view angle of the camera. The bigger
it is, the larger the portion of the scene represented.
- **Camera speed**: Controls the longitudinal speed of the camera.
- **Rotation speed**: Controls the transversal speed of the camera, how fast it
rotates around an object.
- **Turn speed**: Controls the turning speed of the camera.
You can **lock the camera** to the focus when in focus mode. Doing so
links the reference system of the camera to that of the object and thus
it moves with it.
Finally, we can also **lock the orientation** of the camera to that of the focus
so that the same transformation matrix is applied to both.
Additionally, we can also enable the **crosshair**, which will mark the currently
focused object.
### Objects
There is a list of focus objects that can be selected from
the interface. When an object is selected the camera automatically centers
it in the view and you can rotate around it or zoom in and out.
Objects can also be selected by double-clicking on them directly in the view or
by using the search box provided above the list. You can also invoke a search dialogue
by pressing `CTRL+F`.
### Type visibility
Most graphical elements can be turned off and on using these
toggles. For example you can remove the stars from the display by
clicking on the `stars` toggle. The object types available are
the following:
- Stars
- Planets
- Moons
- Satellites, the spacecrafts
- Asteroids
- Labels, all the text labels
- Equatorial grid
- Ecliptic grid
- Galactic grid
- Orbits, the orbit lines
- Atmospheres, the atmospheres of planets
- Constellations, the constellation lines
- Boundaries, the constellation boundaries
- Milky way
- Others
By checking the **proper motion vectors** checkbox we can enable the representation of star proper
motions if the currently loaded catalog provides them. Once proper motions are
activated, we can control the number of displayed proper motions and their length
by using the two sliders that appear.
### Lighting
Here are a few options to control the lighting of the scene:
- **Star brightness**: Controls the brightness of stars.
- **Star size**: Controls the size of point-like stars.
- **Min. star opacity**: Sets a minimum opacity for the faintest stars.
- **Ambient light**: Controls the amount of ambient light. This only
affects the models such as the planets or satellites.
- **Bloom effect**: Controls the bloom effect.
- **Brightness**: Controls the brightness of the image.
- **Contrast**: Controls the contrast of the image.
- **Motion blur**: Enable or disable the motion blur effect.
- **Lens flare**: Enable or disable the lens flare.
- **Star glow**: Enable or disable star glows. If enabled, the stars are rendered
using a glow texture in a post-processing step. This can have a performance hit on some
older graphics cards.
### Gaia scan
You can also enable the real time computation of Gaia observation. To
do so, tick the `Enable Gaia scan` checkbox. Keep in mind that this computation
is done by interpolating the scan path and calculating what stars fall
into Gaia's both fields of view, so if you set the time pace very
high it is going to take a toll on the frames per second.
Also, you can choose to colour the stars observed by Gaia according
to the number of observations, where purple is 1 and red is 75. To do so,
tick the `Colour observed stars` checkbox.
Finally, you can decide to only display the stars that have been observed
by Gaia at least once. To do so, tick the `Show only observed stars`
checkbox.
### Music
Since version 0.800b Gaia Sky also offers a music player in its interface. By default
it ships with two suitable 'spacey' songs, but you can add your own. In order to add your own
songs, drop the `mp3`, `ogg` or `wav` files to the folder `$HOME/.gaiasky/music` and these
will be available during your Gaia Sky sessions to play.
## Running scripts ##
In order to run python scripts, click on the `Run script...` button at the
bottom of the GUI window. A new window will pop up allowing you to select
the script you want to run. Once you have selected it, the script will be
checked for errors. If no errors were found, you will be notified in the
box below and you'll be able to run the script right away by clicking on
the `Run` button. If the script contains errors, you will be notified
in the box below and you will not be able to run the script until these
errors are dealt with.
## Preferences window ##
You can launch the preferences window any time during the execution
of the program. To do so, click on the `Preferences` button at
the bottom of the GUI window. For a detailed description of the
configuration options refer to the [Configuration Instructions](Configuration-interface).
User Interface
**************
GUI window
==========
The Gaia Sky application has an on-screen user interface designed to be
easy to use. It is divided into five sections, `Time <#time>`__,
`Camera <#camera>`__, `Objects <#objects>`__, `Type
visibility <#type-visibility>`__, `Lighting <#lighting>`__ and `Gaia
scan <#gaia-scan>`__.
Time
----
You can play and pause the simulation using the ``PLAY/PAUSE`` button in
the ``Controls`` window to the left. You can also use ``SPACE`` to play
and pause the time. You can also change time warp, which is expressed as
a factor. Use ``,`` and ``.`` to divide by 2 and double the value of the
time warp.
Camera
------
In the camera options pane on the left you can select the type of
camera. This can also be done by using the ``NUMPAD 0-4`` keys.
There are four camera modes: \* ``Free mode``, where the camera is not
linked to any object and its velocity is exponential with respect to the
distance to the origin (Sun). \* ``Focus mode``, where the camera is
linked to a focus object and it rotates and rolls with respect to it. \*
``Gaia FOV``, where the camera simulates either of the fields of view of
Gaia, or both. \* ``Spacecraft``, where you take control of a spacecraft
and navigate around at will.
Additionally, there are a number of sliders for you to control different
parameters of the camera:
- **Field of view**: Controls the field of view angle of the camera.
The bigger it is, the larger the portion of the scene represented.
- **Camera speed**: Controls the longitudinal speed of the camera.
- **Rotation speed**: Controls the transversal speed of the camera, how
fast it rotates around an object.
- **Turn speed**: Controls the turning speed of the camera.
You can **lock the camera** to the focus when in focus mode. Doing so
links the reference system of the camera to that of the object and thus
it moves with it.
Finally, we can also **lock the orientation** of the camera to that of
the focus so that the same transformation matrix is applied to both.
Additionally, we can also enable the **crosshair**, which will mark the
currently focused object.
Objects
-------
There is a list of focus objects that can be selected from the
interface. When an object is selected the camera automatically centers
it in the view and you can rotate around it or zoom in and out. Objects
can also be selected by double-clicking on them directly in the view or
by using the search box provided above the list. You can also invoke a
search dialogue by pressing ``CTRL+F``.
Type visibility
---------------
Most graphical elements can be turned off and on using these toggles.
For example you can remove the stars from the display by clicking on the
``stars`` toggle. The object types available are the following:
- Stars
- Planets
- Moons
- Satellites, the spacecrafts
- Asteroids
- Labels, all the text labels
- Equatorial grid
- Ecliptic grid
- Galactic grid
- Orbits, the orbit lines
- Atmospheres, the atmospheres of planets
- Constellations, the constellation lines
- Boundaries, the constellation boundaries
- Milky way
- Others
By checking the **proper motion vectors** checkbox we can enable the
representation of star proper motions if the currently loaded catalog
provides them. Once proper motions are activated, we can control the
number of displayed proper motions and their length by using the two
sliders that appear.
Lighting
--------
Here are a few options to control the lighting of the scene:
- **Star brightness**: Controls the brightness of stars.
- **Star size**: Controls the size of point-like stars.
- **Min. star opacity**: Sets a minimum opacity for the faintest stars.
- **Ambient light**: Controls the amount of ambient light. This only
affects the models such as the planets or satellites.
- **Bloom effect**: Controls the bloom effect.
- **Brightness**: Controls the brightness of the image.
- **Contrast**: Controls the contrast of the image.
- **Motion blur**: Enable or disable the motion blur effect.
- **Lens flare**: Enable or disable the lens flare.
- **Star glow**: Enable or disable star glows. If enabled, the stars
are rendered using a glow texture in a post-processing step. This can
have a performance hit on some older graphics cards.
Gaia scan
---------
You can also enable the real time computation of Gaia observation. To do
so, tick the ``Enable Gaia scan`` checkbox. Keep in mind that this
computation is done by interpolating the scan path and calculating what
stars fall into Gaia's both fields of view, so if you set the time pace
very high it is going to take a toll on the frames per second. Also, you
can choose to colour the stars observed by Gaia according to the number
of observations, where purple is 1 and red is 75. To do so, tick the
``Colour observed stars`` checkbox. Finally, you can decide to only
display the stars that have been observed by Gaia at least once. To do
so, tick the ``Show only observed stars`` checkbox.
Music
-----
Since version 0.800b Gaia Sky also offers a music player in its
interface. By default it ships with two suitable 'spacey' songs, but you
can add your own. In order to add your own songs, drop the ``mp3``,
``ogg`` or ``wav`` files to the folder ``$HOME/.gaiasky/music`` and
these will be available during your Gaia Sky sessions to play.
Running scripts
===============
In order to run python scripts, click on the ``Run script...`` button at
the bottom of the GUI window. A new window will pop up allowing you to
select the script you want to run. Once you have selected it, the script
will be checked for errors. If no errors were found, you will be
notified in the box below and you'll be able to run the script right
away by clicking on the ``Run`` button. If the script contains errors,
you will be notified in the box below and you will not be able to run
the script until these errors are dealt with.
Preferences window
==================
You can launch the preferences window any time during the execution of
the program. To do so, click on the ``Preferences`` button at the bottom
of the GUI window. For a detailed description of the configuration
options refer to the `Configuration
Instructions <Configuration>`__.
...@@ -9,12 +9,16 @@ Welcome to Gaia Sky's documentation! ...@@ -9,12 +9,16 @@ Welcome to Gaia Sky's documentation!
Contents: Contents:
.. toctree:: .. toctree::
:maxdepth: 4 :maxdepth: 3
Home Home
Requirements Requirements
Configuration Configuration
Running-the-software Running-the-software
User-interface
Controls
Stereoscopic-mode
Recording-camera
Indices and tables Indices and tables
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment