This is the desktop Martian Clock, v0.2.  Analog movement is ©2019 Eric W. Flesch 
and desktop program is ©2024 Reggis E. Sanders.  This clock is free to public use, 
shared under CC BY-NC-SA 4.0 license, i.e., attribution to the above authors 
required for any derivative works, commercial use forbidden except by arrangement 
with the authors, and derivative works must carry this same license. 

Unzip all contents to one folder.  This program requires Java 7 or later, to run.  
To start the clock, run clock.jar.  For convenience, make a shortcut to clock.jar
and place it on the desktop; "marty.ico" can be used as an icon for the shortcut.

The Martian Clock has a different hand movement to standard clocks: on the stroke 
of the hour, all 3 hands meet at that hour on the dial.  The clock shows 24 hours 
per day, divided into hundredths-of-hours (called "minutes") of 36 seconds each 
for Earth, and 37 seconds each for Mars, which fits the slightly longer Mars day.
An alternative is to use 50 min/hr with 74 sec/min for Mars or 72 sec/min for Earth.
A paper with a comprehensive discussion is submitted, and included in this zip file.

This is the second version, v0.2 of this desktop clock.  Some features have not been
optimized, including the clock hands display which is on the developer's to-do list.

The clock program gets its instructions from the "settings" (with no extension) file 
as to which clock to display, i.e., for Earth or Mars, whether analog or digital or 
both, whether to display an "exact" Martian analog clock (second-hand swiftly sweeps 
the dial once per hundredth-of-an-hour, a.k.a. "short minute") or "relaxed" 
(second-hand placidly sweeps once per fiftieth-of-an-hour, a.k.a. "long minute") or
a SpaceClock for use in orbit, or a 20-hour or 10-hour clock, and whether the clock 
face is displayed in small size or large.  There is also a setting to display Earth 
UT time.  The settings file first provided in the zip file is that of the 
"settings-earth-all-exact.txt" file, and gives an exact Martian clock for Earth 
(local time) with a digital display underneath. 

THE EASY METHOD to change the "settings" file is to select one of the other 
settings files provided, and copy it to the "settings" file (thus replacing 
the previous "settings" file), then run the clock.

General guide to the settings file names, e.g., "settings-earth-all-exact.txt":

EARTH/MARS/UT -- "earth": your local time on Earth, "mars": Mars AMT time, 
                 "UT": Earth UT (universal time), a.k.a. GMT.
ALL/DIAL/DIGITAL -- "all" displays both the analog dial and the digital time,
                 "dial" shows only the analog dial, "digital" shows only digital. 
EXACT/RELAX/SPACECLOCK -- which clock face to use, see paper for illustrations.
20H/10H -- displays the 20-hour or 10-hour clock, both analog and digital.
2MIN -- 2 minutes of digital time pass per each sweep of the second hand.
36SEC/37SEC -- digital clock gives "short minutes": 36 sec for Earth, 37 for Mars.
72SEC/74SEC -- digital clock gives "long minutes": 72 sec for Earth, 74 for Mars.
BIG -- twice the dimensions of the small desktop clock otherwise shown.

=============================================================

To customize your own settings, following is a guide to the available settings.
There are 3 sections: the general settings, the settings for the analog clock, 
and the settings for the digital clock.  The first time you do this, it will help
to use an existing settings file as a style guide. 

Each line in "settings" assigns a value to a setting code (consisting of one or 
two case-insensitive letters), e.g., D=1.   

If you write a settings code twice, on 2 different lines, only the first one is 
used, even if its assigned value is invalid.

To write a comment in the settings file, write a new line which contains no
equals sign.  The clock will ignore such a line.  


Guide to Settings which can be used in the settings file
========================================================
W: width of the clock, and height of the analog display (default 216).

D: 0 = the clock displays in a window (default), 1 = displays, but no window.

