proj4rb 4.1.1 → 5.0.0

data/lib/api/proj_experimental.rb

@@ -0,0 +1,7 @@
+# Generated by ruby-bindgen (1.0.0)
+
+module Proj
+  module Api
+
+  end
+end

data/lib/api/proj_ffi.rb

@@ -0,0 +1,47 @@
+# Generated by ruby-bindgen (1.0.0)
+
+require 'ffi'
+
+module Proj
+  module Api
+    extend FFI::Library
+
+    def self.library_names
+      ["proj"]
+    end
+
+    def self.library_versions
+      ["9_1", "9", "25", "22", "19", "17", "15", "14", "13", "12", "11"]
+    end
+
+    def self.search_names
+      result = Array.new
+      self.library_names.each do |name|
+        result << "lib#{name}"
+        self.library_versions.each do |version|
+          case RbConfig::CONFIG['host_os']
+            when /darwin|mac os/
+              result << "lib#{name}.#{version}"
+            when /mingw/
+              result << "lib#{name}-#{version}"
+            when /mswin/
+              result << "#{name}_#{version}"
+            else
+              result << "lib#{name}.so.#{version}"
+          end
+        end
+      end
+      result
+    end
+
+    if ENV['PROJ_LIB_PATH']
+      ffi_lib self.search_names.map { |name| File.join(ENV['PROJ_LIB_PATH'], name) } + self.search_names
+    else
+      ffi_lib self.search_names
+    end
+  end
+end
+
+require_relative 'proj_version'
+require_relative './proj'
+require_relative './proj_experimental'

data/lib/api/proj_version.rb

@@ -0,0 +1,26 @@
+# Generated by ruby-bindgen (1.0.0)
+
+module Proj
+  module Api
+    class PjInfo < FFI::Struct
+      layout :major, :int,
+             :minor, :int,
+             :patch, :int,
+             :release, :string,
+             :version, :string,
+             :searchpath, :string,
+             :paths, :pointer,
+             :path_count, :size_t
+    end
+
+    attach_function :proj_info, :proj_info, [], PjInfo.by_value
+
+    def self.proj_version
+      info = proj_info
+      info[:major] * 10000 + info[:minor] * 100 + info[:patch]
+    end
+
+    info = proj_info
+    Proj::Api::PROJ_VERSION = Gem::Version.new("#{info[:major]}.#{info[:minor]}.#{info[:patch]}")
+  end
+end

data/lib/examples/axis_order_normalization.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'proj'
+
+transform = Proj::Transformation.new('EPSG:4326', 'EPSG:3857')
+normalized = transform.normalize_for_visualization
+
+coord = Proj::Coordinate.new(x: -122.4194, y: 37.7749)
+result = normalized.forward(coord)
+
+raise 'normalization transform failed' unless result.x.finite? && result.y.finite?
+
+puts "ok: web mercator x=#{result.x}, y=#{result.y}"

data/lib/examples/batch_transformation.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'proj'
+
+# Create a UTM zone 32 conversion.
+conversion = Proj::Conversion.new('+proj=utm +zone=32 +ellps=GRS80')
+
+# Build an array of coordinates (lon/lat in radians).
+coordinates = [
+  Proj::Coordinate.new(lon: Proj.degrees_to_radians(12), lat: Proj.degrees_to_radians(55), z: 45),
+  Proj::Coordinate.new(lon: Proj.degrees_to_radians(12), lat: Proj.degrees_to_radians(56), z: 50),
+  Proj::Coordinate.new(lon: Proj.degrees_to_radians(13), lat: Proj.degrees_to_radians(55), z: 30)
+]
+
+# Transform all at once (more efficient than looping).
+results = conversion.transform_array(coordinates, :PJ_FWD)
+
+results.each_with_index do |coord, i|
+  puts "Point #{i}: x=#{coord.x.round(2)}, y=#{coord.y.round(2)}, z=#{coord.z}"
+end
+
+raise 'wrong count' unless results.size == 3
+raise 'bad transform' unless results.all? { |c| c.x.finite? && c.y.finite? }
+
+puts 'ok'

