coordConverter.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
#pragma once
 
//! \file coordConverter.h
//! \brief Provides coordinate conversion functionality between different coordinate systems
 
#include "vreUtil/export.h"
 
#include "vreUtil/initializer.h"
 
#include <matrix/vlVector.h>
#include <matrix/vlTaitBryan.h>
#include <matrix/geodeticCoord.h>
#include <matrix/coordTransform.h>
#include <matrix/utmReferencePoint.h>
 
namespace makVre
{
 
//! \brief Class for converting between different coordinate systems
//!
//! The DtCoordinateConvert class provides methods for converting positions, vectors,
//! and orientations between different coordinate systems, including geocentric,
//! topographic, UTM, and flat-earth coordinates. It also supports axis remapping
//! and flipping to handle different coordinate system conventions.
class UTIL_DLL DtCoordinateConvert
{
public:
   //! \brief Enumeration of axis types
   enum AxisType
   {
      X, //!< X axis
      Y, //!< Y axis
      Z  //!< Z axis
   };
 
   //! \brief Enumeration of coordinate system types
   enum CoordinateType
   {
      FLATEARTH,   //!< Flat earth coordinates (local tangent plane approximation)
      TOPOGRAPHIC, //!< Topographic coordinates (local NED coordinate system)
      UTM,         //!< Universal Transverse Mercator coordinates
      GEOCENTRIC   //!< Earth-centered Earth-fixed coordinates
   };
 
   //! \brief Structure containing initialization data for coordinate conversion
   struct DtCoordConvertInitData
   {
      CoordinateType coordinateType; //!< The coordinate system type
      DtGeodeticCoord origin;        //!< The geodetic origin (lat, lon, alt)
      DtVector offset;               //!< Optional offset to apply to coordinates
      bool flipX;                    //!< Flag to flip the X axis
      bool flipY;                    //!< Flag to flip the Y axis
      bool flipZ;                    //!< Flag to flip the Z axis
      AxisType rempapX;              //!< Axis to use for X in remapping
      AxisType rempapY;              //!< Axis to use for Y in remapping
      AxisType rempapZ;              //!< Axis to use for Z in remapping
      bool useFalseEasting;          //!< Flag to use false easting in UTM coordinates
 
      //! \brief Default constructor with default values
      DtCoordConvertInitData()
      {
         coordinateType = GEOCENTRIC;
         origin = DtGeodeticCoord(0.0, 0.0, 0.0);
         offset = DtVector::zero();
         flipX = flipY = flipZ = false;
         rempapX = X;
         rempapY = Y;
         rempapZ = Z;
         useFalseEasting = false;
      }
   };
 
 
   //! \brief Default constructor
   //!
   //! Creates a coordinate converter with default settings (GEOCENTRIC coordinates)
   DtCoordinateConvert();
 
   //! \brief Virtual destructor
   virtual ~DtCoordinateConvert();
 
   //! \brief Initialize the converter with explicit settings
   //!
   //! \param data The initialization data structure containing converter settings
   virtual void init(DtCoordConvertInitData data);
 
   //! \brief Initialize the converter from a configuration table
   //!
   //! \param init A Lua configuration table containing converter settings
   virtual void init(DtInitTable& init);
 
   //! \brief Convert a position from local to geocentric coordinates
   //!
   //! \param pos The position in local coordinates
   //! \return The position in geocentric coordinates
   virtual DtVector toGeocPos(const DtVector& pos) const;
 
   //! \brief Convert a vector from local to geocentric coordinates
   //!
   //! \param vec The vector in local coordinates
   //! \param localPos The local position where the vector is applied
   //! \return The vector in geocentric coordinates
   virtual DtVector toGeocVec(const DtVector& vec, const DtVector& localPos) const;
 
   //! \brief Convert an orientation from local heading/pitch/roll to geocentric orientation
   //!
   //! \param heading The heading (yaw) angle in radians
   //! \param pitch The pitch angle in radians
   //! \param roll The roll angle in radians
   //! \param localPos The local position associated with the orientation
   //! \return The orientation in geocentric coordinates as a Tait-Bryan representation
   virtual DtTaitBryan toGeocOri(float heading, float pitch, float roll, const DtVector& localPos) const;
 
   //! \brief Convert an orientation from local to geocentric coordinates
   //!
   //! \param localOri The orientation in local coordinates
   //! \param localPos The local position associated with the orientation
   //! \return The orientation in geocentric coordinates
   virtual DtTaitBryan toGeocOri(const DtTaitBryan& localOri, const DtVector& localPos) const;
 
   //! \brief Convert a position from geocentric to local coordinates
   //!
   //! \param pos The position in geocentric coordinates
   //! \return The position in local coordinates
   virtual DtVector fromGeocPos(const DtVector& pos) const;
 
