SUNCLOCK(1) SUNCLOCK(1)
Feb 26, 2001
NAME
sunclock - a fancy clock for the X Window system, providing time and
geographical data through point and click actions.
SYNOPSIS
sunclock [ options ]
DESCRIPTION
sunclock is an X11 application that displays a map of the Earth and
indicates the illuminated portion of the globe by drawing sunlit areas
dark on light, night areas as light on dark. In addition to providing
local time for the default timezone, it also displays GMT time, legal
and solar time of major cities, their latitude and longitude, and the
mutual distances of arbitrary locations on Earth. Sunclock can display
meridians, parallels, tropics and arctic circles. It has builtin
functions that accelerate the speed of time and show the evolution of
seasons. Sunclock can be internationalized for various western
languages. It is possible to customize the app-default file and add
new entries for additional cities.
Sunclock can commute between two states, the "clock window" and the
"map window". The clock window displays a small map of the Earth and
therefore occupies little space on the screen, while the "map window"
displays a large map and offers more advanced functions. The Sunclock
package includes a resizable and zoomable vector map . External Earth
maps can also be loaded (as to version 3.30, formats .jpg, format of
sunclock]). Some additional formats could be added in the future.
The map window can work in five different modes:
- "Legal time" mode: legal time of default time zone and GMT time are
displayed.
- "Coordinate" mode: by clicking on a city, users get coordinates
(latitude, longitude) of that city, legal time and sunrise/sunset.
- "Solar" mode: by clicking on a point of the map (either a city or
another point), solar time and day length are shown.
- "Hour Extension" mode: displays solar times from 00:00 to 23:00 in
bottom strip, according to the Sun position.
- "Distance" mode: shows distances in km and miles between two
arbitrary locations.
- "Progress" mode: allows to speed up the evolution of time, so as to
observe the evolution of day/night periods and seasons.
Depending on the mode chosen, the bottom line shows a short text
displaying the required information. The bottom line can be scrolled
to the right or to the left by pressing the horizontal key arrows.
- 1 - Formatted: October 27, 2025
SUNCLOCK(1) SUNCLOCK(1)
Feb 26, 2001
OPTIONS
The program does not use the Xt nor any other more advanced toolkit,
and hence only those options explicitly enumerated below may be used.
The only needed resource is the list of coordinates and timezones of
cities to be displayed. Users can possibly customize the system-wide
prepackaged configuration file Sunclockrc, or their individual
configuration file ~/.sunclockrc.
-help
Show brief help and exit.
-listmenu
Explanations on the actions available from the builtin menu.
-version
Show program version and exit.
-verbose
Make Sunclock verbose. The program then sends to stderr some
internal information on the operations performed. This is
disabled by default.
-display dispname
Give the name of the X server to contact.
-language name
Select language to be used in the sunclock menu and help.
-bigfont name
Select the big font (used in the bottom line of the map window,
in the menu and file selection windows). Default is 6x13
-smallfont name (used in the bottom
Default is 6x10.
-rcfile filename
Select a configuration file that is possibly different than the
system wide app-default Sunclock or the user default
~/.sunclockrc. The rcfile (or user default) has a higher priority
than the system wide app-default, but it can be overriden by the
command line options which still have a higher priority.
-sharedir directory
Set the directory where system wide shared Earthmaps are located.
Default is /usr/share/sunclock/earthmaps.
-mapimage file.xpm.(gz)
Start sunclock with an Earth map image loaded in the map window.
-clockimage file.xpm.(gz)
Start sunclock with an Earth map image loaded in the clock
- 2 - Formatted: October 27, 2025
SUNCLOCK(1) SUNCLOCK(1)
Feb 26, 2001
window. Those maps are supposed to be somewhat smaller than for
the map window, but sunclock will still accept large ones in the
clock window...
-mono
Use monochrome settings (recommended only for monochrome
screens!). Day and night appear respectively as white and black,
and no shading is available. Only .vmf vector maps can be used in
that case.
-invert
This is essentially the same as the -mono option, except that
menus and cities can be in colors. This mode only involves 12
colors in total, and can be used for Pseudocolor displays which
have only a small number of available colors. Also, the -mono and
-invert options considerably reduce both memory and CPU usage,
and can be useful on slower machines.
-private
Force the allocation of a private colormap. This option has no
effect on truecolor displays, and is also disabled in case -mono
is set. On pseudocolor displays (depth <= 8), the -private
option allows sunclock to run even when the environment makes
intensive use of colors. An automatic quantization of colors is
performed so that true-color Earth maps using hundreds of colors
can still be displayed (of course, one may observe in some cases
a loss of quality).
-dock
With this option, sunclock locks the size of the first launched
window, if this is a (small) clock. Also, this window cannot be
closed unless all other windows are closed as well.
-synchro
With this option, sunclock updates all windows simultaneously.
This, of course, requires more CPU time and may slow down
sunclock's operation if too many windows have been opened. The
default is to update only the active window.
-nosynchro
With this option, sunclock only updates the active window. This
is the default.
-title
With this option, sunclock provides hints to the window manager
so that the title bars can appear.
-notitle
With this option, sunclock does not provide hints to the window
manager so that the title bars might not appear. Many window
managers do it anyway (supplying the missing hints when
- 3 - Formatted: October 27, 2025
SUNCLOCK(1) SUNCLOCK(1)
Feb 26, 2001
necessary), so this option may not be effective for some window
managers.
-clock
Start in the clock state. This is the default and thus need not
be specified.
-dateformat string1|string2|...
Set the format(s) used in the text output in the bottom strip of
the clock. The default date format consists of 3 strings:
%H:%M%_%a%_%d%_%b%_%y|%H:%M:%S%_%Z|%a%_%j/%t%_%U/52
Here %H,%M,%S stand for hour, minutes, seconds, %a for dayname, %b for
monthname, %d for monthday number, %j for yearday number, %m for month
number, %y for year last two digits, %Y for year number, %t for number
of days in year (365 or 366), %Z for timezone, %U for week number
(week #1 is the week with the first thursday of the year); all other
characters are reproduced as such, except %_ which stands for a blank
space, %% which stands for % and %| which stands for |. The vertical
bar | is used as a delimiter to indicate successive time formats.
There can be as many formats as desired, and the actual selection
cycles through all these formats by clicking on the bottom strip with
the mouse. The first string (i.e. the one preceding the first bar) is
taken as the default format.
-map Start in the map state. Useful to start right away with advanced
functionalities.
-decimal
Initializes coordinate values of geographical data in decimal
degrees. However, this can still be switched at runtime.
-dms Initializes coordinate values of geographical data in degrees,
minutes and seconds. However, this can still be switched at
runtime.
-menu
Raise the menu window along with the map window. This has no
effect unless the -map option is also set.
-nomenu
Don't raise the menu window along with the map window. This has
no effect if the clock is raised first.
-mapmode * (single character = C, D, E, L or S)
Start the map functions in mode (C)oordinates, (D)istances, hour
(E)xtension, (L)egal time or (S)olar time respectively. Any other
specification is ignored. Default is legal time mode.
- 4 - Formatted: October 27, 2025
SUNCLOCK(1) SUNCLOCK(1)
Feb 26, 2001
-clockgeom +x+y
Specify the position of the clock window. Only the position is
used; any size information given is ignored.
-mapgeom +x+y
Specify the position of the map window. Only the position is
used; any size information given is ignored.
-placement <choice> (random,fixed,center,NW,NE,
Specify whether commuting between clock and map windows should
proceed with letting the the window centers, respectively, the
NW, NE, SW, SE corners fixed, or rather whether it should operate
randomly, or through user defined placement. Default is NW
placement.
-horizshift w
Specify number of pixels which should separate the central bottom
points of map and menu windows. The default is 0 and may need to
be adjusted according to the window manager used.
-vertshift h
Specify number of pixels which should separate the map and menu
windows. The default is 12 and may need to be adjusted according
to the window manager used.
-spotsize size
Define size=0 [=no spots] or 1,2,3 to use either thin circles,
medium size spots or big spots and circles to represent cities.
Size=3 can be useful for monochrome displays on which cities are
hardly visible, otherwise small color spots of size 1 or 2 are
better). Default is 2 for color mode and 3 for monochrome mode.
-coastlines
In the builtin vector map, generate coast lines without filling
the land areas.
-contour
As before, but use a smart algorithm which eliminates lines,
especially at lower resolutions (in case the coasts are very
irregular, some parts may disappear but the overall picture looks
sharper).
-landfill
In the builtin vector map, fill the land areas without generating
coast lines.
-fillmode 0,1,2
Fillmode=0 is equivalent to -coastlines, fillmode=1 is equivalent
to -contour, and fillmode=2 is equivalent to -landfill.
- 5 - Formatted: October 27, 2025
SUNCLOCK(1) SUNCLOCK(1)
Feb 26, 2001
-dottedlines
Use dotted lines to represent meridians and parallels.
-plainlines
Use plain lines to represent meridians and parallels.
-command string
Specify an external action or program that will be called by
keyboard shortcut 'x'. Default is empty command.
-jump number[unit](whereunit=s,m,h,d,M,Y)
Number of seconds (respectively minutes, hour, days, Months,
Years) by which the current date and time should be shifted. No
blank space should separate the number and its unit. If the unit
is absent, the number is understood to be expressed by default in
seconds. Useful to get sunclock display information on earlier or
later epochs.
-progress number[unit](whereunit=s,m,h,d,M,Y)
Number of seconds (respectively minutes, hour, days, Months,
Years) by which the time progression should operate. No blank
space should separate the number and its unit. If the unit is
absent, the number is understood to be expressed by default in
seconds. Useful to get sunclock progress by other steps than the
predefined ones (by default the steps cycle between the values 1
mn, 1 hour, 1 day, 7 days, 30 days).
-city name
Initialize program so as to display data of city 'name'. This
becomes effective only if the above mentioned city is listed in
the app-default or rc file. The operating mode is set to
Coordinates mode.
-position latitudelongitude
Initialize program so as to display data of the position
specified by two coordinates (in degrees). The operating mode is
set to Solar time mode. -shading mode=0,1,2,3,4 Start sunclock
with the specified shading mode. Mode 0 means that the night area
is not displayed. In higher modes, the night area is displayed,
with increasingly sophisticated shading algorithms. Mode 1 stands
for no shading (i.e. just bright and dark colors are shown). Mode
2 shades the terminator area -- the area in which the sun is
partially hidden by the horizon. Mode 3 shades the region in
which there is still substantial luminosity left after sunset
(depending on the diffusion parameter below). Default is 6 below
horizon. Mode 4 additionally represents the luminosity values in
all parts of the illuminated area.
-terminator
Equivalent to -shading 2
- 6 - Formatted: October 27, 2025
SUNCLOCK(1) SUNCLOCK(1)
Feb 26, 2001
-twilight
Equivalent to -shading 3
-luminosity
Equivalent to -shading 4
-diffusion value(degrees)
Sets the amplitude of the area in which diffusion of light in the
atmosphere is still sufficient to keep some luminosity after
sunset. Default is 3 degrees.
-refraction value(degrees)
Sets the value of the refraction angle for tangential sun rays at
sunset. This is related to the fact that the sun sometimes looks
bigger at sunset. Changing the refraction degree slightly
affects the computation of sunrise and sunset times. Default is
0.1 degree.
-night
Start sunclock with the night region displayed (by default, it
is).
-cities
Start sunclock with the cities displayed (by default, they are).
-sun Start sunclock with the Sun position displayed (by default, it
is).
-meridians
Start sunclock with meridians displayed (by default, they
aren't).
-parallels
Start sunclock with parallels displayed (by default, they
aren't).
-tropics
Start sunclock with tropics and arctic circles displayed (by
default, they aren't).
-nonight -nocities -nosun -nomeridians -noparallels -notropics
These options just negate the above ones.
-landcolor color
Specifies the color of land areas produced by the builtin vector
map. Default is Chartreuse2. This option has no effect on
external image earthmaps being loaded.
-watercolor color
Specifies the color of water (sea) areas. Default is RoyalBlue.
- 7 - Formatted: October 27, 2025
SUNCLOCK(1) SUNCLOCK(1)
Feb 26, 2001
-arcticcolor color
Specifies the color of arctic areas. Default is LemonChiffon.
-textbgcolor color
Specifies the bottom text background color. Default is Grey92.
-textfgcolor color
Specifies the bottom text foreground color. Default is Black.
-dircolor color
Specifies the color used for representing directories in the file
selection widget. Default is Blue.
-imagecolor color
Specifies the color used in the file selection widget for
representing the image files whose formats are recognized and can
be read. Default is Magenta.
-citycolor0 color
Specifies the color of cities (as described in ~/.sunclockrc or
in the systemwide app-default file), when they have not yet been
clicked on with the mouse. Default is Orange.
-citycolor1 color
Specifies the color to be applied to the city which has been
selected just before the last selection, during the process of
calculating distances. Default is Red.
-citycolor2 color
Specifies the color to be applied to the last selected city. The
name and coordinates of this city are displayed in the bottom
line. Default is Red3 (darker red).
-markcolor1 color
Specifies the color to be applied to the first marked position
(any location on Earth other than one of the cities). Default is
Pink1.
-markcolor2 color
Specifies the color to be applied to the second marked position.
Default is Pink2.
-linecolor color
Specifies the color to be applied to meridian and parallel lines.
Default is White.
-tropiccolor color
Specifies the color to be applied to Equator/Tropics/Arctic
circles. Default is White. -suncolor color Specifies the color
to be applied to Sun. Default is Yellow.
- 8 - Formatted: October 27, 2025
SUNCLOCK(1) SUNCLOCK(1)
Feb 26, 2001
Users may keep a file in their home directory called ~/.sunclockrc.
This file can contain lines of the following format:
name: latitude longtitude timezone
where name is the ascii name of the place to be shown on the map.
Latitude and longitude are floating point numbers representing the
geographical location of the place. Western longitudes and southern
latitudes should be entered as negative numbers. timezone is the name
of the timezone that the place is in. This should be the name of a
file under /lib/zoneinfo, incorrect timezones cause the clock to
display GMT. It is also possible to reference a file in a directory
relative to /lib/zoneinfo for example Canada/Eastern instead of
EST5EDT.
The user may click on the dot on the map associated with a place
defined in the .sunclockrc file. When this is done, the city name and
its corresponding local time and time zone will be displayed in the
bottomline.
HOW IT WORKS
sunclock calculates the position of the Sun using the algorithm in
chapter 18 of:
Astronomical Formulae for Calculators by Jean Meeus, Third Edition,
Richmond: Willmann-Bell, 1985.
and Mercator projects the illuminated area onto map image. The Sun's
position is calculated to better than one arc-second in accuracy.
BUGS
The maps are not rescaled if you resize the open window or icon. (I
don't want to have to store a vector database for the map.) The
program contravenes section 4.1.9 of the ICCCM in that its icon window
is a fixed size, and any WM_ICON_SIZE property of the root window is
ignored.
The illuminated area shown is the area which would be sunlit if the
Earth had no atmosphere. The actual illuminated area is larger
because of atmospheric refraction and twilight.
AUTHORS
John Walker, Autodesk, Inc., <kelvin@acad.uu.NET>, wrote the original
Suntools program from which sunclock is derived.
John Mackin, Basser Department of Computer Science, University of
Sydney, Sydney, Australia, <john@cs.su.oz.AU>, wrote the X11 version
out of Suntools.
Stephen Martin, Fujitsu Systems Business of Canada,
smartin@fujitsu.ca, added support for interactive map.
- 9 - Formatted: October 27, 2025
SUNCLOCK(1) SUNCLOCK(1)
Feb 26, 2001
Jean-Pierre Demailly, Universit de Grenoble I, demailly@fourier.ujf-
grenoble.fr added support for numerous new options and functions in
the interface, and made them available through the GUI.
- 10 - Formatted: October 27, 2025