data/lib/examples/context_logging.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'proj'
+
+# Create a dedicated context so we don't affect the default.
+context = Proj::Context.new
+
+# Collect log messages into an array.
+messages = []
+
+context.set_log_function do |_pointer, level, message|
+  messages << "[level=#{level}] #{message}"
+end
+
+# Trigger a log message by setting an invalid database path.
+begin
+  context.database.path = '/nonexistent'
+rescue Proj::Error
+  # Expected - we just want to see the log output.
+end
+
+messages.each { |msg| puts msg }
+
+raise 'no log messages captured' if messages.empty?
+
+puts 'ok'

data/lib/examples/crs_identification.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'proj'
+
+# Start with a CRS created from a well-known string.
+crs = Proj::Crs.new('OGC:CRS84')
+
+# Identify it against the OGC authority.
+objects, confidences = crs.identify('OGC')
+
+objects.count.times do |i|
+  puts "Match: #{objects[i]} (confidence: #{confidences[i]}%)"
+end
+
+raise 'no matches' if objects.count.zero?
+raise 'low confidence' if confidences[0] < 100
+
+puts 'ok'

data/lib/examples/database_query.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'proj'
+
+database = Proj::Database.new(Proj::Context.current)
+
+# List all authorities in the database.
+authorities = database.authorities
+puts "Authorities: #{authorities.to_a.first(5).join(', ')} (#{authorities.count} total)"
+
+# Count EPSG coordinate reference systems.
+codes = database.codes('EPSG', :PJ_TYPE_GEOGRAPHIC_2D_CRS)
+puts "EPSG geographic 2D CRS codes: #{codes.count}"
+
+# Query CRS entries for a specific authority.
+crs_infos = database.crs_info('EPSG')
+puts "EPSG CRS entries: #{crs_infos.count}"
+
+# Show the first entry.
+info = crs_infos.first
+puts "First: #{info.auth_name}:#{info.code} - #{info.name} (#{info.crs_type})"
+puts "  Area: #{info.area_name}"
+puts "  Bounds: W=#{info.west_lon_degree}, S=#{info.south_lat_degree}, E=#{info.east_lon_degree}, N=#{info.north_lat_degree}"
+
+raise 'no CRS info found' if crs_infos.empty?
+
+puts 'ok'

data/lib/examples/geodetic_distance.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'proj'
+
+# Use WGS 84 as the ellipsoid for distance calculations.
+crs = Proj::Crs.new('EPSG:4326')
+
+# Paris (lon, lat) and Berlin (lon, lat) in radians.
+paris  = Proj::Coordinate.new(x: Proj.degrees_to_radians(2.3522),
+                               y: Proj.degrees_to_radians(48.8566))
+berlin = Proj::Coordinate.new(x: Proj.degrees_to_radians(13.4050),
+                               y: Proj.degrees_to_radians(52.5200))
+
+# Simple geodesic distance on the ellipsoid.
+distance = crs.lp_distance(paris, berlin)
+raise "unexpected distance #{distance}" unless (distance - 878_000).abs < 5_000
+
+puts "Distance Paris -> Berlin: #{(distance / 1000).round(1)} km"
+
+# Full geodesic: distance + forward/reverse azimuth.
+# Returns distance (meters) in x, forward azimuth (degrees) in y, reverse azimuth (degrees) in z.
+result = crs.geod_distance(paris, berlin)
+puts "Geodesic distance: #{(result.x / 1000).round(1)} km"
+puts "Forward azimuth:   #{result.y.round(2)} degrees"
+puts "Reverse azimuth:   #{result.z.round(2)} degrees"
+
+# Geodesic direct problem (PROJ 9.7+): given a start point, azimuth, and distance,
+# compute the endpoint.
+if Proj::Api::PROJ_VERSION >= Gem::Version.new('9.7.0')
+  # From Paris, azimuth 0 (due north), 100 km.
+  endpoint = crs.geod_direct(paris, 0.0, 100_000)
+  puts "100 km north of Paris: lon=#{Proj.radians_to_degrees(endpoint.x).round(4)}, lat=#{Proj.radians_to_degrees(endpoint.y).round(4)}"
+  raise 'geod_direct failed' unless endpoint.x.finite? && endpoint.y.finite?
+else
+  puts "geod_direct requires PROJ 9.7+ (have #{Proj::Api::PROJ_VERSION})"
+end
+
+puts 'ok'

