A common requirement when displaying image data is to plot an associated coordinate grid over the displayed image (e.g. the following Figure):
The use of AST in such circumstances is independent of the underlying graphics system, so starting up the graphics system, setting up a coordinate system, displaying the image, and closing down afterwards can all be done using the graphics functions you would normally use.However, displaying an image at a precise location can be a little fiddly with some graphics systems, and obviously the grid drawn by AST will not be accurately registered with the image unless this is done correctly. In the following template, we therefore illustrate both steps, basing the image display on the C interface to the PGPLOT graphics package.7Plotting a coordinate grid with AST then becomes a relatively minor part of what is almost a complete graphics program.
Once again, we assume that a pointer, ``wcsinfo'', to a suitable FrameSetFrameSet associated with the image has already been obtained (3.4).
#include "cpgplot.h" AstPlot *plot; const float *data; float hi, lo, scale, x1, x2, xleft, xright, xscale; float y1, y2, ybottom, yscale, ytop; int nx, ny; ... /* Access the image data, which we assume has dimension sizes "nx" and "ny", and will be accessed via the "data" pointer. Also derive limits for scaling it, which we assign to the variables "hi" and "lo". */ <this stage depends on your data system, so is not shown> /* Open PGPLOT using the device given by environment variable PGPLOT_DEV and check for success. */ if( cpgbeg( 0, " ", 1, 1 ) == 1 ) { /* Clear the screen and ensure equal scales on both axes. */ cpgpage(); cpgwnad( 0.0f, 1.0f, 0.0f, 1.0f ); /* Obtain the extent of the plotting area (not strictly necessary for PGPLOT, but possibly for other graphics systems). From this, derive the display scale in graphics units per pixel so that the image will fit within the display area. */ cpgqwin( &x1, &x2, &y1, &y2 ); xscale = ( x2 - x1 ) / nx; yscale = ( y2 - y1 ) / ny; scale = ( xscale < yscale ) ? xscale : yscale; /* Calculate the extent of the area in graphics units that the image will occupy, so as to centre it within the display area. */ xleft = 0.5f * ( x1 + x2 - nx * scale ); xright = 0.5f * ( x1 + x2 + nx * scale ); ybottom = 0.5f * ( y1 + y2 - ny * scale ); ytop = 0.5f * ( y1 + y2 + ny * scale ); /* Set up a PGPLOT coordinate transformation matrix and display the image data as a grey scale map (these details are specific to PGPLOT). */ { float tr[] = { xleft - 0.5f * scale, scale, 0.0f, ybottom - 0.5f * scale, 0.0f, scale }; cpggray( data, nx, ny, 1, nx, 1, ny, hi, lo, tr ); } /* BEGINNING OF AST BIT */ /* ==================== */ /* Store the locations of the bottom left and top right corners of the region used to display the image, in graphics coordinates. */ { float gbox[] = { xleft, ybottom, xright, ytop }; /* Similarly, store the locations of the image's bottom left and top right corners, in pixel coordinates -- with the first pixel centred at (1,1). */ double pbox[] = { 0.5, 0.5, nx + 0.5, ny + 0.5 }; /* Create a Plot, based on the FrameSet associated with the image. This attaches the Plot to the graphics surface so that it matches the displayed image. Specify that a complete set of grid lines should be drawn (rather than just coordinate axes). */ plot = astPlot( wcsinfo, gbox, pbox, "Grid=1" ); } /* Optionally, we can now set other Plot attributes to control the appearance of the grid. The values assigned here use the colour/font indices defined by the underlying graphics system. */ astSet( plot, "Colour(grid)=2, Font(textlab)=3" ); /* Use the Plot to draw the coordinate grid. */ astGrid( plot ); <maybe some more AST graphics here> /* Annul the Plot when finished (or use the astBegin/astEnd technique shown earlier). */ plot = astAnnul( plot ); /* END OF AST BIT */ /* ============== */ /* Close down the graphics system. */ cpgend(); }
Note that once you have set up a PlotPlot which is aligned with a displayed image, you may also use it to generate further graphical output of your own, specified in the image's world coordinate system (such as markers to represent astronomical objects, annotation, etc.). There is also a range of Plot attributes which gives control over most aspects of the output's appearance. For details of the facilities available, see 21 and the description of the Plot class in D.
For details of how to build a graphics program which uses PGPLOT, see 3.3 and the description of the ast_linkast_link command in E.