5 USING THE NDF LIBRARY TO DO MORE

 5.1 Using regions and slices of images
 5.2 Accessing foreign data formats
 5.3 Using the NDF library directly

IMG is really just a simplified interface to the NDF library (SUN/33), so all the facilities of the NDF format and library can be used along with IMG (and HDR) routines, if required. The following outlines some of the more important facilities this provides.

5.1 Using regions and slices of images

The NDF library allows you to specify that a rectangular region or slice of an image should be used, rather than the whole. You identify the part you want by appending a comma separated list of ranges, in parentheses, to the name of the image. For instance if you wanted to access a square region of an image, you might use (the program running here is the mean example from §2.1):

  % mean
  IN - Input image > image(100:200,100:200)

and the square that covers the region from 100 to 200 pixels in both dimensions will be used. The rest of the image is ignored. Another way that you could get a similar effect would be to use:
     % mean
     IN - Input image > image(155~100,375~100)

which selects a square of side 100 centred on 155,375.

Missing out a “range” results in the whole of that dimension being used:

     % mean
     IN - Input image > image(,100:200)

This uses a rectangle that extends from 100 to 200 in the second dimension and that spans the whole of the first dimension.

If you had a data cube and you wanted to process a plane from it, you might use:

     IN - Input image > cube(,,10)

This would use the 2-D image stored in the tenth plane of the cube.

If the region of the image that you specify doesn’t exist, then the program will still be supplied with an image array of the requested size, but the “non-existent” parts will be set to the bad value (see §4.1.6). A complete description of how to use image “sections” (as they are called by the NDF library) is given in SUN/33.

5.2 Accessing foreign data formats

IMG can be used to access data in formats other than NDF by using the NDF library’s ‘on-the-fly’ data conversion capabilities. If you have the CONVERT package (SUN/55) available on your system, you can use it to give your IMG programs access to several important additional astronomical data formats (including IRAF, disk FITS and FIGARO). All you need to do is issue the package startup command:

  % convert

before running your IMG program. It will then be able to access these other formats in the same way as its “native” NDF format.

If you have copies of the same image in more than one format, you may need to add the appropriate file type extension – .imh, .fit and .dst for the IRAF, FITS and FIGARO formats respectively – as part of the image name, in order to distinguish them. So a typical session in which an IRAF data frame is read might be (the program is the mean example from §2.1):

  % convert
  % mean
  IN - Input image > myimage.imh
  Mean = 108.3154
  %

One point of particular relevance to IMG is the transfer of header information between the different data formats. Unless you take special action, only FITS headers will generally be transferred. So, unless you intend to make sole use of the NDF format, having sources of header information other than FITS may cause problems and is probably best avoided for the sake of simplicity.

If you want to process data in formats other than those provided by CONVERT, then you can define your own conversions. You should consult SSN/20 about how to do this.

5.3 Using the NDF library directly

When all else fails, the full power of the NDF library (SUN/33) can be made available using the call:

        CALL IMG_INDF( ’IN’, ID, ISTAT )

This returns an NDF identifier (ID) to your image dataset (this shouldn’t be confused with the pointers to images which we have used so far). This allows you to get at the other components of the NDF (our “images” are really the main NDF data array) such as its variance, quality or world coordinate system. It also allows you to access NDF extensions (our “sources” of header information) in more sophisticated ways. As a very simple example the next program snippet shows how to write out the name of an image dataset (also see IMG_NAME):
        CALL IMG_INDF( ’IN’, ID, ISTAT )                        [1]
        CALL NDF_MSG( ’NAME’, ID )                              [2]
        CALL MSG_OUT( ’ ’, ’Name of image = ^NAME’, ISTAT )     [3]
        CALL NDF_ANNUL( ID, ISTAT )                             [4]

The following notes refer to the numbered statements:
(1)
IMG_INDF returns an NDF identifier ID.
(2)
The NDF subroutine NDF_MSG sets a message token ’NAME’ (see SUN/104).
(3)
The name is written out.
(4)
The NDF identifier is annulled. It is important that you remember to do this once the identifier has been finished with.