libgd-gis 0.4.1 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff2a73817209bdd6e71f77b83cd0f7ffaee27327e95c199e01bf9eb879b2ff53
-  data.tar.gz: d5fe87d75561eba31a1cae4c46902a16dfcd9a70b525f8d6772682f05f1f9c56
+  metadata.gz: 8fdfcd8c25a4c2d5be9f69153957d4d3c5fbd2b82e26167554be17c7e0ff058c
+  data.tar.gz: 9b5b504f06e11d6a0ac465747237e8832986234bee3ded81f0360a5c6749d29f
 SHA512:
-  metadata.gz: a9e41b51e0e1365eb60905131e2766981de954d74b92b16ba8abb45224e3c6df9215a96628cf23f7c90c6675d2acf98dbafe326c569ee45440dcedd1502f5d7d
-  data.tar.gz: d2598e4392ee4c400a0cf2982d91916119222f9ec4dd869b4851d0b994a0a241f39ef483e720d66121fd070af3b4ba5c46068d2194d8a09b9ed4b61cfa259192
+  metadata.gz: 7ded6603953b5144db8794841f6c898aea15819960b8d1a3b89c46e7122e74bf7c0e344814a983d5fbede7f4472080dc39ea360743d6d73d24c82d31371e5dcc
+  data.tar.gz: 2a2b7f255b78b338e128d9a2a0bd293db0936da7a30cfdb94e710c541251937c798504b9f5c20fd5ccabb8845c10fc29a47878d886a723e0a66f3ce25effd4aa

data/README.md

@@ -202,6 +202,35 @@ This design ensures predictable rendering and makes all visual decisions explici
 and reproducible.
 
 
+---
+
+
+## Named geographic extents
+
+LibGD-GIS includes a global dataset of predefined geographic areas.
+You can use them directly as the `bbox` parameter.
+
+### Example
+
+```ruby
+map = GD::GIS::Map.new(
+  bbox: :argentina,
+  zoom: 5,
+  width: 800,
+  height: 600,
+  basemap: :osm
+)
+```
+You can also use continents or regions:
+
+```
+bbox: :world
+bbox: :europe
+bbox: :south_america
+bbox: :north_america
+bbox: :asia
+```
+
 ---
 
 ## CRS Support

data/lib/gd/gis/bbox_resolver.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module GD
+  module GIS
+    # Resolves bounding box inputs into a normalized WGS84 bbox array.
+    #
+    # Accepts:
+    # - Symbol or String referencing a named extent (e.g. :world, :argentina)
+    # - Array in the form [min_lng, min_lat, max_lng, max_lat]
+    #
+    # Returns a 4-element array of Float values.
+    #
+    # @example Using a named extent
+    #   BBoxResolver.resolve(:europe)
+    #
+    # @example Using a raw bbox
+    #   BBoxResolver.resolve([-10, 35, 5, 45])
+    module BBoxResolver
+      def self.resolve(bbox)
+        case bbox
+        when Symbol, String
+          Extents.fetch(bbox)
+
+        when Array
+          validate!(bbox)
+          bbox.map(&:to_f)
+
+        else
+          raise ArgumentError,
+                "bbox must be Symbol, String or [min_lng, min_lat, max_lng, max_lat]"
+        end
+      end
+
+      def self.validate!(bbox)
+        return if bbox.is_a?(Array) && bbox.size == 4
+
+        raise ArgumentError,
+              "bbox must be [min_lng, min_lat, max_lng, max_lat]"
+      end
+    end
+  end
+end

data/lib/gd/gis/data/extents_global.json

