Navigation: Macros > Macro Language > Built-in Functions > All Functions

PlanetAtExtremalDeclination

int = PlanetAtExtremalDeclination(nDate, nSunSourceIndex, nPlanetID)

Declination measures how far north or south of the celestial equator a body lies. This macro function calculates the time on nDate when nPlanetID reaches a local maximum (most northerly) or minimum (most southerly) of its geocentric declination, as seen from the centre of the Earth.

•The allowed values for nPlanetID range from n_MERCURY to n_PLUTO, and also include n_SUN and n_MOON.

•The sign of the result is positive if the planet is at its maximal northern declination, and negative if the planet has a maximal southern declination, on nDate. If the date nDate does not correspond to either case, then the function returns 0.

•The absolute value of a nonzero result is the local time expressed in millionths of a day. The fractional day is multiplied by 1000000 and truncated. If this would give 0, the function returns +1 or -1, preserving the event's sign and reserving 0 for no event.

The macro code below checks if any of the planets, including Pluto, and the Moon and the Sun, have attained their maximal or minimal declination in the sky, on the date of the incoming macro token.

sResult = ''
for nPlanetID = n_SUN to n_PLUTO step 1
    sBuffer = ''
    nCurResIdx = PlanetAtExtremalDeclination(n_TokenDate, 1, nPlanetID)
    if nCurResIdx > 0
       sBuffer = PlanetName(nPlanetID) + ' furthest north'
    endif
    if nCurResIdx < 0
       sBuffer = PlanetName(nPlanetID) + ' furthest south'
    endif
    // add the time it occurs in parentheses
    if nCurResIdx <> 0
       sBuffer = sBuffer + FormatTime('" ("hh:nn")"', Abs(nCurResIdx), true)
    endif
    if sBuffer <> ''
       if sResult <> ''
          sResult = sResult + ', '
       endif
       sResult = sResult + sBuffer
    endif
endfor

Use a calculated Sun data source, selected by nSunSourceIndex. Dates and returned times use that source's local-time settings. The event is geocentric (as seen from the centre of the Earth): the observer's position on Earth does not change its instant, although the local date and time can differ between sources. The function detects individual turning points in declination; it does not search the whole year for an annual extreme. It does not test visibility or find the highest or lowest altitude above a local horizon. For extrema of local upper-transit altitude, see PlanetAtExtremalUpperTransit.

One millionth of a day represents 0.0864 seconds in the time encoding; this specifies the units, not a guarantee of subsecond calculation accuracy.

Please enable JavaScript to view this site.

PlanetAtExtremalDeclination