libgd-gis 0.4.2 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa4dd3c210385e6b89998eeccbc88c4e82d5c45b6081be260b98843b4bd01124
-  data.tar.gz: c0e6f00da6d017e7d30f8ccc6c14b4a16ee3a5e7799d5cbf8c4a4b72b137bde6
+  metadata.gz: 12f001e0a04fd6daa74954df04a6e9a7fb0c96125dcc4abc9d86ad47e2b88c7f
+  data.tar.gz: 691682c8ba0207ab1e57f6e47b42aca5f352e99674090b0fb88082d9a01252b1
 SHA512:
-  metadata.gz: fd5c30cbcdae3f214a9f0fb9605edd1244ca161774fc6e60fabcff70688b9b3712bc7444be326fd88c5517d470bfa8c06d8bc0522ca470edc86e5608235a26e9
-  data.tar.gz: 1cfd799c2c1abfb457ad761de7b293a97b5f880ddd55cd4e02298820c91f344977ee176abf8d7da9b77594247a1c8c1a1f34db951f69f15ff00ed7748d3c4da5
+  metadata.gz: 7c211ae32a88b7c012ac235a4d00cf03b195074ebfd9a8140f2661368e0515125366e81c576f2d7e277eb38ab56f20e44c484fac8fcf44fb3ce44053d627e146
+  data.tar.gz: 245b629a1c2729a7e43d09a47c9e5833e3032699ca4d2b80479d19b9dfc44f4d14eb16261d2c0a113794ffea3e1eff029aa9cb1ed314e9e6f887c5fa16de28d9

data/README.md

@@ -27,7 +27,6 @@
 <p align="right">
   <img src="docs/images/logo-gis.png" width="160" />
 </p>
-
 ![CI](https://github.com/ggerman/libgd-gis/actions/workflows/ci.yml/badge.svg)
 [![Codacy Badge](https://api.codacy.com/project/badge/Grade/6bc3e7d6118d47e6959b16690b815909)](https://www.codacy.com/app/libgd-gis/libgd-gis?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=libgd-gis/libgd-gis&amp;utm_campaign=Badge_Grade)
 [![Test Coverage](https://coveralls.io/repos/githublibgd-gis/libgd-gis/badge.svg?branch=master)](https://coveralls.io/github/libgd-gis/libgd-gis?branch=master)
@@ -35,16 +34,46 @@
 
 ---
 
-**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.
+**libgd-gis** is a A native map rendering engine for Ruby built on **libgd**.
+
+It allows developers to generate maps, tiles, and heatmaps directly from GeoJSON using the libgd raster engine — without external services.
+
+---
+
+## Use Cases
+
+libgd-gis is useful for:
 
-This library is designed for **map visualization**, not for spatial analysis.
+- Generating static maps for Rails applications
+- Rendering GeoJSON data to PNG images
+- Creating heatmaps and geographic visualizations
+- Building internal dashboards with map outputs
+- Self-hosted alternatives to static map APIs
 
 ---
 
+## Example
+
+```ruby
+map = GD::GIS::Map.new(width: 800, height: 600)
+
+map.add_geojson("countries.geojson")
+map.add_point(lat: -34.6, lon: -58.4)
+map.render
+
+map.save("map.png")
+```
+
+![](examples/parana/parana.png)
+
+---
+
+> 🆕 **Update:** Style is no longer mandatory. Maps now render out-of-the-box using a built-in default style.
+
+---
 ## Features
 
-- Web Mercator tile rendering (OSM, CARTO, ESRI, Stamen, etc.)
+- Web Mercator map and tile rendering (OSM, CARTO, ESRI, Stamen, etc.)
 - CRS normalization (CRS84, EPSG:4326, EPSG:3857, Gauss–Krüger Argentina)
 - Layered rendering pipeline
 - YAML-based styling
@@ -54,20 +83,6 @@ This library is designed for **map visualization**, not for spatial analysis.
 
 ---
 
-## Non-Goals
-
-libgd-gis intentionally does **not** aim to be:
-
-- a spatial analysis engine
-- a replacement for PostGIS / GEOS
-- a full map server
-- a vector tile generator
-
-If you need projections beyond Web Mercator or topological correctness,
-use a full GIS stack.
-
----
-
 ## Installation
 
 Add to your Gemfile:
@@ -124,19 +139,6 @@ map.save("map.png")
 
 ---
 
-## Styles Are Mandatory
-
-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.
-
-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.
-
 ### Example:
 
 ```ruby
@@ -201,6 +203,39 @@ order:
 This design ensures predictable rendering and makes all visual decisions explicit
 and reproducible.
 
+![](examples/paris/paris.png)
+
+
+---
+
+
+## Named geographic extents
+
+LibGD-GIS includes a global dataset of predefined geographic areas.
+You can use them directly as the `bbox` parameter.
+
+![](examples/legend/example_parana_polaroid.png)
+
+### 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
+```
 
 ---
 

data/lib/gd/gis/bbox_resolver.rb

@@ -1,5 +1,20 @@
+# 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
@@ -12,16 +27,16 @@ module GD
 
         else
           raise ArgumentError,
-            "bbox must be Symbol, String or [min_lng, min_lat, max_lng, max_lat]"
+                "bbox must be Symbol, String or [min_lng, min_lat, max_lng, max_lat]"
         end
       end
 
       def self.validate!(bbox)
-        unless bbox.is_a?(Array) && bbox.size == 4
-          raise ArgumentError,
-            "bbox must be [min_lng, min_lat, max_lng, max_lat]"
-        end
+        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
+end

data/lib/gd/gis/extents.rb

@@ -1,7 +1,24 @@
+# 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",
@@ -31,9 +48,10 @@ module GD
 
         def load_data!
           return if @extents
+
           @extents = JSON.parse(File.read(DATA_PATH))
         end
       end
     end
   end
-end
+end

data/lib/gd/gis/map.rb

@@ -132,9 +132,6 @@ module GD
         @lines_layers    = []
         @polygons_layers = []
 
-        # 7. Style
-        @style = nil
-
         @debug = false
         @used_labels = {}
         @count = 1
@@ -190,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
@@ -215,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
@@ -237,6 +236,7 @@ module GD
       end
 
       def draw_legend
+        @style ||= GD::GIS::Style.default
         return unless @legend
         return unless @image
         return unless @style
@@ -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,6 +483,8 @@ module GD
           label: label
         }
 
+        @style ||= GD::GIS::Style.default
+
         @points_layers << GD::GIS::PointsLayer.new(
           [row],
           lon: ->(r) { r[:lon] },
@@ -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

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: {
+              color: [229, 231, 235],
+              font: GD::GIS::FontHelper.find("DejaVuSans"),
+              size: 12
+            }
+          },
+
+          roads: {
+            roads: {
+              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: {
+              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,12 +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.2
+  version: 0.4.4
 platform: ruby
 authors:
 - Germán Alberto Giménez Silva