@@ -0,0 +1,95 @@
+{
+  "world": [-180.0, -90.0, 180.0, 90.0],
+
+  "northern_hemisphere": [-180.0, 0.0, 180.0, 90.0],
+  "southern_hemisphere": [-180.0, -90.0, 180.0, 0.0],
+  "eastern_hemisphere": [0.0, -90.0, 180.0, 90.0],
+  "western_hemisphere": [-180.0, -90.0, 0.0, 90.0],
+
+  "africa": [-25.0, -35.0, 51.0, 38.0],
+  "antarctica": [-180.0, -90.0, 180.0, -60.0],
+  "asia": [26.0, -11.0, 169.0, 78.0],
+  "europe": [-31.0, 34.0, 39.0, 72.0],
+  "north_america": [-168.0, 7.0, -52.0, 83.0],
+  "south_america": [-82.0, -56.0, -34.0, 13.0],
+  "oceania": [110.0, -50.0, 180.0, 0.0],
+
+  "argentina": [-73.6, -55.1, -53.6, -21.7],
+  "bolivia": [-69.7, -22.9, -57.5, -9.7],
+  "brazil": [-74.0, -34.0, -34.0, 5.3],
+  "chile": [-75.6, -56.0, -66.4, -17.5],
+  "colombia": [-79.0, -4.2, -66.9, 13.5],
+  "ecuador": [-81.0, -5.0, -75.0, 1.5],
+  "guyana": [-61.4, 1.2, -56.5, 8.6],
+  "paraguay": [-62.6, -27.6, -54.3, -19.3],
+  "peru": [-81.4, -18.4, -68.7, -0.0],
+  "suriname": [-58.1, 1.8, -53.9, 6.0],
+  "uruguay": [-58.4, -35.0, -53.1, -30.1],
+  "venezuela": [-73.4, 0.6, -59.8, 12.2],
+
+  "canada": [-141.0, 41.0, -52.6, 83.1],
+  "united_states": [-125.0, 24.0, -66.9, 49.4],
+  "mexico": [-118.4, 14.5, -86.7, 32.7],
+  "greenland": [-73.0, 59.8, -12.2, 83.6],
+
+  "iceland": [-24.5, 63.3, -13.5, 66.6],
+  "ireland": [-10.5, 51.4, -6.0, 55.5],
+  "united_kingdom": [-8.6, 49.8, 1.8, 60.9],
+  "portugal": [-9.6, 36.9, -6.2, 42.2],
+  "spain": [-9.5, 35.9, 3.3, 43.8],
+  "france": [-5.2, 41.3, 9.6, 51.1],
+  "belgium": [2.5, 49.5, 6.4, 51.5],
+  "netherlands": [3.3, 50.7, 7.2, 53.7],
+  "germany": [5.9, 47.3, 15.0, 55.1],
+  "switzerland": [5.9, 45.8, 10.5, 47.8],
+  "italy": [6.6, 36.6, 18.5, 47.1],
+  "austria": [9.5, 46.4, 17.2, 49.0],
+  "poland": [14.1, 49.0, 24.1, 54.8],
+  "czechia": [12.1, 48.5, 18.9, 51.1],
+  "hungary": [16.1, 45.7, 22.9, 48.6],
+  "greece": [19.4, 34.8, 28.2, 41.8],
+  "norway": [4.9, 58.0, 31.3, 71.2],
+  "sweden": [11.1, 55.3, 24.2, 69.1],
+  "finland": [20.6, 59.8, 31.6, 70.1],
+  "denmark": [8.0, 54.5, 12.7, 57.8],
+
+  "turkey": [26.0, 36.0, 45.0, 42.1],
+  "russia": [19.0, 41.0, 180.0, 82.0],
+
+  "saudi_arabia": [34.5, 16.3, 55.7, 32.2],
+  "iran": [44.0, 25.0, 63.3, 39.8],
+  "iraq": [38.8, 29.0, 48.6, 37.4],
+  "israel": [34.2, 29.5, 35.9, 33.3],
+  "jordan": [34.9, 29.2, 39.3, 33.4],
+  "syria": [35.7, 32.3, 42.4, 37.3],
+
+  "india": [68.1, 6.5, 97.4, 35.5],
+  "pakistan": [60.9, 23.7, 77.8, 37.1],
+  "bangladesh": [88.0, 20.7, 92.7, 26.6],
+  "china": [73.5, 18.1, 135.1, 53.6],
+  "mongolia": [87.7, 41.6, 119.9, 52.1],
+  "japan": [129.4, 31.0, 145.8, 45.5],
+  "south_korea": [125.0, 33.1, 131.9, 38.6],
+  "north_korea": [124.0, 37.7, 130.7, 43.0],
+
+  "thailand": [97.3, 5.6, 105.6, 20.5],
+  "vietnam": [102.1, 8.2, 109.5, 23.4],
+  "malaysia": [99.6, 0.8, 119.3, 7.4],
+  "indonesia": [95.0, -11.0, 141.0, 6.0],
+  "philippines": [116.9, 4.6, 126.6, 21.2],
+
+  "egypt": [24.7, 22.0, 36.9, 31.7],
+  "libya": [9.3, 19.5, 25.1, 33.2],
+  "algeria": [-8.7, 19.0, 12.0, 37.1],
+  "morocco": [-13.2, 27.7, -1.0, 35.9],
+  "tunisia": [7.5, 30.2, 11.6, 37.3],
+
+  "nigeria": [2.7, 4.2, 14.7, 13.9],
+  "ethiopia": [32.9, 3.4, 47.9, 14.9],
+  "kenya": [33.9, -4.7, 41.9, 5.0],
+  "south_africa": [16.4, -34.8, 32.9, -22.1],
+
+  "australia": [112.9, -43.7, 153.6, -10.7],
+  "new_zealand": [166.4, -47.3, 178.6, -34.4],
+  "papua_new_guinea": [140.8, -11.7, 156.0, -1.4]
+}

