// SPDX-License-Identifier: LGPL-2.1-or-later
// SPDX-FileCopyrightText: 2006 Mathias Froehlich <mathias.froehlich@web.de>

// SGGeod 头文件
// 定义了地理坐标类SGGeod，用于表示地球上的位置 lon为经度, lat为纬度, elevation为海拔高度

#ifndef SGGeod_H
#define SGGeod_H

#include <simgear/constants.h>
#include <simgear/math/SGVec3.hxx>

// #define SG_GEOD_NATIVE_DEGREE

/// Class representing a geodetic location
class SGGeod {
public:
  /// Default constructor, initializes the instance to lat = lon = elev = 0
  SGGeod(void);

  /**
    return an SGGeod for which isValid() returns false.
    This is necessary because for historical reasons, ther default constructor above initialises to zero,zero,zero
    which *is*
   */
  // 返回一个无效的SGGeod对象，用于表示无效的地理坐标
  static SGGeod invalid();

  /// Factory from angular values in radians and elevation is 0
  // 工厂方法：从弧度值创建实例, 海拔高度为0
  static SGGeod fromRad(double lon, double lat);
  /// Factory from angular values in degrees and elevation is 0
  // 工厂方法：从角度值创建实例, 海拔高度为0
  static SGGeod fromDeg(double lon, double lat);
  /// Factory from angular values in radians and elevation in ft
  // 工厂方法：从弧度值和海拔高度（单位：英尺）创建实例
  static SGGeod fromRadFt(double lon, double lat, double elevation);
  /// Factory from angular values in degrees and elevation in ft
  // 工厂方法：从角度值和海拔高度（单位：英尺）创建实例
  static SGGeod fromDegFt(double lon, double lat, double elevation);
  /// Factory from angular values in radians and elevation in m
  // 工厂方法：从弧度值和海拔高度（单位：米）创建实例
  static SGGeod fromRadM(double lon, double lat, double elevation);
  /// Factory from angular values in degrees and elevation in m
  // 工厂方法：从角度值和海拔高度（单位：米）创建实例
  static SGGeod fromDegM(double lon, double lat, double elevation);
  /// Factory from an other SGGeod and a different elevation in m
  // 工厂方法：从另一个地理坐标和不同的海拔高度（单位：米）创建实例
  static SGGeod fromGeodM(const SGGeod& geod, double elevation);
  /// Factory from an other SGGeod and a different elevation in ft
  // 工厂方法：从另一个地理坐标和不同的海拔高度（单位：英尺）创建实例
  static SGGeod fromGeodFt(const SGGeod& geod, double elevation);
  /// Factory to convert position from a cartesian position assumed to be
  /// in wgs84 measured in meters
  /// Note that this conversion is relatively expensive to compute
  // 工厂方法：从ECEF坐标（单位：米）创建实例, 使用WGS84坐标系, 注意这个转换耗时较长
  static SGGeod fromCart(const SGVec3<double>& cart);
  /// Factory to convert position from a geocentric position
  /// Note that this conversion is relatively expensive to compute
  // 工厂方法：从地心坐标创建实例, 注意这个转换耗时较长
  static SGGeod fromGeoc(const SGGeoc& geoc);

  /// Return the geodetic longitude in radians
  // 返回经度（单位：弧度）
  double getLongitudeRad(void) const;
  /// Set the geodetic longitude from the argument given in radians
  // 设置经度（单位：弧度）
  void setLongitudeRad(double lon);

  /// Return the geodetic longitude in degrees
  // 返回经度（单位：度）
  double getLongitudeDeg(void) const;
  /// Set the geodetic longitude from the argument given in degrees
  // 设置经度（单位：度）
  void setLongitudeDeg(double lon);

  /// Return the geodetic latitude in radians
  // 返回纬度（单位：弧度）
  double getLatitudeRad(void) const;
  /// Set the geodetic latitude from the argument given in radians
  // 设置纬度（单位：弧度）
  void setLatitudeRad(double lat);

  /// Return the geodetic latitude in degrees
  // 返回纬度（单位：度）
  double getLatitudeDeg(void) const;
  /// Set the geodetic latitude from the argument given in degrees
  // 设置纬度（单位：度）
  void setLatitudeDeg(double lat);

  /// Return the geodetic elevation in meters
  // 返回海拔高度（单位：米）
  double getElevationM(void) const;
  /// Set the geodetic elevation from the argument given in meters
  // 设置海拔高度（单位：米）
  void setElevationM(double elevation);

