geodetic 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c20a680d6ffe0e6a82f3a0b7e8f6b1a428baa951b7122c0be75079f667f1099
-  data.tar.gz: 28031d89b1a5705cc28f6ddc751034d982e51581544f44a1d46a8792d8fd0f50
+  metadata.gz: 542167ec9e7b27122d31d5287f967481dc9d0d4b293eaaaa349ca4203e2eb302
+  data.tar.gz: f544332a931f775df18ce4e0d2ed78e4d2619bbb946df6d287c8bc3a798d6c9f
 SHA512:
-  metadata.gz: 4c41de7eb8e8bdb61921dfca83310a2d5ed0978d9bd6f0f1d3f06ce33bd877070581c873396a33b80b40722ec741f93f5e80cf2afb0e90561f5a28d2dc6e7953
-  data.tar.gz: 8ce010a527e660a01fab3b93d8a9e4f90bceb688dd753a5a634cbf3d25ba3deaf2b8bc8038e8926767d8bd017a26e09074aa3be1d94df1813bc6407d56865ab0
+  metadata.gz: cca8fc5c8b38722ab95fecfeea576104c180352a9af854171858702d23a240368bef870b831c463601f06f6f04d76671aa8a5254edfc37880b3acef1aced476a
+  data.tar.gz: 29f289c88b14fcbe64091256d61afaa1752a4f405a5a3f88e55b966c7fbc50076c6db6a5e88bbe4f1e4840f3a424c88e37daf167acdca64b1872d81f8a2dcc01

data/CHANGELOG.md

@@ -8,6 +8,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 
+## [0.8.0] - 2026-03-11
+
+### Added
+
+- **Map adapter pattern** (`Geodetic::Map`) for rendering geodetic objects on maps with pluggable backends
+  - `Geodetic::Map::Base` — abstract adapter interface with `add(object, **style)` auto-dispatch by geometry type
+  - `Geodetic::Map::LibGdGis` — concrete adapter for raster PNG output via the `libgd-gis` gem
+  - `MapMethods` mixin — adds `add_to_map(map, **style)` to all coordinates, paths, segments, areas, and features
+  - Render block pattern: `map.render(path) { |gd_map| ... }` for custom GD drawing after adapter layers
+  - `gd_map` accessor for post-render access to the underlying `GD::GIS::Map`
+  - Accepts `BoundingBox` or `[west, south, east, north]` array for bbox
+  - Supports point, line, and polygon layers with style options (color, stroke, fill, width, label, icon, font, symbol, segments)
+- GEOS map rendering example (`examples/14_geos_map_rendering.rb`) — visualizes 8 GEOS operation categories (boolean intersection/difference, point/path buffering, convex hull, simplification, nearest points, prepared geometry containment) on a single raster map with distinct colors and an embedded legend
+- 28 new map adapter tests covering all geometry types, style handling, ENU/NED rejection, chaining, and LibGdGis bbox resolution
+- Documentation: `docs/reference/map-rendering.md` (architecture, usage, style options, color format, prerequisites)
+
+### Changed
+
+- Refactored `examples/05_map_rendering/demo.rb` to use the new `Map::LibGdGis` adapter instead of raw `GD::GIS::Map` calls
+- Updated `docs/reference/geos-acceleration.md` with reference to example 14
+- Updated `examples/README.md` with example 14 description
+- Updated `CLAUDE.md` with map adapter architecture, file layout, and expanded examples range
+
 ## [0.7.0] - 2026-03-10
 
 ### Added

data/docs/reference/geos-acceleration.md

@@ -161,6 +161,12 @@ Run the benchmark yourself:
 ruby -Ilib examples/12_geos_benchmark.rb
 ```
 
+For a visual demonstration of GEOS operations rendered on a map:
+
+```bash
+ruby -Ilib examples/14_geos_map_rendering.rb
+```
+
 ## Architecture Notes
 
 - **Thread safety**: Uses the reentrant GEOS `_r` API with per-process context initialization

data/docs/reference/map-rendering.md

@@ -1,25 +1,106 @@
-# Map Rendering with libgd-gis
+# Map Rendering
 
-Geodetic coordinates and areas can be rendered on raster maps using the [libgd-gis](https://rubygems.org/gems/libgd-gis) gem, which provides tile-based basemap rendering on top of [ruby-libgd](https://rubygems.org/gems/ruby-libgd).
+Geodetic provides a map adapter pattern (`Geodetic::Map`) for rendering coordinates, paths, areas, and features on maps. The adapter abstracts the rendering backend so the same Geodetic objects work with different map engines.
 
-## Overview
+## Architecture
 
-The `libgd-gis` gem downloads map tiles and stitches them into a single raster image for a given bounding box and zoom level. Geodetic's coordinate objects provide the geographic data, and `GD::GIS::Geometry.project` converts longitude/latitude pairs into pixel positions on the rendered map. From there, ruby-libgd primitives (lines, circles, polygons, text, image compositing) can draw overlays on top of the basemap.
+```
+Geodetic::Map::Base          # Abstract adapter interface
+├── Geodetic::Map::LibGdGis  # Raster PNG output via libgd-gis
+├── (future) Leaflet         # Interactive HTML/JS maps
+├── (future) GoogleMaps      # Google Maps HTML or Static API
+└── (future) KML             # KML XML output
+```
 
-This combination supports:
+`MapMethods` is a mixin applied to all coordinates, areas, paths, segments, and features, providing `add_to_map(map, **style)`.
 
-- **Point markers** for any Geodetic coordinate
-- **Polygon overlays** from `Geodetic::Areas::Polygon` boundaries
-- **Bearing arrows** computed with `Feature#bearing_to` and drawn as lines with arrowheads
-- **Distance labels** using `Feature#distance_to` for annotation
-- **Icon compositing** with scaled PNG images positioned at projected coordinates
-- **Light and dark basemaps** via `:carto_light` and `:carto_dark`
+## Usage
 
