Documentation improvements (#170)

asinghvi17 · web-flow · commit a741edcea2be · 2025-05-04T21:44:02.000-04:00
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -36,6 +36,7 @@ Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
 MakieThemes = "e296ed71-da82-5faf-88ab-0034a9761098"
 Measurements = "eff96d63-e80a-5855-80a2-b1b0885c5ab7"
 MonteCarloMeasurements = "0987c9cc-fe09-11e8-30f0-b96dd679fdca"
+Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 MultiFloats = "bdf0d083-296b-4888-a5b6-7498122e68a5"
 NaturalEarth = "436b0209-26ab-4e65-94a9-6526d86fea76"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
diff --git a/docs/make.jl b/docs/make.jl
@@ -64,6 +64,14 @@ function current_module_from_paths(source_path, relative_path)
         return "GeometryOps"
     elseif endswith(source_path, "ext")
         return "Base.get_extension(GeometryOps, :$(splitpath(relative_path)[1]))"
+    elseif contains(relative_path, "SpatialTreeInterface")
+        return "GeometryOps.SpatialTreeInterface"
+    elseif contains(relative_path, "LoopStateMachine")
+        return "GeometryOps.LoopStateMachine"
+    elseif contains(relative_path, "NaturalIndexing")
+        return "GeometryOps.NaturalIndexing"
+    else
+        return "GeometryOps" # default to GO as a last resort
     end
 end
 
@@ -111,7 +119,8 @@ withenv("JULIA_DEBUG" => "Literate") do # allow Literate debug output to escape
 end
 
 # Now that the Literate stuff is done, we also download the call notes from HackMD:
-download("https://hackmd.io/kpIqAR8YRJOZQDJjUKVAUQ/download", joinpath(@__DIR__, "src", "call_notes.md"))
+# download("https://hackmd.io/kpIqAR8YRJOZQDJjUKVAUQ/download", joinpath(@__DIR__, "src", "call_notes.md"))
+# This is a bit unreliable especially at high volumes of traffic, so we don't call this for now.
 
 # Finally, make the docs!
 makedocs(;
@@ -131,8 +140,15 @@ makedocs(;
         ],
         "Explanations" => [
             "Paradigms" => "explanations/paradigms.md",
-            "Peculiarities" => "explanations/peculiarities.md",
             "Manifolds" => "explanations/manifolds.md",
+            "Peculiarities" => "explanations/peculiarities.md",
+            "GIS terminology" => [
+                "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
+            ],
+            "Developer docs" => "explanations/devdocs.md",
         ],
         "Source code" => literate_pages,
     ],
diff --git a/docs/src/experiments/random_walk_through_geometryops.jl b/docs/src/experiments/random_walk_through_geometryops.jl
@@ -0,0 +1,46 @@
+#=
+# 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
+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)
+=#
+
+
+#=
+## 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
diff --git a/docs/src/explanations/crs.md b/docs/src/explanations/crs.md
@@ -0,0 +1,32 @@
+# Coordinate Reference Systems
+
+[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.
+
+## 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 (e.g., [`segmentize`](@ref) with the [`Geodesic`](@ref) manifold).
+
+A non-geographic CRS is assumed to be in Cartesian space.
+
+## Projected CRS
+
+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](@id crs-format-table)
+<!-- TODO: convert this to a Markdown 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: a more structured way to express Proj-strings using JSON.  
+- KML: key-markup language, an XML extension, used in web feature services
+- Mapinfo CoordSys: 
diff --git a/docs/src/explanations/devdocs.md b/docs/src/explanations/devdocs.md
@@ -0,0 +1,30 @@
+# Developer documentation
+
+This is mostly some notes about how GeometryOps is structured, geared towards developers 
+and folks interested in learning about the internals of GeometryOps.
+
+## Coding standards
+
+Every source file is also compiled into the documentation via Literate.jl, so 
+it should have a Markdown section at the top that describes what that file does.  
+
+For most cases, each function has a single file, and so that file should:
+- have a header which is the capitalized name of that function
+- have a docstring that is visible when you first load the page (collapsed or opened is up to you)
+- have some visual examples, rendered in the documentation, of what that function does!  
+  Since this is geometry, it's very easy to plot with e.g Makie.
+
+We also request that you define [`Algorithm`](@ref) types and use those to define the behaviour of your function.  We don't have an operations interface yet (coming soon!) but that should be done as well!
+
+## Geometry representation
+
+In Julia there is no one fixed geometry representation; instead we can use any memory layout in a standardized way via [GeoInterface.jl](https://github.com/JuliaGeo/GeoInterface.jl).  This means
+iterating over `enumerate(GI.getpoint(geom))` rather than `1:length(geom)`, and similar. 
+
+However, sometimes you want a fast, in-Julia geometry with known layout.  For example, `getpoint` on 
+GEOS or GDAL geoms is quite slow because you have to make a `ccall` with a pointer.  For cases like these
+you can simply use `GO.tuples` to convert geometries to [GeoInterface wrapper geometries](https://juliageo.org/GeoInterface.jl/dev/guides/defaults/#Wrapper-types) that wrap (usually) 2-tuple points in vectors.
+
+When returning geometries you can generally return any GeoInterface geometry but should prefer such
+GeoInterface tuple geometries as mentioned above.
+
diff --git 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.
diff --git a/docs/src/tutorials/creating_geometry.md b/docs/src/tutorials/creating_geometry.md
@@ -57,7 +57,9 @@ fig
 x = [-5, -5, 5, 5];
 y = [-5, 5, 5, -5];
 multipoint = GI.MultiPoint(GI.Point.(zip(x, y)));
-plot!(ax, multipoint; marker = '☁', markersize = 30)
+# TODO: GeoInterfaceMakie.jl can't plot multipoints due to breaking changes
+# in Makie.jl.  We should fix that.
+plot!(ax, multipoint.geom; marker = '☁', markersize = 30)
 fig
 ````
 
diff --git a/docs/src/tutorials/spatial_joins.md b/docs/src/tutorials/spatial_joins.md
@@ -1,4 +1,4 @@
-# Spatial joins
+# [Spatial joins](@id tutorial-spatial-joins)
 
 Spatial joins are [table joins](https://www.geeksforgeeks.org/sql-join-set-1-inner-left-right-and-full-joins/) which are based not on equality, but on some predicate ``p(x, y)``, which takes two geometries, and returns a value of either `true` or `false`.  For geometries, the [`DE-9IM`](https://en.wikipedia.org/wiki/DE-9IM) spatial relationship model is used to determine the spatial relationship between two geometries.  
 
diff --git a/ext/GeometryOpsFlexiJoinsExt/GeometryOpsFlexiJoinsExt.jl b/ext/GeometryOpsFlexiJoinsExt/GeometryOpsFlexiJoinsExt.jl
@@ -1,3 +1,12 @@
+# # FlexiJoins extension
+#=
+This is an extension on FlexiJoins.jl that provides spatial tree acceleration to join 
+arbitrary tables, using GeometryOps predicates.
+
+The implementation is specialized on GO predicates.
+
+See the [Spatial Joins tutorial](@ref tutorial-spatial-joins) for more information and for how to use this.
+=#
 module GeometryOpsFlexiJoinsExt
 
 using GeometryOps
diff --git a/ext/GeometryOpsLibGEOSExt/GeometryOpsLibGEOSExt.jl b/ext/GeometryOpsLibGEOSExt/GeometryOpsLibGEOSExt.jl
@@ -1,3 +1,7 @@
+# # LibGEOS extension
+
+# This is the main file for the LibGEOS extension of GeometryOps.
+
 module GeometryOpsLibGEOSExt
 
 import GeometryOps as GO, LibGEOS as LG
@@ -11,6 +15,9 @@ using GeometryOps
 # However, if you import those from another module (which you would with `all=true`),
 # that creates an ambiguity which causes a warning during precompile/load time.
 # In order to avoid this, we filter out these special functions.
+
+# This is kind of like ImportAll.jl but without the macro.  It only imports the functions
+# in names(GeometryOps; all=false).
 for name in filter(!in((:var"#eval", :eval, :var"#include", :include)), names(GeometryOps))
     @eval import GeometryOps: $name
 end
diff --git a/ext/GeometryOpsLibGEOSExt/buffer.jl b/ext/GeometryOpsLibGEOSExt/buffer.jl
@@ -1,3 +1,45 @@
+# # GEOS Buffer
+
+#=
+## What is GEOS buffer?
+
+The GEOS buffer function creates a new geometry that represents all points within
+a specified distance of the input geometry. This is useful for creating zones of
+influence, safety margins, or areas of interest around geometric features.
+
+For example, creating a buffer around a point:
+
+```@example buffer
+import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+# Create a point and buffer it
+point = GI.Point(0, 0)
+buffered = GO.buffer(GO.GEOS(), point, 1.0)  # 1 unit buffer
+```
+
+## Implementation
+
+The implementation uses GEOS's bufferWithStyle function through LibGEOS.jl.
+It supports various buffer styles:
+- Cap styles: round, flat, square
+- Join styles: round, mitre, bevel
+- Mitre limit for sharp corners
+
+Key features:
+- Configurable number of segments for curved parts (quadsegs)
+- Support for different end cap styles
+- Customizable join styles for corners
+- Adjustable mitre limit for sharp angles
+- Preserves CRS information
+- Works with any GeoInterface-compatible geometry
+
+The function handles the conversion between GeometryOps and GEOS geometries
+automatically, and wraps the result back in a GeoInterface-compatible format.
+=#
+
 const _GEOS_CAPSTYLE_LOOKUP = Dict{Symbol, LG.GEOSBufCapStyles}(
     :round => LG.GEOSBUF_CAP_ROUND,
     :flat => LG.GEOSBUF_CAP_FLAT,
diff --git a/ext/GeometryOpsLibGEOSExt/segmentize.jl b/ext/GeometryOpsLibGEOSExt/segmentize.jl
@@ -1,4 +1,5 @@
-# # Segmentize
+# # GEOS segmentize
+# This file implements [`segmentize`](@ref) using the [`GEOS`](@ref) algorithm.
 import GeometryOps: segmentize, apply
 
 #=
diff --git a/ext/GeometryOpsLibGEOSExt/simple_overrides.jl b/ext/GeometryOpsLibGEOSExt/simple_overrides.jl
@@ -1,8 +1,10 @@
 #=
 # Simple overrides
 This file contains simple overrides for GEOS, essentially only those
-functions which have direct counterparts in LG and only
+functions which have direct counterparts in LibGEOS and only
 require conversion before calling.
+
+They can all be invoked by calling `GO.$fname(GO.GEOS(), geom1, ...)`.
 =#
 # ## Polygon set operations
 # ### Difference
diff --git a/ext/GeometryOpsLibGEOSExt/simplify.jl b/ext/GeometryOpsLibGEOSExt/simplify.jl
@@ -1,4 +1,42 @@
-# Address potential ambiguities
+#=
+# GEOS simplify
+
+This file implements [`GO.simplify`](@ref) using the [`GEOS`](@ref) algorithm.
+
+You can pass the keyword `method` to GEOS, to choose between the `:TopologyPreserve` and `:DouglasPeucker` methods.
+
+The only other parameter required is `tol` which defines the simplification tolerance.
+
+## Example
+
+```@example geos-simplify
+import GeometryOps as GO, GeoInterface as GI
+import LibGEOS # activate the GEOS algorithm
+using GADM # get data
+using CairoMakie # to plot
+
+france = GI.geometry(GI.getfeature(GADM.get("FRA"), 1))
+
+simplified = GO.simplify(GO.GEOS(; tol = 1), france)
+
+f, a, p = lines(france; label = "Original")
+lines!(a, simplified; label = "Simplified")
+axislegend(a)
+f
+```
+
+You can also choose the TopologyPreserve method:
+
+```@example geos-simplify
+simplified = GO.simplify(GO.GEOS(; tol = 1, method = :TopologyPreserve), france)
+
+f, a, p = lines(france; label = "Original")
+lines!(a, simplified; label = "Topology preserving simplify")
+axislegend(a)
+f
+```
+
+=#
 GO._simplify(::GI.PointTrait, ::GO.GEOS, geom; kw...) = geom
 GO._simplify(::GI.MultiPointTrait, ::GO.GEOS, geom; kw...) = geom
 
diff --git a/ext/GeometryOpsProjExt/GeometryOpsProjExt.jl b/ext/GeometryOpsProjExt/GeometryOpsProjExt.jl
@@ -1,3 +1,6 @@
+# # Proj extension
+
+# This is the main module for the GeometryOps extension on Proj.jl.
 module GeometryOpsProjExt
 
 using GeometryOps, Proj
diff --git a/ext/GeometryOpsProjExt/reproject.jl b/ext/GeometryOpsProjExt/reproject.jl
@@ -1,3 +1,50 @@
+# # Reproject
+
+
+#=
+```@meta
+CollapsedDocStrings = true
+```
+
+```@docs; canonical=false
+GeometryOps.reproject
+```
+
+The reproject function transforms geometries from one coordinate reference system (CRS)
+to another using PROJ. This is essential for working with geospatial data from different
+sources that use different coordinate systems.
+
+For example, you might have data in WGS84 (EPSG:4326) that you want to display on a
+web map using Web Mercator (EPSG:3857):
+
+```@repl
+import GeometryOps as GO, GeoInterface as GI
+using GeoFormatTypes # for CRS types like EPSG
+point = (0, 0)  # Prime meridian, equator
+GO.reproject(point; source_crs=EPSG(4326), target_crs=EPSG(3857))
+GO.reproject(point, EPSG(4326), EPSG(3857)) # geom, source_crs, target_crs
+GO.reproject(GI.Point(point; crs = EPSG(4326)), EPSG(3857)) # if your geom has a crs, then you only need to pass target.
+```
+
+## Implementation
+
+The implementation uses PROJ's transformation capabilities through the [Proj.jl](https://github.com/JuliaGeo/Proj.jl) package.
+It supports:
+- 2D and 3D coordinates
+- Threaded operations for better performance
+- Automatic CRS detection from geometry metadata
+- Custom transformation contexts
+
+The function handles various input types for CRS specification:
+- GeoFormatTypes.GeoFormat
+- Proj.CRS
+- String representations
+- Nothing (automatic detection)
+
+For threaded operations, it creates separate PROJ contexts and transformations
+for each thread to ensure thread safety.
+=#
+
 import GeometryOps: GI, GeoInterface, reproject, apply, transform, _is3d, istrue,
     True, False, TaskFunctors, WithXY, WithXYZ
 import GeoFormatTypes
diff --git a/ext/GeometryOpsProjExt/segmentize.jl b/ext/GeometryOpsProjExt/segmentize.jl
diff --git a/ext/GeometryOpsTGGeometryExt/GeometryOpsTGGeometryExt.jl b/ext/GeometryOpsTGGeometryExt/GeometryOpsTGGeometryExt.jl
diff --git a/src/methods/area.jl b/src/methods/area.jl
diff --git a/src/methods/distance.jl b/src/methods/distance.jl
diff --git a/src/methods/polygonize.jl b/src/methods/polygonize.jl
diff --git a/src/transformations/simplify.jl b/src/transformations/simplify.jl
diff --git a/src/transformations/transform.jl b/src/transformations/transform.jl

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Spatial joins`
	`1`	`+# [Spatial joins](@id tutorial-spatial-joins)`
`2`	`2`
`3`	`3`	Spatial joins are [table joins](https://www.geeksforgeeks.org/sql-join-set-1-inner-left-right-and-full-joins/) which are based not on equality, but on some predicate ``p(x, y)``, which takes two geometries, and returns a value of either `true` or `false`. For geometries, the [`DE-9IM`](https://en.wikipedia.org/wiki/DE-9IM) spatial relationship model is used to determine the spatial relationship between two geometries.
`4`	`4`