WC: which clock(s) to display: 
    WC=0 for analog only (default), 
    WC=1 for digital only, 
    WC=2 for both.  Analog is on top by default; to put digital on top, also
         write "DP=1" in a new line.

TP: which planet's solar day: TP=0 for Earth (default), TP=1 for Mars. 

Z: for Earth, 0 = local time, 1 = UT (universal time) -- default is 0; 
   no effect for Mars which shows only AMT (Airy Mean Time, like Mars UT).

T: Displays a fixed time, which you specify as the number of seconds since 
   midnight, e.g., T=64800.  The clock will display that time, and not run.


Settings for the analog clock 
==========================================
Note: analog clock size is determined by W, as described above.

Settings for the clock hand movements:
FM: which analog clock movement to use: 
    FM=0 for one-fiftieth of an hour per second-hand sweep (long minute; default). 
    FM=1 for one-hundredth of an hour per second-hand sweep (short minute).
    FM=2 for 20-hour clock; for standard configuration, also set MS=1 & SS=1. 
    FM=3 for 10-hour clock; for standard configuration, also set HS=1, MS=1, & SS=1.
HS (default 0): if 1, hour hand points upwards at midnight; else downwards.
MS (default 0): if 1, minute hand points upwards at midnight; else downwards.
SS (default 0): if 1, second hand points upwards at midnight; else downwards.

F: Chooses an image for the clock face, specified by the file name; defaults to
   "face.png".
   The images provided with the clock are:
   • exact.jpg = exact Martian clock face. 
   • face.jpg = relaxed Martian clock face.
   • orbital.jpg = spaceclock face. 
   • spec-10h.jpg = 10-hour Mars AM-PM clock face. 
   • spec-20h.jpg = 20-hour Mars clock face.
If specified as blank (F=), or file name does not exist, then no image is used.

B: color of the background (default 15658734 -- see notes for color guide).
Note that B has no effect if an image is used for the clock face.

O: radius of an outline drawn around the clock face (default 0).
If O is active, then the following settings are available:
  OT: thickness of the outline of the clock face (default 1).
  OC: color of the outline of the clock face (default 3355443).
  FC: color of the clock face (defaults to the background color).
      Note that FC has no effect if an image is used for the clock face.

C: radius of the center, around which the hands revolve (default 0).
If C is active, then the following setting is available:
  CC: color of the clock center (default 3355443).

Settings for customizing the clock hands:
- H (default 1): hour hand is a line of this width (0=complex shape).
- HL (default 72): length of hour hand, from center of clock to the tip.
- HB (default 0): length of back end of hour hand, from center to back end.
- HC (default 0): color of the hour hand.
- M (default 1): minute hand is a line of this width (0=complex shape).
- ML (default 96): length of minute hand, from center of clock to the tip.
- MB (default 0): length of back end of minute hand, from center to back end.
- MC (default 0): color of the minute hand.
- S (default 1): second hand is a line of this width (0=complex shape).
- SL (default 96): length of second hand, from center of clock to the tip.
- SB (default 0): length of back end of second hand, from center to back end.
- SC (default 255): color of the second hand.

Numbers on the clockface can be drawn if no image file is used, OR if ND=1:
- N (default 96): distance of numbers from clock center (0=not drawn).
If N is active (i.e., not 0), then the following are available:
- ND (default 0): if 1, numbers are drawn even if an image file is used.
- NF (no default): font, e.g., "Arial"; set NT>1 to make it bold as per below.
                   If font is not specified, numerals are constructed from
                   shapes.
- NS (default 8): size of the numbers (when using the numbers constructed from
                  shapes, 8 is the native size).
- NT (default 1): thickness of the numbers. (with a font, set DT>1 to make it
                  bold).
- NO (default 0): 2 = upright numbers which are centred in place.  If needing  
                  to better-fit them to the marks on the dial, try: 
                      1=justified outwards, or 3=justified inwards.
                  0=numbers rotate with the dial, as with the spaceclock.
- NC (default 3355443): color of the numbers.

