Project

fits_parser

0.0
The project is in a healthy, maintained state
fits_parserunixneo/fits_parserHomepageDocumentationSource CodeBug TrackerWiki
A lightweight Ruby parser for FITS files with header/HDU parsing and basic BINTABLE support.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
246
Stars
2
Forks
0
Watchers
0
 Releases
Current version
0.1.0
Total releases
1
First release
2026-04-01
Latest release
2026-04-01
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2026-04-01
Reverse Dependencies
1

 Dependencies

Development

minitest
~> 5.0
rake
~> 13.0
 Project Readme

fits_parser

A minimal Ruby gem to parse astronomy FITS files (.fit / .fits).

DOI

Citation

If you use fits_parser in research or publications, cite:

Bass, T. (2026). fits_parser (v0.1.0) [Software]. Zenodo. https://doi.org/10.5281/zenodo.19363404

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

gem build fits_parser.gemspec
gem install ./fits_parser-0.1.0.gem

Usage

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:

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.

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

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

bin/fits-parser /path/to/file.fit

Prints a JSON summary of HDUs.

Testing

Run tests:

rake test

Alternative direct test command:

ruby -Ilib:test test/fits_parser_test.rb

Quick syntax checks:

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.