Calcelestial

Man Page

NAME

calcelestial - calculates positions, rise, set and transit times of celestial bodies

DESCRIPTION

Together with tools like ‘at’, ‘cron’ and ‘date’ it can be used to schedule arbitrary tasks at planet and moon rise, set or transit times.

SYNOPSIS

calcelestial -p [object] -q [location] -m [moment] -f [format]

OPTIONS

-p, —object

: available objects are:

sun
moon
mars
neptune
jupiter
mercury
uranus
saturn
venus
pluto

-H, —horizon

: calc rise/set time with twilight: nautic, civil or astronomical

-t, —time

: calc at given time: YYYY-MM-DD [HH:MM:SS]

-m, —moment

: calc position at moment of: rise, set, transit

-n, —next

: use rise, set, transit time of tomorrow

-f, —format

: output format: see strftime(3) and FORMAT section below for more details

-a, —lat

: geographical latitude of observer: -90 to 90deg

-o, —lon

: geographical longitude of oberserver: -180 to 180deg

-q, —query

: query geonames.org for geographical coordinates

-z, —timezone

: override system timezone

-u, —universal

: use universial time for parsing and formatting

-l, —local

: use the the timezone at —query or —lat / —lon

-h, —help

: show this help

-v, —version

: show version

FORMAT

calcelestial supports all conversion specifications as documented in strftime(3).
additionally these special specifiers have been added:

%J

: Julian Date

§r

: equatorial right ascension in degrees

§d

: equatorial declination in degrees

§a

: azimut in degrees from north

§h

: altitude in degrees

§d

: diameter in arcseconds

§e

: distance in kilometer

§A

: observer latitude in degrees north

§O

: observer longitude in degrees east

§s

: azimuth direction as letter,

§§

: A literal ’§’ character

NOTES

A combination of —lat & —lon or —query is required.

The argument -q, —query fetches coordinates from the geonames.org database. Fetched coordinates will be cached locally. So an active internet connection is only required for the first time. Please be aware of possible privacy issues!

When symlinking the calcelestial binary to ‘sun’, ‘moon’ etc., the argument -p, —object is negligible:

sun -m rise -q Aachen

EXAMPLES

echo ”~/bin/enable-lightning” | at $(calcelestial -p sun -m set -q Frankfurt -H civil)

: enable lightning at sunset in Frankfurt

shutdown $(date -d “+10min $(calcelestial -m transit -a 50.55 -o -6.2)” +%H:%M)

: shutdown system 10 minutes after solar noon in Berlin

nvram-wakeup -s $(date -d “-10min $(calcelestial -m rise -q Aachen)” +%s)

: start system 10 minutes before sunrise in Aachen

FILES

geonames.org queries will be cached in ~/.geonames.cache

AUTHOR

calcelestial is written by Steffen Vogel <post@steffenvogel.de>

BUGS

%s formatstring has buggy timezone offset in conjunction with daylight savings.