# Viewer

## Usage

    viewer.exe [settings_file]
    viewer.exe --help

Argument | Description
--- | ---
`settings_file` | Path to settings.txt (default: `settings.txt`)

## Description

The viewer displays output frames from shared memory with calibrated grid line overlays for precision distance measurement. It copies each frame to a local buffer before rendering to avoid tearing from concurrent writes.

## Keyboard Controls

Key | Action
--- | ---
`Right Arrow` | Step forward 1 frame
`Left Arrow` | Step back 1 frame
`Down Arrow` | Step forward 7 frames (Shift: 15 frames)
`Up Arrow` | Step back 7 frames (Shift: 15 frames)
`Page Down` | Jump forward 25 frames
`Page Up` | Jump back 25 frames
`1` | Toggle main grid lines on/off
`2` | Toggle sub-meter grid lines on/off
`F1` | Open help documentation
`ESC` or `Q` | Quit

## Mouse Controls

Action | Effect
--- | ---
Move cursor | Distance readout updates at cursor position (top-left corner)
Hold right button + move left/right | Fast navigation through the video — move the mouse left to go backward, right to go forward. Scrolls at 3× speed, covering many frames quickly.
Hold right button + Shift + move left/right | Extra-fast navigation at 6× speed for jumping through large sections of video
Scroll wheel | Step forward or backward one frame at a time for precise frame-by-frame navigation

## Distance Measurement

When grid lines are enabled, the viewer calculates the distance at the cursor position by:

1. Finding the two adjacent grid lines that bracket the cursor's vertical position
2. Projecting the lines to the cursor's Y coordinate using perspective interpolation
3. Computing the fractional position between the lines
4. Displaying the result as meters (e.g., "87.3 M")

Accuracy depends on correct grid line calibration.

## Grid Line Display Modes

- Mode 0 (off) — No grid lines displayed
- Mode 1 — Main meter lines only (press `1`)
- Mode 2 — Sub-meter lines with half-meter markers (press `2`)

## Window Size

The viewer window size is configurable in settings:

    big_window_width=1920
    big_window_height=540

The window is resizable at runtime. The SDL3 renderer scales the frame to fit.

## See Also

- Grid Line Calibration
- File Viewer — offline version
- Testing with Video Files