Spherical offset positions

.settings/language.settings.xml

@@ -5,7 +5,7 @@
 			<provider copy-of="extension" id="org.eclipse.cdt.ui.UserLanguageSettingsProvider"/>
 			<provider-reference id="org.eclipse.cdt.core.ReferencedProjectsLanguageSettingsProvider" ref="shared-provider"/>
 			<provider copy-of="extension" id="org.eclipse.cdt.managedbuilder.core.GCCBuildCommandParser"/>
-			<provider class="org.eclipse.cdt.managedbuilder.language.settings.providers.GCCBuiltinSpecsDetector" console="false" env-hash="-1563840017389652703" id="org.eclipse.cdt.managedbuilder.core.GCCBuiltinSpecsDetector" keep-relative-paths="false" name="CDT GCC Built-in Compiler Settings" parameter="${COMMAND} ${FLAGS} -E -P -v -dD &quot;${INPUTS}&quot;" prefer-non-shared="true">
+			<provider class="org.eclipse.cdt.managedbuilder.language.settings.providers.GCCBuiltinSpecsDetector" console="false" env-hash="-1563587762567252703" id="org.eclipse.cdt.managedbuilder.core.GCCBuiltinSpecsDetector" keep-relative-paths="false" name="CDT GCC Built-in Compiler Settings" parameter="${COMMAND} ${FLAGS} -E -P -v -dD &quot;${INPUTS}&quot;" prefer-non-shared="true">
 				<language-scope id="org.eclipse.cdt.core.gcc"/>
 				<language-scope id="org.eclipse.cdt.core.g++"/>
 			</provider>

include/novas.h

