tcd 1.0.2

data/lib/tcd/header.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module TCD
+    # Parser for TCD ASCII header section.
+    # The header contains [KEY] = VALUE pairs defining all encoding parameters.
+    class Header
+        REQUIRED_KEYS = %i[
+            header_size number_of_records constituents
+            start_year number_of_years
+        ].freeze
+
+        attr_reader :params
+
+        def initialize(io)
+            @params = {}
+            parse(io)
+            validate!
+        end
+
+        # Access header parameters by symbol key
+        def [](key)
+            @params[key]
+        end
+
+        # Check if key exists
+        def key?(key)
+            @params.key?(key)
+        end
+
+        # All parameter keys
+        def keys
+            @params.keys
+        end
+
+        # Convenience accessors for commonly used parameters
+        def header_size;       @params[:header_size]; end
+        def number_of_records; @params[:number_of_records]; end
+        def constituents;      @params[:constituents]; end
+        def start_year;        @params[:start_year]; end
+        def number_of_years;   @params[:number_of_years]; end
+        def version;           @params[:version]; end
+        def major_rev;         @params[:major_rev]; end
+        def minor_rev;         @params[:minor_rev]; end
+        def last_modified;     @params[:last_modified]; end
+        def end_of_file;       @params[:end_of_file]; end
+
+        # Bit field parameters
+        def speed_bits;        @params[:speed_bits]; end
+        def speed_scale;       @params[:speed_scale]; end
+        def speed_offset;      @params[:speed_offset]; end
+        def equilibrium_bits;  @params[:equilibrium_bits]; end
+        def equilibrium_scale; @params[:equilibrium_scale]; end
+        def equilibrium_offset; @params[:equilibrium_offset]; end
+        def node_bits;         @params[:node_bits]; end
+        def node_scale;        @params[:node_scale]; end
+        def node_offset;       @params[:node_offset]; end
+        def amplitude_bits;    @params[:amplitude_bits]; end
+        def amplitude_scale;   @params[:amplitude_scale]; end
+        def epoch_bits;        @params[:epoch_bits]; end
+        def epoch_scale;       @params[:epoch_scale]; end
+
+        # Record field parameters
+        def record_type_bits;  @params[:record_type_bits]; end
+        def latitude_bits;     @params[:latitude_bits]; end
+        def latitude_scale;    @params[:latitude_scale]; end
+        def longitude_bits;    @params[:longitude_bits]; end
+        def longitude_scale;   @params[:longitude_scale]; end
+        def record_size_bits;  @params[:record_size_bits]; end
+        def station_bits;      @params[:station_bits]; end
+        def datum_offset_bits; @params[:datum_offset_bits]; end
+        def datum_offset_scale; @params[:datum_offset_scale]; end
+        def date_bits;         @params[:date_bits]; end
+        def months_on_station_bits; @params[:months_on_station_bits]; end
+        def confidence_value_bits; @params[:confidence_value_bits]; end
+        def time_bits;         @params[:time_bits]; end
+        def level_add_bits;    @params[:level_add_bits]; end
+        def level_add_scale;   @params[:level_add_scale]; end
+        def level_multiply_bits; @params[:level_multiply_bits]; end
+        def level_multiply_scale; @params[:level_multiply_scale]; end
+        def direction_bits;    @params[:direction_bits]; end
+
+        # Lookup table parameters
+        def level_unit_bits;   @params[:level_unit_bits]; end
+        def level_unit_types;  @params[:level_unit_types]; end
+        def level_unit_size;   @params[:level_unit_size]; end
+        def direction_unit_bits; @params[:direction_unit_bits]; end
+        def direction_unit_types; @params[:direction_unit_types]; end
+        def direction_unit_size; @params[:direction_unit_size]; end
+        def restriction_bits;  @params[:restriction_bits]; end
+        def restriction_types; @params[:restriction_types]; end
+        def restriction_size;  @params[:restriction_size]; end
+        def datum_bits;        @params[:datum_bits]; end
+        def datum_types;       @params[:datum_types]; end
+        def datum_size;        @params[:datum_size]; end
+        def legalese_bits;     @params[:legalese_bits]; end
+        def legalese_types;    @params[:legalese_types]; end
+        def legalese_size;     @params[:legalese_size]; end
+        def constituent_bits;  @params[:constituent_bits]; end
+        def constituent_size;  @params[:constituent_size]; end
+        def tzfile_bits;       @params[:tzfile_bits]; end
+        def tzfiles;           @params[:tzfiles]; end
+        def tzfile_size;       @params[:tzfile_size]; end
+        def country_bits;      @params[:country_bits]; end
+        def countries;         @params[:countries]; end
+        def country_size;      @params[:country_size]; end
+
+        private
+
+        def parse(io)
+            io.rewind
+            io.each_line do |line|
+                line = line.strip
+                break if line == "[END OF ASCII HEADER DATA]"
+                next if line.empty?
+
+                if line =~ /^\[(.+?)\]\s*=\s*(.+)$/
+                    key = normalize_key($1)
+                    value = parse_value($2)
+                    @params[key] = value
+                end
+            end
+        end
+
+        def normalize_key(key)
+            key.downcase.gsub(/\s+/, "_").to_sym
+        end
+
+        def parse_value(value)
+            value = value.strip
+            case value
+            when /^-?\d+$/
+                value.to_i
+            when /^-?\d+\.\d+$/
+                value.to_f
+            else
+                value
+            end
+        end
+
+        def validate!
+            missing = REQUIRED_KEYS.reject { |k| @params.key?(k) }
+            unless missing.empty?
+                raise FormatError, "missing required header keys: #{missing.join(', ')}"
+            end
+        end
+    end
+
+    class FormatError < StandardError; end
+end

