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

// SGGeodesy 头文件
// 包含了一系列地理计算相关的函数，包括地球参数、坐标转换、距离计算等

#ifndef SGGeodesy_H
#define SGGeodesy_H

class SGGeodesy {
public:
  // Hard numbers from the WGS84 standard.
  static const double EQURAD; // 地球赤道半径
  static const double iFLATTENING; // 地球扁率
  static const double SQUASH; // 地球压缩率
  static const double STRETCH; // 地球拉伸率
  static const double POLRAD; // 地球极半径

  /// Takes a cartesian coordinate data and returns the geodetic
  /// coordinates.
  // 将ECEF坐标转换为地理坐标
  static void SGCartToGeod(const SGVec3<double>& cart, SGGeod& geod); 
  
  /// Takes a geodetic coordinate data and returns the cartesian
  /// coordinates.
  // 将地理坐标转换为ECEF坐标
  static void SGGeodToCart(const SGGeod& geod, SGVec3<double>& cart); 
  
  /// Takes a geodetic coordinate data and returns the sea level radius.
  // 根据地理坐标计算此处海平面的地球半径
  static double SGGeodToSeaLevelRadius(const SGGeod& geod); 

  /// Takes a cartesian coordinate data and returns the geocentric
  /// coordinates.
  // 将ECEF坐标转换为地心坐标
  static void SGCartToGeoc(const SGVec3<double>& cart, SGGeoc& geoc); 
  
  /// Takes a geocentric coordinate data and returns the cartesian
  /// coordinates.
  // 将地心坐标转换为ECEF坐标
  static void SGGeocToCart(const SGGeoc& geoc, SGVec3<double>& cart); 

  // Geodetic course/distance computation
  // 给定起始点地理坐标和方位角以及距离，计算目标点经纬度和目标点看起始点的方位角
  static bool direct(const SGGeod& p1, double course1,
                     double distance, SGGeod& p2, double& course2);

  /// overloaded version of above, returns new value directly, throws
  /// an sg_exception on failure.
  // 给定起始点地理坐标和方位角以及距离，计算目标点地理坐标
  static SGGeod direct(const SGGeod& p1, double course1,
                     double distance);

  // 给定起始点和目标点地理坐标，计算起始点看目标点的方位角和目标点看起始点的方位角以及距离
  static bool inverse(const SGGeod& p1, const SGGeod& p2, double& course1,
                      double& course2, double& distance);

  // 给定起始点和目标点地理坐标，计算起始点看目标点的方位角
  static double courseDeg(const SGGeod& from, const SGGeod& to);

  // 给定起始点和目标点地理坐标，计算起始点和目标点之间的距离（单位：米）
  static double distanceM(const SGGeod& from, const SGGeod& to);

  // 给定起始点和目标点地理坐标，计算起始点和目标点之间的距离（单位：海里）
  static double distanceNm(const SGGeod& from, const SGGeod& to);
    
  // Geocentric course/distance computation
  // 给定起始点地心坐标和方位角（单位：弧度）以及距离（单位：米），计算目标点地心坐标
  static void advanceRadM(const SGGeoc& geoc, double course, double distance,
                          SGGeoc& result);

  // 给定起始点地心坐标和方位角（单位：度）以及距离（单位：米），计算目标点地心坐标
  static SGGeoc advanceDegM(const SGGeoc &geoc, double course, double distance);

  // 给定起始点和目标点地心坐标，计算起始点和目标点之间的方位角（单位：弧度）
  static double courseRad(const SGGeoc& from, const SGGeoc& to);

  // 给定起始点和目标点地心坐标，计算起始点和目标点之间的距离（单位：弧度）
  static double distanceRad(const SGGeoc& from, const SGGeoc& to);

  // 给定起始点和目标点地心坐标，计算起始点和目标点之间的距离（单位：米）
  static double distanceM(const SGGeoc& from, const SGGeoc& to);
  
  /**
   * compute the intersection of two (true) radials (in degrees), or return false
   * if no intersection culd be computed.
   */
  // 给定两个点地心坐标和方位角，计算两个方向向量之间的交点
  static bool radialIntersection(const SGGeoc& a, double aRadial, 
    const SGGeoc& b, double bRadial, SGGeoc& result);

  // 给定两个点地理坐标和方位角，计算两个方向向量之间的交点
  static bool radialIntersection(const SGGeod& a, double aRadial, 
    const SGGeod& b, double bRadial, SGGeod& result);
};

#endif