data/lib/gd/gis/extents.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "json"
+
+module GD
+  module GIS
+    # Provides access to predefined geographic extents loaded from
+    # a JSON dataset.
+    #
+    # Extents are WGS84 bounding boxes defined as:
+    # [min_lng, min_lat, max_lng, max_lat]
+    #
+    # Supports lookup by symbolic name.
+    #
+    # @example Fetch extent
+    #   Extents.fetch(:world)
+    #
+    # @example Using bracket syntax
+    #   Extents[:argentina]
+    #
+    # @note Bounding boxes are approximate and intended for visualization.
+    module Extents
+      DATA_PATH = File.expand_path(
+        "data/extents_global.json",
+        __dir__
+      )
+
+      @extents = nil
+
+      class << self
+        def fetch(name)
+          load_data!
+          @extents.fetch(name.to_s.downcase) do
+            raise ArgumentError, "Unknown extent: #{name}"
+          end
+        end
+
+        def [](name)
+          fetch(name)
+        end
+
+        def all
+          load_data!
+          @extents.keys.map(&:to_sym)
+        end
+
+        private
+
+        def load_data!
+          return if @extents
+
+          @extents = JSON.parse(File.read(DATA_PATH))
+        end
+      end
+    end
+  end
+end

data/lib/gd/gis/layer_points.rb

@@ -101,16 +101,15 @@ module GD
       #
       # @return [void]
       def render!(img, projector)
-        value = case @icon
-                when "numeric"
-                  @symbol
-                when "alphabetic"
-                  (@symbol + 96).chr
-                when "symbol"
-                  @symbol
-                else
-                  @icon
-                end
+        value =
+          case @icon
+          when "numeric", "symbol"
+            @symbol
+          when "alphabetic"
+            (@symbol + 96).chr
+          else
+            @icon
+          end
 
         if @icon.is_a?(GD::Image)
           w = @icon.width
@@ -176,7 +175,7 @@ module GD
         # baseline  = top_y + h = y + h/2
         text_x = (x - (w / 2.0)).round
         text_y = (y + (h / 2.0)).round
-        
+
         # 4) Draw number
         img.text(
           text,

data/lib/gd/gis/legend.rb

@@ -1,9 +1,27 @@
-# lib/libgd/gis/legend.rb
+# lib/gd/gis/legend.rb
 
 module GD
   module GIS
     LegendItem = Struct.new(:color, :label)
 
+    # Represents a map legend rendered as part of the final image.
+    #
+    # A Legend provides visual context for map elements by associating
+    # colors or symbols with human-readable labels.
+    #
+    # Legends are rendered server-side and embedded directly into the
+    # resulting map image, allowing the map to be self-explanatory
+    # without relying on external UI components.
+    #
+    # A Legend is typically created and configured via {Map#legend}
+    # and rendered automatically during the map rendering pipeline.
+    #
+    # @example Creating a legend
+    #   map.legend do |l|
+    #     l.add [76, 175, 80, 0], "Delivered"
+    #     l.add [255, 193, 7, 0], "In transit"
+    #     l.add [244, 67, 54, 0], "Delayed"
+    #
     class Legend
       attr_reader :items, :position
 

data/lib/gd/gis/map.rb

@@ -43,8 +43,6 @@ module GD
       # @return [Boolean] enables debug rendering
       attr_reader :debug
 
-      attr_reader :legend
-
       # Creates a new map.
       #
       # @param bbox [Array<Float>]
@@ -72,6 +70,9 @@ module GD
         crs: nil,
         fitted_bbox: false
       )
