.. _3d-mode: Stereoscopic (3D) mode ********************** Gaia Sky includes a real-time stereoscopic rendering mode that generates two separate images--one for each eye--creating the illusion of depth. This mode can be activated at any time and works with various 3D viewing technologies. .. hint:: |3d-icon| or :guilabel:`Ctrl` + :guilabel:`s` -- Toggle stereoscopic mode on/off :guilabel:`Ctrl` + :guilabel:`Shift` + :guilabel:`s` -- Cycle through 3D profiles You can also access 3D settings via :menuselection:`Preferences --> Stereoscopic settings` .. _3d-how-it-works: When enabled, Gaia Sky renders the scene from two slightly offset camera positions simulating the left and right eye views. The resulting image pair is arranged according to the selected **stereoscopic profile**. The stereoscopic mode settings is configured from the :ref:`stereoscopic settings ` tab in the preferences window. Basic viewing methods --------------------- **Hardware-Assisted Viewing:** * **3D TVs & Monitors** -- Uses side-by-side or top-bottom formats that compatible displays can convert to 3D. * **Anaglyph** -- Works with tinted glasses that filter light differently for each eye. **Free-Viewing (No Special Equipment):** * **Cross-Eye 3D** -- Right image shown to left eye, left image shown to right eye. * **Parallel View** -- Standard arrangement (right→right eye, left→left eye). .. note:: Free-viewing techniques require practice. For best results: * **Cross-eye**: Focus *behind* the screen as if looking at a distant object * **Parallel view**: Focus *in front* of the screen, letting your eyes diverge .. _stereo-profiles: Stereoscopic profiles --------------------- Gaia Sky provides six stereoscopic profiles optimized for different viewing methods. Each profile handles image separation, arrangement, and processing appropriately. Profile details ~~~~~~~~~~~~~~~ +-----------------------+---------------------+-------------------------------------------+ | Profile | Image Arrangement | Primary Use | +=======================+=====================+===========================================+ | **VR Headset** | Side-by-side | Basic VR viewers (lens distortion applied)| | | Left→Left | | +-----------------------+---------------------+-------------------------------------------+ | **Cross-Eye** | Side-by-side | Free-viewing (cross-eye technique) | | | Left→Right* | | +-----------------------+---------------------+-------------------------------------------+ | **Parallel View** | Side-by-side | Free-viewing (parallel technique) | | | Left→Left | | +-----------------------+---------------------+-------------------------------------------+ | **3DTV Horizontal** | Side-by-side | 3D TVs in side-by-side mode | | | Left→Left | (images stretched vertically) | +-----------------------+---------------------+-------------------------------------------+ | **3DTV Vertical** | Top-bottom | 3D TVs in top-bottom mode | | | Top→Left | (images stretched horizontally) | +-----------------------+---------------------+-------------------------------------------+ | **Anaglyph** | Color overlay | Red/cyan or other color-filter glasses | +-----------------------+---------------------+-------------------------------------------+ \* *In cross-eye mode, the left image is intended for the right eye and vice versa.* .. _anaglyph-profiles: Anaglyph profiles ~~~~~~~~~~~~~~~~~ We offer various **anaglyph** profiles, suited for different color-filter glasses: * **Red/Cyan** -- Standard red/cyan anaglyph with gamma-per-channel enhancement * **Red/Cyan Dubois-style** -- Red/cyan with Dubois-style filtering to reduce ghosting and shimmering * **Amber/Blue** -- Standard amber/blue anaglyph * **Amber/Blue Dubois-style** -- Amber/blue with Dubois-style filtering * **Green/Magenta** -- Standard green/magenta anaglyph * **Green/Magenta Dubois-style** -- Green/magenta with Dubois-style filtering * **Red/Blue** -- Classic red/blue anaglyph * **Custom** -- Choose your own anaglyph colors from the preferences dialog. .. hint:: The **VR Headset** profile applies barrel distortion to counteract pincushion distortion in VR lenses. This works for basic Cardboard-style viewers but is not equivalent to full VR mode. +-----------------------+----------+ | Profile | Preview | +=======================+==========+ | **VR Headset** | |VR| | +-----------------------+----------+ | **Cross-Eye** | |XEYE| | +-----------------------+----------+ | **Parallel View** | |PARA| | +-----------------------+----------+ | **3DTV Horizontal** | |3DTV-h| | +-----------------------+----------+ | **3DTV Vertical** | |3DTV-v| | +-----------------------+----------+ | **Anaglyph red/cyan** | |ANAG| | +-----------------------+----------+ .. |VR| image:: img/3d/3d-vrheadset.jpg :width: 100% :alt: VR headset stereoscopic preview .. |XEYE| image:: img/3d/3d-crosseye.jpg :width: 100% :alt: Cross-eye stereoscopic preview .. |PARA| image:: img/3d/3d-parallel.jpg :width: 100% :alt: Parallel view stereoscopic preview .. |3DTV-h| image:: img/3d/3d-3dtv-h.jpg :width: 100% :alt: 3DTV horizontal stereoscopic preview .. |3DTV-v| image:: img/3d/3d-3dtv-v.jpg :width: 100% :alt: 3DTV vertical stereoscopic preview .. |ANAG| image:: img/3d/3d-anaglyph.jpg :width: 100% :alt: Anaglyph red/cyan stereoscopic preview Stereoscopic mode vs full VR ---------------------------- .. important:: **Stereoscopic Mode** and **Full VR Mode** are different features in Gaia Sky: +-----------------------+------------------------------+-----------------------------------+ | Feature | Stereoscopic Mode | Full VR Mode | +=======================+==============================+===================================+ | **Activation** | Toggle anytime in main app | Special VR launcher required | +-----------------------+------------------------------+-----------------------------------+ | **Technology** | Standard rendering | OpenXR runtime | +-----------------------+------------------------------+-----------------------------------+ | **Tracking** | Mouse/keyboard/gamepad | 6DOF head and controller tracking | +-----------------------+------------------------------+-----------------------------------+ | **Input** | Standard Gaia Sky controls | VR controller input | +-----------------------+------------------------------+-----------------------------------+ | **Use Case** | 3D visualization on screen | Immersive VR experience | +-----------------------+------------------------------+-----------------------------------+ For full VR with head tracking and motion controllers, you need to use the **OpenXR VR mode**. See the :ref:`VR section ` for details on setting up and using Gaia Sky in full VR mode. Troubleshooting --------------- Common Issues: * **Double vision/eye strain** -- Reduce **IPD** value * **Incorrect 3D effect** -- Ensure correct profile for your viewing method * **3D TV not detecting signal** -- Check TV's 3D mode matches Gaia Sky's output format * **Distorted image in VR viewer** -- Use **VR Headset** profile for basic viewers .. |3d-icon| image:: img/ui/3d-icon.png :class: filter-invert :alt: 3D mode icon Technical implementation ------------------------ The stereoscopic mode settings are available in the preferences dialog, :ref:`stereoscopic settings `. We compute the eye separation with this formula: .. math:: S_{eye} = \min\left(k \cdot \frac{IPD}{d_S} \cdot d_B \cdot f_{FOV}, S_{max}\right) with: - :math:`S_{eye}` is the final eye separation, in internal units. - :math:`k` is the global aesthetic scale factor (comfort multiplier). It is a user-adjustable coefficient that scales the entire calculated eye separation, compensating for the mismatch between the theoretical geometric model (based on human-scale IPD and screen distance) and the visually comfortable hyper-stereoscopy required for astronomical scales. Setting :math:`k < 1` pulls the perceived 3D effect deeper behind the screen for user comfort and reduced eye strain. Unitless. - :math:`IPD` is the interpupillary distance, in mm. - :math:`d_S` is the screen distance, in mm. - :math:`d_B` is the distance to the closest body (either the focus or otherwise), in internal units. Sets the zero-parallax plane at the closest object. - :math:`f_{FOV}` is the field of view factor, computed as :math:`tan(fov \cdot 0.5) / tan(fov_{ref} \cdot 0.5)`. Unitless. - :math:`S_{max}` is the maximum separation allowed, ~1.0e8 km, expressed in internal units. The key geometric component is the **FOV Factor** (:math:`f_{FOV}`), which uses the tangent function to ensure the calculated separation correctly correlates with the perspective projection onto the 2D screen plane. :math:`IPD` and :math:`d_S`, together with an effect scale factor, :math:`k`, are user-adjustable. Refer to the :ref:`stereoscopic mode configuration ` section for more information. Low-Pass filter (smoothing) ~~~~~~~~~~~~~~~~~~~~~~~~~~~ To prevent visual artifacts and user discomfort (dizziness) when :math:`d_B` or :math:`fov` changes rapidly, the final :math:`S_{eye}` is fed into a **single-pole low-pass filter (LPF)** function: .. math:: S_{calc}(t) = S_{calc}(t-1) \cdot (1 - \alpha) + S_{eye} \cdot \alpha * :math:`S_{calc}(t)` is the actual separation used for rendering. * :math:`\alpha` (alpha) is the **smoothing factor** (:math:`\alpha \in [0, 1]`), which controls the filter's response time. A small :math:`\alpha` (e.g., 0.05 to 0.10) ensures the transition is smooth and imperceptible to the user.