Randall Clock

Current Version: 1.1.6

Live web clock: hromp.com/clock/

Change your Linux desktop background using the XKCD "Now" clock or the "dark mode" rendition of it (with green overlay!). The same Black Mode clock is also available as a static web page with automatic red-dot placement from the viewer's geolocation.

Optionally put a red dot on the image showing your location.

Special thanks to Randall Munroe and Fred Weinhaus

---

Web Clock

The web version lives entirely under web/ and does not modify the desktop install. Full details are in web/README.md.

Quick deploy

1. Serve the web/ directory as static files (nginx, Apache, or any static host).
2. Use HTTPS in production (browser geolocation requires a secure context).
3. Image assets are in web/assets/ (base_globe.png, stationary_overlay.png).

Local smoke test:

cd web && python3 -m http.server 8080
# open http://localhost:8080/

nginx (subpath example)

If the clock is served from a subpath such as /clock/ (as on hromp.com/clock/), see web/deploy/nginx-subpath.conf.example. You need:

• A location block to serve files from web/
• A same-origin geolocation proxy (location /clock/api/geo) if your site CSP blocks third-party geo APIs

location /clock/api/geo {
    proxy_pass https://ipwho.is/;
    proxy_set_header Host ipwho.is;
    proxy_ssl_server_name on;
    add_header Cache-Control "no-store";
}

location /clock/ {
    alias /path/to/randall-clock/web/;
    index index.html;
    try_files $uri $uri/ /clock/index.html;
}

For a dedicated vhost at the domain root, see web/deploy/nginx.conf.example. Apache examples are in web/deploy/apache.conf.example.

Geolocation

Priority	Source	Notes
1	URL params	?lat=44.5&lon=-72.5 for testing
2	Browser	Prompts for permission; most accurate
3	IP address	Runs in parallel; used when browser access is denied

The globe and correct time display work without geolocation — only the red dot needs a location.

Validate red-dot placement

With the dev server running, open web/tools/validate-projection.html to overlay reference cities on the globe and confirm projection accuracy.

---

Example Images

XKCD Original	Black Green Overlay	Black Green Overlay + Red Dot

---

Project Structure

randall-clock-desktop-background/
├── README.md
├── CHANGELOG.md
├── web/                          # Static web deployment (see web/README.md)
├── install.sh
├── config.ini
├── requirements.txt
├── posterity.pdf
├── timeupdate.bash
├── xkcdOriginalExample.png
├── blackGreenOverlayExample.png
├── blackGreenOverlayRedDotExample.png
├── src/
│   ├── images/
│   │   ├── masks/                  # Alpha masks for globe extraction
│   │   ├── overlays/               # Stationary overlay images
│   │   ├── intervals15m/           # 15-minute interval image sets
│   │   │   ├── xkcdOriginal/           # Original XKCD frames
│   │   │   └── blackGlobeGreenOverlay/ # Black globe with green overlay
│   │   └── intervals1m/            # 1-minute interval image sets
│   │       ├── blackGreenOverlay/      # 1-minute frames (no red dot)
│   │       └── blackGreenOverlayRedDot/ # 1-minute frames (with red dot)
│   └── scripts/
│       ├── generate-masks.py           # Generate globe masks and overlay
│       ├── generate-frames.py          # Generate 1-minute interval frames
│       ├── red-dot.py                  # Add red dot to frames
│       ├── pick-location.py            # Pick your location for the red dot
│       └── measure-globe.py            # Measure globe center/radius
└── ...

Script Explanations

• generate-masks.py: Generates alpha masks for extracting the globe from each 15-minute frame and creates the stationary overlay.
• generate-frames.py: Generates 1-minute interval frames by rotating the globe and compositing it with the overlay.
• red-dot.py: Adds a red dot to each frame, indicating your chosen location, and rotates it with the globe.
• pick-location.py: Lets you interactively pick your location on the globe for the red dot.
• measure-globe.py: Lets you measure the center and radius of the globe for accurate dot placement.

---

Desktop Background Install

Black Mode displays a black background with a green overlay showing the current time. The clock is viewed from the south pole and uses a 24-hour dial. The time display is calibrated with a fixed offset to ensure correct time alignment regardless of installation time.

Quick Install (Recommended)

Run:

./install_blackmode.sh

Or the legacy installer:

./install.sh

This will:

• Check and install dependencies (shows the apt-get command before prompting for sudo)
• Prompt for red dot, location, style, and interval
• Generate overlays, masks, frames, and red dot images as needed
• Set up a cron job for background updates

See Black Mode Installation below for the recommended Black Mode setup with systemd and cron.

Manual Install

1. Install dependencies:

   sudo apt-get install feh imagemagick python3 python3-pip python3-tk python3-pil python3-numpy
   pip3 install -r requirements.txt

2. Generate images:
   • Generate masks and overlay:

     python3 src/scripts/generate-masks.py

   • Generate 1-minute frames:

     python3 src/scripts/generate-frames.py

   • (Optional) Pick your location for the red dot:

     python3 src/scripts/pick-location.py

   • (Optional) Measure globe center/radius:

     python3 src/scripts/measure-globe.py

   • (Optional) Add red dot to frames:

     python3 src/scripts/red-dot.py

