libgd-gis 0.2.8 → 0.3.0

data/lib/gd/gis/layer_lines.rb

@@ -1,8 +1,23 @@
+# frozen_string_literal: true
+
 module GD
   module GIS
+    # Renders collections of line geometries onto a GD image.
+    #
+    # A LinesLayer draws simple line strings using a fixed stroke
+    # color and width. Coordinates are expected to be in
+    # [longitude, latitude] order and are projected at render time.
+    #
     class LinesLayer
+      # @return [Boolean] enables debug rendering
       attr_accessor :debug
 
+      # Creates a new lines layer.
+      #
+      # @param lines [Array<Array<Array<Float>>>]
+      #   array of line strings ([[lng, lat], ...])
+      # @param stroke [GD::Color] line color
+      # @param width [Integer] stroke width in pixels
       def initialize(lines, stroke:, width:)
         @lines  = lines
         @stroke = stroke
@@ -10,6 +25,14 @@ module GD
         @debug  = false
       end
 
+      # Renders the lines onto the given image.
+      #
+      # @param img [GD::Image] target image
+      # @param projection [#call]
+      #   callable converting (lng, lat) → (x, y)
+      #
+      # @raise [RuntimeError] if a line is invalid
+      # @return [void]
       def render!(img, projection)
         @lines.each do |line|
           raise "Invalid line: #{line.inspect}" unless valid_line?(line)
@@ -33,6 +56,10 @@ module GD
 
       private
 
+      # Validates a line string.
+      #
+      # @param line [Object]
+      # @return [Boolean]
       def valid_line?(line)
         line.is_a?(Array) &&
           line.size >= 2 &&

data/lib/gd/gis/layer_points.rb

@@ -1,16 +1,54 @@
+# frozen_string_literal: true
+
 module GD
   module GIS
+    # Renders point data as icons (markers) with optional labels.
+    #
+    # A PointsLayer draws markers for arbitrary data records.
+    # Longitude and latitude values are extracted using callables,
+    # allowing the layer to work with any data structure.
+    #
+    # Optionally, text labels can be rendered next to each marker.
+    #
     class PointsLayer
-
-      def initialize(data, lon:, lat:, icon:, label: nil, font: nil, size: 12, color: [0,0,0])
+      # Creates a new points layer.
+      #
+      # @param data [Enumerable]
+      #   collection of data records
+      # @param lon [#call]
+      #   callable extracting longitude from a data record
+      # @param lat [#call]
+      #   callable extracting latitude from a data record
+      # @param icon [String, Array<GD::Color>, nil]
+      #   path to an icon image, or [fill, stroke] colors,
+      #   or nil to generate a random marker
+      # @param label [#call, nil]
+      #   callable extracting label text from a data record
+      # @param font [String, nil]
+      #   font path used for labels
+      # @param size [Integer]
+      #   font size in pixels
+      # @param color [Array<Integer>]
+      #   label color as RGB array
+      def initialize(
+        data,
+        lon:,
+        lat:,
+        icon:,
+        label: nil,
+        font: nil,
+        size: 12,
+        color: [0, 0, 0]
+      )
         @data = data
         @lon = lon
         @lat = lat
 
-        if icon
-          @icon = GD::Image.open(icon)
+        if icon.is_a?(Array) || icon.nil?
+          fill, stroke = icon || [GD::GIS::ColorHelpers.random_rgb, GD::GIS::ColorHelpers.random_rgb]
+          @icon = build_default_marker(fill, stroke)
         else
-          @icon = build_default_marker
+          @icon = GD::Image.open(icon)
         end
 
         @label = label
@@ -22,27 +60,37 @@ module GD
         @icon.save_alpha = true
       end
 
-      def build_default_marker
+      # Builds a default circular marker icon.
+      #
+      # @param fill [GD::Color]
+      # @param stroke [GD::Color]
+      # @return [GD::Image]
+      def build_default_marker(fill, stroke)
         size = 32
+
         img = GD::Image.new(size, size)
         img.antialias = true
-        
-        white = GD::Color.rgb(255,255,255)
-        black = GD::Color.rgb(0,0,0)
 
         cx = size / 2
         cy = size / 2
-        r  = 12
+        r  = 5
 
-        # borde blanco
-        img.arc(cx, cy, r*2+4, r*2+4, 0, 360, white)
+        # stroke
+        img.arc(cx, cy, (r * 2) + 4, (r * 2) + 4, 0, 360, stroke)
 
