Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,17 @@ 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.1.0] - 2026-10-12

### Added

- `TCD::Writer`: writes TCD files that libtcd and XTide read (`Writer.from_reader(reader)` or plain data)
- Verify the header CRC-32 on open, as libtcd does; a mismatch raises `TCD::ChecksumError` (`Reader.new(path, verify_checksum: false)` skips it)

### Fixed

- Read the equilibrium and node-factor tables of a TCD whose constituent count is not a multiple of 8 (each table starts on a byte boundary, as libtcd writes it)

## [1.0.2] - 2026-01-20

### Fixed
Expand Down
22 changes: 22 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,28 @@ TCD.open("harmonics.tcd") do |db|
end
```

### Writing TCD Files

`TCD::Writer` writes a file that libtcd and XTide read. Copy a file you read:

```ruby
TCD.open("harmonics.tcd") { |db| TCD::Writer.from_reader(db).write("copy.tcd") }
```

Or build one from plain data (units as the reader returns them; time offsets in minutes):

```ruby
writer = TCD::Writer.new(
constituents: [{ name: "M2", speed: 28.9841042, equilibrium: [10.5, 200.25], node_factors: [0.98, 1.02] }],
start_year: 2025
)
writer.add_station(name: "Example", latitude: 59.9, longitude: 10.75, tzfile: "Europe/Oslo",
level_units: "meters", amplitudes: [0.5], epochs: [120.0])
writer.write("example.tcd")
```

Values that do not fit their field (for example a name over 89 bytes in ISO-8859-1) raise `ArgumentError`. `zone_offset` is a signed HHMM integer (`-500` for UTC-5), not minutes; epochs must be 0–360 degrees; dates are 0 or YYYYMMDD.

### Command Line Tool

The gem includes a `tcd-info` command for exploring TCD files:
Expand Down
1 change: 1 addition & 0 deletions lib/tcd.rb
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
require_relative "tcd/version"
require_relative "tcd/reader"
require_relative "tcd/inference"
require_relative "tcd/writer"

module TCD
class << self
Expand Down
7 changes: 7 additions & 0 deletions lib/tcd/constituent.rb
Original file line number Diff line number Diff line change
Expand Up @@ -73,9 +73,16 @@ def load_data
# Read speeds for all constituents
speeds = read_speeds(num_constituents)

# libtcd writes each table into its own whole number of bytes, so skip the
# padding bits that end the previous table (none when the bit count is a
# multiple of 8, e.g. 176 constituents; some for 178).
@bit.align

# Read equilibrium arguments: constituents × years matrix
equilibriums = read_equilibriums(num_constituents, num_years)

@bit.align

# Read node factors: constituents × years matrix
node_factors = read_node_factors(num_constituents, num_years)

Expand Down
33 changes: 33 additions & 0 deletions lib/tcd/header.rb
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# frozen_string_literal: true

require "zlib"

module TCD
# Parser for TCD ASCII header section.
# The header contains [KEY] = VALUE pairs defining all encoding parameters.
Expand Down Expand Up @@ -104,6 +106,36 @@ def country_bits; @params[:country_bits]; end
def countries; @params[:countries]; end
def country_size; @params[:country_size]; end

# CRC-32 of the ASCII header padded to header_size bytes, as libtcd's
# header_checksum() computes it.
def compute_checksum(io)
io.seek(0)
data = io.read(header_size)
if data.nil? || data.bytesize < header_size
raise FormatError, "file is shorter than its #{header_size}-byte header"
end
Zlib.crc32(data)
end

# The CRC-32 stored in the 4 bytes after the header (big-endian).
def stored_checksum(io)
io.seek(header_size)
bytes = io.read(4)
raise FormatError, "file ends before the header checksum" if bytes.nil? || bytes.bytesize < 4
bytes.unpack1("N")
end

# Raises ChecksumError unless the stored checksum matches the header.
# libtcd refuses to open such a file.
def verify_checksum!(io)
stored = stored_checksum(io)
computed = compute_checksum(io)
return if stored == computed

raise ChecksumError, format("header checksum mismatch: stored 0x%08x, computed 0x%08x " \
"(the ASCII header was modified or the file is corrupt)", stored, computed)
end

private

def parse(io)
Expand Down Expand Up @@ -146,4 +178,5 @@ def validate!
end

class FormatError < StandardError; end
class ChecksumError < FormatError; end
end
13 changes: 12 additions & 1 deletion lib/tcd/reader.rb
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,11 @@ module TCD
class Reader
attr_reader :path, :header, :lookup_tables, :constituent_data

def initialize(path)
# verify_checksum: false skips the header CRC-32 check (on by default, as
# in libtcd). Only for files known to carry no valid checksum.
def initialize(path, verify_checksum: true)
@path = path
@verify_checksum = verify_checksum
@file = File.open(path, "rb")
@stations_loaded = false
@stations = []
Expand Down Expand Up @@ -193,6 +196,7 @@ def stats
def load_metadata
# Parse ASCII header
@header = Header.new(@file)
verify_checksum if @verify_checksum

# Load lookup tables (handles interleaved string tables and binary data)
# This also identifies the constituent data offset and station records offset
Expand All @@ -207,6 +211,13 @@ def load_metadata
@stations_offset = @lookup_tables.station_records_offset
end

def verify_checksum
@header.verify_checksum!(@file)
rescue FormatError
close
raise
end

def load_stations
return if @stations_loaded

Expand Down
2 changes: 1 addition & 1 deletion lib/tcd/version.rb
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# frozen_string_literal: true

module TCD
VERSION = "1.0.2"
VERSION = "1.1.0"
end
Loading
Loading