# Stupid Satellites

> Desktop app (macOS + Windows) that removes satellite and plane trails from astrophotos by subtracting the trail's light. The app binary is also a CLI, so an AI agent on the user's machine can clean photos with no UI.

Everything runs locally. No network access, nothing is uploaded.

## Find the binary

Try `stupidsat --version` first. If it is not on PATH, use the per-OS path:

- Windows (installer): `stupidsat` is on PATH after install (installer option, on by default). A terminal opened before the install will not see it; open a new one. Full path: `%LOCALAPPDATA%\Programs\StupidSatellites\stupidsat.exe`
- macOS (direct download / DMG): `/Applications/Stupid Satellites.app/Contents/MacOS/Stupid Satellites` (quote it; the path has spaces). To put it on PATH:
  `mkdir -p ~/.local/bin && ln -sf "/Applications/Stupid Satellites.app/Contents/MacOS/Stupid Satellites" ~/.local/bin/stupidsat` (and make sure `~/.local/bin` is on PATH)
- Mac App Store build: sandboxed. It CANNOT open files passed on the command line. Tell the user to install the direct download from https://stupidsatellites.com/download/
- Source install: `pip install -e .` provides `stupidsat`

## Recommended workflow

1. `stupidsat --version` — confirm the binary works.
2. `stupidsat detect photo.tif` — preview what would be removed. No edits.
3. `stupidsat clean photo.tif --json` — remove the trails; parse the JSON on stdout.
4. Report the `auto` trails removed and any `suggestions` left for the user.

Process files one at a time. Do not overwrite originals unless the user asks (`--in-place`).

## Commands

- `stupidsat clean photo.tif` — writes `photo_clean.tif` next to the input
- `stupidsat clean photo.tif -o out.tif` — choose the output path
- `stupidsat clean photo.tif --in-place` — overwrite the input
- `stupidsat clean photo.tif --lines lines.json` — also write the trail list to a file
- `stupidsat clean photo.tif -v` — progress on stderr
- `stupidsat clean photo.tif --json` — stdout is exactly one JSON object (below)
- `stupidsat detect photo.tif` — detection only; JSON on stdout; no edits
- `stupidsat detect photo.tif --json out.json` — write the detection JSON to a file instead
- `stupidsat gui photo.tif` — open the review UI (for a human)
- `stupidsat --version`

## JSON output

`clean --json` (stdout, one object):

```
{
  "input": "photo.tif",
  "output": "photo_clean.tif",
  "auto": [ /* trail objects, removed */ ],
  "suggestions": [ /* trail objects, NOT removed */ ],
  "seconds": 12.3
}
```

`detect` (stdout or `--json` file):

```
{ "auto": [ ... ], "suggestions": [ ... ] }
```

Trail object:

```
{ "id": 0, "p1": [x, y], "p2": [x, y], "score": 14.2, "channel": "L", "is_dash": false, "enabled": true }
```

- `p1`, `p2`: trail endpoints in full-resolution pixel coordinates, `[x, y]`
- `score`: detection strength (sigma)
- `channel`: `"L"` (luminance) or `"R"` (red)
- `is_dash`: dashed/blinking trail (typically a plane's strobes)

## Exit codes

- `0` — success
- `1` — failure; stderr has `error: <message>`

## Formats

- Input: TIFF, JPEG, PNG, DNG, and camera raws (ARW, CR2, CR3, NEF, RAF, ORF)
- Output: 16-bit TIFF, EXIF preserved

## Guarantees

- Subtraction only: the trail's light is removed; nothing is painted in or generated. Stars are never invented. No AI.
- Pixels outside trail corridors are byte-identical to the input.
- Stars sitting on a trail keep their own flux.

## Limits

- `suggestions` are faint candidates where trail vs. real sky is undecidable. `clean` does NOT remove them. Tell the user and let them confirm in `stupidsat gui photo.tif`.
- The Mac App Store build cannot be used from the command line (sandbox). Use the direct download.

## Docs

- [Command line reference](https://stupidsatellites.com/docs/#cli)
- [For AI agents](https://stupidsatellites.com/docs/#agents)
- [Download](https://stupidsatellites.com/download/)