# fluxSolarSystem

A Window Maker style solar system viewer dockapp for the Fluxbox slit. Renders
a top-down view of the solar system with the Sun at the centre, faint orbit
rings, and the eight major planets as coloured dots at their current
heliocentric positions. Left-click brings up a popup with per-planet
distances. Inspired by [wmsolar](https://github.com/engerim42/wmsolar).

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

## Screenshot

```
┌──────────────┐
│  · ◯ ◯  · .  │  ← faint orbit rings
│ . ◯ ◉ ◯  ·   │  ← Sun in centre, planets as coloured dots
│  ◯  ·  ◯ .   │
└──────────────┘
```

## Installation

Requires Rust and a working X11 environment.

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

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

## Usage

```
fluxSolarSystem [OPTIONS]
```

Add `fluxSolarSystem` 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 (used by the popup) |
| `--interval SECS` | Position update interval in seconds (default 60) |
| `--theme THEME` | Color theme (e.g. `zenburn`) |
| `--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 per-planet distances popup (or run `left_click` command) |
| Middle click | Reload config (or run `middle_click` command) |
| Right click | Run `right_click` command (if configured) |

### Popup info

The left-click popup shows, for the current UTC date and time:

- Heliocentric distance for each planet (AU)
- Distance from Earth for each planet (AU)

## How it works

Planet positions are computed from the [JPL Standish 2006 Keplerian
elements](https://ssd.jpl.nasa.gov/planets/approx_pos.html), valid for
dates in the range 1800 — 2050 AD. Each tick:

1. Compute Julian centuries since J2000.
2. Linearly interpolate each planet's orbital elements.
3. Solve Kepler's equation iteratively (Newton's method).
4. Convert from the perifocal frame to ecliptic Cartesian coordinates.
5. Project (X, Y) to the screen with logarithmic radial scaling so that
   inner planets and outer planets fit in the same dock window.

Earth's distance to a given planet is computed directly from heliocentric
ecliptic coordinates (`|r_planet − r_earth|`).

## Configuration

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

Generate an annotated config:

```sh
fluxSolarSystem --write-config
```

Or use the interactive wizard:

```sh
fluxSolarSystem --configure
```

### 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)

## License

[CC0 1.0](LICENSE) — Public Domain