-## Feature Class
+### Adding objects to a map
+
+Two equivalent APIs — use whichever reads better:
+
+```ruby
+# Map-centric
+map = Geodetic::Map::LibGdGis.new(bbox: bbox, zoom: 12, basemap: :carto_dark)
+map.add(polygon, fill: [0, 200, 120, 170], stroke: [0, 200, 120, 30], width: 2)
+map.add(path, color: [255, 220, 50], width: 3)
+map.add(coordinate, color: [255, 0, 0], label: "Marker")
+
+# Object-centric (via MapMethods mixin)
+polygon.add_to_map(map, fill: [0, 200, 120, 170])
+path.add_to_map(map, color: [255, 220, 50], width: 3)
+coordinate.add_to_map(map, color: [255, 0, 0], label: "Marker")
+```
+
+The `add` method auto-detects the object type and dispatches to the appropriate handler. Supported types:
+
+| Object | Layer type | Notes |
+|--------|-----------|-------|
+| Any coordinate (18 systems) | `:point` | Converts to LLA automatically |
+| `Path` | `:line` | Renders all waypoints as a line |
+| `Segment` | `:line` | Two-point line |
+| `Polygon` (and subclasses) | `:polygon` | Includes Triangle, Rectangle, Hexagon, etc. |
+| `Circle` | `:polygon` | Approximated as N-gon (default 32 segments) |
+| `BoundingBox` | `:polygon` | Four corners as a rectangle |
+| `Feature` | delegates | Extracts geometry; merges label into style |
+| `ENU` / `NED` | rejected | Raises `ArgumentError` (relative systems) |
+
+### Rendering
+
+```ruby
+# Simple render to file
+map.render("output.png")
+
+# Render with custom drawing block (LibGdGis-specific)
+map.render("output.png") do |gd_map|
+  img = gd_map.image
+  # Use GD::Image primitives for custom markers, labels, arrows, etc.
+end
+
+# Render without saving (returns GD::GIS::Map)
+gd_map = map.render
+```
 
-`Geodetic::Feature` wraps a geometry (any coordinate or area) with a label and a metadata hash. It delegates `distance_to` and `bearing_to` to its geometry, using the centroid for area geometries. This makes it straightforward to attach display properties like icon paths and categories alongside the spatial data.
+### Bounding box
 
-## Prerequisites
+The LibGdGis adapter accepts bounding boxes as either:
+
+```ruby
+# Geodetic BoundingBox object
+bbox = Geodetic::Areas::BoundingBox.new(nw: nw_point, se: se_point)
+map = Geodetic::Map::LibGdGis.new(bbox: bbox, zoom: 12)
+
+# Raw [west, south, east, north] array
+map = Geodetic::Map::LibGdGis.new(bbox: [-74.05, 40.65, -73.75, 40.82], zoom: 12)
+```
+
+## LibGdGis Adapter
+
+### Color format
+
+Colors are `[r, g, b]` or `[r, g, b, alpha]` arrays. The alpha channel follows libgd convention:
+
+- `0` = fully opaque
+- `255` = fully transparent
+
+### Style options
+
+| Option | Point | Line | Polygon |
+|--------|:-----:|:----:|:-------:|
+| `color` | marker color | stroke color | — |
+| `stroke` | — | stroke color | outline color |
+| `fill` | — | — | fill color |
+| `width` | — | line width (px) | outline width (px) |
+| `label` | text label | — | — |
+| `icon` | image path | — | — |
+| `font` | font path | — | — |
+| `size` | font size | — | — |
+| `font_color` | label color | — | — |
+| `symbol` | marker style | — | — |
+| `segments` | — | — | circle approximation (default 32) |
+
+### Prerequisites
 
 ```bash
 gem install libgd-gis
@@ -27,6 +108,11 @@ brew install gd   # macOS
 # apt install libgd-dev   # Linux
 ```
 
-## Example
+## Feature Class
+
+`Geodetic::Feature` wraps a geometry (any coordinate or area) with a label and a metadata hash. It delegates `distance_to` and `bearing_to` to its geometry, using the centroid for area geometries. When added to a map, the label is automatically included in the style.
+
+## Examples
 