data/lib/examples/geodetic_to_projected.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'proj'
+
+context = Proj::Context.new
+crs_projected = Proj::Crs.new('+proj=utm +zone=32 +datum=WGS84 +type=crs', context)
+crs_geodetic = crs_projected.geodetic_crs
+transform = Proj::Transformation.new(crs_geodetic, crs_projected, context)
+
+from = Proj::Coordinate.new(lon: 12.0, lat: 55.0)
+to = transform.forward(from)
+back = transform.inverse(to)
+
+raise 'forward failed' unless to.x.finite? && to.y.finite?
+raise 'inverse mismatch lon' unless (back.lon - 12.0).abs < 1e-8
+raise 'inverse mismatch lat' unless (back.lat - 55.0).abs < 1e-8
+
+puts "ok: projected x=#{to.x}, y=#{to.y}"

data/lib/examples/operation_factory_context.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'proj'
+
+context = Proj::Context.new
+source = Proj::Crs.create_from_database('EPSG', '4267', :PJ_CATEGORY_CRS)
+target = Proj::Crs.create_from_database('EPSG', '4269', :PJ_CATEGORY_CRS)
+
+factory = Proj::OperationFactoryContext.new(context)
+factory.spatial_criterion = :PROJ_SPATIAL_CRITERION_PARTIAL_INTERSECTION
+factory.grid_availability = :PROJ_GRID_AVAILABILITY_IGNORED
+
+operations = factory.create_operations(source, target)
+raise 'no operations found' if operations.count.zero?
+
+index = operations.suggested_operation(:PJ_FWD, Proj::Coordinate.new(x: 40, y: -100))
+raise 'invalid suggested operation index' if index.negative? || index >= operations.count
+
+puts "ok: best operation #{index} => #{operations[index].name}"

data/lib/examples/pipeline_operator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'proj'
+
+conversion = Proj::Conversion.new(<<~EOS)
+  +proj=pipeline
+  +step +inv +proj=lcc +lat_1=33.88333333333333
+  +lat_2=32.78333333333333 +lat_0=32.16666666666666
+  +lon_0=-116.25 +x_0=2000000.0001016 +y_0=500000.0001016001 +ellps=GRS80
+  +towgs84=0,0,0,0,0,0,0 +units=us-ft +no_defs
+  +step +proj=lcc +lat_1=33.88333333333333 +lat_2=32.78333333333333 +lat_0=32.16666666666666
+  +lon_0=-116.25 +x_0=2000000 +y_0=500000
+  +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs
+EOS
+
+from = Proj::Coordinate.new(x: 4_760_096.421921, y: 3_744_293.729449)
+to = conversion.forward(from)
+
+raise 'pipeline conversion failed' unless to.x.finite? && to.y.finite?
+
+puts "ok: converted x=#{to.x}, y=#{to.y}"

data/lib/examples/promote_demote_3d.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'proj'
+
+# Start with a 2D geographic CRS.
+crs_2d = Proj::Crs.new('EPSG:4326')
+puts "Original: #{crs_2d.name}"
+puts "  Type: #{crs_2d.proj_type}"
+
+# Promote to 3D (adds an ellipsoidal height axis).
+crs_3d = crs_2d.promote_to_3d
+puts "Promoted: #{crs_3d.name}"
+puts "  Type: #{crs_3d.proj_type}"
+
+# Demote back to 2D.
+crs_back = crs_3d.demote_to_2d
+puts "Demoted:  #{crs_back.name}"
+puts "  Type: #{crs_back.proj_type}"
+
+raise 'promote failed' unless crs_3d.proj_type == :PJ_TYPE_GEOGRAPHIC_3D_CRS
+raise 'demote failed'  unless crs_back.proj_type == :PJ_TYPE_GEOGRAPHIC_2D_CRS
+
+puts 'ok'