3. Set up the background update:
   • Make the update script executable:

     chmod +x timeupdate.bash

   - Add a cron job:
   ```bash
   crontab -e
     # For 1-minute interval:
     * * * * * /path/to/timeupdate.bash
     # For 15-minute interval:
   */15 * * * * /path/to/timeupdate.bash
   

---

Example config.ini

[DEFAULT]
image_style = black
interval = 1m
output_dir = src/images/intervals1m/blackGreenOverlay
mask_dir = src/images/masks
overlay_dir = src/images/overlays
RedDot = 1

[LOCATION]
x = 631
y = 857
mode = black

[BLACK_GLOBE]
center_x = 960
center_y = 960
radius = 900
width = 1920
height = 1920

[XKCD_GLOBE]
center_x = 480
center_y = 480
radius = 450
width = 960
height = 960

• image_style: The style of images to use for the clock (black or xkcd).
• interval: The interval for background updates (1m or 15m).
• output_dir: Where generated frames are saved.
• mask_dir: Where alpha masks are stored.
• overlay_dir: Where overlay images are stored.
• RedDot: 1 to enable the red dot, 0 to disable.
• [LOCATION]: Your picked coordinates and style.
• [BLACK_GLOBE]/[XKCD_GLOBE]: Globe measurement data for accurate dot placement.

---

Troubleshooting

• Make sure all dependencies are installed (see above).
• If the background is not updating:
  1. Make sure feh is installed
  2. Check if the script is executable
  3. Verify your display is set correctly (e.g., DISPLAY=:0)
  4. Check cron logs: grep CRON /var/log/syslog
  5. For Black Mode: Check systemd user service status: systemctl --user status randall-clock-setup.service
  6. For Black Mode: Check service logs: journalctl --user -u randall-clock-setup.service
  7. Check the update log: tail -f /tmp/randall-clock/update_background.log
• If the background doesn't set on reboot/login:
  1. Verify the systemd user service is enabled: systemctl --user is-enabled randall-clock-setup.service
  2. Ensure the service runs after login: systemctl --user start randall-clock-setup.service
  3. Check that X display is available when the service runs
• If you have issues with the red dot or image generation, check the output directories and rerun the relevant scripts with overwrite enabled.

---

Credits

• XKCD "Now" clock: xkcd.com/1335
• Explanation: explainxkcd.com/1335
• Black globe version and batch image processing: Fred Weinhaus's ImageMagick scripts

Black Mode Installation

Quick Install

Run the installation script:

./install_blackmode.sh

This will:

• Check and install dependencies
• Prompt for update interval (how often the clock updates, in minutes)
• Prompt for location (to place the red dot on the globe)
• Generate the base globe image with the red dot
• Set up a cron job for periodic background updates
• Set up a systemd user service to run the background update at login
• Set the initial desktop background

Command-Line Arguments

For automated or non-interactive installation, you can use command-line arguments:

./install_blackmode.sh -i 5 -d s

Options:

• -i interval - Update interval in minutes (1-60, e.g., -i 5 for 5-minute updates)
• -d dot_option - Red dot option: s to skip (use previous location from config.ini) or p to pick location interactively
• -h - Show help message

Examples:

# Interactive installation
./install_blackmode.sh

# Non-interactive: 5-minute updates, skip location picker
./install_blackmode.sh -i 5 -d s

# Non-interactive: 3-minute updates, pick new location
./install_blackmode.sh -i 3 -d p

# Show help
./install_blackmode.sh -h

Automatic Setup at Login

The installation script automatically sets up a systemd user service (randall-clock-setup.service) that runs update_background.sh when you log in. This ensures:

• The background is set correctly after reboot/login
• X display is available (systemd service runs after graphical-session.target)
• The clock starts correctly on each login

The service is enabled automatically during installation. To manually check its status:

systemctl --user status randall-clock-setup.service

To disable it:

systemctl --user disable randall-clock-setup.service

Periodic Updates

The installation script also sets up a cron job that runs update_background.sh at your specified interval (e.g., every 5 minutes). This keeps the clock display current throughout your session.

To view your cron jobs:

crontab -l

Black Mode Globe Workflow

The black mode globe is generated in two phases:

1. Installation Phase
   During installation (via install_blackmode.sh), a base globe image is created with the red dot already placed on it. This is done using the --create-base flag along with the --dot-x and --dot-y coordinates. The resulting image is saved as base_globe_with_dot.png.

2. Update Phase
   During updates (via update_background.sh), the pre-created base_globe_with_dot.png is used as the base image. Since the red dot is already part of the base image, the update process does not add a new dot. Therefore, the update script sets use_red_dot to False, and dot_x and dot_y are None. The workflow is as follows:

   • Installation: Create base globe with red dot → save as base_globe_with_dot.png
   • Updates: Use base_globe_with_dot.png → rotate it → update background