libgd-gis 0.2.9 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f3f45fc1508b900f78e5b11cd5fff6854ff81e1482ca26b8478be88957ba086
-  data.tar.gz: 30df288e61f15f66d0c0f210f9842cc1897ae35b1e6c0a442d6238dbb0c1ce4c
+  metadata.gz: 72c8b1d43f60ad8615302e22054c3d5e00be6bd746c757f00d980e781f760b0c
+  data.tar.gz: 74d09fb46fe02d7d53c75f4c2a9acb6bbab24383b51ef9bd9ec3ad8c89e0253f
 SHA512:
-  metadata.gz: ca3069e841e805116089bc949fa4f14a708775100eed78dbc488fa1c1bba0d0fa66a7acb2fce50711d134e9d98695c2b3c0ecc7f28cdf723b4936da37e22825b
-  data.tar.gz: d12da69bd604584ba37b2b250de904e622a93a325437afec6c6f79f81c53c4863043c2b837e2f73d965423e62229f4838458d485f7f2d44bdf746e7df8c44075
+  metadata.gz: e09c62bf8ee7218019a2e69676cc9b7461982568842bb8afac861f38f290d7fec658ee15269915ec5a3ad925de4d5ef4e6dcdce0415d7b97d438d91795d022a5
+  data.tar.gz: e7a1a6f47da4bbf9db7e18de9c3184e4af3498f636f51ba8b8ee9aa25b1c57c9532be24e71ee76e2201f5f7a240cddc62e33f16d886a1673062d845163831664

data/README.md

@@ -1,4 +1,4 @@
-# LibGD-GIS
+# LibGD GIS
 
 <p align="center">
   <a href="https://rubystacknews.com/2026/01/07/ruby-can-now-draw-maps-and-i-started-with-ice-cream/">