data/lib/examples/serialization_formats.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'proj'
+
+crs = Proj::Crs.new('EPSG:4326')
+wkt = crs.to_wkt(:PJ_WKT2_2019, multiline: false)
+projjson = crs.to_json(multiline: false)
+proj_str = crs.to_proj_string
+
+raise 'wkt missing' if wkt.nil? || wkt.empty?
+raise 'proj string missing' if proj_str.nil? || proj_str.empty?
+
+parsed = JSON.parse(projjson)
+raise 'projjson parse failed' unless parsed['type']
+
+puts "ok: serialized #{crs.auth}"

data/lib/examples/transform_bounds.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'proj'
+
+# Transform a bounding box from geographic to projected coordinates.
+transform = Proj::Transformation.new('EPSG:4326',
+  '+proj=laea +lat_0=45 +lon_0=-100 +x_0=0 +y_0=0 +a=6370997 +b=6370997 +units=m +no_defs')
+
+# Bounding box covering parts of North America (lat_min, lon_min, lat_max, lon_max).
+bounds = Proj::Bounds.new(40, -120, 64, -80)
+result = transform.transform_bounds(bounds, :PJ_FWD, 21)
+
+puts "Input:  xmin=#{bounds.xmin}, ymin=#{bounds.ymin}, xmax=#{bounds.xmax}, ymax=#{bounds.ymax}"
+puts "Output: xmin=#{result.xmin.round(2)}, ymin=#{result.ymin.round(2)}, xmax=#{result.xmax.round(2)}, ymax=#{result.ymax.round(2)}"
+
+raise 'transform_bounds failed' unless result.xmin.finite? && result.ymax.finite?
+
+puts 'ok'

data/lib/examples/transformation_with_area.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'proj'
+
+area = Proj::Area.new(
+  west_lon_degree: -114.1324,
+  south_lat_degree: 49.5614,
+  east_lon_degree: 3.76488,
+  north_lat_degree: 62.1463
+)
+
+transform = Proj::Transformation.new('EPSG:4277', 'EPSG:4326', area: area)
+from = Proj::Coordinate.new(x: 50, y: -2)
+to = transform.forward(from)
+
+raise 'area transformation failed' unless to.x.finite? && to.y.finite?
+
+puts "ok: transformed x=#{to.x}, y=#{to.y}"

data/lib/proj/area.rb

