Field GPS / NMEA Map Generator

A lightweight desktop-style web app for generating realistic GPS / NMEA paths from field boundaries. Designed for agriculture, simulation, testing, and replay workflows.

The application runs a local Flask server, opens automatically in your browser, and can be packaged as a single Windows EXE with no console window.

---

✨ Features

• Draw field boundaries directly on a map
• Optional exclusion zones (sloughs, trees, obstacles)
• Automatic headlands + interior passes
• Constant or randomized speed profiles
• Adjustable sampling rate (Hz)
• Generates valid NMEA GPRMC + GPGGA messages
• Outputs files with a .gps extension
• Saves exports to a predictable local folder
• Preview path before generation
• Single‑instance protection (no double servers)
• Clean quit / shutdown support

---

🗂 Output Files

• Files are always saved with a .gps extension
• MIME type is set to application/octet-stream to avoid browser issues

Default export location (Windows)

C:\Users\<you>\Documents\FieldNMEA\Exports

The generated file is also downloaded automatically by the browser.

---

🧠 How It Works (Architecture)

• Flask runs locally on http://127.0.0.1:5000
• UI is served from templates/index.html
• Geometry is handled with Shapely
• Coordinate transforms via pyproj
• NMEA generation is fully deterministic and reproducible

When packaged as an EXE:

• Flask runs in the background
• Browser is opened automatically
• No console window is shown

---

🚀 Running From Source (Dev Mode)

1. Create & activate venv

python -m venv .venv
.\.venv\Scripts\Activate.ps1

2. Install dependencies

pip install -r requirements.txt

3. Run the app

python app.py

Your browser will open automatically.

---

🧯 Single‑Instance Protection

If you double‑click the EXE while it’s already running:

• The existing instance is reused
• No second Flask server starts
• A new browser tab is opened instead

This is implemented using:

• /health endpoint
• Local TCP lock port

---

❌ Quit / Shutdown Behavior

The UI includes a Quit App button.

When clicked:

• The browser tab closes
• A /shutdown request is sent
• The Flask process terminates cleanly

No orphan background processes remain.

---

📦 Building the Windows EXE

1. Install PyInstaller

pip install pyinstaller

2. Build

pyinstaller --onefile --noconsole --name FieldGPSMapGenerator --add-data "templates;templates" app.py

3. Result

dist\FieldGPSMapGenerator.exe

Double‑click to run.

---

📁 Project Structure

MapMaker-Release/
│
├── app.py
├── requirements.txt
├── README.md
├── templates/
│   └── index.html
└── dist/
    └── FieldGPSMapGenerator.exe

---

⚠️ Notes & Limitations

• Intended for local use only (not a hosted server)

• Geometry may fail if:

  • Field is too small
  • Implement width is too large
  • Excessive exclusions collapse the polygon

Error messages will guide parameter adjustments.

---

🧪 Health Check

The app exposes:

GET /health

Returns:

{ "status": "ok" }

Used for single‑instance detection.

---

🧩 Future Ideas

• ISOXML export
• Multiple vehicle tracks
• Curved guidance lines
• Speed ramps by headland / interior
• CAN / J1939 replay hooks
• Realistic headlands and AB lines

---