data/lib/tcd/inference.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module TCD
+    # Computes inferred constituents when M2, S2, K1, and O1 are given.
+    # This fills remaining unfilled constituents based on article 230 of
+    # "Manual of Harmonic Analysis and Prediction of Tides",
+    # Paul Schureman, C & GS special publication no. 98, October 1971.
+    #
+    # This is useful for stations with short observation periods that only
+    # have a few major constituents developed. The inferred constituents
+    # can improve tide predictions.
+    module Inference
+        # Semi-diurnal constituents that can be inferred from M2 and S2
+        INFERRED_SEMI_DIURNAL = %w[N2 NU2 MU2 2N2 LDA2 T2 R2 L2 K2 KJ2].freeze
+
+        # Coefficients for semi-diurnal inference (relative to M2)
+        SEMI_DIURNAL_COEFF = [
+            0.1759,  # N2
+            0.0341,  # NU2
+            0.0219,  # MU2
+            0.0235,  # 2N2
+            0.0066,  # LDA2
+            0.0248,  # T2
+            0.0035,  # R2
+            0.0251,  # L2
+            0.1151,  # K2
+            0.0064   # KJ2
+        ].freeze
+
+        # Diurnal constituents that can be inferred from K1 and O1
+        INFERRED_DIURNAL = %w[OO1 M1 J1 RHO1 Q1 2Q1 P1 PI1 PHI1 PSI1].freeze
+
+        # Coefficients for diurnal inference (relative to O1)
+        DIURNAL_COEFF = [
+            0.0163,  # OO1
+            0.0209,  # M1
+            0.0297,  # J1
+            0.0142,  # RHO1
+            0.0730,  # Q1
+            0.0097,  # 2Q1
+            0.1755,  # P1
+            0.0103,  # PI1
+            0.0076,  # PHI1
+            0.0042   # PSI1
+        ].freeze
+
+        # Reference coefficients for M2 and O1
+        M2_COEFF = 0.9085
+        O1_COEFF = 0.3771
+
+        # Infer missing constituents for a reference station.
+        #
+        # Requires the station to have non-zero values for M2, S2, K1, and O1.
+        # Modifies the station's amplitudes and epochs arrays in place.
+        #
+        # @param station [Station] A reference station with amplitudes/epochs arrays
+        # @param constituent_data [ConstituentData] The constituent data from the reader
+        # @return [Boolean] true if inference was performed, false if not enough data
+        def self.infer_constituents(station, constituent_data)
+            return false unless station.reference?
+            return false unless station.amplitudes && station.epochs
+
+            # Find the required constituents
+            m2 = constituent_data.find("M2")
+            s2 = constituent_data.find("S2")
+            k1 = constituent_data.find("K1")
+            o1 = constituent_data.find("O1")
+
+            return false unless m2 && s2 && k1 && o1
+
+            m2_idx = m2.index
+            s2_idx = s2.index
+            k1_idx = k1.index
+            o1_idx = o1.index
+
+            # Check that all four required constituents have non-zero values
+            return false if station.amplitudes[m2_idx] == 0.0
+            return false if station.amplitudes[s2_idx] == 0.0
+            return false if station.amplitudes[k1_idx] == 0.0
+            return false if station.amplitudes[o1_idx] == 0.0
+
+            # Get the epochs, handling wrap-around
+            epoch_m2 = station.epochs[m2_idx]
+            epoch_s2 = station.epochs[s2_idx]
+            epoch_k1 = station.epochs[k1_idx]
+            epoch_o1 = station.epochs[o1_idx]
+
+            # Build lookup from constituent name to index
+            constituent_lookup = {}
+            constituent_data.each_with_index do |c, idx|
+                constituent_lookup[c.name] = idx
+            end
+
+            # Infer semi-diurnal constituents
+            INFERRED_SEMI_DIURNAL.each_with_index do |name, j|
+                idx = constituent_lookup[name]
+                next unless idx
+                next unless station.amplitudes[idx] == 0.0 && station.epochs[idx] == 0.0
+
+                constituent = constituent_data[idx]
+                next unless constituent
+
+                # Compute amplitude
+                station.amplitudes[idx] = (SEMI_DIURNAL_COEFF[j] / M2_COEFF) *
+                                          station.amplitudes[m2_idx]
+
+                # Compute epoch with wrap-around handling
+                e_m2 = epoch_m2
+                e_s2 = epoch_s2
+                if (e_s2 - e_m2).abs > 180.0
+                    if e_s2 < e_m2
+                        e_s2 += 360.0
+                    else
+                        e_m2 += 360.0
+                    end
+                end
+
+                speed_diff_ratio = (constituent.speed - m2.speed) / (s2.speed - m2.speed)
+                station.epochs[idx] = e_m2 + speed_diff_ratio * (e_s2 - e_m2)
+            end
+
+            # Infer diurnal constituents
+            INFERRED_DIURNAL.each_with_index do |name, j|
+                idx = constituent_lookup[name]
+                next unless idx
+                next unless station.amplitudes[idx] == 0.0 && station.epochs[idx] == 0.0
+
+                constituent = constituent_data[idx]
+                next unless constituent
+
+                # Compute amplitude
+                station.amplitudes[idx] = (DIURNAL_COEFF[j] / O1_COEFF) *
+                                          station.amplitudes[o1_idx]
+
+                # Compute epoch with wrap-around handling
+                e_k1 = epoch_k1
+                e_o1 = epoch_o1
+                if (e_k1 - e_o1).abs > 180.0
+                    if e_k1 < e_o1
+                        e_k1 += 360.0
+                    else
+                        e_o1 += 360.0
+                    end
+                end
+
+                speed_diff_ratio = (constituent.speed - o1.speed) / (k1.speed - o1.speed)
+                station.epochs[idx] = e_o1 + speed_diff_ratio * (e_k1 - e_o1)
+            end
+
+            true
+        end
+    end
+end

