libgd-gis 0.2.8 → 0.3.0

data/lib/gd/gis/map.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "basemap"
 require_relative "projection"
 require_relative "classifier"
@@ -6,17 +8,58 @@ require_relative "layer_points"
 require_relative "layer_lines"
 require_relative "layer_polygons"
 
+LINE_GEOMS = %w[LineString MultiLineString].freeze
+POLY_GEOMS = %w[Polygon MultiPolygon].freeze
+
 module GD
   module GIS
-    attr_accessor :debug
-
+    # Represents a complete renderable map.
+    #
+    # A Map is responsible for:
+    # - Managing the geographic extent (bounding box + zoom)
+    # - Fetching and compositing basemap tiles
+    # - Managing semantic feature layers
+    # - Managing generic overlay layers (points, lines, polygons)
+    # - Executing the rendering pipeline
+    #
+    # The map can render either:
+    # - A full tile-based image, or
+    # - A fixed-size viewport clipped from the basemap
+    #
     class Map
+      # Tile size in pixels (Web Mercator standard)
       TILE_SIZE = 256
 
+      # @return [GD::Image, nil] rendered image
       attr_reader :image
+
+      # @return [Hash<Symbol, Array>] semantic feature layers
       attr_reader :layers
+
+      # @return [Object, nil] style object
       attr_accessor :style
 
+      # @return [Boolean] enables debug rendering
+      attr_reader :debug
+
+      # Creates a new map.
+      #
+      # @param bbox [Array<Float>]
+      #   bounding box [min_lng, min_lat, max_lng, max_lat]
+      # @param zoom [Integer]
+      #   zoom level
+      # @param basemap [Symbol]
+      #   basemap provider identifier
+      # @param width [Integer, nil]
+      #   viewport width in pixels
+      # @param height [Integer, nil]
+      #   viewport height in pixels
+      # @param crs [String, Symbol, nil]
+      #   input CRS identifier
+      # @param fitted_bbox [Boolean]
+      #   whether the provided bbox is already viewport-fitted
+      #
+      # @raise [ArgumentError] if parameters are invalid
       def initialize(
         bbox:,
         zoom:,
@@ -24,27 +67,21 @@ module GD
         width: nil,
         height: nil,
         crs: nil,
-	      fitted_bbox: false
+        fitted_bbox: false
       )
-        # --------------------------------------------------
         # 1. Basic input validation
-        # --------------------------------------------------
         raise ArgumentError, "bbox must be [min_lng, min_lat, max_lng, max_lat]" unless
           bbox.is_a?(Array) && bbox.size == 4
 
         raise ArgumentError, "zoom must be an Integer" unless zoom.is_a?(Integer)
 
-        if (width && !height) || (!width && height)
-          raise ArgumentError, "width and height must be provided together"
-        end
+        raise ArgumentError, "width and height must be provided together" if (width && !height) || (!width && height)
 
         @zoom   = zoom
         @width  = width
         @height = height
 
-        # --------------------------------------------------
         # 2. CRS normalization (input → WGS84 lon/lat)
-        # --------------------------------------------------
         if crs
           normalizer = GD::GIS::CRS::Normalizer.new(crs)
 
@@ -54,9 +91,7 @@ module GD
           bbox = [min_lng, min_lat, max_lng, max_lat]
         end
 
-        # --------------------------------------------------
         # 3. Final bbox (viewport-aware if width/height)
