libgd-gis 0.2.9 → 0.3.0

data/lib/gd/gis/crs_normalizer.rb

@@ -1,20 +1,56 @@
+# frozen_string_literal: true
+
 module GD
   module GIS
+    # Coordinate Reference System (CRS) helpers and constants.
+    #
+    # This namespace defines common CRS identifiers and utilities
+    # used for normalizing coordinate order and projection.
+    #
     module CRS
+      # OGC CRS84 (longitude, latitude)
       CRS84    = "urn:ogc:def:crs:OGC:1.3:CRS84"
+
+      # EPSG:4326 (latitude, longitude axis order)
       EPSG4326 = "EPSG:4326"
+
+      # EPSG:3857 (Web Mercator)
       EPSG3857 = "EPSG:3857"
 
+      # Normalizes coordinates from different CRS definitions
+      # into a consistent [longitude, latitude] order.
+      #
+      # This class handles:
+      # - Axis order normalization (e.g. EPSG:4326)
+      # - Web Mercator (EPSG:3857) to WGS84 conversion
+      # - Flexible input formats
+      #
+      # The output is always expressed as:
+      #   [longitude, latitude] in degrees
+      #
       class Normalizer
+        # Creates a new CRS normalizer.
+        #
+        # @param crs [String, Symbol, nil]
+        #   CRS identifier (e.g. "EPSG:4326", "EPSG:3857", CRS84)
         def initialize(crs)
           @crs = normalize_name(crs)
         end
 
-        # Accepts:
-        #   normalize(lon,lat)
-        #   normalize(lon,lat,z)
-        #   normalize([lon,lat])
-        #   normalize([lon,lat,z])
+        # Normalizes coordinates into [longitude, latitude].
+        #
+        # Accepted input forms:
+        #
+        #   normalize(lon, lat)
+        #   normalize(lon, lat, z)
+        #   normalize([lon, lat])
+        #   normalize([lon, lat, z])
+        #
+        # Extra dimensions (e.g. Z) are ignored.
+        #
+        # @param args [Array<Float, Array<Float>>]
+        # @return [Array<Float>, nil]
+        #   normalized [lon, lat] or nil if input is invalid
         def normalize(*args)
           lon, lat = args.flatten
           return nil if lon.nil? || lat.nil?
@@ -34,21 +70,31 @@ module GD
             mercator_to_wgs84(lon, lat)
 
           else
-            [lon, lat]
+            raise ArgumentError, "Unsupported CRS: #{@crs}"
           end
         end
 
         private
 
+        # Normalizes a CRS name into a comparable string.
+        #
+        # @param name [Object]
+        # @return [String, nil]
         def normalize_name(name)
           return nil if name.nil?
+
           name.to_s.strip
         end
 
+        # Converts Web Mercator coordinates to WGS84.
+        #
+        # @param x [Float] X coordinate (meters)
+        # @param y [Float] Y coordinate (meters)
+        # @return [Array<Float>] [longitude, latitude] in degrees
         def mercator_to_wgs84(x, y)
           r = 6378137.0
           lon = (x / r) * 180.0 / Math::PI
-          lat = (2 * Math.atan(Math.exp(y / r)) - Math::PI / 2) * 180.0 / Math::PI
+          lat = ((2 * Math.atan(Math.exp(y / r))) - (Math::PI / 2)) * 180.0 / Math::PI
           [lon, lat]
         end
       end

data/lib/gd/gis/feature.rb

@@ -1,17 +1,62 @@
+# frozen_string_literal: true
+
 module GD
   module GIS
+    # Represents a single geographic feature with geometry and properties.
+    #
+    # A Feature acts as the rendering bridge between:
+    # - GeoJSON-like geometry data
+    # - Attribute properties
+    # - GD drawing primitives
+    #
+    # Features are responsible for drawing themselves onto a GD image
+    # using a provided projection and styling information.
+    #
     class Feature
-      attr_reader :geometry, :properties, :layer
-
+      # @return [Hash] GeoJSON geometry object
+      attr_reader :geometry
+
+      # @return [Hash] feature properties (tags)
+      attr_reader :properties
+
+      # @return [Symbol, nil] logical layer identifier
+      attr_reader :layer
+
+      # Creates a new feature.
+      #
+      # @param geometry [Hash]
+      #   GeoJSON-like geometry hash (type + coordinates)
+      # @param properties [Hash, nil]
+      #   feature attributes / tags
+      # @param layer [Symbol, nil]
+      #   optional logical layer identifier
       def initialize(geometry, properties, layer = nil)
         @geometry   = geometry
         @properties = properties || {}
         @layer      = layer
       end
 
