brampf / fitscore

A native Swift library to read and write FITS files

A native Swift library to read and write FITS files

Description

FITSCore is a pure Swift library to read, manipulate and write files conforming to the FITS 4.0 file format, commonly used to store astronomical data.

The aim is to implement a modern, native Swift library to utilize the full computing power of modern apple hardware. In particuary, I was seeking for a simple solution to read, render & review FITS files on an iPad.

FITSCore is the plattform independend base library. It compiles and runs on iOS / iPadOS / macCatalys as well as on Linux. Therefore the featureset is quite limited as the standard libraries on linux currently do not provide a lot of convenience for image generation. A deeper integration into the iOS enviornment and standard libaries is provided via the FITSKit library.

FITSCore	FITSKit	FITSTool
Fits file format read & write	Image rendering & manipulation	Command line tool
macOS, iOS & Linux	iOS / macCatalyst	Linux

Features

• Read & Write FITS 4.0 files
  • Reading files
  • Write Files
• FITS Extensions
  • Image Extensions
  • ASCII Table Extensions
  • Binary Table
• Native code
  • Swift 5.3
  • Compiles for macCatalyst
  • Compiles for iPadOS
  • Compiles for Linux

Getting started

Package Manager

With the swift package manager, add the library to your dependencies

dependencies: [
.package(url: "https://github.com/brampf/fitscore.git", from: "0.1.0")
]

then simply add the FITS import to your target

.target(name: "YourApp", dependencies: ["FITS"])

Documentation

• Introduction
• Working with Files
• Working with HDUs
• Working with Tables

TL;DR

Reading FITS Files

import FITS

/// Parste a FITS File
let fits = FitsFile.read(from: URL("/path/to/some/fits/file"))

Working with vector data

import FITS

// Fetch the whole image data
let image : Data = fits.prime.data(naxis: 1, dimension: 0)

// Fetch the read channel from the primary HDU
let red : Data = fits.prime.data(naxis: 3, dimension: 0)

Tests

There are various test cases implemented to verify compability with a variiety of real word examples of FITS files

License

MIT license; see LICENSE. (c) 2020

fitscore's Issues

Getting values from a BINTABLE

I'm gettting compile time errors at the starred lines using FITSKit to see a BINTABLE:

     if let tableHDU = hdus[i] as? AnyTableHDU<BFIELD> {
                            for i in 0..<tableHDU.tfields! {
                                print("\(i) - \(tableHDU.columns[i].TTYPE!)")
                                print("\(i) - \(tableHDU.columns[i].TUNIT!)")
                                print("\(i) - \(tableHDU.columns[i].TFORM!)")
                            }
                            print(tableHDU.columns[1][2])        ***
                            print(tableHDU.rows[1][2])              ***
                            tableHDU.rows.forEach { row in
                                var  out = ""
                                    for col in 0..<row.values.count{
                                        let field:BFIELD = row.values[1] 
                                        out.append(col.format(row.TDISP(col)) ?? "N/A")).        ***
                                    }
                                    print(out)
                            }
                        }

Any idea what's going on? Thanks for any info ...

• Tod

Update Swift (Async / Await syntax)

File writer could be updated to use the async / await syntax introduced with Swift 5.5

Header validation error

Hi,
I'm using the library to validate an existing fits file, but I get an error message that I don't understand:
"Data contains 9 bytes but supposed to be 24385536 bytes"

I don't understand the validation code that triggers this error. In AnyHDU.swift:
if modified == false && headerUnit.count < headerUnit.dataSize {

It looks like it is comparing two different things, the number of items in the header and the number of bytes in the data ?

Have I missed something ?

Documentation update needed

Since with all the syntactic sugar and especially with the changes made with the new parser, the documentation needs an update. Especially on

• Reading whole files
• Reading / writing header keywords

Bzero getter returns nil when value is stored as Int

This is painful:
When stored as Integer, the bzero & bscale properties on AnyHDU return nil instead of the value since the @Keyworld property wrapper only returns Float values

Proper value implementation for BINTABLES

The BINTABLE implementation is still lacking proper formatting of values according to the TDISP keyword. This should be addressed.

Package manager import not working

Hi,

First off thanks for this great module, it will really help me take a lot of server code out and put it into my app's client side functionality.

I've just finished a Swift wrapper for the MAST API https://github.com/triple7/SwiftMAST

I am at the point of testing product downloads and file manipulation using FITSCore.

Just followed the instructions but I get the 2 errors below:
SwiftMAST, 3 issues
dependency 'fitscore' is not used by any target
product 'FITS' required by package 'swiftmast' target 'SwiftMAST' not found.
FITS, Error
No such module 'FITS'

The relevant portions are:

            targets: ["SwiftMAST"]),
    ],
    dependencies: [
        .package(url: "https://github.com/brampf/fitscore", .upToNextMajor(from: "0.3.0")),    ],
    targets: [
        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
        // Targets can depend on other targets in this package, and on products in packages this package depends on.
        .target(
            name: "SwiftMAST",
            dependencies: ["FITS"]),

Hopefully I can get an answer as I'm working starting Tuesday and would like to have this package completed before then haha

Happy new year :)

