Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@prantogg
prantogg committed Feb 10, 2025
1 parent 4f08c9c commit 13bdaba
Show file tree
Hide file tree
Showing 3 changed files with 82 additions and 29 deletions.
76 changes: 59 additions & 17 deletions docs/api/sql/Raster-operators.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1160,6 +1160,10 @@ Output:

Introduction: This returns a statistic value specified by `statType` over the region of interest defined by `zone`. It computes the statistic from the pixel values within the ROI geometry and returns the result. If the `excludeNoData` parameter is not specified, it will default to `true`. This excludes NoData values from the statistic calculation. Additionally, if the `band` parameter is not provided, band 1 will be used by default for the statistic computation. The valid options for `statType` are:

The `allTouched` parameter (Since `v1.7.1`) determines how pixels are selected:
- When true, any pixel touched by the geometry will be included.
- When false (default), only pixels whose centroid intersects with the geometry will be included.

- `count`: Number of pixels in the region.
- `sum`: Sum of pixel values.
- `mean|average|avg`: Arithmetic mean.
Expand All @@ -1183,15 +1187,19 @@ Introduction: This returns a statistic value specified by `statType` over the re
Format:

```
RS_ZonalStats(raster: Raster, zone: Geometry, band: Integer, statType: String, excludeNoData: Boolean, lenient: Boolean)
RS_ZonalStats(raster: Raster, zone: Geometry, band: Integer, statType: String, allTouched: Boolean, excludeNoData: Boolean, lenient: Boolean)
```

```
RS_ZonalStats(raster: Raster, zone: Geometry, band: Integer, statType: String, allTouched: Boolean, excludeNoData: Boolean)
```

```
RS_ZonalStats(raster: Raster, zone: Geometry, band: Integer, statType: String, excludeNoData: Boolean)
RS_ZonalStats(raster: Raster, zone: Geometry, band: Integer, statType: String, allTouched: Boolean)
```

```
RS_ZonalStats(raster: Raster, zone: Geometry, band: Integer, statType: String)
RS_ZonalStats(raster: Raster, zone: Geometry, statType: String, allTouched: Boolean)
```

```
Expand All @@ -1203,7 +1211,7 @@ Since: `v1.5.1`
SQL Example

```sql
RS_ZonalStats(rast1, geom1, 1, 'sum', false)
RS_ZonalStats(rast1, geom1, 1, 'sum', true, false)
```

Output:
Expand All @@ -1215,7 +1223,7 @@ Output:
SQL Example

```sql
RS_ZonalStats(rast2, geom2, 1, 'mean', true)
RS_ZonalStats(rast2, geom2, 1, 'mean', false, true)
```

Output:
Expand All @@ -1228,6 +1236,10 @@ Output:

Introduction: Returns a struct of statistic values, where each statistic is computed over a region defined by the `zone` geometry. The struct has the following schema:

The `allTouched` parameter (Since `v1.7.1`) determines how pixels are selected:
- When true, any pixel touched by the geometry will be included.
- When false (default), only pixels whose centroid intersects with the geometry will be included.

- count: Count of the pixels.
- sum: Sum of the pixel values.
- mean: Arithmetic mean.
Expand All @@ -1251,11 +1263,15 @@ Introduction: Returns a struct of statistic values, where each statistic is comp
Format:

```
RS_ZonalStatsAll(raster: Raster, zone: Geometry, band: Integer, excludeNodata: Boolean, lenient: Boolean)
RS_ZonalStatsAll(raster: Raster, zone: Geometry, band: Integer, allTouched: Boolean, excludeNodata: Boolean, lenient: Boolean)
```

```
RS_ZonalStatsAll(raster: Raster, zone: Geometry, band: Integer, allTouched: Boolean, excludeNodata: Boolean)
```

```
RS_ZonalStatsAll(raster: Raster, zone: Geometry, band: Integer, excludeNodata: Boolean)
RS_ZonalStatsAll(raster: Raster, zone: Geometry, band: Integer, allTouched: Boolean)
```

```
Expand All @@ -1271,7 +1287,7 @@ Since: `v1.5.1`
SQL Example

```sql
RS_ZonalStatsAll(rast1, geom1, 1, false)
RS_ZonalStatsAll(rast1, geom1, 1, true, false)
```

Output:
Expand All @@ -1283,7 +1299,7 @@ Output:
SQL Example

```sql
RS_ZonalStatsAll(rast2, geom2, 1, true)
RS_ZonalStatsAll(rast2, geom2, 1, false, true)
```

Output:
Expand Down Expand Up @@ -1446,22 +1462,30 @@ Introduction: Returns a raster that is clipped by the given geometry.

If `crop` is not specified then it will default to `true`, meaning it will make the resulting raster shrink to the geometry's extent and if `noDataValue` is not specified then the resulting raster will have the minimum possible value for the band pixel data type.

The `allTouched` parameter (Since `v1.7.1`) determines how pixels are selected:
- When true, any pixel touched by the geometry will be included.
- When false (default), only pixels whose centroid intersects with the geometry will be included.

