From 2efbb7b5a1b76c62e6a0e926b0744645cc830254 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Sun, 30 Jun 2024 22:09:06 -0400 Subject: [PATCH 1/7] Write some copy for CRS + winding order pages --- docs/src/explanations/crs.md | 14 ++++++++++++++ docs/src/explanations/winding_order.md | 11 +++++++++++ 2 files changed, 25 insertions(+) diff --git a/docs/src/explanations/crs.md b/docs/src/explanations/crs.md index e69de29bb..52efc5f43 100644 --- a/docs/src/explanations/crs.md +++ b/docs/src/explanations/crs.md @@ -0,0 +1,14 @@ +# Coordinate Reference Systems + +[Coordinate Reference System](https://en.wikipedia.com/Spatial_reference_system)s are simply descriptions of what some set of coordinates really mean in reference to some standard. + +In a mathematical sense, coordinate reference systems can be thought of defining a _space_, with associated transformations from and to latitude-longitude space (plate-carree, long-lat, WGS84) which is the default CRS we assume. + +## Geographic CRS + +If a CRS is _geographic_, that means that it refers to coordinates on a sphere. Such coordinates should ideally be handled using a spherical geometry library like Google's s2. GeometryOps does not currently handle spherical geometry computations except in special cases ([`perimeter`](@ref), [`GeodesicSegments`](@ref) in `segmentize`, [`GeodesicDistance`](@ref)). + +A non-geographic CRS is assumed to be in Cartesian space. + +## Projected CRS + diff --git a/docs/src/explanations/winding_order.md b/docs/src/explanations/winding_order.md index e69de29bb..060c79a5a 100644 --- a/docs/src/explanations/winding_order.md +++ b/docs/src/explanations/winding_order.md @@ -0,0 +1,11 @@ +# Winding order + +Winding order refers specifically to the "direction" that a polygon's rings go in. This has several different and conflicting definitions, which you can find some discussion of in the following articles: +- [GIS Stack Exchange: Order of polygon vertices?](https://gis.stackexchange.com/questions/119150/order-of-polygon-vertices-in-general-gis-clockwise-or-counterclockwise) +- [ObservableHQ winding order article](https://observablehq.com/@d3/winding-order) + +GeometryOps assumes that polygon exteriors are clockwise and interiors are counterclockwise. However, most algorithms are agnostic to winding order, and instead rely on the GeoInterface `getexterior` and `gethole` functions to distinguish holes from exteriors. Notably, _most_ GIS implementations agree that polygons can have only one exterior but several holes. + +## What other libraries do + +TODO: Markdown table with a bunch of libraries/standards, their winding orders, and references. \ No newline at end of file From faa0217b800a36ad20b0aba42281490d84a2ed68 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Sun, 30 Jun 2024 22:11:33 -0400 Subject: [PATCH 2/7] Add those files to the docs --- docs/make.jl | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/make.jl b/docs/make.jl index 80f6b6246..b7abe0078 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -101,6 +101,12 @@ makedocs(; "Explanations" => [ "Paradigms" => "explanations/paradigms.md", "Peculiarities" => "explanations/peculiarities.md", + "GIS things" => [ + "CRS" => "explanations/crs.md", + "Winding order" => "explanations/winding_order.md", + # "Geometry types and lack of support" => "explanations/well_known_geometry.md", # TODO write this + # "When you should use LibGEOS or ArchGDAL" => "explanations/notgeometryops.md", # TODO write this + ], ], "Source code" => literate_pages, ], From fff2c72b680ada7b2ad8448e5497caf24f8f1368 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Sun, 30 Jun 2024 22:11:44 -0400 Subject: [PATCH 3/7] Basic skeleton for a random walk through GeometryOps --- .../random_walk_through_geometryops.jl | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 docs/src/experiments/random_walk_through_geometryops.jl diff --git a/docs/src/experiments/random_walk_through_geometryops.jl b/docs/src/experiments/random_walk_through_geometryops.jl new file mode 100644 index 000000000..fecee6c00 --- /dev/null +++ b/docs/src/experiments/random_walk_through_geometryops.jl @@ -0,0 +1,15 @@ +import GeometryOps as GO +# ecosystem packages we'll need +import GeoInterface as GI +using CairoMakie # for plotting + + +#= +## LibGEOS extension +> If you can't do it yourself, then use something else. +TODO: chatgpt this quote + +=# +import LibGEOS # we will never actually call LibGEOS here + +GO.buffer(poly, 1) |> Makie.poly From bdcafc62a1062dd51bdbebb93667714ef1606692 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Sun, 30 Jun 2024 22:20:20 -0400 Subject: [PATCH 4/7] Describe CRS formats --- docs/src/explanations/crs.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/src/explanations/crs.md b/docs/src/explanations/crs.md index 52efc5f43..4160cd6d9 100644 --- a/docs/src/explanations/crs.md +++ b/docs/src/explanations/crs.md @@ -12,3 +12,19 @@ A non-geographic CRS is assumed to be in Cartesian space. ## Projected CRS +Projected CRS are generally treated as Cartesian. + +## Ways to describe CRS + +The geographic community seems to be standardizing on [Well Known Text]() as the "best" CRS identifier. This is quite verbose, but is unambiguous and easy enough to read once you get the hang of it. + +To indicate the type of CRS definition you're using, you can wrap a string in its corresponding `GeoFormatTypes` type. + +## CRS format table + +- Proj-strings: a brief but powerful way to describe a set of known CRS + some transformations to them. Really useful when plotting and interactively adjusting CRS. See the Proj docs. +- EPSG codes: a short way to refer to a known coordinate system in the database of the European Petroleum Survey Group. Example: `EPSG:4236`. +- ESRI codes: similar to EPSG codes, but referring to CRS known to ESRI instead. Example: `ESRI:12345` +- ProjJSON +- KML +- Mapinfo CoordSys \ No newline at end of file From 9228fb38f0d06b0284529d4833ec8ec2e4c2b07c Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Sun, 30 Jun 2024 22:29:30 -0400 Subject: [PATCH 5/7] Add a bit more description to crs --- docs/src/explanations/crs.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/src/explanations/crs.md b/docs/src/explanations/crs.md index 4160cd6d9..02361d75f 100644 --- a/docs/src/explanations/crs.md +++ b/docs/src/explanations/crs.md @@ -16,15 +16,17 @@ Projected CRS are generally treated as Cartesian. ## Ways to describe CRS +Completely separate from the _meaning_ of the CRS is the way you describe or define it. There are a [dizzying array of ways](@ref crs-format-table) to do this, but two easy ones are Proj strings and Well Known Text. + The geographic community seems to be standardizing on [Well Known Text]() as the "best" CRS identifier. This is quite verbose, but is unambiguous and easy enough to read once you get the hang of it. To indicate the type of CRS definition you're using, you can wrap a string in its corresponding `GeoFormatTypes` type. -## CRS format table +## [CRS format table](@id crs-format-table) - Proj-strings: a brief but powerful way to describe a set of known CRS + some transformations to them. Really useful when plotting and interactively adjusting CRS. See the Proj docs. - EPSG codes: a short way to refer to a known coordinate system in the database of the European Petroleum Survey Group. Example: `EPSG:4236`. - ESRI codes: similar to EPSG codes, but referring to CRS known to ESRI instead. Example: `ESRI:12345` -- ProjJSON -- KML -- Mapinfo CoordSys \ No newline at end of file +- ProjJSON: a more structured way to express Proj-strings using JSON. +- KML: key-markup language, an XML extension, used in web feature services +- Mapinfo CoordSys: \ No newline at end of file From c9ec0f69ff3aebd6bbe43d5435bdd4ad90b493f2 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Mon, 1 Jul 2024 14:19:12 -0400 Subject: [PATCH 6/7] Add more bones to the skeleton --- .../random_walk_through_geometryops.jl | 33 ++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/docs/src/experiments/random_walk_through_geometryops.jl b/docs/src/experiments/random_walk_through_geometryops.jl index fecee6c00..f9013e876 100644 --- a/docs/src/experiments/random_walk_through_geometryops.jl +++ b/docs/src/experiments/random_walk_through_geometryops.jl @@ -1,7 +1,38 @@ +#= +# A random walk through [GeometryOps.jl](https://juliageo.org/GeometryOps.jl) + +In this tutorial, we'll take a random walk through GeometryOps and its capabilities, just to show off what it can do. + + +=# import GeometryOps as GO -# ecosystem packages we'll need +## ecosystem packages we'll need import GeoInterface as GI using CairoMakie # for plotting +# + +#= +## The `apply` interface + +- my_coord_op +- my_linestring_op +=# + + +#= +## The `applyreduce` interface +This one is arguably more useful for daily tasks. + +- my_centroid on a linestring/ring level +- + +=# + +#= +## The `fix` interface +- Choose your fixes +- How to make a new fix (antimeridian cutting) +=# #= From 101d7b453d664ab0348650f3b5be5be86def3a13 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Mon, 1 Jul 2024 15:06:12 -0400 Subject: [PATCH 7/7] Fix wikipedia link --- docs/src/explanations/crs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/explanations/crs.md b/docs/src/explanations/crs.md index 02361d75f..60d722d33 100644 --- a/docs/src/explanations/crs.md +++ b/docs/src/explanations/crs.md @@ -1,6 +1,6 @@ # Coordinate Reference Systems -[Coordinate Reference System](https://en.wikipedia.com/Spatial_reference_system)s are simply descriptions of what some set of coordinates really mean in reference to some standard. +[Coordinate Reference System](https://en.wikipedia.com/wiki/Spatial_reference_system)s are simply descriptions of what some set of coordinates really mean in reference to some standard. In a mathematical sense, coordinate reference systems can be thought of defining a _space_, with associated transformations from and to latitude-longitude space (plate-carree, long-lat, WGS84) which is the default CRS we assume. @@ -29,4 +29,4 @@ To indicate the type of CRS definition you're using, you can wrap a string in it - ESRI codes: similar to EPSG codes, but referring to CRS known to ESRI instead. Example: `ESRI:12345` - ProjJSON: a more structured way to express Proj-strings using JSON. - KML: key-markup language, an XML extension, used in web feature services -- Mapinfo CoordSys: \ No newline at end of file +- Mapinfo CoordSys: