[DOCS] Fix docs of SedonaSnow, Affine transformation, SedonaUtils, Sh…

…apefile charset (#1377)

* Update SedonaSnow docs

* Add affine transformation, SedonaUtils

* Fix linter

* Add doc for Shapefile charset

docs/api/snowflake/vector-data/AggregateFunction.md

@@ -10,13 +10,20 @@ Format: `ST_Envelope_Aggr (A:geometryColumn)`
 SQL example:
 
 ```sql
-SELECT ST_Envelope_Aggr(ST_GeomFromText('MULTIPOINT(1.1 101.1,2.1 102.1,3.1 103.1,4.1 104.1,5.1 105.1,6.1 106.1,7.1 107.1,8.1 108.1,9.1 109.1,10.1 110.1)'))
+WITH src_tbl AS (
+    SELECT sedona.ST_GeomFromText('POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))') AS geom
+    UNION
+    SELECT sedona.ST_GeomFromText('POLYGON ((0.5 0.5, 0.5 1.5, 1.5 1.5, 1.5 0.5, 0.5 0.5))') AS geom
+)
+SELECT sedona.ST_AsText(envelope)
+FROM src_tbl,
+     TABLE(sedona.ST_Envelope_Aggr(src_tbl.geom) OVER (PARTITION BY 1));
 ```
 
 Output:
 
 ```
-POLYGON ((1.1 101.1, 1.1 120.1, 20.1 120.1, 20.1 101.1, 1.1 101.1))
+POLYGON ((0 0, 0 1.5, 1.5 1.5, 1.5 0, 0 0))
 ```
 
 ## ST_Intersection_Aggr
@@ -28,13 +35,20 @@ Format: `ST_Intersection_Aggr (A:geometryColumn)`
 SQL example:
 
 ```sql
-SELECT ST_Intersection_Aggr(ST_GeomFromText('MULTIPOINT(1.1 101.1,2.1 102.1,3.1 103.1,4.1 104.1,5.1 105.1,6.1 106.1,7.1 107.1,8.1 108.1,9.1 109.1,10.1 110.1)'))
+WITH src_tbl AS (
+    SELECT sedona.ST_GeomFromText('POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))') AS geom
+    UNION
+    SELECT sedona.ST_GeomFromText('POLYGON ((0.5 0.5, 0.5 1.5, 1.5 1.5, 1.5 0.5, 0.5 0.5))') AS geom
+)
+SELECT sedona.ST_AsText(intersected)
+FROM src_tbl,
+     TABLE(sedona.ST_Intersection_Aggr(src_tbl.geom) OVER (PARTITION BY 1));
 ```
 
 Output:
 
 ```
-MULTIPOINT ((1.1 101.1), (2.1 102.1), (3.1 103.1), (4.1 104.1), (5.1 105.1), (6.1 106.1), (7.1 107.1), (8.1 108.1), (9.1 109.1), (10.1 110.1))
+POLYGON ((0.5 1, 1 1, 1 0.5, 0.5 0.5, 0.5 1))
 ```
 
 ## ST_Union_Aggr
@@ -46,11 +60,18 @@ Format: `ST_Union_Aggr (A:geometryColumn)`
 SQL example:
 
 ```sql
-SELECT ST_Union_Aggr(ST_GeomFromText('MULTIPOINT(1.1 101.1,2.1 102.1,3.1 103.1,4.1 104.1,5.1 105.1,6.1 106.1,7.1 107.1,8.1 108.1,9.1 109.1,10.1 110.1)'))
+WITH src_tbl AS (
+    SELECT sedona.ST_GeomFromText('POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))') AS geom
+    UNION
+    SELECT sedona.ST_GeomFromText('POLYGON ((0.5 0.5, 0.5 1.5, 1.5 1.5, 1.5 0.5, 0.5 0.5))') AS geom
+)
+SELECT sedona.ST_AsText(unioned)
+FROM src_tbl,
+     TABLE(sedona.ST_Union_Aggr(src_tbl.geom) OVER (PARTITION BY 1));
 ```
 
 Output:
 
 ```
-MULTIPOINT ((1.1 101.1), (2.1 102.1), (3.1 103.1), (4.1 104.1), (5.1 105.1), (6.1 106.1), (7.1 107.1), (8.1 108.1), (9.1 109.1), (10.1 110.1))
+POLYGON ((0 0, 0 1, 0.5 1, 0.5 1.5, 1.5 1.5, 1.5 0.5, 1 0.5, 1 0, 0 0))
 ```

docs/api/snowflake/vector-data/Function.md

@@ -542,48 +542,38 @@ Output: `POINT(131.59149149528952 101.89887534906197)`
 
 ## ST_Collect
 
-Introduction: Returns MultiGeometry object based on a geometry column.
-
-Format
+Introduction:
 
-`ST_Collect(*geom: geometry)`
+Build an appropriate `Geometry`, `MultiGeometry`, or `GeometryCollection` to contain the `Geometry`s in it. For example:
 
-Example:
+- If `geomList` contains a single `Polygon`, the `Polygon` is returned.
+- If `geomList` contains several `Polygon`s, a `MultiPolygon` is returned.
+- If `geomList` contains some `Polygon`s and some `LineString`s, a `GeometryCollection` is returned.
+- If `geomList` is empty, an empty `GeometryCollection` is returned.
 
-```SQL
-SELECT ST_Collect(
-    tbl.geom) AS geom
-```
+Note that this method does not "flatten" Geometries in the input, and hence if any MultiGeometries are contained in the input, a GeometryCollection containing them will be returned.
 
-Result:
+Format
 
-```
-+---------------------------------------------------------------+
-|geom                                                           |
-+---------------------------------------------------------------+
-|MULTIPOINT ((21.427834 52.042576573), (45.342524 56.342354355))|
-+---------------------------------------------------------------+
-```
+`ST_Collect(*geom: geometry)`
 
 Example:
 
 ```SQL
-SELECT ST_Collect(
-    Array(
-        ST_GeomFromText('POINT(21.427834 52.042576573)'),
-        ST_GeomFromText('POINT(45.342524 56.342354355)')
-    )
-) AS geom
+WITH src_tbl AS (
+    SELECT sedona.ST_GeomFromText('POINT (40 10)') AS geom
+    UNION
+    SELECT sedona.ST_GeomFromText('LINESTRING (0 5, 0 10)') AS geom
+)
+SELECT sedona.ST_AsText(collection)
+FROM src_tbl,
+     TABLE(sedona.ST_Collect(src_tbl.geom) OVER (PARTITION BY 1));
 ```
 
 Result:
 
 ```
-+---------------------------------------------------------------+
-|geom                                                           |
-+---------------------------------------------------------------+
-|MULTIPOINT ((21.427834 52.042576573), (45.342524 56.342354355))|
-+---------------------------------------------------------------+
+GEOMETRYCOLLECTION (POINT (40 10), LINESTRING (0 5, 0 10))
 ```
 
 ## ST_CollectionExtract
@@ -821,17 +811,25 @@ Output: `544430.9411996207`
 
 ## ST_Dump
 
-Introduction: This is an aggregate function that takes a column of geometries as input, and returns a single GeometryCollection of all these geometries.
+Introduction: This function takes a GeometryCollection/Multi Geometry object and returns a set of geometries containing the individual geometries that make up the input geometry. The function is useful for breaking down a GeometryCollection/Multi Geometry into its constituent geometries.
 
 Format: `ST_Dump(geom: geometry)`
 
 SQL example:
 
 ```SQL
-SELECT ST_Dump(tbl.geom)
+SELECT sedona.ST_AsText(geom)
+FROM table(sedona.ST_Dump(sedona.ST_GeomFromText('MULTIPOINT ((10 40), (40 30), (20 20), (30 10))')));
 ```
 
-Output: `GeometryCollection ( (10 40), (40 30), (20 20), (30 10) )`
+Output:
+
+```
+POINT (10 40)
+POINT (40 30)
+POINT (20 20)
+POINT (30 10)
+```
 
 ## ST_DumpPoints
 
@@ -1628,7 +1626,14 @@ Format: `ST_MinimumBoundingRadius(geom: geometry)`
 SQL example:
 
 ```SQL
-SELECT ST_MinimumBoundingRadius(ST_GeomFromText('POLYGON((1 1,0 0, -1 1, 1 1))'))
+SELECT sedona.ST_AsText(center), radius
+FROM table(sedona.ST_MinimumBoundingRadius(sedona.ST_GeomFromText('POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))')))
+```
+
+Result:
+
+```
+POINT (0.5 0.5), 0.7071067811865476
 ```
 
 ## ST_Multi

docs/api/sql/Constructor.md

@@ -35,13 +35,13 @@ spatialDf.printSchema()
 !!!warning
 	Please make sure you use ==ST_GeomFromWKT== to create Geometry type column otherwise that column cannot be used in SedonaSQL.
 
-If the file you are reading contains non-ASCII characters you'll need to explicitly set the encoding
-via `sedona.global.charset` system property before the call to `ShapefileReader.readToGeometryRDD`.
+If the file you are reading contains non-ASCII characters you'll need to explicitly set the Spark config before initializing the SparkSession, then you can use `ShapefileReader.readToGeometryRDD`.
 
 Example:
 
 ```scala
-System.setProperty("sedona.global.charset", "utf8")
+spark.driver.extraJavaOptions  -Dsedona.global.charset=utf8
+spark.executor.extraJavaOptions  -Dsedona.global.charset=utf8
 ```
 
 ## ST_GeomFromEWKT

docs/api/sql/DataFrameAPI.md

@@ -39,14 +39,14 @@ A short example of using this API (uses the `array_min` and `array_max` Spark fu
 	```python3
 	from pyspark.sql import functions as f
 
-	from sedona.sql import st_constructors as stc
+	from sedona.spark import *
 
 	df = spark.sql("SELECT array(0.0, 1.0, 2.0) AS values")
 
 	min_value = f.array_min("values")
 	max_value = f.array_max("values")
 
-	df = df.select(stc.ST_Point(min_value, max_value).alias("point"))
+	df = df.select(ST_Point(min_value, max_value).alias("point"))
 	```
 
 The above code will generate the following dataframe:
@@ -63,7 +63,9 @@ Some functions will take native python values and infer them as literals.
 For example:
 
 ```python3
-df = df.select(stc.ST_Point(1.0, 3.0).alias("point"))
+from sedona.spark import *
+
+df = df.select(ST_Point(1.0, 3.0).alias("point"))
 ```
 
 This will generate a dataframe with a constant point in a column:

docs/api/sql/Raster-affine-transformation.md

@@ -0,0 +1,64 @@
+This page explains the basic concepts of Affine Transformation in Sedona Raster.
+
+## Affine Transformations
+
+Affine transformations are a fundamental concept in computer graphics, geometry, and image processing that involve manipulating an object in a way that preserves lines and parallelism (but not necessarily distances and angles). These transformations are linear transformations followed by a translation, which means they can translate, scale, rotate, and shear objects without altering the relative arrangement of points, lines, or planes.
+
+### Components of Affine Transformations
+
+Affine transformations can be represented as a matrix operation. In two-dimensional space, a typical affine transformation matrix is a 3x3 matrix as follows:
+
+```
+| ScaleX  SkewX   TranslationX |
+| SkewY   ScaleY  TranslationY |
+| 0       0       1            |
+```
+
+Here, `ScaleX, ScaleY, SkewX, SkewY, TranslationX,` and `TranslationY` are parameters that define the transformation:
+
+- `ScaleX` and `ScaleY` are scaling factors for the x and y axes, respectively.
+- `SkewX` and `SkewY` introduce shearing and are responsible for "skewing" the shape.
+- `TranslationX` and `TranslationY` are translation parameters that move the shape in the x and y directions, respectively.
+
+### Types of Affine Transformations
+
+1. **Translation**: Moves every point of a figure or space by the same distance in a given direction. This primarily affects the `TranslationX` and `TranslationY` components.
+
+2. **Scaling**: Multiplies the coordinates of each point by a constant (ScaleX for x-axis and ScaleY for y-axis), enlarging or reducing its size. Scaling can be uniform (the same factor for both axes) or non-uniform (different factors for each axis).
+
+3. **Rotation**: Rotates the object about a point (usually the origin or a specified point). This can be expressed through combinations of `ScaleX, ScaleY, SkewX,` and `SkewY` where these parameters are derived from the cosine and sine of the rotation angle.
+
+4. **Shearing**: Transforms parallel lines to still be parallel but moves them so that they are no longer perpendicular to their original orientations. This affects the `SkewX` and `SkewY` components.
+
+5. **Reflection**: Flips the object over a specified axis, which can be achieved by combining scaling and rotation.
+
+### Mathematical Properties
+
+- **Collinearity and Concurrency**: Affine transformations preserve points on a line (collinearity) and the intersection of lines (concurrency).
+- **Ratios of Segments**: They also preserve the ratios of distances between points lying on a straight line.
+
+## Components of Affine Transformations
+
+In affine transformations, which are integral to manipulating graphics, images, and geometric data, the terms **ScaleX**, **ScaleY**, **SkewX**, and **SkewY** refer to specific types of transformations that alter the shape and position of objects:
+
+### ScaleX and ScaleY
+
+- **ScaleX**: This parameter represents the scaling factor along the x-axis. It modifies the width of an image or object. Values greater than 1 increase the width, values less than 1 decrease it, and negative values reflect the object along the x-axis while scaling.
+
+- **ScaleY**: This parameter represents the scaling factor along the y-axis. It affects the height of the object. Similarly to ScaleX, values greater than 1 enlarge the object vertically, values less than 1 reduce it, and negative values invert it along the y-axis.
+
+### SkewX and SkewY
+
+- **SkewX**: This parameter is used to skew or shear the object along the x-axis. It shifts each point's x-coordinate in proportion to its y-coordinate, creating a slanting effect. This transformation is useful for creating the illusion of depth or perspective in 2D representations.
+
+- **SkewY**: Corresponding to SkewX, SkewY skews the object along the y-axis. It alters each point's y-coordinate relative to its x-coordinate, which also creates a slanting effect, but in the vertical direction.
+
+These transformations are typically used together in a transformation matrix, which allows them to be applied to objects in a combined and coherent way. Here's a typical representation of such a matrix:
+
+```
+| ScaleX  SkewX   TranslationX |
+| SkewY   ScaleY  TranslationY |
+| 0       0       1            |
+```
+
+These parameters can be combined in various ways to perform complex transformations such as rotations, translations, scaling, and shearing of images or shapes in both 2D and 3D graphics applications.

docs/api/sql/Raster-loader.md

@@ -93,14 +93,16 @@ Accepts one of:
 * Height: The height of the raster in pixels.
 * UpperleftX: The X coordinate of the upper left corner of the raster, in terms of the CRS units.
 * UpperleftY: The Y coordinate of the upper left corner of the raster, in terms of the CRS units.
-* ScaleX (pixel size on X): The size of the cells on the X axis, in terms of the CRS units.
-* ScaleY (pixel size on Y): The size of the cells on the Y axis, in terms of the CRS units.
-* SkewX: The skew of the raster on the X axis, in terms of the CRS units.
-* SkewY: The skew of the raster on the Y axis, in terms of the CRS units.
+* ScaleX: The scaling factor of the cells on the X axis
+* ScaleY: The scaling factor of the cells on the Y axis
+* SkewX: The skew of the raster on the X axis, effectively tilting them in the horizontal direction
+* SkewY: The skew of the raster on the Y axis, effectively tilting them in the vertical direction
 * SRID: The SRID of the raster. Use 0 if you want to use the default Cartesian coordinate system. Use 4326 if you want to use WGS84.
 
+For more information about ScaleX, ScaleY, SkewX, SkewY, please refer to the [Affine Transformations](Raster-affine-transformation.md) section.
+
 !!!Note
-  If any other value than the accepted values for the bandDataType is provided, RS_MakeEmptyRaster defaults to double as the data type for the raster.
+    If any other value than the accepted values for the bandDataType is provided, RS_MakeEmptyRaster defaults to double as the data type for the raster.
 
 Spark SQL example 1 (with 2 bands):
 

docs/api/sql/Raster-operators.md

@@ -348,6 +348,8 @@ Provided band index 3 does not lie in the raster
 
 Introduction: Returns the georeference metadata of raster as a string in GDAL or ESRI format. Default is GDAL if not specified.
 
+For more information about ScaleX, ScaleY, SkewX, SkewY, please refer to the [Affine Transformations](Raster-affine-transformation.md) section.
+
 !!!note
     If you are using `show()` to display the output, it will show special characters as escape sequences. To get the expected behavior use the following code:
 
@@ -585,12 +587,15 @@ Output:
 ### RS_ScaleX
 
 Introduction: Returns the pixel width of the raster in CRS units.
+
 !!!Note
     RS_ScaleX attempts to get an Affine transform on the grid in order to return scaleX (See [World File](https://en.wikipedia.org/wiki/World_file) for more details). If the transform on the geometry is not an Affine transform, RS_ScaleX will throw an UnsupportedException:
     ```
     UnsupportedOperationException("Only AffineTransform2D is supported")
     ```
 
+For more information about ScaleX, ScaleY, SkewX, SkewY, please refer to the [Affine Transformations](Raster-affine-transformation.md) section.
+
 Format: `RS_ScaleX(raster: Raster)`
 
 Since: `v1.5.0`
@@ -610,12 +615,15 @@ Output:
 ### RS_ScaleY
 
 Introduction: Returns the pixel height of the raster in CRS units.
+
 !!!Note
     RS_ScaleY attempts to get an Affine transform on the grid in order to return scaleX (See [World File](https://en.wikipedia.org/wiki/World_file) for more details). If the transform on the geometry is not an Affine transform, RS_ScaleY will throw an UnsupportedException:
     ```
     UnsupportedOperationException("Only AffineTransform2D is supported")
     ```
 
+For more information about ScaleX, ScaleY, SkewX, SkewY, please refer to the [Affine Transformations](Raster-affine-transformation.md) section.
+
 Format: `RS_ScaleY(raster: Raster)`
 
 Since: `v1.5.0`
@@ -1539,13 +1547,15 @@ Introduction: Returns the metadata of the raster as an array of double. The arra
 - 1: upper left y coordinate of the raster, in terms of CRS units
 - 2: width of the raster, in terms of pixels
 - 3: height of the raster, in terms of pixels
-- 4: width of a pixel, in terms of CRS units (scaleX)
-- 5: height of a pixel, in terms of CRS units (scaleY), may be negative
+- 4: ScaleX: the scaling factor in the x direction
+- 5: ScaleY: the scaling factor in the y direction
 - 6: skew in x direction (rotation x)
 - 7: skew in y direction (rotation y)
 - 8: srid of the raster
 - 9: number of bands
 
+For more information about ScaleX, ScaleY, SkewX, SkewY, please refer to the [Affine Transformations](Raster-affine-transformation.md) section.
+
 Format: `RS_MetaData (raster: Raster)`
 
 Since: `v1.4.1`
@@ -1688,6 +1698,9 @@ Following are valid values for the algorithm parameter (Case-insensitive):
 
 !!!Tip
     If you just want to resize or rescale an input raster, you can use RS_Resample(raster: Raster, widthOrScale: Double, heightOrScale: Double, useScale: Boolean, algorithm: String)
+
+For more information about ScaleX, ScaleY, SkewX, SkewY, please refer to the [Affine Transformations](Raster-affine-transformation.md) section.
+
 Format:
 
 ```sql
@@ -1830,6 +1843,8 @@ Output:
 Introduction: Sets the Georeference information of an object in a single call. Accepts inputs in `GDAL` and `ESRI` format.
 Default format is `GDAL`. If all 6 parameters are not provided then will return null.
 
+For more information about ScaleX, ScaleY, SkewX, SkewY, please refer to the [Affine Transformations](Raster-affine-transformation.md) section.
+
 Format:
 
 ```

docs/api/sql/Raster-visualizer.md

@@ -58,6 +58,9 @@ Output:
 Example:
 
 ```python
+from sedona.raster_utils.SedonaUtils import SedonaUtils
+# Or from sedona.spark import *
+
 df = sedona.read.format('binaryFile').load(DATA_DIR + 'raster.tiff').selectExpr("RS_FromGeoTiff(content) as raster")
 htmlDF = df.selectExpr("RS_AsImage(raster, 500) as raster_image")
 SedonaUtils.display_image(htmlDF)