Add a setting to control whether gotoSurface preserve initial orientation or not (CelestiaProject#2363)

The current implementation preserves orientation, so after you land you
might be looking up or down, not necessarily looking parallel to the
surface.

adding this for VR/game controller, because in VR/AR you would want the
planet surface to be matching the actual environment when you land, the
landing orientation should be consistent.

Author: levinli303

celestia.cfg.in

@@ -289,6 +289,15 @@ StarTextures
 #  FocusZooming      true
 
 
+#------------------------------------------------------------------------
+# AlignCameraToSurfaceOnLand enables aligning the camera orientation
+# to be parallel with the planetary surface when landing. If false,
+# the current camera orientation is preserved during landing.
+# The default value is false.
+#------------------------------------------------------------------------
+#  AlignCameraToSurfaceOnLand true
+
+
 #------------------------------------------------------------------------
 # The following parameter is used in Lua (.celx) scripting.
 #

src/celengine/observer.cpp

@@ -408,8 +408,9 @@ createFrame(ObserverFrame::CoordinateSystem _coordSys,
  *  updates due to an active goto operation.
  */
 
-Observer::Observer() :
-    frame(std::make_shared<ObserverFrame>())
+Observer::Observer(const std::shared_ptr<celestia::engine::ObserverSettings>& settings) :
+    frame(std::make_shared<ObserverFrame>()),
+    settings(settings)
 {
     updateUniversal();
 }
@@ -438,6 +439,7 @@ Observer::Observer(const Observer& o) :
     zoom(o.zoom),
     alternateZoom(o.alternateZoom),
     reverseFlag(o.reverseFlag),
+    settings(o.settings),
     locationFilter(o.locationFilter),
     displayedSurface(o.displayedSurface)
 {
@@ -470,6 +472,7 @@ Observer& Observer::operator=(const Observer& o)
     zoom = o.zoom;
     alternateZoom = o.alternateZoom;
     reverseFlag = o.reverseFlag;
+    settings = o.settings;
     locationFilter = o.locationFilter;
     displayedSurface = o.displayedSurface;
 
@@ -1505,26 +1508,53 @@ Observer::getSelectionLongLat(const Selection& selection,
 void
 Observer::gotoSurface(const Selection& sel, double duration)
 {
-    Eigen::Vector3d v = getPosition().offsetFromKm(sel.getPosition(getTime()));
-    v.normalize();
-
-    Eigen::Vector3d viewDir = originalOrientationUniv.conjugate() * -Eigen::Vector3d::UnitZ();
-    Eigen::Vector3d up      = originalOrientationUniv.conjugate() * Eigen::Vector3d::UnitY();
-    Eigen::Quaterniond q    = originalOrientationUniv;
-    if (v.dot(viewDir) < 0.0)
-    {
-        q = math::LookAt<double>(Eigen::Vector3d::Zero(), up, v);
-    }
-
     ObserverFrame selFrame(ObserverFrame::CoordinateSystem::BodyFixed, sel);
     UniversalCoord bfPos = selFrame.convertFromUniversal(positionUniv, getTime());
-    q = selFrame.convertFromUniversal(q, getTime());
 
+    // Calculate the surface normal at the landing point (radial direction from center)
+    Eigen::Vector3d surfaceNormal = bfPos.offsetFromKm(UniversalCoord::Zero()).normalized();
+
+    // Position the observer just above the surface
     double height = 1.0001 * sel.radius();
-    Eigen::Vector3d dir = bfPos.offsetFromKm(UniversalCoord::Zero()).normalized() * height;
-    UniversalCoord nearSurfacePoint = UniversalCoord::Zero().offsetKm(dir);
+    UniversalCoord nearSurfacePoint = UniversalCoord::Zero().offsetKm(surfaceNormal * height);
+
+    Eigen::Quaterniond toOrientation;
+    if (celestia::util::is_set(settings->flags, celestia::engine::ObserverFlags::AlignCameraToSurfaceOnLand))
+    {
+        // Get the current orientation in the body-fixed frame
+        Eigen::Quaterniond currentOrientation = selFrame.convertFromUniversal(originalOrientationUniv, getTime());
+
+        // Use the window's up direction (UnitY) as the forward direction
+        Eigen::Vector3d windowUp = currentOrientation.conjugate() * Eigen::Vector3d::UnitY();
+
+        // Project the window's up direction onto the surface plane to get the tangent direction
+        Eigen::Vector3d tangentDirection = windowUp - surfaceNormal * surfaceNormal.dot(windowUp);
 
-    gotoLocation(nearSurfacePoint, q, duration);
+        // Fallback if the projection is too small. In this case the planet is
+        // below or above us (likely not within viewport) so we can just use an
+        // arbitrary orientation.
+        if (tangentDirection.norm() < 0.1)
+        {
+            Eigen::Vector3d reference = (std::abs(surfaceNormal.dot(Eigen::Vector3d::UnitY())) < 0.9) ? Eigen::Vector3d::UnitY() : Eigen::Vector3d::UnitX();
+            tangentDirection = surfaceNormal.cross(reference);
+        }
+
+        tangentDirection.normalize();
+        toOrientation = math::LookAt<double>(Eigen::Vector3d::Zero(), tangentDirection, surfaceNormal);
+    }
+    else
+    {
+        Eigen::Vector3d v       = getPosition().offsetFromKm(sel.getPosition(getTime()));
+        Eigen::Vector3d viewDir = originalOrientationUniv.conjugate() * -Eigen::Vector3d::UnitZ();
+        Eigen::Vector3d up      = originalOrientationUniv.conjugate() * Eigen::Vector3d::UnitY();
+        toOrientation = originalOrientationUniv;
+        if (v.dot(viewDir) < 0.0)
+        {
+            toOrientation = math::LookAt<double>(Eigen::Vector3d::Zero(), up, v);
+        }
+        toOrientation = selFrame.convertFromUniversal(toOrientation, getTime());
+    }
+    gotoLocation(nearSurfacePoint, toOrientation, duration);
 }
 
 void

src/celengine/observer.h

@@ -27,6 +27,8 @@
 #include <Eigen/Geometry>
 
 #include <celcompat/numbers.h>
+#include <celutil/flag.h>
+
 #include "selection.h"
 #include "shared.h"
 #include "univcoord.h"
@@ -37,6 +39,19 @@ namespace celestia::engine
 constexpr inline double MIN_SIG_ANGULAR_SPEED     = 1.0e-10;
 constexpr inline double MIN_SIG_LINEAR_SPEED      = 1.0e-12;
 
+enum class ObserverFlags : unsigned int
+{
+    None                        = 0x0,
+    AlignCameraToSurfaceOnLand  = 0x1,
+};
+
+struct ObserverSettings
+{
+    ObserverFlags flags{ ObserverFlags::None };
+};
+
+ENUM_CLASS_BITWISE_OPS(ObserverFlags);
+
 }
 
 class ReferenceFrame;
@@ -127,7 +142,7 @@ class Observer
     static constexpr const double EndInterpolation   = 0.75;
     static constexpr const double AccelerationTime   = 0.5;
 
-    Observer();
+    explicit Observer(const std::shared_ptr<celestia::engine::ObserverSettings>&);
     Observer(const Observer &o);
     ~Observer() = default;
 
@@ -351,6 +366,8 @@ class Observer
 
     bool reverseFlag{ false };
 
+    std::shared_ptr<celestia::engine::ObserverSettings> settings;
+
     std::uint64_t locationFilter{ DefaultLocationFilter };
     std::string displayedSurface;
 };

src/celengine/simulation.cpp

@@ -21,10 +21,10 @@
 #include "render.h"
 
 
-Simulation::Simulation(Universe* _universe) :
-    universe(_universe)
+Simulation::Simulation(Universe* universe, const std::shared_ptr<celestia::engine::ObserverSettings>& observerSettings) :
+    universe(universe)
 {
-    activeObserver = new Observer();
+    activeObserver = new Observer(observerSettings);
     observers.push_back(activeObserver);
 }
 

src/celengine/simulation.h

@@ -33,7 +33,7 @@ class Renderer;
 class Simulation
 {
 public:
-    explicit Simulation(Universe*);
+    Simulation(Universe*, const std::shared_ptr<celestia::engine::ObserverSettings>&);
     ~Simulation();
 
     double getTime() const; // Julian date

src/celestia/celestiacore.cpp

@@ -2090,6 +2090,16 @@ void CelestiaCore::setInteractionFlags(InteractionFlags flags)
     interactionFlags = flags;
 }
 
+celestia::engine::ObserverFlags CelestiaCore::getObserverFlags() const
+{
+    return observerSettings->flags;
+}
+
+void CelestiaCore::setObserverFlags(celestia::engine::ObserverFlags flags)
+{
+    observerSettings->flags = flags;
+}
+
 // Return true if anything changed that requires re-rendering. Otherwise, we
 // can skip rendering, keep the GPU idle, and save power.
 bool CelestiaCore::viewUpdateRequired() const
@@ -2563,7 +2573,9 @@ bool CelestiaCore::initSimulation(const std::filesystem::path& configFileName,
     set_or_unset(interactionFlags, InteractionFlags::RayBasedDragging, config->mouse.rayBasedDragging);
     set_or_unset(interactionFlags, InteractionFlags::FocusZooming, config->mouse.focusZooming);
 
-    sim = new Simulation(universe);
+    set_or_unset(observerSettings->flags, celestia::engine::ObserverFlags::AlignCameraToSurfaceOnLand, config->observer.alignCameraToSurfaceOnLand);
+
+    sim = new Simulation(universe, observerSettings);
     if (!util::is_set(renderer->getRenderFlags(), RenderFlags::ShowAutoMag))
     {
         sim->setFaintestVisible(config->renderDetails.faintestVisible);

src/celestia/celestiacore.h

@@ -319,6 +319,9 @@ class CelestiaCore // : public Watchable<CelestiaCore>
     InteractionFlags getInteractionFlags() const;
     void setInteractionFlags(InteractionFlags);
 
+    celestia::engine::ObserverFlags getObserverFlags() const;
+    void setObserverFlags(celestia::engine::ObserverFlags);
+
     void setFOVFromZoom();
     void setZoomFromFOV();
 
@@ -436,6 +439,8 @@ class CelestiaCore // : public Watchable<CelestiaCore>
     Simulation* sim{ nullptr };
     Renderer* renderer{ nullptr };
 
+    std::shared_ptr<celestia::engine::ObserverSettings> observerSettings{ std::make_shared<celestia::engine::ObserverSettings>() };
+
     static std::locale loc;
 
     celestia::WindowMetrics metrics;

src/celestia/configfile.cpp

@@ -178,6 +178,13 @@ applyMouse(CelestiaConfig::Mouse& mouse, const AssociativeArray& hash)
 }
 
 
+void
+applyObserver(CelestiaConfig::Observer& observer, const AssociativeArray& hash)
+{
+    applyBoolean(observer.alignCameraToSurfaceOnLand, hash, "AlignCameraToSurfaceOnLand"sv);
+}
+
+
 void
 applyRenderDetails(CelestiaConfig::RenderDetails& renderDetails, const AssociativeArray& hash)
 {
@@ -280,6 +287,7 @@ bool ReadCelestiaConfig(const std::filesystem::path& filename, CelestiaConfig& c
     applyPaths(config.paths, *configParams);
     applyFonts(config.fonts, *configParams);
     applyMouse(config.mouse, *configParams);
+    applyObserver(config.observer, *configParams);
     applyRenderDetails(config.renderDetails, *configParams);
     applyStarTextures(config.starTextures, *configParams, "StarTextures"sv);
 

src/celestia/configfile.h

@@ -63,6 +63,11 @@ struct CelestiaConfig
         bool focusZooming{ false };
     };
 
+    struct Observer
+    {
+        bool alignCameraToSurfaceOnLand{ false };
+    };
+
     struct RenderDetails
     {
         double orbitWindowEnd{ 0.5 };
@@ -96,6 +101,7 @@ struct CelestiaConfig
     Paths paths{ };
     Fonts fonts{ };
     Mouse mouse{ };
+    Observer observer{ };
     RenderDetails renderDetails{ };
     StarDetails::StarTextureSet starTextures{ };