location_plotter/macos/README.md

# Location Plotter

Qt6/C++ GUI that listens to a USB UART on macOS, parses normal debug lines,
and plots live locations on a map.

The application also includes an interactive 3D Earth/orbit view. It downloads the current
stream-derived RINEX 3 navigation file from the BKG/IGS archive at startup and every 15
minutes, then recomputes GPS satellite positions for current UTC every minute. The last valid
file is cached for offline startup.

## Parsed fields

The parser accepts labeled values in the same line or in separate lines:

```text
lat=41.0082 long=28.9784 hheight=123.45 sats=7
latitude: 41.0082 longitude: 28.9784 height: 123.45 activeSats: 7
active_sats=8
navigation software running with 5 satellites
GDOP : 3.9576744550
PDOP : 3.2540598660
HDOP : 2.3631161789
VDOP : 2.2370935468
TDOP : 2.2526165852
tracking PRNs: G03, G08, 14, 21
SV=G27
[LOCATION] source=gps lat=40.7357 lon=31.5985 height=812.0 gdop=4.7 pdop=4.1 hdop=2.7 vdop=3.0 tdop=2.3 tracked=6 used=5
[LOCATION] source=imu_corrected lat=40.7356 lon=31.5985 height=812.7 gdop=4.7 pdop=4.1 hdop=2.7 vdop=3.0 tdop=2.3 tracked=6 used=5
[LOCATION] source=trajectory lat=40.7358 lon=31.5987 height=812.1 tracked=4 used=4
lattitude : 40.78925034214206846173
longitude : 29.46277530841727809729
height    : -89.05779508221894502640
```

Accepted location labels:

- Latitude: `lat`, `latitude`, `lattitude`
- Longitude: `long`, `longitude`, `lon`, `lng`
- Height: `hheight`, `height`, `alt`, `altitude`
- Active satellites: `sat`, `sats`, `satellite`, `satellites`, `active_sats`,
  `activeSats`, `satellites_active`, `num_sats`, `uydu`
- DOP: `GDOP`, `PDOP`, `HDOP`, `VDOP`, `TDOP`
- GPS identifiers: `G03`, `PRN: 3`, `PRNs: 3, 8, 14`, `SV=G21`, `SVID: 27`
- Location source: `source=gps`, `source=imu_corrected`, `source=trajectory`
- `tracked` is accepted as the active satellite count; `used` remains visible in
  the raw UART line and denotes satellites used by the WLS solution.

If a satellite count arrives without a location, the active satellite display is updated.
If a location arrives without a satellite count, the latest known satellite count is attached
to that point.
If DOP values arrive before a location, the latest known values stay visible in the DOP
section and are attached to the next plotted point.
If latitude, longitude, and height arrive as separate consecutive lines, they are combined
into a single plotted point.

The GPS firmware's level-1 paired protocol is source-aware. Every received
`source=gps` location is added to the blue GPS series and every
`source=imu_corrected` location is added to the red corrected series at the
firmware-configured UART cadence.
Paths are built independently, so alternating UART lines do not create GPS-to-IMU
zigzags. A corrected point newer than one second is also preferred for map
auto-follow, the current-position label and the globe receiver marker. Raw GPS
outliers remain visible in blue for diagnosis without pulling the whole view away.
When corrected points exist, CEP50, average and scatter calculations use only that
corrected series; legacy input without a source keeps the previous behavior.
Synthetic `source=trajectory` points form a third independent green ground-truth
path. The map legend identifies all three series.

## UART log replay

Use the `UART Replay` button (or `Dosya > UART Log Replay...`) to feed a recorded
UART `.log`/`.txt` file back through the same parser used by the live serial port.
Choose the raw GPS update interval (default `200 ms`) and sensor/fused update
interval (default `50 ms`) in the replay dialog. Press `Replay Durdur` to stop.

Recorder timestamps are optional and do not control replay speed. The replayer
removes a leading timestamp when present, identifies `source=gps` as raw GPS and
`source=imu_corrected` or `[FUSION]` as fused/sensor output, then synthesizes the
two update timelines while retaining the original UART line order. Other UART
diagnostic lines are forwarded with the surrounding location update.

