smo_os_bng_grids 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 684430c7a6c5d3ef278e2665c6482f8e38d6ce93f390d2559bd04fddf6e19f32
-  data.tar.gz: 457fc3149fc1488920365f45b7368587a7ace3b2498abe0599254a325ea5a7ee
+  metadata.gz: a7b84aefde3700b30bac415cfc3063b022e1784142f9b7b500f9f3aea97c2e41
+  data.tar.gz: db5b6cf873e9d6f267997734544951fcc3f58db1533cba908aef4dbd4bd6a9b1
 SHA512:
-  metadata.gz: e202eea264d08736074bf8783d135382e8107045d12d163a0db6d6ac8a58c478e526c6a9baf19da0ec825d2bd37b68a36edcb49279f2ad9d53b8487db3f97de7
-  data.tar.gz: a936a88d9bedfb7efa63c74d4d56828f85c6a90202f9d8eaf23caa8ff8bb12490c4610b0b3314a2cb351a6ba959358676a83f00d17065a4ccc1b10c24764f7cd
+  metadata.gz: 10aea651302aad06011352d8f0f250c5ceb86ce6a0abcbf9584e793c66045e3596560a85b9c637aa1bf67b2c81addf29ff2b4acb2beebd57cb0353c22b06d3df
+  data.tar.gz: 1ac8d3f6d4a0ea8f9ad9f7b991e3acc45c9b87a62ddff4a3805cdb1a77bb22a74aeb3676f0a066e14d159789486f6a5e07bd9d42c116e6ad44dcb9aff299ec0b

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-04
+
+### Added
+- `SmoOsBngGrids::Grid` for point-to-grid-ref lookup, bounds retrieval, and validation
+- `SmoOsBngGrids::Lister` for listing, filtering, and spatial search of grid squares
+- `SmoOsBngGrids::ShapefileWriter` for ESRI Shapefile export
+- Support for 100km, 50km, 10km, 5km, and 1km resolutions
+- Hardcoded geometry sourced from OS BNG Grids GeoPackage
+- Circular radius and bounding box spatial search
+- Test suite covering data loading, geometry, and bounds

data/LICENSE

@@ -0,0 +1,18 @@
+Open Government Licence v3.0
+
+Copyright (c) 2026 Sebastian Madrid Ontiveros
+
+Contains OS data. Crown copyright and database right 2026.
+
+Licensed under the Open Government Licence v3.0.
+https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/
+
+You are free to copy, publish, distribute, transmit, adapt and exploit the
+information commercially or non-commercially, provided you acknowledge the
+source by including the following attribution statement:
+
+  Contains OS data. Crown copyright and database right 2026.
+
+The Ordnance Survey grid data included in this gem is sourced directly from
+the OS BNG Grids GeoPackage published by Ordnance Survey under the Open
+Government Licence v3.0.

data/README.md

