Light travel correction: improved documentation.

demo/browser/astronomy.browser.js

@@ -3651,6 +3651,10 @@ exports.PositionFunction = PositionFunction;
  * For common use cases, it is simpler to use {@link BackdatePosition}
  * for calculating the light travel time correction of one body observing another body.
  *
+ * For geocentric calculations, {@link GeoVector} also backdates the returned
+ * position vector for light travel time, only it returns the observation time in
+ * the returned vector's `t` field rather than the backdated time.
+ *
  * @param {PositionFunction} func
  *      An arbitrary position vector as a function of time.
  *
@@ -3722,6 +3726,12 @@ class BodyPosition extends PositionFunction {
  * relative position vector of a target body as seen by an observer body
  * at a given observation time.
  *
+ * For geocentric calculations, {@link GeoVector} also includes light
+ * travel time correction, but the time `t` embedded in its returned vector
+ * refers to the observation time, not the backdated time that light left
+ * the observed body. Thus `BackdatePosition` provides direct
+ * access to the light departure time for callers that need it.
+ *
  * For a more generalized light travel correction solver, see {@link CorrectLightTravel}.
  *
  * @param {FlexibleDateTime} date

demo/nodejs/astronomy.js

@@ -3650,6 +3650,10 @@ exports.PositionFunction = PositionFunction;
  * For common use cases, it is simpler to use {@link BackdatePosition}
  * for calculating the light travel time correction of one body observing another body.
  *
+ * For geocentric calculations, {@link GeoVector} also backdates the returned
+ * position vector for light travel time, only it returns the observation time in
+ * the returned vector's `t` field rather than the backdated time.
+ *
  * @param {PositionFunction} func
  *      An arbitrary position vector as a function of time.
  *
@@ -3721,6 +3725,12 @@ class BodyPosition extends PositionFunction {
  * relative position vector of a target body as seen by an observer body
  * at a given observation time.
  *
+ * For geocentric calculations, {@link GeoVector} also includes light
+ * travel time correction, but the time `t` embedded in its returned vector
+ * refers to the observation time, not the backdated time that light left
+ * the observed body. Thus `BackdatePosition` provides direct
+ * access to the light departure time for callers that need it.
+ *
  * For a more generalized light travel correction solver, see {@link CorrectLightTravel}.
  *
  * @param {FlexibleDateTime} date

demo/nodejs/calendar/astronomy.ts

@@ -4064,6 +4064,10 @@ export abstract class PositionFunction {
  * For common use cases, it is simpler to use {@link BackdatePosition}
  * for calculating the light travel time correction of one body observing another body.
  *
+ * For geocentric calculations, {@link GeoVector} also backdates the returned
+ * position vector for light travel time, only it returns the observation time in
+ * the returned vector's `t` field rather than the backdated time.
+ *
  * @param {PositionFunction} func
  *      An arbitrary position vector as a function of time.
  *
@@ -4144,6 +4148,12 @@ class BodyPosition extends PositionFunction {
  * relative position vector of a target body as seen by an observer body
  * at a given observation time.
  *
+ * For geocentric calculations, {@link GeoVector} also includes light
+ * travel time correction, but the time `t` embedded in its returned vector
+ * refers to the observation time, not the backdated time that light left
+ * the observed body. Thus `BackdatePosition` provides direct
+ * access to the light departure time for callers that need it.
+ *
  * For a more generalized light travel correction solver, see {@link CorrectLightTravel}.
  *
  * @param {FlexibleDateTime} date

demo/python/astronomy.py

@@ -4477,6 +4477,10 @@ def CorrectLightTravel(func, time):
     For common use cases, it is simpler to use #BackdatePosition
     for calculating the light travel time correction of one body observing another body.
 
+    For geocentric calculations, #GeoVector also backdates the returned
+    position vector for light travel time, only it returns the observation time in
+    the returned vector's `t` field rather than the backdated time.
+
     Parameters
     ----------
     func : PositionFunction
@@ -4548,6 +4552,12 @@ def BackdatePosition(time, observerBody, targetBody, aberration):
     relative position vector of a target body as seen by an observer body
     at a given observation time.
 
+    For geocentric calculations, #GeoVector also includes light
+    travel time correction, but the time `t` embedded in its returned vector
+    refers to the observation time, not the backdated time that light left
+    the observed body. Thus `BackdatePosition` provides direct
+    access to the light departure time for callers that need it.
+
     For a more generalized light travel correction solver, see #CorrectLightTravel.
 
     Parameters

generate/template/astronomy.c

@@ -3772,6 +3772,10 @@ astro_func_result_t Astronomy_HelioDistance(astro_body_t body, astro_time_t time
  * For common use cases, it is simpler to use #Astronomy_BackdatePosition
  * for calculating the light travel time correction of one body observing another body.
  *
+ * For geocentric calculations, #Astronomy_GeoVector also backdates the returned
+ * position vector for light travel time, only it returns the observation time in
+ * the returned vector's `t` field rather than the backdated time.
+ *
  * @param context   Holds any parameters needed by `func`.
  * @param func      Pointer to a function that returns a relative position vector as a function of time.
  * @param time      The observation time for which to solve for light travel delay.
@@ -3881,6 +3885,12 @@ static astro_vector_t BodyPosition(void *context, astro_time_t time)
  * relative position vector of a target body as seen by an observer body
  * at a given observation time.
  *
+ * For geocentric calculations, #Astronomy_GeoVector also includes light
+ * travel time correction, but the time `t` embedded in its returned vector
+ * refers to the observation time, not the backdated time that light left
+ * the observed body. Thus `Astronomy_BackdatePosition` provides direct
+ * access to the light departure time for callers that need it.
+ *
  * For a more generalized light travel correction solver, see #Astronomy_CorrectLightTravel.
  *
  * @param time          The time of observation.

generate/template/astronomy.cs

@@ -4345,6 +4345,11 @@ private static AstroVector CalcEarth(AstroTime time)
         ///
         /// For common use cases, it is simpler to use #Astronomy.BackdatePosition
         /// for calculating the light travel time correction of one body observing another body.
+        ///
+        /// For geocentric calculations, #Astronomy.GeoVector also backdates the returned
+        /// position vector for light travel time, only it returns the observation time in
+        /// the returned vector's `t` field rather than the backdated time.
+        ///
         /// </remarks>
         /// <param name="func">An arbitrary position vector as a function of time.</param>
         /// <param name="time">The observation time for which to solve for light travel delay.</param>
@@ -4430,6 +4435,12 @@ public AstroVector Position(AstroTime time)
         /// relative position vector of a target body as seen by an observer body
         /// at a given observation time.
         ///
+        /// For geocentric calculations, #Astronomy.GeoVector also includes light
+        /// travel time correction, but the time `t` embedded in its returned vector
+        /// refers to the observation time, not the backdated time that light left
+        /// the observed body. Thus `BackdatePosition` provides direct
+        /// access to the light departure time for callers that need it.
+        ///
         /// For a more generalized light travel correction solver, see #Astronomy.CorrectLightTravel.
         /// </remarks>
         /// <param name="time">The time of observation.</param>

generate/template/astronomy.kt

@@ -4815,6 +4815,10 @@ fun interface PositionFunction {
  * For common use cases, it is simpler to use [backdatePosition]
  * for calculating the light travel time correction of one body observing another body.
  *
+ * For geocentric calculations, #geoVector also backdates the returned
+ * position vector for light travel time, only it returns the observation time in
+ * the returned vector's `t` field rather than the backdated time.
+ *
  * @param func
  * An arbitrary position vector as a function of time.
  *
@@ -4890,6 +4894,12 @@ internal class BodyPosition(
  * relative position vector of a target body as seen by an observer body
  * at a given observation time.
  *
+ * For geocentric calculations, #geoVector also includes light
+ * travel time correction, but the time `t` embedded in its returned vector
+ * refers to the observation time, not the backdated time that light left
+ * the observed body. Thus `backdatePosition` provides direct
+ * access to the light departure time for callers that need it.
+ *
  * For a more generalized light travel correction solver, see [correctLightTravel].
  *
  * @param time

generate/template/astronomy.py

@@ -2435,6 +2435,10 @@ def CorrectLightTravel(func, time):
     For common use cases, it is simpler to use #BackdatePosition
     for calculating the light travel time correction of one body observing another body.
 
+    For geocentric calculations, #GeoVector also backdates the returned
+    position vector for light travel time, only it returns the observation time in
+    the returned vector's `t` field rather than the backdated time.
+
     Parameters
     ----------
     func : PositionFunction
@@ -2506,6 +2510,12 @@ def BackdatePosition(time, observerBody, targetBody, aberration):
     relative position vector of a target body as seen by an observer body
     at a given observation time.
 
+    For geocentric calculations, #GeoVector also includes light
+    travel time correction, but the time `t` embedded in its returned vector
+    refers to the observation time, not the backdated time that light left
+    the observed body. Thus `BackdatePosition` provides direct
+    access to the light departure time for callers that need it.
+
     For a more generalized light travel correction solver, see #CorrectLightTravel.
 
     Parameters

generate/template/astronomy.ts

@@ -3058,6 +3058,10 @@ export abstract class PositionFunction {
  * For common use cases, it is simpler to use {@link BackdatePosition}
  * for calculating the light travel time correction of one body observing another body.
  *
+ * For geocentric calculations, {@link GeoVector} also backdates the returned
+ * position vector for light travel time, only it returns the observation time in
+ * the returned vector's `t` field rather than the backdated time.
+ *
  * @param {PositionFunction} func
  *      An arbitrary position vector as a function of time.
  *
@@ -3138,6 +3142,12 @@ class BodyPosition extends PositionFunction {
  * relative position vector of a target body as seen by an observer body
  * at a given observation time.
  *
+ * For geocentric calculations, {@link GeoVector} also includes light
+ * travel time correction, but the time `t` embedded in its returned vector
+ * refers to the observation time, not the backdated time that light left
+ * the observed body. Thus `BackdatePosition` provides direct
+ * access to the light departure time for callers that need it.
+ *
  * For a more generalized light travel correction solver, see {@link CorrectLightTravel}.
  *
  * @param {FlexibleDateTime} date

source/c/README.md

@@ -297,6 +297,8 @@ When observing a distant object, for example Jupiter as seen from Earth, the amo
 
 This function solves the light travel time correction for the apparent relative position vector of a target body as seen by an observer body at a given observation time.
 
+For geocentric calculations, [`Astronomy_GeoVector`](#Astronomy_GeoVector) also includes light travel time correction, but the time `t` embedded in its returned vector refers to the observation time, not the backdated time that light left the observed body. Thus `Astronomy_BackdatePosition` provides direct access to the light departure time for callers that need it.
+
 For a more generalized light travel correction solver, see [`Astronomy_CorrectLightTravel`](#Astronomy_CorrectLightTravel).
 
 
@@ -449,6 +451,8 @@ This function repeatedly calls `func`, passing `context` and a series of time es
 
 For common use cases, it is simpler to use [`Astronomy_BackdatePosition`](#Astronomy_BackdatePosition) for calculating the light travel time correction of one body observing another body.
 
+For geocentric calculations, [`Astronomy_GeoVector`](#Astronomy_GeoVector) also backdates the returned position vector for light travel time, only it returns the observation time in the returned vector's `t` field rather than the backdated time.
+
 
 
 **Returns:**  The position vector returned by `func` at the solved backdated time. On success, the vector will hold `ASTRO_SUCCESS` in its `status` field, the backdated time in its `t` field, along with the apparent relative position. If an error occurs, `status` will hold an error code and the remaining fields should be ignored. 

source/c/astronomy.c

@@ -5011,6 +5011,10 @@ astro_func_result_t Astronomy_HelioDistance(astro_body_t body, astro_time_t time
  * For common use cases, it is simpler to use #Astronomy_BackdatePosition
  * for calculating the light travel time correction of one body observing another body.
  *
+ * For geocentric calculations, #Astronomy_GeoVector also backdates the returned
+ * position vector for light travel time, only it returns the observation time in
+ * the returned vector's `t` field rather than the backdated time.
+ *
  * @param context   Holds any parameters needed by `func`.
  * @param func      Pointer to a function that returns a relative position vector as a function of time.
  * @param time      The observation time for which to solve for light travel delay.
@@ -5120,6 +5124,12 @@ static astro_vector_t BodyPosition(void *context, astro_time_t time)
  * relative position vector of a target body as seen by an observer body
  * at a given observation time.
  *
+ * For geocentric calculations, #Astronomy_GeoVector also includes light
+ * travel time correction, but the time `t` embedded in its returned vector
+ * refers to the observation time, not the backdated time that light left
+ * the observed body. Thus `Astronomy_BackdatePosition` provides direct
+ * access to the light departure time for callers that need it.
+ *
  * For a more generalized light travel correction solver, see #Astronomy_CorrectLightTravel.
  *
  * @param time          The time of observation.

source/csharp/README.md

@@ -324,6 +324,12 @@ This function solves the light travel time correction for the apparent
 relative position vector of a target body as seen by an observer body
 at a given observation time.
 
+For geocentric calculations, [`Astronomy.GeoVector`](#Astronomy.GeoVector) also includes light
+travel time correction, but the time `t` embedded in its returned vector
+refers to the observation time, not the backdated time that light left
+the observed body. Thus `BackdatePosition` provides direct
+access to the light departure time for callers that need it.
+
 For a more generalized light travel correction solver, see [`Astronomy.CorrectLightTravel`](#Astronomy.CorrectLightTravel).
 
 | Type | Parameter | Description |
@@ -403,6 +409,10 @@ left the target to arrive at the observer.
 For common use cases, it is simpler to use [`Astronomy.BackdatePosition`](#Astronomy.BackdatePosition)
 for calculating the light travel time correction of one body observing another body.
 
+For geocentric calculations, [`Astronomy.GeoVector`](#Astronomy.GeoVector) also backdates the returned
+position vector for light travel time, only it returns the observation time in
+the returned vector's `t` field rather than the backdated time.
+
 | Type | Parameter | Description |
 | --- | --- | --- |
 | [`IPositionFunction`](#IPositionFunction) | `func` | An arbitrary position vector as a function of time. |

source/csharp/astronomy.cs

@@ -5557,6 +5557,11 @@ private static AstroVector CalcEarth(AstroTime time)
         ///
         /// For common use cases, it is simpler to use #Astronomy.BackdatePosition
         /// for calculating the light travel time correction of one body observing another body.
+        ///
+        /// For geocentric calculations, #Astronomy.GeoVector also backdates the returned
+        /// position vector for light travel time, only it returns the observation time in
+        /// the returned vector's `t` field rather than the backdated time.
+        ///
         /// </remarks>
         /// <param name="func">An arbitrary position vector as a function of time.</param>
         /// <param name="time">The observation time for which to solve for light travel delay.</param>
@@ -5642,6 +5647,12 @@ public AstroVector Position(AstroTime time)
         /// relative position vector of a target body as seen by an observer body
         /// at a given observation time.
         ///
+        /// For geocentric calculations, #Astronomy.GeoVector also includes light
+        /// travel time correction, but the time `t` embedded in its returned vector
+        /// refers to the observation time, not the backdated time that light left
+        /// the observed body. Thus `BackdatePosition` provides direct
+        /// access to the light departure time for callers that need it.
+        ///
         /// For a more generalized light travel correction solver, see #Astronomy.CorrectLightTravel.
         /// </remarks>
         /// <param name="time">The time of observation.</param>

source/js/README.md

@@ -1626,6 +1626,10 @@ left the target to arrive at the observer.
 For common use cases, it is simpler to use [BackdatePosition](#BackdatePosition)
 for calculating the light travel time correction of one body observing another body.
 
+For geocentric calculations, [GeoVector](#GeoVector) also backdates the returned
+position vector for light travel time, only it returns the observation time in
+the returned vector's `t` field rather than the backdated time.
+
 **Kind**: global function  
 **Returns**: <code>AstroVector</code> - The position vector at the solved backdated time.
      The `t` field holds the time that light left the observed
@@ -1656,6 +1660,12 @@ This function solves the light travel time correction for the apparent
 relative position vector of a target body as seen by an observer body
 at a given observation time.
 
+For geocentric calculations, [GeoVector](#GeoVector) also includes light
+travel time correction, but the time `t` embedded in its returned vector
+refers to the observation time, not the backdated time that light left
+the observed body. Thus `BackdatePosition` provides direct
+access to the light departure time for callers that need it.
+
 For a more generalized light travel correction solver, see [CorrectLightTravel](#CorrectLightTravel).  
 
 | Param | Type | Description |

source/js/astronomy.browser.js

@@ -3651,6 +3651,10 @@ exports.PositionFunction = PositionFunction;
  * For common use cases, it is simpler to use {@link BackdatePosition}
  * for calculating the light travel time correction of one body observing another body.
  *
+ * For geocentric calculations, {@link GeoVector} also backdates the returned
+ * position vector for light travel time, only it returns the observation time in
+ * the returned vector's `t` field rather than the backdated time.
+ *
  * @param {PositionFunction} func
  *      An arbitrary position vector as a function of time.
  *
@@ -3722,6 +3726,12 @@ class BodyPosition extends PositionFunction {
  * relative position vector of a target body as seen by an observer body
  * at a given observation time.
  *
+ * For geocentric calculations, {@link GeoVector} also includes light
+ * travel time correction, but the time `t` embedded in its returned vector
+ * refers to the observation time, not the backdated time that light left
+ * the observed body. Thus `BackdatePosition` provides direct
+ * access to the light departure time for callers that need it.
+ *
  * For a more generalized light travel correction solver, see {@link CorrectLightTravel}.
  *
  * @param {FlexibleDateTime} date