fits2js

Read and write FITS files with JavaScript. This library aims to support standard FITS 4.0 files (see NASA's website or this copy). Works anywhere.

To-do

[!CAUTION] This library is under heavy development -- proceed with caution.

• Reader
  • [x] FITS with just one HDU
  • [ ] Extensions (see https://fits.gsfc.nasa.gov/xtension.html)
  • [ ] Random-groups structure
  • [ ] More testing
• Writer
  • Somewhat implemented

Usage

npm install fits2js

Read FITS

The reader surface parses single-HDU FITS files from an ArrayBuffer and exposes both header cards and numeric data in a simple API:

• FITS.fromBuffer(...) parses a FITS file buffer.
• fits.header.getValue(...), getValues(...), getComment(...), and getComments(...) read header metadata.
• fits.data.getPoint(...) reads a single pixel/sample by 1-based coordinates.
• fits.data.getData() iterates the full HDU data with coordinates and values.

import { FITS } from "fits2js"

const response = await fetch("/images/m51.fits")
const buffer = await response.arrayBuffer()
const fits = FITS.fromBuffer(buffer, null)

console.log(fits.header.getValue("OBJECT"))
console.log(fits.header.getValue("BITPIX"))
console.log(fits.header.getValue("NAXIS1"), fits.header.getValue("NAXIS2"))
console.log(fits.data.getPoint(1, 1))

import { FITS } from "fits2js"

const response = await fetch("/images/m51.fits")
const buffer = await response.arrayBuffer()
const fits = FITS.fromBuffer(buffer, null)

for (const { coordinates, value } of fits.data.getData()) {
  console.log(coordinates, value)
}

Write FITS

The writer surface includes convenience APIs for building single-HDU FITS products:

• FITS.fromTypedArray(...) writes directly from numeric typed arrays.
• fits.header.append(...), insertAt(...), remove(...), appendComment(...), appendHistory(...), and appendBlank(...) preserve deliberate card ordering.
• fits.header.set(...) updates a value and comment together.
• fits.header.addAxis(...) writes CTYPEn/CUNITn/CRPIXn/CRVALn/CDELTn/CROTAn helpers for calibrated axes.

import { FITS } from "fits2js"

const pixels = new Float32Array([
  0.12, 0.34,
  0.56, 0.78,
])

const fits = FITS.fromTypedArray(pixels, -32, [2, 2])
fits.header.set("OBJECT", "M51", { comment: "Target name" })
fits.header.set("BUNIT", "adu")
fits.header.appendComment("Scanned photographic plate")
fits.header.appendHistory("Generated by fits2js")
fits.header.appendBlank("Axis metadata")
fits.header.addAxis(1, {
  ctype: "WAVELENGTH",
  cunit: "Angstrom",
  crpix: 1,
  crval: 4100,
  cdelt: 0.5,
})

const buffer = fits.toBuffer()

License

MIT License © 2024-PRESENT Juan Martín Seery