@@ -1,74 +1,74 @@
-# encoding: UTF-8
-
-module Proj
-  # Areas are used to specify the area of use for the choice of relevant coordinate operations.
-  # See Transformation#new
-  class Area
-    attr_reader :name, :west_lon_degree, :south_lat_degree, :east_lon_degree, :north_lat_degree
-
-    # @!visibility private
-    def self.finalize(pointer)
-      proc do
-        Api.proj_area_destroy(pointer)
-      end
-    end
-
-    def initialize(west_lon_degree:, south_lat_degree:, east_lon_degree:, north_lat_degree:, name: nil)
-      @west_lon_degree = west_lon_degree
-      @south_lat_degree = south_lat_degree
-      @east_lon_degree = east_lon_degree
-      @north_lat_degree = north_lat_degree
-      @name = name
-      create_area
-    end
-
-    def to_ptr
-      @area
-    end
-
-    # Sets the bounds for an area
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_area_set_bbox
-    #
-    # @param west_lon_degree [Float] West longitude, in degrees. In [-180,180] range.
-    # @param south_lat_degree [Float] South latitude, in degrees. In [-90,90] range.
-    # @param east_lon_degree [Float] East longitude, in degrees. In [-180,180] range.
-    # @param north_lat_degree [Float] North latitude, in degrees. In [-90,90] range.
-    def set_bounds(west_lon_degree:, south_lat_degree:, east_lon_degree:, north_lat_degree:)
-      Api.proj_area_set_bbox(self, west_lon_degree, south_lat_degree, east_lon_degree, north_lat_degree)
-    end
-
-    # Sets the name for an area
-    #
-    # @param value [String] The name of the area
-    def name=(value)
-      @name = name
-      # This Api wasn't added until proj 9.1
-      if defined?(Api.proj_area_set_name)
-        Api.proj_area_set_name(self, value)
-      end
-    end
-
-    # Returns nice printout of an Area
-    #
-    # @return [String]
-    def to_s
-      "Area west_lon_degree: #{self.west_lon_degree}, south_lat_degree: #{self.south_lat_degree}, east_lon_degree: #{self.east_lon_degree}, north_lat_degree: #{self.north_lat_degree}"
-    end
-
-    private
-
-    # Creates an area
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_area_create
-    def create_area
-      @area = Api.proj_area_create
-      self.set_bounds(west_lon_degree: west_lon_degree, south_lat_degree: south_lat_degree,
-                      east_lon_degree: east_lon_degree, north_lat_degree: north_lat_degree)
-      if name
-        self.name = name
-      end
-      ObjectSpace.define_finalizer(self, self.class.finalize(@area))
-    end
-  end
-end
+# encoding: UTF-8
+
+module Proj
+  # Areas are used to specify the area of use for the choice of relevant coordinate operations.
+  # See Transformation#new
+  class Area
+    attr_reader :name, :west_lon_degree, :south_lat_degree, :east_lon_degree, :north_lat_degree
+
+    # @!visibility private
+    def self.finalize(pointer)
+      proc do
+        Api.proj_area_destroy(pointer)
+      end
+    end
+
+    def initialize(west_lon_degree:, south_lat_degree:, east_lon_degree:, north_lat_degree:, name: nil)
+      @west_lon_degree = west_lon_degree
+      @south_lat_degree = south_lat_degree
+      @east_lon_degree = east_lon_degree
+      @north_lat_degree = north_lat_degree
+      @name = name
+      create_area
+    end
+
+    def to_ptr
+      @area
+    end
+
+    # Sets the bounds for an area
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_area_set_bbox
+    #
+    # @param west_lon_degree [Float] West longitude, in degrees. In [-180,180] range.
+    # @param south_lat_degree [Float] South latitude, in degrees. In [-90,90] range.
+    # @param east_lon_degree [Float] East longitude, in degrees. In [-180,180] range.
+    # @param north_lat_degree [Float] North latitude, in degrees. In [-90,90] range.
+    def set_bounds(west_lon_degree:, south_lat_degree:, east_lon_degree:, north_lat_degree:)
+      Api.proj_area_set_bbox(self, west_lon_degree, south_lat_degree, east_lon_degree, north_lat_degree)
+    end
+
+    # Sets the name for an area
+    #
+    # @param value [String] The name of the area
+    def name=(value)
+      @name = value
+      # This Api wasn't added until proj 9.1
+      if defined?(Api.proj_area_set_name)
+        Api.proj_area_set_name(self, value)
+      end
+    end
+
+    # Returns nice printout of an Area
+    #
+    # @return [String]
+    def to_s
+      "Area west_lon_degree: #{self.west_lon_degree}, south_lat_degree: #{self.south_lat_degree}, east_lon_degree: #{self.east_lon_degree}, north_lat_degree: #{self.north_lat_degree}"
+    end
+
+    private
+
+    # Creates an area
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_area_create
+    def create_area
+      @area = Api.proj_area_create
+      self.set_bounds(west_lon_degree: west_lon_degree, south_lat_degree: south_lat_degree,
+                      east_lon_degree: east_lon_degree, north_lat_degree: north_lat_degree)
+      if name
+        self.name = name
+      end
+      ObjectSpace.define_finalizer(self, self.class.finalize(@area))
+    end
+  end
+end

data/lib/proj/axis_info.rb

