From e12d2e88c628b37605e0ca793217f7fbde73d663 Mon Sep 17 00:00:00 2001 From: Don Cross Date: Sun, 27 Nov 2022 12:42:48 -0500 Subject: [PATCH] Updated docs: SearchRiseSet, SearchAltitude. The documentation for SearchRiseSet and SearchAltitude needed clarification about refraction and the part of the body solved for (center versus limb). The JavaScript version was especially lacking compared to documentation for the other languages. Also documented SearchAltitude's limitations; it does not work at or near maximum/minimum altitude. Mention that user-defined stars are allowed for SearchRiseSet, SearchAltitude, and SearchHourAngle. Fixed a couple places where the Kotlin documentation had broken links to other functions. --- demo/browser/astronomy.browser.js | 78 ++++++++++++++----- demo/nodejs/astronomy.js | 78 ++++++++++++++----- demo/nodejs/calendar/astronomy.ts | 78 ++++++++++++++----- demo/python/astronomy.py | 32 ++++++-- generate/template/astronomy.c | 41 +++++++--- generate/template/astronomy.cs | 40 ++++++++-- generate/template/astronomy.kt | 35 +++++++-- generate/template/astronomy.py | 32 ++++++-- generate/template/astronomy.ts | 78 ++++++++++++++----- source/c/README.md | 20 +++-- source/c/astronomy.c | 41 +++++++--- source/csharp/README.md | 32 ++++++-- source/csharp/astronomy.cs | 40 ++++++++-- source/js/README.md | 78 ++++++++++++++----- source/js/astronomy.browser.js | 78 ++++++++++++++----- source/js/astronomy.d.ts | 78 ++++++++++++++----- source/js/astronomy.js | 78 ++++++++++++++----- source/js/astronomy.ts | 78 ++++++++++++++----- source/js/esm/astronomy.js | 78 ++++++++++++++----- source/kotlin/doc/search-altitude.md | 8 +- source/kotlin/doc/search-hour-angle.md | 2 +- .../kotlin/doc/search-local-solar-eclipse.md | 2 +- source/kotlin/doc/search-peak-magnitude.md | 2 +- source/kotlin/doc/search-rise-set.md | 6 +- .../github/cosinekitty/astronomy/astronomy.kt | 35 +++++++-- source/python/README.md | 26 +++++-- source/python/astronomy/astronomy.py | 32 ++++++-- 27 files changed, 924 insertions(+), 282 deletions(-) diff --git a/demo/browser/astronomy.browser.js b/demo/browser/astronomy.browser.js index 12cfcaa8..6e0aa781 100644 --- a/demo/browser/astronomy.browser.js +++ b/demo/browser/astronomy.browser.js @@ -4887,18 +4887,32 @@ function BodyRadiusAu(body) { } } /** - * @brief Finds the next rise or set time for a body. + * @brief Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. * - * Finds a rise or set time for the given body as - * seen by an observer at the specified location on the Earth. - * Rise time is defined as the moment when the top of the body - * is observed to first appear above the horizon in the east. - * Set time is defined as the moment the top of the body - * is observed to sink below the horizon in the west. - * The times are adjusted for typical atmospheric refraction conditions. + * This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. + * Rise time is when the body first starts to be visible above the horizon. + * For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. + * Set time is the moment when the body appears to vanish below the horizon. + * Therefore, this function adjusts for the apparent angular radius of the observed body + * (significant only for the Sun and Moon). + * + * This function corrects for a typical value of atmospheric refraction, which causes celestial + * bodies to appear higher above the horizon than they would if the Earth had no atmosphere. + * Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based + * on air temperature, pressure, and humidity; such weather-based conditions are outside + * the scope of Astronomy Engine. + * + * Note that rise or set may not occur in every 24 hour period. + * For example, near the Earth's poles, there are long periods of time where + * the Sun stays below the horizon, never rising. + * Also, it is possible for the Moon to rise just before midnight but not set during the subsequent 24-hour day. + * This is because the Moon sets nearly an hour later each day due to orbiting the Earth a + * significant amount during each rotation of the Earth. + * Therefore callers must not assume that the function will always succeed. * * @param {Body} body - * The body to find the rise or set time for. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. @@ -4930,7 +4944,7 @@ function SearchRiseSet(body, observer, direction, dateStart, limitDays) { } exports.SearchRiseSet = SearchRiseSet; /** - * @brief Finds the next time a body reaches a given altitude. + * @brief Finds the next time the center of a body passes through a given altitude. * * Finds when the given body ascends or descends through a given * altitude angle, as seen by an observer at the specified location on the Earth. @@ -4948,9 +4962,23 @@ exports.SearchRiseSet = SearchRiseSet; * * Astronomical twilight uses -18 degrees as the `altitude` value. * + * By convention for twilight time calculations, the altitude is not corrected for + * atmospheric refraction. This is because the target altitudes are below the horizon, + * and refraction is not directly observable. + * + * `SearchAltitude` is not intended to find rise/set times of a body for two reasons: + * (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. + * (2) Rise/set times are affected significantly by atmospheric refraction. + * Therefore, it is better to use {@link SearchRiseSet} to find rise/set times, which + * corrects for both of these considerations. + * + * `SearchAltitude` will not work reliably for altitudes at or near the body's + * maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude + * angles, use {@link SearchHourAngle}. + * * @param {Body} body - * The body for which to find the altitude event. - * Can be the Sun, Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. @@ -5201,20 +5229,32 @@ class HourAngleEvent { } exports.HourAngleEvent = HourAngleEvent; /** - * @brief Finds when a body will reach a given hour angle. + * @brief Searches for the time when a celestial body reaches a specified hour angle as seen by an observer on the Earth. + * + * The *hour angle* of a celestial body indicates its position in the sky with respect + * to the Earth's rotation. The hour angle depends on the location of the observer on the Earth. + * The hour angle is 0 when the body reaches its highest angle above the horizon in a given day. + * The hour angle increases by 1 unit for every sidereal hour that passes after that point, up + * to 24 sidereal hours when it reaches the highest point again. So the hour angle indicates + * the number of hours that have passed since the most recent time that the body has culminated, + * or reached its highest point. + * + * This function searches for the next or previous time a celestial body reaches the given hour angle + * relative to the date and time specified by `dateStart`. + * To find when a body culminates, pass 0 for `hourAngle`. + * To find when a body reaches its lowest point in the sky, pass 12 for `hourAngle`. * - * Finds the next time the given body is seen to reach the specified - * hour angle - * by the given observer. - * Providing `hourAngle` = 0 finds the next maximum altitude event (culmination). - * Providing `hourAngle` = 12 finds the next minimum altitude event. * Note that, especially close to the Earth's poles, a body as seen on a given day * may always be above the horizon or always below the horizon, so the caller cannot * assume that a culminating object is visible nor that an object is below the horizon * at its minimum altitude. * + * The function returns the date and time, along with the horizontal coordinates + * of the body at that time, as seen by the given observer. + * * @param {Body} body - * A celestial body other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. diff --git a/demo/nodejs/astronomy.js b/demo/nodejs/astronomy.js index bd01bc02..62d9811a 100644 --- a/demo/nodejs/astronomy.js +++ b/demo/nodejs/astronomy.js @@ -4886,18 +4886,32 @@ function BodyRadiusAu(body) { } } /** - * @brief Finds the next rise or set time for a body. + * @brief Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. * - * Finds a rise or set time for the given body as - * seen by an observer at the specified location on the Earth. - * Rise time is defined as the moment when the top of the body - * is observed to first appear above the horizon in the east. - * Set time is defined as the moment the top of the body - * is observed to sink below the horizon in the west. - * The times are adjusted for typical atmospheric refraction conditions. + * This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. + * Rise time is when the body first starts to be visible above the horizon. + * For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. + * Set time is the moment when the body appears to vanish below the horizon. + * Therefore, this function adjusts for the apparent angular radius of the observed body + * (significant only for the Sun and Moon). + * + * This function corrects for a typical value of atmospheric refraction, which causes celestial + * bodies to appear higher above the horizon than they would if the Earth had no atmosphere. + * Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based + * on air temperature, pressure, and humidity; such weather-based conditions are outside + * the scope of Astronomy Engine. + * + * Note that rise or set may not occur in every 24 hour period. + * For example, near the Earth's poles, there are long periods of time where + * the Sun stays below the horizon, never rising. + * Also, it is possible for the Moon to rise just before midnight but not set during the subsequent 24-hour day. + * This is because the Moon sets nearly an hour later each day due to orbiting the Earth a + * significant amount during each rotation of the Earth. + * Therefore callers must not assume that the function will always succeed. * * @param {Body} body - * The body to find the rise or set time for. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. @@ -4929,7 +4943,7 @@ function SearchRiseSet(body, observer, direction, dateStart, limitDays) { } exports.SearchRiseSet = SearchRiseSet; /** - * @brief Finds the next time a body reaches a given altitude. + * @brief Finds the next time the center of a body passes through a given altitude. * * Finds when the given body ascends or descends through a given * altitude angle, as seen by an observer at the specified location on the Earth. @@ -4947,9 +4961,23 @@ exports.SearchRiseSet = SearchRiseSet; * * Astronomical twilight uses -18 degrees as the `altitude` value. * + * By convention for twilight time calculations, the altitude is not corrected for + * atmospheric refraction. This is because the target altitudes are below the horizon, + * and refraction is not directly observable. + * + * `SearchAltitude` is not intended to find rise/set times of a body for two reasons: + * (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. + * (2) Rise/set times are affected significantly by atmospheric refraction. + * Therefore, it is better to use {@link SearchRiseSet} to find rise/set times, which + * corrects for both of these considerations. + * + * `SearchAltitude` will not work reliably for altitudes at or near the body's + * maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude + * angles, use {@link SearchHourAngle}. + * * @param {Body} body - * The body for which to find the altitude event. - * Can be the Sun, Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. @@ -5200,20 +5228,32 @@ class HourAngleEvent { } exports.HourAngleEvent = HourAngleEvent; /** - * @brief Finds when a body will reach a given hour angle. + * @brief Searches for the time when a celestial body reaches a specified hour angle as seen by an observer on the Earth. + * + * The *hour angle* of a celestial body indicates its position in the sky with respect + * to the Earth's rotation. The hour angle depends on the location of the observer on the Earth. + * The hour angle is 0 when the body reaches its highest angle above the horizon in a given day. + * The hour angle increases by 1 unit for every sidereal hour that passes after that point, up + * to 24 sidereal hours when it reaches the highest point again. So the hour angle indicates + * the number of hours that have passed since the most recent time that the body has culminated, + * or reached its highest point. + * + * This function searches for the next or previous time a celestial body reaches the given hour angle + * relative to the date and time specified by `dateStart`. + * To find when a body culminates, pass 0 for `hourAngle`. + * To find when a body reaches its lowest point in the sky, pass 12 for `hourAngle`. * - * Finds the next time the given body is seen to reach the specified - * hour angle - * by the given observer. - * Providing `hourAngle` = 0 finds the next maximum altitude event (culmination). - * Providing `hourAngle` = 12 finds the next minimum altitude event. * Note that, especially close to the Earth's poles, a body as seen on a given day * may always be above the horizon or always below the horizon, so the caller cannot * assume that a culminating object is visible nor that an object is below the horizon * at its minimum altitude. * + * The function returns the date and time, along with the horizontal coordinates + * of the body at that time, as seen by the given observer. + * * @param {Body} body - * A celestial body other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. diff --git a/demo/nodejs/calendar/astronomy.ts b/demo/nodejs/calendar/astronomy.ts index b4bd023b..df2a5cb3 100644 --- a/demo/nodejs/calendar/astronomy.ts +++ b/demo/nodejs/calendar/astronomy.ts @@ -5428,18 +5428,32 @@ function BodyRadiusAu(body: Body): number { } /** - * @brief Finds the next rise or set time for a body. + * @brief Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. * - * Finds a rise or set time for the given body as - * seen by an observer at the specified location on the Earth. - * Rise time is defined as the moment when the top of the body - * is observed to first appear above the horizon in the east. - * Set time is defined as the moment the top of the body - * is observed to sink below the horizon in the west. - * The times are adjusted for typical atmospheric refraction conditions. + * This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. + * Rise time is when the body first starts to be visible above the horizon. + * For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. + * Set time is the moment when the body appears to vanish below the horizon. + * Therefore, this function adjusts for the apparent angular radius of the observed body + * (significant only for the Sun and Moon). + * + * This function corrects for a typical value of atmospheric refraction, which causes celestial + * bodies to appear higher above the horizon than they would if the Earth had no atmosphere. + * Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based + * on air temperature, pressure, and humidity; such weather-based conditions are outside + * the scope of Astronomy Engine. + * + * Note that rise or set may not occur in every 24 hour period. + * For example, near the Earth's poles, there are long periods of time where + * the Sun stays below the horizon, never rising. + * Also, it is possible for the Moon to rise just before midnight but not set during the subsequent 24-hour day. + * This is because the Moon sets nearly an hour later each day due to orbiting the Earth a + * significant amount during each rotation of the Earth. + * Therefore callers must not assume that the function will always succeed. * * @param {Body} body - * The body to find the rise or set time for. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. @@ -5477,7 +5491,7 @@ export function SearchRiseSet( } /** - * @brief Finds the next time a body reaches a given altitude. + * @brief Finds the next time the center of a body passes through a given altitude. * * Finds when the given body ascends or descends through a given * altitude angle, as seen by an observer at the specified location on the Earth. @@ -5495,9 +5509,23 @@ export function SearchRiseSet( * * Astronomical twilight uses -18 degrees as the `altitude` value. * + * By convention for twilight time calculations, the altitude is not corrected for + * atmospheric refraction. This is because the target altitudes are below the horizon, + * and refraction is not directly observable. + * + * `SearchAltitude` is not intended to find rise/set times of a body for two reasons: + * (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. + * (2) Rise/set times are affected significantly by atmospheric refraction. + * Therefore, it is better to use {@link SearchRiseSet} to find rise/set times, which + * corrects for both of these considerations. + * + * `SearchAltitude` will not work reliably for altitudes at or near the body's + * maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude + * angles, use {@link SearchHourAngle}. + * * @param {Body} body - * The body for which to find the altitude event. - * Can be the Sun, Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. @@ -5812,20 +5840,32 @@ export class HourAngleEvent { } /** - * @brief Finds when a body will reach a given hour angle. + * @brief Searches for the time when a celestial body reaches a specified hour angle as seen by an observer on the Earth. + * + * The *hour angle* of a celestial body indicates its position in the sky with respect + * to the Earth's rotation. The hour angle depends on the location of the observer on the Earth. + * The hour angle is 0 when the body reaches its highest angle above the horizon in a given day. + * The hour angle increases by 1 unit for every sidereal hour that passes after that point, up + * to 24 sidereal hours when it reaches the highest point again. So the hour angle indicates + * the number of hours that have passed since the most recent time that the body has culminated, + * or reached its highest point. + * + * This function searches for the next or previous time a celestial body reaches the given hour angle + * relative to the date and time specified by `dateStart`. + * To find when a body culminates, pass 0 for `hourAngle`. + * To find when a body reaches its lowest point in the sky, pass 12 for `hourAngle`. * - * Finds the next time the given body is seen to reach the specified - * hour angle - * by the given observer. - * Providing `hourAngle` = 0 finds the next maximum altitude event (culmination). - * Providing `hourAngle` = 12 finds the next minimum altitude event. * Note that, especially close to the Earth's poles, a body as seen on a given day * may always be above the horizon or always below the horizon, so the caller cannot * assume that a culminating object is visible nor that an object is below the horizon * at its minimum altitude. * + * The function returns the date and time, along with the horizontal coordinates + * of the body at that time, as seen by the given observer. + * * @param {Body} body - * A celestial body other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. diff --git a/demo/python/astronomy.py b/demo/python/astronomy.py index 3bb82e44..c0108ffe 100644 --- a/demo/python/astronomy.py +++ b/demo/python/astronomy.py @@ -6531,7 +6531,8 @@ def SearchHourAngle(body, observer, hourAngle, startTime, direction = +1): Parameters ---------- body : Body - The celestial body, which can the Sun, the Moon, or any planet other than the Earth. + The Sun, Moon, any planet other than the Earth, + or a user-defined star that was created by a call to #DefineStar. observer : Observer Indicates a location on or near the surface of the Earth where the observer is located. hourAngle : float @@ -6801,10 +6802,15 @@ def SearchRiseSet(body, observer, direction, startTime, limitDays): Rise time is when the body first starts to be visible above the horizon. For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. Set time is the moment when the body appears to vanish below the horizon. + Therefore, this function adjusts for the apparent angular radius of the observed body + (significant only for the Sun and Moon). This function corrects for typical atmospheric refraction, which causes celestial bodies to appear higher above the horizon than they would if the Earth had no atmosphere. It also adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon). + Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based + on air temperature, pressure, and humidity; such weather-based conditions are outside + the scope of Astronomy Engine. Note that rise or set may not occur in every 24 hour period. For example, near the Earth's poles, there are long periods of time where @@ -6817,7 +6823,8 @@ def SearchRiseSet(body, observer, direction, startTime, limitDays): Parameters ---------- body : Body - The Sun, Moon, or any planet other than the Earth. + The Sun, Moon, any planet other than the Earth, or a user-defined star + that was created by a call to #DefineStar. observer : Observer The location where observation takes place. direction : Direction @@ -6850,9 +6857,9 @@ def SearchRiseSet(body, observer, direction, startTime, limitDays): def SearchAltitude(body, observer, direction, startTime, limitDays, altitude): - """Finds the next time a body reaches a given altitude. + """Finds the next time the center of a body passes through a given altitude. - Finds when the given body ascends or descends through a given + Finds when the center of the given body ascends or descends through a given altitude angle, as seen by an observer at the specified location on the Earth. By using the appropriate combination of `direction` and `altitude` parameters, this function can be used to find when civil, nautical, or astronomical twilight @@ -6868,10 +6875,25 @@ def SearchAltitude(body, observer, direction, startTime, limitDays, altitude): Astronomical twilight uses -18 degrees as the `altitude` value. + By convention for twilight time calculations, the altitude is not corrected for + atmospheric refraction. This is because the target altitudes are below the horizon, + and refraction is not directly observable. + + `SearchAltitude` is not intended to find rise/set times of a body for two reasons: + (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. + (2) Rise/set times are affected significantly by atmospheric refraction. + Therefore, it is better to use #SearchRiseSet to find rise/set times, which + corrects for both of these considerations. + + `SearchAltitude` will not work reliably for altitudes at or near the body's + maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude + angles, use #SearchHourAngle. + Parameters ---------- body : Body - The Sun, Moon, or any planet other than the Earth. + The Sun, Moon, any planet other than the Earth, + or a user-defined star that was created by a call to #DefineStar. observer : Observer The location where observation takes place. direction : Direction diff --git a/generate/template/astronomy.c b/generate/template/astronomy.c index 36f51af6..a7f2f945 100644 --- a/generate/template/astronomy.c +++ b/generate/template/astronomy.c @@ -6440,8 +6440,7 @@ astro_search_result_t Astronomy_SearchRelativeLongitude(astro_body_t body, doubl } /** - * @brief - * Searches for the time when a celestial body reaches a specified hour angle as seen by an observer on the Earth. + * @brief Searches for the time when a celestial body reaches a specified hour angle as seen by an observer on the Earth. * * The *hour angle* of a celestial body indicates its position in the sky with respect * to the Earth's rotation. The hour angle depends on the location of the observer on the Earth. @@ -6465,7 +6464,8 @@ astro_search_result_t Astronomy_SearchRelativeLongitude(astro_body_t body, doubl * of the body at that time, as seen by the given observer. * * @param body - * The celestial body, which can the Sun, the Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to #Astronomy_DefineStar. * * @param observer * Indicates a location on or near the surface of the Earth where the observer is located. @@ -6933,17 +6933,20 @@ static astro_search_result_t InternalSearchAltitude( /** - * @brief - * Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. + * @brief Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. * * This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. * Rise time is when the body first starts to be visible above the horizon. * For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. * Set time is the moment when the body appears to vanish below the horizon. + * Therefore, this function adjusts for the apparent angular radius of the observed body + * (significant only for the Sun and Moon). * - * This function corrects for typical atmospheric refraction, which causes celestial + * This function corrects for a typical value of atmospheric refraction, which causes celestial * bodies to appear higher above the horizon than they would if the Earth had no atmosphere. - * It also adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon). + * Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based + * on air temperature, pressure, and humidity; such weather-based conditions are outside + * the scope of Astronomy Engine. * * Note that rise or set may not occur in every 24 hour period. * For example, near the Earth's poles, there are long periods of time where @@ -6954,7 +6957,8 @@ static astro_search_result_t InternalSearchAltitude( * Therefore callers must not assume that the function will always succeed. * * @param body - * The Sun, Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to #Astronomy_DefineStar. * * @param observer * The location where observation takes place. @@ -7003,9 +7007,9 @@ astro_search_result_t Astronomy_SearchRiseSet( /** - * @brief Finds the next time a body reaches a given altitude. + * @brief Finds the next time the center of a body passes through a given altitude. * - * Finds when the given body ascends or descends through a given + * Finds when the center of the given body ascends or descends through a given * altitude angle, as seen by an observer at the specified location on the Earth. * By using the appropriate combination of `direction` and `altitude` parameters, * this function can be used to find when civil, nautical, or astronomical twilight @@ -7021,8 +7025,23 @@ astro_search_result_t Astronomy_SearchRiseSet( * * Astronomical twilight uses -18 degrees as the `altitude` value. * + * By convention for twilight time calculations, the altitude is not corrected for + * atmospheric refraction. This is because the target altitudes are below the horizon, + * and refraction is not directly observable. + * + * `Astronomy_SearchAltitude` is not intended to find rise/set times of a body for two reasons: + * (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. + * (2) Rise/set times are affected significantly by atmospheric refraction. + * Therefore, it is better to use #Astronomy_SearchRiseSet to find rise/set times, which + * corrects for both of these considerations. + * + * `Astronomy_SearchAltitude` will not work reliably for altitudes at or near the body's + * maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude + * angles, use #Astronomy_SearchHourAngleEx. + * * @param body - * The Sun, Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to #Astronomy_DefineStar. * * @param observer * The location where observation takes place. diff --git a/generate/template/astronomy.cs b/generate/template/astronomy.cs index 94967cf6..dd6bc5c6 100644 --- a/generate/template/astronomy.cs +++ b/generate/template/astronomy.cs @@ -6180,15 +6180,20 @@ $ASTRO_IAU_DATA() /// /// Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. /// + /// /// /// This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. /// Rise time is when the body first starts to be visible above the horizon. /// For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. /// Set time is the moment when the body appears to vanish below the horizon. + /// Therefore, this function adjusts for the apparent angular radius of the observed body + /// (significant only for the Sun and Moon). /// - /// This function corrects for typical atmospheric refraction, which causes celestial + /// This function corrects for a typical value of atmospheric refraction, which causes celestial /// bodies to appear higher above the horizon than they would if the Earth had no atmosphere. - /// It also adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon). + /// Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based + /// on air temperature, pressure, and humidity; such weather-based conditions are outside + /// the scope of Astronomy Engine. /// /// Note that rise or set may not occur in every 24 hour period. /// For example, near the Earth's poles, there are long periods of time where @@ -6199,7 +6204,10 @@ $ASTRO_IAU_DATA() /// Therefore callers must not assume that the function will always succeed. /// /// - /// The Sun, Moon, or any planet other than the Earth. + /// + /// The Sun, Moon, any planet other than the Earth, + /// or a user-defined star that was created by a call to #Astronomy.DefineStar. + /// /// /// The location where observation takes place. /// @@ -6253,10 +6261,10 @@ $ASTRO_IAU_DATA() } /// - /// Finds the next time a body reaches a given altitude. + /// Finds the next time the center of a body passes through a given altitude. /// /// - /// Finds when the given body ascends or descends through a given + /// Finds when the center of the given body ascends or descends through a given /// altitude angle, as seen by an observer at the specified location on the Earth. /// By using the appropriate combination of `direction` and `altitude` parameters, /// this function can be used to find when civil, nautical, or astronomical twilight @@ -6271,9 +6279,26 @@ $ASTRO_IAU_DATA() /// Nautical twilight is similar to civil twilight, only the `altitude` value should be -12 degrees. /// /// Astronomical twilight uses -18 degrees as the `altitude` value. + /// + /// By convention for twilight time calculations, the altitude is not corrected for + /// atmospheric refraction. This is because the target altitudes are below the horizon, + /// and refraction is not directly observable. + /// + /// `SearchAltitude` is not intended to find rise/set times of a body for two reasons: + /// (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. + /// (2) Rise/set times are affected significantly by atmospheric refraction. + /// Therefore, it is better to use #Astronomy.SearchRiseSet to find rise/set times, which + /// corrects for both of these considerations. + /// + /// `SearchAltitude` will not work reliably for altitudes at or near the body's + /// maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude + /// angles, use #Astronomy.SearchHourAngle. /// /// - /// The Sun, Moon, or any planet other than the Earth. + /// + /// The Sun, Moon, any planet other than the Earth, + /// or a user-defined star that was created by a call to #Astronomy.DefineStar. + /// /// /// The location where observation takes place. /// @@ -6346,7 +6371,8 @@ $ASTRO_IAU_DATA() /// /// /// - /// The celestial body, which can the Sun, the Moon, or any planet other than the Earth. + /// The Sun, Moon, any planet other than the Earth, + /// or a user-defined star that was created by a call to #Astronomy.DefineStar. /// /// /// diff --git a/generate/template/astronomy.kt b/generate/template/astronomy.kt index 80052383..a1179920 100644 --- a/generate/template/astronomy.kt +++ b/generate/template/astronomy.kt @@ -2707,7 +2707,7 @@ fun globalSolarEclipsesAfter(startTime: Time): Sequence * See [LocalSolarEclipseInfo] for more information. * * To find a series of solar eclipses, call this function once, - * then keep calling #Astronomy.NextLocalSolarEclipse as many times as desired, + * then keep calling [nextLocalSolarEclipse] as many times as desired, * passing in the `peak` value returned from the previous call. * * IMPORTANT: An eclipse reported by this function might be partly or @@ -6223,7 +6223,8 @@ fun moonQuartersAfter(startTime: Time): Sequence = * of the body at that time, as seen by the given observer. * * @param body - * The celestial body, which can the Sun, the Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to [defineStar]. * * @param observer * A location on or near the surface of the Earth where the observer is located. @@ -6543,10 +6544,14 @@ private fun internalSearchAltitude( * Rise time is when the body first starts to be visible above the horizon. * For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. * Set time is the moment when the body appears to vanish below the horizon. + * Therefore, this function adjusts for the apparent angular radius of the observed body + * (significant only for the Sun and Moon). * - * This function corrects for typical atmospheric refraction, which causes celestial + * This function corrects for a typical value of atmospheric refraction, which causes celestial * bodies to appear higher above the horizon than they would if the Earth had no atmosphere. - * It also adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon). + * Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based + * on air temperature, pressure, and humidity; such weather-based conditions are outside + * the scope of Astronomy Engine. * * Note that rise or set may not occur in every 24 hour period. * For example, near the Earth's poles, there are long periods of time where @@ -6557,7 +6562,8 @@ private fun internalSearchAltitude( * Therefore callers must not assume that the function will always succeed. * * @param body - * The Sun, Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to [defineStar]. * * @param observer * The location where observation takes place. @@ -6618,8 +6624,23 @@ fun searchRiseSet( * * Astronomical twilight uses -18 degrees as the `altitude` value. * + * By convention for twilight time calculations, the altitude is not corrected for + * atmospheric refraction. This is because the target altitudes are below the horizon, + * and refraction is not directly observable. + * + * `searchAltitude` is not intended to find rise/set times of a body for two reasons: + * (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. + * (2) Rise/set times are affected significantly by atmospheric refraction. + * Therefore, it is better to use [searchRiseSet] to find rise/set times, which + * corrects for both of these considerations. + * + * `searchAltitude` will not work reliably for altitudes at or near the body's + * maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude + * angles, use [searchHourAngle]. + * * @param body - * The Sun, Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to [defineStar]. * * @param observer * The location where observation takes place. @@ -7165,7 +7186,7 @@ internal fun magnitudeSlope(body: Body, time: Time): Double { * Mercury's peak magnitude occurs at superior conjunction, when it is virtually impossible to see from the Earth, * so peak magnitude events have little practical value for that planet. * Planets other than Venus and Mercury reach peak magnitude at opposition, which can - * be found using #Astronomy.SearchRelativeLongitude. + * be found using [searchRelativeLongitude]. * The Moon reaches peak magnitude at full moon, which can be found using * [searchMoonQuarter] or [searchMoonPhase]. * The Sun reaches peak magnitude at perihelion, which occurs each year in January. diff --git a/generate/template/astronomy.py b/generate/template/astronomy.py index 22b0d1c1..a95ffcef 100644 --- a/generate/template/astronomy.py +++ b/generate/template/astronomy.py @@ -4489,7 +4489,8 @@ def SearchHourAngle(body, observer, hourAngle, startTime, direction = +1): Parameters ---------- body : Body - The celestial body, which can the Sun, the Moon, or any planet other than the Earth. + The Sun, Moon, any planet other than the Earth, + or a user-defined star that was created by a call to #DefineStar. observer : Observer Indicates a location on or near the surface of the Earth where the observer is located. hourAngle : float @@ -4759,10 +4760,15 @@ def SearchRiseSet(body, observer, direction, startTime, limitDays): Rise time is when the body first starts to be visible above the horizon. For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. Set time is the moment when the body appears to vanish below the horizon. + Therefore, this function adjusts for the apparent angular radius of the observed body + (significant only for the Sun and Moon). This function corrects for typical atmospheric refraction, which causes celestial bodies to appear higher above the horizon than they would if the Earth had no atmosphere. It also adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon). + Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based + on air temperature, pressure, and humidity; such weather-based conditions are outside + the scope of Astronomy Engine. Note that rise or set may not occur in every 24 hour period. For example, near the Earth's poles, there are long periods of time where @@ -4775,7 +4781,8 @@ def SearchRiseSet(body, observer, direction, startTime, limitDays): Parameters ---------- body : Body - The Sun, Moon, or any planet other than the Earth. + The Sun, Moon, any planet other than the Earth, or a user-defined star + that was created by a call to #DefineStar. observer : Observer The location where observation takes place. direction : Direction @@ -4808,9 +4815,9 @@ def SearchRiseSet(body, observer, direction, startTime, limitDays): def SearchAltitude(body, observer, direction, startTime, limitDays, altitude): - """Finds the next time a body reaches a given altitude. + """Finds the next time the center of a body passes through a given altitude. - Finds when the given body ascends or descends through a given + Finds when the center of the given body ascends or descends through a given altitude angle, as seen by an observer at the specified location on the Earth. By using the appropriate combination of `direction` and `altitude` parameters, this function can be used to find when civil, nautical, or astronomical twilight @@ -4826,10 +4833,25 @@ def SearchAltitude(body, observer, direction, startTime, limitDays, altitude): Astronomical twilight uses -18 degrees as the `altitude` value. + By convention for twilight time calculations, the altitude is not corrected for + atmospheric refraction. This is because the target altitudes are below the horizon, + and refraction is not directly observable. + + `SearchAltitude` is not intended to find rise/set times of a body for two reasons: + (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. + (2) Rise/set times are affected significantly by atmospheric refraction. + Therefore, it is better to use #SearchRiseSet to find rise/set times, which + corrects for both of these considerations. + + `SearchAltitude` will not work reliably for altitudes at or near the body's + maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude + angles, use #SearchHourAngle. + Parameters ---------- body : Body - The Sun, Moon, or any planet other than the Earth. + The Sun, Moon, any planet other than the Earth, + or a user-defined star that was created by a call to #DefineStar. observer : Observer The location where observation takes place. direction : Direction diff --git a/generate/template/astronomy.ts b/generate/template/astronomy.ts index 3f27ed22..a8141a88 100644 --- a/generate/template/astronomy.ts +++ b/generate/template/astronomy.ts @@ -4422,18 +4422,32 @@ function BodyRadiusAu(body: Body): number { } /** - * @brief Finds the next rise or set time for a body. + * @brief Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. * - * Finds a rise or set time for the given body as - * seen by an observer at the specified location on the Earth. - * Rise time is defined as the moment when the top of the body - * is observed to first appear above the horizon in the east. - * Set time is defined as the moment the top of the body - * is observed to sink below the horizon in the west. - * The times are adjusted for typical atmospheric refraction conditions. + * This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. + * Rise time is when the body first starts to be visible above the horizon. + * For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. + * Set time is the moment when the body appears to vanish below the horizon. + * Therefore, this function adjusts for the apparent angular radius of the observed body + * (significant only for the Sun and Moon). + * + * This function corrects for a typical value of atmospheric refraction, which causes celestial + * bodies to appear higher above the horizon than they would if the Earth had no atmosphere. + * Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based + * on air temperature, pressure, and humidity; such weather-based conditions are outside + * the scope of Astronomy Engine. + * + * Note that rise or set may not occur in every 24 hour period. + * For example, near the Earth's poles, there are long periods of time where + * the Sun stays below the horizon, never rising. + * Also, it is possible for the Moon to rise just before midnight but not set during the subsequent 24-hour day. + * This is because the Moon sets nearly an hour later each day due to orbiting the Earth a + * significant amount during each rotation of the Earth. + * Therefore callers must not assume that the function will always succeed. * * @param {Body} body - * The body to find the rise or set time for. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. @@ -4471,7 +4485,7 @@ export function SearchRiseSet( } /** - * @brief Finds the next time a body reaches a given altitude. + * @brief Finds the next time the center of a body passes through a given altitude. * * Finds when the given body ascends or descends through a given * altitude angle, as seen by an observer at the specified location on the Earth. @@ -4489,9 +4503,23 @@ export function SearchRiseSet( * * Astronomical twilight uses -18 degrees as the `altitude` value. * + * By convention for twilight time calculations, the altitude is not corrected for + * atmospheric refraction. This is because the target altitudes are below the horizon, + * and refraction is not directly observable. + * + * `SearchAltitude` is not intended to find rise/set times of a body for two reasons: + * (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. + * (2) Rise/set times are affected significantly by atmospheric refraction. + * Therefore, it is better to use {@link SearchRiseSet} to find rise/set times, which + * corrects for both of these considerations. + * + * `SearchAltitude` will not work reliably for altitudes at or near the body's + * maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude + * angles, use {@link SearchHourAngle}. + * * @param {Body} body - * The body for which to find the altitude event. - * Can be the Sun, Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. @@ -4806,20 +4834,32 @@ export class HourAngleEvent { } /** - * @brief Finds when a body will reach a given hour angle. + * @brief Searches for the time when a celestial body reaches a specified hour angle as seen by an observer on the Earth. + * + * The *hour angle* of a celestial body indicates its position in the sky with respect + * to the Earth's rotation. The hour angle depends on the location of the observer on the Earth. + * The hour angle is 0 when the body reaches its highest angle above the horizon in a given day. + * The hour angle increases by 1 unit for every sidereal hour that passes after that point, up + * to 24 sidereal hours when it reaches the highest point again. So the hour angle indicates + * the number of hours that have passed since the most recent time that the body has culminated, + * or reached its highest point. + * + * This function searches for the next or previous time a celestial body reaches the given hour angle + * relative to the date and time specified by `dateStart`. + * To find when a body culminates, pass 0 for `hourAngle`. + * To find when a body reaches its lowest point in the sky, pass 12 for `hourAngle`. * - * Finds the next time the given body is seen to reach the specified - * hour angle - * by the given observer. - * Providing `hourAngle` = 0 finds the next maximum altitude event (culmination). - * Providing `hourAngle` = 12 finds the next minimum altitude event. * Note that, especially close to the Earth's poles, a body as seen on a given day * may always be above the horizon or always below the horizon, so the caller cannot * assume that a culminating object is visible nor that an object is below the horizon * at its minimum altitude. * + * The function returns the date and time, along with the horizontal coordinates + * of the body at that time, as seen by the given observer. + * * @param {Body} body - * A celestial body other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. diff --git a/source/c/README.md b/source/c/README.md index d9e4c33c..e3daf385 100644 --- a/source/c/README.md +++ b/source/c/README.md @@ -2379,11 +2379,11 @@ If the search does not converge within 20 iterations, it will fail with status c ### Astronomy_SearchAltitude(body, observer, direction, startTime, limitDays, altitude) ⇒ [`astro_search_result_t`](#astro_search_result_t) -**Finds the next time a body reaches a given altitude.** +**Finds the next time the center of a body passes through a given altitude.** -Finds when the given body ascends or descends through a given altitude angle, as seen by an observer at the specified location on the Earth. By using the appropriate combination of `direction` and `altitude` parameters, this function can be used to find when civil, nautical, or astronomical twilight begins (dawn) or ends (dusk). +Finds when the center of the given body ascends or descends through a given altitude angle, as seen by an observer at the specified location on the Earth. By using the appropriate combination of `direction` and `altitude` parameters, this function can be used to find when civil, nautical, or astronomical twilight begins (dawn) or ends (dusk). Civil dawn begins before sunrise when the Sun ascends through 6 degrees below the horizon. To find civil dawn, pass `DIRECTION_RISE` for `direction` and -6 for `altitude`. @@ -2393,6 +2393,12 @@ Nautical twilight is similar to civil twilight, only the `altitude` value should Astronomical twilight uses -18 degrees as the `altitude` value. +By convention for twilight time calculations, the altitude is not corrected for atmospheric refraction. This is because the target altitudes are below the horizon, and refraction is not directly observable. + +`Astronomy_SearchAltitude` is not intended to find rise/set times of a body for two reasons: (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. (2) Rise/set times are affected significantly by atmospheric refraction. Therefore, it is better to use [`Astronomy_SearchRiseSet`](#Astronomy_SearchRiseSet) to find rise/set times, which corrects for both of these considerations. + +`Astronomy_SearchAltitude` will not work reliably for altitudes at or near the body's maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude angles, use [`Astronomy_SearchHourAngleEx`](#Astronomy_SearchHourAngleEx). + **Returns:** On success, the `status` field in the returned structure contains `ASTRO_SUCCESS` and the `time` field contains the date and time of the requested altitude event. If the `status` field contains `ASTRO_SEARCH_FAILURE`, it means the altitude event does not occur within `limitDays` days of `startTime`. This is a normal condition, not an error. Any other value of `status` indicates an error of some kind. @@ -2401,7 +2407,7 @@ Astronomical twilight uses -18 degrees as the `altitude` value. | Type | Parameter | Description | | --- | --- | --- | -| [`astro_body_t`](#astro_body_t) | `body` | The Sun, Moon, or any planet other than the Earth. | +| [`astro_body_t`](#astro_body_t) | `body` | The Sun, Moon, any planet other than the Earth, or a user-defined star that was created by a call to [`Astronomy_DefineStar`](#Astronomy_DefineStar). | | [`astro_observer_t`](#astro_observer_t) | `observer` | The location where observation takes place. You can create an observer structure by calling [`Astronomy_MakeObserver`](#Astronomy_MakeObserver). | | [`astro_direction_t`](#astro_direction_t) | `direction` | Either `DIRECTION_RISE` to find when the body ascends through the altitude, or `DIRECTION_SET` for when the body descends through the altitude. | | [`astro_time_t`](#astro_time_t) | `startTime` | The date and time at which to start the search. | @@ -2460,7 +2466,7 @@ On success, the function reports the date and time, along with the horizontal co | Type | Parameter | Description | | --- | --- | --- | -| [`astro_body_t`](#astro_body_t) | `body` | The celestial body, which can the Sun, the Moon, or any planet other than the Earth. | +| [`astro_body_t`](#astro_body_t) | `body` | The Sun, Moon, any planet other than the Earth, or a user-defined star that was created by a call to [`Astronomy_DefineStar`](#Astronomy_DefineStar). | | [`astro_observer_t`](#astro_observer_t) | `observer` | Indicates a location on or near the surface of the Earth where the observer is located. Call [`Astronomy_MakeObserver`](#Astronomy_MakeObserver) to create an observer structure. | | `double` | `hourAngle` | An hour angle value in the range [0, 24) indicating the number of sidereal hours after the body's most recent culmination. | | [`astro_time_t`](#astro_time_t) | `startTime` | The date and time at which to start the search. | @@ -2757,9 +2763,9 @@ Certain astronomical events are defined in terms of relative longitude between t -This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. Rise time is when the body first starts to be visible above the horizon. For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. Set time is the moment when the body appears to vanish below the horizon. +This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. Rise time is when the body first starts to be visible above the horizon. For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. Set time is the moment when the body appears to vanish below the horizon. Therefore, this function adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon). -This function corrects for typical atmospheric refraction, which causes celestial bodies to appear higher above the horizon than they would if the Earth had no atmosphere. It also adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon). +This function corrects for a typical value of atmospheric refraction, which causes celestial bodies to appear higher above the horizon than they would if the Earth had no atmosphere. Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based on air temperature, pressure, and humidity; such weather-based conditions are outside the scope of Astronomy Engine. Note that rise or set may not occur in every 24 hour period. For example, near the Earth's poles, there are long periods of time where the Sun stays below the horizon, never rising. Also, it is possible for the Moon to rise just before midnight but not set during the subsequent 24-hour day. This is because the Moon sets nearly an hour later each day due to orbiting the Earth a significant amount during each rotation of the Earth. Therefore callers must not assume that the function will always succeed. @@ -2771,7 +2777,7 @@ Note that rise or set may not occur in every 24 hour period. For example, near t | Type | Parameter | Description | | --- | --- | --- | -| [`astro_body_t`](#astro_body_t) | `body` | The Sun, Moon, or any planet other than the Earth. | +| [`astro_body_t`](#astro_body_t) | `body` | The Sun, Moon, any planet other than the Earth, or a user-defined star that was created by a call to [`Astronomy_DefineStar`](#Astronomy_DefineStar). | | [`astro_observer_t`](#astro_observer_t) | `observer` | The location where observation takes place. You can create an observer structure by calling [`Astronomy_MakeObserver`](#Astronomy_MakeObserver). | | [`astro_direction_t`](#astro_direction_t) | `direction` | Either `DIRECTION_RISE` to find a rise time or `DIRECTION_SET` to find a set time. | | [`astro_time_t`](#astro_time_t) | `startTime` | The date and time at which to start the search. | diff --git a/source/c/astronomy.c b/source/c/astronomy.c index 486e8ee9..683f2f2d 100644 --- a/source/c/astronomy.c +++ b/source/c/astronomy.c @@ -7679,8 +7679,7 @@ astro_search_result_t Astronomy_SearchRelativeLongitude(astro_body_t body, doubl } /** - * @brief - * Searches for the time when a celestial body reaches a specified hour angle as seen by an observer on the Earth. + * @brief Searches for the time when a celestial body reaches a specified hour angle as seen by an observer on the Earth. * * The *hour angle* of a celestial body indicates its position in the sky with respect * to the Earth's rotation. The hour angle depends on the location of the observer on the Earth. @@ -7704,7 +7703,8 @@ astro_search_result_t Astronomy_SearchRelativeLongitude(astro_body_t body, doubl * of the body at that time, as seen by the given observer. * * @param body - * The celestial body, which can the Sun, the Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to #Astronomy_DefineStar. * * @param observer * Indicates a location on or near the surface of the Earth where the observer is located. @@ -8172,17 +8172,20 @@ static astro_search_result_t InternalSearchAltitude( /** - * @brief - * Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. + * @brief Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. * * This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. * Rise time is when the body first starts to be visible above the horizon. * For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. * Set time is the moment when the body appears to vanish below the horizon. + * Therefore, this function adjusts for the apparent angular radius of the observed body + * (significant only for the Sun and Moon). * - * This function corrects for typical atmospheric refraction, which causes celestial + * This function corrects for a typical value of atmospheric refraction, which causes celestial * bodies to appear higher above the horizon than they would if the Earth had no atmosphere. - * It also adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon). + * Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based + * on air temperature, pressure, and humidity; such weather-based conditions are outside + * the scope of Astronomy Engine. * * Note that rise or set may not occur in every 24 hour period. * For example, near the Earth's poles, there are long periods of time where @@ -8193,7 +8196,8 @@ static astro_search_result_t InternalSearchAltitude( * Therefore callers must not assume that the function will always succeed. * * @param body - * The Sun, Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to #Astronomy_DefineStar. * * @param observer * The location where observation takes place. @@ -8242,9 +8246,9 @@ astro_search_result_t Astronomy_SearchRiseSet( /** - * @brief Finds the next time a body reaches a given altitude. + * @brief Finds the next time the center of a body passes through a given altitude. * - * Finds when the given body ascends or descends through a given + * Finds when the center of the given body ascends or descends through a given * altitude angle, as seen by an observer at the specified location on the Earth. * By using the appropriate combination of `direction` and `altitude` parameters, * this function can be used to find when civil, nautical, or astronomical twilight @@ -8260,8 +8264,23 @@ astro_search_result_t Astronomy_SearchRiseSet( * * Astronomical twilight uses -18 degrees as the `altitude` value. * + * By convention for twilight time calculations, the altitude is not corrected for + * atmospheric refraction. This is because the target altitudes are below the horizon, + * and refraction is not directly observable. + * + * `Astronomy_SearchAltitude` is not intended to find rise/set times of a body for two reasons: + * (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. + * (2) Rise/set times are affected significantly by atmospheric refraction. + * Therefore, it is better to use #Astronomy_SearchRiseSet to find rise/set times, which + * corrects for both of these considerations. + * + * `Astronomy_SearchAltitude` will not work reliably for altitudes at or near the body's + * maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude + * angles, use #Astronomy_SearchHourAngleEx. + * * @param body - * The Sun, Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to #Astronomy_DefineStar. * * @param observer * The location where observation takes place. diff --git a/source/csharp/README.md b/source/csharp/README.md index 01fda8f2..35488077 100644 --- a/source/csharp/README.md +++ b/source/csharp/README.md @@ -1749,9 +1749,9 @@ If the search does not converge within 20 iterations, it will throw an exception ### Astronomy.SearchAltitude(body, observer, direction, startTime, limitDays, altitude) ⇒ [`AstroTime`](#AstroTime) -**Finds the next time a body reaches a given altitude.** +**Finds the next time the center of a body passes through a given altitude.** -Finds when the given body ascends or descends through a given +Finds when the center of the given body ascends or descends through a given altitude angle, as seen by an observer at the specified location on the Earth. By using the appropriate combination of `direction` and `altitude` parameters, this function can be used to find when civil, nautical, or astronomical twilight @@ -1767,9 +1767,23 @@ Nautical twilight is similar to civil twilight, only the `altitude` value should Astronomical twilight uses -18 degrees as the `altitude` value. +By convention for twilight time calculations, the altitude is not corrected for +atmospheric refraction. This is because the target altitudes are below the horizon, +and refraction is not directly observable. + +`SearchAltitude` is not intended to find rise/set times of a body for two reasons: +(1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. +(2) Rise/set times are affected significantly by atmospheric refraction. +Therefore, it is better to use [`Astronomy.SearchRiseSet`](#Astronomy.SearchRiseSet) to find rise/set times, which +corrects for both of these considerations. + +`SearchAltitude` will not work reliably for altitudes at or near the body's +maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude +angles, use [`Astronomy.SearchHourAngle`](#Astronomy.SearchHourAngle). + | Type | Parameter | Description | | --- | --- | --- | -| [`Body`](#Body) | `body` | The Sun, Moon, or any planet other than the Earth. | +| [`Body`](#Body) | `body` | The Sun, Moon, any planet other than the Earth, or a user-defined star that was created by a call to [`Astronomy.DefineStar`](#Astronomy.DefineStar). | | [`Observer`](#Observer) | `observer` | The location where observation takes place. | | [`Direction`](#Direction) | `direction` | Either `Direction.Rise` to find an ascending altitude event or `Direction.Set` to find a descending altitude event. | | [`AstroTime`](#AstroTime) | `startTime` | The date and time at which to start the search. | @@ -1824,7 +1838,7 @@ of the body at that time, as seen by the given observer. | Type | Parameter | Description | | --- | --- | --- | -| [`Body`](#Body) | `body` | The celestial body, which can the Sun, the Moon, or any planet other than the Earth. | +| [`Body`](#Body) | `body` | The Sun, Moon, any planet other than the Earth, or a user-defined star that was created by a call to [`Astronomy.DefineStar`](#Astronomy.DefineStar). | | [`Observer`](#Observer) | `observer` | Indicates a location on or near the surface of the Earth where the observer is located. | | `double` | `hourAngle` | An hour angle value in the range [0, 24) indicating the number of sidereal hours after the body's most recent culmination. | | [`AstroTime`](#AstroTime) | `startTime` | The date and time at which to start the search. | @@ -2092,10 +2106,14 @@ This function finds the next rise or set time of the Sun, Moon, or planet other Rise time is when the body first starts to be visible above the horizon. For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. Set time is the moment when the body appears to vanish below the horizon. +Therefore, this function adjusts for the apparent angular radius of the observed body +(significant only for the Sun and Moon). -This function corrects for typical atmospheric refraction, which causes celestial +This function corrects for a typical value of atmospheric refraction, which causes celestial bodies to appear higher above the horizon than they would if the Earth had no atmosphere. -It also adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon). +Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based +on air temperature, pressure, and humidity; such weather-based conditions are outside +the scope of Astronomy Engine. Note that rise or set may not occur in every 24 hour period. For example, near the Earth's poles, there are long periods of time where @@ -2107,7 +2125,7 @@ Therefore callers must not assume that the function will always succeed. | Type | Parameter | Description | | --- | --- | --- | -| [`Body`](#Body) | `body` | The Sun, Moon, or any planet other than the Earth. | +| [`Body`](#Body) | `body` | The Sun, Moon, any planet other than the Earth, or a user-defined star that was created by a call to [`Astronomy.DefineStar`](#Astronomy.DefineStar). | | [`Observer`](#Observer) | `observer` | The location where observation takes place. | | [`Direction`](#Direction) | `direction` | Either `Direction.Rise` to find a rise time or `Direction.Set` to find a set time. | | [`AstroTime`](#AstroTime) | `startTime` | The date and time at which to start the search. | diff --git a/source/csharp/astronomy.cs b/source/csharp/astronomy.cs index 860f5132..8b77e76b 100644 --- a/source/csharp/astronomy.cs +++ b/source/csharp/astronomy.cs @@ -7392,15 +7392,20 @@ namespace CosineKitty /// /// Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. /// + /// /// /// This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. /// Rise time is when the body first starts to be visible above the horizon. /// For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. /// Set time is the moment when the body appears to vanish below the horizon. + /// Therefore, this function adjusts for the apparent angular radius of the observed body + /// (significant only for the Sun and Moon). /// - /// This function corrects for typical atmospheric refraction, which causes celestial + /// This function corrects for a typical value of atmospheric refraction, which causes celestial /// bodies to appear higher above the horizon than they would if the Earth had no atmosphere. - /// It also adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon). + /// Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based + /// on air temperature, pressure, and humidity; such weather-based conditions are outside + /// the scope of Astronomy Engine. /// /// Note that rise or set may not occur in every 24 hour period. /// For example, near the Earth's poles, there are long periods of time where @@ -7411,7 +7416,10 @@ namespace CosineKitty /// Therefore callers must not assume that the function will always succeed. /// /// - /// The Sun, Moon, or any planet other than the Earth. + /// + /// The Sun, Moon, any planet other than the Earth, + /// or a user-defined star that was created by a call to #Astronomy.DefineStar. + /// /// /// The location where observation takes place. /// @@ -7465,10 +7473,10 @@ namespace CosineKitty } /// - /// Finds the next time a body reaches a given altitude. + /// Finds the next time the center of a body passes through a given altitude. /// /// - /// Finds when the given body ascends or descends through a given + /// Finds when the center of the given body ascends or descends through a given /// altitude angle, as seen by an observer at the specified location on the Earth. /// By using the appropriate combination of `direction` and `altitude` parameters, /// this function can be used to find when civil, nautical, or astronomical twilight @@ -7483,9 +7491,26 @@ namespace CosineKitty /// Nautical twilight is similar to civil twilight, only the `altitude` value should be -12 degrees. /// /// Astronomical twilight uses -18 degrees as the `altitude` value. + /// + /// By convention for twilight time calculations, the altitude is not corrected for + /// atmospheric refraction. This is because the target altitudes are below the horizon, + /// and refraction is not directly observable. + /// + /// `SearchAltitude` is not intended to find rise/set times of a body for two reasons: + /// (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. + /// (2) Rise/set times are affected significantly by atmospheric refraction. + /// Therefore, it is better to use #Astronomy.SearchRiseSet to find rise/set times, which + /// corrects for both of these considerations. + /// + /// `SearchAltitude` will not work reliably for altitudes at or near the body's + /// maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude + /// angles, use #Astronomy.SearchHourAngle. /// /// - /// The Sun, Moon, or any planet other than the Earth. + /// + /// The Sun, Moon, any planet other than the Earth, + /// or a user-defined star that was created by a call to #Astronomy.DefineStar. + /// /// /// The location where observation takes place. /// @@ -7558,7 +7583,8 @@ namespace CosineKitty /// /// /// - /// The celestial body, which can the Sun, the Moon, or any planet other than the Earth. + /// The Sun, Moon, any planet other than the Earth, + /// or a user-defined star that was created by a call to #Astronomy.DefineStar. /// /// /// diff --git a/source/js/README.md b/source/js/README.md index 30d8c1f3..4ce2ea04 100644 --- a/source/js/README.md +++ b/source/js/README.md @@ -2681,7 +2681,7 @@ or even that the function will return `null`, indicating that no event was found **Kind**: global function **Returns**: [AstroTime](#AstroTime) \| null - The date and time of the altitude event, or null if no such event occurs within the specified time window. -**Brief**: Finds the next time a body reaches a given altitude. +**Brief**: Finds the next time the center of a body passes through a given altitude. Finds when the given body ascends or descends through a given altitude angle, as seen by an observer at the specified location on the Earth. @@ -2697,11 +2697,25 @@ To find civil dusk, pass -1 for `direction` and -6 for `altitude`. Nautical twilight is similar to civil twilight, only the `altitude` value should be -12 degrees. -Astronomical twilight uses -18 degrees as the `altitude` value. +Astronomical twilight uses -18 degrees as the `altitude` value. + +By convention for twilight time calculations, the altitude is not corrected for +atmospheric refraction. This is because the target altitudes are below the horizon, +and refraction is not directly observable. + +`SearchAltitude` is not intended to find rise/set times of a body for two reasons: +(1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. +(2) Rise/set times are affected significantly by atmospheric refraction. +Therefore, it is better to use [SearchRiseSet](#SearchRiseSet) to find rise/set times, which +corrects for both of these considerations. + +`SearchAltitude` will not work reliably for altitudes at or near the body's +maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude +angles, use [SearchHourAngle](#SearchHourAngle). | Param | Type | Description | | --- | --- | --- | -| body | [Body](#Body) | The body for which to find the altitude event. Can be the Sun, Moon, or any planet other than the Earth. | +| body | [Body](#Body) | The Sun, Moon, any planet other than the Earth, or a user-defined star that was created by a call to [DefineStar](#DefineStar). | | observer | [Observer](#Observer) | Specifies the geographic coordinates and elevation above sea level of the observer. | | direction | number | Either +1 to find when the body ascends through the altitude, or -1 for when the body descends through the altitude. Any other value will cause an exception to be thrown. | | dateStart | [FlexibleDateTime](#FlexibleDateTime) | The date and time after which the specified altitude event is to be found. | @@ -2735,21 +2749,32 @@ passing in the `peak` value returned from the previous call. ## SearchHourAngle(body, observer, hourAngle, dateStart, direction) ⇒ [HourAngleEvent](#HourAngleEvent) **Kind**: global function -**Brief**: Finds when a body will reach a given hour angle. +**Brief**: Searches for the time when a celestial body reaches a specified hour angle as seen by an observer on the Earth. + +The *hour angle* of a celestial body indicates its position in the sky with respect +to the Earth's rotation. The hour angle depends on the location of the observer on the Earth. +The hour angle is 0 when the body reaches its highest angle above the horizon in a given day. +The hour angle increases by 1 unit for every sidereal hour that passes after that point, up +to 24 sidereal hours when it reaches the highest point again. So the hour angle indicates +the number of hours that have passed since the most recent time that the body has culminated, +or reached its highest point. + +This function searches for the next or previous time a celestial body reaches the given hour angle +relative to the date and time specified by `dateStart`. +To find when a body culminates, pass 0 for `hourAngle`. +To find when a body reaches its lowest point in the sky, pass 12 for `hourAngle`. -Finds the next time the given body is seen to reach the specified -hour angle -by the given observer. -Providing `hourAngle` = 0 finds the next maximum altitude event (culmination). -Providing `hourAngle` = 12 finds the next minimum altitude event. Note that, especially close to the Earth's poles, a body as seen on a given day may always be above the horizon or always below the horizon, so the caller cannot assume that a culminating object is visible nor that an object is below the horizon -at its minimum altitude. +at its minimum altitude. + +The function returns the date and time, along with the horizontal coordinates +of the body at that time, as seen by the given observer. | Param | Type | Description | | --- | --- | --- | -| body | [Body](#Body) | A celestial body other than the Earth. | +| body | [Body](#Body) | The Sun, Moon, any planet other than the Earth, or a user-defined star that was created by a call to [DefineStar](#DefineStar). | | observer | [Observer](#Observer) | Specifies the geographic coordinates and elevation above sea level of the observer. | | hourAngle | number | The hour angle expressed in sidereal hours for which the caller seeks to find the body attain. The value must be in the range [0, 24). The hour angle represents the number of sidereal hours that have elapsed since the most recent time the body crossed the observer's local meridian. This specifying `hourAngle` = 0 finds the moment in time the body reaches the highest angular altitude in a given sidereal day. | | dateStart | [FlexibleDateTime](#FlexibleDateTime) | The date and time after which the desired hour angle crossing event is to be found. | @@ -2990,19 +3015,32 @@ This means the Earth and the other planet are on opposite sides of the Sun. **Kind**: global function **Returns**: [AstroTime](#AstroTime) \| null - The date and time of the rise or set event, or null if no such event occurs within the specified time window. -**Brief**: Finds the next rise or set time for a body. +**Brief**: Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. -Finds a rise or set time for the given body as -seen by an observer at the specified location on the Earth. -Rise time is defined as the moment when the top of the body -is observed to first appear above the horizon in the east. -Set time is defined as the moment the top of the body -is observed to sink below the horizon in the west. -The times are adjusted for typical atmospheric refraction conditions. +This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. +Rise time is when the body first starts to be visible above the horizon. +For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. +Set time is the moment when the body appears to vanish below the horizon. +Therefore, this function adjusts for the apparent angular radius of the observed body +(significant only for the Sun and Moon). + +This function corrects for a typical value of atmospheric refraction, which causes celestial +bodies to appear higher above the horizon than they would if the Earth had no atmosphere. +Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based +on air temperature, pressure, and humidity; such weather-based conditions are outside +the scope of Astronomy Engine. + +Note that rise or set may not occur in every 24 hour period. +For example, near the Earth's poles, there are long periods of time where +the Sun stays below the horizon, never rising. +Also, it is possible for the Moon to rise just before midnight but not set during the subsequent 24-hour day. +This is because the Moon sets nearly an hour later each day due to orbiting the Earth a +significant amount during each rotation of the Earth. +Therefore callers must not assume that the function will always succeed. | Param | Type | Description | | --- | --- | --- | -| body | [Body](#Body) | The body to find the rise or set time for. | +| body | [Body](#Body) | The Sun, Moon, any planet other than the Earth, or a user-defined star that was created by a call to [DefineStar](#DefineStar). | | observer | [Observer](#Observer) | Specifies the geographic coordinates and elevation above sea level of the observer. | | direction | number | Either +1 to find rise time or -1 to find set time. Any other value will cause an exception to be thrown. | | dateStart | [FlexibleDateTime](#FlexibleDateTime) | The date and time after which the specified rise or set time is to be found. | diff --git a/source/js/astronomy.browser.js b/source/js/astronomy.browser.js index 12cfcaa8..6e0aa781 100644 --- a/source/js/astronomy.browser.js +++ b/source/js/astronomy.browser.js @@ -4887,18 +4887,32 @@ function BodyRadiusAu(body) { } } /** - * @brief Finds the next rise or set time for a body. + * @brief Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. * - * Finds a rise or set time for the given body as - * seen by an observer at the specified location on the Earth. - * Rise time is defined as the moment when the top of the body - * is observed to first appear above the horizon in the east. - * Set time is defined as the moment the top of the body - * is observed to sink below the horizon in the west. - * The times are adjusted for typical atmospheric refraction conditions. + * This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. + * Rise time is when the body first starts to be visible above the horizon. + * For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. + * Set time is the moment when the body appears to vanish below the horizon. + * Therefore, this function adjusts for the apparent angular radius of the observed body + * (significant only for the Sun and Moon). + * + * This function corrects for a typical value of atmospheric refraction, which causes celestial + * bodies to appear higher above the horizon than they would if the Earth had no atmosphere. + * Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based + * on air temperature, pressure, and humidity; such weather-based conditions are outside + * the scope of Astronomy Engine. + * + * Note that rise or set may not occur in every 24 hour period. + * For example, near the Earth's poles, there are long periods of time where + * the Sun stays below the horizon, never rising. + * Also, it is possible for the Moon to rise just before midnight but not set during the subsequent 24-hour day. + * This is because the Moon sets nearly an hour later each day due to orbiting the Earth a + * significant amount during each rotation of the Earth. + * Therefore callers must not assume that the function will always succeed. * * @param {Body} body - * The body to find the rise or set time for. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. @@ -4930,7 +4944,7 @@ function SearchRiseSet(body, observer, direction, dateStart, limitDays) { } exports.SearchRiseSet = SearchRiseSet; /** - * @brief Finds the next time a body reaches a given altitude. + * @brief Finds the next time the center of a body passes through a given altitude. * * Finds when the given body ascends or descends through a given * altitude angle, as seen by an observer at the specified location on the Earth. @@ -4948,9 +4962,23 @@ exports.SearchRiseSet = SearchRiseSet; * * Astronomical twilight uses -18 degrees as the `altitude` value. * + * By convention for twilight time calculations, the altitude is not corrected for + * atmospheric refraction. This is because the target altitudes are below the horizon, + * and refraction is not directly observable. + * + * `SearchAltitude` is not intended to find rise/set times of a body for two reasons: + * (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. + * (2) Rise/set times are affected significantly by atmospheric refraction. + * Therefore, it is better to use {@link SearchRiseSet} to find rise/set times, which + * corrects for both of these considerations. + * + * `SearchAltitude` will not work reliably for altitudes at or near the body's + * maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude + * angles, use {@link SearchHourAngle}. + * * @param {Body} body - * The body for which to find the altitude event. - * Can be the Sun, Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. @@ -5201,20 +5229,32 @@ class HourAngleEvent { } exports.HourAngleEvent = HourAngleEvent; /** - * @brief Finds when a body will reach a given hour angle. + * @brief Searches for the time when a celestial body reaches a specified hour angle as seen by an observer on the Earth. + * + * The *hour angle* of a celestial body indicates its position in the sky with respect + * to the Earth's rotation. The hour angle depends on the location of the observer on the Earth. + * The hour angle is 0 when the body reaches its highest angle above the horizon in a given day. + * The hour angle increases by 1 unit for every sidereal hour that passes after that point, up + * to 24 sidereal hours when it reaches the highest point again. So the hour angle indicates + * the number of hours that have passed since the most recent time that the body has culminated, + * or reached its highest point. + * + * This function searches for the next or previous time a celestial body reaches the given hour angle + * relative to the date and time specified by `dateStart`. + * To find when a body culminates, pass 0 for `hourAngle`. + * To find when a body reaches its lowest point in the sky, pass 12 for `hourAngle`. * - * Finds the next time the given body is seen to reach the specified - * hour angle - * by the given observer. - * Providing `hourAngle` = 0 finds the next maximum altitude event (culmination). - * Providing `hourAngle` = 12 finds the next minimum altitude event. * Note that, especially close to the Earth's poles, a body as seen on a given day * may always be above the horizon or always below the horizon, so the caller cannot * assume that a culminating object is visible nor that an object is below the horizon * at its minimum altitude. * + * The function returns the date and time, along with the horizontal coordinates + * of the body at that time, as seen by the given observer. + * * @param {Body} body - * A celestial body other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. diff --git a/source/js/astronomy.d.ts b/source/js/astronomy.d.ts index 53f23639..33f84796 100644 --- a/source/js/astronomy.d.ts +++ b/source/js/astronomy.d.ts @@ -1570,18 +1570,32 @@ export declare function SearchMoonQuarter(dateStart: FlexibleDateTime): MoonQuar */ export declare function NextMoonQuarter(mq: MoonQuarter): MoonQuarter; /** - * @brief Finds the next rise or set time for a body. + * @brief Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. * - * Finds a rise or set time for the given body as - * seen by an observer at the specified location on the Earth. - * Rise time is defined as the moment when the top of the body - * is observed to first appear above the horizon in the east. - * Set time is defined as the moment the top of the body - * is observed to sink below the horizon in the west. - * The times are adjusted for typical atmospheric refraction conditions. + * This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. + * Rise time is when the body first starts to be visible above the horizon. + * For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. + * Set time is the moment when the body appears to vanish below the horizon. + * Therefore, this function adjusts for the apparent angular radius of the observed body + * (significant only for the Sun and Moon). + * + * This function corrects for a typical value of atmospheric refraction, which causes celestial + * bodies to appear higher above the horizon than they would if the Earth had no atmosphere. + * Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based + * on air temperature, pressure, and humidity; such weather-based conditions are outside + * the scope of Astronomy Engine. + * + * Note that rise or set may not occur in every 24 hour period. + * For example, near the Earth's poles, there are long periods of time where + * the Sun stays below the horizon, never rising. + * Also, it is possible for the Moon to rise just before midnight but not set during the subsequent 24-hour day. + * This is because the Moon sets nearly an hour later each day due to orbiting the Earth a + * significant amount during each rotation of the Earth. + * Therefore callers must not assume that the function will always succeed. * * @param {Body} body - * The body to find the rise or set time for. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. @@ -1609,7 +1623,7 @@ export declare function NextMoonQuarter(mq: MoonQuarter): MoonQuarter; */ export declare function SearchRiseSet(body: Body, observer: Observer, direction: number, dateStart: FlexibleDateTime, limitDays: number): AstroTime | null; /** - * @brief Finds the next time a body reaches a given altitude. + * @brief Finds the next time the center of a body passes through a given altitude. * * Finds when the given body ascends or descends through a given * altitude angle, as seen by an observer at the specified location on the Earth. @@ -1627,9 +1641,23 @@ export declare function SearchRiseSet(body: Body, observer: Observer, direction: * * Astronomical twilight uses -18 degrees as the `altitude` value. * + * By convention for twilight time calculations, the altitude is not corrected for + * atmospheric refraction. This is because the target altitudes are below the horizon, + * and refraction is not directly observable. + * + * `SearchAltitude` is not intended to find rise/set times of a body for two reasons: + * (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. + * (2) Rise/set times are affected significantly by atmospheric refraction. + * Therefore, it is better to use {@link SearchRiseSet} to find rise/set times, which + * corrects for both of these considerations. + * + * `SearchAltitude` will not work reliably for altitudes at or near the body's + * maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude + * angles, use {@link SearchHourAngle}. + * * @param {Body} body - * The body for which to find the altitude event. - * Can be the Sun, Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. @@ -1682,20 +1710,32 @@ export declare class HourAngleEvent { constructor(time: AstroTime, hor: HorizontalCoordinates); } /** - * @brief Finds when a body will reach a given hour angle. + * @brief Searches for the time when a celestial body reaches a specified hour angle as seen by an observer on the Earth. + * + * The *hour angle* of a celestial body indicates its position in the sky with respect + * to the Earth's rotation. The hour angle depends on the location of the observer on the Earth. + * The hour angle is 0 when the body reaches its highest angle above the horizon in a given day. + * The hour angle increases by 1 unit for every sidereal hour that passes after that point, up + * to 24 sidereal hours when it reaches the highest point again. So the hour angle indicates + * the number of hours that have passed since the most recent time that the body has culminated, + * or reached its highest point. + * + * This function searches for the next or previous time a celestial body reaches the given hour angle + * relative to the date and time specified by `dateStart`. + * To find when a body culminates, pass 0 for `hourAngle`. + * To find when a body reaches its lowest point in the sky, pass 12 for `hourAngle`. * - * Finds the next time the given body is seen to reach the specified - * hour angle - * by the given observer. - * Providing `hourAngle` = 0 finds the next maximum altitude event (culmination). - * Providing `hourAngle` = 12 finds the next minimum altitude event. * Note that, especially close to the Earth's poles, a body as seen on a given day * may always be above the horizon or always below the horizon, so the caller cannot * assume that a culminating object is visible nor that an object is below the horizon * at its minimum altitude. * + * The function returns the date and time, along with the horizontal coordinates + * of the body at that time, as seen by the given observer. + * * @param {Body} body - * A celestial body other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. diff --git a/source/js/astronomy.js b/source/js/astronomy.js index bd01bc02..62d9811a 100644 --- a/source/js/astronomy.js +++ b/source/js/astronomy.js @@ -4886,18 +4886,32 @@ function BodyRadiusAu(body) { } } /** - * @brief Finds the next rise or set time for a body. + * @brief Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. * - * Finds a rise or set time for the given body as - * seen by an observer at the specified location on the Earth. - * Rise time is defined as the moment when the top of the body - * is observed to first appear above the horizon in the east. - * Set time is defined as the moment the top of the body - * is observed to sink below the horizon in the west. - * The times are adjusted for typical atmospheric refraction conditions. + * This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. + * Rise time is when the body first starts to be visible above the horizon. + * For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. + * Set time is the moment when the body appears to vanish below the horizon. + * Therefore, this function adjusts for the apparent angular radius of the observed body + * (significant only for the Sun and Moon). + * + * This function corrects for a typical value of atmospheric refraction, which causes celestial + * bodies to appear higher above the horizon than they would if the Earth had no atmosphere. + * Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based + * on air temperature, pressure, and humidity; such weather-based conditions are outside + * the scope of Astronomy Engine. + * + * Note that rise or set may not occur in every 24 hour period. + * For example, near the Earth's poles, there are long periods of time where + * the Sun stays below the horizon, never rising. + * Also, it is possible for the Moon to rise just before midnight but not set during the subsequent 24-hour day. + * This is because the Moon sets nearly an hour later each day due to orbiting the Earth a + * significant amount during each rotation of the Earth. + * Therefore callers must not assume that the function will always succeed. * * @param {Body} body - * The body to find the rise or set time for. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. @@ -4929,7 +4943,7 @@ function SearchRiseSet(body, observer, direction, dateStart, limitDays) { } exports.SearchRiseSet = SearchRiseSet; /** - * @brief Finds the next time a body reaches a given altitude. + * @brief Finds the next time the center of a body passes through a given altitude. * * Finds when the given body ascends or descends through a given * altitude angle, as seen by an observer at the specified location on the Earth. @@ -4947,9 +4961,23 @@ exports.SearchRiseSet = SearchRiseSet; * * Astronomical twilight uses -18 degrees as the `altitude` value. * + * By convention for twilight time calculations, the altitude is not corrected for + * atmospheric refraction. This is because the target altitudes are below the horizon, + * and refraction is not directly observable. + * + * `SearchAltitude` is not intended to find rise/set times of a body for two reasons: + * (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. + * (2) Rise/set times are affected significantly by atmospheric refraction. + * Therefore, it is better to use {@link SearchRiseSet} to find rise/set times, which + * corrects for both of these considerations. + * + * `SearchAltitude` will not work reliably for altitudes at or near the body's + * maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude + * angles, use {@link SearchHourAngle}. + * * @param {Body} body - * The body for which to find the altitude event. - * Can be the Sun, Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. @@ -5200,20 +5228,32 @@ class HourAngleEvent { } exports.HourAngleEvent = HourAngleEvent; /** - * @brief Finds when a body will reach a given hour angle. + * @brief Searches for the time when a celestial body reaches a specified hour angle as seen by an observer on the Earth. + * + * The *hour angle* of a celestial body indicates its position in the sky with respect + * to the Earth's rotation. The hour angle depends on the location of the observer on the Earth. + * The hour angle is 0 when the body reaches its highest angle above the horizon in a given day. + * The hour angle increases by 1 unit for every sidereal hour that passes after that point, up + * to 24 sidereal hours when it reaches the highest point again. So the hour angle indicates + * the number of hours that have passed since the most recent time that the body has culminated, + * or reached its highest point. + * + * This function searches for the next or previous time a celestial body reaches the given hour angle + * relative to the date and time specified by `dateStart`. + * To find when a body culminates, pass 0 for `hourAngle`. + * To find when a body reaches its lowest point in the sky, pass 12 for `hourAngle`. * - * Finds the next time the given body is seen to reach the specified - * hour angle - * by the given observer. - * Providing `hourAngle` = 0 finds the next maximum altitude event (culmination). - * Providing `hourAngle` = 12 finds the next minimum altitude event. * Note that, especially close to the Earth's poles, a body as seen on a given day * may always be above the horizon or always below the horizon, so the caller cannot * assume that a culminating object is visible nor that an object is below the horizon * at its minimum altitude. * + * The function returns the date and time, along with the horizontal coordinates + * of the body at that time, as seen by the given observer. + * * @param {Body} body - * A celestial body other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. diff --git a/source/js/astronomy.ts b/source/js/astronomy.ts index b4bd023b..df2a5cb3 100644 --- a/source/js/astronomy.ts +++ b/source/js/astronomy.ts @@ -5428,18 +5428,32 @@ function BodyRadiusAu(body: Body): number { } /** - * @brief Finds the next rise or set time for a body. + * @brief Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. * - * Finds a rise or set time for the given body as - * seen by an observer at the specified location on the Earth. - * Rise time is defined as the moment when the top of the body - * is observed to first appear above the horizon in the east. - * Set time is defined as the moment the top of the body - * is observed to sink below the horizon in the west. - * The times are adjusted for typical atmospheric refraction conditions. + * This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. + * Rise time is when the body first starts to be visible above the horizon. + * For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. + * Set time is the moment when the body appears to vanish below the horizon. + * Therefore, this function adjusts for the apparent angular radius of the observed body + * (significant only for the Sun and Moon). + * + * This function corrects for a typical value of atmospheric refraction, which causes celestial + * bodies to appear higher above the horizon than they would if the Earth had no atmosphere. + * Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based + * on air temperature, pressure, and humidity; such weather-based conditions are outside + * the scope of Astronomy Engine. + * + * Note that rise or set may not occur in every 24 hour period. + * For example, near the Earth's poles, there are long periods of time where + * the Sun stays below the horizon, never rising. + * Also, it is possible for the Moon to rise just before midnight but not set during the subsequent 24-hour day. + * This is because the Moon sets nearly an hour later each day due to orbiting the Earth a + * significant amount during each rotation of the Earth. + * Therefore callers must not assume that the function will always succeed. * * @param {Body} body - * The body to find the rise or set time for. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. @@ -5477,7 +5491,7 @@ export function SearchRiseSet( } /** - * @brief Finds the next time a body reaches a given altitude. + * @brief Finds the next time the center of a body passes through a given altitude. * * Finds when the given body ascends or descends through a given * altitude angle, as seen by an observer at the specified location on the Earth. @@ -5495,9 +5509,23 @@ export function SearchRiseSet( * * Astronomical twilight uses -18 degrees as the `altitude` value. * + * By convention for twilight time calculations, the altitude is not corrected for + * atmospheric refraction. This is because the target altitudes are below the horizon, + * and refraction is not directly observable. + * + * `SearchAltitude` is not intended to find rise/set times of a body for two reasons: + * (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. + * (2) Rise/set times are affected significantly by atmospheric refraction. + * Therefore, it is better to use {@link SearchRiseSet} to find rise/set times, which + * corrects for both of these considerations. + * + * `SearchAltitude` will not work reliably for altitudes at or near the body's + * maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude + * angles, use {@link SearchHourAngle}. + * * @param {Body} body - * The body for which to find the altitude event. - * Can be the Sun, Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. @@ -5812,20 +5840,32 @@ export class HourAngleEvent { } /** - * @brief Finds when a body will reach a given hour angle. + * @brief Searches for the time when a celestial body reaches a specified hour angle as seen by an observer on the Earth. + * + * The *hour angle* of a celestial body indicates its position in the sky with respect + * to the Earth's rotation. The hour angle depends on the location of the observer on the Earth. + * The hour angle is 0 when the body reaches its highest angle above the horizon in a given day. + * The hour angle increases by 1 unit for every sidereal hour that passes after that point, up + * to 24 sidereal hours when it reaches the highest point again. So the hour angle indicates + * the number of hours that have passed since the most recent time that the body has culminated, + * or reached its highest point. + * + * This function searches for the next or previous time a celestial body reaches the given hour angle + * relative to the date and time specified by `dateStart`. + * To find when a body culminates, pass 0 for `hourAngle`. + * To find when a body reaches its lowest point in the sky, pass 12 for `hourAngle`. * - * Finds the next time the given body is seen to reach the specified - * hour angle - * by the given observer. - * Providing `hourAngle` = 0 finds the next maximum altitude event (culmination). - * Providing `hourAngle` = 12 finds the next minimum altitude event. * Note that, especially close to the Earth's poles, a body as seen on a given day * may always be above the horizon or always below the horizon, so the caller cannot * assume that a culminating object is visible nor that an object is below the horizon * at its minimum altitude. * + * The function returns the date and time, along with the horizontal coordinates + * of the body at that time, as seen by the given observer. + * * @param {Body} body - * A celestial body other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. diff --git a/source/js/esm/astronomy.js b/source/js/esm/astronomy.js index 3b833bd9..fdd9f170 100644 --- a/source/js/esm/astronomy.js +++ b/source/js/esm/astronomy.js @@ -4826,18 +4826,32 @@ function BodyRadiusAu(body) { } } /** - * @brief Finds the next rise or set time for a body. + * @brief Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. * - * Finds a rise or set time for the given body as - * seen by an observer at the specified location on the Earth. - * Rise time is defined as the moment when the top of the body - * is observed to first appear above the horizon in the east. - * Set time is defined as the moment the top of the body - * is observed to sink below the horizon in the west. - * The times are adjusted for typical atmospheric refraction conditions. + * This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. + * Rise time is when the body first starts to be visible above the horizon. + * For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. + * Set time is the moment when the body appears to vanish below the horizon. + * Therefore, this function adjusts for the apparent angular radius of the observed body + * (significant only for the Sun and Moon). + * + * This function corrects for a typical value of atmospheric refraction, which causes celestial + * bodies to appear higher above the horizon than they would if the Earth had no atmosphere. + * Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based + * on air temperature, pressure, and humidity; such weather-based conditions are outside + * the scope of Astronomy Engine. + * + * Note that rise or set may not occur in every 24 hour period. + * For example, near the Earth's poles, there are long periods of time where + * the Sun stays below the horizon, never rising. + * Also, it is possible for the Moon to rise just before midnight but not set during the subsequent 24-hour day. + * This is because the Moon sets nearly an hour later each day due to orbiting the Earth a + * significant amount during each rotation of the Earth. + * Therefore callers must not assume that the function will always succeed. * * @param {Body} body - * The body to find the rise or set time for. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. @@ -4868,7 +4882,7 @@ export function SearchRiseSet(body, observer, direction, dateStart, limitDays) { return InternalSearchAltitude(body, observer, direction, dateStart, limitDays, body_radius_au, -REFRACTION_NEAR_HORIZON); } /** - * @brief Finds the next time a body reaches a given altitude. + * @brief Finds the next time the center of a body passes through a given altitude. * * Finds when the given body ascends or descends through a given * altitude angle, as seen by an observer at the specified location on the Earth. @@ -4886,9 +4900,23 @@ export function SearchRiseSet(body, observer, direction, dateStart, limitDays) { * * Astronomical twilight uses -18 degrees as the `altitude` value. * + * By convention for twilight time calculations, the altitude is not corrected for + * atmospheric refraction. This is because the target altitudes are below the horizon, + * and refraction is not directly observable. + * + * `SearchAltitude` is not intended to find rise/set times of a body for two reasons: + * (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. + * (2) Rise/set times are affected significantly by atmospheric refraction. + * Therefore, it is better to use {@link SearchRiseSet} to find rise/set times, which + * corrects for both of these considerations. + * + * `SearchAltitude` will not work reliably for altitudes at or near the body's + * maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude + * angles, use {@link SearchHourAngle}. + * * @param {Body} body - * The body for which to find the altitude event. - * Can be the Sun, Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. @@ -5137,20 +5165,32 @@ export class HourAngleEvent { } } /** - * @brief Finds when a body will reach a given hour angle. + * @brief Searches for the time when a celestial body reaches a specified hour angle as seen by an observer on the Earth. + * + * The *hour angle* of a celestial body indicates its position in the sky with respect + * to the Earth's rotation. The hour angle depends on the location of the observer on the Earth. + * The hour angle is 0 when the body reaches its highest angle above the horizon in a given day. + * The hour angle increases by 1 unit for every sidereal hour that passes after that point, up + * to 24 sidereal hours when it reaches the highest point again. So the hour angle indicates + * the number of hours that have passed since the most recent time that the body has culminated, + * or reached its highest point. + * + * This function searches for the next or previous time a celestial body reaches the given hour angle + * relative to the date and time specified by `dateStart`. + * To find when a body culminates, pass 0 for `hourAngle`. + * To find when a body reaches its lowest point in the sky, pass 12 for `hourAngle`. * - * Finds the next time the given body is seen to reach the specified - * hour angle - * by the given observer. - * Providing `hourAngle` = 0 finds the next maximum altitude event (culmination). - * Providing `hourAngle` = 12 finds the next minimum altitude event. * Note that, especially close to the Earth's poles, a body as seen on a given day * may always be above the horizon or always below the horizon, so the caller cannot * assume that a culminating object is visible nor that an object is below the horizon * at its minimum altitude. * + * The function returns the date and time, along with the horizontal coordinates + * of the body at that time, as seen by the given observer. + * * @param {Body} body - * A celestial body other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to {@link DefineStar}. * * @param {Observer} observer * Specifies the geographic coordinates and elevation above sea level of the observer. diff --git a/source/kotlin/doc/search-altitude.md b/source/kotlin/doc/search-altitude.md index 6e68b80e..36c41729 100644 --- a/source/kotlin/doc/search-altitude.md +++ b/source/kotlin/doc/search-altitude.md @@ -16,6 +16,12 @@ Nautical twilight is similar to civil twilight, only the altitude value should b Astronomical twilight uses -18 degrees as the altitude value. +By convention for twilight time calculations, the altitude is not corrected for atmospheric refraction. This is because the target altitudes are below the horizon, and refraction is not directly observable. + +searchAltitude is not intended to find rise/set times of a body for two reasons: (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. (2) Rise/set times are affected significantly by atmospheric refraction. Therefore, it is better to use [searchRiseSet](search-rise-set.md) to find rise/set times, which corrects for both of these considerations. + +searchAltitude will not work reliably for altitudes at or near the body's maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude angles, use [searchHourAngle](search-hour-angle.md). + #### Return The date and time of the altitude event, or null if no such event occurs within the specified time window. @@ -24,7 +30,7 @@ The date and time of the altitude event, or null if no such event occurs within | | | |---|---| -| body | The Sun, Moon, or any planet other than the Earth. | +| body | The Sun, Moon, any planet other than the Earth, or a user-defined star that was created by a call to [defineStar](define-star.md). | | observer | The location where observation takes place. | | direction | Either [Direction.Rise](-direction/-rise/index.md) to find an ascending altitude event or [Direction.Set](-direction/-set/index.md) to find a descending altitude event. | | startTime | The date and time at which to start the search. | diff --git a/source/kotlin/doc/search-hour-angle.md b/source/kotlin/doc/search-hour-angle.md index 457129f3..7906971c 100644 --- a/source/kotlin/doc/search-hour-angle.md +++ b/source/kotlin/doc/search-hour-angle.md @@ -22,7 +22,7 @@ The time when the body reaches the hour angle, and the horizontal coordinates of | | | |---|---| -| body | The celestial body, which can the Sun, the Moon, or any planet other than the Earth. | +| body | The Sun, Moon, any planet other than the Earth, or a user-defined star that was created by a call to [defineStar](define-star.md). | | observer | A location on or near the surface of the Earth where the observer is located. | | hourAngle | An hour angle value in the range [0, 24) indicating the number of sidereal hours after the body's most recent culmination. | | startTime | The date and time at which to start the search. | diff --git a/source/kotlin/doc/search-local-solar-eclipse.md b/source/kotlin/doc/search-local-solar-eclipse.md index 969739f3..538240a5 100644 --- a/source/kotlin/doc/search-local-solar-eclipse.md +++ b/source/kotlin/doc/search-local-solar-eclipse.md @@ -8,7 +8,7 @@ Searches for a solar eclipse visible at a specific location on the Earth's surfa This function finds the first solar eclipse that occurs after startTime. A solar eclipse may be partial, annular, or total. See [LocalSolarEclipseInfo](-local-solar-eclipse-info/index.md) for more information. -To find a series of solar eclipses, call this function once, then keep calling #Astronomy.NextLocalSolarEclipse as many times as desired, passing in the peak value returned from the previous call. +To find a series of solar eclipses, call this function once, then keep calling [nextLocalSolarEclipse](next-local-solar-eclipse.md) as many times as desired, passing in the peak value returned from the previous call. IMPORTANT: An eclipse reported by this function might be partly or completely invisible to the observer due to the time of day. See [LocalSolarEclipseInfo](-local-solar-eclipse-info/index.md) for more information about this topic. diff --git a/source/kotlin/doc/search-peak-magnitude.md b/source/kotlin/doc/search-peak-magnitude.md index 80cfef41..d95a2ef7 100644 --- a/source/kotlin/doc/search-peak-magnitude.md +++ b/source/kotlin/doc/search-peak-magnitude.md @@ -6,7 +6,7 @@ fun [searchPeakMagnitude](search-peak-magnitude.md)(body: [Body](-body/index.md) Searches for the date and time Venus will next appear brightest as seen from the Earth. -This function searches for the date and time Venus appears brightest as seen from the Earth. Currently only Venus is supported for the body parameter, though this could change in the future. Mercury's peak magnitude occurs at superior conjunction, when it is virtually impossible to see from the Earth, so peak magnitude events have little practical value for that planet. Planets other than Venus and Mercury reach peak magnitude at opposition, which can be found using #Astronomy.SearchRelativeLongitude. The Moon reaches peak magnitude at full moon, which can be found using [searchMoonQuarter](search-moon-quarter.md) or [searchMoonPhase](search-moon-phase.md). The Sun reaches peak magnitude at perihelion, which occurs each year in January. However, the difference is minor and has little practical value. +This function searches for the date and time Venus appears brightest as seen from the Earth. Currently only Venus is supported for the body parameter, though this could change in the future. Mercury's peak magnitude occurs at superior conjunction, when it is virtually impossible to see from the Earth, so peak magnitude events have little practical value for that planet. Planets other than Venus and Mercury reach peak magnitude at opposition, which can be found using [searchRelativeLongitude](search-relative-longitude.md). The Moon reaches peak magnitude at full moon, which can be found using [searchMoonQuarter](search-moon-quarter.md) or [searchMoonPhase](search-moon-phase.md). The Sun reaches peak magnitude at perihelion, which occurs each year in January. However, the difference is minor and has little practical value. ## Parameters diff --git a/source/kotlin/doc/search-rise-set.md b/source/kotlin/doc/search-rise-set.md index 1c25a6ac..19a7059d 100644 --- a/source/kotlin/doc/search-rise-set.md +++ b/source/kotlin/doc/search-rise-set.md @@ -6,9 +6,9 @@ fun [searchRiseSet](search-rise-set.md)(body: [Body](-body/index.md), observer: Searches for the next time a celestial body rises or sets as seen by an observer on the Earth. -This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. Rise time is when the body first starts to be visible above the horizon. For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. Set time is the moment when the body appears to vanish below the horizon. +This function finds the next rise or set time of the Sun, Moon, or planet other than the Earth. Rise time is when the body first starts to be visible above the horizon. For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. Set time is the moment when the body appears to vanish below the horizon. Therefore, this function adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon). -This function corrects for typical atmospheric refraction, which causes celestial bodies to appear higher above the horizon than they would if the Earth had no atmosphere. It also adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon). +This function corrects for a typical value of atmospheric refraction, which causes celestial bodies to appear higher above the horizon than they would if the Earth had no atmosphere. Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based on air temperature, pressure, and humidity; such weather-based conditions are outside the scope of Astronomy Engine. Note that rise or set may not occur in every 24 hour period. For example, near the Earth's poles, there are long periods of time where the Sun stays below the horizon, never rising. Also, it is possible for the Moon to rise just before midnight but not set during the subsequent 24-hour day. This is because the Moon sets nearly an hour later each day due to orbiting the Earth a significant amount during each rotation of the Earth. Therefore callers must not assume that the function will always succeed. @@ -20,7 +20,7 @@ On success, returns the date and time of the rise or set time as requested. If t | | | |---|---| -| body | The Sun, Moon, or any planet other than the Earth. | +| body | The Sun, Moon, any planet other than the Earth, or a user-defined star that was created by a call to [defineStar](define-star.md). | | observer | The location where observation takes place. | | direction | Either [Direction.Rise](-direction/-rise/index.md) to find a rise time or [Direction.Set](-direction/-set/index.md) to find a set time. | | startTime | The date and time at which to start the search. | 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 f4b51e72..a08e23ed 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 @@ -2707,7 +2707,7 @@ fun globalSolarEclipsesAfter(startTime: Time): Sequence * See [LocalSolarEclipseInfo] for more information. * * To find a series of solar eclipses, call this function once, - * then keep calling #Astronomy.NextLocalSolarEclipse as many times as desired, + * then keep calling [nextLocalSolarEclipse] as many times as desired, * passing in the `peak` value returned from the previous call. * * IMPORTANT: An eclipse reported by this function might be partly or @@ -6223,7 +6223,8 @@ fun moonQuartersAfter(startTime: Time): Sequence = * of the body at that time, as seen by the given observer. * * @param body - * The celestial body, which can the Sun, the Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to [defineStar]. * * @param observer * A location on or near the surface of the Earth where the observer is located. @@ -6543,10 +6544,14 @@ private fun internalSearchAltitude( * Rise time is when the body first starts to be visible above the horizon. * For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. * Set time is the moment when the body appears to vanish below the horizon. + * Therefore, this function adjusts for the apparent angular radius of the observed body + * (significant only for the Sun and Moon). * - * This function corrects for typical atmospheric refraction, which causes celestial + * This function corrects for a typical value of atmospheric refraction, which causes celestial * bodies to appear higher above the horizon than they would if the Earth had no atmosphere. - * It also adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon). + * Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based + * on air temperature, pressure, and humidity; such weather-based conditions are outside + * the scope of Astronomy Engine. * * Note that rise or set may not occur in every 24 hour period. * For example, near the Earth's poles, there are long periods of time where @@ -6557,7 +6562,8 @@ private fun internalSearchAltitude( * Therefore callers must not assume that the function will always succeed. * * @param body - * The Sun, Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to [defineStar]. * * @param observer * The location where observation takes place. @@ -6618,8 +6624,23 @@ fun searchRiseSet( * * Astronomical twilight uses -18 degrees as the `altitude` value. * + * By convention for twilight time calculations, the altitude is not corrected for + * atmospheric refraction. This is because the target altitudes are below the horizon, + * and refraction is not directly observable. + * + * `searchAltitude` is not intended to find rise/set times of a body for two reasons: + * (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. + * (2) Rise/set times are affected significantly by atmospheric refraction. + * Therefore, it is better to use [searchRiseSet] to find rise/set times, which + * corrects for both of these considerations. + * + * `searchAltitude` will not work reliably for altitudes at or near the body's + * maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude + * angles, use [searchHourAngle]. + * * @param body - * The Sun, Moon, or any planet other than the Earth. + * The Sun, Moon, any planet other than the Earth, + * or a user-defined star that was created by a call to [defineStar]. * * @param observer * The location where observation takes place. @@ -7165,7 +7186,7 @@ internal fun magnitudeSlope(body: Body, time: Time): Double { * Mercury's peak magnitude occurs at superior conjunction, when it is virtually impossible to see from the Earth, * so peak magnitude events have little practical value for that planet. * Planets other than Venus and Mercury reach peak magnitude at opposition, which can - * be found using #Astronomy.SearchRelativeLongitude. + * be found using [searchRelativeLongitude]. * The Moon reaches peak magnitude at full moon, which can be found using * [searchMoonQuarter] or [searchMoonPhase]. * The Sun reaches peak magnitude at perihelion, which occurs each year in January. diff --git a/source/python/README.md b/source/python/README.md index ed7f61f3..eb1e1211 100644 --- a/source/python/README.md +++ b/source/python/README.md @@ -2823,9 +2823,9 @@ the function returns `None`. ### SearchAltitude(body, observer, direction, startTime, limitDays, altitude) -**Finds the next time a body reaches a given altitude.** +**Finds the next time the center of a body passes through a given altitude.** -Finds when the given body ascends or descends through a given +Finds when the center of the given body ascends or descends through a given altitude angle, as seen by an observer at the specified location on the Earth. By using the appropriate combination of `direction` and `altitude` parameters, this function can be used to find when civil, nautical, or astronomical twilight @@ -2836,10 +2836,21 @@ Civil dusk ends after sunset when the Sun descends through 6 degrees below the h To find civil dusk, pass `Direction.Set` for `direction` and -6 for `altitude`. Nautical twilight is similar to civil twilight, only the `altitude` value should be -12 degrees. Astronomical twilight uses -18 degrees as the `altitude` value. +By convention for twilight time calculations, the altitude is not corrected for +atmospheric refraction. This is because the target altitudes are below the horizon, +and refraction is not directly observable. +`SearchAltitude` is not intended to find rise/set times of a body for two reasons: +(1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. +(2) Rise/set times are affected significantly by atmospheric refraction. +Therefore, it is better to use [`SearchRiseSet`](#SearchRiseSet) to find rise/set times, which +corrects for both of these considerations. +`SearchAltitude` will not work reliably for altitudes at or near the body's +maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude +angles, use [`SearchHourAngle`](#SearchHourAngle). | Type | Parameter | Description | | --- | --- | --- | -| [`Body`](#Body) | `body` | The Sun, Moon, or any planet other than the Earth. | +| [`Body`](#Body) | `body` | The Sun, Moon, any planet other than the Earth, or a user-defined star that was created by a call to [`DefineStar`](#DefineStar). | | [`Observer`](#Observer) | `observer` | The location where observation takes place. | | [`Direction`](#Direction) | `direction` | Either `Direction.Rise` to find an ascending altitude event or `Direction.Set` to find a descending altitude event. | | [`Time`](#Time) | `startTime` | The date and time at which to start the search. | @@ -2897,7 +2908,7 @@ of the body at that time, as seen by the given observer. | Type | Parameter | Description | | --- | --- | --- | -| [`Body`](#Body) | `body` | The celestial body, which can the Sun, the Moon, or any planet other than the Earth. | +| [`Body`](#Body) | `body` | The Sun, Moon, any planet other than the Earth, or a user-defined star that was created by a call to [`DefineStar`](#DefineStar). | | [`Observer`](#Observer) | `observer` | Indicates a location on or near the surface of the Earth where the observer is located. | | `float` | `hourAngle` | An hour angle value in the range [0.0, 24.0) indicating the number of sidereal hours after the body's most recent culmination. | | [`Time`](#Time) | `startTime` | The date and time at which to start the search. | @@ -3167,9 +3178,14 @@ This function finds the next rise or set time of the Sun, Moon, or planet other Rise time is when the body first starts to be visible above the horizon. For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. Set time is the moment when the body appears to vanish below the horizon. +Therefore, this function adjusts for the apparent angular radius of the observed body +(significant only for the Sun and Moon). This function corrects for typical atmospheric refraction, which causes celestial bodies to appear higher above the horizon than they would if the Earth had no atmosphere. It also adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon). +Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based +on air temperature, pressure, and humidity; such weather-based conditions are outside +the scope of Astronomy Engine. Note that rise or set may not occur in every 24 hour period. For example, near the Earth's poles, there are long periods of time where the Sun stays below the horizon, never rising. @@ -3180,7 +3196,7 @@ Therefore callers must not assume that the function will always succeed. | Type | Parameter | Description | | --- | --- | --- | -| [`Body`](#Body) | `body` | The Sun, Moon, or any planet other than the Earth. | +| [`Body`](#Body) | `body` | The Sun, Moon, any planet other than the Earth, or a user-defined star that was created by a call to [`DefineStar`](#DefineStar). | | [`Observer`](#Observer) | `observer` | The location where observation takes place. | | [`Direction`](#Direction) | `direction` | Either `Direction.Rise` to find a rise time or `Direction.Set` to find a set time. | | [`Time`](#Time) | `startTime` | The date and time at which to start the search. | diff --git a/source/python/astronomy/astronomy.py b/source/python/astronomy/astronomy.py index 3bb82e44..c0108ffe 100644 --- a/source/python/astronomy/astronomy.py +++ b/source/python/astronomy/astronomy.py @@ -6531,7 +6531,8 @@ def SearchHourAngle(body, observer, hourAngle, startTime, direction = +1): Parameters ---------- body : Body - The celestial body, which can the Sun, the Moon, or any planet other than the Earth. + The Sun, Moon, any planet other than the Earth, + or a user-defined star that was created by a call to #DefineStar. observer : Observer Indicates a location on or near the surface of the Earth where the observer is located. hourAngle : float @@ -6801,10 +6802,15 @@ def SearchRiseSet(body, observer, direction, startTime, limitDays): Rise time is when the body first starts to be visible above the horizon. For example, sunrise is the moment that the top of the Sun first appears to peek above the horizon. Set time is the moment when the body appears to vanish below the horizon. + Therefore, this function adjusts for the apparent angular radius of the observed body + (significant only for the Sun and Moon). This function corrects for typical atmospheric refraction, which causes celestial bodies to appear higher above the horizon than they would if the Earth had no atmosphere. It also adjusts for the apparent angular radius of the observed body (significant only for the Sun and Moon). + Astronomy Engine uses a correction of 34 arcminutes. Real-world refraction varies based + on air temperature, pressure, and humidity; such weather-based conditions are outside + the scope of Astronomy Engine. Note that rise or set may not occur in every 24 hour period. For example, near the Earth's poles, there are long periods of time where @@ -6817,7 +6823,8 @@ def SearchRiseSet(body, observer, direction, startTime, limitDays): Parameters ---------- body : Body - The Sun, Moon, or any planet other than the Earth. + The Sun, Moon, any planet other than the Earth, or a user-defined star + that was created by a call to #DefineStar. observer : Observer The location where observation takes place. direction : Direction @@ -6850,9 +6857,9 @@ def SearchRiseSet(body, observer, direction, startTime, limitDays): def SearchAltitude(body, observer, direction, startTime, limitDays, altitude): - """Finds the next time a body reaches a given altitude. + """Finds the next time the center of a body passes through a given altitude. - Finds when the given body ascends or descends through a given + Finds when the center of the given body ascends or descends through a given altitude angle, as seen by an observer at the specified location on the Earth. By using the appropriate combination of `direction` and `altitude` parameters, this function can be used to find when civil, nautical, or astronomical twilight @@ -6868,10 +6875,25 @@ def SearchAltitude(body, observer, direction, startTime, limitDays, altitude): Astronomical twilight uses -18 degrees as the `altitude` value. + By convention for twilight time calculations, the altitude is not corrected for + atmospheric refraction. This is because the target altitudes are below the horizon, + and refraction is not directly observable. + + `SearchAltitude` is not intended to find rise/set times of a body for two reasons: + (1) Rise/set times of the Sun or Moon are defined by their topmost visible portion, not their centers. + (2) Rise/set times are affected significantly by atmospheric refraction. + Therefore, it is better to use #SearchRiseSet to find rise/set times, which + corrects for both of these considerations. + + `SearchAltitude` will not work reliably for altitudes at or near the body's + maximum or minimum altitudes. To find the time a body reaches minimum or maximum altitude + angles, use #SearchHourAngle. + Parameters ---------- body : Body - The Sun, Moon, or any planet other than the Earth. + The Sun, Moon, any planet other than the Earth, + or a user-defined star that was created by a call to #DefineStar. observer : Observer The location where observation takes place. direction : Direction