org.jscience.io.fits
Class FitsImageData

java.lang.Object
  extended by org.jscience.io.fits.FitsData
      extended by org.jscience.io.fits.FitsImageData

public class FitsImageData
extends FitsData

*********************************************************************** Represents the data in the primary HDU of an image extension. The philosophy of this package is to represent FITS data in ways that are natural to Java. So for example, a table is represented as a Swing TableModel. Although the representation of images in Java has evolved over the years, this class follows the old ImageProducer/ImageConsumer paradigm of treating images a data streams. The problem is that that paradigm only handled integer pixel values. So I invented a similar set of interfaces: RealImageProducer and RealImageConsumer, and an ImageDigitizer class which can convert from real to integer images.

Another issue is that displayable images are two-dimensional, while FITS image can have any number of dimensions. So we need a mechanism for making two dimensional slices through the FITS data array.

So you use the following proceedure to display an image:

  1. create a RealImageProducer with createView(int,int,int[]) or createView()
  2. create an ImageDigitizer and register it as a consumer of the producer you just created.
  3. Get a graphics Toolkit by calling the getToolkit() method of an AWT Containter.
  4. Call the createImage(ImageProducer) method of the toolkit, using the digitizer as the producer.
  5. Finally, you can display the image by putting it in an ImageIcon in a JLabel, or by doing custom painting of a subclass of JPanel.

It made sense to treat images as data streams back when computers had less memory and connections to the internet had less bandwidth. However, Java has evolved to the simpler BufferedImage paradigm, where the pixel data are held in memory. So at some point I plan to modify this class to be more like a DataBuffer. It also might be nice to make an image implement the TableModel interface, to give tabular access to the pixels. ************************************************************************


Field Summary
 
Fields inherited from class org.jscience.io.fits.FitsData
data, interpreter, isComplete, PADDING, setter, valid_bytes
 
Constructor Summary
FitsImageData()
          ************************************************************************ make an empty image.
FitsImageData(FitsHeader header)
          *********************************************************************** Create an image as specified by the given HDU header
FitsImageData(int bitpix, boolean isReal, int[] dimen)
          ************************************************************************ Create an image from a set of image characteristics
 
Method Summary
 FitsHeader createHeader(java.lang.String name)
          ************************************************************************** create the minimum header needed for this image.
 RealImageProducer createView()
          *********************************************************************** create a new view of this image which is the first plane of the first two axes.
 RealImageProducer createView(int x_axis, int y_axis, int[] plane)
          *********************************************************************** create a new view of this image.
 double getNextPixel()
          *********************************************************************** returns the scaled value of the pixel currently pointed to by the reader ************************************************************************
 java.lang.Number getNextRawPixel()
          *********************************************************************** returns the unscaled value of the pixel currently pointed to by the reader ************************************************************************
 void goToPixel()
          *********************************************************************** set the internal pointer to the first pixel in the image ************************************************************************
 void goToPixel(int[] coord)
          *********************************************************************** set the internal pointer so the interpreter will read a given pixel next ************************************************************************
 double max()
          *********************************************************************** returns the maximum pixel value in the image.
 double min()
          *********************************************************************** returns the minimum pixel value in the image.
 int pixelCount()
          *********************************************************************** returns the total number of pixels in the image ************************************************************************
 void removeView(org.jscience.io.fits.FitsImageData.View view)
          *********************************************************************** remove a view from the internal registry.
 void setValidBytes(int valid_bytes)
          *********************************************************************** update the number of valid bytes.
 
Methods inherited from class org.jscience.io.fits.FitsData
available, blockCount, createFrom, data, goToByte, incrementValidBytes, isComplete
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FitsImageData

public FitsImageData(FitsHeader header)
              throws FitsException
*********************************************************************** Create an image as specified by the given HDU header

Parameters:
header - the HDU header which defined the image
Throws:
FitsException - if there is a problem with the FITS format ************************************************************************

