# Star Chart Calculation and Rendering Implementation

## Overview

This document explains the implementation of a real-time star chart calculation and rendering feature for the meteor detection system. The feature uses astrometry.net's `solve-field` tool to solve for celestial coordinates in camera frames, then renders an overlay of stars and constellations.

## Components

### 1. StarChartOptions (Configuration)

The configuration is stored in the `config-example-updated.toml` file under the `[star_chart]` section:

```toml
[star_chart]
# Whether the star chart overlay is enabled
enabled = true
# Path to the astrometry.net solve-field binary
solve_field_path = "/usr/local/bin/solve-field"
# Path to the astrometry.net index files
index_path = "/usr/local/share/astrometry"
# Update frequency in seconds
update_frequency = 30.0
# Star marker color (B, G, R, A)
star_color = [0, 255, 0, 255] # Green
# Constellation line color (B, G, R, A)
constellation_color = [0, 180, 0, 180] # Semi-transparent green
# Star marker size
star_size = 3
# Constellation line thickness
line_thickness = 1
# Working directory for temporary files
working_dir = "/tmp/astrometry"
# Whether to show star names
show_star_names = true
# Size of index files to use (in arcminutes)
index_scale_range = [10.0, 60.0]
# Maximum time to wait for solve-field (seconds)
max_solve_time = 60
```

### 2. StarChart Module

Created a new module in `src/overlay/star_chart.rs` with the following components:

- `StarChart`: Main class for handling star chart calculation and rendering
- `SolutionHint`: Stores previous solution data for providing as a hint to future solves
- `Star` and `ConstellationLine`: Data structures for storing celestial objects
- Background thread for running astrometry.net calculations asynchronously

### 3. Integration with Main Application

The star chart component is integrated into the application in `src/app.rs`:

1. Added StarChart to the Application struct
2. Initialized the StarChart in the initialize() method
3. Registered a frame hook to apply the star chart overlay
4. Added shutdown handling for the StarChart

## Technical Details

### Astrometry.net Integration

The `solve-field` tool is executed with carefully chosen parameters:

- When a previous solution exists, it's used as a hint (ra, dec, radius, scale)
- Otherwise, GPS position is used as a general hint
- Scale range is provided to limit the search space
- A custom configuration file is created for pointing to the index files
- Timeout handling prevents hanging on difficult images

### Optimization Techniques

1. **Solution Hinting**: Each solution is saved and used as a hint for subsequent calculations, significantly improving performance.

2. **Background Processing**: Star chart calculations run in a separate thread to avoid blocking the main application.

3. **Frequency Control**: Calculations are performed at controlled intervals (configurable via `update_frequency`), not on every frame.

4. **Timeout Control**: Maximum solve time is configurable, preventing hang-ups on difficult frames.

## Usage

1. Ensure astrometry.net is installed with appropriate index files
2. Configure the `[star_chart]` section in the config file
3. The star overlay will be rendered on frames when solutions are available
4. Adjustments can be made to visualization parameters without restarting

## Future Enhancements

1. **Star Catalog Integration**: Currently uses a simplified method for rendering stars. Could be enhanced to use a proper star catalog.

2. **Advanced Celestial Rendering**: Add more detailed rendering of celestial objects beyond simple stars and constellations.

3. **WCS Library Integration**: Replace the simple WCS parsing with a proper WCS library for more accurate coordinate transformations.

4. **Parallel Solving**: Allow multiple solves to run in parallel for different regions of the sky.

5. **Sub-Frame Solving**: Process smaller sections of the image to improve solve speed.