The AstroMed FITS Reader for 3D Slicer

Table of Contents:

Introduction

Adding FITS input capability to 3D Slicer is AstroMed's main engineering effort at the moment. We have created a stand-alone FITS reader for this purpose. This program, fits2itk, bridges the gap between data formats in the astronomical and medical communities. The present version translates FITS files into NRRD data, which then can be read into Slicer. Current Slicer versions cannot handle celestial coordinates yet. Data can only be explored in a qualitative sense. However, future versions of 3D Slicer will have a built-in FITS reader that will also preserve coordinate information.

The fits2itk reader is still in an early development stage, so it has not undergone exhaustive testing. Please contact us if you encounter problems with it. Such feedback will provide us with very valuable information for the ongoing development process!

Features

Our fits2itk FITS reader is a command-line tool that converts a FITS file into a NRRD file that is readable by Slicer. The user usually needs to set some options in order to obtain an optimized output file. Input FITS files must have three dimensions, out of which the first two should encode spatial information. Data can still be processed and viewed if these dimensions are not spatial, but the data orientation in the viewing window will then deviate from the usual one, which normally puts the "on-the-sky" view on Slicer's "A" perspective. Please see the documentation section below for details on the fits2itk command line options.

In principle fits2itk also supports output data types other than NRRD; i.e., in principle it can output any file type supported by ITK. fits2itk is, however, tuned for the purposes of NRRD output. We do not officially support other forms of data output. Notwithstanding this, please contact us in case of related questions.

fits2itk is built upon the CFITSIO library and consequently supports most of CFITSIO's features.

Syntax and Typical Program Calls

fits2itk is called using the syntax

fits2itk [-ASU] [-a axes-scale] [-D debug-level] [-N null-value]
            [-r RA-scale] [-s pixel-scale] [-v velocity-scale]
            input-file output-file

To give an example,

fits2itk --typical inputfile.fits outputfile.nrrd

converts a FITS file into a NRRD file in a way that is appropriate for most FITS data. This is a shortcut for

fits2itk -A -a1000 -s1000 -r-1 inputfile.fits outputfile.nrrd

The above commands convert the RA-DEC-Velocity ordered data cube inputfile.fits that contains an intensity map into the NRRD file outfile.nrrd. The "-A" option optimizes the projection of the velocity axis (for which no obvious relation to the spatial axes exists), the "-a1000" and "-s1000" options scale all axes and voxel values, respectively, by a factor 1000 to overcome a problem in Slicer's handling of floats (this is solved in existing development versions of Slicer), and the "-r-1" flips the RA axis (solved in future Slicer versions handling celestial coordinates).

In case of "label maps" marking specific regions in a cube, or more generally in case of FITS files only containing integers, the "-s1000" option should be dropped:

fits2itk -A -a1000 -r-1 inputfile.fits outputfile.nrrd

Our fits2itk reader supports CFITSIO's "extended filename syntax". This allows you to perform very complex operations on the FITS data cube while reading the file with fits2itk. The requested operations are attached to the file name for this purpose. For example,

fits2itk -A -a1000 -s1000 -r-1 "inputfile.fits[*,*,50:130:2]" outputfile.nrrd

would only process velocity slice #50 through velocity slice #130, while also skipping every other slice. Such "slicing" operations allow efficient reduction of the data. They can be used to shrink datasets that would otherwise be too large to be handled by Slicer. The quotes around the extended filename in the above example are necessary to prevent the Unix shell from attempting to do wildcard expansion on the asterisks used by the slicing notation.

The CFITSIO extended filename syntax also allows you to read remote data over the internet by using URLs instead of local file names.

Please refer to the fits2itk documentation below for an explanation of all of fits2itk's options.

Download

fits2itk is presently available as a binary executable compiled for the following platforms. Use "tar -xvjf [filename]" to unpack the download:

Binary releases for Microsoft Windows and Solaris are presently being developed.

Source code is available for Unix/Linux/OS X from this Google Code repository. fits2itk is free software, whose source code is available under the terms of the permissive "MIT License". It currently relies, however, on libraries that are GPL'ed. As a result, fits2itk executables, as they are currently being distributed (or as you are likely to build them, should you chose to build the executables from source) acquire the requirements of these copylefts. See LICENSE.txt in the source distribution for details. For instructions on how to build fits2itk see the file "==README==.txt" in the distribution. Warning: building fits2itk from source is nontrivial.

You might also be interested in using two IDL scripts used to transform velocity data cubes from the usual Velocity-RA-DEC order into the RA-DEC-Velocity order expected by fits2itk, and back.

The IDL scripts are only supported on a best-effort base.

Documentation