-      # -------------------------------------------------
-      # Main draw entry point
-      # -------------------------------------------------
+      # Draws the feature onto a GD image.
+      #
+      # This is the main rendering entry point and dispatches
+      # to the appropriate drawing method based on geometry type
+      # and layer styling.
+      #
+      # Supported geometry types:
+      # - Polygon
+      # - MultiPolygon
+      # - LineString
+      # - MultiLineString
+      #
+      # @param img [GD::Image] target image
+      # @param projection [#call]
+      #   callable object converting (lon, lat) → (x, y)
+      # @param color [GD::Color, nil] base color
+      # @param width [Integer] stroke width
+      # @param layer [Symbol, Hash, nil]
+      #   layer identifier or style hash
+      #
+      # @return [void]
       def draw(img, projection, color, width, layer = nil)
         case geometry["type"]
         when "Polygon"
@@ -37,43 +82,58 @@ module GD
         end
       end
 
-      # -------------------------------------------------
-      # Styled polygon rendering (fill + stroke)
-      # -------------------------------------------------
+      # Draws a polygon with fill and stroke styling.
+      #
+      # @param img [GD::Image]
+      # @param projection [#call]
+      # @param rings [Array]
+      #   polygon rings (GeoJSON format)
+      # @param style [Hash]
+      #   style hash with :fill and/or :stroke RGB arrays
+      #
+      # @return [void]
       def draw_polygon_styled(img, projection, rings, style)
         fill   = style[:fill]   ? GD::Color.rgb(*style[:fill])   : nil
         stroke = style[:stroke] ? GD::Color.rgb(*style[:stroke]) : nil
 
         rings.each do |ring|
-          pts = ring.map do |lon,lat|
-            x,y = projection.call(lon,lat)
+          pts = ring.filter_map do |lon, lat|
+            x, y = projection.call(lon, lat)
             next if x.nil? || y.nil?
+
             [x.to_i, y.to_i]
-          end.compact
+          end
 
-          pts = pts.chunk_while { |a,b| a == b }.map(&:first)
+          pts = pts.chunk_while { |a, b| a == b }.map(&:first)
           next if pts.length < 3
 
           img.filled_polygon(pts, fill) if fill
 
           if stroke
-            pts.each_cons(2) { |a,b| img.line(a[0],a[1], b[0],b[1], stroke) }
+            pts.each_cons(2) { |a, b| img.line(a[0], a[1], b[0], b[1], stroke) }
             img.line(pts.last[0], pts.last[1], pts.first[0], pts.first[1], stroke)
           end
         end
       end
 
-      # -------------------------------------------------
-      # Polygon outline (used for water)
-      # -------------------------------------------------
+      # Draws only the outline of a polygon.
+      #
+      # Used primarily for water bodies.
+      #
+      # @param img [GD::Image]
+      # @param projection [#call]
+      # @param rings [Array]
+      # @param color [GD::Color]
+      # @param width [Integer]
+      # @return [void]
       def draw_polygon_outline(img, projection, rings, color, width)
         return if color.nil?
 
         rings.each do |ring|
-          pts = ring.map do |lon, lat|
+          pts = ring.filter_map do |lon, lat|
             x, y = projection.call(lon, lat)
             [x.to_i, y.to_i] if x && y
-          end.compact
+          end
 
           next if pts.size < 2
 
@@ -81,29 +141,39 @@ module GD
         end
       end
 
-      # -------------------------------------------------
-      # Legacy filled polygon (single color)
-      # -------------------------------------------------
+      # Draws a filled polygon using a single color.
+      #
+      # @param img [GD::Image]
+      # @param projection [#call]
+      # @param rings [Array]
+      # @param color [GD::Color]
+      # @return [void]
       def draw_polygon(img, projection, rings, color)
         return if color.nil?
 
         rings.each do |ring|
-          pts = ring.map do |lon,lat|
-            x,y = projection.call(lon,lat)
+          pts = ring.filter_map do |lon, lat|
+            x, y = projection.call(lon, lat)
             next if x.nil? || y.nil?
+
             [x.to_i, y.to_i]
-          end.compact
+          end
 
-          pts = pts.chunk_while { |a,b| a == b }.map(&:first)
+          pts = pts.chunk_while { |a, b| a == b }.map(&:first)
           next if pts.length < 3
 
           img.filled_polygon(pts, color)
         end
       end
 
-      # -------------------------------------------------
-      # Lines
-      # -------------------------------------------------
+      # Draws line or multiline geometries.
+      #
+      # @param img [GD::Image]
+      # @param projection [#call]
+      # @param coords [Array]
+      # @param color [GD::Color]
+      # @param width [Integer]
+      # @return [void]
       def draw_lines(img, projection, coords, color, width)
         return if color.nil?
 
