A Content Handler for the FITS Image Format

Example 17-9. An x-fits content handler

package com.macfaq.net.www.content.image;
import java.net.*;
import java.io.*;
import java.awt.image.*;
import java.util.*;
public class x_fits extends ContentHandler {
 public Object getContent(URLConnection uc) throws IOException {
 int width = -1;
 int height = -1;
 int bitpix = 16;
 int[] data = null;
 int naxis = 2;
 Hashtable header = null;
 DataInputStream dis = new DataInputStream(uc.getInputStream( ));
 header = readHeader(dis);
 bitpix = getIntFromHeader("BITPIX ", -1, header);
 if (bitpix <= 0) return null;
 naxis = getIntFromHeader("NAXIS ", -1, header);
 if (naxis < 1) return null;
 width = getIntFromHeader("NAXIS1 ", -1, header);
 if (width <= 0) return null;
 if (naxis == 1) height = 1;
 else height = getIntFromHeader("NAXIS2 ", -1, header);
 if (height <= 0) return null;
 if (bitpix == 16) {
 short[] theInput = new short[height * width]; for (int i = 0; i < theInput.length; i++) {
 theInput[i] = dis.readShort( );
 }
 data = scaleArray(theInput);
 }
 else if (bitpix == 32) {
 int[] theInput = new int[height * width]; for (int i = 0; i < theInput.length; i++) {
 theInput[i] = dis.readInt( );
 }
 data = scaleArray(theInput);
 }
 else if (bitpix == 64) { long[] theInput = new long[height * width]; for (int i = 0; i < theInput.length; i++) {
 theInput[i] = dis.readLong( );
 }
 data = scaleArray(theInput);
 }
 else if (bitpix == -32) { float[] theInput = new float[height * width]; for (int i = 0; i < theInput.length; i++) {
 theInput[i] = dis.readFloat( );
 }
 data = scaleArray(theInput);
 }
 else if (bitpix == -64) { double[] theInput = new double[height * width]; for (int i = 0; i < theInput.length; i++) {
 theInput[i] = dis.readDouble( );
 }
 data = scaleArray(theInput); } else {
 System.err.println("Invalid BITPIX");
 return null;
 } // end if-else-if
 return new MemoryImageSource(width, height, data, 0, width);
 } // end getContent
 private Hashtable readHeader(DataInputStream dis) throws IOException {
 int blocksize = 2880;
 int fieldsize = 80;
 String key, value;
 int linesRead = 0;
 byte[] buffer = new byte[fieldsize];
 Hashtable header = new Hashtable( );
 while (true) {
 dis.readFully(buffer);
 key = new String(buffer, 0, 8, "ASCII");
 linesRead++;
 if (key.substring(0, 3).equals("END")) break;
 if (buffer[8] != '=' || buffer[9] != ' ') continue;
 value = new String(buffer, 10, 20, "ASCII");
 header.put(key, value);
 }
 int linesLeftToRead = (blocksize - ((linesRead * fieldsize) % blocksize))/fieldsize;
 for (int i = 0; i < linesLeftToRead; i++) dis.readFully(buffer);
 return header;
 }
 private int getIntFromHeader(String name, int defaultValue, Hashtable header) {
 String s = "";
 int result = defaultValue;
 try {
 s = (String) header.get(name);
 }
 catch (NullPointerException ex) { return defaultValue;
 }
 try {
 result = Integer.parseInt(s.trim( ));
 }
 catch (NumberFormatException ex) { System.err.println(ex);
 System.err.println(s);
 return defaultValue;
 }
 return result;
 }
 private int[] scaleArray(short[] theInput) {
 int data[] = new int[theInput.length];
 int max = 0;
 int min = 0;
 for (int i = 0; i < theInput.length; i++) {
 if (theInput[i] > max) max = theInput[i];
 if (theInput[i] < min) min = theInput[i];
 }
 long r = max - min;
 double a = 255.0/r;
 double b = -a * min;
 int opaque = 255;
 for (int i = 0; i < data.length; i++) {
 int temp = (int) (theInput[i] * a + b);
 data[i] = (opaque << 24) | (temp << 16) | (temp << 8) | temp;
 }
 return data;
 } private int[] scaleArray(int[] theInput) {
 int data[] = new int[theInput.length];
 int max = 0;
 int min = 0;
 for (int i = 0; i < theInput.length; i++) {
 if (theInput[i] > max) max = theInput[i];
 if (theInput[i] < min) min = theInput[i];
 }
 long r = max - min;
 double a = 255.0/r;
 double b = -a * min;
 int opaque = 255;
 for (int i = 0; i < data.length; i++) {
 int temp = (int) (theInput[i] * a + b);
 data[i] = (opaque << 24) | (temp << 16) | (temp << 8) | temp;
 }
 return data;
 } private int[] scaleArray(long[] theInput) {
 int data[] = new int[theInput.length];
 long max = 0;
 long min = 0;
 for (int i = 0; i < theInput.length; i++) {
 if (theInput[i] > max) max = theInput[i];
 if (theInput[i] < min) min = theInput[i];
 }
 long r = max - min;
 double a = 255.0/r;
 double b = -a * min;
 int opaque = 255;
 for (int i = 0; i < data.length; i++) {
 int temp = (int) (theInput[i] * a + b);
 data[i] = (opaque << 24) | (temp << 16) | (temp << 8) | temp;
 }
 return data;
 } private int[] scaleArray(double[] theInput) {
 int data[] = new int[theInput.length];
 double max = 0;
 double min = 0;
 for (int i = 0; i < theInput.length; i++) {
 if (theInput[i] > max) max = theInput[i];
 if (theInput[i] < min) min = theInput[i];
 }
 double r = max - min;
 double a = 255.0/r;
 double b = -a * min;
 int opaque = 255;
 for (int i = 0; i < data.length; i++) {
 int temp = (int) (theInput[i] * a + b);
 data[i] = (opaque << 24) | (temp << 16) | (temp << 8) | temp;
 }
 return data;
 }
 private int[] scaleArray(float[] theInput) {
 int data[] = new int[theInput.length];
 float max = 0;
 float min = 0;
 for (int i = 0; i < theInput.length; i++) {
 if (theInput[i] > max) max = theInput[i];
 if (theInput[i] < min) min = theInput[i];
 }
 double r = max - min;
 double a = 255.0/r;
 double b = -a * min;
 int opaque = 255;
 for (int i = 0; i < data.length; i++) {
 int temp = (int) (theInput[i] * a + b);
 data[i] = (opaque << 24) | (temp << 16) | (temp << 8) | temp;
 }
 return data;
 }
}

