libgd-gis 0.2.9 → 0.3.1

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
 
+      # 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 }
@@ -20,11 +63,11 @@ module GD
           end
         end
 
+        # Fallback classification
         return :points if geometry_type == "Point"
 
         nil
       end
-
     end
   end
 end

data/lib/gd/gis/ontology.yml

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

data/lib/gd/gis/projection.rb

@@ -1,36 +1,86 @@
+# frozen_string_literal: true
+
 module GD
   module GIS
+    # Projection helpers for Web Mercator–based maps.
+    #
+    # This module provides low-level projection utilities used
+    # throughout the rendering pipeline to convert geographic
+    # coordinates (longitude, latitude) into projected and pixel
+    # coordinates.
+    #
+    # All longitude and latitude values are assumed to be in
+    # WGS84 (EPSG:4326).
+    #
     module Projection
+      # Earth radius used for Web Mercator (meters)
       R = 6378137.0
 
+      # Converts longitude to Web Mercator X coordinate.
+      #
+      # @param lon [Float] longitude in degrees
+      # @return [Float] X coordinate in meters
       def self.mercator_x(lon)
         lon * Math::PI / 180.0 * R
       end
 
+      # Converts latitude to Web Mercator Y coordinate.
+      #
+      # @param lat [Float] latitude in degrees
+      # @return [Float] Y coordinate in meters
       def self.mercator_y(lat)
-        Math.log(Math.tan(Math::PI/4 + lat * Math::PI / 360.0)) * R
+        Math.log(Math.tan((Math::PI / 4) + (lat * Math::PI / 360.0))) * R
       end
 
+      # Projects geographic coordinates into pixel space
+      # relative to a bounding box.
+      #
+      # This method is typically used for viewport-based rendering
+      # where a fixed image size is mapped to a geographic extent.
+      #
+      # @param lon [Float] longitude in degrees
+      # @param lat [Float] latitude in degrees
+      # @param min_x [Float] minimum Web Mercator X (meters)
+      # @param max_x [Float] maximum Web Mercator X (meters)
+      # @param min_y [Float] minimum Web Mercator Y (meters)
+      # @param max_y [Float] maximum Web Mercator Y (meters)
+      # @param width [Integer] image width in pixels
+      # @param height [Integer] image height in pixels
+      #
+      # @return [Array<Integer>] pixel coordinates [x, y]
       def self.lonlat_to_pixel(lon, lat, min_x, max_x, min_y, max_y, width, height)
         x = mercator_x(lon)
         y = mercator_y(lat)
 
         px = (x - min_x) / (max_x - min_x) * width
-        py = height - (y - min_y) / (max_y - min_y) * height
+        py = height - ((y - min_y) / (max_y - min_y) * height)
 
         [px.to_i, py.to_i]
       end
 
+      # Web Mercator tile size in pixels
       TILE_SIZE = 256
 
+      # Converts geographic coordinates to global pixel coordinates.
+      #
+      # This method implements the standard XYZ / Web Mercator
+      # tiling scheme used by most web map providers.
+      #
+      # Latitude values are clamped to the valid Web Mercator range.
+      #
+      # @param lon [Float] longitude in degrees
+      # @param lat [Float] latitude in degrees
+      # @param zoom [Integer] zoom level
+      #
+      # @return [Array<Float>] global pixel coordinates [x, y]
       def self.lonlat_to_global_px(lon, lat, zoom)
-        lat = [[lat, 85.05112878].min, -85.05112878].max
-        n = 2.0 ** zoom
+        lat = lat.clamp(-85.05112878, 85.05112878)
+        n = 2.0**zoom
 
         x = (lon + 180.0) / 360.0 * n * TILE_SIZE
 
         lat_rad = lat * Math::PI / 180.0
-        y = (1.0 - Math.log(Math.tan(lat_rad) + 1.0 / Math.cos(lat_rad)) / Math::PI) / 2.0 * n * TILE_SIZE
+        y = (1.0 - (Math.log(Math.tan(lat_rad) + (1.0 / Math.cos(lat_rad))) / Math::PI)) / 2.0 * n * TILE_SIZE
 
         [x, y]
       end

data/lib/gd/gis/style.rb

@@ -1,19 +1,75 @@
+# frozen_string_literal: true
+
 require "yaml"
 
 module GD
   module GIS
+    # Defines visual styling rules for map rendering.
+    #
+    # A Style object encapsulates all visual configuration used
+    # during rendering, including colors, stroke widths, fonts,
+    # and layer ordering.
+    #
+    # Styles are typically loaded from YAML files and applied
+    # to a {GD::GIS::Map} instance before rendering.
+    #
     class Style