-        # relleno negro
-        img.filled_arc(cx, cy, r*2, r*2, 0, 360, black)
+        # fill
+        img.filled_arc(cx, cy, r * 2, r * 2, 0, 360, fill)
 
         img
       end
 
+      # Renders all points onto the image.
+      #
+      # @param img [GD::Image] target image
+      # @param projector [#call]
+      #   callable converting (lon, lat) → (x, y)
+      #
+      # @return [void]
       def render!(img, projector)
         w = @icon.width
         h = @icon.height
@@ -51,26 +99,25 @@ module GD
           lon = @lon.call(row)
           lat = @lat.call(row)
 
-          x,y = projector.call(lon,lat)
+          x, y = projector.call(lon, lat)
 
           # icono
-          img.copy(@icon, x - w/2, y - h/2, 0,0,w,h)
+          img.copy(@icon, x - (w / 2), y - (h / 2), 0, 0, w, h)
 
           # etiqueta opcional
-          if @label && @font
-            text = @label.call(row)
-            unless text.nil? || text.strip.empty?
-              font_h = @size * 1.1
-
-              img.text(text,
-                x: x + w/2 + 4,
-                y: y + font_h/2,
-                size: @size,
-                color: @color,
-                font: @font
-              )
-            end
-          end
+          next unless @label && @font
+
+          text = @label.call(row)
+          next if text.nil? || text.strip.empty?
+
+          font_h = @size * 1.1
+
+          img.text(text,
+                   x: x + (w / 2) + 4,
+                   y: y + (font_h / 2),
+                   size: @size,
+                   color: @color,
+                   font: @font)
         end
       end
     end

data/lib/gd/gis/layer_polygons.rb

@@ -1,17 +1,46 @@
+# frozen_string_literal: true
+
 module GD
   module GIS
+    # Renders polygon geometries onto a GD image.
+    #
+    # A PolygonsLayer draws filled polygons with optional
+    # stroke outlines. Polygons are expected to be provided
+    # as arrays of rings in [longitude, latitude] order.
+    #
     class PolygonsLayer
+      # @return [Boolean] enables debug rendering
       attr_accessor :debug
 
+      # Creates a new polygons layer.
+      #
+      # @param polygons [Array<Array<Array<Array<Float>>>>]
+      #   array of polygons, each consisting of one or more rings
+      # @param fill [GD::Color] fill color
+      # @param stroke [GD::Color, nil] stroke color
+      # @param width [Integer, nil] stroke width in pixels
       def initialize(polygons, fill:, stroke: nil, width: nil)
         @polygons = polygons
         @fill = fill
         @stroke = stroke
         @width = width
-
-	@debug = false
+        @debug = false
       end
 
+      # Builds a polygon layer by buffering line features.
+      #
+      # This is a convenience constructor that converts
+      # line geometries into polygon buffers using a naive
+      # geometric approximation.
+      #
+      # @param features [Array<Hash>]
+      #   GeoJSON-like features with LineString geometries
+      # @param stroke [GD::Color]
+      # @param fill [GD::Color]
+      # @param width [Numeric]
+      #   buffer width (approximate)
+      #
+      # @return [PolygonsLayer]
       def self.from_lines(features, stroke:, fill:, width:)
         polys = []
 
@@ -24,6 +53,13 @@ module GD
         new(polys, fill: fill, stroke: stroke)
       end
 
+      # Renders all polygons onto the image.
+      #
+      # @param img [GD::Image] target image
+      # @param projection [#call]
+      #   callable converting (lng, lat) → (x, y)
+      #
+      # @return [void]
       def render!(img, projection)
         @polygons.each do |polygon|
           # polygon = [ ring, ring, ... ]
@@ -35,20 +71,19 @@ module GD
             @stroke = GD::GIS::ColorHelpers.random_vivid if @debug
             @fill   = GD::GIS::ColorHelpers.random_vivid if @debug
 
-            if idx == 0
+            if idx.zero?
               # ring exterior
               img.filled_polygon(pts, @fill)
             end
 
-            if @stroke
-              pts.each_cons(2) do |a, b|
-                img.line(a[0], a[1], b[0], b[1], @stroke, thickness: (@width || 1))
-              end
+            next unless @stroke
+
+            pts.each_cons(2) do |a, b|
+              img.line(a[0], a[1], b[0], b[1], @stroke, thickness: @width || 1)
             end
           end
         end
       end
-
     end
   end
 end