geodetic 0.2.0 → 0.3.1

data/examples/05_map_rendering/demo.rb

@@ -0,0 +1,264 @@
+#!/usr/bin/env ruby
+
+# Demonstration of rendering geodetic coordinates on a map
+# using the libgd-gis gem for native Ruby map generation.
+# Shows how Geodetic::Feature wraps named coordinates and areas.
+#
+# Prerequisites:
+#   gem install libgd-gis
+#   brew install gd  (macOS) or apt install libgd-dev (Linux)
+#
+# Usage:
+#   ruby -Ilib examples/05_map_rendering.rb
+
+if ARGV.include?("-h") || ARGV.include?("--help")
+  puts <<~HELP
+    Usage: ./demo.rb [options]
+
+    Options:
+      --light              Use light basemap with dark labels
+      --dark               Use dark basemap with light labels
+                           Default: follows macOS appearance setting
+
+      --central-park       Show Central Park polygon boundary (default)
+      --no-central-park    Hide Central Park polygon boundary
+
+      --icon-scale=N       Scale icons by factor N (default: 0.5)
+                           Examples: --icon-scale=0.25, --icon-scale=1.0
+
+      -h, --help           Show this help message
+  HELP
+  exit
+end
+
+require_relative "../../lib/geodetic"
+require "gd/gis"
+
+include Geodetic
+LLA = Coordinate::LLA
+
+# --- Theme detection: --light, --dark, or macOS system default ---
+
+def detect_macos_dark_mode
+  result = `defaults read -g AppleInterfaceStyle 2>/dev/null`.strip
+  result == "Dark"
+rescue
+  false
+end
+
+DARK_MODE = if ARGV.include?("--dark")
+              true
+            elsif ARGV.include?("--light")
+              false
+            else
+              detect_macos_dark_mode
+            end
+
+BASEMAP      = DARK_MODE ? :carto_dark  : :carto_light
+LABEL_COLOR  = DARK_MODE ? [255, 255, 255] : [0, 0, 0]
+ICON_BG      = DARK_MODE  # draw a white disc behind icons on dark basemaps
+CENTRAL_PARK = !ARGV.include?("--no-central-park")  # --central-park is the default
+ICON_SCALE   = (ARGV.find { |a| a.start_with?("--icon-scale=") }&.split("=", 2)&.last&.to_f) || 0.5
+
+# --- 1. Define landmarks as Features with icon paths ---
+
+ICONS_DIR = File.join(__dir__, "icons")
+
+landmarks = [
+  Feature.new(label: "Statue of Liberty", geometry: LLA.new(lat: 40.6892, lng: -74.0445, alt: 0),
+              metadata: { category: "monument", year: 1886, icon: File.join(ICONS_DIR, "monument.png") }),
+  Feature.new(label: "Empire State Bldg",  geometry: LLA.new(lat: 40.7484, lng: -73.9857, alt: 0),
+              metadata: { category: "building", floors: 102, icon: File.join(ICONS_DIR, "building.png") }),
+  Feature.new(label: "Central Park",       geometry: LLA.new(lat: 40.7829, lng: -73.9654, alt: 0),
+              metadata: { category: "park", acres: 843, icon: File.join(ICONS_DIR, "park.png") }),
+  Feature.new(label: "Brooklyn Bridge",    geometry: LLA.new(lat: 40.7061, lng: -73.9969, alt: 0),
+              metadata: { category: "bridge", year: 1883, icon: File.join(ICONS_DIR, "bridge.png") }),
+  Feature.new(label: "Times Square",       geometry: LLA.new(lat: 40.7580, lng: -73.9855, alt: 0),
+              metadata: { category: "landmark", icon: File.join(ICONS_DIR, "landmark.png") }),
+]
+
+# An area-based Feature: Central Park as a polygon boundary
+# Vertices trace the park perimeter (59th St to 110th St)
+central_park_area = Feature.new(
+  label:    "Central Park",
+  geometry: Areas::Polygon.new(boundary: [
+    # Vertices from OpenStreetMap data (way 427818536), simplified.
+    # Central Park is a parallelogram tilted ~29° with Manhattan's grid.
+    LLA.new(lat: 40.7679, lng: -73.9818, alt: 0),  # SW corner (Columbus Circle, 59th & CPW)
+    LLA.new(lat: 40.7649, lng: -73.9727, alt: 0),  # SE corner (Grand Army Plaza, 59th & 5th Ave)
+    LLA.new(lat: 40.7691, lng: -73.9697, alt: 0),  # E edge — 65th St
+    LLA.new(lat: 40.7728, lng: -73.9672, alt: 0),  # E edge — 70th St
+    LLA.new(lat: 40.7766, lng: -73.9648, alt: 0),  # E edge — 75th St
+    LLA.new(lat: 40.7812, lng: -73.9618, alt: 0),  # E edge — 81st St (Met Museum)
+    LLA.new(lat: 40.7855, lng: -73.9592, alt: 0),  # E edge — 86th St
+    LLA.new(lat: 40.7903, lng: -73.9561, alt: 0),  # E edge — 92nd St
+    LLA.new(lat: 40.7950, lng: -73.9531, alt: 0),  # E edge — 97th St
+    LLA.new(lat: 40.7994, lng: -73.9500, alt: 0),  # E edge — 108th St
+    LLA.new(lat: 40.8003, lng: -73.9494, alt: 0),  # NE corner (110th & 5th Ave)
+    LLA.new(lat: 40.8013, lng: -73.9580, alt: 0),  # N edge
+    LLA.new(lat: 40.8008, lng: -73.9585, alt: 0),  # NW corner (110th & CPW)
+    LLA.new(lat: 40.7962, lng: -73.9614, alt: 0),  # W edge — 103rd St
+    LLA.new(lat: 40.7915, lng: -73.9648, alt: 0),  # W edge — 93rd St
+    LLA.new(lat: 40.7863, lng: -73.9679, alt: 0),  # W edge — 86th St
+    LLA.new(lat: 40.7815, lng: -73.9706, alt: 0),  # W edge — 79th St
+    LLA.new(lat: 40.7769, lng: -73.9731, alt: 0),  # W edge — 73rd St
+    LLA.new(lat: 40.7726, lng: -73.9755, alt: 0),  # W edge — 68th St
+    LLA.new(lat: 40.7698, lng: -73.9772, alt: 0),  # W edge — 64th St
+  ]),
+  metadata: { note: "simplified boundary from OpenStreetMap way 427818536" }
+)
+
+# --- 2. Compute a bounding box from Feature coordinates ---
+
+all_points = landmarks.map { |f| f.geometry }
+all_points += central_park_area.geometry.boundary if CENTRAL_PARK
+lats = all_points.map(&:lat)
+lngs = all_points.map(&:lng)
+padding = 0.03
+
+bbox = [
+  lngs.min - padding,  # west
+  lats.min - padding,  # south
+  lngs.max + padding,  # east
+  lats.max + padding   # north
+]
+
+# --- 3. Create the map ---
+
+ZOOM = 12
+
+map = GD::GIS::Map.new(
+  bbox:    bbox,
+  zoom:    ZOOM,
+  basemap: BASEMAP,
+  width:   1024,
+  height:  768
+)
+
+# --- 4. Optionally draw Central Park polygon on the map ---
+
+if CENTRAL_PARK
+  park_coords = central_park_area.geometry.boundary.map { |pt| [pt.lng, pt.lat] }
+
+  map.add_polygons(
+    [[park_coords]],  # polygons > rings > [lng, lat] points
+    fill:   [80, 255, 120, 60],
+    stroke: [50, 200, 80, 255],
+    width:  2
+  )
+end
+
+# Style must be set (add_polygons sets it as a side effect, but just in case)
+map.style ||= GD::GIS::Style.default
+
+# --- 6. Show Feature info using delegation ---
+
+liberty = landmarks.first
+
+puts "Landmarks relative to #{liberty.label}:"
+puts "-" * 60
+
+landmarks.each do |feature|
+  utm = feature.geometry.to_utm
+
+  puts <<~INFO
+    #{feature.label} [#{feature.metadata[:category]}]
+      LLA: #{feature.geometry.to_s(4)}
+      UTM: #{utm.to_s(2)}
+      Distance to #{liberty.label}: #{feature.distance_to(liberty).to_km}
+      Bearing to #{liberty.label}:  #{feature.bearing_to(liberty)}
+
+  INFO
+end
+
+# Distance from an area Feature to a point Feature
+puts "#{central_park_area.label} -> #{liberty.label}: #{central_park_area.distance_to(liberty).to_km}"
+puts
+
+# --- 7. Render, draw markers/areas/labels, and save ---
+
+output_path = File.join(__dir__, "nyc_landmarks.png")
+map.render
+
+img      = map.image
+map_bbox = map.instance_variable_get(:@bbox)
+zoom     = ZOOM
+FONT     = "/System/Library/Fonts/Supplemental/Arial Bold.ttf"
+
+# Draw landmark icons and labels
+landmarks.each do |feature|
+  pt     = feature.geometry
+  px, py = GD::GIS::Geometry.project(pt.lng, pt.lat, map_bbox, zoom)
+  x, y   = px.round, py.round
+
+  # Load and scale the icon
+  icon = GD::Image.open(feature.metadata[:icon])
+  icon.alpha_blending = true
+  icon.save_alpha = true
+  iw = (icon.width  * ICON_SCALE).round
+  ih = (icon.height * ICON_SCALE).round
+  scaled = icon.scale(iw, ih)
+  scaled.alpha_blending = true
+  scaled.save_alpha = true
+
+  # On dark basemaps, add a white disc so black icons are visible
+  if ICON_BG
+    radius = (iw / 2 * 1.3).round
+    img.filled_circle(x, y, radius, [255, 255, 255])
+  end
+
+  img.copy(scaled, x - iw / 2, y - ih / 2, 0, 0, iw, ih)
+
+  # Label to the right of the icon
+  img.text(feature.label, x: x + iw / 2 + 6, y: y + 5,
+                          font: FONT, size: 16, color: LABEL_COLOR)
+end
+
+# --- 8. Draw bearing arrows ---
+
+def draw_bearing_arrow(img, from_feature, to_feature, map_bbox, zoom, color, font)
+  bearing = from_feature.bearing_to(to_feature)
+
+  x1, y1 = GD::GIS::Geometry.project(from_feature.geometry.lng, from_feature.geometry.lat, map_bbox, zoom).map(&:round)
+  x2, y2 = GD::GIS::Geometry.project(to_feature.geometry.lng, to_feature.geometry.lat, map_bbox, zoom).map(&:round)
+
+  # Line (doubled for thickness)
+  img.line(x1, y1, x2, y2, color)
+  img.line(x1 + 1, y1, x2 + 1, y2, color)
+
+  # Arrowhead at destination
+  dx, dy = (x2 - x1).to_f, (y2 - y1).to_f
+  len = Math.sqrt(dx * dx + dy * dy)
+  ux, uy = dx / len, dy / len
+
+  tip_x  = x2 - (ux * 20).round
+  tip_y  = y2 - (uy * 20).round
+  base_x = tip_x - (ux * 14).round
+  base_y = tip_y - (uy * 14).round
+  px, py = -uy, ux
+  p1x = base_x + (px * 7).round
+  p1y = base_y + (py * 7).round
+  p2x = base_x - (px * 7).round
+  p2y = base_y - (py * 7).round
+  img.filled_polygon([[tip_x, tip_y], [p1x, p1y], [p2x, p2y]], color)
+
+  # Label at midpoint
+  mid_x = (x1 + x2) / 2
+  mid_y = (y1 + y2) / 2
+  img.text("#{bearing.degrees.round(1)}\u00B0", x: mid_x + 8, y: mid_y + 5,
+                                                 font: font, size: 14, color: color)
+end
+
+img.antialias = true
+brooklyn = landmarks.find { |f| f.label == "Brooklyn Bridge" }
+liberty  = landmarks.find { |f| f.label == "Statue of Liberty" }
+empire   = landmarks.find { |f| f.label == "Empire State Bldg" }
+
+arrow_color = DARK_MODE ? [255, 100, 100] : [200, 30, 30]
+
+draw_bearing_arrow(img, brooklyn, liberty, map_bbox, zoom, arrow_color, FONT)
+draw_bearing_arrow(img, brooklyn, empire,  map_bbox, zoom, arrow_color, FONT)
+
+map.save(output_path)
+
+puts "Map saved to #{output_path}"