!!!Note
- Since `v1.5.1`, if the coordinate reference system (CRS) of the input `geom` geometry differs from that of the `raster`, then `geom` will be transformed to match the CRS of the `raster`. If the `raster` or `geom` doesn't have a CRS then it will default to `4326/WGS84`.
- Since `v1.7.0`, `RS_Clip` function will return `null` if the `raster` and `geometry` geometry do not intersect. If you want to throw an exception in this case, you can set the `lenient` parameter to `false`.

Format:

```
RS_Clip(raster: Raster, band: Integer, geom: Geometry, noDataValue: Double, crop: Boolean, lenient: Boolean)
RS_Clip(raster: Raster, band: Integer, geom: Geometry, allTouched: Boolean, noDataValue: Double, crop: Boolean, lenient: Boolean)
```

```
RS_Clip(raster: Raster, band: Integer, geom: Geometry, allTouched: Boolean, noDataValue: Double, crop: Boolean)
```

```
RS_Clip(raster: Raster, band: Integer, geom: Geometry, noDataValue: Double, crop: Boolean)
RS_Clip(raster: Raster, band: Integer, geom: Geometry, allTouched: Boolean, noDataValue: Double)
```

```
RS_Clip(raster: Raster, band: Integer, geom: Geometry, noDataValue: Double)
RS_Clip(raster: Raster, band: Integer, geom: Geometry, allTouched: Boolean)
```

```
Expand All @@ -1480,7 +1504,7 @@ SQL Example
SELECT RS_Clip(
RS_FromGeoTiff(content), 1,
ST_GeomFromWKT('POLYGON ((236722 4204770, 243900 4204770, 243900 4197590, 221170 4197590, 236722 4204770))'),
200, true
false, 200, true
)
```

