next up previous 231
Next: Creating a new image
Up: ACCESSING IMAGE DATA
Previous: ACCESSING IMAGE DATA


Accessing an existing image

The first example is a complete program. It gets an existing image, works out its mean value and then writes it out:
      SUBROUTINE MEAN( ISTAT )                                [1]

*  Access an input image.
      CALL IMG_IN( 'IN', NX, NY, IP, ISTAT )                  [2]

*  Derive the mean and write it out.
      CALL DOSTAT( %VAL( IP ), NX, NY, ISTAT )                [3]

*  Free the input image.
      CALL IMG_FREE( 'IN', ISTAT )                            [4]
      END

      SUBROUTINE DOSTAT( IMAGE, NX, NY, ISTAT )
      INCLUDE 'SAE_PAR'                                       [5]
      REAL IMAGE( NX, NY )                                    [6]

      IF ( ISTAT .NE. SAI__OK ) RETURN                        [7]

*  Initialise the sum and loop over all elements of the image.
      SUM = 0.0
      DO 1 J = 1, NY
         DO 2 I = 1, NX
            SUM = SUM + IMAGE( I, J )
 2       CONTINUE
 1    CONTINUE

*  Write out the mean value.
      WRITE( *, * ) 'Mean = ', SUM / REAL( NX * NY )          [8]

      END

The following notes refer to the numbered statements:

1.
Programs that use IMG should always have a main subroutine with an INTEGER argument. This subroutine should be named after the program and be stored in a file with the same name (mean and mean.f in this case). You should consider this subroutine as a replacement for the file that normally has a PROGRAM statement in it.

2.
The call to IMG_IN gets the input image. The image is associated with the ``parameter'' 'IN' which usually means that you will be prompted for the name of an image data-file. The subroutine then returns the size of the image - NX  x  NY - and a pointer IP to its data (don't panic - hold on for the next item).

3.
A call to the subroutine DOSTAT, which performs the real work, is now made. Since any realistically useful program needs to be able to handle images of any size, a cheat is necessary - this is the %VAL(IP) argument. Basically, this makes the pointer to the image data, IP, look just like an array declaration in the calling routine (i.e. like say REAL IMAGE(NX,NY)). This isn't standard Fortran, but should work on any machine that has IMG installed. Pointers are stored in INTEGER variables.

4.
A call to IMG_FREE is made for each image parameter to tidy up before a program ends.

5.
The INCLUDE statement in the subroutine DOSTAT inserts the contents of the file `SAE_PAR'. This defines some standard Fortran parameters for you, such as SAI__OK (note the double underscore). Include this file as standard as the parameters it defines are usually necessary.

6.
The image is now available as an adjustable 2-dimensional array within the subroutine DOSTAT.

7.
The value of the ISTAT argument is tested against SAI__OK at the start of DOSTAT. This is done in case an error has occurred earlier on (in which case ISTAT will not be equal to SAI__OK, so the remainder of DOSTAT will not execute).

Doing this means that the program will not crash if an earlier error results in (say) the IMAGE array containing rubbish, and it makes sure that you get a sensible error message at the end telling you what went wrong.

8.
The calculation result is written out. In a more sophisticated program you might want to use routines from the MSG library (SUN/104) to do this.

To complete the program another file is required. This is an ``interface'' file (which should be named after the program but with a file extension of .ifl). It contains a description of each parameter associated with an image. The following will do for this example program:

interface MEAN
   parameter IN
      prompt 'Input image'
   endparameter
endinterface
The main point is that it is necessary to include a parameter ...endparameter statement for each input or output image. SUN/101 and SUN/115 describe numerous other parameter options if you need more sophisticated control.

Once you have the two files mean.f and mean.ifl you can compile and run the program by following the instructions given elsewhere.

To recap: The most important IMG concepts to remember from this example are:

1.
Images are associated with a label known as a ``parameter''.

2.
Image data is accessed by a ``pointer'' that needs to be passed to a subroutine using the %VAL mechanism.

3.
It is necessary to call IMG_FREE to free images before the program ends.



next up previous 231
Next: Creating a new image
Up: ACCESSING IMAGE DATA
Previous: ACCESSING IMAGE DATA

IMG Simple Image Data Access
Starlink User Note 160
P.W. Draper
R.F. Warren-Smith
3 March 2003
E-mail:P.W.Draper@durham.ac.uk

Copyright © 2000-2003 Council for the Central Laboratory of the Research Councils