@@ -114,23 +184,36 @@ module GD
         end
       end
 
+      # Draws a single line geometry.
+      #
+      # @param img [GD::Image]
+      # @param projection [#call]
+      # @param coords [Array]
+      # @param color [GD::Color]
+      # @param width [Integer]
+      # @return [void]
       def draw_line(img, projection, coords, color, width)
         return if color.nil?
 
-        coords.each_cons(2) do |(lon1,lat1),(lon2,lat2)|
-          x1,y1 = projection.call(lon1,lat1)
-          x2,y2 = projection.call(lon2,lat2)
+        coords.each_cons(2) do |(lon1, lat1), (lon2, lat2)|
+          x1, y1 = projection.call(lon1, lat1)
+          x2, y2 = projection.call(lon2, lat2)
           img.line(x1, y1, x2, y2, color, thickness: width)
         end
       end
 
-      # -------------------------------------------------
-      # Metadata helpers
-      # -------------------------------------------------
+      # Returns the display label for the feature.
+      #
+      # Prefers Japanese names if present.
+      #
+      # @return [String, nil]
       def label
         properties["name:ja"] || properties["name"]
       end
 
+      # Computes a simple centroid for line-based geometries.
+      #
+      # @return [Array<Float>, nil] [lon, lat] or nil
       def centroid
         pts = []
 
@@ -143,8 +226,8 @@ module GD
 
         return nil if pts.empty?
 
-        lon = pts.map(&:first).sum / pts.size
-        lat = pts.map(&:last).sum / pts.size
+        lon = pts.sum(&:first) / pts.size
+        lat = pts.sum(&:last) / pts.size
 
         [lon, lat]
       end

data/lib/gd/gis/font_helper.rb

@@ -0,0 +1,33 @@
+module GD
+  module GIS
+    module FontHelper
+      PATHS = [
+        "/usr/share/fonts",
+        "/usr/local/share/fonts",
+        File.expand_path("~/.fonts")
+      ].freeze
+
+      EXTENSIONS = %w[ttf otf ttc].freeze
+
+      def self.all
+        @all ||= PATHS.flat_map do |path|
+          next [] unless Dir.exist?(path)
+
+          EXTENSIONS.flat_map do |ext|
+            Dir.glob("#{path}/**/*.#{ext}")
+          end
+        end.compact.uniq
+      end
+
+      def self.random
+        all.sample or raise "GD::GIS::FontHelper: no fonts found on system"
+      end
+
+      def self.find(name)
+        all.find do |f|
+          File.basename(f).downcase.include?(name.downcase)
+        end
+      end
+    end
+  end
+end

data/lib/gd/gis/geometry.rb

@@ -1,54 +1,101 @@
+# frozen_string_literal: true
+
 module GD
   module GIS
+    # Geometry and projection helpers for Web Mercator maps.
+    #
+    # This module provides low-level utilities for:
+    # - Web Mercator (EPSG:3857) projection math
+    # - Bounding box manipulation
+    # - Viewport fitting
+    # - Simple geometric operations for visualization
+    #
+    # All longitude/latitude values are assumed to be in WGS84
+    # (EPSG:4326), unless explicitly stated otherwise.
+    #
+    # ⚠️ These helpers are intended for *rendering and visualization*,
+    # not for precise geospatial analysis.
+    #
     module Geometry
-
+      # Web Mercator tile size in pixels
       TILE_SIZE = 256.0
-      MAX_LAT   = 85.05112878
 
-      # --------------------------------------------------
-      # Validation
-      # --------------------------------------------------
+      # Maximum latitude supported by Web Mercator
+      MAX_LAT   = 85.05112878
 