The key method of the x_fits class is getContent( ); it is the one method that the ContentHandler class requires subclasses to implement. The other methods in this class are all utility methods that help to break up the program into easier-to-digest chunks. getContent( ) is called by a URLConnection, which passes a reference to itself in the argument uc. The getContent() method reads data from that URLConnection and uses it to construct an object that implements the ImageProducer interface. To simplify the task of creating an ImageProducer, we create an array of image data and use a MemoryImageSource object, which implements the ImageProducer interface, to convert that array into an image. getContent( ) returns this MemoryImageSource. MemoryImageSource has several constructors. The one invoked here requires us to provide the width and height of the image, an array of integer values containing the RGB data for each pixel, the offset of the start of that data in the array, and the number of pixels per line in the array:

public MemoryImageSource(int width, int height, int[] pixels, int offset, int scanlines);

The width, height, and pixel data can be read from the header of the FITS image. Since we are creating a new array to hold the pixel data, the offset is zero and the scanlines are the width of the image. Our content handler has a utility method called readHeader() that reads the image header from uc's InputStream. This method returns a Hashtable containing the keywords and their values as String objects. Comments are thrown away. readHeader( ) reads 80 bytes at a time, since that's the length of each field. The first eight bytes are transformed into the String key. If there is no key, the line is a comment and is ignored. If there is a key, then the eleventh through thirtieth bytes are stored in a String called value. The key-value pair is stored in the Hashtable. This continues until the END keyword is spotted. At this point, we break out of the loop and read as many lines as necessary to finish the block. (Recall that the header is padded with spaces to make an integral multiple of 2,880.) Finally, readHeader() returns the Hashtable header. After the header has been read into the Hashtable, the InputStream is now pointing at the first byte of data. However, before we're ready to read the data, we must extract the height, width, and bits per pixel of the primary data unit from the header. These are all integer values, so to simplify the code we use the getIntFromHeader(String name, int defaultValue, Hashtable header) method. This method takes as arguments the name of the header whose value we want (e.g., BITPIX), a default value for that header, and the Hashtable that contains the header. This method retrieves the value associated with the string name from the Hashtable and casts the result to a String object-we know this cast is safe because we put only String data into the Hashtable. This String is then converted to an int using Integer.parseInt(s.trim( )); we then return the resulting int. If an exception is thrown, getIntFromHeader( ) returns the defaultValue argument instead. In this content handler, we use an impossible flag value (-1) as the default to indicate that getIntFromHeader( ) failed. getContent( ) uses getIntFromHeader() to retrieve four crucial values from the header: NAXIS, NAXIS1, NAXIS2, and BITPIX. NAXIS is the number of dimensions in the primary data array; if it is greater than or equal to two, we read the width and height from NAXIS1 and NAXIS2. If there are more than two dimensions, we still read a single two-dimensional frame from the data. A more advanced FITS content handler might read subsequent frames and include them below the original image or display the sequence of images as an animation. If NAXIS is one, the width is read from NAXIS1 and the height is set to one. (A FITS file with NAXIS as one would typically be produced from observations that used a one-dimensional CCD.) If NAXIS is less than one, there's no image data at all, so we return null. Now we are ready to read the image data. The data can be stored in one of five formats, depending on the value of BITPIX: unsigned bytes, shorts, ints, floats, or doubles. This is where the lack of generics that can handle primitive types makes coding painful: we need to repeat the algorithm for reading data five times, once for each of the five possible data types. In each case, the data is first read from the stream into an array of the appropriate type called theInput. Then this array is passed to the scaleArray( ) method, which returns a scaled array. scaleArray( ) is an overloaded method that reads the data in theInput and copies the data into the int array theData, while scaling the data to fall from 0 to 255; there is a different version of scaleArray( ) for each of the five data types it might need to handle. Thus, no matter what format the data starts in, it becomes an int array with values from 0 to 255. This data now needs to be converted into grayscale RGB values. The standard 32-bit RGB color model allows 256 different shades of gray, ranging from pure black to pure white; 8 bits are used to represent opacity, usually called "alpha". To get a particular shade of gray, the red, green, and blue bytes of an RGB triple should all be set to the same value, and the alpha value should be 255 (fully opaque). Thinking of these as four byte values, we need colors like 255.127.127.127 (medium gray) or 255.255.255.255 (pure white). These colors are produced by the lines:

int temp = (int) (theInput[i] * a + b);
theData[i] = (opaque << 24) | (temp << 16) | (temp << 8) | temp;

Once it has converted every pixel in theInput[] into a 32-bit color value and stored the result in theData[], scaleArray( ) returns theData. The only thing left for getContent( ) to do is feed this array, along with the header values previously retrieved, into the MemoryImageSource constructor and return the result. This FITS content handler has one glaring problem. The image has to be completely loaded before the method returns. Since FITS images are quite literally astronomical in size, loading the image can take a significant amount of time. It would be better to create a new class for FITS images that implements the ImageProducer interface and into which the data can be streamed asynchronously. The ImageConsumer that eventually displays the image can use the methods of ImageProducer to determine when the height and width are available, when a new scanline has been read, when the image is completely loaded or errored out, and so on. getContent( ) would spawn a separate thread to feed the data into the ImageProducer and would return almost immediately. However, a FITS ImageProducer would not be able to take significant advantage of progressive loading because the file format doesn't unambiguously define what each data value means; before we can generate RGB pixels, we must read all of the data and find the minimum and maximum values. Example 17-10 is a simple ContentHandlerFactory that recognizes FITS images. For all types other than image/x-fits, it returns null so that the default locations will be searched for content handlers.

Example 17-10. The FITS ContentHandlerFactory

import java.net.*;
public class FitsFactory implements ContentHandlerFactory {
 public ContentHandler createContentHandler(String mimeType) {
 if (mimeType.equalsIgnoreCase("image/x-fits")) {
 return new com.macfaq.net.www.content.image.x_fits( );
 }
 return null;
 }
}

Example 17-11 is a simple program that tests this content handler by loading and displaying a FITS image from a URL. In fact, it can display any image type for which a content handler is installed. However, it does use the FitsFactory to recognize FITS images.

Example 17-11. The FITS viewer

import java.awt.*;
import javax.swing.*;
import java.awt.image.*;
import java.net.*;
import java.io.*;
public class FitsViewer extends JFrame {
 private URL url;
 private Image theImage;
 public FitsViewer(URL u) { super(u.getFile( ));
 this.url = u;
 }
 public void loadImage( ) throws IOException {
 Object content = this.url.getContent( );
 ImageProducer producer;
 try {
 producer = (ImageProducer) content;
 }
 catch (ClassCastException e) {
 throw new IOException("Unexpected type " + content.getClass( )); }
 if (producer == null) theImage = null;
 else {
 theImage = this.createImage(producer);
 int width = theImage.getWidth(this);
 int height = theImage.getHeight(this);
 if (width > 0 && height > 0) this.setSize(width, height);
 }
 }
 public void paint(Graphics g) { if (theImage != null) g.drawImage(theImage, 0, 0, this);
 }
 public static void main(String[] args) {
 URLConnection.setContentHandlerFactory(new FitsFactory( ));
 for (int i = 0; i < args.length; i++) {
 try {
 FitsViewer f = new FitsViewer(new URL(args[i]));
 f.setSize(252, 252);
 f.loadImage( );
 f.show( );
 }
 catch (MalformedURLException ex) {
 System.err.println(args[i] + " is not a URL I recognize."); }
 catch (IOException ex) {
 ex.printStackTrace( ); }
 }
 }
}

The FitsViewer program extends JFrame. The main( ) method loops through all the command-line arguments, creating a new window for each one. Then it loads the image into the window and shows it. The loadImage( ) method actually downloads the requested picture by implicitly using the content handler of Example 17-9 to convert the FITS data into a java.awt.Image object stored in the field theImage. If the width and the height of the image are available (as they will be for a FITS image using our content handler but maybe not for some other image types that load the image in a separate thread), then the window is resized to the exact size of the image. The paint( ) method simply draws this image on the screen. Most of the work is done inside the content handler. In fact, this program can actually display images of any type for which a content handler is installed and available. For instance, it works equally well for GIF and JPEG images. Screenshot-2 shows this program displaying a picture of part of solar granulation.

Screenshot-2. The FitsViewer app displaying a FITS image of solar granulation