## Sentetik ESKF senaryolarini açma

GPS deposundan 48 kombinasyonun replay loglarini üretin:

```bash
cd /home/onur/Desktop/gps
make -C soc/software/fusion/tests scenario-logs
```

Sonra GUI'yi açıp `Senaryo Logu Ac` düğmesinden örneğin
`soc/software/fusion/tests/output/scenarios/car_gps200_imu20.log` dosyasını seçin.
GUI logdaki bütün rotayı otomatik sığdırır. Aynı dosya komut satırından da
doğrudan açılabilir:

```bash
cd location_plotter/macos
cmake -S . -B build
cmake --build build -j
./build/location_plotter --replay \
  /home/onur/Desktop/gps/soc/software/fusion/tests/output/scenarios/car_gps200_imu20.log
```

Tek bir özel kombinasyon üretmek için:

```bash
cd /home/onur/Desktop/gps/soc/software/fusion/tests
make platform_scenario_matrix_test
./platform_scenario_matrix_test --log aircraft 500 19 aircraft.log
```

Desteklenen senaryolar `stationary`, `pedestrian`, `car`, `aircraft`; GNSS
periyotları 200/500/1000 ms, IMU periyotları 19/20/200/300 ms'dir.

## macOS'ta kurulum (MacBook Air, Apple Silicon veya Intel)