+        # resolve symbolic bbox
+        bbox = GD::GIS::BBoxResolver.resolve(bbox)
+
         # 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
@@ -131,9 +132,6 @@ module GD
         @lines_layers    = []
         @polygons_layers = []
 
-        # 7. Style
-        @style = nil
-
         @debug = false
         @used_labels = {}
         @count = 1
@@ -189,6 +187,7 @@ module GD
       #   before rendering. It intentionally does not depend on map style
       #   configuration, which is applied later during rendering.
       def maybe_create_line_label(feature)
+        @style ||= GD::GIS::Style.default
         return true if @style.global[:label] == false || @style.global[:label].nil?
 
         geom = feature.geometry
@@ -214,7 +213,8 @@ module GD
           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
+          color: @style.global[:label][:color] || GD::GIS::ColorHelpers.random_rgba,
+          font_color: @style.global[:label][:color] || GD::GIS::ColorHelpers.random_rgba
         )
 
         @used_labels[key] = true
@@ -230,11 +230,13 @@ module GD
 
         layers.each do |layer|
           next unless layer.respond_to?(:color)
+
           @legend.add(layer.color, layer.name)
         end
       end
 
       def draw_legend
+        @style ||= GD::GIS::Style.default
         return unless @legend
         return unless @image
         return unless @style
@@ -272,8 +274,8 @@ module GD
           w
         end
 
-        width  = (text_widths.max || 0) + box_size + padding * 3
-        height = @legend.items.size * line_height + padding * 2
+        width  = (text_widths.max || 0) + box_size + (padding * 3)
+        height = (@legend.items.size * line_height) + (padding * 2)
 
         # --- position --------------------------------------------
 
@@ -285,8 +287,6 @@ module GD
             [margin, @image.height - height - margin]
           when :top_right
             [@image.width - width - margin, margin]
-          when :top_left
-            [margin, margin]
           else
             [margin, margin]
           end
@@ -302,7 +302,7 @@ module GD
         # --- items -----------------------------------------------
 
         @legend.items.each_with_index do |item, idx|
-          iy = y + padding + idx * line_height
+          iy = y + padding + (idx * line_height)
 
           # color box
           @image.filled_rectangle(
@@ -335,6 +335,7 @@ module GD
       # @param path [String] path to GeoJSON file
       # @return [void]
       def add_geojson(path)
+        @style ||= GD::GIS::Style.default
         features = LayerGeoJSON.load(path)
 
         features.each do |feature|
@@ -482,12 +483,14 @@ module GD
           label: label
         }
 