+      # Validates a bounding box.
+      #
+      # @param bbox [Array<Float>]
+      #   [min_lng, min_lat, max_lng, max_lat]
+      # @raise [ArgumentError] if the bbox is invalid
+      # @return [void]
       def self.validate_bbox!(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
 
+      # Validates a coordinate array.
+      #
+      # @param coords [Array<Array<Float>>]
+      # @raise [ArgumentError] if the coordinates are invalid
+      # @return [void]
       def self.validate_coords!(coords)
-        unless coords.is_a?(Array) && coords.size >= 2
-          raise ArgumentError, "coords must be an Array of at least 2 points"
-        end
-      end
+        return if coords.is_a?(Array) && coords.size >= 2
 
-      # --------------------------------------------------
-      # Web Mercator Projection
-      # --------------------------------------------------
+        raise ArgumentError, "coords must be an Array of at least 2 points"
+      end
 
+      # Converts longitude to Web Mercator X coordinate.
+      #
+      # @param lng [Float] longitude in degrees
+      # @param zoom [Integer] zoom level
+      # @return [Float] X coordinate in pixels
       def self.lng_to_x(lng, zoom)
         ((lng + 180.0) / 360.0) * TILE_SIZE * (2**zoom)
       end
 
+      # Converts latitude to Web Mercator Y coordinate.
+      #
+      # Latitude values are clamped to the valid Web Mercator range.
+      #
+      # @param lat [Float] latitude in degrees
+      # @param zoom [Integer] zoom level
+      # @return [Float] Y coordinate in pixels
       def self.lat_to_y(lat, zoom)
-        lat = [[lat, MAX_LAT].min, -MAX_LAT].max
+        lat = lat.clamp(-MAX_LAT, MAX_LAT)
         lat_rad = lat * Math::PI / 180.0
-        n = Math.log(Math.tan(Math::PI / 4.0 + lat_rad / 2.0))
-        (1.0 - n / Math::PI) / 2.0 * TILE_SIZE * (2**zoom)
+        n = Math.log(Math.tan((Math::PI / 4.0) + (lat_rad / 2.0)))
+        (1.0 - (n / Math::PI)) / 2.0 * TILE_SIZE * (2**zoom)
       end
 
+      # Converts Web Mercator X coordinate to longitude.
+      #
+      # @param x [Float] X coordinate in pixels
+      # @param zoom [Integer] zoom level
+      # @return [Float] longitude in degrees
       def self.x_to_lng(x, zoom)
-        (x / (TILE_SIZE * (2**zoom))) * 360.0 - 180.0
+        ((x / (TILE_SIZE * (2**zoom))) * 360.0) - 180.0
       end
 
+      # Converts Web Mercator Y coordinate to latitude.
+      #
+      # @param y [Float] Y coordinate in pixels
+      # @param zoom [Integer] zoom level
+      # @return [Float] latitude in degrees
       def self.y_to_lat(y, zoom)
-        n = Math::PI - 2.0 * Math::PI * y / (TILE_SIZE * (2**zoom))
+        n = Math::PI - (2.0 * Math::PI * y / (TILE_SIZE * (2**zoom)))
         180.0 / Math::PI * Math.atan(0.5 * (Math.exp(n) - Math.exp(-n)))
       end
 
-      # --------------------------------------------------
-      # Viewport
-      # --------------------------------------------------
-
+      # Computes a viewport bounding box fitted to an image size.
+      #
+      # @param bbox [Array<Float>]
+      #   input bounding box [min_lng, min_lat, max_lng, max_lat]
+      # @param zoom [Integer] zoom level
+      # @param width [Integer] image width in pixels
+      # @param height [Integer] image height in pixels
+      # @return [Array<Float>] fitted bounding box
       def self.viewport_bbox(bbox:, zoom:, width:, height:)
         validate_bbox!(bbox)
 
@@ -76,19 +123,15 @@ module GD
         ]
       end
 
-      # --------------------------------------------------
-      # Geometry helpers
-      # --------------------------------------------------
-
-      # buffer_line(coords, meters)
+      # Creates a naive buffer polygon around a line.
       #
-      # coords  :: Array<[lng, lat]> in WGS84
-      # meters  :: Numeric (approximate)
-      #
-      # NOTE:
-      # - Naive meters-to-degrees conversion
-      # - Suitable for visualization, not analysis
+      # ⚠️ This uses an approximate meters-to-degrees conversion
+      # and is intended for visualization only.
       #
+      # @param coords [Array<Array<Float>>]
+      #   array of [lng, lat] points
+      # @param meters [Numeric] buffer distance (approximate)
+      # @return [Array<Array<Float>>] polygon coordinates
       def self.buffer_line(coords, meters)
         validate_coords!(coords)
 
@@ -102,7 +145,7 @@ module GD
           dx = x2 - x1
           dy = y2 - y1
 
-          len = Math.sqrt(dx * dx + dy * dy)
+          len = Math.sqrt((dx * dx) + (dy * dy))
           next if len.zero?
 
           nx = -dy / len
@@ -110,8 +153,8 @@ module GD
 
           off = meters / 111_320.0
 
-          left  << [x1 + nx * off, y1 + ny * off]
-          right << [x1 - nx * off, y1 - ny * off]
+          left  << [x1 + (nx * off), y1 + (ny * off)]
+          right << [x1 - (nx * off), y1 - (ny * off)]
         end
 
         x2, y2 = coords.last