Guncel macOS surumunde once [Homebrew](https://brew.sh) kurulu olmalidir. Ardindan:

```bash
cd location_plotter/macos
chmod +x setup-macos.sh run.sh
./setup-macos.sh
./run.sh
```

Betik Homebrew ile guncel `cmake` ve `qt` paketlerini kurar, yerel mimari icin
`location_plotter.app` paketini derler, gerekli Qt kutuphanelerini uygulama paketine
ekler ve testleri calistirir.

macOS USB UART aygitlarini genellikle iki adla gosterir:

```text
/dev/cu.usbserial-XXXXXXXX
/dev/tty.usbserial-XXXXXXXX
```

veya bir CDC aygitinda:

```text
/dev/cu.usbmodemXXXX
/dev/tty.usbmodemXXXX
```

Uygulama her iki bicimi de algilar. Mümkünse `cu.usb...` yolunu secin; macOS'ta
disariya baglanti baslatan uygulamalar icin uygun olan aygit budur. UART uygulama
acikken takildiysa port alaninin yanindaki `Yenile` dugmesine basin. Otomatik
algilanmayan bir yol port alanina elle de yazilabilir.

Istenen port baslatmadan once ortam degiskeniyle de secilebilir:

```bash
LOCATION_PLOTTER_PORT=/dev/cu.usbserial-XXXXXXXX ./run.sh
```

Port hic gorunmuyorsa `ls /dev/cu.usb* /dev/tty.usb*` ile macOS'un aygiti olusturup
olusturmadigini kontrol edin. Hic sonuc yoksa kabloyu/veri baglantisini ve UART
donaniminizin macOS surucusunu kontrol edin.

## Elle derleme

Homebrew ile `cmake` ve `qt` kurulduktan sonra derleme ve test:

```bash
cmake -S . -B build -DCMAKE_PREFIX_PATH="$(brew --prefix qt)"
cmake --build build
ctest --test-dir build --output-on-failure
```

Run:

```bash
./run.sh
```

Uygulama Qt tabanli bir macOS masaustu arayuzudur. Harita karolari ve guncel
RINEX verisi icin internet erisimi gerekir; son gecerli RINEX verisi ve harita
onbellegiyle cevrimdisi kullanim da desteklenir. Port secici USB ile ilgili
`/dev/cu.*` ve `/dev/tty.*` aygitlarini listeler. Hic aygit algilanmazsa
`/dev/cu.usbserial` duzenlenebilir bir varsayilan yol olarak gosterilir.

## Notes

- The map uses OpenStreetMap tiles through Qt Network. If there is no internet connection,
  points are still drawn over a fallback grid.
- The `3B Dunya · Uydular` tab appears beside the map. It uses broadcast ephemeris values
  from BKG's near-real-time `BRDC00WRD_S` RINEX file to propagate GPS satellites in ECEF.
  PRNs parsed from the current navigation solve are green; other RINEX satellites are red.
  Drag to rotate the globe and use the mouse wheel to zoom.
- The globe includes a shaded continent layer and a receiver-centred translucent visibility
  cone. `Min. elevation` accepts a directly typed decimal value from 0 to 90 degrees
  (10 degrees by default, press Enter after typing);
  satellites inside the mask get a cyan sight line and halo. Incoming positions update the
  receiver marker without resetting a globe orientation chosen by dragging.
- The globe surface uses NASA/GSFC Scientific Visualization Studio's 2048x1024 Blue Marble
  mosaic (NASA SVS visualization 2915), projected locally without a runtime network request.
- RINEX download starts at every launch, repeats every 15 minutes, and falls back through the
  previous two UTC days if today's stream file is unavailable. Current and next-minute satellite
  positions are propagated from the cached ephemeris, then smoothly interpolated at 10 FPS.
- The 3D Earth tab includes a `RINEX Guncelle` button for an immediate manual refresh. Its status
  line shows the system-local time of the last successful download or cache load.
- Complete UART channel snapshots such as `tracked satellites=5 prn_indices=[...]` replace the
  previous connected-PRN set, so satellites that were lost no longer remain green. Firmware
  channel indices are zero-based and are normalized for display (`0` is GPS PRN `G01`).
- RINEX text is parsed once per download and retained as compact ephemeris records. The static
  globe is cached between camera changes, reducing CPU and allocation load during orbit animation.
- The globe uses an embedded Natural Earth coastline mask with terrain-like land colouring,
  shallow-water edges, atmospheric shading, and a cached Earth-fixed texture for smooth rotation.
- The main content width and the right-side dashboard/UART height are both adjustable by
  dragging their splitter handles. Dashboard cards scroll independently so the UART log can
  be enlarged substantially.
- `Max` controls how many recent points stay visible and are included in location
  analysis. The default is 10. When the limit is reached, older points are removed
  automatically.
- Location analysis shows the average of the plotted samples, the last point's deviation
  from that average, mean deviation, RMS scatter, and max deviation in meters. The average
  marker can be toggled on the map.
- The map layers panel can hide all telemetry overlays, show only the newest location instead
  of the recent path, and independently toggle the average marker.
- GPS points and paths are blue. IMU+ESKF corrected points and their independent
  path are red. Synthetic ground-truth trajectory is green; the locations table
  shows the parsed source in its `Kaynak` column.
- The application calculates empirical CEP50 as the median horizontal distance of the retained
  measurements from their spherical mean, then draws the circle around that measurement center.
  This is the radius containing 50 percent of the retained position fixes and is independent of
  the optional user reference.
- A user reference can be selected by right-clicking the map. The selected WGS84 coordinates
  are transferred to the reference fields with 15 decimal places but do not alter CEP50.
- Latitude and longitude tokens are preserved exactly as received for the table and map
  label. Calculations and map projection use IEEE 754 `double` precision.
- The OpenStreetMap Standard raster layer supports zoom levels through 19. At latitude 40.8,
  zoom 19 is approximately 0.23 meters per pixel; the marker still uses subpixel coordinates,
  but the background tiles cannot add accuracy to the GNSS measurement.
- OpenStreetMap attribution is shown on the map. Tile responses use a 100 MB persistent HTTP
  cache in the application's standard cache directory.
- UART log and telemetry views are refreshed in batches so a high-rate serial stream does not
  rebuild the complete interface for every received line. The locations table uses a virtual
  model and remains usable with a high `Max` value.
- Her basarili UART baglantisi, dosya adinda ve her satirda yerel zaman damgasi bulunan ayri bir
  log olusturur. Dosyalar kaynak kodun ana klasorundeki `uart_logs` dizinine yazilir;
  `LOCATION_PLOTTER_UART_LOG_DIR` ile farkli bir klasor secilebilir.
- If no new plotted location arrives for 10 seconds while listening, current location
  points and analysis values are cleared.