# fluxEarth

A Window Maker style rotating globe dockapp for the Fluxbox slit. Displays
Earth with orthographic projection, day/night terminator, limb darkening, and
an embedded NASA Blue Marble texture. The globe centers on the user's location.

Part of the [Flux Dock Apps Suite](https://osugisakae.com/software/flux-dock-apps/).

## Screenshot

```
┌──────────────┐
│              │
│    🌍        │  ← Earth with day/night terminator
│              │
└──────────────┘
```

## Installation

Requires Rust and a working X11 environment.

```sh
cargo build --release
cp target/release/fluxEarth ~/.local/bin/
```

The release build is stripped and LTO-optimized. No runtime dependencies beyond
libc and libX11.

## Usage

```
fluxEarth [OPTIONS]
```

Add `fluxEarth` to your Fluxbox startup to embed it in the slit.

### Options

| Flag | Description |
|---|---|
| `--size SIZE` | Window size: 64, 96 (default), or 128 pixels |
| `--font PATH` | Path to a TTF/OTF font file |
| `--latitude DEG` | Override latitude (decimal degrees) |
| `--longitude DEG` | Override longitude (decimal degrees) |
| `--background`, `--bg` | Run in background |
| `--write-config [PATH]` | Write annotated config file and exit |
| `--configure` | Interactive configuration wizard |
| `--help` | Show help message |

### Click behavior

| Button | Action |
|---|---|
| Left click | Toggle sun detail popup (or run `left_click` command) |
| Middle click | Run `middle_click` command (if configured) |
| Right click | Run `right_click` command (if configured) |

### Popup info

The left-click popup shows sun data (same as fluxSun):
- Sunrise and sunset times
- Solar transit (noon)
- Civil twilight begin and end
- Day length

### Globe rendering

- Orthographic projection covering ~88% of window area
- Per-pixel inverse projection to lat/lon with equirectangular texture lookup
- Day/night terminator via subsolar point with smoothstep transition (~6°)
- Limb darkening: 1.0 - 0.25*(dist/radius)²
- Anti-aliased edge
- Subsolar point updates every 60 seconds using solar declination and
  Equation of Time correction

### Location

Location is resolved in order:
1. `--latitude`/`--longitude` CLI flags
2. `latitude`/`longitude` in config file
3. fluxData location (from `data.json`)
4. Default: 0°N, 0°E

## Configuration

Config file: `~/.config/fluxEarth/config`

Generate an annotated config:

```sh
fluxEarth --write-config
```

Or use the interactive wizard:

```sh
fluxEarth --configure
```

### Config options

```ini
# Window size: 64, 96, or 128 pixels
size = 96

# Font file path (leave unset for auto-detect via fontconfig)
font = /path/to/font.ttf

# Main color (R, G, B)
color = 0, 255, 0

# Dim color (R, G, B)
dim_color = 0, 200, 0

# Override location (decimal degrees)
latitude = 40.7128
longitude = -74.0060

# Left click command (default: toggle sun detail popup)
left_click =

# Middle click command
middle_click =

# Right click command
right_click =

# Run in the background
background = true
```

### Font discovery

Font is resolved in order:
1. `--font` flag or `font` config option
2. fontconfig (`fc-match monospace`)
3. Hardcoded paths (DejaVu Sans Mono, Liberation Mono, Noto Sans Mono)

### Embedded asset

The NASA Blue Marble texture (`assets/earth.png`, 512x256 equirectangular) is
embedded in the binary at compile time.

### fluxData integration

fluxEarth reads `~/.local/share/fluxData/data.json` for location and sun data.
Start fluxData before fluxEarth for full functionality.

## License

[CC0 1.0](LICENSE) — Public Domain