-        # --------------------------------------------------
         @bbox =
           if width && height && !fitted_bbox
             GD::GIS::Geometry.viewport_bbox(
@@ -69,14 +104,10 @@ module GD
             bbox
           end
 
-        # --------------------------------------------------
         # 4. Basemap (uses FINAL bbox)
-        # --------------------------------------------------
         @basemap = GD::GIS::Basemap.new(zoom, @bbox, basemap)
 
-        # --------------------------------------------------
         # 5. Legacy semantic layers (REQUIRED by render)
-        # --------------------------------------------------
         @layers = {
           motorway:  [],
           primary:   [],
@@ -91,21 +122,22 @@ module GD
         # Optional alias (semantic clarity, no behavior change)
         @road_layers = @layers
 
-        # --------------------------------------------------
         # 6. Overlay layers (generic)
-        # --------------------------------------------------
         @points_layers   = []
         @lines_layers    = []
         @polygons_layers = []
 
-        # --------------------------------------------------
         # 7. Style
-        # --------------------------------------------------
         @style = nil
 
-	      @debug = false
+        @debug = false
+        @used_labels = {}
       end
 
+      # Returns all features belonging to a given semantic layer.
+      #
+      # @param layer [Symbol]
+      # @return [Array<Feature>]
       def features_by_layer(layer)
         return [] unless @layers[layer]
 
@@ -114,25 +146,68 @@ module GD
         end
       end
 
+      # Returns all features in the map.
+      #
+      # @return [Array<Feature>]
       def features
         @layers.values.flatten.map do |item|
           item.is_a?(Array) ? item.last : item
         end
       end
 
-      # -----------------------------------
-      # GeoJSON input (unchanged behavior)
-      # -----------------------------------
+      def maybe_create_line_label(feature)
+        geom = feature.geometry
+        return unless LINE_GEOMS.include?(geom["type"])
+
+        name = feature.properties["name"]
+        return if name.nil? || name.empty?
+
+        key = feature.properties["wikidata"] || name
+        return if @used_labels[key]
+
+        coords = geom["coordinates"]
+        coords = coords.flatten(1) if geom["type"] == "MultiLineString"
+        return if coords.size < 2
+
+        lon, lat = coords[coords.size / 2]
+
+	puts @style
+
+        @points_layers << GD::GIS::PointsLayer.new(
+          [feature],
+          lon:   ->(_) { lon },
+          lat:   ->(_) { lat },
+	        icon: nil,
+          label: ->(_) { name },
+      	  font:  GD::GIS::FontHelper.random,
+      	  size:  10,
+      	  color: GD::Color.rgb(0, 0, 0)
+        )
+
+        @used_labels[key] = true
+      end
+
+      # Loads features from a GeoJSON file.
+      #
+      # This method:
+      # - Normalizes CRS
+      # - Classifies features into semantic layers
+      # - Creates overlay layers when needed (points)
+      #
+      # @param path [String] path to GeoJSON file
+      # @return [void]
       def add_geojson(path)
         features = LayerGeoJSON.load(path)
 
         features.each do |feature|
+          maybe_create_line_label(feature)
+
           case feature.layer
           when :water
             kind =
               case (feature.properties["objeto"] || feature.properties["waterway"]).to_s.downcase
-              when /river|río/     then :river
-              when /stream|arroyo/ then :stream
+              when /river|río|canal/	then :river
+              when /stream|arroyo/ 	then :stream
               else :minor
               end
 
@@ -146,35 +221,86 @@ module GD
 
           when :track
             # elegí una:
-            @layers[:minor]  << feature
+            @layers[:minor] << feature
             # o @layers[:street] << feature
           else
             geom_type = feature.geometry["type"]
-            if geom_type == "LineString" || geom_type == "MultiLineString"
+
+            if geom_type == "Point"
+              points_style = @style.points || begin
+                warn "Style error: missing 'points' section"
+              end
+
+              font = points_style[:font] || begin
+                warn "[libgd-gis] points.font not defined in style, using random system font"
+                GD::GIS::FontHelper.random
+              end
+
+              size = points_style[:size] || begin
+                warn "[libgd-gis] points.font size not defined in style, using random system font size"
+                (6..14).to_a.sample
+              end
+
+              raw_color = points_style[:color]
+              color = @style.normalize_color(raw_color)
+
+              icon  = if points_style.key?(:icon_fill) && points_style.key?(:icon_stroke)
+                        [points_style[:icon_stroke],
+                         points_style[:icon_stroke]]
+                      end
+              icon  = points_style.key?(:icon) ? points_style[:icon] : nil if icon.nil?
+
+              @points_layers << GD::GIS::PointsLayer.new(
+                [feature],
+                lon:   ->(f) { f.geometry["coordinates"][0] },
+                lat:   ->(f) { f.geometry["coordinates"][1] },
+                icon:  icon,
+                label: ->(f) { f.properties["name"] },
+                font:  font,
+                size:  size,
+                color: color
+              )
+            elsif LINE_GEOMS.include?(geom_type)
               @layers[:minor] << feature
             end
           end
         end
       end
 
-      # -----------------------------------
-      # Overlay layers
-      # -----------------------------------
+      # Adds a generic points overlay layer.
+      #
+      # @param data [Enumerable]
+      # @param opts [Hash]
+      # @return [void]
       def add_points(data, **opts)
         @points_layers << GD::GIS::PointsLayer.new(data, **opts)
       end
 
+      # Adds a generic lines overlay layer.
+      #
+      # @param features [Array]
+      # @param opts [Hash]
+      # @return [void]
       def add_lines(features, **opts)
         @lines_layers << GD::GIS::LinesLayer.new(features, **opts)
       end
 
+      # Adds a generic polygons overlay layer.
+      #
+      # @param polygons [Array]
+      # @param opts [Hash]
+      # @return [void]
       def add_polygons(polygons, **opts)
         @polygons_layers << GD::GIS::PolygonsLayer.new(polygons, **opts)
       end
 
-      # -----------------------------------
-      # Rendering (LEGACY, UNCHANGED)
-      # -----------------------------------
+      # Renders the map.
+      #
+      # Chooses between tile rendering and viewport rendering
+      # depending on whether width and height are set.
+      #
+      # @return [void]
+      # @raise [RuntimeError] if style is not set
       def render
         raise "map.style must be set" unless @style
 
@@ -184,7 +310,7 @@ module GD
           render_tiles
         end
       end
-      
+
       def render_tiles
         raise "map.style must be set" unless @style
 
@@ -221,12 +347,12 @@ module GD
           [(x - origin_x).round, (y - origin_y).round]
         end
 
-        # 1️⃣ GeoJSON semantic layers
+        # 1. GeoJSON semantic layers
         @style.order.each do |kind|
           draw_layer(kind, projection)
         end
 
-        # 2️⃣ Generic overlays
+        # 2. Generic overlays
         @polygons_layers.each { |l| l.render!(@image, projection) }
         @lines_layers.each    { |l| l.render!(@image, projection) }
         @points_layers.each   { |l| l.render!(@image, projection) }
@@ -238,22 +364,16 @@ module GD
         @image = GD::Image.new(@width, @height)
         @image.antialias = false
 
-        # --------------------------------------------------
         # 1. Compute global pixel bbox
-        # --------------------------------------------------
         min_lng, min_lat, max_lng, max_lat = @bbox
 
         x1, y1 = GD::GIS::Projection.lonlat_to_global_px(min_lng, max_lat, @zoom)
-        x2, y2 = GD::GIS::Projection.lonlat_to_global_px(max_lng, min_lat, @zoom)
+        GD::GIS::Projection.lonlat_to_global_px(max_lng, min_lat, @zoom)
 
-        # --------------------------------------------------
         # 2. Fetch tiles
-        # --------------------------------------------------
         tiles, = @basemap.fetch_tiles
 
-        # --------------------------------------------------
         # 3. Draw tiles clipped to viewport
-        # --------------------------------------------------
         tiles.each do |x, y, file|
           tile = GD::Image.open(file)
 
@@ -282,16 +402,12 @@ module GD
           )
         end
 
-        # --------------------------------------------------
         # 4. Projection (viewport version)
-        # --------------------------------------------------
         projection = lambda do |lon, lat|
           GD::GIS::Geometry.project(lon, lat, @bbox, @zoom)
         end
 
-        # --------------------------------------------------
         # 5. REUSE the same render pipeline
-        # --------------------------------------------------
         @style.order.each do |kind|
           draw_layer(kind, projection)
         end
@@ -301,10 +417,19 @@ module GD
         @points_layers.each   { |l| l.render!(@image, projection) }
       end
 
+      # Saves the rendered image to disk.
+      #
+      # @param path [String]
+      # @return [void]
       def save(path)
         @image.save(path)
       end
 
+      # Draws a semantic feature layer.
+      #
+      # @param kind [Symbol]
+      # @param projection [#call]
+      # @return [void]
       def draw_layer(kind, projection)
         items = @layers[kind]
         return if items.nil? || items.empty?
@@ -347,24 +472,20 @@ module GD
             f = item
             geom = f.geometry["type"]
 
-            if geom == "Polygon" || geom == "MultiPolygon"
+            if POLY_GEOMS.include?(geom)
               f.draw(@image, projection, nil, nil, style)
-            else
-              if style[:stroke]
-                color = GD::Color.rgb(*style[:stroke])
+            elsif style[:stroke]
+              color = GD::Color.rgb(*style[:stroke])
 
-                color = GD::GIS::ColorHelpers.random_vivid if @debug
+              color = GD::GIS::ColorHelpers.random_vivid if @debug
 
-                width = style[:stroke_width] ? style[:stroke_width].round : 1
-                width = 1 if width < 1
-                f.draw(@image, projection, color, width)
-              end
+              width = style[:stroke_width] ? style[:stroke_width].round : 1
+              width = 1 if width < 1
+              f.draw(@image, projection, color, width)
             end
           end
         end
       end
-
     end
   end
 end
-

data/lib/gd/gis/middleware.rb

@@ -1,17 +1,65 @@
+# frozen_string_literal: true
+
 module GD
   module GIS
+    # Coordinate Reference System (CRS) helpers and normalizers.
+    #
+    # This module defines commonly used CRS identifiers and
+    # utilities for normalizing coordinates into a single,
+    # consistent representation.
+    #
     module CRS
+      # OGC CRS84 (longitude, latitude)
       CRS84      = "urn:ogc:def:crs:OGC:1.3:CRS84"
+
+      # EPSG:4326 (latitude, longitude axis order)
       EPSG4326   = "EPSG:4326"
+
+      # EPSG:3857 (Web Mercator)
       EPSG3857   = "EPSG:3857"
-      GK_ARGENTINA = "EPSG:22195"   # Gauss–Krüger Argentina (zone 5 example)
 
-      # Normalize any CRS → CRS84 (lon,lat in degrees)
+      # Gauss–Krüger Argentina, zone 5
+      #
+      # Note: This constant represents a *specific* GK zone
+      # and is not a generic Gauss–Krüger definition.
+      GK_ARGENTINA = "EPSG:22195"
+
+      # Normalizes coordinates from supported CRS definitions
+      # into CRS84 (longitude, latitude in degrees).
+      #
+      # Supported input CRS:
+      # - CRS84
+      # - EPSG:4326 (axis order normalization)
+      # - EPSG:3857 (Web Mercator)
+      # - EPSG:22195 (Gauss–Krüger Argentina, zone 5)
+      #
+      # All outputs are returned as:
+      #   [longitude, latitude] in degrees
+      #
+      # ⚠️ Projection conversions are intended for mapping
+      # and visualization, not for high-precision geodesy.
+      #
       class Normalizer
+        # Creates a new CRS normalizer.
+        #
+        # @param crs [String, Symbol, nil]
+        #   CRS identifier; defaults to CRS84 if nil
         def initialize(crs)
           @crs = normalize_name(crs)
         end
 
+        # Normalizes a coordinate pair into CRS84.
+        #
+        # @param lon [Numeric]
+        #   first coordinate (meaning depends on input CRS)
+        # @param lat [Numeric]
+        #   second coordinate (meaning depends on input CRS)
+        #
+        # @return [Array<Float>]
+        #   normalized [longitude, latitude] in degrees
+        #
+        # @raise [RuntimeError]
+        #   if the CRS is not supported
         def normalize(lon, lat)
           case @crs
           when CRS84
@@ -34,52 +82,67 @@ module GD
 
         private
 
+        # Normalizes a CRS name into a comparable string.
+        #
+        # @param name [Object]
+        # @return [String]
         def normalize_name(name)
           return CRS84 if name.nil?
+
           name.to_s.strip
         end
 
-        # Web Mercator → WGS84
+        # Converts Web Mercator coordinates to WGS84.
+        #
+        # @param x [Numeric] X coordinate in meters
+        # @param y [Numeric] Y coordinate in meters
+        # @return [Array<Float>] [longitude, latitude] in degrees
         def mercator_to_wgs84(x, y)
           r = 6378137.0
           lon = (x / r) * 180.0 / Math::PI
-          lat = (2 * Math.atan(Math.exp(y / r)) - Math::PI / 2) * 180.0 / Math::PI
+          lat = ((2 * Math.atan(Math.exp(y / r))) - (Math::PI / 2)) * 180.0 / Math::PI
           [lon, lat]
         end
 
-        # Gauss–Krüger Argentina (Zone 5) → WGS84
-        # This is enough precision for mapping
+        # Converts Gauss–Krüger Argentina (zone 5) coordinates to WGS84.
+        #
+        # This implementation provides sufficient accuracy for
+        # cartographic rendering and visualization.
+        #
+        # @param easting [Numeric] easting (meters)
+        # @param northing [Numeric] northing (meters)
+        # @return [Array<Float>] [longitude, latitude] in degrees
         def gk_to_wgs84(easting, northing)
           # Parameters for Argentina GK Zone 5
           a = 6378137.0
           f = 1 / 298.257223563
-          e2 = 2*f - f*f
-          lon0 = -60.0 * Math::PI / 180.0   # central meridian zone 5
+          e2 = (2 * f) - (f * f)
+          lon0 = -60.0 * Math::PI / 180.0 # central meridian zone 5
 
           x = easting - 500000.0
           y = northing
 
           m = y
-          mu = m / (a * (1 - e2/4 - 3*e2*e2/64))
+          mu = m / (a * (1 - (e2 / 4) - (3 * e2 * e2 / 64)))
 
           e1 = (1 - Math.sqrt(1 - e2)) / (1 + Math.sqrt(1 - e2))
 
-          j1 = 3*e1/2 - 27*e1**3/32
-          j2 = 21*e1**2/16 - 55*e1**4/32
+          j1 = (3 * e1 / 2) - (27 * (e1**3) / 32)
+          j2 = (21 * (e1**2) / 16) - (55 * (e1**4) / 32)
 
-          fp = mu + j1*Math.sin(2*mu) + j2*Math.sin(4*mu)
+          fp = mu + (j1 * Math.sin(2 * mu)) + (j2 * Math.sin(4 * mu))
 
-          c1 = e2 * Math.cos(fp)**2
+          c1 = e2 * (Math.cos(fp)**2)
           t1 = Math.tan(fp)**2
-          r1 = a * (1 - e2) / (1 - e2 * Math.sin(fp)**2)**1.5
-          n1 = a / Math.sqrt(1 - e2 * Math.sin(fp)**2)
+          r1 = a * (1 - e2) / ((1 - (e2 * (Math.sin(fp)**2)))**1.5)
+          n1 = a / Math.sqrt(1 - (e2 * (Math.sin(fp)**2)))
 
           d = x / n1
 
-          lat = fp - (n1*Math.tan(fp)/r1) *
-            (d**2/2 - (5 + 3*t1 + 10*c1)*d**4/24)
+          lat = fp - ((n1 * Math.tan(fp) / r1) *
+                     (((d**2) / 2) - ((5 + (3 * t1) + (10 * c1)) * (d**4) / 24)))
 
-          lon = lon0 + (d - (1 + 2*t1 + c1)*d**3/6) / Math.cos(fp)
+          lon = lon0 + ((d - ((1 + (2 * t1) + c1) * (d**3) / 6)) / Math.cos(fp))
 
           [lon * 180.0 / Math::PI, lat * 180.0 / Math::PI]
         end

data/lib/gd/gis/ontology.rb

@@ -1,16 +1,59 @@
+# frozen_string_literal: true
+
 require "yaml"
 
 module GD
   module GIS
+    # Classifies features into semantic layers using rule-based matching.
+    #
+    # An Ontology maps feature properties to logical layer identifiers
+    # (e.g. :water, :road, :park) based on a YAML rule definition.
+    #
+    # The ontology is intentionally simple and heuristic-based:
+    # - Rules are evaluated in order
+    # - The first matching rule wins
+    # - Matching is case-insensitive and substring-based
+    #
+    # This design favors robustness and flexibility over strict
+    # schema enforcement.
+    #
     class Ontology
+      # Creates a new ontology.
+      #
+      # @param path [String, nil]
+      #   path to a YAML ontology file; defaults to `ontology.yml`
+      #   shipped with the gem
+      #
+      # @raise [Errno::ENOENT] if the file does not exist
+      # @raise [Psych::SyntaxError] if the YAML is invalid
       def initialize(path = nil)
         path ||= File.expand_path("ontology.yml", __dir__)
         @rules = YAML.load_file(path)
       end
 
-      def classify(properties)
+      # Classifies a feature into a semantic layer.
+      #
+      # Properties are matched against ontology rules using
+      # case-insensitive substring comparison.
+      #
+      # @param properties [Hash]
+      #   feature attributes / tags
+      # @param geometry_type [String, nil]
+      #   GeoJSON geometry type
+      #
+      # @return [Symbol, nil]
+      #   semantic layer identifier, or nil if no rule matches
+      #
+      # @example
+      #   ontology.classify({ "waterway" => "river" })
+      #   #=> :water
+      #
+      # @example
+      #   ontology.classify({}, geometry_type: "Point")
+      #   #=> :points
+      def classify(properties, geometry_type: nil)
         @rules.each do |layer, sources|
-          sources.each do |source, rules|
+          sources.each_value do |rules|
             rules.each do |key, values|
               v = (properties[key.to_s] || properties[key.to_sym]).to_s.strip.downcase
               values = values.map { |x| x.to_s.downcase }
@@ -19,6 +62,10 @@ module GD
             end
           end
         end
+
+        # Fallback classification
+        return :points if geometry_type == "Point"
+
         nil
       end
     end

data/lib/gd/gis/ontology.yml

@@ -1,4 +1,10 @@
 water:
+  osm:
+    waterway:
+      - river
+      - canal
+      - stream
+
   ign:
     objeto:
       - canal
@@ -26,3 +32,5 @@ track:
   gps:
     name:
       - track
+
+