FitsModel 1.8.8

• Overview
• Fits Model
  • Fits File
  • Fits HDU
  • Fits Header
  • Fits Header Entry
  • Fits Data
  • Fits Data Block
  • BitPix
  • Fits Header Constants
  • Fits Data Stats
  • WCS
• Fits Stream
  • Fits Data Block Stream
  • Fits Stream Writer
    • Fits File Writer
    • Fits HDU Writer
    • Fits Header Writer
    • Fits Data Writer
    • Fits Value Writer
  • Fits Stream Reader
    • Fits Value Reader
      • Fits Stats Reader
      • Fits Value Normalizer
      • Fits Value Count Reader
• Usage
  • Create FITS File
    • Create Image Helper Method
    • From Scratch
  • FITS File Creation And Streaming

Overview

A FITS File is the standard data format used in astronomy. At a high level, a FITS file contains one or more Header Data Units (HDU). Each HDU contains metadata in the header and an optional data field. You can find more detailed information on FITS files at The FITS Support Office

The FitsModel project provides an object-oriented way to create, represent, and process FITS files and the data they contain. This project is intended to comply with version 4.0 of the FITS Standard.

FitsModel can be found at nuget.org/packages/FitsModel. This readme is published here and there is publicly available API Documentation.

FitsModel is divided into 2 major sections:

• Model
  • Contains representations for a FITS file and its various sub-components.
  • An attempt is made to ensure each component complies with the FITS standard at runtime.
• Stream
  • Various classes are provided to process FITS file data from a stream.
  • Provides optimizations to reduce load on FITS file providers such as the Barbara A. Mikulski Archive for Space Telescopes.

Fits Model

The FitsModel classes provide base functionality to represent various parts of a FITS file. An attempt is made to validate each element in accordance with the official FITS standards but it is an ongoing effort. Each element also provides methods to write its contents to a stream.

Fits File

A FitsFile is just a list of FitsHdus. Contains methods to validate that the first HDU is a 'primary' HDU and that all HDUs are valid according to the FITS standard. A FITS file should contain at least 1 'Primary HDU' and 0 or more 'Extensions'. See section 3 of the FITS Standard for more detail on FITS file organizations.

Fits HDU

Contains a single FitsHeader and its FitsData (which can be empty). See section 3.2 of the FITS Standard for more information on individual FITS structures.

Fits Header

A FITS header is metadata that generally describes a set of data. A header is a collection of header entries that generally describes a set of data. Each header is an 80 byte ascii string that can be a key/value pair or a raw string. See section 4 of the FITS Standard for more details.

Fits Header Entry

An 80 byte ascii string that can be a key/value pair or a raw string. See section 4 of the FITS Standard for more details.

Fits Data

Represents and entire data set for an associated FitsHeader. These are made of zero or more FitsDataBlocks. See section 5 of the FITS Standard for more details on how data is represented within a FITS file.

Fits Data Block

A single 2880 byte block of raw data for a FITS file. All data in a FITS file, whether it be a header or data set, is made up of these blocks. Note: A FitsDataBlock can be used to represent data from a header OR its data section.

BitPix

The raw data provided in a FITS file can be 1 of 6 different data types. The BitPix class is an enumeration of these types and corresponds to the following C# data types.

Fits Header Constants

The FitsHeaderConstants class contains various constants that are used to define and process FITS files. For instance, all FitsDAtaBlocks contain FitsHeaderConstants.BlockSize (2880) bytes. Each FitsHeaderEntry contains FitsHeaderConstants.RecordSize (80) bytes.

Fits Data Stats

The FitsDataStats class holds basic info about statistics. It does not contain any methods to calculate statistics.

WCS

Representations of the mapping between image coordinates and physical (i.e., world) coordinate systems (WCSs) may be represented within FITS HDUs.

Rather than store world coordinates separately for each datum, the regular lattice structure of a FITS image offers the possibility of defining rules for computing world coordinates at each point.

See chapter 8 of the FITS Standard for more detailed information on WCS.

Fits Stream

The FitsStream classes provide a way to construct FITS files (or its constituent components) from a stream. This is handled by processing incoming stream data into discrete FitsHeaderBlocks and forwarding those to any registered "Data Block Writers". Some data block writers also contain methods to perform callbacks once an HDU, header, HDU data, or individual values have been read.

The major components for the streaming classes are:

• FitsDataBlockStream - Converts conventional byte streams into discrete FitsDataBlock
• Writers handle the 'writing' of FitsDataBlocks and converting them to a particular component of a FITS file.
• Readers are called when a complete sub-component has been read from the block stream. This is one place that you can apply any custom processing such as producing images from the data.

Fits Data Block Stream

The FitsDataBlockStream transforms written data to FitsDataBlocks. After a complete data block is formed, it is written to any registered FitsDataWriters