data/examples/README.md

@@ -0,0 +1,62 @@
+# Geodetic Examples
+
+Runnable demo scripts showing progressive usage of the Geodetic library. Run any single-file example from the project root:
+
+```bash
+ruby -Ilib examples/01_basic_conversions.rb
+```
+
+## 01 - Basic Conversions
+
+Converts a single point between LLA, ECEF, UTM, ENU, and NED coordinate systems. Demonstrates roundtrip accuracy and local coordinate frames with a reference point.
+
+## 02 - All Coordinate Systems
+
+Walks through all 18 coordinate systems with cross-system conversion chains. Covers spatial hashes (GH, GH36, HAM, OLC, GEOREF, GARS, H3), areas, and neighbor lookups.
+
+## 03 - Distance Calculations
+
+Demonstrates the `Distance` class: great-circle and straight-line distances, unit conversions (km, mi, ft, nmi), arithmetic, comparison, and cross-system distance calculations.
+
+## 04 - Bearing Calculations
+
+Demonstrates the `Bearing` class: forward azimuth, back azimuth, compass directions (4/8/16-point), elevation angles, chain bearings, and cross-system bearing calculations.
+
+## 05 - Map Rendering
+
+Renders geodetic data on a raster map using the [libgd-gis](https://rubygems.org/gems/libgd-gis) gem. Showcases `Geodetic::Feature` for wrapping coordinates and areas with labels and metadata.
+
+Features demonstrated:
+
+- **Feature objects** with point and polygon geometries
+- **Landmark icons** scaled and composited onto the map
+- **Polygon rendering** of Central Park's boundary
+- **Bearing arrows** with degree labels between landmarks
+- **Distance and bearing delegation** through Feature objects
+- **UTM conversion** output for each landmark
+- **Light/dark theme** switching with macOS system detection
+
+Prerequisites:
+
+```bash
+gem install libgd-gis
+brew install gd   # macOS
+```
+
+Run from the project root:
+
+```bash
+ruby -Ilib examples/05_map_rendering/demo.rb
+```
+
+CLI flags:
+
+```
+--light / --dark       Select basemap theme (default: macOS system setting)
+--central-park         Show Central Park polygon (default)
+--no-central-park      Hide Central Park polygon
+--icon-scale=N         Scale landmark icons (default: 0.5)
+-h, --help             Show help
+```
+
+Output: `examples/05_map_rendering/nyc_landmarks.png`

data/fiddle_pointer_buffer_pool.md

@@ -0,0 +1,119 @@
+# H3 Fiddle Pointer Buffer Pool Optimization
+
+## Problem
+
+Every H3 C function call in `lib/geodetic/coordinate/h3.rb` allocates fresh `Fiddle::Pointer` objects that are immediately discarded after use. At high call volumes (1M+ conversions), this creates hundreds of thousands of short-lived heap objects and GC pressure.
+
+## Affected Methods
+
+| Method | Pointers Allocated | Sizes |
+|--------|-------------------|-------|
+| `lat_lng_to_cell` | 2 | `SIZEOF_LATLNG` (16B) + `SIZEOF_H3INDEX` (8B) |
+| `cell_to_lat_lng` | 1 | `SIZEOF_LATLNG` (16B) |
+| `cell_to_boundary` | 1 | `SIZEOF_CELL_BOUNDARY` (168B) |
+| `grid_disk` | 2 | `SIZEOF_INT64` (8B) + variable |
+| `cell_area_m2` | 1 | `SIZEOF_DOUBLE` (8B) |
+| `cell_to_parent` | 1 | `SIZEOF_H3INDEX` (8B) |
+| `cell_to_children` | 2 | `SIZEOF_INT64` (8B) + variable |
+
+## Proposed Solution
+
+Pre-allocate thread-local reusable buffers for fixed-size structs. Variable-size buffers (`grid_disk` output, `cell_to_children` output) cannot be pre-allocated since their size depends on input.
+
+### Thread-Local Buffer Helper
+
+```ruby
+module LibH3
+  def self.thread_buffer(name, size)
+    key = :"geodetic_h3_#{name}"
+    Thread.current[key] ||= Fiddle::Pointer.malloc(size)
+  end
+end
+```
+
+### Before (current code)
+
+```ruby
+def self.lat_lng_to_cell(lat_rad, lng_rad, resolution)
+  require_library!
+  latlng = Fiddle::Pointer.malloc(SIZEOF_LATLNG, Fiddle::RUBY_FREE)
+  latlng[0, SIZEOF_LATLNG] = [lat_rad, lng_rad].pack('d2')
+  out = Fiddle::Pointer.malloc(SIZEOF_H3INDEX, Fiddle::RUBY_FREE)
+  err = F_LAT_LNG_TO_CELL.call(latlng, resolution, out)
+  raise ArgumentError, "H3 latLngToCell error (code #{err})" unless err == 0
+  out[0, SIZEOF_H3INDEX].unpack1('Q')
+end
+```
+
+### After (with buffer reuse)
+
+```ruby
+def self.lat_lng_to_cell(lat_rad, lng_rad, resolution)
+  require_library!
+  latlng = thread_buffer(:latlng, SIZEOF_LATLNG)
+  latlng[0, SIZEOF_LATLNG] = [lat_rad, lng_rad].pack('d2')
+  out = thread_buffer(:h3index, SIZEOF_H3INDEX)
+  err = F_LAT_LNG_TO_CELL.call(latlng, resolution, out)
+  raise ArgumentError, "H3 latLngToCell error (code #{err})" unless err == 0
+  out[0, SIZEOF_H3INDEX].unpack1('Q')
+end
+
+def self.cell_to_lat_lng(h3_index)
+  require_library!
+  latlng = thread_buffer(:latlng, SIZEOF_LATLNG)
+  err = F_CELL_TO_LAT_LNG.call(h3_index, latlng)
+  raise ArgumentError, "H3 cellToLatLng error (code #{err})" unless err == 0
+  lat_rad, lng_rad = latlng[0, SIZEOF_LATLNG].unpack('d2')
+  { lat: lat_rad * DEG_PER_RAD, lng: lng_rad * DEG_PER_RAD }
+end
+
+def self.cell_to_boundary(h3_index)
+  require_library!
+  cb = thread_buffer(:cell_boundary, SIZEOF_CELL_BOUNDARY)
+  err = F_CELL_TO_BOUNDARY.call(h3_index, cb)
+  raise ArgumentError, "H3 cellToBoundary error (code #{err})" unless err == 0
+  num_verts = cb[0, 4].unpack1('i')
+  verts = cb[8, num_verts * SIZEOF_LATLNG].unpack("d#{num_verts * 2}")
+  (0...num_verts).map do |i|
+    { lat: verts[i * 2] * DEG_PER_RAD, lng: verts[i * 2 + 1] * DEG_PER_RAD }
+  end
+end
+
+def self.cell_area_m2(h3_index)
+  require_library!
+  out = thread_buffer(:double, Fiddle::SIZEOF_DOUBLE)
+  err = F_CELL_AREA_M2.call(h3_index, out)
+  raise ArgumentError, "H3 cellAreaM2 error (code #{err})" unless err == 0
+  out[0, Fiddle::SIZEOF_DOUBLE].unpack1('d')
+end
+
+def self.cell_to_parent(h3_index, parent_res)
+  require_library!
+  out = thread_buffer(:h3index, SIZEOF_H3INDEX)
+  err = F_CELL_TO_PARENT.call(h3_index, parent_res, out)
+  raise ArgumentError, "H3 cellToParent error (code #{err})" unless err == 0
+  out[0, SIZEOF_H3INDEX].unpack1('Q')
+end
+```
+
+### Reusable Fixed-Size Buffers
+
+| Buffer Name | Size | Used By |
+|-------------|------|---------|
+| `:latlng` | 16 bytes | `lat_lng_to_cell`, `cell_to_lat_lng` |
+| `:h3index` | 8 bytes | `lat_lng_to_cell`, `cell_to_parent` |
+| `:cell_boundary` | 168 bytes | `cell_to_boundary` |
+| `:int64` | 8 bytes | `grid_disk`, `cell_to_children` |
+| `:double` | 8 bytes | `cell_area_m2` |
+
+## Thread Safety
+
+Using `Thread.current` ensures each thread gets its own buffer. No mutex needed. Buffers are overwritten on each call, so stale data is not a concern — the C function fills the buffer before Ruby reads it.
+
+## When to Implement
+
+This optimization is only worthwhile for high-volume batch processing (1M+ H3 conversions). For typical usage the current per-call allocation is fine and simpler to reason about.
+
+## Not Optimizable
+
+The `grid_disk` and `cell_to_children` output buffers are variable-sized (depends on `k` ring size or child resolution) and must be allocated per call.

data/lib/geodetic/coordinate/bng.rb

@@ -35,6 +35,13 @@ module Geodetic
         ['HL', 'HM', 'HN', 'HO', 'HP', 'JL', 'JM']
       ]
 
