ray360 0.1.0__tar.gz

ray360-0.1.0/.github/workflows/end-to-end.yml

@@ -0,0 +1,30 @@
+name: real media and model validation
+on: workflow_dispatch
+
+permissions:
+  contents: read
+
+jobs:
+  cpu:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
+        with:
+          version: '0.10.9'
+          python-version: '3.12'
+      - run: uv sync --locked --group dev --extra image
+      - run: uv pip install torch==2.15.0 torchvision==0.29.2 --index https://download.pytorch.org/whl/cpu
+      - run: uv pip install av==19.0.2 ultralytics==8.4.213
+      - run: uv run --no-sync python scripts/fetch_test_data.py --include-e2e
+      - run: uv run --no-sync python -m pytest tests/test_end_to_end.py --e2e --e2e-output .test-results/e2e -v -s
+        env:
+          YOLO_CONFIG_DIR: .test-results/yolo
+          YOLO_OFFLINE: 'true'
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: cpu-validation-report
+          path: .test-results/e2e/report.json
+          include-hidden-files: true

ray360-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,68 @@
+name: publish to PyPI
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: '0.10.9'
+          python-version: '3.12'
+      - run: uv sync --locked --group dev --extra image
+      - name: Check release tag and package version
+        run: |
+          uv run --no-sync python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+          import ray360
+          project = tomllib.loads(Path('pyproject.toml').read_text())['project']
+          version = project['version']
+          if project['name'] != 'ray360' or ray360.__version__ != version:
+              raise SystemExit('Package name or version does not match the source')
+          if os.environ['GITHUB_REF_NAME'] != f'v{version}':
+              raise SystemExit('Release tag must match the package version')
+          PY
+      - run: uv run --no-sync python -m pytest
+      - run: uv build --no-sources
+      - run: uv tool run --from twine==7.0.0 twine check --strict dist/*
+      - run: uv run --no-sync python scripts/check_wheel.py
+      - run: uv run --no-sync python scripts/check_wheel.py --image
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/ray360/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
+        with:
+          version: '0.10.9'
+          enable-cache: false
+      - run: uv publish --trusted-publishing always dist/*

ray360-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,44 @@
+name: tests
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        include:
+          - {os: ubuntu-latest, python: '3.11'}
+          - {os: ubuntu-latest, python: '3.13'}
+          - {os: ubuntu-latest, python: '3.14'}
+          - {os: windows-latest, python: '3.12'}
+          - {os: macos-latest, python: '3.12'}
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: '0.10.9'
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked --group dev --extra image
+      - run: uv run --no-sync ruff check src tests scripts examples benchmarks
+      - run: uv run --no-sync ruff format --check src tests scripts examples benchmarks
+      - run: uv run --no-sync mypy
+      - run: uv run --no-sync python -m pytest
+      - run: uv run --no-sync python examples/basic.py
+      - run: uv build --no-sources
+      - run: uv run --no-sync python scripts/check_wheel.py
+      - run: uv run --no-sync python scripts/check_wheel.py --image
+
+  minimum-dependencies:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
+        with:
+          version: '0.10.9'
+          python-version: '3.11'
+      - run: uv sync --locked --group dev --extra image
+      - run: uv pip install 'numpy==1.24.0' 'Pillow==10.0.0'
+      - run: uv run --no-sync python -m pytest

ray360-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+.venv-e2e/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/
+benchmark-results*.json
+.test-data/
+.test-results/
+.coverage*
+htmlcov/

ray360-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ray360 contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ray360-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.5
+Name: ray360
+Version: 0.1.0
+Summary: Perspective views, cubemap conversion and prediction mapping for stitched panoramas
+Project-URL: Repository, https://github.com/aasmanbashyal/ray360
+Project-URL: Documentation, https://github.com/aasmanbashyal/ray360/blob/main/docs/api.md
+Project-URL: Issues, https://github.com/aasmanbashyal/ray360/issues
+Author: Aasman Bashyal
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Provides-Extra: image
+Requires-Dist: pillow>=10; extra == 'image'
+Description-Content-Type: text/markdown
+
+# Ray360
+
+Perspective views and reversible prediction mapping for **already-stitched 360 images**.
+
+Ray360 extracts model inputs from equirectangular NumPy arrays and retains the
+geometry through crop, resize, and letterbox operations. Map points and predicted
+boxes back to the panorama, including objects crossing its seam or covering a pole.
+
+Python 3.11+. NumPy is the only required dependency. Version 0.1.0 is the focused
+first-release API; the earlier development API has been removed.
+
+## Install
+
+```bash
+uv add ray360                 # NumPy core
+uv add "ray360[image]"        # Optional Pillow image helpers
+```
+
+With pip, use `pip install ray360` or `pip install "ray360[image]"`.
+
+For development, clone [the repository](https://github.com/aasmanbashyal/ray360)
+and install from the checkout:
+
+```bash
+uv sync --locked                         # NumPy core
+uv sync --locked --extra image           # Optional Pillow image helpers
+uv sync --locked --group dev --extra image
+```
+
+To test a local build in another environment, run `uv build --no-sources`,
+then use `uv pip install /path/to/ray360-0.1.0-py3-none-any.whl`.
+
+## Extract a view and map a prediction
+
+```python
+import numpy as np
+from ray360 import Box2D, Panorama, Perspective
+
+# Supplying Panorama explicitly declares that these pixels are already stitched.
+panorama = Panorama(np.zeros((1024, 2048, 3), dtype=np.uint8), source_id="capture")
+view = panorama.view(Perspective(960, 540, yaw=180, pitch=10, hfov=100))
+model_view = view.crop(40, 20, 880, 500).letterbox(640, 640)
+
+# Run any model in the application. Its predictions must use model_view pixels.
+boxes = [Box2D(250, 240, 390, 400, label="person", score=0.93, track_id=7)]
+regions = model_view.map_boxes(boxes)
+for region in regions:
+    polygons = region.polygons(panorama.projection)
+    rectangles = region.boxes(panorama.projection)
+    membership = region.rasterize(panorama.projection)
+
+points, valid = model_view.transform.to_panorama([[320, 320], [10, 0]])
+```
+
+One `SphericalRegion` remains one object even when rendering produces two seam
+pieces. `region.box` retains labels, scores, tracking IDs, and attributes. Exported
+rectangles enclose sampled boundaries and are approximate. Use `rasterize()` for
+membership at pixel centers.
+
+Predictions entirely in preprocessing padding are discarded; partial boxes are
+clipped. Point mapping returns a validity mask. Ignore coordinates marked false.
+`model_view.valid` identifies retained pixels, including after a crop followed by
+new padding. These masks describe geometry, not detector confidence or occlusion.
+
+## Arrays, sampling, and repeated frames
+
+HW and HWC arrays retain their dtype. Bilinear interpolation is the default for
+images. Use `interpolation="nearest"` for class labels; the choice carries through
+all subsequent view preprocessing unless explicitly overridden. Boolean and
+64-bit integer arrays require nearest sampling.
+
+```python
+from ray360 import MapCache, coverage_views
+
+cache = MapCache(max_bytes=64 * 1024 * 1024)
+targets = coverage_views(width=320, height=320)
+for view in panorama.views(targets, cache=cache):
+    pass  # Process and release each view instead of retaining all images.
+```
+
+Reuse the cache and targets for subsequent panoramas with the same dimensions and
+orientation. The default shared cache holds at most 128 MiB of coordinate maps.
+Pass `cache=None` to disable caching. The budget covers cached maps, not caller
+images, returned views, or temporary allocations. Arrays remain caller-owned.
+
+`coverage_views()` defaults to 24 views covering the sphere. This does not
+guarantee detection recall. Choose view size, field of view, and overlap using the
+application's accuracy and latency measurements.
+
+## Persistence and optional image helpers
+
+`ViewTransform.to_dict()` and `.from_dict()` preserve the mapping without storing
+pixels. `view.provenance()` adds source ID, optional timestamp, and interpolation.
+`SphericalRegion.to_dict()` and `.from_dict()` preserve both a region's boundary
+definition and its intended interior. Both schemas carry a version. Keep custom
+annotation attributes JSON-compatible when writing them as JSON.
+
+```python
+from ray360.image import overlay, read_panorama, write_image
+
+panorama = read_panorama("stitched.jpg")  # Explicit declaration of stitched geometry
+view = panorama.view(Perspective(640, 360, yaw=180))
+regions = view.map_boxes([Box2D(240, 100, 400, 260)])
+write_image("mapped.png", overlay(panorama.image, regions, projection=panorama.projection))
+```
+
+Image loading returns uint8 RGB and preserves stored pixel orientation. Saving
+refuses existing files unless `overwrite=True` is supplied.
+
+## Cubemap conversion
+
+```python
+from ray360 import Equirectangular, cube_projections, from_cubemap, to_cubemap
+
+faces = to_cubemap(panorama, size=512)  # dict of six HW or HWC arrays
+restored = from_cubemap(faces, Equirectangular(2048, 1024))
+
+# For predictions on cube faces, keep the ordinary View and its transform.
+front = panorama.view(cube_projections(512)["front"])
+regions = front.map_boxes([Box2D(200, 180, 300, 320)])
+```
+
+Faces are named `front`, `right`, `back`, `left`, `up`, and `down`. Each is square
+with a 90-degree field of view. [The orientation table](https://github.com/aasmanbashyal/ray360/blob/main/docs/api.md#cubemap-conversion)
+defines the pole faces. Bilinear conversion back to a panorama samples adjacent
+faces at cube boundaries. Use `interpolation="nearest"` in both directions for
+label arrays. Conversion preserves dtype and can lose detail through resampling.
+Atlas layouts and raw-camera stitching remain application concerns.
+
+## Scope and experimental operations
+
+The package owns projection geometry, cubemap conversion, preprocessing transforms,
+box/point mapping, and map caching. Applications own inference, video decoding, timestamps, dataset
+formats, and encoding. Raw-camera stitching, fisheye calibration, tensor backends,
+network streaming, and segmentation/pose annotation codecs are outside this release.
+
+`ray360.experimental` contains sampled spherical IoU and class-aware NMS. They
+are outside the stable root API. Small objects can miss every sample and receive
+zero overlap, even against themselves. NMS suppresses predictions; it does not
+fuse partial detections or establish detector accuracy. See [scope](https://github.com/aasmanbashyal/ray360/blob/main/docs/scope.md).
+
+## Examples and development
+
+```bash
+uv run --no-sync python examples/basic.py
+uv run --no-sync python -m pytest
+uv run --no-sync ruff check src tests scripts examples benchmarks
+uv run --no-sync mypy
+uv build --no-sources
+uv run --no-sync python scripts/check_wheel.py
+```
+
+[The basic example](https://github.com/aasmanbashyal/ray360/blob/main/examples/basic.py) needs only NumPy. It can write a synthetic
+overlay with `--output .test-results/demo.png` when Pillow is installed.
+[The model example](https://github.com/aasmanbashyal/ray360/blob/main/examples/detect.py) and [decoder example](https://github.com/aasmanbashyal/ray360/blob/main/examples/video_frames.py)
+show application-owned integrations with separately installed dependencies.
+The opt-in [end-to-end suite](https://github.com/aasmanbashyal/ray360/blob/main/docs/validation.md#real-media-and-model-validation)
+executes these examples and runs cube conversion and CPU detection on every frame
+of two real panorama video encodings. It also checks two stitched photos and
+photographic cube faces. Media and model weights are checksum-verified local fixtures.
+
+See [API conventions](https://github.com/aasmanbashyal/ray360/blob/main/docs/api.md), [validation](https://github.com/aasmanbashyal/ray360/blob/main/docs/validation.md), and
+[whole-panorama benchmarks](https://github.com/aasmanbashyal/ray360/blob/main/docs/benchmarks.md). The ordinary test suite never
+downloads media or model weights.
+
+Maintainers can follow the [release guide](https://github.com/aasmanbashyal/ray360/blob/main/docs/releasing.md)
+to publish a version from a Git tag.

ray360-0.1.0/README.md

@@ -0,0 +1,167 @@
+# Ray360
+
+Perspective views and reversible prediction mapping for **already-stitched 360 images**.
+
+Ray360 extracts model inputs from equirectangular NumPy arrays and retains the
+geometry through crop, resize, and letterbox operations. Map points and predicted
+boxes back to the panorama, including objects crossing its seam or covering a pole.
+
+Python 3.11+. NumPy is the only required dependency. Version 0.1.0 is the focused
+first-release API; the earlier development API has been removed.
+
+## Install
+
+```bash
+uv add ray360                 # NumPy core
+uv add "ray360[image]"        # Optional Pillow image helpers
+```
+
+With pip, use `pip install ray360` or `pip install "ray360[image]"`.
+
+For development, clone [the repository](https://github.com/aasmanbashyal/ray360)
+and install from the checkout:
+
+```bash
+uv sync --locked                         # NumPy core
+uv sync --locked --extra image           # Optional Pillow image helpers
+uv sync --locked --group dev --extra image
+```
+
+To test a local build in another environment, run `uv build --no-sources`,
+then use `uv pip install /path/to/ray360-0.1.0-py3-none-any.whl`.
+
+## Extract a view and map a prediction
+
+```python
+import numpy as np
+from ray360 import Box2D, Panorama, Perspective
+
+# Supplying Panorama explicitly declares that these pixels are already stitched.
+panorama = Panorama(np.zeros((1024, 2048, 3), dtype=np.uint8), source_id="capture")
+view = panorama.view(Perspective(960, 540, yaw=180, pitch=10, hfov=100))
+model_view = view.crop(40, 20, 880, 500).letterbox(640, 640)
+
+# Run any model in the application. Its predictions must use model_view pixels.
+boxes = [Box2D(250, 240, 390, 400, label="person", score=0.93, track_id=7)]
+regions = model_view.map_boxes(boxes)
+for region in regions:
+    polygons = region.polygons(panorama.projection)
+    rectangles = region.boxes(panorama.projection)
+    membership = region.rasterize(panorama.projection)
+
+points, valid = model_view.transform.to_panorama([[320, 320], [10, 0]])
+```
+
+One `SphericalRegion` remains one object even when rendering produces two seam
+pieces. `region.box` retains labels, scores, tracking IDs, and attributes. Exported
+rectangles enclose sampled boundaries and are approximate. Use `rasterize()` for
+membership at pixel centers.
+
+Predictions entirely in preprocessing padding are discarded; partial boxes are
+clipped. Point mapping returns a validity mask. Ignore coordinates marked false.
+`model_view.valid` identifies retained pixels, including after a crop followed by
+new padding. These masks describe geometry, not detector confidence or occlusion.
+
+## Arrays, sampling, and repeated frames
+
+HW and HWC arrays retain their dtype. Bilinear interpolation is the default for
+images. Use `interpolation="nearest"` for class labels; the choice carries through
+all subsequent view preprocessing unless explicitly overridden. Boolean and
+64-bit integer arrays require nearest sampling.
+
+```python
+from ray360 import MapCache, coverage_views
+
+cache = MapCache(max_bytes=64 * 1024 * 1024)
+targets = coverage_views(width=320, height=320)
+for view in panorama.views(targets, cache=cache):
+    pass  # Process and release each view instead of retaining all images.
+```
+
+Reuse the cache and targets for subsequent panoramas with the same dimensions and
+orientation. The default shared cache holds at most 128 MiB of coordinate maps.
+Pass `cache=None` to disable caching. The budget covers cached maps, not caller
+images, returned views, or temporary allocations. Arrays remain caller-owned.
+
+`coverage_views()` defaults to 24 views covering the sphere. This does not
+guarantee detection recall. Choose view size, field of view, and overlap using the
+application's accuracy and latency measurements.
+
+## Persistence and optional image helpers
+
+`ViewTransform.to_dict()` and `.from_dict()` preserve the mapping without storing
+pixels. `view.provenance()` adds source ID, optional timestamp, and interpolation.
+`SphericalRegion.to_dict()` and `.from_dict()` preserve both a region's boundary
+definition and its intended interior. Both schemas carry a version. Keep custom
+annotation attributes JSON-compatible when writing them as JSON.
+
+```python
+from ray360.image import overlay, read_panorama, write_image
+
+panorama = read_panorama("stitched.jpg")  # Explicit declaration of stitched geometry
+view = panorama.view(Perspective(640, 360, yaw=180))
+regions = view.map_boxes([Box2D(240, 100, 400, 260)])
+write_image("mapped.png", overlay(panorama.image, regions, projection=panorama.projection))
+```
+
+Image loading returns uint8 RGB and preserves stored pixel orientation. Saving
+refuses existing files unless `overwrite=True` is supplied.
+
+## Cubemap conversion
+
+```python
+from ray360 import Equirectangular, cube_projections, from_cubemap, to_cubemap
+
+faces = to_cubemap(panorama, size=512)  # dict of six HW or HWC arrays
+restored = from_cubemap(faces, Equirectangular(2048, 1024))
+
+# For predictions on cube faces, keep the ordinary View and its transform.
+front = panorama.view(cube_projections(512)["front"])
+regions = front.map_boxes([Box2D(200, 180, 300, 320)])
+```
+
+Faces are named `front`, `right`, `back`, `left`, `up`, and `down`. Each is square
+with a 90-degree field of view. [The orientation table](https://github.com/aasmanbashyal/ray360/blob/main/docs/api.md#cubemap-conversion)
+defines the pole faces. Bilinear conversion back to a panorama samples adjacent
+faces at cube boundaries. Use `interpolation="nearest"` in both directions for
+label arrays. Conversion preserves dtype and can lose detail through resampling.
+Atlas layouts and raw-camera stitching remain application concerns.
+
+## Scope and experimental operations
+
+The package owns projection geometry, cubemap conversion, preprocessing transforms,
+box/point mapping, and map caching. Applications own inference, video decoding, timestamps, dataset
+formats, and encoding. Raw-camera stitching, fisheye calibration, tensor backends,
+network streaming, and segmentation/pose annotation codecs are outside this release.
+
+`ray360.experimental` contains sampled spherical IoU and class-aware NMS. They
+are outside the stable root API. Small objects can miss every sample and receive
+zero overlap, even against themselves. NMS suppresses predictions; it does not
+fuse partial detections or establish detector accuracy. See [scope](https://github.com/aasmanbashyal/ray360/blob/main/docs/scope.md).
+
+## Examples and development
+
+```bash
+uv run --no-sync python examples/basic.py
+uv run --no-sync python -m pytest
+uv run --no-sync ruff check src tests scripts examples benchmarks
+uv run --no-sync mypy
+uv build --no-sources
+uv run --no-sync python scripts/check_wheel.py
+```
+
+[The basic example](https://github.com/aasmanbashyal/ray360/blob/main/examples/basic.py) needs only NumPy. It can write a synthetic
+overlay with `--output .test-results/demo.png` when Pillow is installed.
+[The model example](https://github.com/aasmanbashyal/ray360/blob/main/examples/detect.py) and [decoder example](https://github.com/aasmanbashyal/ray360/blob/main/examples/video_frames.py)
+show application-owned integrations with separately installed dependencies.
+The opt-in [end-to-end suite](https://github.com/aasmanbashyal/ray360/blob/main/docs/validation.md#real-media-and-model-validation)
+executes these examples and runs cube conversion and CPU detection on every frame
+of two real panorama video encodings. It also checks two stitched photos and
+photographic cube faces. Media and model weights are checksum-verified local fixtures.
+
+See [API conventions](https://github.com/aasmanbashyal/ray360/blob/main/docs/api.md), [validation](https://github.com/aasmanbashyal/ray360/blob/main/docs/validation.md), and
+[whole-panorama benchmarks](https://github.com/aasmanbashyal/ray360/blob/main/docs/benchmarks.md). The ordinary test suite never
+downloads media or model weights.
+
+Maintainers can follow the [release guide](https://github.com/aasmanbashyal/ray360/blob/main/docs/releasing.md)
+to publish a version from a Git tag.

ray360-0.1.0/benchmarks/benchmark.py

@@ -0,0 +1,123 @@
+"""Measure one view and a complete geometry workflow; inference and I/O are excluded."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import platform
+import time
+from pathlib import Path
+
+import numpy as np
+
+from ray360 import Box2D, MapCache, Panorama, Perspective, ProjectionMap, coverage_views
+
+
+def measure(operation, iterations):
+    times = []
+    for _ in range(iterations):
+        start = time.perf_counter()
+        operation()
+        times.append((time.perf_counter() - start) * 1000)
+    return {"p50_ms": float(np.percentile(times, 50)), "p95_ms": float(np.percentile(times, 95))}
+
+
+def peak_rss_bytes():
+    if os.name == "nt":
+        import ctypes
+        from ctypes import wintypes
+
+        class Counters(ctypes.Structure):
+            _fields_ = [("cb", wintypes.DWORD), ("PageFaultCount", wintypes.DWORD)] + [
+                (name, ctypes.c_size_t)
+                for name in (
+                    "PeakWorkingSetSize",
+                    "WorkingSetSize",
+                    "QuotaPeakPagedPoolUsage",
+                    "QuotaPagedPoolUsage",
+                    "QuotaPeakNonPagedPoolUsage",
+                    "QuotaNonPagedPoolUsage",
+                    "PagefileUsage",
+                    "PeakPagefileUsage",
+                )
+            ]
+
+        kernel = ctypes.WinDLL("kernel32", use_last_error=True)
+        psapi = ctypes.WinDLL("psapi", use_last_error=True)
+        kernel.GetCurrentProcess.restype = wintypes.HANDLE
+        psapi.GetProcessMemoryInfo.argtypes = [
+            wintypes.HANDLE,
+            ctypes.POINTER(Counters),
+            wintypes.DWORD,
+        ]
+        psapi.GetProcessMemoryInfo.restype = wintypes.BOOL
+        counters = Counters()
+        counters.cb = ctypes.sizeof(counters)
+        if not psapi.GetProcessMemoryInfo(
+            kernel.GetCurrentProcess(), ctypes.byref(counters), counters.cb
+        ):
+            raise ctypes.WinError(ctypes.get_last_error())
+        return counters.PeakWorkingSetSize
+    import resource
+
+    rss = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+    return rss if platform.system() == "Darwin" else rss * 1024
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--width", type=int, default=4096)
+    parser.add_argument("--height", type=int, default=2048)
+    parser.add_argument("--view-size", type=int, default=320)
+    parser.add_argument("--iterations", type=int, default=5)
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    if min(args.width, args.height, args.view_size, args.iterations) < 1:
+        parser.error("dimensions and iterations must be positive")
+    image = np.random.default_rng(42).integers(0, 256, (args.height, args.width, 3), np.uint8)
+    panorama = Panorama(image)
+    target = Perspective(args.view_size, args.view_size, yaw=179, pitch=20)
+    cache = MapCache()
+    targets = coverage_views(args.view_size, args.view_size)
+    padded_size = args.view_size + max(1, args.view_size // 4)
+    box = Box2D(
+        args.view_size * 0.25, padded_size * 0.35, args.view_size * 0.75, padded_size * 0.65
+    )
+
+    def full_workflow():
+        for view in panorama.views(targets, cache=cache):
+            view = view.letterbox(args.view_size, padded_size)
+            view.transform.to_panorama([[args.view_size / 2, padded_size / 2]])
+            for region in view.map_boxes([box]):
+                region.polygons(panorama.projection)
+
+    panorama.view(target, cache=cache)
+    full_workflow()
+    result = {
+        "python": platform.python_version(),
+        "numpy": np.__version__,
+        "platform": platform.platform(),
+        "cpu_count": os.cpu_count(),
+        "source_size": list(panorama.projection.size),
+        "view_size": list(target.size),
+        "coverage_view_count": len(targets),
+        "iterations": args.iterations,
+        "map_build": measure(
+            lambda: ProjectionMap.build(panorama.projection, target), args.iterations
+        ),
+        "cached_single_view": measure(lambda: panorama.view(target, cache=cache), args.iterations),
+        "full_panorama_geometry": measure(full_workflow, args.iterations),
+        "cache_bytes": cache.nbytes,
+        "cache_budget_bytes": cache.max_bytes,
+        "process_peak_rss_bytes": peak_rss_bytes(),
+        "scope": "Already-decoded pixels; all coverage views, letterboxing, one point and box mapping per view, polygon rendering. Excludes decoding, inference, NMS and file output.",
+    }
+    encoded = json.dumps(result, indent=2) + "\n"
+    if args.output:
+        args.output.write_text(encoded, encoding="utf-8")
+    print(encoded, end="")
+
+
+if __name__ == "__main__":
+    main()