Fits Stream Writer

FitsDataBlocks are written to stream writers and convert them to various sub-components of a FITS file. Many writers include methods to add Fits Stream Readers that will be called when a particular sub-component has been read from the block stream. For instance, the FitsFileWriter provides callbacks whenever a full header has been read. This can allow you to define custom processing of data at runtime.

Fits File Writer

The FitsFileWriter class is used to handle reading complete FITS files from a data block stream. The file writer also contains header and HDU callbacks that are called whenever a complete header or HDU has been read.

To read a FITS file from a stream, the basic flow is as follows:

1. Create a FitsFileWriter.
   • This will read whole FitsDataBlocks as they are processed from the stream.
2. Create a FitsDataBlockStream using the FitsFileWriter in the constructor.
   • The data block stream will be used to process data from the raw stream and send it to the file writer.
3. Write data to the FitsDataBlockStream.
   • This can be from any source such as a file stream or a network stream.
   • FitsModel classes also contain WriteToStream methods that can be used to write data to the FitsDataBlockStream.
4. Once the stream is finished writing, you should have a reference to the parsed file on the FitsFileWriter that was provided.

Fits HDU Writer

An HDU writer manages the writing of a header followed by it's associated data if there is any. The HDU writer contains callbacks that can be used to process a header or data block as soon as it is read.

Fits Header Writer

Reads FitsDataBlocks until a complete FitsHeader has been read. Once a header is read, a callback is performed to all registered Fits Header Readers.

Fits Data Writer

Reads raw data bytes from the data section associated with an HDU. Data is read until the number of bytes specified the HDU's header has been written. Once complete, all registered FitsDataReaders are updated.

Fits Value Writer

Value writers parse raw data from a FitsDataBlock, converts it to individual values based on the data's BitPix (data type). Values are written to any provided readers as they are parsed. For convenience, the value writer contains 2 built in value readers that can be optionally used.

• Calculate Stats: If configured, a running count of statistics will be calculated as values are written.
• Accumulate Values: If configured, all values will be stored in a list for future reference.

Since value writers are converting byte arrays into a specific data type (based on the header BitPix setting), you need to know what type of value writer to create to handle your data.

Fits Stream Reader

Various interfaces are provided to handle various FITS file sub-components as they are read from a data block stream. These interfaces are where you can build any custom processing required while reading a FITS file stream. You can see these readers in action within many of the writers that implement these interfaces.

• Fits HDU Reader
• Fits Header Reader
• Fits Data Reader
• Fits Value Reader

Fits Value Reader

Value readers handle converting raw FITS data to typed values taking into account the "endianness" of the runtime environment. A few readers provided by default are described below.

Fits Stats Reader

Calculates running statistics for values as they are read from the data block stream.

Fits Value Normalizer

Creates a byte array of linearly normalized data. Values are normalized based on a provided min / max value. This effectively creates a monochrome image of the data.

Fits Value Count Reader

Very basic reader that counts the number of values read. Mainly this just serves as an example or template for a value reader.

Usage

Below are some concrete examples on how to use FitsModel.

Create FITS File

A FitsFile objects can be created programmatically or read from a stream.

Create Image Helper Method

You can use the FitsFile.CreateImageFile method to create a base FITS file with a primary HDU and an empty image HDU that you can then modify and add data to as needed. See FitsFileTest.CreateImageHeaderTest for full example.

var bitPix = BitPix.UnsignedChar;
var width = 2;
var height = 3;
var file = FitsFile.CreateImageFile(bitPix, width, height);

From Scratch

The below example shows how to create a basic FITS file from scratch. The file contains a default Primary HDU and a simple 10x10 pixel image for its data.

// Create a new FitsFile with a default primary HDU.
var file = new FitsFile();

// Create a new image header for a 10x10 image.
var imageHeader = FitsHeader.CreateImageHeader(FitsHeader.CreateImageHeader(BitPix.UnsignedChar, 10, 10));

// Create data for the HDU (see later examples to properly format data)
var imageData = new FitsData(new byte[10 * 10]);

// Create image HDU with the header and data units.
var imageHdu = new FitsHdu(imageHeader, imageData);

// Add image HDU to the file
file.Add(imageHdu);

FITS File Creation And Streaming

We will then create a copy of the FITS file from a FitsDataBlockStream by using the file created above. The FitsFileWriter continuously parses FitsDataBlocks from the FitsDataBlockStream and builds a collection of FitsHdus.

// Create FitsFileWriter
var fileWriter = new FitsFileWriter();

// Create data block stream
await using var blockStream = new FitsDataBlockStream(fileWriter);

// Follow the Create FITS File
// Write base file contents to the block stream
await file.WriteToStream(blockStream);

// Inspect the parsed file
var parsedFile = fileWriter.File;
Console.WriteLine(parsedFile);