FitsImageData

public FitsImageData(int bitpix,
                     boolean isReal,
                     int[] dimen)
              throws FitsException
************************************************************************ Create an image from a set of image characteristics

Parameters:
bitpix - the number of bits per pixel. Note this should always be positive even though FITS uses a negative BITPIX to indicate real valued pixels.
isReal - true if the pixels should have floating point values.
dimen - an array of image dimensions
Throws:
FitsException - if invalid values are given. For example only certain values of bitpix are allowed. *************************************************************************

FitsImageData

public FitsImageData()
              throws FitsException
************************************************************************ make an empty image. Useful for empty primary HDUs *************************************************************************

Throws:
FitsException
Method Detail

pixelCount

public int pixelCount()
*********************************************************************** returns the total number of pixels in the image ************************************************************************


min

public double min()
           throws FitsException
*********************************************************************** returns the minimum pixel value in the image. This is read from the DATAMIN keyword if it exists, otherwise it is calculated from the image ************************************************************************

Throws:
FitsException

max

public double max()
           throws FitsException
*********************************************************************** returns the maximum pixel value in the image. This is read from the DATAMAX keyword if it exists, otherwise it is calculated from the image ************************************************************************

Throws:
FitsException

setValidBytes

public void setValidBytes(int valid_bytes)
                   throws FitsException
*********************************************************************** update the number of valid bytes. This overrides the parent class method to also track the number of valid full pixels. This would be nice if we actually had a FitsFile class which read pixels a few at a time, but we don't. At some point this whole setValidBytes framework may get stripped out. ************************************************************************

Overrides:
setValidBytes in class FitsData
Parameters:
valid_bytes - the new number of valid bytes in the raw data array
Throws:
FitsException - never, however subclasses may do so.
See Also:
*************************************************************************

createView

public RealImageProducer createView(int x_axis,
                                    int y_axis,
                                    int[] plane)
                             throws FitsException
*********************************************************************** create a new view of this image. A view is a two dimensional slice of the FITS image data cube.

Parameters:
x_axis - the index of the horizontal axis in the slice. This index counts from zero.
y_axis - the index of the vertical axis in the slice. This index counts from zero.
plane - an array indicating the coordinates at which to slide the data cube. For instance for a three dimensional image data array, if x_axis=0 and Y_axis=1, then if plane = {0, 0, 10} then the slice will be those pixels values with the third coordinates equals to 10. In this case the first two elements of plane are ignored. ************************************************************************
Throws:
FitsException

createView

public RealImageProducer createView()
                             throws FitsException
*********************************************************************** create a new view of this image which is the first plane of the first two axes. This method is mostly for convenience with two dimensional images. ************************************************************************

Throws:
FitsException

removeView

public void removeView(org.jscience.io.fits.FitsImageData.View view)
*********************************************************************** remove a view from the internal registry. Such a view will no longer be updated when new pixels are read. We don't actually have any methods which read pixels incrementally, though. ************************************************************************


goToPixel

public void goToPixel(int[] coord)
*********************************************************************** set the internal pointer so the interpreter will read a given pixel next ************************************************************************


goToPixel

public void goToPixel()
*********************************************************************** set the internal pointer to the first pixel in the image ************************************************************************


getNextRawPixel

public java.lang.Number getNextRawPixel()
                                 throws FitsException
*********************************************************************** returns the unscaled value of the pixel currently pointed to by the reader ************************************************************************

Throws:
FitsException

getNextPixel

public double getNextPixel()
                    throws FitsException
*********************************************************************** returns the scaled value of the pixel currently pointed to by the reader ************************************************************************

Throws:
FitsException

createHeader

public FitsHeader createHeader(java.lang.String name)
************************************************************************** create the minimum header needed for this image. This is useful if you want to create an image in memory and write the result to a FITS file. Only problem is that we don't currently have a convenient way to set pixels. ***************************************************************************