Spatial phase I: Layer

Cargo.toml

@@ -62,6 +62,10 @@ proptest = "1.4"
 # Color interpolation
 palette = "0.7"
 
+# Spatial
+geozero = { version = "0.14", default-features = false }
+hex = "0.4"
+
 # Utilities
 regex = "1.10"
 chrono = "0.4"

doc/ggsql.xml

@@ -142,6 +142,7 @@
       <item>arrow</item>
       <item>rule</item>
       <item>errorbar</item>
+      <item>spatial</item>
     </list>
 
     <!-- Aesthetics -->
@@ -188,6 +189,7 @@
       <!-- Specialty aesthetics -->
       <item>slope</item>
       <item>intercept</item>
+      <item>geometry</item>
       <!-- Facet aesthetics -->
       <item>panel</item>
       <item>row</item>

doc/syntax/index.qmd

@@ -33,6 +33,7 @@ There are many different layers to choose from when visualising your data. Some
 - [`boxplot`](layer/type/boxplot.qmd) displays continuous variables as 5-number summaries.
 - [`errorbar`](layer/type/errorbar.qmd) a line segment with hinges at the endpoints.
 - [`smooth`](layer/type/smooth.qmd) a trendline that follows the data shape.
+- [`spatial`](layer/type/spatial.qmd) simple features from geometry.
 
 ### Position adjustments
 - [`stack`](layer/position/stack.qmd) places objects with a shared baseline on top of each other.

doc/syntax/layer/type/spatial.qmd

@@ -0,0 +1,84 @@
+---
+title: "Spatial"
+---
+
+> Layers are declared with the [`DRAW` clause](../../clause/draw.qmd). Read the documentation for this clause for a thorough description of how to use it.
+
+The spatial layer is used to render geographic geometries consisting of polygons, lines and points used to make maps like choropleths.
+It differs from other layers in that uses a special [simple features](https://en.wikipedia.org/wiki/Simple_Features) geometry column that defines the shapes.
+
+## Aesthetics
+The following aesthetics are recognised by the spatial layer.
+
+### Required
+* `geometry`: a column of simple features.
+
+Note that the `geometry` column is required, but an attempt is made to detect such a column automatically.
+In practise, this mapping does not often need to be declared.
+
+### Optional
+* `stroke` The colour of the lines.
+* `fill` The colour of the inner area.
+* `colour` Shorthand for setting `stroke` and `fill` simultaneously.
+* `opacity` The opacity of colours.
+* `linewidth` The width of the lines.
+* `linetype` The dash pattern of the line.
+
+## Settings
+The spatial layer has no additional settings.
+
+## Data transformation
+The spatial layer transforms the `geometry` column to [Well-Known Binary](https://libgeos.org/specifications/wkb/).
+
+## Orientation
+The spatial layer has no orientations.
+
+## Examples
+
+Note that depending on your reader, you may need to activate modules for spatial analysis.
+
+```{ggsql}
+-- For example, for DuckDB, one could use:
+INSTALL spatial;
+LOAD spatial;
+```
+
+A basic map of the world using built-in data.
+Note that the geometry column is automatically detected.
+
+```{ggsql}
+VISUALISE FROM ggsql:world
+  DRAW spatial
+```
+
+If the geometry column isn't automatically detected —for example because it has a non-standard name— you may need to declare the mapping explicitly.
+
+```{ggsql}
+SELECT geom AS foo FROM ggsql:world
+VISUALISE
+  DRAW spatial MAPPING foo AS geometry
+```
+
+Filtering on other columns.
+
+```{ggsql}
+VISUALISE FROM ggsql:world
+  DRAW spatial FILTER continent == 'Asia'
+```
+
+Filtering based on spatial operations.
+
+```{ggsql}
+VISUALISE FROM ggsql:world
+  DRAW spatial 
+  FILTER ST_Intersects(geom, ST_MAkeEnvelope(-20.0, -35.0, 55.0, 38.0))
+```
+
+Make a choropleth map by mapping a variable to a fill aesthetic.
+
+```{ggsql}
+VISUALISE FROM ggsql:world
+  DRAW spatial 
+    MAPPING population AS fill
+    SETTING opacity => 1
+```

ggsql-vscode/syntaxes/ggsql.tmLanguage.json

@@ -269,7 +269,7 @@
         {
           "comment": "Specialty and computed aesthetics",
           "name": "support.type.aesthetic.ggsql",
-          "match": "\\b(weight|coef|intercept|offset|density|count|intensity)\\b"
+          "match": "\\b(weight|coef|intercept|offset|density|count|intensity|geometry)\\b"
         },
         {
           "comment": "Facet aesthetics",
@@ -320,7 +320,7 @@
         {
           "comment": "Geom types from grammar.js",
           "name": "support.type.geom.ggsql",
-          "match": "\\b(point|line|path|bar|col|area|tile|polygon|ribbon|histogram|density|smooth|boxplot|violin|text|label|segment|arrow|rule|errorbar)\\b"
+          "match": "\\b(point|line|path|bar|col|area|tile|polygon|ribbon|histogram|density|smooth|boxplot|violin|text|label|segment|arrow|rule|errorbar|spatial)\\b"
         },
         { "include": "#common-clause-patterns" }
       ]
@@ -334,7 +334,7 @@
       "patterns": [
         {
           "name": "support.type.geom.ggsql",
-          "match": "\\b(point|line|path|bar|col|area|tile|polygon|ribbon|histogram|density|smooth|boxplot|violin|text|label|segment|arrow|rule|errorbar)\\b"
+          "match": "\\b(point|line|path|bar|col|area|tile|polygon|ribbon|histogram|density|smooth|boxplot|violin|text|label|segment|arrow|rule|errorbar|spatial)\\b"
         },
         { "include": "#common-clause-patterns" }
       ]

src/Cargo.toml

@@ -40,6 +40,9 @@ bytes = { workspace = true }
 # Writers
 plotters = { workspace = true, optional = true }
 
+# Spatial
+geozero = { workspace = true, optional = true, features = ["with-wkb", "with-geojson"] }
+
 # Serialization
 serde.workspace = true
 serde_json.workspace = true
@@ -64,13 +67,14 @@ tempfile = "3.8"
 ureq = "3"
 
 [features]
-default = ["duckdb", "sqlite", "vegalite", "ipc", "parquet", "builtin-data", "odbc"]
+default = ["duckdb", "sqlite", "vegalite", "ipc", "parquet", "builtin-data", "odbc", "spatial"]
 ipc = []
 duckdb = ["dep:duckdb"]
 parquet = ["dep:parquet"]
 postgres = ["dep:postgres"]
 sqlite = ["dep:rusqlite"]
 odbc = ["dep:odbc-api", "dep:toml_edit"]
+spatial = ["dep:geozero"]
 vegalite = []
 ggplot2 = []
 builtin-data = []