-      attr_reader :roads, :rails, :water, :parks, :points, :order
+      # @return [Hash] global styling rules
+      attr_reader :global
+
+      # @return [Hash] road styling rules
+      attr_reader :roads
+
+      # @return [Hash] rail styling rules
+      attr_reader :rails
+
+      # @return [Hash] water styling rules
+      attr_reader :water
+
+      # @return [Hash] park styling rules
+      attr_reader :parks
+
+      # @return [Hash] point styling rules
+      attr_reader :points
+
+      # @return [Hash] track styling rules
+      attr_reader :track
+
+      # @return [Array<Symbol>] drawing order of semantic layers
+      attr_reader :order
 
+      # Creates a new style from a definition hash.
+      #
+      # @param definition [Hash]
+      #   style definition with optional sections:
+      #   :global, :roads, :rails, :water, :parks, :points, :order, :track
       def initialize(definition)
+        @global = definition[:global] || {}
         @roads = definition[:roads] || {}
         @rails = definition[:rails] || {}
         @water = definition[:water] || {}
         @parks = definition[:parks] || {}
         @points = definition[:points] || {}
+        @track = definition[:track] || {}
         @order = definition[:order] || []
       end
 
+      # Loads a style definition from a YAML file.
+      #
+      # The file name is resolved as:
+      #
+      #   <from>/<name>.yml
+      #
+      # All keys are deep-symbolized on load.
+      #
+      # @param name [String, Symbol]
+      #   style name (without extension)
+      # @param from [String]
+      #   directory containing style files
+      #
+      # @return [Style]
+      # @raise [RuntimeError] if the style file does not exist
+      # @raise [Psych::SyntaxError] if the YAML is invalid
       def self.load(name, from: "styles")
         path = File.join(from, "#{name}.yml")
         raise "Style not found: #{path}" unless File.exist?(path)
@@ -22,8 +78,10 @@ module GD
         data = deep_symbolize(data)
 
         new(
+          global: data[:global],
           roads: data[:roads],
           rails: data[:rail] || data[:rails],
+          track: data[:track],
           water: data[:water],
           parks: data[:park] || data[:parks],
           points: data[:points],
@@ -31,6 +89,10 @@ module GD
         )
       end
 
+      # Recursively converts hash keys to symbols.
+      #
+      # @param obj [Object]
+      # @return [Object]
       def self.deep_symbolize(obj)
         case obj
         when Hash
@@ -43,6 +105,17 @@ module GD
         end
       end
 
+      # Normalizes a color definition into a GD::Color.
+      #
+      # Accepted formats:
+      # - GD::Color instance
+      # - [r, g, b]
+      # - [r, g, b, a]
+      # - nil (generates a random vivid color)
+      #
+      # @param color [GD::Color, Array<Integer>, nil]
+      # @return [GD::Color]
+      # @raise [ArgumentError] if the format is invalid
       def normalize_color(color)
         case color
         when GD::Color
@@ -56,7 +129,7 @@ module GD
             GD::Color.rgba(*color)
           else
             raise ArgumentError,
-              "Style error: color array must be [r,g,b] or [r,g,b,a]"
+                  "Style error: color array must be [r,g,b] or [r,g,b,a]"
           end
 
         when nil
@@ -64,7 +137,7 @@ module GD
 
         else
           raise ArgumentError,
-            "Style error: invalid color format (#{color.inspect})"
+                "Style error: invalid color format (#{color.inspect})"
         end
       end
     end

data/lib/gd/gis.rb

@@ -1,6 +1,34 @@
+# frozen_string_literal: true
+
 require "gd"
 
+# LibGD::GIS provides high-level GIS rendering primitives
+# built on top of the GD graphics library.
+#
+# The library is focused on rendering geographic data
+# (points, lines, polygons, and GeoJSON) into raster images
+# using a layered map model.
+#
+# ## Core concepts
+#
+# - {LibGD::GIS::Map} — rendering surface and orchestration
+# - {LibGD::GIS::Layer} — drawable data layers
+# - {LibGD::GIS::Geometry} — geometric primitives
+# - {LibGD::GIS::Projection} — coordinate transformations
+#
+# ## Typical usage
+#
+#   map = LibGD::GIS::Map.new(
+#                            bbox: bbox,
+#                            zoom: zoom,
+#                            basemap: :nasa_goes_geocolor
+#   )
+#   map.style = GD::GIS::Style.load(style_name.yml)
+#   map.render
+#   map.save("map_name.png")
+#
 require_relative "gis/color_helpers"
+require_relative "gis/font_helper"
 require_relative "gis/style"
 require_relative "gis/classifier"
 

data/lib/libgd_gis.rb

@@ -1,44 +1,74 @@
 require "libgd_gis"
-
 require "open-uri"
 require "tempfile"
 require "gd"
 
+# Namespace for LibGD extensions
 module LibGD
   module GIS
+    # Represents a single map tile fetched from a remote tile provider.
     class Tile