Marks on the clockface:
- L (default 0): if 0, marks are not drawn; else distance from clock center.
If L is active, then the following are available:
- P (default 3): length of the hour marks, going towards the clock center.
- PW (default 1): width of the hour marks.
- PC (default 3355443): color of the hour marks.
- I (default 2): length of the minute marks, towards the clock center.
- IW (default 1): width of the minute marks.
- IO (default 0): offset of where the minute marks start from L.
- IC (default 3355443): color of the minute marks.


Settings for the digital clock
=========================================
Note: digital clock width is determined by W, as described above.
DH (default 24): height of the digital display.

DM: which digital clock movement to use:
    DM=0 for long minutes (one-fiftieth of an hour) (default), 
    DM=1 for short minutes (one-hundredth of an hour),
    DM=2 for 20-hour clock, 
    DM=3 for 10-hour clock. 
If displaying both analog and digital, DM should typically have the same value
       as FM, except when relaxed clock (FM=0) is counting short minutes (DM=1). 

DF (no default): font of the text, e.g., "Arial"; set DT>1 to make it bold as
                 per below. If font is not specified, numerals are constructed
                 from shapes.
DS (default 8): size of the text (when using the numbers constructed from
                shapes, 8 is the native size).
DT (default 1): thickness of the text (with a font, set DT>1 to make it bold).
DZ (default 0): if 1, always displays two digits for the hour, leading zero ok.
DC (default 3355443): color of the text.
DB (default 15658734): color of the background of the digital display.
DX (defaults to middle): horizontal offset from left edge of display to center of text.
DY (defaults to middle): vertical offset from top edge of display to center of text.

The following settings are for additional text on the digital display called
extra text.  If the main digital text uses a font, this same font is also used
for the extra text; otherwise, the extra text uses the default Java font.
This extra text can be used for all kinds of different custom purposes.
X (defaults to nothing): notation for the extra text; see notes for the guide to
                         the notations.
XS (default 16): size of the extra text.
XT (default 1): if greater than 1, extra text is bold.
XC (default 3355443): color of the extra text.
XX (default 156): horizontal offset of the extra text from the left edge of the 
                  digital display to a point specified by XA, below. 
XY (default 12): vertical offset of the extra text from the top edge of the
                 digital display to the center of the extra text.
XA (default 0): specifies the place in the extra text with respect to which it
                is positioned horizontally (0=left edge of text, 1=center,
                2=right edge).

Notes
=====
Color guide:
  To specify a color, add together its red value, 256 times its green value, and
  65536 times its blue value, where the three values are taken as ranging from 0
  (none) to 255 (full). The corresponding mathematical formula is r+256g+65536b.
  Example colors are:
  0 = black
  255 = red
  1111111 = green
  3333333 = yellow
  3355443 = dark grey
  9999999 = blue
  11111111 = purple
  15658734 = light grey

Guide to extra text notations:
  The following are converted to hour, minute and second numbers:
  - H: hour on a 24-hour clock.
  - i: hour on a 20-hour clock.
  - I: hour on a 10-hour clock.
  - h: for Earth, hour on a 12-hour clock; for Mars, same as I.
  - M: minute on a 24-hour clock using the long minute.
  - c: minute on a 24-hour clock using the short minute.
  - C: minute on a 20- or 10-hour clock.
  - m: for Earth, minute on a standard clock; for Mars, same as C.
  - S: second on a clock using the long minute.
  - e: second on a clock using the short minute.
  - s: for Earth, second on a standard clock; for Mars, same as S.
  For the above, repeat the letter to indicate the number must use two digits
  even if less than 10 (H becomes a number ranging from 0 to 23 whereas HH
  becomes a number ranging from 00 to 23, and so on).
  The following are converted to AM-PM text:
  t: a/p, tt: am/pm, T: A/P, TT: AM/PM.
  To include literal text containing letters, enclose it in quotation marks (")
  to avoid having the letters converted as per the above.
 