327 lines
12 KiB
Plaintext
327 lines
12 KiB
Plaintext
KML MAP TOOL — DIAGNOSTIC TEST PLAN
|
|
====================================
|
|
|
|
Goal: isolate where pan/zoom lag actually originates (WebView vs app code vs
|
|
data scale) before deciding which optimisation to invest in next.
|
|
|
|
How to use: run sections in the order at the bottom of this file. Record FPS
|
|
and console-counter numbers as you go. The numbers — not feel — decide what
|
|
ships next.
|
|
|
|
------------------------------------------------------------------------------
|
|
A. WEBVIEW BASELINE TESTS (do first, cheapest)
|
|
------------------------------------------------------------------------------
|
|
|
|
A1. Confirm GPU acceleration
|
|
|
|
Command: glxinfo | grep "OpenGL renderer"
|
|
|
|
Pass: Output names a real GPU
|
|
(e.g. "Mesa Intel(R) HD Graphics 630",
|
|
"NVIDIA GeForce RTX 5070/PCIe/SSE2").
|
|
Fail: Output says "llvmpipe" (software rendering).
|
|
|
|
If fail: No code change will help. Fix drivers / Mesa / permissions
|
|
first. Stop here.
|
|
|
|
|
|
A2. WebKitGTK DMA-BUF mitigation
|
|
|
|
Run two sessions and compare FPS at the same dataset/zoom:
|
|
Baseline: npm run tauri dev
|
|
Mitigated: WEBKIT_DISABLE_DMABUF_RENDERER=1 npm run tauri dev
|
|
|
|
Expected: FPS jumps >= 1.5x with the env var set on Linux + Mesa
|
|
setups suffering DMA-BUF compositor regressions.
|
|
|
|
If pass: WebKitGTK compositor is the bottleneck. Document the env
|
|
var in INSTALLATION.md as a required workaround.
|
|
|
|
|
|
A3. Tauri WKGTK vs Chromium A/B
|
|
|
|
Terminal 1 (Tauri / WebKitGTK):
|
|
npm run tauri dev
|
|
Pan/zoom over a fixed area at z=14 for 5 seconds, record FPS.
|
|
|
|
Terminal 2 (vanilla browser):
|
|
npm run dev
|
|
Open http://localhost:1420 in Firefox or Chromium.
|
|
Login as "browser-test" (synthetic ~5000 dots around Hyderabad).
|
|
Settings -> Performance mode ON (FPS counter top-centre).
|
|
Pan/zoom at z=14 for 5 seconds, record FPS.
|
|
|
|
Compare: same code, different WebView. Big delta = WebView is the
|
|
bottleneck. Small delta = the issue is below the WebView
|
|
(drivers/compositor/dataset).
|
|
|
|
|
|
A4. Same build, cross-OS (if Windows machine available)
|
|
|
|
Build / run the Tauri app on Windows (uses WebView2 = Chromium-
|
|
based). Repeat A3 measurement with the same dataset.
|
|
|
|
Pass: Windows holds steady FPS while Linux does not -> WebKitGTK
|
|
is conclusively the issue on the user's Linux box.
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
B. APP-LEVEL ISOLATION (uses perfMode + console counters)
|
|
------------------------------------------------------------------------------
|
|
|
|
B1. perfMode on/off A/B
|
|
|
|
1. Settings -> Performance mode OFF. Pan/zoom 5 seconds. Record FPS.
|
|
2. Settings -> Performance mode ON. Pan/zoom 5 seconds. Record FPS.
|
|
|
|
Big jump (>= +20 FPS): Layer complexity matters. Move to test
|
|
B3 to find the most expensive layer.
|
|
No change: Bottleneck is below the layer effect
|
|
(WebView / Mesa / compositor). Move to A2/A3.
|
|
|
|
|
|
B2. Console-count check
|
|
|
|
1. Open DevTools console.
|
|
2. Pan continuously for 5 seconds.
|
|
|
|
Expected:
|
|
"MapView render" increments by ~2 per gesture
|
|
(movestart + moveend toggles).
|
|
"deck layer rebuild" increments by <= 2 per gesture.
|
|
|
|
Fail mode: either counter increments by tens or hundreds during
|
|
a single pan -> a regression has snuck in. Investigate.
|
|
|
|
|
|
B3. Layer-by-layer cost ladder (with perfMode OFF)
|
|
|
|
Toggle right-panel Layer checkboxes off one at a time.
|
|
Record FPS after each step:
|
|
|
|
All on (baseline) FPS = ____
|
|
Scope off FPS = ____
|
|
Metadata off FPS = ____
|
|
OSM off FPS = ____
|
|
Range off FPS = ____
|
|
Fixed off FPS = ____
|
|
|
|
The biggest single-step jump = the layer to simplify first.
|
|
|
|
|
|
B4. Filter-down ladder
|
|
|
|
1. Filter to a single video. Record FPS.
|
|
2. Then filter to a single asset_name. Record FPS.
|
|
3. Then zoom in by 2 levels. Record FPS.
|
|
|
|
If FPS climbs sharply, dataset density is the load and the answer
|
|
is zoom-tier sampling, not layer code.
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
C. SCENARIO REGRESSION TESTS (verify recent fixes)
|
|
------------------------------------------------------------------------------
|
|
|
|
C1. OSM import auto-recentre
|
|
|
|
1. Open app fresh (default viewport = [51.4, 25.5], near Qatar).
|
|
2. Do NOT pan.
|
|
3. Import an OSM GeoJSON for a far-away region (e.g. Hyderabad).
|
|
|
|
Expected: map flies to imported region, roads visible immediately,
|
|
status bar shows "Loaded N road segment(s). Centred on
|
|
imported area."
|
|
|
|
Fail: roads invisible after import. Was the user-reported bug
|
|
"imports 10-15 times before showing".
|
|
|
|
|
|
C2. Pan/zoom doesn't churn React
|
|
|
|
1. Open DevTools -> React DevTools -> Profiler.
|
|
2. Click record. Pan continuously 5 seconds. Stop record.
|
|
|
|
Expected: <= 2 AppShell renders per gesture (movestart + moveend).
|
|
Fail: ~60 renders/sec -> the move-sync regression is back.
|
|
|
|
|
|
C3. Decorative overlays hide during gestures
|
|
|
|
1. Tap a metadata polyline to select it (arrows, S/E rings, name
|
|
badge appear).
|
|
2. Begin a pan or zoom.
|
|
|
|
Expected: arrows, name badge, S/E rings/labels, link halos disappear
|
|
during the gesture and reappear on moveend.
|
|
|
|
|
|
C4. zoomBand quantisation
|
|
|
|
1. Open DevTools console (counters visible from B2).
|
|
2. Mouse-wheel zoom by tiny increments within one 0.5-zoom band
|
|
(e.g. 14.0 -> 14.1 -> 14.2 -> 14.3).
|
|
|
|
Expected: "deck layer rebuild" does NOT increment for sub-band moves.
|
|
It should only increment when crossing a 0.5 boundary.
|
|
|
|
|
|
C5. Stale-fetch guard
|
|
|
|
1. Pan rapidly across many tiles for 10 seconds without stopping.
|
|
|
|
Expected: assets array updates only with the latest viewport's data.
|
|
No flicker of old viewports' points appearing late.
|
|
|
|
|
|
C6. Compare mode default off
|
|
|
|
1. Open app fresh.
|
|
2. Inspect .map-area in DevTools.
|
|
|
|
Expected: exactly one <MapView> child rendered. Toggle the Compare
|
|
checkbox in the Basemap panel and a second canvas mounts;
|
|
uncheck it and the second canvas unmounts.
|
|
|
|
|
|
C7. Browser-mode shim
|
|
|
|
1. npm run dev (no Tauri).
|
|
2. Open http://localhost:1420 in Firefox or Chromium.
|
|
|
|
Expected:
|
|
- Login screen lists one user "Browser Test", no console errors.
|
|
- After login, ~5000 dots visible around Hyderabad.
|
|
- Pan/zoom works.
|
|
- Filtering, search, perfMode toggle all work.
|
|
- Edit operations log "[browser-mode] invoke(...) is not stubbed"
|
|
warnings — expected, those mutations are no-ops in browser mode.
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
D. STRESS / SCALE TESTS
|
|
------------------------------------------------------------------------------
|
|
|
|
D1. 50k assets in viewport
|
|
|
|
1. Import the largest realistic dataset.
|
|
2. Zoom out so most points are in viewport.
|
|
3. Pan across — measure FPS and frame consistency.
|
|
|
|
Acceptable: >= 30 FPS with perfMode OFF
|
|
>= 50 FPS with perfMode ON
|
|
|
|
|
|
D2. Dense OSM (no class filter)
|
|
|
|
1. Import a full-city OSM GeoJSON WITHOUT the major-only filter
|
|
(i.e. accept all road classes).
|
|
2. Zoom out to z=12.
|
|
|
|
If FPS tanks: zoom-tier simplification (Test 4 plan in chat) or
|
|
class-prune workflow is required for that workload.
|
|
|
|
|
|
D3. Many metadata polylines
|
|
|
|
1. Import the per-video metadata JSON with 40+ tracks.
|
|
2. Zoom out to fit all tracks. Pan.
|
|
|
|
With viewport-cull + zoom-decimation already in place, should still
|
|
be smooth. If not, lower the per-track point cap or the global
|
|
arrow cap.
|
|
|
|
|
|
D4. Long edit session (memory leak check)
|
|
|
|
1. Drag 100 asset pins in succession.
|
|
2. Mix snap-to-road, side-toggle, rename, delete, restore, undo.
|
|
3. Watch memory in DevTools.
|
|
|
|
Expected: heap stays stable. No leaks from event listeners or
|
|
MapLibre Marker objects.
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
E. FEATURE SMOKE TESTS (run before any release)
|
|
------------------------------------------------------------------------------
|
|
|
|
For each, confirm the feature still works after recent edits.
|
|
|
|
1. Login + create user + switch user
|
|
2. Import fixed assets JSON -> markers visible
|
|
3. Import range assets JSON -> S/M/E lines visible
|
|
4. Import KML scope -> polygon visible,
|
|
out-of-scope filter works
|
|
5. Import per-video metadata JSON -> coloured polylines visible
|
|
6. Import OSM GeoJSON -> roads visible AND map
|
|
auto-centres (see C1)
|
|
7. Click asset -> image popup opens
|
|
(popupEnabled on)
|
|
8. Drag pin -> asset moves, action appears
|
|
in Recent actions
|
|
9. Lasso (circle / rect / polygon) -> bulk delete / set-scope /
|
|
restore work
|
|
10. Find duplicates within viewport
|
|
11. Mark anchor -> drag -> Distribute correction
|
|
12. Auto-link in polygon (L<->R, by-video, nearest)
|
|
13. Right-click two assets -> manual link, pink line
|
|
Right-click them again -> unlink
|
|
14. OSM edit mode -> drag vertex, shift-click + Del,
|
|
simplify slider all work
|
|
15. Search by lat/lng -> red goto pin appears
|
|
16. Search by video name -> flies to video, highlights
|
|
metadata track
|
|
17. Export Source JSON / GeoJSON / KML / CSV
|
|
Round-trip: re-import the Source JSON cleanly
|
|
18. Settings: toggle popup, aspect ratio, snap-to-centerline names,
|
|
perfMode
|
|
19. Undo last action -> state restored
|
|
20. Reset DB -> app empty, but classes.txt
|
|
suggestions still load
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
RECOMMENDED RUN ORDER (fastest signal first)
|
|
------------------------------------------------------------------------------
|
|
|
|
1. A1, A2 (5 min, no code touched)
|
|
2. B2 (1 min — confirms recent perf changes are working)
|
|
3. B1 (2 min — quantifies what perfMode buys)
|
|
4. A3 (10 min — Tauri vs Chromium)
|
|
5. B3 (10 min — which layer is most expensive)
|
|
6. C1 (1 min — verifies the OSM auto-recentre fix)
|
|
7. D1, D2, D3 (only if A2/A3 inconclusive)
|
|
8. E (full smoke) (before any release)
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
DECISION TREE
|
|
------------------------------------------------------------------------------
|
|
|
|
A2 alone fixes the user's lag -> ship the env var in
|
|
INSTALLATION.md, done.
|
|
|
|
A3 shows Chromium is dramatically faster -> plan browser-mode
|
|
deployment for Linux
|
|
QA reviewers (keep
|
|
Tauri for the import
|
|
operator).
|
|
|
|
B3 isolates one heavy layer -> zoom-tier
|
|
simplification for
|
|
that layer only.
|
|
|
|
B1 jump is large but A3 delta is small -> invest in zoom-tier
|
|
simplification
|
|
(Test 4 plan).
|
|
|
|
None of the above conclusive -> re-run on the actual
|
|
user hardware before
|
|
investing further.
|
|
|
|
|
|
==============================================================================
|
|
End of test plan.
|
|
==============================================================================
|