-        attr_reader :z, :x, :y, :image
+      # @return [Integer] zoom level
+      attr_reader :z
+
+      # @return [Integer] tile X coordinate
+      attr_reader :x
+
+      # @return [Integer] tile Y coordinate
+      attr_reader :y
+
+      # @return [GD::Image, nil] rendered image
+      attr_reader :image
 
-        def self.osm(z:, x:, y:)
+      # Builds a tile using an OSM-compatible XYZ source
+      #
+      # @param z [Integer] zoom level
+      # @param x [Integer] X coordinate
+      # @param y [Integer] Y coordinate
+      # @return [Tile]
+      def self.osm(z:, x:, y:)
         new(
-            z: z,
-            x: x,
-            y: y,
-            source: "https://api.maptiler.com/maps/basic/#{z}/#{x}/#{y}.png?key=GetYourOwnKey"
+          z: z,
+          x: x,
+          y: y,
+          source: "https://api.maptiler.com/maps/basic/#{z}/#{x}/#{y}.png?key=GetYourOwnKey"
         )
-        end
-
-        def initialize(z:, x:, y:, source:)
-            @z = z
-            @x = x
-            @y = y
-            @source = source
-        end
-
-        def render
-            tmp = Tempfile.new(["tile", ".png"])
-            tmp.binmode
-            tmp.write URI.open(@source).read
-            tmp.flush
-
-            @image = GD::Image.open(tmp.path)
-        ensure
-            tmp.close
-        end
-
-        def save(path)
-            @image.save(path)
-        end
+      end
+
+      # @param z [Integer]
+      # @param x [Integer]
+      # @param y [Integer]
+      # @param source [String] remote image URL
+      def initialize(z:, x:, y:, source:)
+        @z = z
+        @x = x
+        @y = y
+        @source = source
+      end
+
+      # Downloads and renders the tile image
+      #
+      # @return [GD::Image]
+      def render
+        tmp = Tempfile.new(["tile", ".png"])
+        tmp.binmode
+        uri = URI(@source)
+        response = Net::HTTP.get(uri)
+        tmp.write(response)
+        tmp.flush
+
+        @image = GD::Image.open(tmp.path)
+      ensure
+        tmp.close
+      end
+
+      # Saves the rendered image to disk
+      #
+      # @param path [String]
+      # @return [void]
+      def save(path)
+        @image.save(path)
+      end
     end
   end
 end

data/lib/test.rb

@@ -0,0 +1,4 @@
+def foo
+end
+
+foo(1, 2)

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: libgd-gis
 version: !ruby/object:Gem::Version
-  version: 0.2.9
+  version: 0.3.1
 platform: ruby
 authors:
 - Germán Alberto Giménez Silva
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-22 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-libgd
@@ -45,11 +44,8 @@ files:
 - lib/gd/gis/color_helpers.rb
 - lib/gd/gis/crs_normalizer.rb
 - lib/gd/gis/feature.rb
+- lib/gd/gis/font_helper.rb
 - lib/gd/gis/geometry.rb
-- lib/gd/gis/input/detector.rb
-- lib/gd/gis/input/geojson.rb
-- lib/gd/gis/input/kml.rb
-- lib/gd/gis/input/shapefile.rb
 - lib/gd/gis/layer_geojson.rb
 - lib/gd/gis/layer_lines.rb
 - lib/gd/gis/layer_points.rb
@@ -61,11 +57,12 @@ files:
 - lib/gd/gis/projection.rb
 - lib/gd/gis/style.rb
 - lib/libgd_gis.rb
+- lib/test.rb
 homepage: https://github.com/ggerman/libgd-gis
 licenses:
 - MIT
-metadata: {}
-post_install_message:
+metadata:
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -80,8 +77,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.4
 specification_version: 4
 summary: Geospatial raster rendering for Ruby using libgd
 test_files: []

data/lib/gd/gis/input/detector.rb

@@ -1,34 +0,0 @@
-module GD
-  module GIS
-    module Input
-      module Detector
-        def self.detect(path)
-          return :geojson   if geojson?(path)
-          return :kml       if kml?(path)
-          return :shapefile if shapefile?(path)
-          return :osm_pbf   if pbf?(path)
-          :unknown
-        end
-
-        def self.geojson?(path)
-          File.open(path) do |f|
-            head = f.read(2048)
-            head.include?('"FeatureCollection"') || head.include?('"GeometryCollection"')
-          end
-        end
-
-        def self.kml?(path)
-          File.open(path) { |f| f.read(512).include?("<kml") }
-        end
-
-        def self.shapefile?(path)
-          File.open(path, "rb") { |f| f.read(4) == "\x00\x00\x27\x0A" }
-        end
-
-        def self.pbf?(path)
-          File.open(path, "rb") { |f| f.read(2) == "\x1f\x8b" }
-        end
-      end
-    end
-  end
-end