You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sedona.apache.org by ji...@apache.org on 2024/04/28 01:02:23 UTC
(sedona) branch fix-docs updated (6365680b8 -> 2bde0069b)
This is an automated email from the ASF dual-hosted git repository.
jiayu pushed a change to branch fix-docs
in repository https://gitbox.apache.org/repos/asf/sedona.git
from 6365680b8 Update SedonaSnow docs
new da72b53b6 Add affine transformation, SedonaUtils
new 2bde0069b Fix linter
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
docs/api/sql/DataFrameAPI.md | 8 ++--
docs/api/sql/Raster-affine-transformation.md | 64 ++++++++++++++++++++++++++++
docs/api/sql/Raster-loader.md | 12 +++---
docs/api/sql/Raster-operators.md | 19 ++++++++-
docs/api/sql/Raster-visualizer.md | 3 ++
docs/api/sql/Raster-writer.md | 2 +
mkdocs.yml | 1 +
7 files changed, 99 insertions(+), 10 deletions(-)
create mode 100644 docs/api/sql/Raster-affine-transformation.md
(sedona) 02/02: Fix linter
Posted by ji...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jiayu pushed a commit to branch fix-docs
in repository https://gitbox.apache.org/repos/asf/sedona.git
commit 2bde0069ba6969da81cbe13ced4326f87aecd736
Author: Jia Yu <ji...@apache.org>
AuthorDate: Sat Apr 27 18:02:13 2024 -0700
Fix linter
---
docs/api/sql/Raster-affine-transformation.md | 1 +
1 file changed, 1 insertion(+)
diff --git a/docs/api/sql/Raster-affine-transformation.md b/docs/api/sql/Raster-affine-transformation.md
index 53160d0aa..b7c93f890 100644
--- a/docs/api/sql/Raster-affine-transformation.md
+++ b/docs/api/sql/Raster-affine-transformation.md
@@ -15,6 +15,7 @@ Affine transformations can be represented as a matrix operation. In two-dimensio
```
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.
(sedona) 01/02: Add affine transformation, SedonaUtils
Posted by ji...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jiayu pushed a commit to branch fix-docs
in repository https://gitbox.apache.org/repos/asf/sedona.git
commit da72b53b61ac3d4b6107fc0a1baebcf378848a27
Author: Jia Yu <ji...@apache.org>
AuthorDate: Sat Apr 27 18:01:11 2024 -0700
Add affine transformation, SedonaUtils
---
docs/api/sql/DataFrameAPI.md | 8 ++--
docs/api/sql/Raster-affine-transformation.md | 63 ++++++++++++++++++++++++++++
docs/api/sql/Raster-loader.md | 12 +++---
docs/api/sql/Raster-operators.md | 19 ++++++++-
docs/api/sql/Raster-visualizer.md | 3 ++
docs/api/sql/Raster-writer.md | 2 +
mkdocs.yml | 1 +
7 files changed, 98 insertions(+), 10 deletions(-)
diff --git a/docs/api/sql/DataFrameAPI.md b/docs/api/sql/DataFrameAPI.md
index 25409856c..aaa5b9044 100644
--- a/docs/api/sql/DataFrameAPI.md
+++ b/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:
diff --git a/docs/api/sql/Raster-affine-transformation.md b/docs/api/sql/Raster-affine-transformation.md
new file mode 100644
index 000000000..53160d0aa
--- /dev/null
+++ b/docs/api/sql/Raster-affine-transformation.md
@@ -0,0 +1,63 @@
+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.
diff --git a/docs/api/sql/Raster-loader.md b/docs/api/sql/Raster-loader.md
index 713d480e8..67fd76c02 100644
--- a/docs/api/sql/Raster-loader.md
+++ b/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):
diff --git a/docs/api/sql/Raster-operators.md b/docs/api/sql/Raster-operators.md
index b1847c188..34fab567e 100644
--- a/docs/api/sql/Raster-operators.md
+++ b/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:
```
diff --git a/docs/api/sql/Raster-visualizer.md b/docs/api/sql/Raster-visualizer.md
index 7b756bd9a..7dc20a94f 100644
--- a/docs/api/sql/Raster-visualizer.md
+++ b/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)
diff --git a/docs/api/sql/Raster-writer.md b/docs/api/sql/Raster-writer.md
index 06e61f57b..c7c03c442 100644
--- a/docs/api/sql/Raster-writer.md
+++ b/docs/api/sql/Raster-writer.md
@@ -247,6 +247,8 @@ Since: `v1.5.0`
```
If a raster is provided with anyone of these properties then IllegalArgumentException is thrown.
+For more information about ScaleX, ScaleY, SkewX, SkewY, please refer to the [Affine Transformations](Raster-affine-transformation.md) section.
+
SQL Example
```sql
diff --git a/mkdocs.yml b/mkdocs.yml
index 369d31dc2..3e3408c3f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -77,6 +77,7 @@ nav:
- Raster operators: api/sql/Raster-operators.md
- Raster map algebra: api/sql/Raster-map-algebra.md
- Raster visualization: api/sql/Raster-visualizer.md
+ - Raster affine transformation: api/sql/Raster-affine-transformation.md
- Parameter: api/sql/Parameter.md
- RDD (core):
- Scala/Java doc: api/java-api.md