FITSByte_* normalization returns wrong values

The method should use bigEndian, perhaps also the property float!

This returns a very high value for a linear FITS image:
public func normalize(_ bzero: Float = 0, _ bscale: Float = 1, _ min: FITSByte_16 = .min, _ max: FITSByte_16 = .max) -> Float {
return (bzero + Float(self) * bscale) / Self.range
}

This would return the correct value:
public func normalize(_ bzero: Float = 0, _ bscale: Float = 1, _ min: FITSByte_16 = .min, _ max: FITSByte_16 = .max) -> Float {
return (bzero + Float(self.bigEndian) * bscale) / Self.range
}

Improve implementation for random groups

"Random-groups structures" are currently not fully implemented but skipped over instead. To fully complete the implementation of the 4.0 Standard, PrimaryHDU should be extended by some high-level code to handle those structures

Incorrect Endianness when writing files

Writing files does encode values littleEndian (or whatever) instead of explicitly bigEndian

Improve validation Code

The validation routines are currently very limited and do not cover many cases. It should be a piece of cake to implement most if not all of the rule for FITSverify(https://heasarc.gsfc.nasa.gov/docs/software/ftools/fitsverify/):

SEVERE ERROR CONDITIONS

• Mandatory keyword not present or out of order
• Mandatory keyword has wrong datatype or illegal value
• END header keyword is not present
• Sum of table column widths is inconsistent with NAXIS1 value
• BLANK keyword present in image with floating-point datatype
• TNULLn keyword present for floating-point binary table column
• Bit column has non-zero fill bits or is not left adjusted(*)
• ASCII TABLE column contains illegal value inconsistent with TFORMn(*)
• Address to a variable length array not within the data heap(*)
• Extraneous bytes in the FITS file following the last HDU

ERROR CONDITIONS

• Mandatory keyword values not expressed in fixed format
• Mandatory keyword duplicated elsewhere in the header
• Header contains illegal ASCII character (not ASCII 32 - 126)
• Keyword name contains illegal character
• Keyword value field has illegal format
• Value and comment fields not separated by a slash character
• END keyword not filled with blanks in columns 9 - 80
• Reserved keyword with wrong datatype or illegal value
• XTENSION keyword in the primary array
• Column related keyword (TFIELDS, TTYPEn,TFORMn, etc.) in an image
• SIMPLE, EXTEND, or BLOCKED keyword in any extension
• BSCALE, BZERO, BUNIT, BLANK, DATAMAX, DATAMIN keywords in a table
• Table WCS keywords (TCTYPn, TCRPXn, TCRVLn, etc.) in an image
• TDIMn or THEAP keyword in an ASCII table
• TBCOLn keyword in a Binary table
• THEAP keyword in a binary table that has PCOUNT = 0
• XTENSION, TFORMn, TDISPn or TDIMn value contains leading space(s)
• WCSAXES keyword appears after other WCS keywords
• Index of any WCS keyword (CRPIXn, CRVALn, etc.) greater than value of WCSAXES
• Index of any table column descriptor keyword (TTYPEn, TFORMn, etc.) greater than value of TFIELDS
• TSCALn or TZEROn present for an ASCII, logical, or Bit column
• TDISPn value is inconsistent with the column datatype
• Length of a variable length array greater than the maximum length as given by the TFORMn keyword
• ASCII table floating-point column value does not have decimal point(*)
• ASCII table numeric column value has embedded space character
• Logical column contains illegal value not equal to 'T', 'F', or 0(*)
• Character string column contains non-ASCII text character(*)
• Header fill bytes not all blanks (**)
• Data fill bytes not all blanks in ASCII tables or all zeros in any other type of HDU (**)
• Gaps between defined ASCII table columns contain characters with ASCII value > 127 (**)

WARNING CONDITIONS

• SIMPLE = F
• Presence of deprecated keywords BLOCKED or EPOCH
• 2 HDUs have identical EXTNAME and EXTVER values
• BSCALE or TSCALn value = 0.
• BLANK OR TNULLn value exceeds the legal range
• TFORMn has 'rAw' format and r is not a multiple of w
• DATE = 'dd/mm/yy' and yy is less than 10 (Y2K problem??)
• Index of any WCS keyword (CRPIXn, CRVALn, etc.) greater than value of NAXIS, if the WCSAXES keyword is not present
• Duplicated keyword (except COMMENT, HISTORY, blank, etc.)
• Column name (TTYPEn) does not exist or contains characters other than letter, digit and underscore
• Binary table has PCOUNT > 0, but no variable-length array columns
• Calculated checksum inconsistent with CHECKSUM or DATASUM keyword(***)
• The HEASARC long string keyword convention is used without the recommended LONGSTRN keyword (****)

(*) only checked when "testdata" is 'Yes'
(**) only checked when "testdata" and "testfill" are 'Yes'
(***) only checked when "testdata" and "tchksum" are 'Yes'
(****) only checked when the "heasarc" is 'Yes'

Every HDU in the FITS file is checked in turn until the end of file is detected.

Implement CHECKSUM

Implementation of the CHECKSUM keyword according to the standard Appendix J