str = PlanetVisibilityOverPeriod(nFirstDate, nLastDate, nSunSourceIndex, nPlanetID, bMorning, nRefTime, nRefOffset, nMinDuration)
This macro function returns the planetary visibility periods within the inclusive range nFirstDate to nLastDate.
➢The parameters nPlanetID, bMorning, nRefTime, nRefOffset, nMinDuration are defined in the same manner as for the function PlanetIsVisible.
This function is designed to be used in a format listing the period(s) when a given planet is visible.
•Gaps of up to four non-visible days are automatically bridged.
•Periods containing fewer than three actually visible days are then discarded.
•Dates outside the requested range are checked before the result is clipped, so a returned period may contain only one or two days if it belongs to a longer qualifying period.
The result is a string containing pairs of integer dates in the format first:last, separated by semicolons. Both endpoints are inclusive, and the dates use the same integer format as other macro date functions. An empty string means that no qualifying visibility period was found.
Note that the value of nRefOffset and nMinDuration are ignored when nRefTime is 7 or 8 (the Grundlagen and USNO approximations).
// Jupiter's evening visibility periods, using the Grundlagen approximation
sPeriods = PlanetVisibilityOverPeriod(nFirstDate, nLastDate, 1, n_JUPITER, false, 7, 0, 0)
// Mercury's morning visibility periods, using the USNO approximation
sPeriods = PlanetVisibilityOverPeriod(nFirstDate, nLastDate, 1, n_MERCURY, true, 8, 0, 0)
Examples
For example, when requesting dates 46338 to 46367, possible results are:
Result |
Meaning |
46338:46367 |
Visible throughout the requested period, allowing for bridged gaps. |
46339:46367 |
Visible from the second day through the end. |
46338:46349 |
Visible from the beginning through date 46349. |
46342:46355 |
Visible during a period wholly within the requested range. |
46338:46345;46357:46367 |
Two separate visibility periods. |
'' |
No qualifying visibility period. |
See also: PlanetIsVisible.
Topic 190265, last updated on 17-Nov-2026