diff --git a/demo/browser/astronomy.browser.js b/demo/browser/astronomy.browser.js index 1c73526d..75ec7ce7 100644 --- a/demo/browser/astronomy.browser.js +++ b/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 diff --git a/demo/nodejs/astronomy.js b/demo/nodejs/astronomy.js index 17663741..621dabd6 100644 --- a/demo/nodejs/astronomy.js +++ b/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 diff --git a/demo/nodejs/calendar/astronomy.ts b/demo/nodejs/calendar/astronomy.ts index bde05681..3ef8043b 100644 --- a/demo/nodejs/calendar/astronomy.ts +++ b/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 diff --git a/demo/python/astronomy.py b/demo/python/astronomy.py index 2bf18956..9efc2fe8 100644 --- a/demo/python/astronomy.py +++ b/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 diff --git a/generate/template/astronomy.c b/generate/template/astronomy.c index c811fd0d..088d90bd 100644 --- a/generate/template/astronomy.c +++ b/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. diff --git a/generate/template/astronomy.cs b/generate/template/astronomy.cs index 881b34e2..32b8f99d 100644 --- a/generate/template/astronomy.cs +++ b/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. + /// /// /// An arbitrary position vector as a function of time. /// The observation time for which to solve for light travel delay. @@ -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. /// /// The time of observation. diff --git a/generate/template/astronomy.kt b/generate/template/astronomy.kt index 959b5493..5634ecfe 100644 --- a/generate/template/astronomy.kt +++ b/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 diff --git a/generate/template/astronomy.py b/generate/template/astronomy.py index 186efd70..74622f98 100644 --- a/generate/template/astronomy.py +++ b/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 diff --git a/generate/template/astronomy.ts b/generate/template/astronomy.ts index 548afa6b..03e9c900 100644 --- a/generate/template/astronomy.ts +++ b/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 diff --git a/source/c/README.md b/source/c/README.md index 1335ee8c..81b4ca36 100644 --- a/source/c/README.md +++ b/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. diff --git a/source/c/astronomy.c b/source/c/astronomy.c index 44210c38..9651e9c9 100644 --- a/source/c/astronomy.c +++ b/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. diff --git a/source/csharp/README.md b/source/csharp/README.md index b8eccca7..5c95249d 100644 --- a/source/csharp/README.md +++ b/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. | diff --git a/source/csharp/astronomy.cs b/source/csharp/astronomy.cs index 5976d52e..94c22a6d 100644 --- a/source/csharp/astronomy.cs +++ b/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. + /// /// /// An arbitrary position vector as a function of time. /// The observation time for which to solve for light travel delay. @@ -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. /// /// The time of observation. diff --git a/source/js/README.md b/source/js/README.md index 06b708e2..e7165266 100644 --- a/source/js/README.md +++ b/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**: AstroVector - 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 | diff --git a/source/js/astronomy.browser.js b/source/js/astronomy.browser.js index 1c73526d..75ec7ce7 100644 --- a/source/js/astronomy.browser.js +++ b/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 diff --git a/source/js/astronomy.d.ts b/source/js/astronomy.d.ts index 3cff64a9..f400110d 100644 --- a/source/js/astronomy.d.ts +++ b/source/js/astronomy.d.ts @@ -990,6 +990,10 @@ export declare 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. * @@ -1013,6 +1017,12 @@ export declare function CorrectLightTravel(func: PositionFunction, time: AstroTi * 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 diff --git a/source/js/astronomy.js b/source/js/astronomy.js index 17663741..621dabd6 100644 --- a/source/js/astronomy.js +++ b/source/js/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 diff --git a/source/js/astronomy.ts b/source/js/astronomy.ts index bde05681..3ef8043b 100644 --- a/source/js/astronomy.ts +++ b/source/js/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 diff --git a/source/js/esm/astronomy.js b/source/js/esm/astronomy.js index b976532e..09e1b049 100644 --- a/source/js/esm/astronomy.js +++ b/source/js/esm/astronomy.js @@ -3610,6 +3610,10 @@ export 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. * @@ -3680,6 +3684,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 diff --git a/source/kotlin/doc/backdate-position.md b/source/kotlin/doc/backdate-position.md index 875a0bb2..9b207d60 100644 --- a/source/kotlin/doc/backdate-position.md +++ b/source/kotlin/doc/backdate-position.md @@ -10,6 +10,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, #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](correct-light-travel.md). #### Return diff --git a/source/kotlin/doc/correct-light-travel.md b/source/kotlin/doc/correct-light-travel.md index 95981861..172fa1d6 100644 --- a/source/kotlin/doc/correct-light-travel.md +++ b/source/kotlin/doc/correct-light-travel.md @@ -12,6 +12,8 @@ This function repeatedly calls func.Position, passing a series of time estimates For common use cases, it is simpler to use [backdatePosition](backdate-position.md) 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. + #### Return The position vector at the solved backdated time. The t field holds the time that light left the observed body to arrive at the observer at the observation time. diff --git a/source/kotlin/src/main/kotlin/io/github/cosinekitty/astronomy/astronomy.kt b/source/kotlin/src/main/kotlin/io/github/cosinekitty/astronomy/astronomy.kt index 32ca5c67..f1049f27 100644 --- a/source/kotlin/src/main/kotlin/io/github/cosinekitty/astronomy/astronomy.kt +++ b/source/kotlin/src/main/kotlin/io/github/cosinekitty/astronomy/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 diff --git a/source/python/README.md b/source/python/README.md index 4f18edea..5773b69d 100644 --- a/source/python/README.md +++ b/source/python/README.md @@ -1259,6 +1259,11 @@ observer can significantly affect the object's apparent position. 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). | Type | Parameter | Description | @@ -1372,6 +1377,9 @@ the observer and the target. `CorrectLightTravel` keeps calling 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. time : Time The observation time for which to solve for light travel delay. diff --git a/source/python/astronomy/astronomy.py b/source/python/astronomy/astronomy.py index 2bf18956..9efc2fe8 100644 --- a/source/python/astronomy/astronomy.py +++ b/source/python/astronomy/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