Howto for using DJI SRT as a flight log

docs/howto-dji-srt-uaslogreader.md

+# DJI SRT With `UasLogReader` (Offline How-To)
+
+This note explains how to use DJI `.SRT` flight logs with the existing `UasLogReader` path used by CUAS processing.
+
+## 1) What is supported
+
+`UasLogReader` auto-detects input type:
+
+- JSON flight log (legacy format)
+- DJI SRT input (new path)
+
+Detection is done in `UasLogReader`:
+
+- if path "looks like SRT" -> uses `DjiSrtReader`
+- otherwise -> loads JSON
+
+Code references:
+
+- `src/main/java/com/elphel/imagej/ims/UasLogReader.java`
+- `src/main/java/com/elphel/imagej/ims/DjiSrtReader.java`
+
+## 2) Accepted DJI SRT path formats
+
+Set the "UAS log file" field to one of:
+
+1. Single file:
+- `/path/to/DJI_20260303111653_0042_D.SRT`
+
+2. Directory (all `.srt`/`.SRT` files in directory):
+- `/path/to/dji/c-UAS_GreatSaltLake_03-26`
+
+3. Glob:
+- `/path/to/dji/c-UAS_GreatSaltLake_03-26/*.SRT`
+
+4. Multiple items separated by comma/semicolon/newline:
+- `/path/a/one.SRT,/path/b/two.SRT`
+- `/path/a/*.SRT;/path/b/*.SRT`
+
+`DjiSrtReader` sorts records by timestamp and merges them.
+
+## 3) Parameters to set in GUI
+
+Open `Setup CLT`, then `Directories` tab (camera correction parameters):
+
+1. `UAS log file`
+- Put one of the path formats above.
+
+2. `UAS log start timestamp`
+- Recommended for DJI SRT: set to `0`.
+- Behavior: if `0`, first SRT epoch is used automatically.
+
+3. `Camera ATR in world coordinates`
+- Keep your CUAS camera ATR values.
+
+4. `UAS home position NED relative to the LWIR16`
+- Optional.
+- Used only if `Use specified NED instead of accurate GPS` is checked.
+
+5. `Use specified NED instead of accurate GPS`
+- Off: use GPS-derived NED.
+- On: apply your manual home/NED offset.
+
+## 4) How runtime wiring works
+
+During series processing (`TwoQuadCLT`):
+
+1. Reads `getUasLogsPath()`
+2. Creates `new UasLogReader(...)`
+3. Applies:
+- `setCameraATR(...)`
+- `setUASHomeNed(...)` (if enabled)
+
+Then `uasLogReader` is passed into `OpticalFlow.buildSeries(...)`, and later used by CUAS target/ranging code.
+
+## 5) Console lines to confirm DJI mode is active
+
+Look for:
+
+- `UasLogReader: using DJI SRT first timestamp ... (input was 0)`
+- `UasLogReader: loaded DJI SRT path "...": ... records ... source files=...`
+- `DjiSrtReader: loaded ... records from ... file(s)`
+
+If you see JSON parser field errors, the path was interpreted as JSON input.
+
+## 6) Fast sanity checks before full CUAS run
+
+1. Parse test:
+- Button: `DJI SRT`
+- Confirms SRT file can be parsed.
+
+2. Visual track check:
+- Button: `SRT to KML`
+- Open generated KML in Google Earth to verify flight path/time ordering.
+
+3. Full pipeline check:
+- Use `Aux Build Series` (`cuas_proc_mode=0`).
+- Keep CUAS phase-1 settings as usual.
+
+## 7) Important caveats
+
+1. Path auto-suffix logic (`getUasLogsPath()`):
+- If path is plain text without known SRT/JSON markers, `.json` may be appended.
+- Use explicit `.SRT`, glob, directory, or separators for DJI input.
+
+2. Empty/invalid SRT rows are skipped:
+- rows without parseable timestamp/lat/lon are ignored.
+
+3. If no valid DJI records remain:
+- throws `IllegalArgumentException("No valid DJI SRT records found ...")`.
+
+4. Start timestamp alignment:
+- with `UAS log start timestamp = 0`, SRT first epoch is used as CUAS time zero.
+- if needed, you can set explicit timestamp manually.
+
+## 8) Recommended default for DJI bring-up
+
+1. `UAS log file`: directory or glob covering all flight SRT files.
+2. `UAS log start timestamp`: `0`.
+3. `Use specified NED instead of accurate GPS`: off (unless you explicitly need manual offset).
+4. Run one short sequence first and verify console lines in section 5.