+        @style ||= GD::GIS::Style.default
+
         @points_layers << GD::GIS::PointsLayer.new(
           [row],
-          lon: -> r { r[:lon] },
-          lat: -> r { r[:lat] },
+          lon: ->(r) { r[:lon] },
+          lat: ->(r) { r[:lat] },
           icon: icon || @style.point[:icon],
-          label: label ? -> r { r[:label] } : nil,
+          label: label ? ->(r) { r[:label] } : nil,
           font: font || @style.point[:font],
           size: size || @style.point[:size],
           color: color || @style.point[:color],
@@ -502,6 +505,7 @@ module GD
       # @param opts [Hash]
       # @return [void]
       def add_points(data, **)
+        @style ||= GD::GIS::Style.default
         @points_layers << GD::GIS::PointsLayer.new(data, **)
       end
 
@@ -511,6 +515,7 @@ module GD
       # @param opts [Hash]
       # @return [void]
       def add_lines(features, **)
+        @style ||= GD::GIS::Style.default
         @lines_layers << GD::GIS::LinesLayer.new(features, **)
       end
 
@@ -520,6 +525,7 @@ module GD
       # @param opts [Hash]
       # @return [void]
       def add_polygons(polygons, **)
+        @style ||= GD::GIS::Style.default
         @polygons_layers << GD::GIS::PolygonsLayer.new(polygons, **)
       end
 
@@ -531,6 +537,7 @@ module GD
       # @return [void]
       # @raise [RuntimeError] if style is not set
       def render
+        # Style assign DEFAULT Styles
         raise "map.style must be set" unless @style
 
         if @width && @height
@@ -585,7 +592,7 @@ module GD
         @polygons_layers.each { |l| l.render!(@image, projection) }
         @lines_layers.each    { |l| l.render!(@image, projection) }
         @points_layers.each   { |l| l.render!(@image, projection) }
-        
+
         draw_legend
       end
 
@@ -646,7 +653,7 @@ module GD
         @polygons_layers.each { |l| l.render!(@image, projection) }
         @lines_layers.each    { |l| l.render!(@image, projection) }
         @points_layers.each   { |l| l.render!(@image, projection) }
-        
+
         draw_legend
       end
 

data/lib/gd/gis/style.rb

@@ -110,6 +110,80 @@ module GD
         end
       end
 
+      # Returns a built-in default style so Map can render even if no external style is set.
+      #
+      # @return [Style]
+      def self.default
+        new({
+              global: {
+                background: [15, 23, 42],
+                font: GD::GIS::FontHelper.find("DejaVuSans"),
+                font_color: [243, 244, 246],
+                label: {
+                  color: [229, 231, 235],
+                  font: GD::GIS::FontHelper.find("DejaVuSans"),
+                  size: 12
+                }
+              },
+
+          label: {
+            label: {   # ← envolver
+              color: [229, 231, 235],
+              font: GD::GIS::FontHelper.find("DejaVuSans"),
+              size: 12
+            }
+          },
+
+          roads: {
+            roads: {   # ← envolver
+              color: [229, 231, 235],
+              font: GD::GIS::FontHelper.find("DejaVuSans"),
+              width: 6
+            }
+          },
+
+          rails: {
+            rails: {
+              color: [156, 163, 175],
+              font: GD::GIS::FontHelper.find("DejaVuSans"),
+              width: 5
+            }
+          },
+
+          water: {
+            water: {
+              color: [59, 130, 246]
+            }
+          },
+
+          parks: {
+            parks: {
+              color: [34, 197, 94]
+            }
+          },
+
+          points: {
+            points: {
+              color: [239, 68, 68],
+              radius: 4,
+              font: GD::GIS::FontHelper.find("DejaVuSans"),
+              font_color: [243, 244, 246]
+            }
+          },
+
+          track: {
+            track: {   # ← CLAVE
+              stroke: [0, 85, 127, 250],
+              color: [250, 204, 21],
+              width: 2,
+              font_color: [243, 244, 246]
+            }
+          },
+
+          order: %i[water parks rails roads points track]
+            })
+      end
+
       # Normalizes a color definition into a GD::Color.
       #
       # Accepted formats:

data/lib/gd/gis.rb

@@ -29,9 +29,11 @@ require "gd"
 #
 require_relative "gis/color_helpers"
 require_relative "gis/font_helper"
-require_relative "gis/style"
 require_relative "gis/classifier"
+require_relative "gis/style"
 
+require_relative "gis/extents"
+require_relative "gis/bbox_resolver"
 require_relative "gis/feature"
 require_relative "gis/map"
 require_relative "gis/basemap"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: libgd-gis
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.3
 platform: ruby
 authors:
 - Germán Alberto Giménez Silva
@@ -40,9 +40,12 @@ files:
 - README.md
 - lib/gd/gis.rb
 - lib/gd/gis/basemap.rb
+- lib/gd/gis/bbox_resolver.rb
 - lib/gd/gis/classifier.rb
 - lib/gd/gis/color_helpers.rb
 - lib/gd/gis/crs_normalizer.rb
+- lib/gd/gis/data/extents_global.json
+- lib/gd/gis/extents.rb
 - lib/gd/gis/feature.rb
 - lib/gd/gis/font_helper.rb
 - lib/gd/gis/geometry.rb