tcd 1.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 52207edb47be792acadf50b6e0c2217572de0301aa38620fc258f7485bcce803
+  data.tar.gz: a3d9fca3dfba730fa8da2d52a49c9624fd59c6b2f2d79730e17b1d394b3d76a0
+SHA512:
+  metadata.gz: 482e904705050a9bf467b149d744d3e440777db12af520fc5d8ed7883b5753cdab4c47c1b6a321ae666c8aefd973b4984da1809f2717507a01c9e98edbf7a672
+  data.tar.gz: '0971d1ed74eec9cdff65c09fe62795bfeec8c7bb20de02eb3f6d6f1aa0ac86479889b6b1f9344868eae3edfa5b624052303defdc692850d5ee1552b17dcf87ea'

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# 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).
+
+## [1.0.2] - 2026-01-20
+
+### Fixed
+
+- Strip leading colon from timezone strings returned by `Station#tzfile`
+  - TCD files store timezones with a leading colon (e.g., `:America/Los_Angeles`)
+  - Now returns standard IANA timezone names (e.g., `America/Los_Angeles`)
+  - Fixes compatibility with Ruby timezone libraries that don't recognize the colon prefix
+
+## [1.0.1] - 2026-01-20
+
+### Fixed
+
+- Fixed tide/current classification for subordinate stations with asymmetric corrections
+  - Previously, subordinate stations with different high/low time offsets or level multipliers were incorrectly classified as current stations
+  - Now correctly classifies stations based on presence of current-specific indicators (flood/ebb times, direction data)
+  - Subordinate tide stations can have different corrections for high vs low tides and are now properly identified as tide stations
+
+## [1.0.0] - 2026-01-20
+
+### Added
+
+- Initial release
+- Pure Ruby TCD file reader (no C extensions)
+- Support for TCD v2 format
+- Read reference and subordinate station records
+- Read constituent data (speeds, equilibrium arguments, node factors)
+- Constituent inference from M2, S2, K1, O1 (Schureman method)
+- Geospatial queries: `nearest_station`, `stations_near`
+- Station type detection: `tide?`, `current?`, `simple?`
+- Station search by name substring
+- `tcd-info` command-line tool
+- Comprehensive test suite

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jordan Ritter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,187 @@
+# TCD - Tidal Constituent Database Reader [![Tests](https://github.com/jpr5/tcd/actions/workflows/test.yml/badge.svg)](https://github.com/jpr5/tcd/actions/workflows/test.yml)
+
+A pure Ruby gem for reading TCD (Tidal Constituent Database) files used by [XTide](https://flaterco.com/xtide/) for tide predictions.
+
+## Features
+
+- **Pure Ruby** - No C extensions, FFI, or external dependencies
+- **Complete TCD v2 support** - Reads all station types and constituent data
+- **Lazy loading** - Stations can be iterated without loading all into memory
+- **Constituent inference** - Compute missing constituents from major ones (M2, S2, K1, O1)
+- **Geospatial queries** - Find nearest stations or stations within a radius
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'tcd'
+```
+
+Or install it directly:
+
+```bash
+gem install tcd
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+require 'tcd'
+
+TCD.open("harmonics.tcd") do |db|
+    puts "Stations: #{db.station_count}"
+    puts "Constituents: #{db.constituent_count}"
+    puts "Year Range: #{db.year_range}"
+
+    # Search for stations
+    db.find_stations("San Francisco").each do |station|
+        puts "#{station.name}: #{station.latitude}, #{station.longitude}"
+    end
+end
+```
+
+### Station Types
+
+TCD files contain two types of stations:
+
+- **Reference stations** - Have full harmonic constituent data (amplitudes & epochs)
+- **Subordinate stations** - Have time/height offsets relative to a reference station
+
+```ruby
+TCD.open("harmonics.tcd") do |db|
+    # Get only reference stations
+    db.reference_stations.each do |s|
+        puts "#{s.name}: #{s.active_constituents} constituents"
+    end
+
+    # Get only subordinate stations
+    db.subordinate_stations.each do |s|
+        puts "#{s.name}: offset from station ##{s.reference_station}"
+    end
+end
+```
+
+### Geospatial Queries
+
+```ruby
+TCD.open("harmonics.tcd") do |db|
+    # Find nearest station to coordinates
+    nearest = db.nearest_station(37.8, -122.4)
+    puts "Nearest: #{nearest.name}"
+
+    # Find nearest reference station only
+    nearest_ref = db.nearest_station(37.8, -122.4, type: :reference)
+
+    # Find all stations within 1 degree (~111 km at equator)
+    nearby = db.stations_near(37.8, -122.4, radius: 1.0)
+    puts "Found #{nearby.size} stations within 1 degree"
+end
+```
+
+### Constituent Data
+
+```ruby
+TCD.open("harmonics.tcd") do |db|
+    # Access constituent information
+    m2 = db.constituent("M2")
+    puts "M2 speed: #{m2.speed} degrees/hour"
+
+    # Get equilibrium argument for a specific year
+    eq = m2.equilibrium_for_year(2025, db.header.start_year)
+
+    # Get node factor for a specific year
+    nf = m2.node_factor_for_year(2025, db.header.start_year)
+end
+```
+
+### Constituent Inference
+
+For stations with limited observation data, you can infer missing constituents:
+
+```ruby
+TCD.open("harmonics.tcd") do |db|
+    station = db.station_by_name("Some Station")
+
+    before = station.active_constituents
+    if db.infer_constituents(station)
+        after = station.active_constituents
+        puts "Inferred #{after - before} additional constituents"
+    end
+end
+```
+
+### Station Type Detection
+
+```ruby
+TCD.open("harmonics.tcd") do |db|
+    db.stations.each do |s|
+        if s.tide?
+            puts "#{s.name} is a TIDE station"
+        elsif s.current?
+            puts "#{s.name} is a CURRENT station"
+        end
+    end
+end
+```
+
+### Command Line Tool
+
+The gem includes a `tcd-info` command for exploring TCD files:
+
+```bash
+# Show database summary
+tcd-info harmonics.tcd
+
+# List stations
+tcd-info harmonics.tcd --stations 20
+
+# Search for stations
+tcd-info harmonics.tcd --search "Boston"
+
+# List constituents
+tcd-info harmonics.tcd --constituents
+```
+
+## TCD File Format
+
+TCD files are binary databases containing:
+
+- **Header** - ASCII key-value pairs defining encoding parameters
+- **Lookup tables** - Countries, timezones, datums, level units, etc.
+- **Constituent data** - Speeds, equilibrium arguments, and node factors
+- **Station records** - Bit-packed binary records for each station
+
+This gem implements a complete reader for the TCD v2 format as documented in the [libtcd](https://flaterco.com/xtide/libtcd.html) library.
+
+## Obtaining TCD Files
+
+Harmonics data files are available from the [XTide website](https://flaterco.com/xtide/files.html). The "harmonics-dwf" files are free and contain data for thousands of stations worldwide.
+
+## Development
+
+```bash
+# Run tests
+rake test
+
+# Run tests with a specific TCD file
+TCD_TEST_FILE=/path/to/harmonics.tcd rake test
+
+# Run example program
+TCD_FILE=/path/to/harmonics.tcd rake example
+
+# Open console
+rake console
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+## Acknowledgments
+
+- [XTide](https://flaterco.com/xtide/) by David Flater
+- [libtcd](https://flaterco.com/xtide/libtcd.html) by Jan Depner and David Flater
+- Tidal analysis methods from "Manual of Harmonic Analysis and Prediction of Tides" by Paul Schureman

data/bin/tcd-info

@@ -0,0 +1,178 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/tcd"
+
+def format_number(n)
+    n.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+end
+
+def format_time_offset(minutes)
+    return "N/A" if minutes.nil?
+    sign = minutes < 0 ? "-" : "+"
+    minutes = minutes.abs
+    hours = minutes / 60
+    mins = minutes % 60
+    "#{sign}#{hours}:%02d" % mins
+end
+
+if ARGV.empty?
+    puts "Usage: tcd-info <file.tcd>"
+    puts "       tcd-info <file.tcd> --stations [limit]"
+    puts "       tcd-info <file.tcd> --search <query>"
+    puts "       tcd-info <file.tcd> --constituents"
+    exit 1
+end
+
+path = ARGV[0]
+
+unless File.exist?(path)
+    puts "Error: File not found: #{path}"
+    exit 1
+end
+
+TCD.open(path) do |db|
+    filename = File.basename(path)
+
+    puts "TCD Database: #{filename}"
+    puts "=" * (14 + filename.length)
+    puts
+    puts "Version: #{db.version}"
+    puts "Last Modified: #{db.last_modified}"
+    puts "Format: v#{db.header.major_rev}.#{db.header.minor_rev}"
+    puts
+
+    stats = db.stats
+
+    puts "Database Statistics:"
+    puts "  Total Stations: #{format_number(stats[:total_stations])}"
+    puts "  Reference Stations: #{format_number(stats[:reference_stations])}"
+    puts "  Subordinate Stations: #{format_number(stats[:subordinate_stations])}"
+    puts "  Constituents: #{stats[:constituents]}"
+    puts "  Year Range: #{stats[:year_range].first}-#{stats[:year_range].last} (#{stats[:year_range].size} years)"
+    puts "  Countries: #{stats[:countries]}"
+    puts "  Timezones: #{stats[:timezones]}"
+    puts "  Datums: #{stats[:datums]}"
+    puts "  File Size: #{format_number(stats[:file_size])} bytes"
+    puts
+
+    # Handle command-line options
+    if ARGV.include?("--constituents")
+        puts "Constituents (by speed):"
+        puts "-" * 50
+
+        # Sort by speed descending
+        sorted = db.constituents.sort_by { |c| -c.speed }
+        sorted.first(20).each do |c|
+            puts "  %-10s %12.7f °/hr" % [c.name, c.speed]
+        end
+        if sorted.size > 20
+            puts "  ... and #{sorted.size - 20} more"
+        end
+        puts
+
+    elsif ARGV.include?("--search")
+        idx = ARGV.index("--search")
+        query = ARGV[idx + 1]
+        if query.nil?
+            puts "Error: --search requires a query string"
+            exit 1
+        end
+
+        puts "Searching for: #{query}"
+        puts "-" * 50
+
+        results = db.find_stations(query)
+        if results.empty?
+            puts "  No stations found matching '#{query}'"
+        else
+            results.first(20).each_with_index do |s, i|
+                puts
+                puts "  #{i + 1}. #{s.name}"
+                type_str = s.reference? ? "Reference" : "Subordinate"
+                puts "     Type: #{type_str} | Lat: #{format('%.5f', s.latitude)} | Lon: #{format('%.5f', s.longitude)}"
+                puts "     Timezone: #{s.tzfile} | Country: #{s.country}"
+                if s.reference?
+                    puts "     Datum: #{s.datum} | Active Constituents: #{s.active_constituents}"
+                else
+                    puts "     Time Offsets: High #{format_time_offset(s.max_time_add)}, Low #{format_time_offset(s.min_time_add)}"
+                    puts "     Level Multiply: High ×#{format('%.3f', s.max_level_multiply)}, Low ×#{format('%.3f', s.min_level_multiply)}"
+                end
+            end
+            if results.size > 20
+                puts
+                puts "  ... and #{results.size - 20} more results"
+            end
+        end
+        puts
+
+    elsif ARGV.include?("--stations")
+        idx = ARGV.index("--stations")
+        limit = (ARGV[idx + 1] || "10").to_i
+
+        puts "Sample Reference Stations:"
+        puts "-" * 50
+
+        ref_stations = db.reference_stations.first(limit)
+        ref_stations.each_with_index do |s, i|
+            puts
+            puts "  #{i + 1}. #{s.name}"
+            puts "     Lat: #{format('%.5f', s.latitude)} | Lon: #{format('%.5f', s.longitude)}"
+            puts "     Timezone: #{s.tzfile} | Country: #{s.country}"
+            puts "     Datum: #{s.datum} | Offset: #{format('%.4f', s.datum_offset)} #{s.level_units}"
+            puts "     Active Constituents: #{s.active_constituents} of #{db.constituent_count}"
+        end
+
+        puts
+        puts "Sample Subordinate Stations:"
+        puts "-" * 50
+
+        sub_stations = db.subordinate_stations.first(limit)
+        sub_stations.each_with_index do |s, i|
+            puts
+            puts "  #{i + 1}. #{s.name}"
+            puts "     Lat: #{format('%.5f', s.latitude)} | Lon: #{format('%.5f', s.longitude)}"
+            puts "     Reference: Station ##{s.reference_station}"
+            puts "     Time Offsets: High #{format_time_offset(s.max_time_add)}, Low #{format_time_offset(s.min_time_add)}"
+            puts "     Level Add: High #{format('%+.3f', s.max_level_add)}, Low #{format('%+.3f', s.min_level_add)}"
+            puts "     Level Multiply: High ×#{format('%.3f', s.max_level_multiply)}, Low ×#{format('%.3f', s.min_level_multiply)}"
+        end
+        puts
+
+    else
+        # Default: show summary with a few sample stations
+        puts "Sample Reference Stations:"
+        puts "-" * 50
+
+        db.reference_stations.first(3).each_with_index do |s, i|
+            puts
+            puts "  #{i + 1}. #{s.name}"
+            puts "     Type: Reference | Lat: #{format('%.5f', s.latitude)} | Lon: #{format('%.5f', s.longitude)}"
+            puts "     Timezone: #{s.tzfile} | Country: #{s.country}"
+            puts "     Datum: #{s.datum} | Active Constituents: #{s.active_constituents}"
+        end
+
+        puts
+        puts "Sample Subordinate Stations:"
+        puts "-" * 50
+
+        db.subordinate_stations.first(3).each_with_index do |s, i|
+            puts
+            puts "  #{i + 1}. #{s.name}"
+            puts "     Type: Subordinate | Lat: #{format('%.5f', s.latitude)} | Lon: #{format('%.5f', s.longitude)}"
+            puts "     Reference: Station ##{s.reference_station}"
+            puts "     Time Offsets: High #{format_time_offset(s.max_time_add)}, Low #{format_time_offset(s.min_time_add)}"
+        end
+
+        puts
+        puts "Top Constituents by Speed:"
+        puts "-" * 50
+
+        db.constituents.sort_by { |c| -c.speed }.first(5).each do |c|
+            puts "  %-6s %12.7f °/hr" % [c.name, c.speed]
+        end
+
+        puts
+        puts "Use --stations, --constituents, or --search <query> for more details."
+    end
+end

data/lib/tcd/bit_buffer.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module TCD
+    # Pure Ruby bit-level I/O for reading arbitrary bit-width integers from a binary stream.
+    # TCD files use bit-packing where fields don't align to byte boundaries.
+    class BitBuffer
+        def initialize(io)
+            @io = io
+            @buffer = 0          # Accumulated bits (MSB first)
+            @bits_available = 0  # Number of valid bits in buffer
+        end
+
+        # Read n bits as unsigned integer (1-32 bits supported)
+        def read_uint(n)
+            raise ArgumentError, "bit count must be 1-32, got #{n}" if n < 1 || n > 32
+
+            # Fill buffer until we have enough bits
+            while @bits_available < n
+                byte = @io.readbyte
+                @buffer = (@buffer << 8) | byte
+                @bits_available += 8
+            end
+
+            # Extract top n bits
+            shift = @bits_available - n
+            value = (@buffer >> shift) & ((1 << n) - 1)
+
+            # Remove extracted bits from buffer
+            @bits_available = shift
+            @buffer &= (1 << shift) - 1
+
+            value
+        end
+
+        # Read n bits as signed integer (two's complement)
+        def read_int(n)
+            value = read_uint(n)
+            msb = 1 << (n - 1)
+            value >= msb ? value - (1 << n) : value
+        end
+
+        # Read n bits and apply scale factor: value / scale
+        def read_scaled(n, scale, signed: false)
+            raw = signed ? read_int(n) : read_uint(n)
+            raw.to_f / scale
+        end
+
+        # Read n bits with offset and scale: (raw + offset) / scale
+        # Used for constituent speeds where offset shifts the range
+        def read_offset_scaled(n, offset, scale)
+            raw = read_uint(n)
+            (raw.to_f + offset) / scale
+        end
+
+        # Discard any partial byte and align to next byte boundary
+        def align
+            @buffer = 0
+            @bits_available = 0
+        end
+
+        # Read a null-terminated string
+        # Strings in TCD are NOT byte-aligned - they start at the current bit position
+        # and are read 8 bits at a time until a null byte is found.
+        def read_cstring
+            chars = []
+            loop do
+                byte = read_uint(8)
+                break if byte == 0
+                chars << byte
+            end
+            chars.pack("C*").force_encoding("ISO-8859-1").encode("UTF-8")
+        end
+
+        # Read fixed-size string, stripping null padding
+        def read_fixed_string(size)
+            align
+            bytes = @io.read(size)
+            return "" if bytes.nil? || bytes.empty?
+            # Find first null and truncate, handle encoding
+            bytes.force_encoding("ISO-8859-1")
+            null_pos = bytes.index("\x00")
+            str = null_pos ? bytes[0, null_pos] : bytes
+            str.encode("UTF-8", invalid: :replace, undef: :replace)
+        end
+
+        # Current position in underlying IO
+        def pos
+            @io.pos
+        end
+
+        # Seek to absolute position (clears bit buffer)
+        def seek(offset)
+            @io.seek(offset)
+            align
+        end
+    end
+end

data/lib/tcd/constituent.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module TCD
+    # Data structure for tidal constituent information.
+    # Each constituent has a speed and year-indexed equilibrium/node factor arrays.
+    Constituent = Struct.new(
+        :index,          # Index in the constituent table (0-based)
+        :name,           # Constituent name (e.g., "M2", "S2", "K1")
+        :speed,          # Angular speed in degrees per hour
+        :equilibrium,    # Array of equilibrium arguments by year (degrees)
+        :node_factors,   # Array of node factors by year (dimensionless, ~1.0)
+        keyword_init: true
+    ) do
+        # Get equilibrium argument for a specific year
+        def equilibrium_for_year(year, start_year)
+            idx = year - start_year
+            return nil if idx < 0 || idx >= equilibrium.size
+            equilibrium[idx]
+        end
+
+        # Get node factor for a specific year
+        def node_factor_for_year(year, start_year)
+            idx = year - start_year
+            return nil if idx < 0 || idx >= node_factors.size
+            node_factors[idx]
+        end
+
+        def to_s
+            "#{name}: #{format('%.7f', speed)}°/hr"
+        end
+    end
+
+    # Reader for constituent data (speeds, equilibrium args, node factors).
+    # Data is stored as bit-packed arrays after the lookup tables.
+    class ConstituentData
+        attr_reader :constituents
+
+        def initialize(bit_buffer, header, lookup_tables)
+            @bit = bit_buffer
+            @header = header
+            @lookup = lookup_tables
+            @constituents = []
+            load_data
+        end
+
+        # Find constituent by name
+        def find(name)
+            @constituents.find { |c| c.name == name }
+        end
+
+        # Find constituent by index
+        def [](idx)
+            @constituents[idx]
+        end
+
+        # Number of constituents
+        def size
+            @constituents.size
+        end
+
+        # Iterate over constituents
+        def each(&block)
+            @constituents.each(&block)
+        end
+        include Enumerable
+
+        private
+
+        def load_data
+            num_constituents = @header.constituents
+            num_years = @header.number_of_years
+
+            # Read speeds for all constituents
+            speeds = read_speeds(num_constituents)
+
+            # Read equilibrium arguments: constituents × years matrix
+            equilibriums = read_equilibriums(num_constituents, num_years)
+
+            # Read node factors: constituents × years matrix
+            node_factors = read_node_factors(num_constituents, num_years)
+
+            # Build Constituent structs
+            num_constituents.times do |i|
+                @constituents << Constituent.new(
+                    index: i,
+                    name: @lookup.constituent(i) || "C#{i}",
+                    speed: speeds[i],
+                    equilibrium: equilibriums[i],
+                    node_factors: node_factors[i]
+                )
+            end
+        end
+
+        def read_speeds(count)
+            bits = @header.speed_bits
+            scale = @header.speed_scale
+            offset = @header.speed_offset || 0
+
+            count.times.map do
+                raw = @bit.read_uint(bits)
+                (raw.to_f + offset) / scale
+            end
+        end
+
+        def read_equilibriums(num_constituents, num_years)
+            bits = @header.equilibrium_bits
+            scale = @header.equilibrium_scale
+            offset = @header.equilibrium_offset || 0
+
+            num_constituents.times.map do
+                num_years.times.map do
+                    raw = @bit.read_uint(bits)
+                    (raw.to_f + offset) / scale
+                end
+            end
+        end
+
+        def read_node_factors(num_constituents, num_years)
+            bits = @header.node_bits
+            scale = @header.node_scale
+            offset = @header.node_offset || 0
+
+            num_constituents.times.map do
+                num_years.times.map do
+                    raw = @bit.read_uint(bits)
+                    (raw.to_f + offset) / scale
+                end
+            end
+        end
+    end
+end