Skip to content

Add sky-view factor function (#962)#972

Merged
brendancol merged 4 commits intomasterfrom
issue-962
Mar 5, 2026
Merged

Add sky-view factor function (#962)#972
brendancol merged 4 commits intomasterfrom
issue-962

Conversation

@brendancol
Copy link
Contributor

Summary

  • Add sky_view_factor() — fraction of visible sky hemisphere per DEM cell
  • All four backends: NumPy (@ngjit), CuPy (@cuda.jit), Dask+NumPy (map_overlap), Dask+CuPy
  • Casts rays at n_directions azimuths out to max_radius cells, tracks max horizon angle per direction
  • SVF = 1 - mean(sin(max_horizon_angle)) per Zakek et al. (2011)

What changed

  • New module xrspatial/sky_view_factor.py — CPU kernel, CUDA kernel, Dask wrappers
  • Export in xrspatial/__init__.py
  • 25 tests: correctness (flat, valley, ridge, ramp), NaN handling, validation, cross-backend, Dataset support
  • API docs in docs/source/reference/surface.rst
  • User guide notebook examples/user_guide/22_Sky_View_Factor.ipynb
  • README feature matrix row under Surface

Test plan

  • pytest xrspatial/tests/test_sky_view_factor.py — 25/25 pass
  • All four backends produce matching results
  • Flat surface gives SVF=1.0, valley floor < 1, ridge summit > 0.9
  • NaN propagation and single-cell raster work correctly
  • Bad parameters raise errors

Closes #962

New xrspatial.sky_view_factor module with all four backends:
NumPy (@ngjit), CuPy (@cuda.jit), Dask+NumPy, and Dask+CuPy.
25 tests covering correctness, NaN handling, range validation,
cross-backend equivalence (NumPy/Dask/CuPy/Dask+CuPy), and
Dataset support. Edge cells now compute with truncated rays
instead of returning NaN, keeping numpy and dask paths consistent.
- Add Sky-View Factor entry to docs/source/reference/surface.rst
- Add examples/user_guide/22_Sky_View_Factor.ipynb with parameter
  exploration and hillshade comparison
@brendancol brendancol added the enhancement New feature or request label Mar 5, 2026
@github-actions github-actions bot added the performance PR touches performance-sensitive code label Mar 5, 2026
@brendancol brendancol merged commit ede4c44 into master Mar 5, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request performance PR touches performance-sensitive code

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add sky-view factor to surface module

1 participant