  /// Return the geodetic elevation in feet
  // 返回海拔高度（单位：英尺）
  double getElevationFt(void) const;
  /// Set the geodetic elevation from the argument given in feet
  // 设置海拔高度（单位：英尺）
  void setElevationFt(double elevation);

  /// Compare two geodetic positions for equality
  // 比较两个地理坐标是否相等
  bool operator == ( const SGGeod & other ) const;

  /// check the Geod contains sane values (finite, inside appropriate
  /// ranges for lat/lon)
  // 检查地理坐标是否包含合理的值（有限、在适当的范围内）
  bool isValid() const;
private:
  /// This one is private since construction is not unique if you do
  /// not know the units of the arguments. Use the factory methods for
  /// that purpose
  // 私有构造函数，因为构造函数不是唯一的，如果不知道参数的单位，请使用工厂方法
  SGGeod(double lon, double lat, double elevation);

  //// FIXME: wrong comment!
  /// The actual data, angles in degrees, elevation in meters
  /// The rationale for storing the values in degrees is that most code places
  /// in flightgear/terragear use degrees as a native input and output value.
  /// The places where it makes sense to use radians is when we convert
  /// to other representations or compute rotation matrices. But both tasks
  /// are computationally intensive anyway and that additional 'toRadian'
  /// conversion does not hurt too much
  // 实际数据：角度以度为单位，海拔高度以米为单位
  // 选择以度为单位存储值的原因是，flightgear/terragear中的大多数代码
  // 都使用度作为原生的输入和输出值。
  // 使用弧度更有意义的情况是在我们进行坐标转换
  /// 或计算旋转矩阵时。但这两项任务本身计算量就很大，
  /// 所以额外的"转换为弧度"操作并不会造成太大影响
  double _lon;
  double _lat;
  double _elevation;  // 海拔高度
};

inline
SGGeod::SGGeod(void) :
  _lon(0), _lat(0), _elevation(0)
{
}

inline
SGGeod::SGGeod(double lon, double lat, double elevation) :
  _lon(lon), _lat(lat), _elevation(elevation)
{
}

inline
SGGeod
SGGeod::fromRad(double lon, double lat)
{
#ifdef SG_GEOD_NATIVE_DEGREE
  return SGGeod(lon*SGD_RADIANS_TO_DEGREES, lat*SGD_RADIANS_TO_DEGREES, 0);
#else
  return SGGeod(lon, lat, 0);
#endif
}

inline
SGGeod
SGGeod::fromDeg(double lon, double lat)
{
#ifdef SG_GEOD_NATIVE_DEGREE
  return SGGeod(lon, lat, 0);
#else
  return SGGeod(lon*SGD_DEGREES_TO_RADIANS, lat*SGD_DEGREES_TO_RADIANS, 0);
#endif
}

inline
SGGeod
SGGeod::fromRadFt(double lon, double lat, double elevation)
{
#ifdef SG_GEOD_NATIVE_DEGREE
  return SGGeod(lon*SGD_RADIANS_TO_DEGREES, lat*SGD_RADIANS_TO_DEGREES,
                elevation*SG_FEET_TO_METER);
#else
  return SGGeod(lon, lat, elevation*SG_FEET_TO_METER);
#endif
}

inline
SGGeod
SGGeod::fromDegFt(double lon, double lat, double elevation)
{
#ifdef SG_GEOD_NATIVE_DEGREE
  return SGGeod(lon, lat, elevation*SG_FEET_TO_METER);
#else
  return SGGeod(lon*SGD_DEGREES_TO_RADIANS, lat*SGD_DEGREES_TO_RADIANS,
                elevation*SG_FEET_TO_METER);
#endif
}

inline
SGGeod
SGGeod::fromRadM(double lon, double lat, double elevation)
{
#ifdef SG_GEOD_NATIVE_DEGREE
  return SGGeod(lon*SGD_RADIANS_TO_DEGREES, lat*SGD_RADIANS_TO_DEGREES,
                elevation);
#else
  return SGGeod(lon, lat, elevation);
#endif
}

inline
SGGeod
SGGeod::fromDegM(double lon, double lat, double elevation)
{
#ifdef SG_GEOD_NATIVE_DEGREE
  return SGGeod(lon, lat, elevation);
#else
  return SGGeod(lon*SGD_DEGREES_TO_RADIANS, lat*SGD_DEGREES_TO_RADIANS,
                elevation);
#endif
}

