SUNCLOCK(1)SUNCLOCK(1)NAMEsunclock - a fancy clock for the X Window system, providing local time
(legal time and solar time), sunrise, sunset and various geographical
data through a point and click interface.
SYNOPSISsunclock [ options ]
where the list of licit options is the following long list (starting
from (**) the options are configurable at runtime):
[-help] [-listmenu] [-version] [-citycheck] [-display name] [-sharedir
directory] [-citycategories value] [-clock] [-map] [-dock] [-undock]
[-menu] [-nomenu] [-selector] [-noselector] [-zoom] [-nozoom] [-option]
[-nooption] [-urban] [-nourban]
(**) [-language name] [-rcfile file] [-command string] [-editorcommand
string] [-mapmode * <L,C,S,D,E>] [-dateformat string1|string2|...]
[-image file] [-clockimage file] [-mapimage file] [-zoomimage file]
[-clockgeom <geom>] [-mapgeom <geom>] [-auxilgeom <geom>] [-menugeom
<geom>] [-selgeom <geom>] [-zoomgeom <geom>] [-optiongeom <geom>]
[-urbangeom <geom>] [-title name] [-clockclassname name] [-mapclassname
name] [-auxilclassname name] [-classname name] [-setfont
<field>|<fontsetting>{|<languages>}] [-verbose] [-silent] [-synchro]
[-nosynchro] [-zoomsync] [-nozoomsync] [-placement (random, fixed, cen‐
ter, NW, NE, SW, SE)] [-placementshift x y] [-extrawidth value] [-deci‐
mal] [-dms] [-city name] [-position latitude|longitude] [-addcity
size|name|lat|lon|tz] [-removecity name (name|lat|lon)] [-rootdx value]
[-rootdy value] [-fixedrootpos] [-randomrootpos] [-screensaver]
[-noscreensaver] [-rootperiod value (in seconds)] [-animation] [-noani‐
mation] [-animateperiod value (in seconds)] [-progress num‐
ber[s,m,h,d,M,Y]] [-jump number[s,m,h,d,M,Y]] [-aspect mode] [-color‐
level level=0,1,2,3] [-fillmode number=0,1,2] [-coastlines] [-contour]
[-landfill] [-shading mode=0,1,2,3,4,5] [-diffusion value] [-refraction
value] [-night] [-terminator] [-twilight] [-luminosity] [-lightgradi‐
ent] [-nonight] [-darkness value<=1.0] [-colorscale number>=1] [-mag
value] [-magx value] [-magy value] [-dx value ] [-dy value] [-spotsizes
s1|s2|s3|... (0<=si<=4, 1<=i<=citycategories)] [-sizelimits
w1|w2|w3|... (wi = zoom width values, 1<=i<=citycategories)] [-citymode
mode=0,1,2,3] [-objectmode mode=0,1,2] [-sun] [-nosun] [-moon]
[-nomoon] [-tropics] [-notropics] [-meridianmode mode=0,1,2,3] [-paral‐
lelmode mode=0,1,2,3] [-meridianspacing value] [-parallelspacing value]
[-dottedlines] [-plainlines] [-bottomline] [-nobottomline] [-reformat]
[-vmfcolors color1|color2|color3...] [-vmfrange a|b|c|d] [-vmfcoordfor‐
mat format] [-vmfflags integer] [-setcolor field|color]
DESCRIPTIONsunclock is an X11 application that displays a map of the Earth and
shows the illuminated portion of the globe. 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, the
mutual distances of arbitrary locations on Earth, the position at
zenith of Sun and Moon. 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 cus‐
tomize the app-default file and enter additional city entries.
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 (starting with version 3.51, formats .jpg,
.gif, .png, .xpm or .xpm.gz, .vmf can be read [.vmf is the specific
vector map 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 (lat‐
itude, 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 arbi‐
trary locations.
Depending on the mode chosen, the bottom line shows a short text dis‐
playing the requested information. The bottom line can be scrolled to
the right or to the left by pressing the PageUp/PageDown and Home/End
key arrows.
A further functionality is the "Progress" feature, which allows to
accelerate the evolution of time, so as to observe the evolution of
day/night periods and seasons. By default, the Sun and Moon are also
shown on the map (rather, the positions of Earth where Sun and Moon are
at zenith are shown). Coordinates of meridians, parallels, cities, the
names of cities can be displayed on the map.
All functionalities can be accessed though GUI actions on the main win‐
dow or the auxiliary windows. The main window is resizable by pulling
the window edges - as the current window manager permits it. There are
5 auxiliary windows:
- Menu Window. This is the main menu, which offers a wide list of
actions. The menu window is launched by typing 'H' or clicking on the
bottom strip with the left mouse button once. Each action can be
obtained by using the indicated keyboard shortcut or by clicking with
the mouse on the corresponding entry. Upper/lower case is irrelevant,
except for options or actions which have more than 2 switches. Lower
case then rotates the switches in one direction, upper case in the
other direction. For those switches, the left mouse button will have
the same effect as lower case, and the right mouse button the same
effect as upper case.
- File Selector window. It can be accessed by clicking on the upper
part of the main window with the middle mouse button. It allows to
select the Earth image file (in formats *.vmf *.xpm, *.xpm.gz, *.jpg,
*.gif, *.png) to be loaded.
- Zoom window. It can be accessed by clicking on the upper part of the
main window with the right mouse button. The zoom window allows to
select a specific area on the Earth, to translate or zoom it up to 100
times. High resolutions (larger than 10) are only recommended with the
"huge" Earthmap of 11 Mbytes, which offers clean images up to 20 times
magnification at least.
- Urban selector window. Allows to modify interactively the list of
shown cities and locations.
- Option window. Allows to reconfigure pretty much everything on the
fly (colors, fonts, etc), exactly as with the command line options.
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 time‐
zones of cities to be displayed. The system administrator can possibly
customize the system-wide prepackaged config file Sunclockrc before
installing the package, while users can tweak their individual configu‐
ration file ~/.sunclockrc at any time. The individual config file
~/.sunclockrc is read *after* the system wide config file Sunclockrc,
and therefore its settings override those of the system wide config.
The command line options can be used to override ~/.sunclockrc itself.
-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
information on the internal operations performed. This is dis‐
abled by default.
-silent
Make Sunclock silent about internal operations performed. This
is the default.
-citycheck
At start-up, check that there are no repetitions in the list of
cities (a city is considered to be repeated if it appears twice
under the same name, with coordinates differing by at most 0.5
degree). By default no check is performed on Sunclockrc - which
is supposedly correctly set up...
-display dispname
Give the name of the X server to contact.
-language name
Select language to be used in the sunclock menu and help.
-title name
Change the specification of the string which should appear in
the title bar of the main and auxiliary windows. Default is the
application name, i.e., sunclock.
-classname name
Change the specification of class application name. Default is
Sunclock. Other specifications can be passed so that aware win‐
dow managers might use it for configuration purposes. You might
e.g. pass -classname NoTitle-Sticky, and configure properly
your WM so that it removes the title bar, and make the window
sticky with respect to the Desktop Pager. With fvwm, you could
use for instance
Style "*NoTitle*" NoTitle, WindowListHit, Sticky
Style "*ShowTitle*" Title, WindowListHit, Slippery
Style "*Sticky*" Sticky
to specify such a behaviour.
-setfont <field>|<fontsetting>{|<languages>}
Select the font for the given text field (clockstrip, menustrip,
city, coord, menu). Optionally, one can specify a list of lan‐
guages for which this font setting should apply. If the <lan‐
guages> option is not specified, the font setting applies to all
languages.
-rcfile filename
Read a configuration file that is different from the user
default ~/.sunclockrc (if this option is not set, the user con‐
fig file defaults to ~/.sunclockrc). Notice that the app-default
config file Sunclockrc is read first, and the file set by the
-rcfile option is read afterwards; therefore its settings over‐
ride those set by the system wide config file. Reading further
config files is possible at runtime, using the option window.
Set -rcfile with a void string "" if you wish to bypass the user
config file step.
-sharedir directory
Set the directory where system wide shared Earthmaps are
located. Default is /usr/share/sunclock/earthmaps.
-image *.jpg (or *.gif, *.png, *.vmf, *.xpm, *.xpm.gz)
Start sunclock with an Earth map image loaded in the clock and
map windows. The same map is then used for both windows, but the
clock image is usually scaled down.
-mapimage *.jpg (or *.gif, *.png, *.vmf, *.xpm, *.xpm.gz)
Start sunclock with an Earth map image loaded in the map window.
-clockimage *.jpg (or *.gif, *.png, *.vmf, *.xpm, *.xpm.gz)
Start sunclock with an Earth map image loaded in the clock win‐
dow.
-zoomimage *.jpg (or *.gif, *.png, *.vmf, *.xpm, *.xpm.gz)
Use specified file as image in the zoom widget
-colorlevel level=0,1,2,3
Sets the color level (0=monochrome, 1=few colors, 2=many colors,
3=full colors). With the "monochrome" setting, day and night
appear respectively as mapbgcolor (white by default) and mapfg‐
color (black by default), and no shading is available; all other
features (city names, coordinates) appear also as monochrome.
With the "few colors" setting, the menus and city spots can be
represented with dedicated colors, but the meridians/paral‐
lels/tropics are still monochrome. With the "many colors" opri‐
ons, meridians/parallels/tropics can also be drawn in color. In
these first 3 modes, only .vmf vector maps can be loaded. These
modes save a lot of CPU power - since a simple algorithm of
inversion of colors is used to set colors of all points in the
map. Monochrome mode can be useful for very slow CPUs, such as
those in use in PDAs with black and white screen. The full color
mode (level=3) allows to load jpeg or other colorful images; day
and night can be drawn with various shading parameters. This is
the default and recommended mode if you have a reasonably recent
machine with enough video RAM.
-dock This option is meant to give sunclock the ability to be docked
in the window manager buttons or menu bar, providing that the WM
offers this possibility without requiring special hints (fvwm2
or windowmaker or afterstep will work perfectly well for that
purpose, KDE or Gnome won't...) Under the -dock option, sunclock
locks the size of the first launched window, which is necessar‐
ily a small clock. Also, that initial window can no longer be
closed by typing 'K' or 'Q'. (The only way to exit the applica‐
tion, then, is to kill it with xkill, or to undock it first with
the -undock option from the Option window). The user might want
to customize the size and suitable options so that sunclock fits
with the size of the dockable applets. As an example, sunclock
could be invoked as follows:
sunclock-language fr -nobottomline -dock -clockgeom 63x42+2+190
-dateformat "%H:%M:%S|%a%_%d%_%b|%b%_%Y|%j%_%U/52" -command
"xdiary"
-undock
Undocks sunclock. This option has no other effect than reallow‐
ing the use of options that were "frozen" under -dock. It can be
used e.g. to exit the application when sunclock has been started
in dock mode.
-synchro
With this option, sunclock updates all windows simultaneously.
This, of course, requires more CPU time and may slow down sun‐
clock'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.
-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 charac‐
ters 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. There are a few other switches, such as %h for hour in 12-hour
mode, %P fo AM/PM indicator, %G for hour in GMT time, %N for minutes in
GMT time.
-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 run‐
time.
-menu Raise the menu window along with the main (map, clock) window.
-nomenu
Don't raise the menu window along with the main (map, clock)
window. This is the default.
-selector
Raise the selector window along with the main (map, clock) win‐
dow.
-noselector
Don't raise the selector window along with the main (map, clock)
window. This is the default.
-zoom Raise the zoom window along with the main (map, clock) window.
-nozoom
Don't raise the zoom window along with the main (map, clock)
window. This is the default.
-option
Raise the option window along with the main (map, clock) window.
-nooption
Don't raise the option window along with the main (map, clock)
window. This is the default.
-urban Raise the urban window along with the main (map, clock) window.
-nourban
Don't raise the urban window along with the main (map, clock)
window. This is the default.
-aspect mode
Sets the aspect mode, i.e. the way by which zooming behaves with
respect to horizontal and vertical directions. Mode = 0 means
that no synchronizations are made, mode = 1 means that the zoom
factors are always made to be equal, mode = 2 (the more subtle
one) means that the horizontal and vertical zoom factors are
adjusted so that the region located near the central point of
the zoomed area will be conformal to its actual geometry on
Earth, i.e. will not appear to be distorted horizontally or ver‐
tically. This won't be true elsewhere, though, especially if
the zoomed area is large.
-zoomsync
When the option is set, the zoom window will open in synchro‐
nization mode: any zooming action made from the main map or from
the zoom window will take place as the mouse button is released
(or as a key is pressed). This is the default when the zoom
window has not been opened (synchronization is automatically
set).
-nozoomsync
When set, the zoom window will open in non-synchro mode. Syn‐
chronizing the zoom will still be possible, though, by clicking
on the "Synchro" button. By default, synchronization does not
occur when the zoom window is opened, unless option -zoomsync
has been set.
-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.
-placement <choice> (random,fixed,center,NW,NE,SW,SE)
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 oper‐
ate randomly, or through user defined placement. Default is NW
placement.
-placementshift x y
Relative displacement <clock window> --> <map window>, to apply
with respect to the -placement specification. If placement is
NW, then the NW window corner will move by (x,y) pixels. Defaut
is (0,0), i.e. no modification to apply to the -placement spec‐
ification.
-extrawidth value
When using the 'enlarge window' command specified by key '>',
the width of the full X display is used, minus some default
width equal to 10 pixels. This is enough the accomodate the
width of window borders of most window managers. In case it is
not, -extrawidth <value> can be used to change this setting.
-clockgeom (width)x(height)+(xcoord)+(ycoord)
Specify the geometry of the clock window, i.e. its size and
position (absolute position with respect to the left upper cor‐
ner of the screen).
-mapgeom (width)x(height)+(xcoord)+(ycoord)
Specify the geometry of the map window, i.e. its size and posi‐
tion (absolute position with respect to the left upper corner of
the screen).
-menugeom +(xcoord)+(ycoord)
Specify the relative position (x = horizontal shift, y = verti‐
cal shift) of the menu window with respect to the main window,
starting from the bottom edge of the main window (from its top
edge in case of SW or SE placements, see above). The y value may
need an adjustment, according to the height of the title bar
allocated by the window manager, if any. In the case of the
menu window, width and height solely depend on the menufont, and
therefore any given specification of width and height is
ignored. The default relative position is x = 0, y = 30.
-selgeom (width)x(height)+(xcoord)+(ycoord)
Specify the geometry of the selector window. The position speci‐
fication is relative to the main window (or to the menu, when
the menu is raised). See above option -menugeom for further
explanations. The default geometry of the selector window is
600x180+0+30.
-zoomgeom (width)x(height)+(xcoord)+(ycoord)
Specify the geometry of the zoom window. The position specifica‐
tion is relative to the main window (or to the menu, when the
menu is raised). See above option -menugeom for further expla‐
nations. The default geometry of the zoom window is
500x320+0+30.
-optiongeom (width)x(height)+(xcoord)+(ycoord)
Specify the geometry of the option window. The position specifi‐
cation is relative to the main window (or to the menu, when the
menu is raised). See above option -menugeom for further expla‐
nations. The height specification depends solely on the selected
menufont and is therefore ignored. The default geometry of the
option window is 630x80+0+30.
-urbangeom +(xcoord)+(ycoord)
Specify the relative position (x = horizontal shift, y = verti‐
cal shift) of the urban window with respect to the main window
(or to the menu, when the menu is raised). See above option
-menugeom for further explanations.
-auxilgeom +(xcoord)+(ycoord)
Specify the relative position (x = horizontal shift, y = verti‐
cal shift) of the auxiliary windows (menu, zoom, selector,
option). All relative displacements are set to (x,y).
-mag value
Rescale the image by a magnification factor equal to <value>,
which must be at least equal to 1.0. This means that the window
only shows a fraction of the entire map namely, 1/<value> x
1/<value>. Default value is 1.0.
-magx value
Same as for the -mag option, but only the x direction (width) is
rescaled. Default value for magx is 1.0.
-magy value
Same as for the -mag option, but only the y direction (height)
is rescaled. Default value for magy is 1.0.
-dx value (degrees)
Options -dx and -dy allow to set the longitude, respectively the
latitude, of the city or location at which the zoom area should
be centered. The values should be given in degrees. Default
(dx,dy) is (0.0,0.0).
-dy value (degrees)
See -dx above.
-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 generat‐
ing coast lines.
-fillmode 0,1,2
Fillmode=0 is equivalent to -coastlines, fillmode=1 is equiva‐
lent to -contour, and fillmode=2 is equivalent to -landfill.
-dottedlines
Use dotted lines to represent meridians and parallels.
-plainlines
Use plain lines to represent meridians and parallels.
-bottomline
Draw a line at the bottom of the map, to separate the map from
the text strip showing time and coordinates.
-nobottomline
Don't draw the bottom line. This is the default.
-command string
Specify an external action or program that will be called
through keyboard shortcut 'x'. Default is empty command.
-editorcommand string
Specify an external file editor program that will be called
through keyboard shortcut double 'h' (call help). Default is
"/usr/lib/sunclock/emx -edit 0 -fn 9x15" (included emx editor,
in no-edit mode...)
-jump number[unit] (where unit=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 ear‐
lier or later epochs.
-progress number[unit] (where unit=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).
-rootdx value (between 0.0 and 1.0)
Options -rootdx and -rootdy allow to set the position where the
sunclock map is copied on the root window in rootwindow or
screensaver modes. '-rootdx 0.0' means on the left side,
'-rootdx 1.0' on the right side, '-rootdy 0.0' means at the top,
'-rootdy 1.0' at the bottom of the root window. Default is 0.5
for both values, i.e. a centered map.
-rootdy value (degrees)
See -rootdx above.
-fixedrootpos
Use the above rootdx and rootdy values to fix the position of
the map on the root window. This is the default unless -screen‐
saver has been specified.
-randomrootpos
Instead of using the above rootdx and rootdy values to fix the
position of the map on the root window, just use a random posi‐
tion instead. This is the default in case the -screensaver
option has been set.
-screensaver
Start sunclock in screensaver mode (no window nor any GUI con‐
trols are available in that case, and the only way to terminate
the program is to kill it explicitly).
-noscreensaver
Do not start sunclock in screensaver mode. This is the default.
-rootperiod value (in seconds, between 1 and 120 sec)
Set the period for refreshing the root window. Default is 30
seconds. This takes effect only when writing the map onto the
root window is active (strike twice on '[' or hit the relevant
box in the Option window). Writing onto the root window is dis‐
abled by using the ']' key.
-animation
Start the animation mode right away when sunclock is launched.
-noanimation
Don't start the animation mode when sunclock is launched - this
is the default. Sunclock can anyway switch between the anima‐
tion/noanimation modes by typing key ' (apostrophe) at runtime.
-animateperiod value (in seconds, between 0 and 5 sec)
Set the period for animating the map. Default is 0 seconds,
which means that images are switched as fast as sunclock can
compute them. Otherwise time is shifted by the current progress
value (as set by the -progess option) after waiting the number
of seconds prescribed by the animateperiod value. This takes
effect only when the animation is active (strike on the ' key or
hit the relevant box in the Option window).
-addcity size|name|latitude|longitude|timezone
where name is the ascii name of the place to be shown on the map. The
first argument "size" is an nonnegative integer meant to indicate the
size of the city (1: major city, 2: important city, 3: less important
city, ...). The argument "size" can also be set to 0, with the effect
of hiding the corresponding city, while keeping in memory all of its
other parameters. The city can then be shown again with 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
/usr/share/zoneinfo (or whatever directory is used on your system),
incorrect timezones cause the clock to display GMT. It is also possible
to reference a file in a directory relative to /usr/share/zoneinfo for
example Canada/Eastern instead of EST5EDT.
-city name (name|lat|lon)
Initialize program so as to display data of city 'name', respec‐
tively (name, with latitude and longitude specified). This
becomes effective only if the above mentioned city is listed in
the systemwide RC file Sunclockrc or in the user's private
~/.sunclockrc. The operating mode is set to Coordinates mode.
-position latitude|longitude
Initialize program so as to display data of the position speci‐
fied by two coordinates (in degrees). The operating mode is set
to Solar time mode. Notice that with a vertical bar | (a blank
space is also admitted instead of a |).
-addcity size|name|lat|lon|tz
Adds a city in the list of cities to be displayed on the map.
They must be defined by exactly 5 parameters: size, name, lati‐
tude, longitude, timezone, in this order, with parameters being
separated by a vertical bar |. Blank characters may appear in
the name if double quotes are used to mark the group of parame‐
ters (but there shouldn't be any blank characters in the other
parameters). In the RC config file, blank characters should be
replaced by the octal character 037 (i.e. Ctrl-Q Ctrl-_ within
emacs).
-removecity name (name|lat|lon)
Removes name (respectively name|lat|lon) from the list of cities
to be displayed. Same remarks as above for blank characters.
-citycategories value
Specifies the maximal number of city categories: categories
range from 1 (highest catgory, i.e. major city) to some maximum
number. The option -citycategories specifies that maximum num‐
ber. It can only be used at start-up, not at runtime. The
default value is 5.
-spotsizes s1|s2|s3|... (0<=si<=5, 1<=i<=citycategories)
With this setting, major cities (category 1) will be represented
by the symbol of size s1, category 2 cities by the symbol off
size s2, etc. The default setting is -spotsize 1|2|3|4|5.
Assigning size si=0 means that the corresponding category of
cities (rank i) will not be displayed. If there are less data
than the number of city categories (5 by default), the last
given data is repeated as many times as needed, e.g. -spotsizes
2 is equivalent to -spotsizes 2|2|2|2|2. Example: specifying
-spotsizes 0|2|0|3|0 will let appear only city categories 2 and
4, but those of category 4 will appear with the symbol normally
allocated to cities of category 3. This is useful in combination
with the option -sizelimits (see below).
-sizelimits w1|w2|w3|...
(wi = zoom width values, 1<=i<=citycategories) With this set‐
ting, cities of rank i=1,2,3,... will appear if (and only if)
the width of the zoomed map is at least equal to wi (as it would
appear if the Earth would be entirely displayed...) . The
default is 0|580|2500|6000|12000 (no constraint for major
cities, rank 4 cities appear only if the width is at least 6000
pixels, e.g. if an original window of width 800, say, has been
applied a zoom at least equal to 7.5). Thus -sizelimits 0 is
equivalent to -sizelimits 0|0|0|0|0, -sizelimits 0|400 is equiv‐
alent to -sizelimits 0|400|400|400|400.
-shading mode=0,1,2,3,4,5
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 algo‐
rithms. 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 3˚ below horizon. Mode 4 additionally represents the
luminosity values in all parts of the illuminated area. Mode 5
represents the gradient of luminosity from the brightest area
(facing the sun) to the darkest area (opposite to the sun); this
has nothing to do, though, with the actual luminosity values.
-nonight
Start sunclock with the night region not drawn. This is equiva‐
lent to -shading 0.
-night Start sunclock with the night region in plain shading mode. This
is equivalent to -shading 1.
-terminator
Equivalent to -shading 2
-twilight
Equivalent to -shading 3
-luminosity
Equivalent to -shading 4
-lightgradient
Equivalent to -shading 5
-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.
-darkness value (in the range 0.0 ... 1.0)
Sets the constrast between day and night areas. A 0.0 value
means that the night area will not be distinguishable from day,
while 1.0 means that it will be completely black. Default is
0.5.
-colorscale value (integer in the range 1 ... 256)
Sets the number of color subdvisions which will be in use for
producing shading, that is, the number of colors ranging from
bright colors (day) to dark colors (night). Default is 16.
-meridianmode mode=0,1,2,3
Start sunclock with meridians displayed or not, according to the
mode, mode=0 : no meridians, mode=1 : meridians drawn, mode=2 :
meridians drawn with labels at the bottom, mode=3 : meridians
drawn with labels at the top. The default mode is 0 (no meridi‐
ans).
-parallelmode mode=0,1,2,3
Start sunclock with parallels displayed or not, according to the
mode, mode=0 : no parallels, mode=1 : parallels drawn, mode=2 :
parallels drawn with labels at the left hand side, mode=3 : par‐
allels drawn with labels at the right hand side. The default
mode is 0 (no parallels).
-meridianspacing value (degree)
Specify how many degrees (or fractions of degree) should sepa‐
rate meridians drawn on the map.
-parallelspacing value (degree)
Specify how many degrees (or fractions of degree) should sepa‐
rate parallels drawn on the map.
-citymode mode=0,1,2,3
Start sunclock with cities displayed or not, according to the
mode, mode=0 : no cities, mode=1 : cities drawn, mode=2 : cities
drawn with their names, mode=3 : cities drawn with their coordi‐
nates. The default mode is 1 (cities shown without names or
coordinates).
-tropics
Start sunclock with tropics and arctic circles displayed (by
default, they aren't).
-sun Start sunclock with the Sun position displayed (by default, it
is).
-moon Start sunclock with the Moon position displayed (by default, it
is).
-notropics -nosun -nomoon
These options just negate the above ones.
-objectmode mode=0,1,2
Mode=0 stands for no objects (Sun, Moon) at all, mode=1 for
objects just drawn by their symbol, mode=2 for objects drawn
with their symbol and coordinates in decimal degrees (or
degrees, minutes, seconds, using the ˚ key switch).
-reformat
This option only produces an effect when a *.vmf file is loaded.
The file is then reformatted according to the allowed syntax and
normal line length, and printed to stdout. To capture the aout‐
put, one should redirect the standard output to a file (with a
'> file' as usual).
-vmfcolors color1|color2|color3...
Redefine the list of colors to be used in the .vmf file. This
option has no effect when loading files with other formats.
Default is NULL string (so that the default colors are loaded).
The string "|" is also considered to be a void string and can be
used in the option widget to enforce default colors back.
-vmfrange a|b|c|d
Define the range in which point coordinates (latitude, longi‐
tude) should vary in the *.vmf files, default is
-90|90|-180|180. This option can be useful in combination with
-reformat to make a linear change of coordinates in a *.vmf
file.
-vmcoordformat format
Set the format for the output of double values produced via the
-reformat option. The default format is "%7.3f %8.3f" (format
for latitude and longitude, respectively), unless the -vmfrange
has been modified, in which case the default becomes "%g %g"
(from the POSIX rules, this stands for 6 significant digits in
any position).
-vmfflags number
Sets the flags (integer value) for a *.vmf file. Each bit is a
distinct flag. The zeroth order bit (i.e. &1) determines whether
features which have their own zeroth bit set are to be drawn in
clock window mode (if the zeroth bit is not set, the feature
will always be drawn). Other bits are used to control whether
given features are to be drawn or not. For instance setting
-vmfflags 2 with timezones.vmf will let the timezone regions
appear, while -vmfflags 6 will also show the timezone boundary
lines. (Only bits 0, 1, 2 are currently used in timezones.vmf).
-setcolor field|color
Sets the color of a specified field in the sunclock widgets.
The color can be specified as any litteral value (red, yellow,
etc..., as defined in the resource file rgb.txt), or as a 6
digit hexadecimal value #ijklmn, or even 12 digits (for 48 bits
displays!) The field can take any of the following values
(between parentheses, the meaning and default value):
clockbg (clock background color; White)
clockfg (clock foreground color; Black)
mapbg (map background color; White)
mapfg (map foreground color; Black)
menubg (menu text background color; Grey92)
menufg (menu text foreground color; Black)
buttonbg (button background color; Grey84)
buttonfg1 (button very dark border color ; Black)
buttonfg2 (button dark border color ; Grey50)
buttonfg3 (button light border color ; Grey95)
buttonfg4 (button very light border color ; White)
weak (color for disabled menu commands; Red)
clockstripbg (background color of bottom strip in clock window; Grey92)
clockstripfg (foreground color of bottom strip in clock window; Black)
mapstripbg (background color of bottom strip in map window; Grey92)
mapstripfg (foreground color of bottom strip in map window; Black)
zoombg (background color of the small monochrome map used in the zoom
widget; White)
zoomfg (foreground color of the small monochrome map used in the zoom
widget; Black)
optionbg (background color of option text entry; White)
optionfg (foreground color of option text entry; Black)
caret (color of text caret; SkyBlue2)
change (color for temporary changes; Brown)
choice (color for selected changes and choices; SkyBlue2)
directory (color of text indicating directory entries; Blue)
image (color of text indicating image files; Magenta)
cityname (color of text indicating city names; Red)
city0 (color of unmarked cities; Orange)
city1 (color of marked cities, main selection; Red)
city2 (color of marked cities, secondary selection; Red3)
mark1 (color of first mark; Pink1)
mark2 (color of secondary mark; Pink2)
line (color of geodesic lines; White).
meridian (color of meridians; White).
parallel (color of parallels; White).
tropic (color of Equator/Tropics/Arctic circles; White)
sun (color of Sun; Yellow)
moon (color of Moon; Khaki)
star (color of Stars; White)
root (color of Root window on which stars will be drawn; Black)
PRIVATE CONFIGURATION FILE
Users may keep a file in their home directory called ~/.sunclockrc.
This file can contain specify any number of options which are also
available as command line options:
mapmode: L
language: en
city: Washington
map
mapimage: /usr/share/sunclock/earthmaps/jpeg/caida.jpg
tropics
twilight
HOW IT WORKSsunclock 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 projects the illuminated area onto the map image by an equidis‐
tributed (latitude, longitude) cylindrical projection. The Sun's posi‐
tion is calculated to better than one arc-second in accuracy.
BUGS
Sunclock makes intensive use of pointers and memory allocation/deallo‐
cation, so memory leaks might still be possible under some circum‐
stances. However, the program has been thoroughly debugged, and
crashes seem to be rather rare. As new features are introduced, older
ones may become broken during the phase of development :-(
The illuminated area shown is the area which would be sunlit if the
Earth atmosphere would be absolutely uniform. The actual illuminated
area may depend on weather, temperature, atmospheric refraction and
diffusion, etc.
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 Syd‐
ney, 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.
Jean-Pierre Demailly, Université de Grenoble I, demailly@fourier.ujf-
grenoble.fr worked out versions 3.xx, which add many new major features
(loading maps, shading, zoom functionalities, configuration of options
on the fly at runtime, through a point and click GUI interface).
June 22, 2006 SUNCLOCK(1)