@@ -33,156 +33,190 @@
 [![Test Coverage](https://coveralls.io/repos/githublibgd-gis/libgd-gis/badge.svg?branch=master)](https://coveralls.io/github/libgd-gis/libgd-gis?branch=master)
 [![Gem Version](https://img.shields.io/gem/v/libgd-gis.svg)](https://rubygems.org/gems/libgd-gis)
 
+---
+
+**libgd-gis** is a lightweight Ruby GIS rendering library built on top of **GD**.
+It renders geographic data (GeoJSON, points, lines, polygons) into raster images using Web Mercator tiles and a simple, explicit rendering pipeline.
 
-| Examples | Examples | Examples |
-| :----: | :----: | :--: |
-| <img src="docs/examples/parana.png" height="250"> | <img src="docs/examples/nyc.png" height="250"> | <img src="docs/examples/paris.png" height="250"> |
-| <img src="examples/nyc/nyc.png" height="250"> | <img src="docs/examples/tokyo_solarized.png" height="250"> | <img src="examples/parana/parana.png" height="250"> |
-| <img src="docs/examples/america.png" height="250"> | <img src="docs/examples/argentina_museum.png" height="250"> | <img src="docs/examples/museos_parana.png" height="250"> |
-| <img src="docs/examples/asia.png" height="250"> | <img src="docs/examples/europe.png" height="250"> | <img src="docs/examples/icecream_parana.png" height="250"> |
-| <img src="docs/examples/argentina_cities.png" height="250"> | <img src="docs/examples/tanzania_hydro.png" height="250"> | <img src="docs/examples/parana_polygon.png" height="250"> |
-| <img src="docs/examples/parana_carto_dark.png" height="250"> | <img src="docs/examples/ramirez_avenue.png" height="250"> | <img src="examples/paris/paris.png" height="250"> |
+This library is designed for **map visualization**, not for spatial analysis.
 
 ---
 
-> **libgd-gis is evolving very fast**, so some examples may temporarily stop working.  
-> Please report issues or ask for help — feedback is very welcome.  
-> https://github.com/ggerman/libgd-gis/issues or ggerman@gmail.com
+## Features
 
---
+- Web Mercator tile rendering (OSM, CARTO, ESRI, Stamen, etc.)
+- CRS normalization (CRS84, EPSG:4326, EPSG:3857, Gauss–Krüger Argentina)
+- Layered rendering pipeline
+- YAML-based styling
+- Rule-based semantic classification (ontology)
+- Points, lines, and polygons support
+- No heavy GIS dependencies
 
-## A geospatial raster engine for Ruby.
+---
 
-libgd-gis allows Ruby to render real maps, GeoJSON layers, vector features, and geospatial tiles using a native raster backend powered by **libgd**.
+## Non-Goals
 
-It restores something Ruby lost over time:
- the ability to generate **maps, tiles, and GIS-grade visualizations natively**, without relying on external tools like QGIS, Mapnik, ImageMagick, or Mapbox.
+libgd-gis intentionally does **not** aim to be:
 
-Built on top of **ruby-libgd**, this project turns Ruby into a **map rendering engine**, capable of producing spatial graphics, tiled maps, and geospatial outputs directly inside Ruby processes.
+- a spatial analysis engine
+- a replacement for PostGIS / GEOS
+- a full map server
+- a vector tile generator
 
-- No external renderers.
--  No shelling out.
--  Just Ruby, raster, and GIS.
+If you need projections beyond Web Mercator or topological correctness,
+use a full GIS stack.
 
 ---
 
-## What is this?
+## Installation
 
-`libgd-gis` is a **geospatial rendering engine** for Ruby built on top of [`ruby-libgd`](https://github.com/ggerman/ruby-libgd).
+Add to your Gemfile:
 
-It allows you to:
+```ruby
+gem "libgd-gis"
+```
 
-- Load GeoJSON, CSV, or any dataset with coordinates  
-- Fetch real basemap tiles  
-- Reproject WGS84 (lat/lon) into Web Mercator  
-- Render points, icons, and layers onto a raster map  
-- Generate PNG maps or map tiles  
+Then run:
 
-This is the same type of pipeline used by professional GIS systems — implemented in Ruby.
+```bash
+bundle install
+```
 
----
+You must also have **GD** available on your system.
 
-## Installation
+---
 
-### System dependency
+## Basic Usage
 
-`libgd-gis` depends on **libgd**, via `ruby-libgd`.
+### Create a map
 
-Install libgd first:
+```ruby
+require "gd/gis"
 
-**Ubuntu / Debian**
+map = GD::GIS::Map.new(
+  bbox: [-58.45, -34.7, -58.35, -34.55],
+  zoom: 13,
+  basemap: :carto_light,
+  width: 1024,
+  height: 768
+)
 ```
-sudo apt install libgd-dev
+
+### Load a style
+
+```ruby
+map.style = GD::GIS::Style.load("default", from: "styles")
 ```
 
-**macOS**
+### Load GeoJSON
+
+```ruby
+map.add_geojson("data/roads.geojson")
+map.add_geojson("data/water.geojson")
 ```
-brew install gd
+
+### Render
+
+```ruby
+map.render
+map.save("map.png")
 ```
 
 ---
 
-### Ruby gems
+## Styles Are Mandatory
 
-```
-gem install ruby-libgd
-gem install libgd-gis
-```
+libgd-gis requires an explicit **style definition** in order to render a map.
 
----
+A `GD::GIS::Map` instance **will not render without a style**, and calling
+`map.render` before assigning one will raise an error.
+
+This is intentional.
 
-## Quick Example
+Styles define how semantic layers (roads, water, parks, points, etc.) are mapped
+to visual properties such as colors, stroke widths, fills, and drawing order.
+No implicit or default styling is applied.
 
-Render hydroelectric plants from a GeoJSON file:
+### Example:
 
 ```ruby
-require "json"
 require "gd/gis"
 
-# ---------------------------
-# Bounding box mundial
-# ---------------------------
-AMERICA = [-170, -60, -30, 75]
-
-# ---------------------------
-# Crear mapa
-# ---------------------------
 map = GD::GIS::Map.new(
-  bbox: AMERICA,
-  zoom: 4,
+  bbox: PARIS,
+  zoom: 13,
   basemap: :carto_light
 )
 
-# Cargar datos
-# ---------------------------
-peaks = JSON.parse(File.read("picks.json"))
-
-# ---------------------------
-# Agregar capa de puntos
-# ---------------------------
-map.add_points(
-  peaks,
-  lon: ->(p) { p["longitude"] },
-  lat: ->(p) { p["latitude"] },
-  icon: "peak.png",
-  label: ->(p) { p["name"] },
-  font: "./fonts/DejaVuSans.ttf",
-  size: 10,
-  color: [0,0,0]
-)
+map.style = GD::GIS::Style.load("default")
 
-# ---------------------------
-# Renderizar y guardar
-# ---------------------------
 map.render
-map.save("output/america.png")
-
-puts "Saved output/america.png"
-
 ```
+### Example:
+
+```yml
+# styles/default.yml
+
+roads:
+  motorway:
+    stroke: [255, 255, 255]
+    stroke_width: 10
+    fill: [60, 60, 60]
+    fill_width: 6
+
+  primary:
+    stroke: [200, 200, 200]
+    stroke_width: 7
+    fill: [80, 80, 80]
+    fill_width: 4
+
+  street:
+    stroke: [120, 120, 120]
+    stroke_width: 1
+
+rail:
+  stroke: [255, 255, 255]
+  stroke_width: 6
+  fill: [220, 50, 50]
+  fill_width: 4
+  center: [255, 255, 255]
+  center_width: 1
+
+water:
+  fill: [120, 180, 255]
+  fill_width: 4
+  stroke: [80, 140, 220]
+
+park:
+  fill: [40, 80, 40]
+
+order:
+  - water
+  - park
+  - street
+  - primary
+  - motorway
+  - rail
+```
+This design ensures predictable rendering and makes all visual decisions explicit
+and reproducible.
 
----
 
-## Features
+---
 
-- Real basemap tiles  
-- WGS84 → Web Mercator projection  
-- GeoJSON point rendering  
-- CSV / JSON support  
-- Icon-based symbol layers  
-- Automatic bounding box fitting  
-- Raster output (PNG)  
+## CRS Support
 
----
+Supported input CRS:
 
-## License
+- CRS84
+- EPSG:4326
+- EPSG:3857
+- EPSG:22195 (Gauss–Krüger Argentina, zone 5)
 
-MIT
+All coordinates are normalized internally to **CRS84 (lon, lat)**.
 
 ---
 
-## Author
+## License
 
-Germán Silva
-https://github.com/ggerman
-https://rubystacknews.com
+MIT

data/lib/gd/gis/basemap.rb

@@ -1,18 +1,55 @@
+# frozen_string_literal: true
+
 require "net/http"
 require "fileutils"
 
 module GD
   module GIS
+    # Fetches and manages raster basemap tiles using the XYZ
+    # Web Mercator tiling scheme.
+    #
+    # A Basemap is responsible for:
+    # - Converting geographic coordinates to tile coordinates
+    # - Downloading raster tiles from public tile providers
+    # - Caching tiles on disk
+    # - Exposing pixel origins for map composition
+    #
+    # All tiles are assumed to be 256×256 pixels.
+    #
+    # @example Fetch tiles for a bounding box
+    #   bbox = [-3.8, 40.3, -3.6, 40.5] # west, south, east, north
+    #   basemap = GD::GIS::Basemap.new(12, bbox, :carto_light)
+    #   tiles, origin_x, origin_y = basemap.fetch_tiles
+    #
     class Basemap
+      # Tile size in pixels (Web Mercator standard)
       TILE_SIZE = 256
-      attr_reader :origin_x, :origin_y
 
-      def initialize(zoom, bbox, provider=:carto_light)
+      # @return [Integer] pixel X origin of the basemap
+      attr_reader :origin_x
+
+      # @return [Integer] pixel Y origin of the basemap
+      attr_reader :origin_y
+
+      # Creates a new basemap tile source.
+      #
+      # @param zoom [Integer] zoom level
+      # @param bbox [Array<Float>] bounding box [west, south, east, north]
+      # @param provider [Symbol] tile provider/style
+      def initialize(zoom, bbox, provider = :carto_light)
         @zoom = zoom
         @bbox = bbox
         @provider = provider
       end
 
+      # Builds a tile URL for a given provider and tile coordinate.
+      #
+      # @param z [Integer] zoom level
+      # @param x [Integer] tile X coordinate
+      # @param y [Integer] tile Y coordinate
+      # @param style [Symbol] tile style/provider
+      # @return [String] tile URL
+      # @raise [RuntimeError] if the provider is unknown
       def url(z, x, y, style = :osm)
         case style
 
@@ -55,9 +92,6 @@ module GD
         when :esri_terrain
           "https://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/tile/#{z}/#{y}/#{x}"
 
-        when :esri_hybrid
-          "https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/#{z}/#{y}/#{x}"
-
         # ==============================
         # STAMEN 503
         # ==============================
@@ -102,15 +136,34 @@ module GD
         end
       end
 
+      # Converts longitude to tile X coordinate.
+      #
+      # @param lon [Float] longitude in degrees
+      # @return [Integer] tile X coordinate
       def lon2tile(lon)
-        ((lon + 180.0) / 360.0 * (2 ** @zoom)).floor
+        ((lon + 180.0) / 360.0 * (2**@zoom)).floor
       end
 
+      # Converts latitude to tile Y coordinate.
+      #
+      # @param lat [Float] latitude in degrees
+      # @return [Integer] tile Y coordinate
       def lat2tile(lat)
         rad = lat * Math::PI / 180
-        ((1 - Math.log(Math.tan(rad) + 1 / Math.cos(rad)) / Math::PI) / 2 * (2 ** @zoom)).floor
+        ((1 - (Math.log(Math.tan(rad) + (1 / Math.cos(rad))) / Math::PI)) / 2 * (2**@zoom)).floor
       end
 
+      # Downloads all tiles required to cover the bounding box.
+      #
+      # Tiles are cached on disk under `tmp/tiles`.
+      #
+      # @return [Array]
+      #   - tiles [Array<Array(Integer, Integer, String)>]
+      #     list of [x, y, file_path]
+      #   - origin_x [Integer] pixel X origin
+      #   - origin_y [Integer] pixel Y origin
+      #
+      # @raise [RuntimeError] if a tile cannot be fetched
       def fetch_tiles
         west, south, east, north = @bbox
 
@@ -133,8 +186,14 @@ module GD
           (y_min..y_max).each do |y|
             path = nil
 
-            unless File.exist?("tmp/tiles/#{@provider}_#{@zoom}_#{x}_#{y}.png") ||
-                  File.exist?("tmp/tiles/#{@provider}_#{@zoom}_#{x}_#{y}.jpg")
+            if File.exist?("tmp/tiles/#{@provider}_#{@zoom}_#{x}_#{y}.png") ||
+               File.exist?("tmp/tiles/#{@provider}_#{@zoom}_#{x}_#{y}.jpg")
+              path = if File.exist?("tmp/tiles/#{@provider}_#{@zoom}_#{x}_#{y}.png")
+                       "tmp/tiles/#{@provider}_#{@zoom}_#{x}_#{y}.png"
+                     else
+                       "tmp/tiles/#{@provider}_#{@zoom}_#{x}_#{y}.jpg"
+                     end
+            else
 
               uri = URI(url(@zoom, x, y, @provider))
 
@@ -159,15 +218,9 @@ module GD
                 path = "tmp/tiles/#{@provider}_#{@zoom}_#{x}_#{y}.#{ext}"
                 File.binwrite(path, res.body)
               end
-            else
-              if File.exist?("tmp/tiles/#{@provider}_#{@zoom}_#{x}_#{y}.png")
-                path = "tmp/tiles/#{@provider}_#{@zoom}_#{x}_#{y}.png"
-              else
-                path = "tmp/tiles/#{@provider}_#{@zoom}_#{x}_#{y}.jpg"
-              end
             end
 
-            tiles << [x,y,path]
+            tiles << [x, y, path]
           end
         end
 

data/lib/gd/gis/classifier.rb

@@ -1,6 +1,31 @@
+# frozen_string_literal: true
+
 module GD
   module GIS
+    # Classifies geographic features based on their properties.
+    #
+    # This class provides a set of stateless helpers used to
+    # infer semantic categories (roads, water, parks, rails)
+    # from feature attribute tags, typically originating from
+    # OpenStreetMap or similar datasets.
+    #
+    # All methods are pure functions and return symbols or booleans
+    # suitable for styling or rendering decisions.
+    #
     class Classifier
+      # Classifies a road feature into a road category.
+      #
+      # The classification is based on the `highway` tag.
+      #
+      # @param feature [GD::GIS::Feature]
+      # @return [Symbol, nil]
+      #   one of:
+      #   - :motorway
+      #   - :primary
+      #   - :secondary
+      #   - :street
+      #   - :minor
+      #   - nil if the feature is not a road
       def self.road(feature)
         tags = feature.properties || {}
 
@@ -11,37 +36,52 @@ module GD
           :primary
         when "secondary", "secondary_link"
           :secondary
-        when "tertiary"
-          :street
-        when "residential", "living_street"
+        when "tertiary", "residential", "living_street"
           :street
         when "service", "track"
           :minor
-        else
-          nil
         end
       end
 
+      # Determines whether a feature represents water.
+      #
+      # @param feature [GD::GIS::Feature]
+      # @return [Boolean] true if the feature is water-related
       def self.water?(feature)
         p = feature.properties
 
         p["waterway"] ||
-        p["natural"] == "water" ||
-        p["fclass"] == "river" ||
-        p["fclass"] == "stream"
+          p["natural"] == "water" ||
+          p["fclass"] == "river" ||
+          p["fclass"] == "stream"
       end
 
+      # Determines whether a feature represents a railway.
+      #
+      # @param feature [GD::GIS::Feature]
+      # @return [Boolean] true if the feature is a rail feature
       def self.rail?(feature)
         tags = feature.properties || {}
         tags["railway"]
       end
 
+      # Determines whether a feature represents a park or green area.
+      #
+      # @param feature [GD::GIS::Feature]
+      # @return [Boolean] true if the feature is a park or green space
       def self.park?(feature)
         tags = feature.properties || {}
         %w[park recreation_ground garden].include?(tags["leisure"]) ||
           %w[park grass forest].include?(tags["landuse"])
       end
 
+      # Classifies the type of water feature.
+      #
+      # @param feature [GD::GIS::Feature]
+      # @return [Symbol]
+      #   - :river
+      #   - :stream
+      #   - :minor (default / fallback)
       def self.water_kind(feature)
         p = feature.properties
 
@@ -51,7 +91,6 @@ module GD
         else :minor
         end
       end
-
     end
   end
 end

data/lib/gd/gis/color_helpers.rb

@@ -1,9 +1,21 @@
+# frozen_string_literal: true
+
 module GD
   module GIS
+    # Utility helpers for generating colors compatible with GD.
+    #
+    # This module provides convenience methods for creating
+    # random RGB / RGBA colors and vivid colors suitable for
+    # map rendering and styling.
+    #
+    # All methods return instances of {GD::Color}.
+    #
     module ColorHelpers
-      # --------------------------------------------------
-      # Random RGB color
-      # --------------------------------------------------
+      # Generates a random RGB color.
+      #
+      # @param min [Integer] minimum channel value (0–255)
+      # @param max [Integer] maximum channel value (0–255)
+      # @return [GD::Color]
       def self.random_rgb(min: 0, max: 255)
         GD::Color.rgb(
           rand(min..max),
@@ -12,9 +24,12 @@ module GD
         )
       end
 
-      # --------------------------------------------------
-      # Random RGBA color
-      # --------------------------------------------------
+      # Generates a random RGBA color.
+      #
+      # @param min [Integer] minimum channel value (0–255)
+      # @param max [Integer] maximum channel value (0–255)
+      # @param alpha [Integer, nil] alpha channel (0–255), random if nil
+      # @return [GD::Color]
       def self.random_rgba(min: 0, max: 255, alpha: nil)
         GD::Color.rgba(
           rand(min..max),
@@ -24,9 +39,12 @@ module GD
         )
       end
 
-      # --------------------------------------------------
-      # Random vivid color (avoid gray/mud)
-      # --------------------------------------------------
+      # Generates a random vivid RGB color.
+      #
+      # Vivid colors avoid low saturation and brightness values,
+      # making them suitable for distinguishing map features.
+      #
+      # @return [GD::Color]
       def self.random_vivid
         h = rand
         s = rand(0.6..1.0)
@@ -36,15 +54,21 @@ module GD
         GD::Color.rgb(r, g, b)
       end
 
-      # --------------------------------------------------
-      # HSV → RGB
-      # --------------------------------------------------
+      # Converts HSV color values to RGB.
+      #
+      # Hue, saturation, and value are expected to be in the
+      # range 0.0–1.0.
+      #
+      # @param h [Float] hue
+      # @param s [Float] saturation
+      # @param v [Float] value
+      # @return [Array<Integer>] RGB values in the range 0–255
       def self.hsv_to_rgb(h, s, v)
         i = (h * 6).floor
-        f = h * 6 - i
+        f = (h * 6) - i
         p = v * (1 - s)
-        q = v * (1 - f * s)
-        t = v * (1 - (1 - f) * s)
+        q = v * (1 - (f * s))
+        t = v * (1 - ((1 - f) * s))
 
         r, g, b =
           case i % 6
@@ -58,8 +82,6 @@ module GD
 
         [(r * 255).to_i, (g * 255).to_i, (b * 255).to_i]
       end
-
     end
   end
 end
-