libgd-gis 0.2.9 → 0.3.0

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,10 +1,42 @@
+# 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] 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 [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:
+      #   :roads, :rails, :water, :parks, :points, :order
       def initialize(definition)
         @roads = definition[:roads] || {}
         @rails = definition[:rails] || {}
@@ -14,6 +46,22 @@ module GD
         @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)
@@ -31,6 +79,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 +95,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 +119,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 +127,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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: libgd-gis
 version: !ruby/object:Gem::Version
-  version: 0.2.9
+  version: 0.3.0
 platform: ruby
 authors:
 - Germán Alberto Giménez Silva
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-22 00:00:00.000000000 Z
+date: 2026-01-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-libgd
@@ -30,6 +30,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.2.3
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.20'
 description: A native GIS raster engine for Ruby built on libgd. Render maps, GeoJSON,
   heatmaps and tiles.
 email:
@@ -45,11 +73,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

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