-See [`examples/05_map_rendering/demo.rb`](https://github.com/madbomber/geodetic/tree/main/examples/05_map_rendering) for a complete working demo that renders NYC landmarks with icons, a Central Park polygon boundary, and bearing arrows between landmarks. The demo supports light/dark themes, icon scaling, and CLI flags for toggling features.
+- [`examples/05_map_rendering/demo.rb`](https://github.com/madbomber/geodetic/tree/main/examples/05_map_rendering) — NYC landmarks with icons, Central Park polygon, bearing arrows, light/dark themes
+- [`examples/14_geos_map_rendering.rb`](https://github.com/madbomber/geodetic/tree/main/examples/14_geos_map_rendering.rb) — GEOS operations (intersection, difference, buffer, convex hull, simplification, nearest points, prepared geometry) all visualized on a single map with distinct colors

data/examples/05_map_rendering/demo.rb

@@ -1,15 +1,16 @@
 #!/usr/bin/env ruby
 
 # Demonstration of rendering geodetic coordinates on a map
-# using the libgd-gis gem for native Ruby map generation.
-# Shows how Geodetic::Feature wraps named coordinates and areas.
+# using the Geodetic::Map::LibGdGis adapter.
+# Shows how Geodetic objects flow directly into map rendering
+# via the adapter pattern.
 #
 # Prerequisites:
 #   gem install libgd-gis
 #   brew install gd  (macOS) or apt install libgd-dev (Linux)
 #
 # Usage:
-#   ruby -Ilib examples/05_map_rendering.rb
+#   ruby -Ilib examples/05_map_rendering/demo.rb
 
 if ARGV.include?("-h") || ARGV.include?("--help")
   puts <<~HELP
@@ -32,7 +33,6 @@ if ARGV.include?("-h") || ARGV.include?("--help")
 end
 
 require_relative "../../lib/geodetic"
-require "gd/gis"
 
 include Geodetic
 LLA = Coordinate::LLA
@@ -78,12 +78,9 @@ landmarks = [
 ]
 
 # An area-based Feature: Central Park as a polygon boundary
-# Vertices trace the park perimeter (59th St to 110th St)
 central_park_area = Feature.new(
   label:    "Central Park",
   geometry: Areas::Polygon.new(boundary: [
-    # Vertices from OpenStreetMap data (way 427818536), simplified.
-    # Central Park is a parallelogram tilted ~29° with Manhattan's grid.
     LLA.new(lat: 40.7679, lng: -73.9818, alt: 0),  # SW corner (Columbus Circle, 59th & CPW)
     LLA.new(lat: 40.7649, lng: -73.9727, alt: 0),  # SE corner (Grand Army Plaza, 59th & 5th Ave)
     LLA.new(lat: 40.7691, lng: -73.9697, alt: 0),  # E edge — 65th St
@@ -116,18 +113,16 @@ lats = all_points.map(&:lat)
 lngs = all_points.map(&:lng)
 padding = 0.03
 
-bbox = [
-  lngs.min - padding,  # west
-  lats.min - padding,  # south
-  lngs.max + padding,  # east
-  lats.max + padding   # north
-]
+bbox = Areas::BoundingBox.new(
+  nw: LLA.new(lat: lats.max + padding, lng: lngs.min - padding, alt: 0),
+  se: LLA.new(lat: lats.min - padding, lng: lngs.max + padding, alt: 0)
+)
 
-# --- 3. Create the map ---
+# --- 3. Create the map via the adapter ---
 
 ZOOM = 12
 
-map = GD::GIS::Map.new(
+map = Map::LibGdGis.new(
   bbox:    bbox,
   zoom:    ZOOM,
   basemap: BASEMAP,
@@ -135,23 +130,17 @@ map = GD::GIS::Map.new(
   height:  768
 )
 
-# --- 4. Optionally draw Central Park polygon on the map ---
+# --- 4. Add Central Park polygon via the adapter ---
 
 if CENTRAL_PARK
-  park_coords = central_park_area.geometry.boundary.map { |pt| [pt.lng, pt.lat] }
-
-  map.add_polygons(
-    [[park_coords]],  # polygons > rings > [lng, lat] points
+  central_park_area.add_to_map(map,
     fill:   [80, 255, 120, 60],
     stroke: [50, 200, 80, 255],
     width:  2
   )
 end
 
-# Style must be set (add_polygons sets it as a side effect, but just in case)
-map.style ||= GD::GIS::Style.default
-
-# --- 6. Show Feature info using delegation ---
+# --- 5. Show Feature info using delegation ---
 
 liberty = landmarks.first
 
@@ -171,94 +160,90 @@ landmarks.each do |feature|
   INFO
 end
 
-# Distance from an area Feature to a point Feature
 puts "#{central_park_area.label} -> #{liberty.label}: #{central_park_area.distance_to(liberty).to_km}"
 puts
 
-# --- 7. Render, draw markers/areas/labels, and save ---
+# --- 6. Render and do custom drawing via the block ---
 
 output_path = File.join(__dir__, "nyc_landmarks.png")
-map.render
-
-img      = map.image
-map_bbox = map.instance_variable_get(:@bbox)
-zoom     = ZOOM
-FONT     = "/System/Library/Fonts/Supplemental/Arial Bold.ttf"
-
-# Draw landmark icons and labels
-landmarks.each do |feature|
-  pt     = feature.geometry
-  px, py = GD::GIS::Geometry.project(pt.lng, pt.lat, map_bbox, zoom)
-  x, y   = px.round, py.round
-
-  # Load and scale the icon
-  icon = GD::Image.open(feature.metadata[:icon])
-  icon.alpha_blending = true
-  icon.save_alpha = true
-  iw = (icon.width  * ICON_SCALE).round
-  ih = (icon.height * ICON_SCALE).round
-  scaled = icon.scale(iw, ih)
-  scaled.alpha_blending = true
-  scaled.save_alpha = true
-
-  # On dark basemaps, add a white disc so black icons are visible
-  if ICON_BG
-    radius = (iw / 2 * 1.3).round
-    img.filled_circle(x, y, radius, [255, 255, 255])
+FONT = "/System/Library/Fonts/Supplemental/Arial Bold.ttf"
+
+map.render(output_path) do |gd_map|
+  img      = gd_map.image
+  map_bbox = gd_map.instance_variable_get(:@bbox)
+  gd_map.style ||= GD::GIS::Style.default
+
+  # Draw landmark icons and labels
+  landmarks.each do |feature|
+    pt     = feature.geometry
+    px, py = GD::GIS::Geometry.project(pt.lng, pt.lat, map_bbox, ZOOM)
+    x, y   = px.round, py.round
+
+    # Load and scale the icon
+    icon = GD::Image.open(feature.metadata[:icon])
+    icon.alpha_blending = true
+    icon.save_alpha = true
+    iw = (icon.width  * ICON_SCALE).round
+    ih = (icon.height * ICON_SCALE).round
+    scaled = icon.scale(iw, ih)
+    scaled.alpha_blending = true
+    scaled.save_alpha = true
+
+    # On dark basemaps, add a white disc so black icons are visible
+    if ICON_BG
+      radius = (iw / 2 * 1.3).round
+      img.filled_circle(x, y, radius, [255, 255, 255])
+    end
+
+    img.copy(scaled, x - iw / 2, y - ih / 2, 0, 0, iw, ih)
+
+    # Label to the right of the icon
+    img.text(feature.label, x: x + iw / 2 + 6, y: y + 5,
+                            font: FONT, size: 16, color: LABEL_COLOR)
   end
 
-  img.copy(scaled, x - iw / 2, y - ih / 2, 0, 0, iw, ih)
-
-  # Label to the right of the icon
-  img.text(feature.label, x: x + iw / 2 + 6, y: y + 5,
-                          font: FONT, size: 16, color: LABEL_COLOR)
-end
-
-# --- 8. Draw bearing arrows ---
-
-def draw_bearing_arrow(img, from_feature, to_feature, map_bbox, zoom, color, font)
-  bearing = from_feature.bearing_to(to_feature)
-
-  x1, y1 = GD::GIS::Geometry.project(from_feature.geometry.lng, from_feature.geometry.lat, map_bbox, zoom).map(&:round)
-  x2, y2 = GD::GIS::Geometry.project(to_feature.geometry.lng, to_feature.geometry.lat, map_bbox, zoom).map(&:round)
-
-  # Line (doubled for thickness)
-  img.line(x1, y1, x2, y2, color)
-  img.line(x1 + 1, y1, x2 + 1, y2, color)
-
-  # Arrowhead at destination
-  dx, dy = (x2 - x1).to_f, (y2 - y1).to_f
-  len = Math.sqrt(dx * dx + dy * dy)
-  ux, uy = dx / len, dy / len
-
-  tip_x  = x2 - (ux * 20).round
-  tip_y  = y2 - (uy * 20).round
-  base_x = tip_x - (ux * 14).round
-  base_y = tip_y - (uy * 14).round
-  px, py = -uy, ux
-  p1x = base_x + (px * 7).round
-  p1y = base_y + (py * 7).round
-  p2x = base_x - (px * 7).round
-  p2y = base_y - (py * 7).round
-  img.filled_polygon([[tip_x, tip_y], [p1x, p1y], [p2x, p2y]], color)
-
-  # Label at midpoint
-  mid_x = (x1 + x2) / 2
-  mid_y = (y1 + y2) / 2
-  img.text("#{bearing.degrees.round(1)}\u00B0", x: mid_x + 8, y: mid_y + 5,
-                                                 font: font, size: 14, color: color)
+  # --- Draw bearing arrows ---
+  img.antialias = true
+  brooklyn = landmarks.find { |f| f.label == "Brooklyn Bridge" }
+  empire   = landmarks.find { |f| f.label == "Empire State Bldg" }
+
+  arrow_color = DARK_MODE ? [255, 100, 100] : [200, 30, 30]
+
+  [
+    [brooklyn, liberty],
+    [brooklyn, empire],
+  ].each do |from_feature, to_feature|
+    bearing = from_feature.bearing_to(to_feature)
+
+    x1, y1 = GD::GIS::Geometry.project(from_feature.geometry.lng, from_feature.geometry.lat, map_bbox, ZOOM).map(&:round)
+    x2, y2 = GD::GIS::Geometry.project(to_feature.geometry.lng, to_feature.geometry.lat, map_bbox, ZOOM).map(&:round)
+
+    # Line (doubled for thickness)
+    img.line(x1, y1, x2, y2, arrow_color)
+    img.line(x1 + 1, y1, x2 + 1, y2, arrow_color)
+
+    # Arrowhead at destination
+    dx, dy = (x2 - x1).to_f, (y2 - y1).to_f
+    len = Math.sqrt(dx * dx + dy * dy)
+    ux, uy = dx / len, dy / len
+
+    tip_x  = x2 - (ux * 20).round
+    tip_y  = y2 - (uy * 20).round
+    base_x = tip_x - (ux * 14).round
+    base_y = tip_y - (uy * 14).round
+    px, py = -uy, ux
+    p1x = base_x + (px * 7).round
+    p1y = base_y + (py * 7).round
+    p2x = base_x - (px * 7).round
+    p2y = base_y - (py * 7).round
+    img.filled_polygon([[tip_x, tip_y], [p1x, p1y], [p2x, p2y]], arrow_color)
+
+    # Label at midpoint
+    mid_x = (x1 + x2) / 2
+    mid_y = (y1 + y2) / 2
+    img.text("#{bearing.degrees.round(1)}\u00B0", x: mid_x + 8, y: mid_y + 5,
+                                                   font: FONT, size: 14, color: arrow_color)
+  end
 end
 
-img.antialias = true
-brooklyn = landmarks.find { |f| f.label == "Brooklyn Bridge" }
-liberty  = landmarks.find { |f| f.label == "Statue of Liberty" }
-empire   = landmarks.find { |f| f.label == "Empire State Bldg" }
-
-arrow_color = DARK_MODE ? [255, 100, 100] : [200, 30, 30]
-
-draw_bearing_arrow(img, brooklyn, liberty, map_bbox, zoom, arrow_color, FONT)
-draw_bearing_arrow(img, brooklyn, empire,  map_bbox, zoom, arrow_color, FONT)
-
-map.save(output_path)
-
 puts "Map saved to #{output_path}"

data/examples/14_geos_map_rendering.rb

@@ -0,0 +1,323 @@
+#!/usr/bin/env ruby
+
+# Demonstration of GEOS operations visualized on a single LibGdGis map.
+# Shows boolean operations, buffering, convex hull, simplification,
+# nearest points, and prepared geometry — all rendered with distinct colors.
+#
+# Prerequisites:
+#   gem install libgd-gis
+#   brew install gd geos
+#
+# Usage:
+#   ruby -Ilib examples/14_geos_map_rendering.rb
+#   ruby -Ilib examples/14_geos_map_rendering.rb --dark
+
+require_relative "../lib/geodetic"
+
+include Geodetic
+LLA     = Coordinate::LLA
+Polygon = Areas::Polygon
+
+unless Geos.available?
+  abort "libgeos_c not found. Install with: brew install geos"
+end
+
+# --- Theme ---
+
+def detect_macos_dark_mode
+  `defaults read -g AppleInterfaceStyle 2>/dev/null`.strip == "Dark"
+rescue
+  false
+end
+
+DARK_MODE = if ARGV.include?("--dark") then true
+            elsif ARGV.include?("--light") then false
+            else detect_macos_dark_mode
+            end
+
+BASEMAP     = DARK_MODE ? :carto_dark : :carto_light
+LABEL_COLOR = DARK_MODE ? [255, 255, 255] : [20, 20, 20]
+
+# ─── Color palette ─────────────────────────────────────────────────────
+
+# libgd alpha convention: 0 = opaque, 255 = fully transparent
+# (ruby-libgd converts to GD's internal 0=opaque/127=transparent scale)
+COLORS = {
+  lower:          { fill: [70, 130, 255, 180],  stroke: [70, 130, 255, 40]   },  # blue
+  midtown:        { fill: [255, 160, 40, 180],  stroke: [255, 160, 40, 40]   },  # orange
+  overlap:        { fill: [255, 50, 50, 140],   stroke: [255, 50, 50, 0]     },  # red
+  difference:     { fill: [180, 80, 220, 170],  stroke: [180, 80, 220, 40]   },  # purple
+  buffer_point:   { fill: [0, 200, 120, 170],   stroke: [0, 200, 120, 30]    },  # green
+  buffer_path:    { fill: [255, 220, 50, 180],  stroke: [255, 220, 50, 40]   },  # yellow
+  hull:           { fill: [0, 220, 220, 245],   stroke: [0, 220, 220, 40]    },  # cyan — very transparent fill
+  simplified:     { fill: [255, 100, 180, 170], stroke: [255, 100, 180, 40]  },  # pink
+  nearest_line:   { stroke: [255, 255, 0, 0] },                                  # bright yellow (opaque)
+  inside_point:   [0, 255, 100],                                                  # green dot
+  outside_point:  [255, 60, 60],                                                  # red dot
+  landmark_point: [255, 255, 255],                                                # white dot
+}
+
+# ─── 1. Build geometry ─────────────────────────────────────────────────
+
+# Two overlapping polygons covering Manhattan
+lower = Polygon.new(boundary: [
+  LLA.new(lat: 40.700, lng: -74.020, alt: 0),
+  LLA.new(lat: 40.700, lng: -73.970, alt: 0),
+  LLA.new(lat: 40.730, lng: -73.970, alt: 0),
+  LLA.new(lat: 40.730, lng: -74.020, alt: 0),
+])
+
+midtown = Polygon.new(boundary: [
+  LLA.new(lat: 40.720, lng: -74.010, alt: 0),
+  LLA.new(lat: 40.720, lng: -73.960, alt: 0),
+  LLA.new(lat: 40.760, lng: -73.960, alt: 0),
+  LLA.new(lat: 40.760, lng: -74.010, alt: 0),
+])
+
+# ─── 2. GEOS boolean operations ────────────────────────────────────────
+
+puts "Computing GEOS operations..."
+
+overlap    = Geos.intersection(lower, midtown)
+diff_lower = Geos.difference(lower, midtown)
+
+puts "  intersection:  #{overlap.class}"
+puts "  difference:    #{diff_lower.class}"
+
+# ─── 3. GEOS buffering ─────────────────────────────────────────────────
+
+# Buffer a point (Empire State Building) — creates a circle-like polygon
+empire = LLA.new(lat: 40.7484, lng: -73.9857, alt: 0)
+point_buffer = Geos.buffer(empire, 0.008, quad_segs: 16)
+puts "  point buffer:  #{point_buffer.class}"
+
+# Buffer a path — creates a corridor
+route = Path.new(coordinates: [
+  LLA.new(lat: 40.7061, lng: -73.9969, alt: 0),   # Brooklyn Bridge
+  LLA.new(lat: 40.7128, lng: -74.0060, alt: 0),   # One World Trade
+  LLA.new(lat: 40.7484, lng: -73.9857, alt: 0),   # Empire State
+  LLA.new(lat: 40.7580, lng: -73.9855, alt: 0),   # Times Square
+])
+path_buffer = Geos.buffer(route, 0.0015)
+puts "  path buffer:   #{path_buffer.class}"
+
+# ─── 4. Convex hull of scattered landmarks ─────────────────────────────
+
+landmarks = {
+  "Statue of Liberty" => LLA.new(lat: 40.6892, lng: -74.0445, alt: 0),
+  "Brooklyn Bridge"   => LLA.new(lat: 40.7061, lng: -73.9969, alt: 0),
+  "One World Trade"   => LLA.new(lat: 40.7128, lng: -74.0060, alt: 0),
+  "Empire State"      => LLA.new(lat: 40.7484, lng: -73.9857, alt: 0),
+  "Times Square"      => LLA.new(lat: 40.7580, lng: -73.9855, alt: 0),
+  "Central Park S"    => LLA.new(lat: 40.7649, lng: -73.9727, alt: 0),
+  "JFK Airport"       => LLA.new(lat: 40.6413, lng: -73.7781, alt: 0),
+  "Coney Island"      => LLA.new(lat: 40.5749, lng: -73.9857, alt: 0),
+}
+
+landmark_path = Path.new(coordinates: landmarks.values)
+hull = Geos.convex_hull(landmark_path)
+puts "  convex hull:   #{hull.class} (from #{landmarks.size} landmarks)"
+
+# ─── 5. Simplification ─────────────────────────────────────────────────
+
+# Build a detailed 60-vertex circle
+step = 360.0 / 60
+detailed_circle = Polygon.new(boundary: 60.times.map { |i|
+  angle = i * step * RAD_PER_DEG
+  LLA.new(lat: 40.66 + 0.015 * Math.sin(angle),
+          lng: -74.04 + 0.015 * Math.cos(angle), alt: 0)
+})
+
+simplified = Geos.simplify(detailed_circle, 0.004)
+puts "  simplify:      60 vertices -> #{simplified.is_a?(Polygon) ? simplified.boundary.length - 1 : '?'} vertices"
+
+# ─── 6. Nearest points between non-overlapping geometries ──────────────
+
+brooklyn_poly = Polygon.new(boundary: [
+  LLA.new(lat: 40.630, lng: -73.990, alt: 0),
+  LLA.new(lat: 40.630, lng: -73.940, alt: 0),
+  LLA.new(lat: 40.660, lng: -73.940, alt: 0),
+  LLA.new(lat: 40.660, lng: -73.990, alt: 0),
+])
+
+nearest = Geos.nearest_points(lower, brooklyn_poly)
+nearest_dist = nearest[0].distance_to(nearest[1])
+puts "  nearest pts:   #{nearest_dist}"
+
+# ─── 7. Prepared geometry — batch point-in-polygon ─────────────────────
+
+srand(42)
+test_points = 30.times.map do
+  LLA.new(lat: 40.56 + rand * 0.22, lng: -74.06 + rand * 0.30, alt: 0)
+end
+
+prepared = Geos.prepare(hull)
+inside_pts  = test_points.select { |pt| prepared.contains?(pt) }
+outside_pts = test_points.reject { |pt| prepared.contains?(pt) }
+prepared.release
+
+puts "  prepared test: #{inside_pts.size} inside hull, #{outside_pts.size} outside"
+
+# ─── 8. Compute bounding box for the map ───────────────────────────────
+
+all_points = landmarks.values + test_points +
+             [LLA.new(lat: 40.56, lng: -74.06, alt: 0),
+              LLA.new(lat: 40.78, lng: -73.75, alt: 0)]
+lats = all_points.map(&:lat)
+lngs = all_points.map(&:lng)
+padding = 0.02
+
+bbox = Areas::BoundingBox.new(
+  nw: LLA.new(lat: lats.max + padding, lng: lngs.min - padding, alt: 0),
+  se: LLA.new(lat: lats.min - padding, lng: lngs.max + padding, alt: 0)
+)
+
+# ─── 9. Build the map and add all layers ───────────────────────────────
+
+puts
+puts "Building map..."
+
+map = Map::LibGdGis.new(
+  bbox:    bbox,
+  zoom:    12,
+  basemap: BASEMAP,
+  width:   1400,
+  height:  1000
+)
+
+# Layer 1: Convex hull (background — largest area)
+if hull.is_a?(Polygon)
+  hull.add_to_map(map, **COLORS[:hull])
+end
+
+# Layer 2: Input polygons
+lower.add_to_map(map, **COLORS[:lower], width: 2)
+midtown.add_to_map(map, **COLORS[:midtown], width: 2)
+
+# Layer 3: Boolean intersection (overlap zone)
+if overlap.is_a?(Polygon)
+  overlap.add_to_map(map, **COLORS[:overlap], width: 2)
+end
+
+# Layer 4: Difference (lower minus midtown)
+if diff_lower.is_a?(Polygon)
+  diff_lower.add_to_map(map, **COLORS[:difference], width: 2)
+end
+
+# Layer 5: Point buffer (Empire State)
+if point_buffer.is_a?(Polygon)
+  point_buffer.add_to_map(map, **COLORS[:buffer_point], width: 2)
+end
+
+# Layer 6: Path buffer (route corridor)
+if path_buffer.is_a?(Polygon)
+  path_buffer.add_to_map(map, **COLORS[:buffer_path], width: 1)
+end
+
+# Layer 7: The route path itself
+route.add_to_map(map, color: [255, 220, 50, 255], width: 2)
+
+# Layer 8: Simplified polygon near Statue of Liberty
+if simplified.is_a?(Polygon)
+  simplified.add_to_map(map, **COLORS[:simplified], width: 2)
+end
+
+# Layer 9: Nearest-points connecting line
+nearest_seg = Segment.new(nearest[0], nearest[1])
+nearest_seg.add_to_map(map, color: COLORS[:nearest_line][:stroke], width: 2)
+
+# Layer 10: Brooklyn polygon (for nearest-points context)
+brooklyn_poly.add_to_map(map, fill: [100, 100, 100, 40], stroke: [150, 150, 150, 180], width: 1)
+
+# ─── 10. Render and draw custom markers ────────────────────────────────
+
+output_path = File.join(__dir__, "geos_showcase.png")
+FONT = "/System/Library/Fonts/Supplemental/Arial Bold.ttf"
+
+map.render(output_path) do |gd_map|
+  img      = gd_map.image
+  map_bbox = gd_map.instance_variable_get(:@bbox)
+  zoom     = 12
+
+  # Helper: project LLA to pixel coords
+  project = ->(lla) {
+    GD::GIS::Geometry.project(lla.lng, lla.lat, map_bbox, zoom).map(&:round)
+  }
+
+  # Draw landmark dots with labels
+  landmarks.each do |name, pt|
+    x, y = project.call(pt)
+    img.filled_circle(x, y, 6, COLORS[:landmark_point])
+    img.circle(x, y, 6, [0, 0, 0])
+    img.text(name, x: x + 8, y: y + 4, font: FONT, size: 11, color: LABEL_COLOR)
+  end
+
+  # Draw test points (green inside hull, red outside)
+  inside_pts.each do |pt|
+    x, y = project.call(pt)
+    img.filled_circle(x, y, 5, COLORS[:inside_point])
+    img.circle(x, y, 5, [0, 80, 40])
+  end
+
+  outside_pts.each do |pt|
+    x, y = project.call(pt)
+    img.filled_circle(x, y, 5, COLORS[:outside_point])
+    img.circle(x, y, 5, [150, 30, 30])
+  end
+
+  # Draw nearest-points markers
+  nearest.each do |pt|
+    x, y = project.call(pt)
+    img.filled_circle(x, y, 7, [255, 255, 0])
+    img.circle(x, y, 7, [0, 0, 0])
+  end
+
+  # Legend
+  img.antialias = true
+  lx, ly = 12, 12
+  line_h = 20
+  entries = [
+    [[70, 130, 255],  "Lower Manhattan (input)"],
+    [[255, 160, 40],  "Midtown (input)"],
+    [[255, 50, 50],   "Intersection (overlap)"],
+    [[180, 80, 220],  "Difference (lower - midtown)"],
+    [[0, 200, 120],   "Point buffer (Empire State)"],
+    [[255, 220, 50],  "Path buffer (route corridor)"],
+    [[0, 220, 220],   "Convex hull (8 landmarks)"],
+    [[255, 100, 180], "Simplified polygon (60->few vertices)"],
+    [[255, 255, 0],   "Nearest points (Lower<->Brooklyn)"],
+    [[100, 100, 100], "Brooklyn (nearest-points target)"],
+    [[0, 255, 100],   "Test point: inside hull"],
+    [[255, 60, 60],   "Test point: outside hull"],
+  ]
+
+  # Legend background
+  legend_w = 310
+  legend_h = entries.size * line_h + 10
+  bg_color = DARK_MODE ? [30, 30, 30, 200] : [255, 255, 255, 200]
+  img.filled_rectangle(lx, ly, lx + legend_w, ly + legend_h, bg_color)
+  img.rectangle(lx, ly, lx + legend_w, ly + legend_h, [100, 100, 100])
+
+  entries.each_with_index do |(color, label), i|
+    y = ly + 6 + i * line_h
+    img.filled_rectangle(lx + 6, y, lx + 20, y + 12, color)
+    img.rectangle(lx + 6, y, lx + 20, y + 12, [60, 60, 60])
+    img.text(label, x: lx + 26, y: y + 11, font: FONT, size: 10, color: LABEL_COLOR)
+  end
+end
+
+puts "Map saved to #{output_path}"
+
+puts <<~HEREDOC
+
+  GEOS operations rendered:
+    1. intersection(lower, midtown)      -> red overlay
+    2. difference(lower, midtown)        -> purple area
+    3. buffer(empire_state, 0.004)       -> green circle
+    4. buffer(route, 0.0015)             -> yellow corridor
+    5. convex_hull(8 landmarks)          -> cyan boundary
+    6. simplify(60-vertex circle, 0.004) -> pink polygon
+    7. nearest_points(lower, brooklyn)   -> yellow dots + line
+    8. prepare(hull).contains?(30 pts)   -> green/red dots
+
+HEREDOC

data/examples/README.md

@@ -213,3 +213,40 @@ Run:
 ```bash
 ruby -Ilib examples/13_geos_operations.rb
 ```
+
+## 14 - GEOS Map Rendering
+
+Visualizes GEOS spatial operations on a single raster map using the `Geodetic::Map::LibGdGis` adapter. All eight GEOS operation categories rendered with distinct colors on a dark or light basemap, with an embedded legend. Covers:
+
+- **Boolean intersection** (red) of two overlapping Manhattan polygons
+- **Boolean difference** (purple) showing lower Manhattan minus midtown
+- **Point buffer** (green) around the Empire State Building via `Geos.buffer`
+- **Path buffer** (yellow corridor) along a 4-point route via `Geos.buffer`
+- **Convex hull** (cyan, transparent) enclosing 8 NYC landmarks via `Geos.convex_hull`
+- **Simplification** (pink) reducing a 60-vertex circle to 8 vertices via `Geos.simplify`
+- **Nearest points** (yellow dots + line) between Lower Manhattan and Brooklyn via `Geos.nearest_points`
+- **Prepared geometry containment** (green/red dots) testing 30 random points against the hull via `Geos.prepare`
+- **Map adapter pattern** using `Geodetic::Map::LibGdGis` with `add_to_map` on Geodetic objects
+- **Custom drawing** via render block for landmark labels, test point markers, and color legend
+- **Light/dark theme** switching with macOS system detection
+
+Prerequisites:
+
+```bash
+gem install libgd-gis
+brew install gd geos   # macOS
+```
+
+Run:
+
+```bash
+ruby -Ilib examples/14_geos_map_rendering.rb
+```
+
+CLI flags:
+
+```
+--light / --dark       Select basemap theme (default: macOS system setting)
+```
+
+Output: `examples/geos_showcase.png`

data/lib/geodetic/map/base.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Geodetic
+  module Map
+    class Base
+      attr_reader :layers
+
+      def initialize(**options)
+        @layers  = []
+        @options = options
+      end
+
+      # --- Adding geometry ---
+
+      def add(object, **style)
+        case object
+        when Feature
+          add_feature(object, **style)
+        when Path
+          add_path(object, **style)
+        when Segment
+          add_segment(object, **style)
+        when Areas::Circle
+          add_circle(object, **style)
+        when Areas::BoundingBox
+          add_bounding_box(object, **style)
+        when Areas::Polygon
+          add_polygon(object, **style)
+        else
+          if coordinate?(object)
+            add_coordinate(object, **style)
+          else
+            raise ArgumentError, "unsupported object type: #{object.class}"
+          end
+        end
+
+        self
+      end
+
+      def add_coordinate(coordinate, **style)
+        lla = to_lla(coordinate)
+        @layers << { type: :point, lla: lla, style: style }
+        self
+      end
+
+      def add_path(path, **style)
+        llas = path.map { |c| to_lla(c) }
+        @layers << { type: :line, llas: llas, style: style }
+        self
+      end
+
+      def add_segment(segment, **style)
+        llas = [segment.start_point, segment.end_point]
+        @layers << { type: :line, llas: llas, style: style }
+        self
+      end
+
+      def add_polygon(polygon, **style)
+        llas = polygon.boundary.map { |c| to_lla(c) }
+        @layers << { type: :polygon, llas: llas, style: style }
+        self
+      end
+
+      def add_circle(circle, **style)
+        segments = style.delete(:segments) || 32
+        step = 360.0 / segments
+        llas = segments.times.map do |i|
+          Vector.new(distance: circle.radius, bearing: step * i).destination_from(circle.centroid)
+        end
+        llas << llas.first
+        @layers << { type: :polygon, llas: llas, style: style }
+        self
+      end
+
+      def add_bounding_box(bbox, **style)
+        llas = [bbox.nw, bbox.ne, bbox.se, bbox.sw, bbox.nw]
+        @layers << { type: :polygon, llas: llas, style: style }
+        self
+      end
+
+      def add_feature(feature, **style)
+        merged_style = feature_style(feature, style)
+        add(feature.geometry, **merged_style)
+      end
+
+      # --- Output ---
+
+      def render(output_path)
+        raise NotImplementedError, "#{self.class}#render must be implemented by subclass"
+      end
+
+      # --- Query ---
+
+      def size
+        @layers.size
+      end
+
+      def empty?
+        @layers.empty?
+      end
+
+      def clear
+        @layers.clear
+        self
+      end
+
+      private
+
+      def coordinate?(object)
+        Coordinate.systems.any? { |klass| object.is_a?(klass) }
+      end
+
+      def to_lla(coord)
+        return coord if coord.is_a?(Coordinate::LLA)
+
+        if coord.is_a?(Coordinate::ENU) || coord.is_a?(Coordinate::NED)
+          raise ArgumentError,
+            "#{coord.class.name.split('::').last} is a relative coordinate system. " \
+            "Convert to an absolute system before adding to a map."
+        end
+
+        coord.to_lla
+      end
+
+      def feature_style(feature, explicit_style)
+        style = {}
+        style[:label] = feature.label if feature.label
+        style.merge(explicit_style)
+      end
+    end
+  end
+end

data/lib/geodetic/map/lib_gd_gis.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Geodetic
+  module Map
+    class LibGdGis < Base
+      def initialize(bbox: nil, zoom: 10, width: nil, height: nil, basemap: :osm, **options)
+        super(**options)
+        @bbox    = resolve_bbox(bbox)
+        @zoom    = zoom
+        @width   = width
+        @height  = height
+        @basemap = basemap
+      end
+
+      def render(output_path = nil, &block)
+        require_gd_gis!
+
+        @gd_map = build_map
+        apply_layers(@gd_map)
+        @gd_map.render
+
+        yield @gd_map if block_given?
+
+        if output_path
+          @gd_map.save(output_path)
+        end
+
+        @gd_map
+      end
+
+      # Access the underlying GD::GIS::Map after render.
+      attr_reader :gd_map
+
+      private
+
+      def require_gd_gis!
+        require "gd/gis"
+      rescue LoadError
+        raise LoadError,
+          "libgd-gis is required for Geodetic::Map::LibGdGis. " \
+          "Add `gem 'libgd-gis'` to your Gemfile."
+      end
+
+      def build_map
+        args = { zoom: @zoom, basemap: @basemap }
+        args[:bbox]   = @bbox   if @bbox
+        args[:width]  = @width  if @width
+        args[:height] = @height if @height
+
+        ::GD::GIS::Map.new(**args)
+      end
+
+      def apply_layers(map)
+        @layers.each do |layer|
+          case layer[:type]
+          when :point
+            apply_point(map, layer)
+          when :line
+            apply_line(map, layer)
+          when :polygon
+            apply_polygon(map, layer)
+          end
+        end
+      end
+
+      def apply_point(map, layer)
+        lla   = layer[:lla]
+        style = layer[:style]
+
+        map.add_point(
+          lon: lla.longitude,
+          lat: lla.latitude,
+          **point_options(style)
+        )
+      end
+
+      def apply_line(map, layer)
+        coords = layer[:llas].map { |p| [p.longitude, p.latitude] }
+        style  = layer[:style]
+
+        map.add_lines(
+          [coords],
+          **line_options(style)
+        )
+      end
+
+      def apply_polygon(map, layer)
+        ring  = layer[:llas].map { |p| [p.longitude, p.latitude] }
+        style = layer[:style]
+
+        map.add_polygons(
+          [[ring]],
+          **polygon_options(style)
+        )
+      end
+
+      # --- Style translation ---
+
+      def point_options(style)
+        opts = {}
+        opts[:label]      = style[:label]      if style[:label]
+        opts[:icon]       = style[:icon]        if style[:icon]
+        opts[:font]       = style[:font]        if style[:font]
+        opts[:size]       = style[:size]        if style[:size]
+        opts[:color]      = style[:color]       if style[:color]
+        opts[:font_color] = style[:font_color]  if style[:font_color]
+        opts[:symbol]     = style[:symbol]      if style[:symbol]
+        opts
+      end
+
+      def line_options(style)
+        opts = {}
+        opts[:stroke] = style[:stroke] || style[:color] || [255, 0, 0]
+        opts[:width]  = style[:width] || 2
+        opts
+      end
+
+      def polygon_options(style)
+        opts = {}
+        opts[:fill]   = style[:fill]   || style[:color] || [0, 0, 255, 80]
+        opts[:stroke] = style[:stroke] if style[:stroke]
+        opts[:width]  = style[:width]  if style[:width]
+        opts
+      end
+
+      # --- BBox resolution ---
+
+      def resolve_bbox(bbox)
+        case bbox
+        when nil
+          nil
+        when Array
+          bbox
+        when Areas::BoundingBox
+          [bbox.nw.longitude, bbox.se.latitude, bbox.se.longitude, bbox.nw.latitude]
+        else
+          if Coordinate.systems.any? { |klass| bbox.is_a?(klass) }
+            raise ArgumentError,
+              "single coordinate is not a valid bbox. " \
+              "Use Geodetic::Areas::BoundingBox or a [west, south, east, north] array."
+          end
+          bbox
+        end
+      end
+    end
+  end
+end

data/lib/geodetic/map.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "map/base"
+require_relative "map/lib_gd_gis"
+
+module Geodetic
+  module Map
+    # Mixin that adds add_to_map to geometry classes.
+    # Applied to coordinates, areas, paths, segments, and features.
+    module MapMethods
+      def add_to_map(map, **style)
+        map.add(self, **style)
+      end
+    end
+  end
+end
+
+# Apply MapMethods to all coordinate classes
+Geodetic::Coordinate.systems.each do |klass|
+  klass.include(Geodetic::Map::MapMethods)
+end
+
+# Apply MapMethods to geometry types
+[
+  Geodetic::Path,
+  Geodetic::Segment,
+  Geodetic::Feature,
+  Geodetic::Areas::Polygon,
+  Geodetic::Areas::Circle,
+  Geodetic::Areas::BoundingBox
+].each { |klass| klass.include(Geodetic::Map::MapMethods) }

data/lib/geodetic/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Geodetic
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/geodetic.rb

@@ -19,3 +19,4 @@ require_relative "geodetic/geojson"
 require_relative "geodetic/wkt"
 require_relative "geodetic/wkb"
 require_relative "geodetic/geos"
+require_relative "geodetic/map"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: geodetic
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -85,11 +85,13 @@ files:
 - examples/11_wkb_serialization.rb
 - examples/12_geos_benchmark.rb
 - examples/13_geos_operations.rb
+- examples/14_geos_map_rendering.rb
 - examples/README.md
 - examples/geodetic_demo.geojson
 - examples/geodetic_demo.wkb
 - examples/geodetic_demo.wkt
 - examples/geodetic_demo_output.wkb.hex
+- examples/geos_showcase.png
 - examples/sample_geometries.wkb
 - examples/sample_geometries.wkb.hex
 - fiddle_pointer_buffer_pool.md
@@ -131,6 +133,9 @@ files:
 - lib/geodetic/geoid_height.rb
 - lib/geodetic/geojson.rb
 - lib/geodetic/geos.rb
+- lib/geodetic/map.rb
+- lib/geodetic/map/base.rb
+- lib/geodetic/map/lib_gd_gis.rb
 - lib/geodetic/path.rb
 - lib/geodetic/segment.rb
 - lib/geodetic/vector.rb
@@ -162,7 +167,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.7
+rubygems_version: 4.0.8
 specification_version: 4
 summary: Convert between geodetic coordinate systems with distance calculations
 test_files: []