From 972e43e95234c0df8809eab1233c9b554381efe0 Mon Sep 17 00:00:00 2001 From: Don Cross Date: Fri, 19 Jul 2019 21:01:13 -0400 Subject: [PATCH] Python: added documentation for function Illumination. --- generate/template/astronomy.py | 31 +++++++++++++++++++++++++++++++ source/python/README.md | 30 ++++++++++++++++++++++++++++++ source/python/astronomy.py | 31 +++++++++++++++++++++++++++++++ 3 files changed, 92 insertions(+) diff --git a/generate/template/astronomy.py b/generate/template/astronomy.py index 95f5245f..6c57ec35 100644 --- a/generate/template/astronomy.py +++ b/generate/template/astronomy.py @@ -2198,6 +2198,37 @@ def _VisualMagnitude(body, phase, helio_dist, geo_dist): return mag def Illumination(body, time): + """Finds visual magnitude, phase angle, and other illumination information about a celestial body. + + This function calculates information about how bright a celestial body appears from the Earth, + reported as visual magnitude, which is a smaller (or even negative) number for brighter objects, + and a larger number for dimmer objects. + + For bodies other than the Sun, it reports a phase angle, which is the angle in degrees between + the Sun and the Earth, as seen from the center of the body. Phase angle indicates what fraction + of the body appears illuminated as seen from the Earth. For example, when the phase angle is + near zero, it means the body appears "full" as seen from the Earth. A phase angle approaching + 180 degrees means the body appears as a thin crescent as seen from the Earth. A phase angle + of 90 degrees means the body appears "half full". + For the Sun, the phase angle is always reported as 0; the Sun emits light rather than reflecting it, + so it doesn't have a phase angle. + + When the body is Saturn, the returned object contains a field `ring_tilt` that holds + the tilt angle in degrees of Saturn's rings as seen from the Earth. A value of 0 means + the rings appear edge-on, and are thus nearly invisible from the Earth. The `ring_tilt` holds + 0 for all bodies other than Saturn. + + Parameters + ---------- + body : Body + The Sun, Moon, or any planet other than the Earth. + time : Time + The date and time of the observation. + + Returns + ------- + #IlluminationInfo + """ if body == Body.Earth: raise EarthNotAllowedError() earth = _CalcEarth(time) diff --git a/source/python/README.md b/source/python/README.md index 8d54133f..7c366118 100644 --- a/source/python/README.md +++ b/source/python/README.md @@ -633,6 +633,36 @@ for more details. --- + +### Illumination(body, time) + +**Finds visual magnitude, phase angle, and other illumination information about a celestial body.** + +This function calculates information about how bright a celestial body appears from the Earth, +reported as visual magnitude, which is a smaller (or even negative) number for brighter objects, +and a larger number for dimmer objects. +For bodies other than the Sun, it reports a phase angle, which is the angle in degrees between +the Sun and the Earth, as seen from the center of the body. Phase angle indicates what fraction +of the body appears illuminated as seen from the Earth. For example, when the phase angle is +near zero, it means the body appears "full" as seen from the Earth. A phase angle approaching +180 degrees means the body appears as a thin crescent as seen from the Earth. A phase angle +of 90 degrees means the body appears "half full". +For the Sun, the phase angle is always reported as 0; the Sun emits light rather than reflecting it, +so it doesn't have a phase angle. +When the body is Saturn, the returned object contains a field `ring_tilt` that holds +the tilt angle in degrees of Saturn's rings as seen from the Earth. A value of 0 means +the rings appear edge-on, and are thus nearly invisible from the Earth. The `ring_tilt` holds +0 for all bodies other than Saturn. + +| Type | Parameter | Description | +| --- | --- | --- | +| [`Body`](#Body) | `body` | The Sun, Moon, or any planet other than the Earth. | +| [`Time`](#Time) | `time` | The date and time of the observation. | + +### Returns: #IlluminationInfo + +--- + ### LongitudeFromSun(body, time) diff --git a/source/python/astronomy.py b/source/python/astronomy.py index 91997d13..c0e1357b 100644 --- a/source/python/astronomy.py +++ b/source/python/astronomy.py @@ -4259,6 +4259,37 @@ def _VisualMagnitude(body, phase, helio_dist, geo_dist): return mag def Illumination(body, time): + """Finds visual magnitude, phase angle, and other illumination information about a celestial body. + + This function calculates information about how bright a celestial body appears from the Earth, + reported as visual magnitude, which is a smaller (or even negative) number for brighter objects, + and a larger number for dimmer objects. + + For bodies other than the Sun, it reports a phase angle, which is the angle in degrees between + the Sun and the Earth, as seen from the center of the body. Phase angle indicates what fraction + of the body appears illuminated as seen from the Earth. For example, when the phase angle is + near zero, it means the body appears "full" as seen from the Earth. A phase angle approaching + 180 degrees means the body appears as a thin crescent as seen from the Earth. A phase angle + of 90 degrees means the body appears "half full". + For the Sun, the phase angle is always reported as 0; the Sun emits light rather than reflecting it, + so it doesn't have a phase angle. + + When the body is Saturn, the returned object contains a field `ring_tilt` that holds + the tilt angle in degrees of Saturn's rings as seen from the Earth. A value of 0 means + the rings appear edge-on, and are thus nearly invisible from the Earth. The `ring_tilt` holds + 0 for all bodies other than Saturn. + + Parameters + ---------- + body : Body + The Sun, Moon, or any planet other than the Earth. + time : Time + The date and time of the observation. + + Returns + ------- + #IlluminationInfo + """ if body == Body.Earth: raise EarthNotAllowedError() earth = _CalcEarth(time)