FindTheRails – Rail Tracking Overlay Prototype

ScreenCapture10x10 is a .NET console app that:

• Captures the primary display at native resolution for a fixed duration
• Detects two railway rails in the bottom part of the image
• Tracks the rails upward through the frame over time
• Draws thin white lines along the rails plus a red “bullseye” at the farthest visible point
• Exports a PNG sequence and an MP4 video for review

It’s designed to work with full-screen locomotive cab videos and act as a prototype for an AI-assisted track-following light system.

---

High-Level Flow

1. Capture phase

   • Records the primary screen for durationSeconds at framesPerSecond.
   • Frames are held in memory as Bitmap objects.
   • Capture is time-based (wall-clock), not frame-count based.
   • Capture stats (timing, FPS) are logged to the console.

2. Rail detection & tracking phase

   • For each frame:
     • Runs an initial bottom lock-on using TryInitialLockOnBottomBlocks:
       • Takes a 100px-tall band at the bottom of the frame.
       • Scans horizontally using paired snippets (two 200×100 blocks separated by a fixed offset).
       • Uses RailSnippetAnalyzer to:
         • Convert the snippet to a simplified, quantized grayscale representation
         • Detect a strong linear feature (candidate rail)
         • Return (cx, angleDeg, lengthNorm, score)
       • Evaluates the pair of rails using:
         • Per-rail score and length
         • Angle agreement between left and right rails
         • Gauge reasonableness (distance between rails vs expected gauge)
       • Chooses the best rail pair and seeds the frame’s tracking state.
     • Runs TrackRailsInFrame:
       • Steps upward in overlapping horizontal slivers.
       • Within each sliver:
         • Uses a narrowed horizontal band based on the current rail positions.
         • Re-detects left/right rail positions using brightness analysis.
         • Applies limits on:
           • Max allowed horizontal shift per sliver
           • Max allowed change in rail separation
         • Falls back to recent verified track history if detection is noisy or fails briefly.
       • Writes all accepted rail coordinates into:
         • Per-frame point lists (for drawing)
         • A global TrackPoint database (for time-based lookups and debugging).

3. Overlay rendering phase

   • For each frame with at least minimal valid rail paths:
     • Draws 2px white polylines along each rail (DrawRailOverlayOnFrame).
     • Replaces the last few points of each rail with a red bullseye, centered on the averaged “tail” of both rails.
   • Frames with insufficient data are left unmodified.

4. Export phase

   • Saves all frames to an output folder as frame_###.png.
   • Optionally writes debug snippets in Snippets/:
     • Combined bottom band snippets
     • Per-pair analysis frames
     • Filenames encode scoring and geometry metadata.
   • Uses ffmpeg to build:
     • A main body video (capture_body.mp4) from the PNG sequence.
     • Optionally concatenates an intro video (Intro/intro.mp4) before the body and outputs capture.mp4.

---

Features

• Full-resolution screen capture
  No resizing, scaling, or cropping; the primary display is captured as-is.

• Rail-specific lock-on
  Uses geometric and brightness cues (length, orientation, gauge, angle agreement) to pick the best pair of rails from candidate snippets.

• Temporal tracking
  Tracks rails upward and maintains a global TrackPoint list with:

  • Frame index
  • X/Y coordinates
  • Timestamp
  • Left/right rail flag

• Error resilience

  • Rejects sudden implausible shifts (noise, artifacts).
  • Reuses recent “verified” track points if a few slivers fail.
  • Stops gracefully if tracking becomes unreliable.

• Overlay visualization

  • Thin white lines along both rails.
  • Red bullseye at the farthest visible point of the rails (end of usable tracking).
  • All overlays drawn directly onto the captured frames.

• Snippets & scoring for debugging

  • Writes bottom-band snippets and combined pair snippets into Snippets/.
  • Filenames encode:
    • dualScore (pair score)
    • Per-rail scores, lengths, angles
    • Gauge
    • Horizontal position (blockLeft)
  • Lets you sort by filename to see strongest rail candidates first.

---

Requirements

• OS: Windows 10 or later
• Runtime: .NET 8 (or compatible .NET desktop runtime)
• Graphics: Primary display accessible via System.Windows.Forms.Screen
• Libraries:
  • System.Drawing.Common (GDI+)
  • System.Windows.Forms
• External tool: ffmpeg (installed and accessible at the path hard-coded in Program.cs)

---

Building

1. Clone the repository:

   git clone <your-repo-url>.git
   cd <repo-folder>