fits_parser 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 55051bb0876a15d09837328787edb5d4105d104e3c65f3eafe99724681d54a18
+  data.tar.gz: 44048b67f3a83a50799d2b4165ff1098705f9e2a331ee2833667c9e3b72bd231
+SHA512:
+  metadata.gz: ecf542f8a1809cf7451fb4bfb4050ebcd874bf3d3566215b1c9cb7ad7e2993c288df474eb599ecded906f6c085ae2485484271904c5245b303f32f2dc1afc4e1
+  data.tar.gz: e5945ff730f26b2a41ecb5858650551bdb8ef883c92605acfb5bd665d464ef1ab0076c8acaf43e97deb8de722fabe3249ebbb6493131cd9e6606b8cfd55fe4a3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,128 @@
+# fits_parser
+
+A minimal Ruby gem to parse astronomy FITS files (`.fit` / `.fits`).
+
+## Features
+
+- Parse FITS HDUs and headers.
+- Convert common FITS header value types (string, bool, int, float).
+- Read basic BINTABLE metadata and rows for common `TFORM` codes (`A`, `B`, `I`, `J`, `K`, `E`, `D`).
+
+## Install
+
+```bash
+gem build fits_parser.gemspec
+gem install ./fits_parser-0.1.0.gem
+```
+
+## Usage
+
+```ruby
+require "fits_parser"
+
+parser = FitsParser.new("/path/to/file.fit")
+hdus = parser.parse_hdus
+
+table_hdu = hdus.find { |h| h[:header]["XTENSION"] == "BINTABLE" }
+if table_hdu
+  table = parser.read_bintable(table_hdu)
+  p table[:columns]
+  p table[:rows].first
+end
+
+parser.close
+```
+
+Using block form:
+
+```ruby
+FitsParser.open("/path/to/file.fits") do |parser|
+  p parser.parse_hdus
+end
+```
+
+### Stream BINTABLE rows (memory-safe)
+
+Use this when tables are large and you do not want to load all rows at once.
+
+```ruby
+require "fits_parser"
+
+FitsParser.open("/path/to/file.fits") do |parser|
+  hdus = parser.parse_hdus
+  table_hdu = hdus.find { |h| h[:header]["XTENSION"] == "BINTABLE" }
+  raise "No BINTABLE found" unless table_hdu
+
+  columns = parser.bintable_columns(table_hdu)
+  p columns
+
+  parser.each_bintable_row(table_hdu).with_index do |row, idx|
+    puts "row=#{idx} #{row.inspect}"
+    break if idx >= 4 # sample only first 5 rows
+  end
+end
+```
+
+### Read one specific row by index
+
+```ruby
+require "fits_parser"
+
+target_index = 123
+
+FitsParser.open("/path/to/file.fits") do |parser|
+  hdu = parser.parse_hdus.find { |h| h[:header]["XTENSION"] == "BINTABLE" }
+  row = nil
+  parser.each_bintable_row(hdu).with_index do |r, i|
+    if i == target_index
+      row = r
+      break
+    end
+  end
+  p row
+end
+```
+
+## API Summary
+
+- `FitsParser.new(path)` opens a FITS file.
+- `FitsParser.open(path) { |parser| ... }` block form with auto-close.
+- `parse_hdus` returns HDU metadata (headers, data positions, sizes).
+- `read_bintable(hdu)` returns `{ columns:, rows: }` (loads all rows).
+- `bintable_columns(hdu)` returns column metadata only.
+- `each_bintable_row(hdu)` yields rows one by one (streaming).
+- `close` closes the file handle.
+
+## CLI
+
+```bash
+bin/fits-parser /path/to/file.fit
+```
+
+Prints a JSON summary of HDUs.
+
+## Testing
+
+Run tests:
+
+```bash
+rake test
+```
+
+Alternative direct test command:
+
+```bash
+ruby -Ilib:test test/fits_parser_test.rb
+```
+
+Quick syntax checks:
+
+```bash
+ruby -c lib/fits_parser.rb
+ruby -c lib/fits_parser/parser.rb
+```
+
+## Notes
+
+- FITS is broad; this gem intentionally implements a practical subset.
+- Variable-length arrays and many advanced FITS conventions are not yet supported.

data/bin/fits-parser

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require_relative "../lib/fits_parser"
+
+path = ARGV[0]
+abort "Usage: fits-parser /path/to/file.fit" if path.nil? || path.strip.empty?
+
+FitsParser.open(path) do |parser|
+  hdus = parser.parse_hdus
+  summary = hdus.map.with_index do |hdu, idx|
+    header = hdu[:header]
+    {
+      index: idx,
+      xtension: header["XTENSION"] || "PRIMARY",
+      extname: header["EXTNAME"],
+      naxis: header["NAXIS"],
+      naxis1: header["NAXIS1"],
+      naxis2: header["NAXIS2"],
+      tfields: header["TFIELDS"],
+      data_size: hdu[:data_size]
+    }
+  end
+
+  puts JSON.pretty_generate(summary)
+end