inline
SGGeod
SGGeod::fromGeodM(const SGGeod& geod, double elevation)
{
  return SGGeod(geod._lon, geod._lat, elevation);
}

inline
SGGeod
SGGeod::fromGeodFt(const SGGeod& geod, double elevation)
{
  return SGGeod(geod._lon, geod._lat, elevation*SG_FEET_TO_METER);
}

inline
SGGeod
SGGeod::fromCart(const SGVec3<double>& cart)
{
  SGGeod geod;
  SGGeodesy::SGCartToGeod(cart, geod);
  return geod;
}

inline
SGGeod
SGGeod::fromGeoc(const SGGeoc& geoc)
{
  SGVec3<double> cart;
  SGGeodesy::SGGeocToCart(geoc, cart);
  SGGeod geod;
  SGGeodesy::SGCartToGeod(cart, geod);
  return geod;
}

inline
double
SGGeod::getLongitudeRad(void) const
{
#ifdef SG_GEOD_NATIVE_DEGREE
  return _lon*SGD_DEGREES_TO_RADIANS;
#else
  return _lon;
#endif
}

inline
void
SGGeod::setLongitudeRad(double lon)
{
#ifdef SG_GEOD_NATIVE_DEGREE
  _lon = lon*SGD_RADIANS_TO_DEGREES;
#else
  _lon = lon;
#endif
}

inline
double
SGGeod::getLongitudeDeg(void) const
{
#ifdef SG_GEOD_NATIVE_DEGREE
  return _lon;
#else
  return _lon*SGD_RADIANS_TO_DEGREES;
#endif
}

inline
void
SGGeod::setLongitudeDeg(double lon)
{
#ifdef SG_GEOD_NATIVE_DEGREE
  _lon = lon;
#else
  _lon = lon*SGD_DEGREES_TO_RADIANS;
#endif
}

inline
double
SGGeod::getLatitudeRad(void) const
{
#ifdef SG_GEOD_NATIVE_DEGREE
  return _lat*SGD_DEGREES_TO_RADIANS;
#else
  return _lat;
#endif
}

inline
void
SGGeod::setLatitudeRad(double lat)
{
#ifdef SG_GEOD_NATIVE_DEGREE
  _lat = lat*SGD_RADIANS_TO_DEGREES;
#else
  _lat = lat;
#endif
}

inline
double
SGGeod::getLatitudeDeg(void) const
{
#ifdef SG_GEOD_NATIVE_DEGREE
  return _lat;
#else
  return _lat*SGD_RADIANS_TO_DEGREES;
#endif
}

inline
void
SGGeod::setLatitudeDeg(double lat)
{
#ifdef SG_GEOD_NATIVE_DEGREE
  _lat = lat;
#else
  _lat = lat*SGD_DEGREES_TO_RADIANS;
#endif
}

inline
double
SGGeod::getElevationM(void) const
{
  return _elevation;
}

inline
void
SGGeod::setElevationM(double elevation)
{
  _elevation = elevation;
}

inline
double
SGGeod::getElevationFt(void) const
{
  return _elevation*SG_METER_TO_FEET;
}

inline
void
SGGeod::setElevationFt(double elevation)
{
  _elevation = elevation*SG_FEET_TO_METER;
}

inline
bool
SGGeod::operator == ( const SGGeod & other ) const
{
  return _lon == other._lon &&
         _lat == other._lat &&
         _elevation == other._elevation;
}

inline
bool
SGGeod::isValid() const
{
  if (SGMiscd::isNaN(_lon))
      return false;
  if (SGMiscd::isNaN(_lat))
      return false;
#ifdef SG_GEOD_NATIVE_DEGREE
  return (_lon >= -180.0) && (_lon <= 180.0) &&
  (_lat >= -90.0) && (_lat <= 90.0);
#else
  return (_lon >= -SGD_PI) && (_lon <= SGD_PI) &&
  (_lat >= -SGD_PI_2) && (_lat <= SGD_PI_2);
#endif
}

/// Output to an ostream
template<typename char_type, typename traits_type>
inline
std::basic_ostream<char_type, traits_type>&
operator<<(std::basic_ostream<char_type, traits_type>& s, const SGGeod& g)
{
  return s << "lon = " << g.getLongitudeDeg()
           << "deg, lat = " << g.getLatitudeDeg()
           << "deg, elev = " << g.getElevationM()
           << "m";
}

#endif
