# Video Align: instructions for AI-assisted reproduction

This document describes a reproducible workflow for an AI system or human developer implementing astronomical video alignment. It is a methodological guide, not hidden model instructions and not a claim that every dataset can be processed automatically.

## Objective

Given a video containing a drifting or rotating star field and an approximately linearly moving object:

1. retain every readable frame;
2. align the stellar background without reducing the recorded image scale;
3. expand the output canvas so every recorded region remains available;
4. mark absent regions white and match overlapping brightness robustly;
5. detect and centre the moving object;
6. produce common-coverage crops;
7. export mean and median products as PNG and FITS;
8. keep all processing local and document every calibration assumption.

## Recommended processing order

### 1. Decode and inspect every frame

- Preserve original dimensions, frame order and frame rate.
- Reject no frame silently. Record unreadable or deliberately excluded frames with reasons.
- Check whether usable WCS metadata exists. Ordinary MP4 normally contains none.

### 2. Register the stellar field

- Remove broad background temporarily for detection.
- Detect many stellar point candidates.
- Combine phase correlation with matched point positions.
- Fit translation and small rotation robustly, for example with affine RANSAC.
- Measure and report the residual registration error.

### 3. Build the expanded canvas

- Transform the four corners of every input frame.
- Use their global bounds as the output canvas.
- Never shrink the video merely to obtain a common field.
- Fill pixels missing from a particular frame with white.
- Match brightness only in valid overlapping regions with a robust statistic.

### 4. Estimate stationary sensor structure

- Work in original sensor coordinates before image registration.
- Repair persistent hot and dark pixels from a robust temporal statistic.
- Create a registered sky model, project it back into each original frame and subtract it.
- Combine the remaining residuals robustly to estimate stationary additive horizontal, vertical and non-separable fixed-pattern noise.
- Subtract this additive pattern before applying any multiplicative flat.
- A direct temporal-median residual pass may remove remaining stationary bands, but must be checked for suppression of real extended sky structure.

### 5. Apply broad flat and cloud correction

- Derive only broad multiplicative illumination structure from the sensor-calibrated frames.
- In star-aligned coordinates, compare every frame with the robust temporal sky model.
- Estimate a broad per-frame illumination or cloud field with normalized weighted smoothing so missing borders do not contaminate it.
- Define an unrest index from robust spatial variation and frame-to-frame change of that field.
- Use the index to control correction strength. Do not claim that obscured stars can be reconstructed; only background and transparency variations can be normalized.

### 6. Detect the moving object

- Subtract the temporal median stellar background in registered coordinates.
- Search only within coverage shared by all relevant frames.
- Score candidate paths across time and fit an approximately linear trajectory.
- Preserve the fitted position for every frame.

### 7. Produce both reference systems

- Stellar reference: keep registered stars fixed.
- Object reference: shift every registered frame so the fitted moving object remains at the same pixel position.
- For each reference system, produce the expanded view and the largest axis-aligned rectangle covered by every frame.

### 8. Export and verify

- Encode playable H.264 MP4 with a web-compatible pixel format.
- Add the requested visible attribution to every output video.
- Export arithmetic mean and per-pixel median for every complete sequence.
- Write PNG previews and FITS arrays with frame-count metadata.
- Verify every video, every link, every FITS file and every claimed count.

## Scientific cautions

- Video-derived pseudodarks and pseudoflats do not replace measured calibration frames.
- Clouds can attenuate or erase astronomical signal; normalization cannot recreate missing photons.
- A stationary-pattern estimate may accidentally absorb extended celestial structure when field motion is insufficient.
- Compare star flux, FWHM, background variation and moving-object morphology before and after every correction.
- Keep intermediate masks, diagnostic measurements and algorithm parameters inspectable.

## Development acknowledgement

Video Align was developed by Jost Jahn with assistance from OpenAI Codex. AI was used as a development tool, not as a runtime image-processing service. The implementation uses deterministic local algorithms and established components including Python, NumPy, OpenCV, Astropy, FFmpeg and PyInstaller.