Expand All @@ -1494,7 +1518,7 @@ SQL Example
SELECT RS_Clip(
RS_FromGeoTiff(content), 1,
ST_GeomFromWKT('POLYGON ((236722 4204770, 243900 4204770, 243900 4197590, 221170 4197590, 236722 4204770))'),
200, false
false, 200, false
)
```

Expand Down Expand Up @@ -2039,14 +2063,14 @@ to this function.
!!!Note
Since `v1.5.1`, if the coordinate reference system (CRS) of the input `geom` geometry differs from that of the `raster`, then `geom` will be transformed to match the CRS of the `raster`. If the `raster` or `geom` doesn't have a CRS then it will default to `4326/WGS84`.

Format:
Format without ROI `geom`:

```
RS_SetValues(raster: Raster, bandIndex: Integer, colX: Integer, rowY: Integer, width: Integer, height: Integer, newValues: ARRAY[Double], keepNoData: Boolean = false)
```

```
RS_SetValues(raster: Raster, bandIndex: Integer, geom: Geometry, newValue: Double, keepNoData: Boolean = false)
RS_SetValues(raster: Raster, bandIndex: Integer, colX: Integer, rowY: Integer, width: Integer, height: Integer, newValues: ARRAY[Double])
```

Since: `v1.5.0`
Expand All @@ -2056,12 +2080,30 @@ set to the corresponding value in `newValues`. The `newValues` should be provide

The geometry variant of this function accepts all types of Geometries, and it sets the `newValue` in the specified region under the `geom`.

The `allTouched` parameter (Since `v1.7.1`) determines how pixels are selected:
- When true, any pixel touched by the geometry will be included.
- When false (default), only pixels whose centroid intersects with the geometry will be included.

!!!note
If the shape of `newValues` doesn't match with provided `width` and `height`, `IllegalArgumentException` is thrown.

!!!Note
If the mentioned `bandIndex` doesn't exist, this will throw an `IllegalArgumentException`.

Format with ROI `geom`:

```
RS_SetValues(raster: Raster, bandIndex: Integer, geom: Geometry, newValue: Double, allTouched: Boolean = false, keepNoData: Boolean = false)
```

```
RS_SetValues(raster: Raster, bandIndex: Integer, geom: Geometry, newValue: Double, allTouched: Boolean = false)
```

```
RS_SetValues(raster: Raster, bandIndex: Integer, geom: Geometry, newValue: Double)
```

SQL Example

```sql
Expand Down Expand Up @@ -2091,7 +2133,7 @@ SELECT RS_BandAsArray(
RS_MakeEmptyRaster(1, 5, 5, 1, -1, 1, -1, 0, 0, 0),
Array(0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0), 1
),
1, ST_GeomFromWKT('POLYGON((1 -1, 3 -3, 6 -6, 4 -1, 1 -1))'), 255, false
1, ST_GeomFromWKT('POLYGON((1 -1, 3 -3, 6 -6, 4 -1, 1 -1))'), 255, false, false
)
)
```
Expand Down
27 changes: 19 additions & 8 deletions docs/api/sql/Raster-writer.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -245,21 +245,32 @@ The newly created DataFrame can be written to disk again but must be under a dif

#### RS_AsRaster

Introduction: Converts a Geometry to a Raster dataset. Defaults to using `1.0` for cell `value` and `null` for `noDataValue` if not provided. Supports all geometry types.
The `pixelType` argument defines data type of the output raster. This can be one of the following, D (double), F (float), I (integer), S (short), US (unsigned short) or B (byte).
The `useGeometryExtent` argument defines the extent of the resultant raster. When set to `true`, it corresponds to the extent of `geom`, and when set to false, it corresponds to the extent of `raster`. Default value is `true` if not set.
Introduction: `RS_AsRaster` converts a vector geometry into a raster dataset by assigning a specified value to all pixels covered by the geometry. Unlike `RS_Clip`, which extracts a subset of an existing raster while preserving its original values, `RS_AsRaster` generates a new raster where the geometry is rasterized onto a raster grid. The function supports all geometry types and takes the following parameters:

- `geom`: The geometry to be rasterized.
- `raster`: The reference raster to be used for overlaying the `geom` on.
- `pixelType`: Defines data type of the output raster. This can be one of the following, D (double), F (float), I (integer), S (short), US (unsigned short) or B (byte).
- `allTouched` (Since: `v1.7.1`): Decides the pixel selection criteria. If set to `true`, the function selects all pixels touched by the geometry, else, selects only pixels who's centroids intersect the geometry. Defaults to `false`.
- `Value`: The value to be used for assigning pixels covered by the geometry. Defaults to using `1.0` for cell `value` if not provided.
- `noDataValue`: Used for assigning the no data value of the resultant raster. Defaults to `null` if not provided.
- `useGeometryExtent`: Defines the extent of the resultant raster. When set to `true`, it corresponds to the extent of `geom`, and when set to false, it corresponds to the extent of `raster`. Default value is `true` if not set.

Format:

```
RS_AsRaster(geom: Geometry, raster: Raster, pixelType: String, value: Double, noDataValue: Double, useGeometryExtent: Boolean)
RS_AsRaster(geom: Geometry, raster: Raster, pixelType: String, allTouched: Boolean, value: Double, noDataValue: Double, useGeometryExtent: Boolean)
```

```
RS_AsRaster(geom: Geometry, raster: Raster, pixelType: String, allTouched: Boolean, value: Double, noDataValue: Double)
```

```
RS_AsRaster(geom: Geometry, raster: Raster, pixelType: String, value: Double, noDataValue: Double)
RS_AsRaster(geom: Geometry, raster: Raster, pixelType: String, allTouched: Boolean, value: Double)
```

```
RS_AsRaster(geom: Geometry, raster: Raster, pixelType: String, value: Double)
RS_AsRaster(geom: Geometry, raster: Raster, pixelType: String, allTouched: Boolean)
```

```
Expand All @@ -286,7 +297,7 @@ SQL Example
SELECT RS_AsRaster(
ST_GeomFromWKT('POLYGON((15 15, 18 20, 15 24, 24 25, 15 15))'),
RS_MakeEmptyRaster(2, 255, 255, 3, -215, 2, -2, 0, 0, 4326),
'D', 255.0, 0d
'D', false, 255.0, 0d
)
```

Expand Down Expand Up @@ -316,7 +327,7 @@ GridCoverage2D["g...
SELECT RS_AsRaster(
ST_GeomFromWKT('POLYGON((15 15, 18 20, 15 24, 24 25, 15 15))'),
RS_MakeEmptyRaster(2, 255, 255, 3, 215, 2, -2, 0, 0, 0),
'D',255, 0d, false
'D', true, 255, 0d, false
)
```

Expand Down
8 changes: 4 additions & 4 deletions pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -545,7 +545,7 @@
<failOnWarning>false</failOnWarning>
<sourceDirectory>${project.basedir}/src/main/scala</sourceDirectory>
<testSourceDirectory>${project.basedir}/src/test/scala</testSourceDirectory>
<configLocation>/Users/pranavtoggi/Documents/sedona/tools/maven/scalastyle_config.xml</configLocation>
<configLocation>tools/maven/scalastyle_config.xml</configLocation>
<outputFile>${project.basedir}/target/scalastyle-output.xml</outputFile>
<outputEncoding>UTF-8</outputEncoding>
</configuration>
Expand Down Expand Up @@ -650,17 +650,17 @@
<version>1.7</version>
</googleJavaFormat>
<licenseHeader>
<file>/Users/pranavtoggi/Documents/sedona/tools/maven/license-header.txt</file>
<file>tools/maven/license-header.txt</file>
</licenseHeader>
</java>
<scala>
<scalafmt>
<version>3.7.5</version>
<file>/Users/pranavtoggi/Documents/sedona/tools/maven/scalafmt.conf</file>
<file>tools/maven/scalafmt.conf</file>
<scalaMajorVersion>2.12</scalaMajorVersion>
</scalafmt>
<licenseHeader>
<file>/Users/pranavtoggi/Documents/sedona/tools/maven/license-header.txt</file>
<file>tools/maven/license-header.txt</file>
</licenseHeader>
</scala>
</configuration>
Expand Down

0 comments on commit 13bdaba

Please sign in to comment.