data/lib/fits_parser/parser.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+# Minimal FITS parser for astronomy .fit/.fits files.
+# Reads:
+# - primary/header HDUs
+# - basic keyword values
+# - BINTABLE metadata
+#
+# This is not a full FITS implementation, but it provides a practical skeleton.
+class FitsParser
+  CARD_SIZE = 80
+  BLOCK_SIZE = 2880
+
+  def initialize(path)
+    @io = File.open(path, "rb")
+  end
+
+  def self.open(path)
+    parser = new(path)
+    return parser unless block_given?
+
+    begin
+      yield parser
+    ensure
+      parser.close
+    end
+  end
+
+  def close
+    @io&.close
+  end
+
+  def parse_hdus
+    hdus = []
+
+    until @io.eof?
+      start_pos = @io.pos
+      header_cards = read_header_cards
+      break if header_cards.empty?
+
+      header = cards_to_hash(header_cards)
+      data_pos = @io.pos
+
+      data_size = hdu_data_size(header)
+      hdus << {
+        start_pos: start_pos,
+        header: header,
+        data_pos: data_pos,
+        data_size: data_size
+      }
+
+      skip_padded_data(data_size)
+      break if @io.eof?
+    end
+
+    hdus
+  end
+
+  def read_bintable(hdu)
+    columns = bintable_columns(hdu)
+    data_rows = each_bintable_row(hdu).to_a
+
+    {
+      columns: columns,
+      rows: data_rows
+    }
+  end
+
+  def bintable_columns(hdu)
+    header = hdu[:header]
+    raise "Not a BINTABLE HDU" unless header["XTENSION"] == "BINTABLE"
+
+    tfields = integer_value(header["TFIELDS"])
+    (1..tfields).map do |i|
+      {
+        index: i,
+        name: string_value(header["TTYPE#{i}"]),
+        form: string_value(header["TFORM#{i}"])
+      }
+    end
+  end
+
+  def each_bintable_row(hdu)
+    return enum_for(:each_bintable_row, hdu) unless block_given?
+
+    header = hdu[:header]
+    raise "Not a BINTABLE HDU" unless header["XTENSION"] == "BINTABLE"
+
+    rows = integer_value(header["NAXIS2"])
+    rowlen = integer_value(header["NAXIS1"])
+    columns = bintable_columns(hdu)
+
+    @io.seek(hdu[:data_pos])
+
+    rows.times do
+      row_bytes = @io.read(rowlen)
+      raise "Short BINTABLE row" if row_bytes.nil? || row_bytes.bytesize != rowlen
+
+      yield parse_bintable_row(row_bytes, columns)
+    end
+  end
+
+  private
+
+  def read_header_cards
+    cards = []
+
+    loop do
+      card = @io.read(CARD_SIZE)
+      break unless card
+      raise "Short FITS card" if card.bytesize != CARD_SIZE
+
+      cards << card
+      if card.start_with?("END")
+        pad_after_end(cards.length)
+        return cards
+      end
+    end
+
+    cards
+  end
+
+  def pad_after_end(card_count)
+    header_bytes = card_count * CARD_SIZE
+    padded = ((header_bytes + BLOCK_SIZE - 1) / BLOCK_SIZE) * BLOCK_SIZE
+    extra = padded - header_bytes
+    @io.seek(extra, IO::SEEK_CUR) if extra.positive?
+  end
+
+  def cards_to_hash(cards)
+    hash = {}
+
+    cards.each do |card|
+      key = card[0, 8].strip
+      next if key.empty? || key == "END"
+
+      if card[8] == "="
+        raw = card[10, 70]
+        value_part = raw.split("/", 2).first&.rstrip
+        hash[key] = parse_value(value_part)
+      else
+        hash[key] = true
+      end
+    end
+
+    hash
+  end
+
+  def parse_value(v)
+    return nil if v.nil?
+
+    v = v.strip
+    return nil if v.empty?
+
+    if v.start_with?("'")
+      v.sub(/^'/, "").sub(/'\s*$/, "").rstrip
+    elsif v == "T"
+      true
+    elsif v == "F"
+      false
+    elsif v.match?(/\A[+-]?\d+\z/)
+      v.to_i
+    elsif v.match?(/\A[+-]?(?:\d+\.\d*|\.\d+)(?:[EeDd][+-]?\d+)?\z/) || v.match?(/\A[+-]?\d+[EeDd][+-]?\d+\z/)
+      v.tr("Dd", "Ee").to_f
+    else
+      v
+    end
+  end
+
+  def hdu_data_size(header)
+    # IMAGE HDU
+    if header["XTENSION"].nil?
+      bitpix = integer_value(header["BITPIX"])
+      naxis = integer_value(header["NAXIS"])
+      dims = (1..naxis).map { |i| integer_value(header["NAXIS#{i}"]) }
+      return 0 if naxis.zero?
+
+      bytes_per_pixel = bitpix.abs / 8
+      dims.inject(1, :*) * bytes_per_pixel
+    else
+      case header["XTENSION"]
+      when "BINTABLE", "TABLE"
+        integer_value(header["NAXIS1"]) * integer_value(header["NAXIS2"])
+      else
+        naxis = integer_value(header["NAXIS"])
+        dims = (1..naxis).map { |i| integer_value(header["NAXIS#{i}"]) }
+        bitpix = integer_value(header["BITPIX"])
+        bytes_per_pixel = bitpix.abs / 8
+        dims.inject(1, :*) * bytes_per_pixel
+      end
+    end
+  end
+
+  def skip_padded_data(data_size)
+    padded = ((data_size + BLOCK_SIZE - 1) / BLOCK_SIZE) * BLOCK_SIZE
+    @io.seek(padded, IO::SEEK_CUR)
+  end
+
+  def integer_value(v)
+    Integer(v)
+  end
+
+  def string_value(v)
+    v.to_s
+  end
+
+  # Very minimal BINTABLE row parser.
+  # Extend this for more FITS TFORM types as needed.
+  def parse_bintable_row(row_bytes, columns)
+    offset = 0
+
+    columns.each_with_object({}) do |col, row|
+      form = col[:form]
+
+      value, consumed = parse_tform_value(row_bytes, offset, form)
+      row[col[:name]] = value
+      offset += consumed
+    end
+  end
+
+  def parse_tform_value(buf, offset, form)
+    # examples: "E", "D", "J", "K", "10A"
+    m = form.match(/\A(\d*)([A-Z])\z/)
+    raise "Unsupported TFORM: #{form}" unless m
+
+    repeat = m[1].empty? ? 1 : m[1].to_i
+    code = m[2]
+
+    case code
+    when "A"
+      bytes = buf.byteslice(offset, repeat)
+      [bytes.to_s.rstrip, repeat]
+    when "B"
+      vals = buf.byteslice(offset, repeat).bytes
+      [repeat == 1 ? vals[0] : vals, repeat]
+    when "I" # 16-bit signed big-endian
+      vals = repeat.times.map { |i| buf.byteslice(offset + i * 2, 2).unpack1("s>") }
+      [repeat == 1 ? vals[0] : vals, repeat * 2]
+    when "J" # 32-bit signed big-endian
+      vals = repeat.times.map { |i| buf.byteslice(offset + i * 4, 4).unpack1("l>") }
+      [repeat == 1 ? vals[0] : vals, repeat * 4]
+    when "K" # 64-bit signed big-endian
+      vals = repeat.times.map { |i| buf.byteslice(offset + i * 8, 8).unpack1("q>") }
+      [repeat == 1 ? vals[0] : vals, repeat * 8]
+    when "E" # 32-bit float big-endian
+      vals = repeat.times.map { |i| buf.byteslice(offset + i * 4, 4).unpack1("g") }
+      [repeat == 1 ? vals[0] : vals, repeat * 4]
+    when "D" # 64-bit float big-endian
+      vals = repeat.times.map { |i| buf.byteslice(offset + i * 8, 8).unpack1("G") }
+      [repeat == 1 ? vals[0] : vals, repeat * 8]
+    else
+      raise "Unsupported FITS TFORM code: #{code}"
+    end
+  end
+end

data/lib/fits_parser/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class FitsParser
+  VERSION = "0.1.0"
+end

data/lib/fits_parser.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "fits_parser/version"
+require_relative "fits_parser/parser"

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: fits_parser
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tim Bass
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: A lightweight Ruby parser for FITS files with header/HDU parsing and
+  basic BINTABLE support.
+email:
+- tim@unix.com
+executables:
+- fits-parser
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- bin/fits-parser
+- lib/fits_parser.rb
+- lib/fits_parser/parser.rb
+- lib/fits_parser/version.rb
+homepage: https://github.com/unixneo/fits_parser
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/unixneo/fits_parser
+  source_code_uri: https://github.com/unixneo/fits_parser
+  changelog_uri: https://github.com/unixneo/fits_parser/releases
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Minimal FITS (.fit/.fits) parser for astronomy data
+test_files: []