feat(viz): count rays whose origin is outside the sensor world

[WomB0ComB0]

Summary

• Real audit-signal finding. The visualization terrain is 4000 m × 4000 m (TERRAIN_SIZE in client/terrain.ts) but the default sensor world is a 1024 m cube (128³ voxels at 8 m, origin [-512, 0, -512]). Drones flying outside [-512, 512] on X/Z get clean LoS misses against terrain that exists in the visualization but not in the brick map — silently wrong.
• Add LosQueryStats.raysOutsideWorld. Counts during host-side ray packing in runBatch, ~6 comparisons per ray on a path that already iterates each ray. Pure observability — no behavioural change.
• The actual fix (resize the world to ~4096 m, or make it configurable) is a separate decision because it bumps GPU voxel-buffer memory ~8x (8 → 64 MB). This PR just gives the audit a way to confirm whether the gap is being hit before committing to the memory cost.

Test plan

• npm run build passes; main bundle 809 KB (under 800 KiB cap)
• tsc --noEmit clean
• LosQueryStats extends — existing consumers (none yet, landed in feat(viz): expose lifetime stats on LosQueryManager #78) are forward-compatible
• Audit (in 2 weeks) reads getSensorContext()?.los.stats.raysOutsideWorld to decide if a world resize PR is warranted

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Line-of-sight query statistics now track rays originating outside the world boundary.

[coderabbitai]

📝 Walkthrough

Walkthrough

A new raysOutsideWorld metric is added to LosQueryStats. The LosQueryManager initializes this counter and increments it during each query() call by synchronously computing the world voxel AABB and counting rays with origins outside it, before GPU batch queueing.

Changes

Cohort / File(s)	Summary
Ray Origin Boundary Tracking src/ResQ.Viz.Web/client/webgpu/los.ts	Added raysOutsideWorld: number field to LosQueryStats export. LosQueryManager.query() now synchronously computes world AABB from world.params, iterates submitted rays, counts origins strictly outside AABB, and increments the counter before GPU batch submission.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• refactor(viz): ring-buffered LosQueryManager (foundation for LiDAR) #71 — Refactors LosQueryManager.query() and runBatch() flow using per-slot ring buffers, directly intersects with the same code path being modified here.
• feat(viz): expose lifetime stats on LosQueryManager #78 — Extends LosQueryStats with additional lifetime metrics (totalQueries, totalRays, peakSlotDepth) alongside updates to LosQueryManager, sharing identical structural patterns.
• feat(viz): WebGPU sensor primitive on production route (foundation) #69 — Modifies LosQueryManager and ray query implementation in the same file with related logic adjustments.

Poem

🐰 A ray hops through the voxel space,
But some stray far beyond the place!
Now we count the wanderers wild,
Those origins that left the grid beguiled. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a counter for rays whose origin is outside the sensor world.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/webgpu-out-of-bounds-stat

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request introduces a new audit metric, raysOutsideWorld, to track rays with origins outside the voxel AABB in the Line-of-Sight (LOS) query manager. This helps identify cases where sensor coverage might not match the visualization terrain. Feedback was provided regarding the timing of the statistic update; because raysOutsideWorld is updated within the asynchronous runBatch method, it may become temporarily out of sync with other counters that are updated synchronously, which could impact tools that snapshot statistics immediately after a query.

[coderabbitai]

🧹 Nitpick comments (1)

src/ResQ.Viz.Web/client/webgpu/los.ts (1)

60-71: Clarify “strictly outside” vs half-open bounds in the metric definition.

Line 61 says “strictly outside,” but Lines 261-263 classify o[*] >= *Max as outside, which is half-open [min, max) behavior. Please align wording (or comparisons) so audits interpret boundary rays consistently.

Suggested doc-only alignment

- * Rays whose world-space origin fell strictly outside the world's
- * voxel AABB.
+ * Rays whose world-space origin fell outside the world's voxel AABB
+ * using half-open bounds per axis: [min, max).

Also applies to: 261-263

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/ResQ.Viz.Web/client/webgpu/los.ts` around lines 60 - 71, The docstring
for raysOutsideWorld claims “strictly outside” but the classification code
treats o[*] >= *Max as outside (half-open [min, max)) — update one of them to be
consistent: either change the prose for raysOutsideWorld to mention the
half-open interval semantics (e.g., “outside the half-open [min, max) voxel
AABB”) or modify the comparison in the ray-origin classification (the o[*] >=
*Max checks) to use > instead of >= so the metric truly reflects “strictly
outside”; reference the raysOutsideWorld field and the o[*] >= *Max
classification logic when making the change.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@src/ResQ.Viz.Web/client/webgpu/los.ts`:
- Around line 60-71: The docstring for raysOutsideWorld claims “strictly
outside” but the classification code treats o[*] >= *Max as outside (half-open
[min, max)) — update one of them to be consistent: either change the prose for
raysOutsideWorld to mention the half-open interval semantics (e.g., “outside the
half-open [min, max) voxel AABB”) or modify the comparison in the ray-origin
classification (the o[*] >= *Max checks) to use > instead of >= so the metric
truly reflects “strictly outside”; reference the raysOutsideWorld field and the
o[*] >= *Max classification logic when making the change.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 31ee410d-616d-4d23-a504-604d6d3a27f4

📥 Commits

Reviewing files that changed from the base of the PR and between 6afd38a and af3645a.

📒 Files selected for processing (1)

• src/ResQ.Viz.Web/client/webgpu/los.ts