libgd-gis 0.2.9 → 0.3.1

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:,
@@ -26,25 +69,19 @@ module GD
         crs: nil,
         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,19 +104,16 @@ 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:   [],
           secondary: [],
           street:    [],
+          track:     [],
           minor:     [],
           rail:      [],
           water:     [],
@@ -91,21 +123,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 +147,96 @@ 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)
-      # -----------------------------------
+      # Creates a single text label for a named linear feature (LineString or
+      # MultiLineString), avoiding duplicate labels for the same named entity.
+      #
+      # Many datasets (especially OSM) split a single logical entity
+      # (rivers, streets, railways, etc.) into multiple line features that
+      # all share the same name. This method ensures that:
+      #
+      # - Only one label is created per unique entity name
+      # - The label is placed on a representative segment of the geometry
+      # - The logic is independent of the feature's semantic layer (water, road, rail)
+      #
+      # Labels are rendered using a PointsLayer because libgd-gis does not
+      # support text rendering directly on line geometries.
+      #
+      # The label position is chosen as the midpoint of the line coordinates.
+      # This is a simple heuristic that provides a reasonable placement without
+      # requiring geometry merging or topological analysis.
+      #
+      # @param feature [GD::GIS::Feature]
+      #   A feature with a linear geometry and a "name" property.
+      #
+      # @return [void]
+      #   Adds a PointsLayer to @points_layers if a label is created.
+      #
+      # @note
+      #   This method must be called during feature loading (add_geojson),
+      #   before rendering. It intentionally does not depend on map style
+      #   configuration, which is applied later during rendering.
+      def maybe_create_line_label(feature)
+        return true if @style.global[:label] == false || @style.global[:label].nil?
+
+        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]
+
+        @points_layers << GD::GIS::PointsLayer.new(
+          [feature],
+          lon:   ->(_) { lon },
+          lat:   ->(_) { lat },
+          icon: @style.global[:label][:icon],
+          label: ->(_) { name },
+          font:  @style.global[:label][:font] || GD::GIS::FontHelper.random,
+          size:  @style.global[:label][:size] || (6..20).to_a.sample,
+          color: @style.global[:label][:color] || GD::GIS::ColorHelpers.random_rgba
+        )
+
+        @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
 
@@ -145,26 +249,32 @@ module GD
             @layers[:park] << feature
 
           when :track
-            # elegí una:
-            @layers[:minor]  << feature
-            # o @layers[:street] << feature
+            @layers[:track] << feature
           else
             geom_type = feature.geometry["type"]
 
             if geom_type == "Point"
-              points_style = @style.points or
-                raise ArgumentError, "Style error: missing 'points' section"
+              points_style = @style.points || begin
+                warn "Style error: missing 'points' section"
+              end
 
-              font = points_style[:font] or
-                raise ArgumentError, "Style error: points.font is required"
+              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] or
-                raise ArgumentError, "Style error: points.size is required"
+              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  = points_style.key?(:icon_fill) && points_style.key?(:icon_stroke) ? [points_style[:icon_stroke], points_style[:icon_stroke]] : nil
+              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(
@@ -172,36 +282,52 @@ module GD
                 lon:   ->(f) { f.geometry["coordinates"][0] },
                 lat:   ->(f) { f.geometry["coordinates"][1] },
                 icon:  icon,
-                label: ->(f) { f.properties["name"] },  # 👈 TEXTO
+                label: ->(f) { f.properties["name"] },
                 font:  font,
                 size:  size,
                 color: color
               )
-            elsif geom_type == "LineString" || geom_type == "MultiLineString"
+            elsif LINE_GEOMS.include?(geom_type)
               @layers[:minor] << feature
             end
           end
         end
       end
 
-      # -----------------------------------
-      # Overlay layers
-      # -----------------------------------
-      def add_points(data, **opts)
-        @points_layers << GD::GIS::PointsLayer.new(data, **opts)
+      # Adds a generic points overlay layer.
+      #
+      # @param data [Enumerable]
+      # @param opts [Hash]
+      # @return [void]
+      def add_points(data, **)
+        @points_layers << GD::GIS::PointsLayer.new(data, **)
       end
 
-      def add_lines(features, **opts)
-        @lines_layers << GD::GIS::LinesLayer.new(features, **opts)
+      # Adds a generic lines overlay layer.
+      #
+      # @param features [Array]
+      # @param opts [Hash]
+      # @return [void]
+      def add_lines(features, **)
+        @lines_layers << GD::GIS::LinesLayer.new(features, **)
       end
 
-      def add_polygons(polygons, **opts)
-        @polygons_layers << GD::GIS::PolygonsLayer.new(polygons, **opts)
+      # Adds a generic polygons overlay layer.
+      #
+      # @param polygons [Array]
+      # @param opts [Hash]
+      # @return [void]
+      def add_polygons(polygons, **)
+        @polygons_layers << GD::GIS::PolygonsLayer.new(polygons, **)
       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
 
@@ -211,7 +337,7 @@ module GD
           render_tiles
         end
       end
-      
+
       def render_tiles
         raise "map.style must be set" unless @style
 
@@ -248,12 +374,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) }
@@ -265,22 +391,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)
 
@@ -309,16 +429,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
@@ -328,10 +444,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?
@@ -340,6 +465,8 @@ module GD
           case kind
           when :street, :primary, :motorway, :secondary, :minor
             @style.roads[kind]
+          when :track
+            @style.track[kind]
           when :rail
             @style.rails
           when :water
@@ -374,24 +501,22 @@ 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]
+              r, g, b, a = style[:stroke]
+              a = 0 if a.nil?
+              color = GD::Color.rgba(r, g, b, a)
 
-                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