# astrophotography

Everything to do with taking, processing and understanding astronomical images:
the remote telescopes, the code that turns their frames into pictures and
measurements, and the plans for observing in person.

Formed by merging the `itelescope` and `astro-pipeline` repositories, with the
history of both preserved.

## Layout

| Directory | What it is |
|---|---|
| **[itelescope/](itelescope/)** | The iTelescope.net remote telescope network: a review of every scope, a southern-target guide, the observing plans, and the points drain campaign |
| **[pipeline/](pipeline/)** | The processing and analysis code. Calibration, stacking, plate solving, rendering and the science analyses |
| **[observing/](observing/)** | Plans for observing in person. Currently the total solar eclipse of 12 August 2026 from Menorca |
| **[state/](state/)** | Project state under the Default Workflow: objective, current work, decisions, working notes |
| **[docs/](docs/)** | The Default Workflow itself: branching, commits, documentation policy, cost control |

## Start here

- Planning or reviewing a remote imaging run: **[itelescope/CAMPAIGN.md](itelescope/CAMPAIGN.md)** and **[itelescope/TELESCOPES.md](itelescope/TELESCOPES.md)**
- Processing a session's data: **[pipeline/README.md](pipeline/README.md)**
- What is happening right now: **[state/TODO.md](state/TODO.md)**
- Why something was done a particular way: **[state/DECISIONS.md](state/DECISIONS.md)**

## Where the image data lives

**Not in this repository.** A single calibrated frame is 61 MB and a session
runs to several gigabytes, so sessions stay on disk and the code finds them
through the `ASTRO_SESSION` environment variable:

```
set ASTRO_SESSION=...\NGC5128\20260721
python pipeline/stack.py
```

Each session directory carries its own `METHODS.md` describing what was done to
that data and what was found, written for a reader who was not there. The code
lives here; the pixels and the account of them live with the data.

## Things learned the hard way

Recorded because each cost real time or real money, and because each is a
requirement for anything built next rather than a curiosity:

- **Measure whether a core is saturated before buying time to fix it.** A
  foreground star 69 arcsec from Centaurus A's nucleus was mistaken for the
  galaxy, and a telescope booking was made to solve a problem that did not
  exist. Filter the stars out of the measurement first.
- **Vet moving-object candidates in detector coordinates.** Registration holds
  the sky still, so it drags sensor defects across the frame on perfectly
  straight, constant-rate tracks. Hot pixels are better-behaved asteroids than
  real asteroids. One cut took 141 confident spurious detections to zero.
- **Never compare an aperture magnitude against a point-source catalogue
  without checking the source is a point.** A resolved object looks exactly like
  a 2.8 magnitude outburst.
- **Never fit a sky background to a field the target fills.** A plane fitted
  around a large galaxy eats its halo, measured at -17.9 ADU/px. Fit the
  background and a source model together.
- **A photographic ND filter is not a solar filter.** It passes the infrared
  that carries the heat.