@@ -120,7 +163,14 @@ module GD
 
         left + right.reverse
       end
-      
+
+      # Projects geographic coordinates into pixel space relative to a bbox.
+      #
+      # @param lng [Float] longitude
+      # @param lat [Float] latitude
+      # @param bbox [Array<Float>] reference bounding box
+      # @param zoom [Integer] zoom level
+      # @return [Array<Float>] [x, y] pixel coordinates
       def self.project(lng, lat, bbox, zoom)
         min_lng, _min_lat, _max_lng, max_lat = bbox
 
@@ -136,6 +186,18 @@ module GD
         ]
       end
 
+      # Computes a bounding box that fits all features in a GeoJSON file.
+      #
+      # The resulting bbox is padded and adjusted to match the
+      # requested image aspect ratio.
+      #
+      # @param path [String] path to GeoJSON file
+      # @param zoom [Integer] zoom level
+      # @param width [Integer] image width in pixels
+      # @param height [Integer] image height in pixels
+      # @param padding_px [Integer] padding in pixels
+      # @return [Array<Float>] bounding box
+      # @raise [RuntimeError] if no coordinates are found
       def self.bbox_for_image(path, zoom:, width:, height:, padding_px: 80)
         data = JSON.parse(File.read(path))
         points = []
@@ -143,6 +205,7 @@ module GD
         data["features"].each do |f|
           geom = f["geometry"]
           next unless geom
+
           collect_points(geom, points)
         end
 
@@ -167,7 +230,7 @@ module GD
         # --------------------------------------------------
         # 2. Fit bbox to image aspect ratio
         # --------------------------------------------------
-        target_ratio = width.to_f / height.to_f
+        target_ratio = width.to_f / height
         current_ratio = (max_x - min_x) / (max_y - min_y)
 
         if current_ratio > target_ratio
@@ -195,6 +258,11 @@ module GD
         ]
       end
 
+      # Collects all coordinate points from a GeoJSON geometry.
+      #
+      # @param geom [Hash] GeoJSON geometry
+      # @param points [Array] accumulator array
+      # @return [void]
       def self.collect_points(geom, points)
         case geom["type"]
         when "Point"
@@ -217,6 +285,14 @@ module GD
         end
       end
 
+      # Builds a bounding box around a point using a radius.
+      #
+      # Uses a simple spherical approximation.
+      #
+      # @param lon [Float] longitude
+      # @param lat [Float] latitude
+      # @param radius_km [Numeric] radius in kilometers
+      # @return [Array<Float>] bounding box
       def self.bbox_around_point(lon, lat, radius_km:)
         delta_lat = radius_km / 111.0
         delta_lon = radius_km / (111.0 * Math.cos(lat * Math::PI / 180.0))
@@ -228,8 +304,6 @@ module GD
           lat + delta_lat
         ]
       end
-
     end
   end
 end
-

data/lib/gd/gis/layer_geojson.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "json"
 require_relative "feature"
 require_relative "crs_normalizer"
@@ -5,7 +7,24 @@ require_relative "ontology"
 
 module GD
   module GIS
+    # Loads GeoJSON files into renderable Feature objects.
+    #
+    # This class is responsible for:
+    # - Parsing GeoJSON files
+    # - Normalizing coordinates across CRS definitions
+    # - Classifying features using an ontology
+    # - Producing {GD::GIS::Feature} instances
+    #
+    # All coordinates are normalized to WGS84
+    # in [longitude, latitude] order.
+    #
     class LayerGeoJSON
+      # Loads a GeoJSON file and returns normalized features.
+      #
+      # @param path [String] path to GeoJSON file
+      # @return [Array<GD::GIS::Feature>]
+      # @raise [JSON::ParserError] if the file is invalid JSON
+      # @raise [Errno::ENOENT] if the file does not exist
       def self.load(path)
         data = JSON.parse(File.read(path))
 
@@ -27,9 +46,15 @@ module GD
         end
       end
 
-      # --------------------------------------------
-      # CRS normalization (2D + 3D safe)
-      # --------------------------------------------
+      # Normalizes a GeoJSON geometry in-place.
+      #
+      # Supports 2D and 3D coordinate arrays.
+      # Any additional dimensions (e.g. Z) are preserved or ignored
+      # depending on the CRS normalizer.
+      #
+      # @param geometry [Hash] GeoJSON geometry object
+      # @param normalizer [CRS::Normalizer]
+      # @return [void]
       def self.normalize_geometry!(geometry, normalizer)
         case geometry["type"]
 
@@ -62,7 +87,6 @@ module GD
             end
         end
       end
-
     end
   end
 end