# Grid Line Calibration

## Overview

Grid lines are the foundation of distance measurement. Each line represents a known meter mark on the hill. The viewer interpolates between lines to calculate the distance at any cursor position.

## Concepts

### Anchor Points

Each grid line is defined by two anchor points:

- Far point (`@far[feed][line]`) — where the meter mark crosses the far edge of the landing hill (top of frame or vanishing point)
- Near point (`@near[feed][line]`) — where the meter mark crosses the near edge (bottom of frame, closer to camera)

The viewer draws a line between these two points. Because of perspective, lines closer to the camera are spaced farther apart on screen.

### Perspective Projection

The system uses linear interpolation in screen space between adjacent grid lines. For a cursor at vertical position Y between two lines at Y1 and Y2:

    fraction = (Y - Y1) / (Y2 - Y1)
    distance = meter1 + fraction * (meter2 - meter1)

This linear model is accurate when grid lines are close together (1-meter increments).

## Calibration Procedure

### Prerequisites

- Video footage showing the landing hill with visible distance markers
- Known meter positions on the hill (painted marks, surveyor stakes, etc.)
- The file viewer or live viewer running

### Step 1: Set Line Parameters

In `settings.txt`, configure the range for each feed:

    # Feed 0 (top of hill camera): 80m to 99m
    meter_line_count[0]=20
    meter_line_start[0]=80
    meter_line_increment[0]=1
    meter_line_radius[0]=1

    # Feed 1 (middle camera): 100m to 119m
    meter_line_count[1]=20
    meter_line_start[1]=100
    meter_line_increment[1]=1
    meter_line_radius[1]=1

    # Feed 2 (bottom of hill camera): 120m to 139m
    meter_line_count[2]=20
    meter_line_start[2]=120
    meter_line_increment[2]=1
    meter_line_radius[2]=1

### Step 2: Identify Reference Points

In the video, locate visible distance markers on the hill. You need at least two known points per feed, but calibrating every meter line gives the best accuracy.

### Step 3: Set Anchor Points

For each visible meter mark, record the pixel coordinates where the mark intersects the far and near edges of the hill:

    # Feed 0, line 0 = 80 meters
    @far[0][ 0]=480,120
    @near[0][ 0]=320,950

    # Feed 0, line 1 = 81 meters
    @far[0][ 1]=510,120
    @near[0][ 1]=360,950

Tip: Use the mouse cursor position display in the viewer to read pixel coordinates. Move the cursor to where a known meter mark crosses the hill edge and note the X,Y values.

### Step 4: Verify

1. Save `settings.txt`
2. Press `1` in the viewer to enable grid lines
3. Verify that lines align with known distance markers on the hill
4. Move the cursor along the hill and check that the distance readout matches known positions

### Step 5: Fine-tune

If lines don't align perfectly:

- Adjust individual anchor points in `settings.txt`
- Reload settings (restart viewer or use controller's Settings tab)
- Repeat until lines match the physical markers

## Tips for Accurate Calibration

- Calibrate in clear weather with good visibility
- Use high-contrast reference markers (painted lines, colored stakes)
- Calibrate each feed independently — camera angles differ
- More anchor points = better accuracy (set every meter line if possible)
- The near and far points should be as far apart vertically as possible
- Re-calibrate if cameras are moved, even slightly

## Grid Line Display Modes

Mode | Key | Display
--- | --- | ---
0 | (default off) | No grid lines
1 | `1` | Main meter lines at configured color
2 | `2` | Main lines plus sub-meter half-meter markers

## Settings Summary

Setting | Purpose
--- | ---
`meter_line_count[N]` | Number of grid lines per feed
`meter_line_start[N]` | First meter mark value
`meter_line_increment[N]` | Meters between lines (usually 1)
`meter_line_radius[N]` | Line thickness in pixels
`@far[N][L]` | Far anchor point for line L
`@near[N][L]` | Near anchor point for line L
`meter_line_Y/U/V` | Main line color
`meter1_line_Y/U/V` | Highlighted line color
`meterD_line_Y/U/V` | Sub-meter division color

## See Also

- Viewer — distance measurement controls
- Settings Reference — all grid line parameters
- Testing with Video Files — calibrate from recordings