data/lib/tcd/lookup_tables.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module TCD
+    # Reader for TCD lookup tables (fixed-size string arrays).
+    #
+    # TCD v2 stores string tables in this order after the 4-byte checksum:
+    # 1. Level units (level_unit_types × level_unit_size) - exact count
+    # 2. Direction units (dir_unit_types × dir_unit_size) - exact count
+    # 3. Restrictions (max_restriction_types × restriction_size) - reads until "__END__"
+    # 4. [v1 only: Pedigrees - skipped in v2]
+    # 5. Timezones (max_tzfiles × tzfile_size) - reads until "__END__"
+    # 6. Countries (max_countries × country_size) - reads until "__END__"
+    # 7. Datums (max_datum_types × datum_size) - reads until "__END__"
+    # 8. [v2 only: Legalese (max_legaleses × legalese_size) - reads until "__END__"]
+    # 9. Constituent names (constituents × constituent_size) - exact count
+    # 10. Constituent speeds (bit-packed)
+    # 11. Equilibrium arguments (bit-packed)
+    # 12. Node factors (bit-packed)
+    # 13. Station records (bit-packed)
+    #
+    class LookupTables
+        attr_reader :level_units, :direction_units, :restrictions
+        attr_reader :legalese, :datums, :constituents
+        attr_reader :timezones, :countries
+
+        # Positions tracked for the reader
+        attr_reader :constituent_data_offset  # Where bit-packed constituent data starts
+        attr_reader :station_records_offset   # Where station records start
+
+        def initialize(io, header)
+            @io = io
+            @header = header
+            load_tables
+        end
+
+        # Lookup by index with bounds checking
+        def level_unit(idx);     safe_lookup(@level_units, idx); end
+        def direction_unit(idx); safe_lookup(@direction_units, idx); end
+        def restriction(idx);    safe_lookup(@restrictions, idx); end
+        def legalese_text(idx);  safe_lookup(@legalese, idx); end
+        def datum(idx);          safe_lookup(@datums, idx); end
+        def constituent(idx);    safe_lookup(@constituents, idx); end
+        def country(idx);        safe_lookup(@countries, idx); end
+
+        # Timezone strings in TCD files have a leading colon (e.g., ":America/New_York")
+        # Strip it to return standard IANA timezone names
+        def timezone(idx)
+            tz = safe_lookup(@timezones, idx)
+            tz&.sub(/^:/, '')
+        end
+
+        private
+
+        def load_tables
+            # Seek to start of binary section (right after ASCII header)
+            @io.seek(@header.header_size)
+
+            # Skip 4-byte CRC/checksum at start of binary section
+            @io.read(4)
+
+            # Tables are stored in fixed order per libtcd.
+            # Some tables use exact count, others allocate max space based on bits.
+
+            # 1. Level units - exact count
+            @level_units = read_table_exact(@header.level_unit_types, @header.level_unit_size)
+
+            # 2. Direction units - exact count
+            @direction_units = read_table_exact(@header.direction_unit_types, @header.direction_unit_size)
+
+            # 3. Restrictions - max entries based on bits, reads until "__END__"
+            max_restrictions = 2**@header.restriction_bits
+            @restrictions = read_table_with_end(max_restrictions, @header.restriction_size)
+
+            # 4. Pedigrees - skipped in v2 (major_rev >= 2)
+            #    In v1, space was allocated: pedigree_size × 2^pedigree_bits
+            #    But in v2, we skip this entirely
+            if @header.major_rev && @header.major_rev < 2 && @header[:pedigree_bits] && @header[:pedigree_size]
+                pedigree_max = 2**@header[:pedigree_bits]
+                @io.seek(@io.pos + pedigree_max * @header[:pedigree_size])
+            end
+
+            # 5. Timezones - max entries based on bits, reads until "__END__"
+            max_tzfiles = 2**@header.tzfile_bits
+            @timezones = read_table_with_end(max_tzfiles, @header.tzfile_size)
+
+            # 6. Countries - max entries based on bits, reads until "__END__"
+            max_countries = 2**@header.country_bits
+            @countries = read_table_with_end(max_countries, @header.country_size)
+
+            # 7. Datums - max entries based on bits, reads until "__END__"
+            max_datums = 2**@header.datum_bits
+            @datums = read_table_with_end(max_datums, @header.datum_size)
+
+            # 8. Legalese - v2 only (major_rev >= 2), max based on bits
+            if @header.major_rev && @header.major_rev >= 2 && @header.legalese_bits && @header.legalese_size
+                max_legaleses = 2**@header.legalese_bits
+                @legalese = read_table_with_end(max_legaleses, @header.legalese_size)
+            else
+                @legalese = ["NULL"]
+            end
+
+            # 9. Constituent names - exact count
+            @constituents = read_table_exact(@header.constituents, @header.constituent_size)
+
+            # After constituent names, constituent binary data begins (speeds, equilibriums, node factors)
+            @constituent_data_offset = @io.pos
+
+            # Calculate size of constituent binary data in bytes
+            constituent_bytes = calculate_constituent_data_bytes
+            @station_records_offset = @constituent_data_offset + constituent_bytes
+        end
+
+        # Read a table with exact count (no __END__ marker)
+        def read_table_exact(count, entry_size)
+            entries = []
+            count.times do
+                bytes = @io.read(entry_size)
+                break if bytes.nil? || bytes.empty?
+                entries << decode_string(bytes)
+            end
+            entries
+        end
+
+        # Read a table that uses __END__ as terminator but allocates max space
+        def read_table_with_end(max_entries, entry_size)
+            start_pos = @io.pos
+            entries = []
+
+            max_entries.times do
+                bytes = @io.read(entry_size)
+                break if bytes.nil? || bytes.empty?
+
+                str = decode_string(bytes)
+                break if str == "__END__"
+
+                entries << str
+            end
+
+            # Seek past the full allocated space regardless of where __END__ was found
+            @io.seek(start_pos + max_entries * entry_size)
+            entries
+        end
+
+        def decode_string(bytes)
+            # Handle encoding: TCD uses ISO-8859-1
+            bytes.force_encoding("ISO-8859-1")
+
+            # Find null terminator and truncate
+            null_pos = bytes.index("\x00")
+            str = null_pos ? bytes[0, null_pos] : bytes
+
+            # Convert to UTF-8 for Ruby compatibility
+            str.encode("UTF-8", invalid: :replace, undef: :replace)
+        end
+
+        def calculate_constituent_data_bytes
+            num_c = @header.constituents
+            num_y = @header.number_of_years
+
+            # In v2, we use bits2bytes which is (bits + 7) / 8
+            # In v1, there was a "wasted byte bug": (bits / 8) + 1
+
+            is_v1 = @header.major_rev && @header.major_rev < 2
+
+            # Speeds: one per constituent
+            speed_bits = num_c * @header.speed_bits
+            speed_bytes = is_v1 ? (speed_bits / 8) + 1 : (speed_bits + 7) / 8
+
+            # Equilibrium arguments: constituents × years matrix
+            eq_bits = num_c * num_y * @header.equilibrium_bits
+            eq_bytes = is_v1 ? (eq_bits / 8) + 1 : (eq_bits + 7) / 8
+
+            # Node factors: constituents × years matrix
+            node_bits = num_c * num_y * @header.node_bits
+            node_bytes = is_v1 ? (node_bits / 8) + 1 : (node_bits + 7) / 8
+
+            speed_bytes + eq_bytes + node_bytes
+        end
+
+        def safe_lookup(table, idx)
+            return nil if idx.nil? || idx < 0 || idx >= table.size
+            table[idx]
+        end
+    end
+end