jiayuasu opened a new pull request, #3212: URL: https://github.com/apache/sedona/pull/3212
## Did you read the Contributor Guide? - Yes, I have read the [Contributor Rules](https://sedona.apache.org/latest/community/rule/) and [Contributor Development Guide](https://sedona.apache.org/latest/community/develop/) ## Is this PR related to a ticket? - No: - this is a documentation update. The PR name follows the format `[DOCS] my subject` ## What changes were proposed in this PR? Raster-returning Python UDFs landed in #2956 and ship in 1.9.1, but they are documented only as a ~55-line subsection of `docs/tutorial/raster.md` — no page under `docs/api/sql/`, no nav entry, and no link to them from the map algebra docs. Map algebra by contrast has a concept page in nav, a per-function reference page, an index row, and a worked example in the tutorial walkthrough, so a reader comparing the two options sees them very unevenly. This adds `docs/api/sql/Raster-UDF.md` (plus the `zh` translation and both nav entries) as a concept page beside `Raster-map-algebra.md`, covering both ways of reading pixels: - when a UDF is a better fit than `RS_MapAlgebra` and when it isn't, including where each one runs and a pointer to `pandas_udf` for batching - raster-to-scalar and raster-to-raster, in both the DataFrame form and the `register` + `expr` form (the DataFrame form is used throughout `test_flexible_bands.py` but appeared in no doc) - NDVI written as a Jiffle script and as NumPy, side by side - two-raster UDFs — the equivalent of `RS_MapAlgebra`'s five-argument form - using rasterio inside a UDF: `as_rasterio()` → compute → `with_bands()` round-trips for grid-preserving operations such as `fillnodata`. This works today but was not documented, and the tutorial's only rasterio mention showed `ds.read(1)` with no return path, which made it look impossible. - **Limits**, stated plainly: the output stays on the input's grid; NODATA is inherited from the input rather than settable; and `uint32`, `int8`, `int64`/`uint64` don't survive the round trip cleanly - Scala UDFs over `GridCoverage2D`, which work in both directions and — unlike the Python path — have no restriction on the output grid Also cross-links `Raster-map-algebra.md` (+ `zh`), `RS_MapAlgebra.md`, `Raster-Functions.md`, and `docs/tutorial/raster.md` (+ `zh`), and fixes the `RS_SetBandNoDataValue` link path in the new tutorial text — that page lives under `Raster-Operators/`, not `Raster-Band-Accessors/`. ## How was this patch tested? Every code example was executed against a local `1.9.1-SNAPSHOT` build (`-Dspark=3.4 -Dscala=2.12 -Dgeotools`) rather than written from reading the source. The stated limits and error messages are observed behaviour: - the NDVI UDF, the two-raster UDF, and the `fillnodata` rasterio round trip all produce single-band rasters with SRID and scale carried over from the input - `with_bands()` on a mismatched shape raises exactly the `ValueError` quoted on the page - NODATA inheritance: with NODATA `0` on the input's band 1, a 4→1 band UDF yields an output whose band 1 NODATA is also `0`, and `RS_Count(rast, 1, true)` returns 6 against `RS_Count(rast, 1, false)` returning 12 on a 12-pixel mask - the Python/JVM disagreement noted in the page: widening a 4-band raster whose band 4 has NODATA `-1` to 8 bands gives Python `[nan, nan, nan, -1.0, nan, nan, nan, nan]` while SQL reports `-1.0` for bands 4–8 - `int8` `-2` reads back as `254`; `int64`/`uint64` raise `ValueError` - all three `udf.register` forms shown work - the Scala examples were run as a ScalaTest suite, including one that returns a 7×5 EPSG:4326 raster from a 4×3 EPSG:3857 input, which is what backs the claim that Scala UDFs aren't pinned to the input grid `uv run mkdocs build` produces 15 warnings, identical to the count on unmodified `master` — the change introduces none. Both locales render, the new nav entry appears in each, and the `#limits` / `#scala-and-java` anchors resolve in both. The `zh` page needed its explicit anchors wrapped in `{% raw %}` (the convention already used in `raster.zh.md`) because `{#...}` otherwise opens an unterminated Jinja comment and the macros plugin replaces the page with a syntax error. Full pre-commit suite passes. ## Did this PR include necessary documentation updates? - Yes, I have updated the documentation. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