fits2itk assumes that the axes are ordered RA-DEC-Velocity and have decreasing RA with increasing RA index, increasing DEC with increasing DEC index, and increasing velocity with increasing velocity index. Please use the "-r" and "-v" options of fits2itk, as well as the above IDL scripts, if this is not the case.

A short fits2itk feature explanation is provided by typing "fits2itk -h":

fits2itk Version 0.3

usage:
  fits2itk [-ASU] [-a axes-scale] [-D debug-level] [-N null-value]
    [-r RA-scale] [-s pixel-scale] [-v velocity-scale]
    input-file output-file

  A: auto-scale velocity axis
  S: coerce pixel values to shorts
  U: coerce pixel values to unsigned shorts

"-a" scales all the axes, while "-v" scales only the velocity
axis.  If both are used, then both scaling factors will be applied.

fits2itk supports CFITSIO's "extended filename syntax".

Use the "--help" option to get a longer usage message.

Typing "fits2itk --help" provides a more detailed description of the options.

fits2itk Version 0.3

usage:
  fits2itk [-ASU] [-a axes-scale] [-D debug-level] [-N null-value]
    [-r RA-scale] [-s pixel-scale] [-v velocity-scale]
    input-file output-file

  A: auto-scale velocity axis
  S: coerce pixel values to shorts
  U: coerce pixel values to unsigned shorts

"-a" scales all the axes, while "-v" scales only the velocity
axis.  If both are used, then both scaling factors will be applied.

fits2itk supports CFITSIO's "extended filename syntax".

Use the "-h" option to get a terser usage message than this one.

Typical Usage
-------------
The typical usage of fits2itk for converting FITS files into "nrrd" files
for use with 3D Slicer is as follows:

   $ fits2itk -A -a 1000 -r -1 -s 1000 inputfile.fits outputfile.nrrd

The above command auto-scales the velocity axis, and then scales all of the
axes by 1000.  The right ascension axis is then flipped in order to present
it in the orientation to which astronomers are accustomed.  The pixel
values of the image are then all multiplied by 1000.

To save you a bit of typing, this can be abbreviated as

   $ fits2itk --typical inputfile.fits outputfile.nrrd


Auto Scaling
------------

The "-A" (velocity auto-scale) option works by fitting the velocity axis
into a cube that is defined by the larger of the two positional axes.  If
this option is specified in conjunction with other scaling options (such as
-v, for instance), then -A is applied first.  The other scaling option are
then also applied, multiplicatively.


Dealing with NaN's
------------------

"NaN" means "not a number".  This is a special floating point value
that represents undefined values.  FITS images often use NaN's to represent
undefined pixels, but unfortunately not all software can handle NaN's,
including some versions of 3D Slicer.  If you have images that contain
NaN's and want to use them with software that doesn't understand NaN's, you
can tell fits2itk to change all of the NaN's to a floating point value of
your choice using the "-N" option.  (Note: The value you specify is not
allowed to be 0, but it can be 0.000001, or somesuch.)

In addition to supporting undefined floating point values, FITS also has a
notion of an undefined value for a FITS image with integral pixel values.
Unlike for floating point values, however, there is no special integer
value that represents an undefined values.  Consequently, FITS allows the
creator of a FITS image to specify whatever integer he or she would like to
represent undefined pixels.  If, as it so happens, that you don't like the
specific integer chosen by the creator of a FITS image for representing
undefined pixels, you can remap the undefined value to a different integer
using the -N option of fits2itk.


CFITSIO Extended Filename Syntax
--------------------------------

fits2itk supports CFITSIO's "extended filename syntax", which allows all
sorts of interesting things.  For example, if you have a data cube with an
extra 1-pixel-thick fourth dimension, you can slice off the extra dimension
like so:

   $ fits2itk "input.fits[*,*,*,1:1][col #NAXIS=3]" output.nrrd

You can also specify a URL, rather than a filename, for the input file and
the input file will be automatically fetched via HTTP.  For the complete
manual on the extended filename syntax, see the CFITSIO User's Reference
Guide chapter on it here:

   http://heasarc.nasa.gov/docs/software/fitsio/c/c_user/node79.html


Debugging Output
----------------

Various bits of information that are useful to the developer of fits2itk,
but which probably aren't of much interest to you, can be output to stderr
during a file conversion by specifying "-D1" on the fits2itk command
line.


This Help Text
--------------

If this help text scrolled by too quickly for you to read, you might try
piping it through "more", like so:

   $ fits2itk --help | more

If you would like a terser help message than this one, use the "-h"
option instead of "--help"

FITS-reader (last edited 2011-02-18 17:29:42 by borkin)