+      # Reverse lookup: grid square letters → [x, y] coordinates
+      GRID_SQUARE_LOOKUP = GRID_SQUARES.each_with_index.each_with_object({}) do |(row, y), hash|
+        row.each_with_index do |square, x|
+          hash[square] = [x, 12 - y]
+        end
+      end.freeze
+
       # OSGB36 datum (approximation - use Airy 1830 ellipsoid)
       OSGB36 = Struct.new(:name, :a, :b, :f, :e, :e2).new(
         'OSGB36',
@@ -252,22 +259,9 @@ module Geodetic
           east_digits = $2
           north_digits = $3
 
-          # Find grid square
-          grid_x = nil
-          grid_y = nil
-
-          GRID_SQUARES.each_with_index do |row, y|
-            row.each_with_index do |square, x|
-              if square == letters
-                grid_x = x
-                grid_y = 12 - y
-                break
-              end
-            end
-            break if grid_x
-          end
-
-          raise ArgumentError, "Invalid grid square: #{letters}" unless grid_x
+          grid_coords = GRID_SQUARE_LOOKUP[letters]
+          raise ArgumentError, "Invalid grid square: #{letters}" unless grid_coords
+          grid_x, grid_y = grid_coords
 
           # Calculate coordinates
           precision = east_digits.length
@@ -279,22 +273,9 @@ module Geodetic
         elsif grid_ref.match(/^([A-Z]{2})$/)
           letters = $1
 
-          # Grid square only - use center point
-          grid_x = nil
-          grid_y = nil
-
-          GRID_SQUARES.each_with_index do |row, y|
-            row.each_with_index do |square, x|
-              if square == letters
-                grid_x = x
-                grid_y = 12 - y
-                break
-              end
-            end
-            break if grid_x
-          end
-
-          raise ArgumentError, "Invalid grid square: #{letters}" unless grid_x
+          grid_coords = GRID_SQUARE_LOOKUP[letters]
+          raise ArgumentError, "Invalid grid square: #{letters}" unless grid_coords
+          grid_x, grid_y = grid_coords
 
           @easting = grid_x * 100000 + 50000  # Center of square
           @northing = grid_y * 100000 + 50000  # Center of square
@@ -353,7 +334,7 @@ module Geodetic
         new(easting: easting, northing: northing)
       end
 
-      Coordinate.register_class(self)
+      Coordinate.register_class(self, hash_conversion_style: :with_datum)
     end
   end
 end

data/lib/geodetic/coordinate/ecef.rb

@@ -206,6 +206,10 @@ module Geodetic
         new(x: parts[0].to_f, y: parts[1].to_f, z: parts[2].to_f)
       end
 
+      def valid?
+        @x.finite? && @y.finite? && @z.finite?
+      end
+
       def ==(other)
         return false unless other.is_a?(ECEF)
 
@@ -217,7 +221,7 @@ module Geodetic
       end
 
 
-      Coordinate.register_class(self)
+      Coordinate.register_class(self, hash_conversion_style: :no_datum)
     end
   end
 end

data/lib/geodetic/coordinate/enu.rb

@@ -212,6 +212,15 @@ module Geodetic
         from_lla(lla, reference_lla)
       end
 
+      def to_h3(reference_lla, precision: 7)
+        H3.new(to_lla(reference_lla), precision: precision)
+      end
+
+      def self.from_h3(h3_coord, reference_lla)
+        lla = h3_coord.to_lla
+        from_lla(lla, reference_lla)
+      end
+
       def to_s(precision = 2)
         precision = precision.to_i
         if precision == 0
@@ -234,6 +243,10 @@ module Geodetic
         new(e: parts[0].to_f, n: parts[1].to_f, u: parts[2].to_f)
       end
 
+      def valid?
+        @e.finite? && @n.finite? && @u.finite?
+      end
+
       def ==(other)
         return false unless other.is_a?(ENU)
 

data/lib/geodetic/coordinate/gars.rb

@@ -76,12 +76,12 @@ module Geodetic
         VALID_LENGTHS.include?(@code.length) && valid_characters?(@code)
       end
 
+      protected
+
       def code_value
         @code
       end
 
-      protected
-
       def normalize(string)
         result = String.new(capacity: string.length)
         string.each_char.with_index do |ch, i|
@@ -227,7 +227,6 @@ module Geodetic
       end
 
       register_hash_system(:gars, self, default_precision: 7)
-      Coordinate.register_class(self)
     end
   end
 end

data/lib/geodetic/coordinate/georef.rb

@@ -55,12 +55,12 @@ module Geodetic
         VALID_LENGTHS.include?(@code.length) && valid_characters?(@code)
       end
 
+      protected
+
       def code_value
         @code
       end
 
-      protected
-
       def normalize(string)
         string.upcase
       end
@@ -198,7 +198,6 @@ module Geodetic
       end
 
       register_hash_system(:georef, self, default_precision: 8)
-      Coordinate.register_class(self)
     end
   end
 end

data/lib/geodetic/coordinate/gh.rb

@@ -39,13 +39,12 @@ module Geodetic
         @geohash.length > 0 && @geohash.each_char.all? { |c| CHAR_INDEX.key?(c) }
       end
 
-      # Expose code_value for base class equality and other shared methods
+      protected
+
       def code_value
         @geohash
       end
 
-      protected
-
       def normalize(string)
         string.downcase
       end
@@ -155,7 +154,6 @@ module Geodetic
       alias_method :validate_code!, :validate_geohash!
 
       register_hash_system(:gh, self, default_precision: 12)
-      Coordinate.register_class(self)
     end
   end
 end

data/lib/geodetic/coordinate/gh36.rb

@@ -74,10 +74,6 @@ module Geodetic
         @geohash.length > 0 && @geohash.each_char.all? { |c| VALID_CHARS_SET.include?(c) }
       end
 
-      def code_value
-        @geohash
-      end
-
       # --- GH36-specific overrides (matrix-based algorithms) ---
 
       # Uses recursive matrix-based neighbor calculation instead of bounds-based
@@ -105,6 +101,10 @@ module Geodetic
 
       protected
 
+      def code_value
+        @geohash
+      end
+
       def set_code(value)
         @geohash = value
       end
@@ -243,7 +243,6 @@ module Geodetic
       alias_method :validate_code!, :validate_geohash!
 
       register_hash_system(:gh36, self, default_precision: 10)
-      Coordinate.register_class(self)
     end
   end
 end