@@ -0,0 +1,208 @@
+# smo_os_bng_grids
+
+Pure Ruby gem for working with **Ordnance Survey British National Grid (BNG)** squares.
+Point lookup, spatial search, bounds, corner coordinates, and Shapefile export — no external dependencies.
+
+Developed by **Sebastian Madrid Ontiveros**.
+Contains OS data. Crown copyright and database right 2025.
+Licensed under the [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).
+
+[![Gem Version](https://badge.fury.io/rb/smo_os_bng_grids.svg)](https://badge.fury.io/rb/smo_os_bng_grids)
+
+---
+
+## Features
+
+- **Hardcoded geometry** sourced directly from the OS BNG Grids GeoPackage (EPSG:27700)
+- Grid squares at **100km, 50km, 10km, 5km, and 1km** resolutions (910,091 squares total)
+- **Point lookup** — find the grid ref containing any easting/northing at any resolution
+- **Spatial search** — find all tiles intersecting a radius or bounding box around a point
+- **Bounds** — retrieve min/max easting/northing for any grid ref
+- **Corner points** — NW → NE → SE → SW → NW, ready for InfoWorks ICM `boundary_array`
+- **Shapefile export** — pure Ruby SHP/SHX/DBF/PRJ writer, no GDAL required
+- **Pure Ruby stdlib only** — works in InfoWorks ICM 2027 embedded Ruby
+
+---
+
+## Installation
+
+```ruby
+gem "smo_os_bng_grids"
+```
+
+Or install directly:
+
+```bash
+gem install smo_os_bng_grids
+```
+
+---
+
+## Quick start
+
+```ruby
+require "smo_os_bng_grids"
+
+lister = SmoOsBngGrids::Lister.new
+
+# Point lookup — what grid square is Edinburgh city centre in?
+easting  = 325000
+northing = 673000
+
+SmoOsBngGrids::Grid.ref_at(easting, northing, resolution: "10km")  # => "NT27"
+SmoOsBngGrids::Grid.ref_at(easting, northing, resolution: "1km")   # => "NT2573"
+
+# All resolutions at once
+lister.find(easting, northing)
+# => {"100km"=>"NT", "50km"=>"NTNW", "10km"=>"NT27", "5km"=>"NT27SE", "1km"=>"NT2573"}
+
+# Bounds of a grid square
+SmoOsBngGrids::Grid.bounds("NT27")
+# => {min_e: 320000, min_n: 670000, max_e: 330000, max_n: 680000}
+```
+
+---
+
+## Grid resolutions
+
+| Resolution | Count  | Example ref | Square size     |
+|-----------|--------|-------------|-----------------|
+| 100km     | 91     | `NT`        | 100km × 100km   |
+| 50km      | 364    | `NTNW`      | 50km × 50km     |
+| 10km      | 9,100  | `NT27`      | 10km × 10km     |
+| 5km       | 36,400 | `NT27SE`    | 5km × 5km       |
+| 1km       | 910,000| `NT2573`    | 1km × 1km       |
+
+---
+
+## Listing grid squares
+
+```ruby
+lister = SmoOsBngGrids::Lister.new
+
+# All 100km squares
+lister.list("100km")
+
+# All 10km squares within NT
+lister.list("10km", within: "NT")
+
+# All 1km squares within NT27
+lister.list("1km", within: "NT27")
+```
+
+Each entry is a Hash:
+
+```ruby
+{
+  ref:    "NT27",
+  min_e:  320000, min_n: 670000,
+  max_e:  330000, max_n: 680000,
+  points: [
+    [320000, 680000],  # NW
+    [330000, 680000],  # NE
+    [330000, 670000],  # SE
+    [320000, 670000],  # SW
+    [320000, 680000]   # NW (closed)
+  ]
+}
+```
+
+---
+
+## Spatial search
+
+Find all tiles intersecting a radius or bounding box around a point:
+
+```ruby
+lister = SmoOsBngGrids::Lister.new
+
+# All 10km tiles within 12km of Edinburgh
+tiles = lister.search(325000, 673000, resolution: "10km", radius: 12000)
+tiles.each { |t| puts "#{t[:ref]}  #{t[:distance_m]} m" }
+
+# All 1km tiles within 1.5km of Edinburgh
+lister.search(325000, 673000, resolution: "1km", radius: 1500)
+
+# All 5km tiles within a 15km box around Edinburgh
+lister.search(325000, 673000, resolution: "5km", box: 15000)
+```
+
+Radius search also returns `:distance_m` — `0.0` when the point is inside the tile.
+
+---
+
+## Corner points — InfoWorks ICM
+
+Every entry returned by `list`, `search`, and `entry_for` includes a `:points` array in **NW → NE → SE → SW → NW** order, matching the InfoWorks ICM `boundary_array` convention:
+
+```ruby
+lister = SmoOsBngGrids::Lister.new
+
+# Single tile containing a point
+tile = lister.search(325000, 673000, resolution: "10km", radius: 1).first
+boundary_array = tile[:points]
+# => [[320000, 680000], [330000, 680000], [330000, 670000], [320000, 670000], [320000, 680000]]
+
+# Flat XY array if needed
+flat_xy = tile[:points].flatten
+# => [320000, 680000, 330000, 680000, 330000, 670000, 320000, 670000, 320000, 680000]
+
+# Convert a ref string to a full entry
+entry = lister.entry_for("NT27SE")
+entry[:points]  # => [[325000, 675000], [330000, 675000], [330000, 670000], [325000, 670000], [325000, 675000]]
+```
+
+---
+
+## Shapefile export
+
+Export any set of entries to ESRI Shapefile format (OSGB36 / EPSG:27700).
+Pure Ruby — no GDAL, no external gems, works in InfoWorks ICM 2027.
+
+```ruby
+lister = SmoOsBngGrids::Lister.new
+writer = SmoOsBngGrids::ShapefileWriter.new
+
+# From list()
+writer.write(lister.list("10km", within: "NT"), "/tmp/nt_10km")
+
+# From search()
+entries = lister.search(325000, 673000, resolution: "10km", radius: 20000)
+writer.write(entries, "/tmp/edinburgh_10km_20km")
+
+# From find() — one tile per resolution
+found = lister.find(325000, 673000)
+found.each do |res, ref|
+  writer.write([lister.entry_for(ref)], "/tmp/edinburgh_#{res}")
+end
+```
+
+Produces `.shp`, `.shx`, `.dbf`, `.prj` — open directly in QGIS or ArcGIS.
+
+---
+
+## Grid reference validation
+
+```ruby
+SmoOsBngGrids::Grid.valid?("NT")      # => true
+SmoOsBngGrids::Grid.valid?("NT27")    # => true
+SmoOsBngGrids::Grid.valid?("NT2573")  # => true
+SmoOsBngGrids::Grid.valid?("ZZ")      # => false
+```
+
+---
+
+## Data
+
+All geometry is hardcoded from the **OS BNG Grids GeoPackage** published by Ordnance Survey.
+Source: [github.com/OrdnanceSurvey/osbng-grids](https://github.com/OrdnanceSurvey/osbng-grids)
+
+Contains OS data. Crown copyright and database right 2025.
+Licensed under the Open Government Licence v3.0.
+
+---
+
+## Attribution
+
+Built by **Sebastian Madrid Ontiveros** to support hydraulic modelling and flood risk workflows in the UK.
+If this gem saves you time, consider [buying Sebastian a coffee](https://buymeacoffee.com/smadrid).

data/lib/smo_os_bng_grids/constants.rb

@@ -32,6 +32,9 @@ module SmoOsBngGrids
 
   QUADRANTS = %w[SW SE NW NE].freeze
 
+  MSG_INVALID_RESOLUTION = "Unknown resolution %s. Valid: #{VALID_RESOLUTIONS.join(', ')}"
+  MSG_PROVIDE_RADIUS_OR_BOX = "Provide radius: or box: (not both)"
+
   # Quadrant offsets [easting_offset, northing_offset] from parent SW corner.
   QUADRANT_OFFSETS = {
     "SW" => [0,      0],

data/lib/smo_os_bng_grids/grid.rb

@@ -162,7 +162,7 @@ module SmoOsBngGrids
     def self.validate_resolution!(res)
       return if VALID_RESOLUTIONS.include?(res)
 
-      raise ArgumentError, "Unknown resolution #{res.inspect}. Valid: #{VALID_RESOLUTIONS.join(', ')}"
+      raise ArgumentError, format(MSG_INVALID_RESOLUTION, res.inspect)
     end
 
     def self.validate_coords!(easting, northing)

data/lib/smo_os_bng_grids/lister.rb

@@ -33,8 +33,8 @@ module SmoOsBngGrids
     # @return [Array<Hash>] matching entries, each with :ref, :min_e, :min_n,
     #                       :max_e, :max_n, :points, :distance_m (circle only)
     def search(easting, northing, resolution: "10km", radius: nil, box: nil)
-      raise ArgumentError, "Provide radius: or box: (not both)" if radius.nil? && box.nil?
-      raise ArgumentError, "Provide radius: or box: (not both)" if radius && box
+      raise ArgumentError, MSG_PROVIDE_RADIUS_OR_BOX if radius.nil? && box.nil?
+      raise ArgumentError, MSG_PROVIDE_RADIUS_OR_BOX if radius && box
 
       Grid.validate_coords!(easting, northing)
       validate_resolution!(resolution)
@@ -153,7 +153,7 @@ module SmoOsBngGrids
     def validate_resolution!(res)
       return if VALID_RESOLUTIONS.include?(res)
 
-      raise ArgumentError, "Unknown resolution #{res.inspect}. Valid: #{VALID_RESOLUTIONS.join(', ')}"
+      raise ArgumentError, format(MSG_INVALID_RESOLUTION, res.inspect)
     end
   end
 end

data/lib/smo_os_bng_grids/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SmoOsBngGrids
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: smo_os_bng_grids
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Sebastian Madrid Ontiveros
 bindir: bin
 cert_chain: []
-date: 2026-05-04 00:00:00.000000000 Z
+date: 2026-06-10 00:00:00.000000000 Z
 dependencies: []
 description: |
   Developed by Sebastian Madrid Ontiveros. Pure Ruby gem providing all Ordnance Survey
@@ -20,11 +20,15 @@ description: |
   Built to support hydraulic modelling and flood risk workflows in the UK.
   If this gem saves you time, consider buying Sebastian a coffee at
   https://buymeacoffee.com/smadrid
-email: []
+email:
+- sebasmadrid20@hotmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
+- README.md
 - lib/smo_os_bng_grids.rb
 - lib/smo_os_bng_grids/constants.rb
 - lib/smo_os_bng_grids/data/grid_100km.rb