@@ -1,44 +1,44 @@
-module Proj
-  class AxisInfo
-    # @!attribute [r] name
-    #   @return [String] Axis name
-    # @!attribute [r] abbreviation
-    #   @return [String] Axis abbreviation
-    # @!attribute [r] direction
-    #   @return [String] Axis direction
-    # @!attribute [r] unit_conv_factor
-    #   @return [String] Axis unit_conv_factor
-    # @!attribute [r] unit_name
-    #   @return [String] Axis unit_name
-    # @!attribute [r] unit_auth_name
-    #   @return [String] Axis unit_auth_name
-    # @!attribute [r] unit_code
-    #   @return [String] Axis unit_code
-    attr_reader :name, :abbreviation, :direction,
-                :unit_name, :unit_auth_name, :unit_code, :unit_conv_factor
-
-      def initialize(name:, abbreviation:, direction:, unit_conv_factor:, unit_name:, unit_auth_name:, unit_code:)
-      @name = name
-      @abbreviation = abbreviation
-      @direction = direction
-      @unit_conv_factor = unit_conv_factor
-      @unit_name = unit_name
-      @unit_auth_name = unit_auth_name
-      @unit_code = unit_code
-    end
-
-    # Returns axis information in PJ_AXIS_DESCRIPTION structure
-    #
-    # @return [PJ_AXIS_DESCRIPTION]
-    def to_description
-      Api::PJ_AXIS_DESCRIPTION.create(name: name, abbreviation: abbreviation, direction: direction,
-                                      unit_conv_factor: unit_conv_factor, unit_name: name, unit_type: self.unit_type)
-    end
-    
-    def unit_type
-      database = Database.new(Context.default)
-      unit = database.unit(self.unit_auth_name, self.unit_code)
-      unit.unit_type
-    end
-  end
-end
+module Proj
+  class AxisInfo
+    # @!attribute [r] name
+    #   @return [String] Axis name
+    # @!attribute [r] abbreviation
+    #   @return [String] Axis abbreviation
+    # @!attribute [r] direction
+    #   @return [String] Axis direction
+    # @!attribute [r] unit_conv_factor
+    #   @return [String] Axis unit_conv_factor
+    # @!attribute [r] unit_name
+    #   @return [String] Axis unit_name
+    # @!attribute [r] unit_auth_name
+    #   @return [String] Axis unit_auth_name
+    # @!attribute [r] unit_code
+    #   @return [String] Axis unit_code
+    attr_reader :name, :abbreviation, :direction,
+                :unit_name, :unit_auth_name, :unit_code, :unit_conv_factor
+
+    def initialize(name:, abbreviation:, direction:, unit_conv_factor:, unit_name:, unit_auth_name:, unit_code:)
+      @name = name
+      @abbreviation = abbreviation
+      @direction = direction
+      @unit_conv_factor = unit_conv_factor
+      @unit_name = unit_name
+      @unit_auth_name = unit_auth_name
+      @unit_code = unit_code
+    end
+
+    # Returns axis information in PjAxisDescription structure
+    #
+    # @return [PjAxisDescription]
+    def to_description
+      Api::PjAxisDescription.create(name: name, abbreviation: abbreviation, direction: direction,
+                                    unit_conv_factor: unit_conv_factor, unit_name: unit_name, unit_type: self.unit_type)
+    end
+    
+    def unit_type
+      database = Database.new(Context.default)
+      unit = database.unit(self.unit_auth_name, self.unit_code)
+      unit.unit_type
+    end
+  end
+end

data/lib/proj/bounds.rb

@@ -1,7 +1,29 @@
 module Proj
+  # Represents a 2D bounding box defined by minimum and maximum x/y values.
+  # Used with {CoordinateOperationMixin#transform_bounds} to transform rectangular
+  # regions between coordinate reference systems.
   class Bounds
+    # @!attribute [r] xmin
+    #   @return [Float] Minimum x value (e.g., west longitude)
+    # @!attribute [r] ymin
+    #   @return [Float] Minimum y value (e.g., south latitude)
+    # @!attribute [r] xmax
+    #   @return [Float] Maximum x value (e.g., east longitude)
+    # @!attribute [r] ymax
+    #   @return [Float] Maximum y value (e.g., north latitude)
+    # @!attribute [r] name
+    #   @return [String, nil] Optional name for this bounds
     attr_reader :name, :xmin, :ymin, :xmax, :ymax
 
+    # Creates a new 2D bounding box.
+    #
+    # @param xmin [Float] Minimum x value
+    # @param ymin [Float] Minimum y value
+    # @param xmax [Float] Maximum x value
+    # @param ymax [Float] Maximum y value
+    # @param name [String, nil] Optional name
+    #
+    # @return [Bounds]
     def initialize(xmin, ymin, xmax, ymax, name = nil)
       @xmin = xmin
       @ymin = ymin