Derotation documentation and examples

docs/make.jl

@@ -34,6 +34,7 @@ makedocs(;
                 "Is it in a GeoRegion?"        => "tutorials/using/isin.md",
                 "Is it on a GeoRegion?"        => "tutorials/using/ison.md",
                 "Equivalence in GeoRegions.jl" => "tutorials/using/isequal.md",
+                "Derotation of Coordinates"    => "tutorials/using/derotate.md",
             ],
             "GeoRegions.jl for Projects"   => [
                 "Setting Up"        => "tutorials/projects/setup.md",

docs/src/tutorials/using/derotate.md

@@ -1,2 +1,105 @@
 # Derotating Coordinates around a given GeoRegion
 
+Using the rotation and centroid properties of a GeoRegion, we are able to perform derotation of coordinates about the centroid of a given GeoRegion, allowing us to project longitude/latitude coordinates and even data into a x/y-cartesian coordinate system.
+
+Let us now setup the example
+
+```@example derotate
+using GeoRegions
+using DelimitedFiles
+using CairoMakie
+
+download("https://raw.githubusercontent.com/natgeo-wong/GeoPlottingData/main/coastline_resl.txt","coast.cst")
+coast = readdlm("coast.cst",comments=true)
+clon  = coast[:,1]
+clat  = coast[:,2]
+nothing
+```
+
+Let us create a custom GeoRegion around the Sumatra island, with a defined rotation of -45º:
+
+```@example derotate
+geo = GeoRegion([104.5, 92.5, 97, 109, 104.5],[-8.5, 3.5, 8, -4, -8.5],rotation=-45)
+```
+
+For more information about creating custom GeoRegions, see [here]() and [here]().
+
+## Derotating the GeoRegion itself
+
+First, let us retrieve the normal coordinates of the GeoRegion and plot them
+
+```@example derotate
+lon,lat = coordinates(geo)
+lonc,latc = geo.geometry.centroid
+fig = Figure()
+ax = Axis(
+    fig[1,1],width=375,height=375,
+    limits=(89,113,-12,12)
+)
+lines!(ax,clon,clat,color=:black,linewidth=3)
+lines!(ax,lon,lat,linewidth=5)
+scatter!(ax,lonc,latc,markersize=20)
+resize_to_layout!(fig)
+fig
+```
+
+We can pass the arguments `derotate` and `rotation` to the `coordinates()` function in order to obtain the derotated shape coordinates, as follows:
+
+```@example derotate
+rlon1,rlat1 = coordinates(geo,derotate=true)
+rlon2,rlat2 = coordinates(geo,derotate=true,rotation=0)
+rlon3,rlat3 = coordinates(geo,derotate=true,rotation=-30)
+rlon4,rlat4 = coordinates(geo,derotate=true,rotation=-45)
+nothing
+```
+
+## Derotation of Longitude/Latitude Coordinates
+
+Similarly, we can also derotate a given set of coordinates around the centroid of the GeoRegion, based on our estimate in `geo.θ` as to how much the GeoRegion was originally rotated.
+
+```@example derotate
+rclon1,rclat1 = derotatecoordinates(clon,clat,geo,derotate=true)
+rclon2,rclat2 = derotatecoordinates(clon,clat,geo,derotate=true,rotation=0)
+rclon3,rclat3 = derotatecoordinates(clon,clat,geo,derotate=true,rotation=-30)
+rclon4,rclat4 = derotatecoordinates(clon,clat,geo,derotate=true,rotation=-45)
+nothing
+```
+
+## Visualization of the Derotation
+
+Now, let's visualize these derotated coordinates and shapes
+
+```@example derotate
+fig = Figure()
+
+ax1 = Axis(
+    fig[1,1],width=375,height=375,
+    limits=(-2000,2000,-2000,2000)
+)
+lines!(ax1,rclon1,rclat1,color=:black,linewidth=3)
+lines!(ax1,rlon1,rlat1,linewidth=5)
+
+ax2 = Axis(
+    fig[1,2],width=375,height=375,
+    limits=(-2000,2000,-2000,2000)
+)
+lines!(ax2,rclon2,rclat2,color=:black,linewidth=3)
+lines!(ax2,rlon2,rlat2,linewidth=5)
+
+ax3 = Axis(
+    fig[2,1],width=375,height=375,
+    limits=(-2000,2000,-2000,2000)
+)
+lines!(ax3,rclon3,rclat3,color=:black,linewidth=3)
+lines!(ax3,rlon3,rlat3,linewidth=5)
+
+ax4 = Axis(
+    fig[2,2],width=375,height=375,
+    limits=(-2000,2000,-2000,2000)
+)
+lines!(ax4,rclon4,rclat4,color=:black,linewidth=3)
+lines!(ax4,rlon4,rlat4,linewidth=5)
+
+resize_to_layout!(fig)
+fig
+```

src/GeoRegions.jl

@@ -131,7 +131,7 @@ include("georegions/tables.jl")
 include("is/isequal.jl")
 include("is/isgeo.jl")
 include("is/isgeoshape.jl")
-include("is/isiD.jl")
+include("is/isID.jl")
 include("is/isin.jl")
 include("is/ison.jl")
 

src/georegions/derotate.jl

@@ -66,7 +66,7 @@ function derotatecoordinates!(
     lon :: Vector{<:Real},
     lat :: Vector{<:Real},
     geo :: GeoRegion;
-    rotation :: Real = geo.θ
+    rotation :: Real = 0
 )
 
     npnts = length(lon)
@@ -105,7 +105,7 @@ Returns
 function derotatecoordinates(
     pnts :: Vector{Point2{<:Real}},
     geo  :: GeoRegion;
-    rotation :: Real = geo.θ
+    rotation :: Real = 0
 )
 
     npnts = length(pnts)
@@ -149,12 +149,12 @@ function derotatepoint(
     lon :: Real,
     lat :: Real,
     geo :: GeoRegion;
-    rotation :: Real = geo.θ
+    rotation :: Real = 0
 )
 
     Xc,Yc = geo.geometry.centroid
     ir = haversine((lon,lat),(Xc,Yc))
-    iθ = atand(lat-Yc,lon-Xc) - rotation
+    iθ = atand(lat-Yc,lon-Xc) - (geo.θ - rotation)
 
     return ir * cosd(iθ), ir * sind(iθ)
 
@@ -186,12 +186,12 @@ Returns
 function derotatepoint(
     pnt :: Point2{<:Real},
     geo :: GeoRegion;
-    rotation :: Real = geo.θ
+    rotation :: Real = 0
 )
 
     Xc,Yc = geo.geometry.centroid
     ir = haversine((pnt[1],pnt[2]),(Xc,Yc))
-    iθ = atand(pnt[1]-Yc,pnt[2]-Xc) - rotation
+    iθ = atand(pnt[1]-Yc,pnt[2]-Xc) - (geo.θ - rotation)
 
     return ir * cosd(iθ),ir * sind(iθ)