   //! \brief Convert a vector from geocentric to local coordinates
   //!
   //! \param geocVec The vector in geocentric coordinates
   //! \param geocPos The geocentric position where the vector is applied
   //! \return The vector in local coordinates
   virtual DtVector fromGeocVec(const DtVector& geocVec, const DtVector& geocPos) const;
 
   //! \brief Convert an orientation from geocentric to local coordinates
   //!
   //! \param geocOri The orientation in geocentric coordinates
   //! \param geocLoc The geocentric position associated with the orientation
   //! \return The orientation in local coordinates
   virtual DtTaitBryan fromGeocOri(const DtTaitBryan& geocOri, const DtVector& geocLoc) const;
 
   //! \brief Calculate heading from geocentric location and orientation
   //!
   //! \param geocLoc The geocentric location
   //! \param geocOri The geocentric orientation
   //! \return The heading angle in radians
   static double calcHeading(DtVector geocLoc, DtTaitBryan geocOri);
 
   //! \brief Calculate pitch from geocentric location and orientation
   //!
   //! \param geocLoc The geocentric location
   //! \param geocOri The geocentric orientation
   //! \return The pitch angle in radians
   static double calcPitch(DtVector geocLoc, DtTaitBryan geocOri);
 
   //! \brief Calculate roll from geocentric location and orientation
   //!
   //! \param geocLoc The geocentric location
   //! \param geocOri The geocentric orientation
   //! \return The roll angle in radians
   static double calcRoll(DtVector geocLoc, DtTaitBryan geocOri);
 
   //! \brief Calculate heading, pitch, and roll from geocentric location and orientation
   //!
   //! \param geocLoc The geocentric location
   //! \param geocOri The geocentric orientation
   //! \param[out] heading The calculated heading angle in radians
   //! \param[out] pitch The calculated pitch angle in radians
   //! \param[out] roll The calculated roll angle in radians
   static void calcHeadingPitchRoll(
      DtVector geocLoc, DtTaitBryan geocOri, double& heading, double& pitch, double& roll);
 
   //! \brief Calculate Tait-Bryan orientation from heading, pitch, roll and geocentric location
   //!
   //! \param heading The heading angle in radians
   //! \param pitch The pitch angle in radians
   //! \param roll The roll angle in radians
   //! \param geocLoc The geocentric location
   //! \return The Tait-Bryan orientation in geocentric coordinates
   static DtTaitBryan calcTaitBryan(double heading, double pitch, double roll, DtVector geocLoc);
 
   //! \brief returns the geodetic coordinate origin
   //! @return the geodetic coordinate. Can be zero if not using geocentric coordinate
   const DtGeodeticCoord& origin() const;
 
protected:
   //! \brief Handle axis remapping for vector conversion
   //!
   //! \param vec The input vector
   //! \param x The axis to use for X
   //! \param y The axis to use for Y
   //! \param z The axis to use for Z
   //! \return The remapped vector
   DtVector handleRemapping(const DtVector& vec, AxisType x, AxisType y, AxisType z) const;
 
   //! \brief Handle axis flipping for vector conversion
   //!
   //! \param vec The input vector
   //! \param x Whether to flip the X axis
   //! \param y Whether to flip the Y axis
   //! \param z Whether to flip the Z axis
   //! \return The flipped vector
   DtVector handleFlipping(const DtVector& vec, bool x, bool y, bool z) const;
 
   //! \brief Convert a string to a double
   //!
   //! \param str The string to convert
   //! \return The double value
   double convertToDouble(const std::string& str) const;
 
   //! \brief The current coordinate system type
   CoordinateType myCoordinateType;
 
   //! \brief Transformation from topographic to geocentric coordinates
   DtCoordTransform myTopoTransform;
 
   //! \brief Transformation from geocentric to topographic coordinates
   DtCoordTransform myInverseTopoTransform;
 
   //! \brief UTM reference point for UTM conversions
   DtUtmReferencePoint myUtmReference;
 
   //! \brief The axis to use for X in remapping
   AxisType myRemapX;
 
   //! \brief The axis to use for Y in remapping
   AxisType myRemapY;
 
   //! \brief The axis to use for Z in remapping
   AxisType myRemapZ;
 
   //! \brief Whether to flip the X axis
   bool myFlipX;
 
   //! \brief Whether to flip the Y axis
   bool myFlipY;
 
   //! \brief Whether to flip the Z axis
   bool myFlipZ;
 
   //! \brief Offset to apply to coordinates
   DtVector myOffset;
 
   //! \brief Geodetic origin (lat, lon, alt)
   DtGeodeticCoord myOrigin;
};
 
} // namespace makVre