@@ -3384,6 +3384,16 @@ int novas_icrs_to_sys(const double *in, double jd_tdb, enum novas_accuracy accur
 int novas_sys_to_icrs(enum novas_reference_system sys, const double *in, double jd_tdb, enum novas_accuracy accuracy, double *out);
 
 
+// ---------------------- Added in 1.6.0 -------------------------
+
+// in util.c
+/// @c_util
+int novas_offset_by(double lon, double lat, double direction, double distance, double *restrict out_lon, double *restrict out_lat);
+
+/// @c_util
+int novas_equ_offset_by(double ra, double dec, double direction, double distance, double *restrict out_ra, double *restrict out_dec);
+
+
 // <================= END of SuperNOVAS API =====================>
 
 

include/supernovas.h

@@ -1030,6 +1030,10 @@ class Equatorial : public Spherical {
 
   Angle distance_to(const Equatorial& other) const;
 
+  Equatorial offset(double direction_rad, double distance_rad) const;
+
+  Equatorial offset( const Angle& direction, const Angle& distance) const;
+
   Equatorial to_system(const Equinox& system, enum novas_accuracy accuracy = NOVAS_FULL_ACCURACY) const;
 
   Equatorial to_icrs() const;
@@ -1106,6 +1110,10 @@ class Ecliptic : public Spherical {
 
   Angle distance_to(const Ecliptic& other) const;
 
+  Ecliptic offset(double direction_rad, double distance_rad) const;
+
+  Ecliptic offset(const Angle& direction, const Angle& distance) const;
+
   Ecliptic to_system(const Equinox& system, enum novas_accuracy accuracy = NOVAS_FULL_ACCURACY) const;
 
   Ecliptic to_icrs() const;
@@ -1159,6 +1167,10 @@ class Galactic : public Spherical {
 
   Angle distance_to(const Galactic& other) const;
 
+  Galactic offset(double direction_rad, double distance_rad) const;
+
+  Galactic offset(const Angle& direction, const Angle& distance) const;
+
   /// @ingroup equatorial
   Equatorial to_equatorial() const;
 
@@ -2654,6 +2666,10 @@ class Horizontal : public Spherical {
 
   Angle distance_to(const Horizontal& other) const;
 
+  Horizontal offset(double direction_rad, double distance_rad) const;
+
+  Horizontal offset(const Angle& direction, const Angle& distance) const;
+
   const Angle& azimuth() const;
 
   const Angle& elevation() const;

src/c99/util.c

@@ -715,6 +715,7 @@ double d_light(const double *pos_src, const double *pos_body) {
  * @author Attila Kovacs
  *
  * @sa novas_equ_sep(), novas_sun_angle(), novas_moon_angle()
+ * @sa novas_offset_by()
  */
 double novas_sep(double lon1, double lat1, double lon2, double lat2) {
   const double cp1 = cos(lat1 * DEGREE);
@@ -742,6 +743,7 @@ double novas_sep(double lon1, double lat1, double lon2, double lat2) {
  * @author Attila Kovacs
  *
  * @sa novas_sep(), novas_sun_angle(), novas_moon_angle()
+ * @sa novas_equ_offset_by()
  */
 double novas_equ_sep(double ra1, double dec1, double ra2, double dec2) {
   return novas_sep(15.0 * ra1, dec1, 15.0 * ra2, dec2);
@@ -971,3 +973,119 @@ int novas_print_dms(double degrees, enum novas_separator_type sep, int decimals,
   return strlen(buf);
 }
 
+/**
+ * Calculates offset spherical coordinates at some distance away from the input coordinates along
+ * a great circle which crosses the input position at the specified direction. Based on the
+ * __astropy__ `offset_by()` implementation.
+ *
+ * @param lon             [deg] reference point longitude
+ * @param lat             [deg] reference point latitude
+ * @param direction       [deg] direction (measured East of North).
+ * @param distance        [deg] offset distance on great circle
+ * @param[out] out_lon    [deg] longitude at offset position in [-&pi:π) range. It may be NULL
+ *                        if not needed.
+ * @param[out] out_lat    [deg] latitude at offset position in [-&pi/2:π/2] range. It may be
+ *                        NULL if not needed.
+ * @return                0 if successful, or else -1 if very close to the pole, and longitude at
+ *                        the offset position is requested, or if the input latitude is outside of
+ *                        the [-90:90] range.
+ *
+ * @since 1.7
+ * @sa Attila Kovacs
+ *
+ * @sa novas_equ_offset_by(), novas_sep()
+ * @sa https://docs.astropy.org/en/stable/_modules/astropy/coordinates/angles/utils.html#offset_at
+ */
+int novas_offset_by(double lon, double lat, double direction, double distance, double *restrict out_lon, double *restrict out_lat) {
+  static const char *fn = "novas_offset_by";
+
+  const double eps = 1e-12;  // precision tolerance around poles
+  double clat, slat, cD, sD_clat, cb;
+
+  if(fabs(lat) > 90.0 + eps)
+    return novas_error(-1, EINVAL, fn, "latitude is outside of the [-90:90] range.");
+
+  if(distance == 0.0) {
+    // not offset at all...
+    if(out_lon)
+      *out_lon = lon;
+    if(out_lat)
+      *out_lat = lat;
+    return 0;
+  }
+
+  clat = cos(lat * DEGREE);
+
+  if(fabs(clat) < eps) {
+    // Very close to the pole, longitude is undefined, but latitude can be determined
+    // assuming that we start exactly from the pole.
+    if(out_lat) {
+      *out_lat = remainder(90.0 - distance, DEG360);
+
+      // wrap as needed...
+      if(*out_lat > 90.0)
+        *out_lat = 180.0 - *out_lat;
+      else if(*out_lat < -90.0)
+        *out_lat = -180.0 - *out_lat;
+    }
+
+    if(out_lon) {
+      *out_lon = NAN;
+      return novas_error(-1, EDOM, fn, "longitude is undefined at the poles");
+    }
+
+    return 0;
+  }
+
+  slat = sin(lat * DEGREE);
+  cD = cos(distance * DEGREE);
+  sD_clat = sin(distance * DEGREE) * clat;
+  cb = slat * cD + sD_clat * cos(direction * DEGREE);
+
+  if(out_lon) {
+    double dlon = atan2(sD_clat * sin(direction * DEGREE), cD - cb * slat) / DEGREE;
+    *out_lon = remainder(lon + dlon, DEG360);
+  }
+
+  if(out_lat)
+    *out_lat = asin(cb) / DEGREE;
+
+  return 0;
+}
+
+/**
+ * Calculates offset equatorial coordinates at some distance away from the input coordinates along
+ * a great circle which crosses the input position at the specified position angle.
+ *
+ * @param ra              [deg] reference point right ascention (R.A.)
+ * @param dec             [deg] reference point declination
+ * @param direction       [deg] direction (measured East of North).
+ * @param distance        [deg] offset distance on great circle
+ * @param[out] out_ra     [deg] right ascention (R.A.) at offset position in [0:24) range. It may
+ *                        be NULL if not needed.
+ * @param[out] out_dec    [deg] declination at offset position in [-&pi/2:&pi;/2] range. It may be
+ *                        NULL if not needed.
+ * @return                0 if successful, or else -1 if very close to the pole, and right
+ *                        ascention (R.A.) at the offset position is requested, or if the
+ *                        input declination is outside of the [-90:90] range.
+ *
+ * @since 1.7
+ * @sa Attila Kovacs
+ *
+ * @sa novas_offset_by(), novas_equ_sep()
+ */
+int novas_equ_offset_by(double ra, double dec, double direction, double distance, double *restrict out_ra, double *restrict out_dec) {
+  double out_lon = NAN;
+
+  int status = novas_offset_by(15.0 * ra, dec, direction, distance, &out_lon, out_dec);
+
+  if(out_lon < 0.0)
+    out_lon += DEG360;
+
+  if(out_ra)
+    *out_ra = out_lon / 15.0;
+
+  prop_error("novas_equ_offset", status, 0);
+
+  return 0;
+}

src/cpp/Ecliptic.cpp

@@ -253,6 +253,8 @@ Equinox Ecliptic::system() const {
  * @return        the angular distance of these coordinates to/from the argument.
  *
  * @since 1.6
+ *
+ * @sa offset_by()
  */
 Angle Ecliptic::distance_to(const Ecliptic& other) const {
   Angle a = Spherical::distance_to(other >> system());
@@ -261,6 +263,43 @@ Angle Ecliptic::distance_to(const Ecliptic& other) const {
   return a;
 }
 
+/**
+ * Returns ecliptic coordinates for an offset position from these along the great circle that
+ * crosses these coordinates in the speciifed direction.
+ *
+ * @param direction_rad   [rad] offset direction, measured East of the local ecliptic North.
+ * @param distance_rad    [rad] offset great circle distance.
+ * @return                The ecliptic coordinates of the offset position
+ *
+ * @since 1.7
+ *
+ * @sa distance_to(), Equatorial::offset(), Galactic::offset(), Horizontal::offset()
+ */
+Ecliptic Ecliptic::offset(double direction_rad, double distance_rad) const {
+  double lon = NAN, lat = NAN;
+  novas_offset_by(longitude().deg(), latitude().deg(), direction_rad / Unit::deg, distance_rad / Unit::deg, &lon, &lat);
+  Ecliptic e(lon * Unit::deg, lat * Unit::deg, system());
+  if(!e.is_valid())
+    novas_trace_invalid("Ecliptic::offset()");
+  return e;
+}
+
+/**
+ * Returns ecliptic coordinates for an offset position from these along the great circle that
+ * crosses these coordinates in the speciifed direction.
+ *
+ * @param direction   offset direction, measured East of the local ecliptic North.
+ * @param distance    offset great circle distance.
+ * @return            The ecliptic coordinates of the offset position
+ *
+ * @since 1.7
+ *
+ * @sa distance_to(), Equatorial::offset(), Galactic::offset(), Horizontal::offset()
+ */
+Ecliptic Ecliptic::offset(const Angle& direction, const Angle& distance) const {
+  return offset(direction.rad(), distance.rad());
+}
+
 /**
  * Converts these ecliptic coordinates to the ecliptic coordinate system with respect to the
  * specified equinox of date.

src/cpp/Equatorial.cpp

@@ -214,6 +214,8 @@ enum novas_reference_system Equatorial::system_type() const {
  * @return        the angular distance of thereturn Angle::operator+(r);se coordinates to/from the argument.
  *
  * @since 1.6
+ *
+ * @sa offset_by()
  */
 Angle Equatorial::distance_to(const Equatorial& other) const {
   Angle a = Spherical::distance_to(other >> _sys);
@@ -222,6 +224,45 @@ Angle Equatorial::distance_to(const Equatorial& other) const {
   return a;
 }
 
+/**
+ * Returns equatorial coordinates for an offset position from these along the great circle that
+ * crosses these coordinates in the speciifed direction.
+ *
+ * @param direction_rad   [rad] offset direction, measured East of the local North.
+ * @param distance_rad    [rad] offset great circle distance.
+ *
+ * @return                The equatorial coordinates of the offset position
+ *
+ * @since 1.7
+ *
+ * @sa distance_to(), Ecliptic::offset(), Galactic::offset(), Horizontal::offset()
+ */
+Equatorial Equatorial::offset(double direction_rad, double distance_rad) const {
+  double lon = NAN, lat = NAN;
+  novas_offset_by(ra().deg(), dec().deg(), direction_rad / Unit::deg, distance_rad / Unit::deg, &lon, &lat);
+  Equatorial e(lon * Unit::deg, lat * Unit::deg, system());
+  if(!e.is_valid())
+    novas_trace_invalid("Equatorial::offset()");
+  return e;
+}
+
+/**
+ * Returns equatorial coordinates for an offset position from these along the great circle that
+ * crosses these coordinates in the speciifed direction.
+ *
+ * @param direction   offset direction, measured East of the local North.
+ * @param distance    offset great circle distance.
+ *
+ * @return            The equatorial coordinates of the offset position
+ *
+ * @since 1.7
+ *
+ * @sa distance_to(), Ecliptic::offset(), Galactic::offset(), Horizontal::offset()
+ */
+Equatorial Equatorial::offset(const Angle& direction, const Angle& distance) const {
+  return offset(direction.rad(), distance.rad());
+}
+
 /**
  * Converts these equatorial coordinates to another equatorial coordinate system.
  *

src/cpp/Galactic.cpp

@@ -150,6 +150,8 @@ bool Galactic::operator!=(const Galactic& other) const {
  * @return        the angular distance of these coordinates to/from the argument.
  *
  * @since 1.6
+ *
+ * @sa offset_by()
  */
 Angle Galactic::distance_to(const Galactic& other) const {
   Angle a = Spherical::distance_to(other);
@@ -158,6 +160,43 @@ Angle Galactic::distance_to(const Galactic& other) const {
   return a;
 }
 
+/**
+ * Returns galactic coordinates for an offset position from these along the great circle that
+ * crosses these coordinates in the speciifed direction.
+ *
+ * @param direction_rad   [rad] offset direction, measured East of the local galactic North.
+ * @param distance_rad    [rad] offset great circle distance.
+ * @return                The galactic coordinates of the offset position
+ *
+ * @since 1.7
+ *
+ * @sa distance_to(), Equatorial::offset(), Ecliptic::offset(), Horizontal::offset()
+ */
+Galactic Galactic::offset(double direction_rad, double distance_rad) const {
+  double lon = NAN, lat = NAN;
+  novas_offset_by(longitude().deg(), latitude().deg(), direction_rad / Unit::deg, distance_rad / Unit::deg, &lon, &lat);
+  Galactic g(lon * Unit::deg, lat * Unit::deg);
+  if(!g.is_valid())
+    novas_trace_invalid("Galactic::offset()");
+  return g;
+}
+
+/**
+ * Returns galactic coordinates for an offset position from these along the great circle that
+ * crosses these coordinates in the speciifed direction.
+ *
+ * @param direction   offset direction, measured East of the local galactic North.
+ * @param distance    offset great circle distance.
+ * @return            The galactic coordinates of the offset position
+ *
+ * @since 1.7
+ *
+ * @sa distance_to(), Equatorial::offset(), Ecliptic::offset(), Horizontal::offset()
+ */
+Galactic Galactic::offset(const Angle& direction, const Angle& distance) const {
+  return offset(direction.rad(), distance.rad());
+}
+
 /**
  * Converts these galactic coordinates to equivalent ICRS equatorial coordinates.
  *