### 3 What does it actually do?

The capabilities of GAIA fall roughly into three areas; those of an image and cube display tool, those provided for the analysis of images and cubes amd those for querying on-line resources (images and catalogue data held in the VO and other places). Each of these areas is described very briefly in the next sections. As with most graphical tools, probably the best way to find out about GAIA is to explore it interactively. Failing that many windows have a one-page description in the on-line help system and most graphical elements (buttons, entry fields etc.) have one-line descriptions that appear in the short-help region at the bottom of windows.

Windows that provide a limited range of controls for some kind of focussed task are called ‘toolboxes’. In general what they do should be obvious or they are really front-ends for other software packages. Good examples of this latter type are the photometry and object detection toolboxes. When such a toolbox is used the documentation for the command-line tools is the primary source for finding out what is going on under the bonnet.

#### 3.1 Image display capabilities

GAIA provides the following normal “image display tool” features:

• Display of images in FITS and Starlink NDF formats (this also means that it will display many other data formats using the on-the-fly data conversion ability of the NDF library, most notably the IRAF data format).
• Panning, zooming, data range and colour table manipulations.
• Continuous display of the cursor position and the image data value.
• Display of many images (clones), each in its own window.
• Coloured annotation, using text and line graphics (boxes, circles, polygons, lines with arrowheads, ellipses …).
• Printing of the displayed image and annotations (annotations are drawn using printer resolution, i.e. not a screen dump) to a postscript file.
• Real time pixel value table. A table displaying the data values and simple statistics of a region about the cursor can be displayed.
• Display of image planes and spectra from data cubes. Using this you can step along an axis and display the image formed by the other two axes. You can also combine a range of image planes or do the stepping using a timed animation. The displayed images created by this tool can be analysed in the image-analysis toolboxes. A spectrum from the hidden dimension of the cube can be displayed and updated interactively and even sent to the Starlink SPLAT-VO program for analysis and additional inspection. Finally the spectral coordinates can be interactively transformed between various wavelength, frequency, energy and velocity systems.
• Selection of 2D or 3D regions using an integer mask. If you have a mask that segments your image into regions based on some integer value you can view only those parts of your image that correspond to some given values. Such masks are produced by the EXTRACTOR/SExtractor and CUPID applications.
• Histograms of the pixel distribution in rectangular regions of the displayed image. This also shows parabolic and gaussian fits to the distribution (mainly for background estimation), as well as allowing the comparison of two regions.

#### 3.2 Image analysis capabilities

GAIA provides the following features, which are specifically aimed at astronomical work with images:

• Aperture & optimal photometry. A highly interactive environment for controlling the positions, sizes and orientations of circular and elliptical apertures. The sky estimates can be made from annuli of these apertures or from related sky apertures. The measurements can be in either instrumental magnitudes or mean counts (based on the PHOTOM - SUN/45 - program AUTOPHOTOM)
• Automatic source detection. This feature provides the ability to automatically detect and parameterise all the objects on an image. These objects are then identified by displaying ellipses over the image and are available for interactive inspection. The resultant measurements are displayed in a catalogue window which can be used to inspect the individual values, select data on the bases of range limits and change the appearance of the ellipses. This is based on the EXTRACTOR (SUN/226) package, a derivative of SExtractor.
• Extended surface photometry. This allows the interactive identification of extended objects (galaxies) and profile measurements using ellipse fitting. The resultant fits are shown over the images and the measurements can be inspected (based on the ESP - SUN/180 - programs ELLPRO and ELLFOU).
• Image patching. This provides the ability to select arbitrary shaped regions on an image and replace them with a surface fit to other regions, together with an artificial noise component. An ideal way to remove unwanted defects from an image for cosmetic reasons.
• Interactive ARD (SUN/183) regions. This allows the calculation of statistics, the masking out and extraction of arbitrary shaped parts of your images as well defining ARD regions for other programs to use.
• Contouring. This allows the contouring of the displayed image, or the overlay of contours derived from other images. The images are aligned using sky coordinates, if available. Control over individual line colours and thicknesses is provided.
• Polarization vector plotting and manipulation. This provides the ability to display vector maps produced by the POLPACK (SUN/223) package. It also allows you to select sub-sets of vectors, either by algebraic expressions or by rectangular regions. Selected parts can be removed or saved to new catalogues. New vector maps can be created by binning vectors and reports of the properties of selections can be displayed.
• Blink comparison. All the displayed images can be animated (as quickly as your hardware/CPU combination allow), or you can cycle through them by hand.
• Interactive position marking: Mark and label positions on your images and print or record them for future reference. This also allows positions to be read in from text files and input sky coordinates to be transformed to different celestial coordinate systems. Mean seeing and shape parameters of any marked stars are also available as part of this analysis.
• Celestial coordinates readout. If your data have suitable astrometric calibration data available (in recognised headers i.e. FITS/IRAF or NDF WCS) then a continuous readout of the current RA and Dec is provided.
• Astrometric calibration. You can either fit a new astrometric calibration to your image (using semi-automated matching between detected images and on-line catalogues or you can define your own reference positions), set one using known information (such the image scale and a reference point), copy one from another image and finally tweak one to make it fit better.
• Astrometric grid overlay. If you can read out sky coordinates then you can also plot a grid overlay with labelled axes. The grid facility is provided with an enormous range of customization options, such as being able to change the celestial coordinate system (from say FK5 to Galactic etc.).
• Celestial coordinate system control. You can change the celestial coordinate system used by your image to a new one (to/from FK5, FK4, Ecliptic, Geocentric apparent, Galactic and SuperGalactic).
• Sky coordinate offsets. This feature also relies on being able to read celestial coordinates, if so then you can determine the distance and offsets between any two points on your image (in arc minutes).
• Real time profiling. Two separate toolboxes allow you to either move a line around on the image and see the image data values displayed as a profile change (this profile can also be saved as a spectrum), or do the same with a rectangle, in which case the mean profiles along the X and Y directions are shown.
• Object parameterization. This allows you to select a single object on the image. Details such as its full width half maximum, peak intensity etc. will be shown. These values are based on a 2D gaussian fit.
• STC-S regions. STC-S region outlines (often used to define footprints of various kinds) can be drawn.

#### 3.3 On-line catalogue capabilities

More recently GAIA has been extended to offer similar features, catalogue and image access, using the developing Virtual Observatory. These like the features above are found in the Data-Servers menu of the main window.

Note: you should take time to find what your obligations, in terms of the correct acknowledgement of copyright, use of service etc. are, whenever you use facilities such as those mentioned above.

#### 3.4 Local catalogues

GAIA allows you to save remote catalogue queries to a local file. These can then be re-loaded and plotted as if on-line catalogues. This is very useful if you need to re-plot catalogues, but equally useful is the fact that local catalogues may be modified. So you can edit, sort, select and delete records (using a tool like TOPCAT9 or a simple editor if the facilities GAIA offers are not sufficient).

##### 3.4.1 Catalogue formats

Local catalogues may be stored in several formats. The “native” version is called a “tab separated table” (TST). This is a simple text file in which the values of the various fields are separated by a single <TAB> character and the catalogue headers are separated from these by a dashed line:

#  comment
keyword1: value1
keyword2: value2

...
ID   <TAB>   RA     <TAB>   DEC   <TAB>  MAG     ...
--           --             ---          ---
OBJ1 <TAB>   210.00 <TAB>   54.00 <TAB>  16.1
OBJ2 <TAB>   210.01 <TAB>   54.01 <TAB>  15.1
....

The usual format of a catalogue is as above, i.e. an object identifier followed by an RA and DEC (in J2000 decimal degrees). Note the <TAB> strings shouldn’t be typed in, they are shown explicitly just to make clear where they should be placed. The TST format is also recognised by the TOPCAT and CURSA packages (SUN/190). CURSA also contains a description of this format.

Additional formats that can be also read and written by GAIA (with a performance penalty) are those supported by the CURSA package (i.e. FITS-tables and STL format) and the “ASCII_HEAD” format of the SExtractor/EXTRACTOR package (SUN/226), as well as the XML VOTable10 format.

The format that is used to open or write a catalogue, is determined by the file extension:

• FITS tables, accepted file types: .FIT .fit .FITS .fits .GSC .gsc
• STL, accepted file types: .TXT .txt
• ASCII_HEAD, accepted file types: .asc .ASC .lis .LIS
• VOTable, accepted file types: .xml .XML .vot .VOT

All other file extensions are assumed to indicate a TST (the preferred extensions for these are .tab or .TAB).

##### 3.4.2 Using your own local catalogues

If you have a simple text file containing columns of positions then the most straight-forward way to plot them in GAIA is by using the ‘Select Positions...’ toolbox. This accepts (as do the various astrometry toolboxes) a file containing the following values:

ID  RA  DEC  X  Y

in that order, e.g.

1   00:19:49.47   00:07:25.9   854    50
2   00:20:06.71   00:06:05.3   240   244
3   00:19:47.54   00:04:23.2   925   484
4   00:19:58.07   00:04:49.1   549   424
5   00:19:48.69   00:06:59.0   882   114

The columns should be space separated and the celestial coordinates should be in decimal degrees, or sexagesimal format as shown above. More complex files can be imported into this toolbox using its ‘Import text file...’ option (this allows fixed column widths or other separators). If you need to import such a file into a catalogue window, (this is the sort of window that queries to on-line catalogues are shown in, and provide extra facilities like applying intensity cuts etc.) then use the Import plain text file... toolbox from the Positions... menu.

You can also create your own local catalogues in TST format. This allows you to describe how to plot the catalogue. For instance if you wanted to plot position vectors as correctly orientated lines over an image you would need a tab table that contained the following sort of information (again note that the <TAB> string should be replace by a single tab character):

# File created by: pwd on June 15, 1999 at 10:24:04
id_col: 0
x_col: 1
y_col: 2
symbol: {ID LENGTH ANGLE} {line {} {} {$ANGLE+27.0} {} {}} {{$LENGTH*0.1} {}}
#
ID <TAB>    XPOS    <TAB> YPOS    <TAB> LENGTH   <TAB>  ANGLE
--          ----          ---           ------          -----
ID#1 <TAB>  206.000 <TAB> 189.000 <TAB> 6.32528  <TAB>  104.816
ID#2 <TAB>  209.000 <TAB> 189.000 <TAB> 5.86891  <TAB>  109.238

The x_col and y_col parameters indicate the columns of the data that correspond to the X and Y positions and the symbol parameter how to plot a line centered on that position. In this case the statements says extract values for the ID, LENGTH and ANGLE columns, then draw lines with position angle ANGLE+27 and length LENGTH$\ast$0.1 pixels. Note that a dollar sign is used to prefix column names in these expressions (in fact these expressions will be parsed by the Tcl “expr” command, with the column values set to a variable with the same name as the column for each line in the table).

Creating such a symbol parameter is best done by using the special Set Plot Symbols... window, available under the local catalogue menu Options. Using this window you can plot multiple symbols per object, specify which column to use as labels, change the graphic colour etc.. Now if you look in the file ˜/.skycat/skycat.cfg after setting up your options a suitable symbol parameter is recorded together which the description for your local catalogue (which you can then edit into your tab files).

To find out more about the TST format and how to configure plot symbols you should consult the ESO document ‘Astronomical Catalog Library’11 and ‘Writing Catalogue and Image Servers for GAIA and CURSA ’ (SSN/75).

##### 3.4.3 FITS tables

Much of the above also applies to FITS tables that GAIA will read, i.e. FITS keywords with the name SYMBOL will be interpreted correctly. Special parameter names that are longer than 8 characters (such as search_cols, sort_order, show_cols and copyright) should be truncated. Long symbol expressions can span more than one card by using the names: SYMBOL1 through SYMBOL9. The columns used for world coordinates should have units of degrees or radians and have names like RA and DEC.

#### 3.5 CUPID catalogues and masks

Catalogues produced by the CUPID application can be displayed in 2D or 3D and it’s masks can be displayed or used to view regions.

To display a 2D catalogue just open it as a local catalogue or import it using the Import CUPID catalogue... toolbox in the Image-Analysispositions menu. This latter option allows you to select which columns to use as RA and Dec and whether to use the special Shape column as the plotting symbol (STC-S ellipses and polygons are supported). If you choose not to use the STC-S shapes then boxes based on the extents will be displayed.

Displaying 3D catalogues should be done by importing them using the cube toolbox (ViewImport CUPID catalogue). When imported this way only regions that are in the current slice will be displayed. Note that if opened as a 2D catalogue all the regions will be displayed. 3D catalogues can also be viewed in a 3D scene as prisms, just select one of the 3D renderers in the View menu in the cube toolbox and click on the CUPID tab and select Display catalogues:. You can restrict the regions displayed to rows selected in the associated catalogue window by selecting Only show selected rows:.

To use a 2D mask open it using the Mask image... toolbox in the Image-Analysis menu. This can then be applied to the displayed image and individual or ranges of regions can be selected for display.

To use a 3D mask look in the CUPID tab in the 3D rendering window and select your mask in the Mask: entry. To just display the mask select Display: and press Draw. To view individual regions or a range enter some values into Values:. To apply these regions to the main cube and select the original flux you need to select Apply mask: and probably select Display: of the mask itself (although you can display both together, in that case you may want to change the opacity).

#### 3.6 Accessing images of differing formats

GAIA can display and perform analyses on many different data formats. It does this by using the “on-the-fly” conversion facilities of the NDF library, which it uses directly. This on-the-fly conversion uses external programs that can convert your data from its current format into an NDF and then back again (if necessary).

The CONVERT (SUN/55) package provides many formats that are useful for astronomers (e.g. FITS, IRAF and old FIGARO formats) and is automatically used by GAIA (unless you have set up your own conversion facilities, see SSN/20 if you think you need to do this). All the formats recognised at any time by GAIA are shown in a menu in the file chooser, so check this to see if your format is available.

FITS files are a special case in that GAIA will read these natively (which gains increased efficiency), however, any external analysis routines (such as those used in the photometry toolbox) will still need to be able to convert these files into NDFs, using the on-the-fly facility, so if you define your own conversion facilities make sure that you include a FITS converter (note these doesn’t apply to FITS data cubes, GAIA handles converting these into NDFs for the various toolboxes directly).

To display any of these images in GAIA just type the full disk-file name on the command-line (either when you start GAIA or by using the gaiadisp command), or similarly select the disk-file in the open file window.

To display a FITS file extension image, either open the disk file and choose the extension from the HDU selector window that appears, or add the extension number to the disk-file name:

# gaia mef_file.fits’[2]’

The FITS primary array is number $1$.

A similar mechanism exists for NDFs stored in container files at other than the top-level:

# gaia hdscontainer.ndf_1

In this case any other NDFs stored at the same level in the container file will also be shown in a selector window. NDF slices can also be used:

# gaia hdscontainer.ndf_1’(200:500,100:700)’

This can also be applied to FITS files and other foreign formats, but note that this means that FITS files will now be accessed as foreign, i.e. the FITS files will really be NDFs:

# gaia file.fits’(300:700,300:700)’

#### 3.7 SAMP interoperability

SAMP stands for Simple Application Messaging Protocol. It is a protocol which allows tools on the desktop to communicate with each other. Very briefly, the way it works is that applications can send messages to a central hub process which will then pass them on to other applications which can respond to them in some appropriate way. GAIA can use SAMP to send and receive images, sky position information, and catalogues or identification of rows within them. It can also send extracted spectra. You will require a hub, either free-standing or integral to some other application, to use these capabilities.

You can find more information about how it works, what applications are compatible, and how it can be useful at the SAMP12 web page. To remove the Interop menu you can use the Startup options... window located in the File menu.

SAMP is an evolution of the earlier similar protocol PLASTIC13. PLASTIC support, which was provided in earlier versions of GAIA, has now been withdrawn in favour of SAMP.

4http://nedwww.ipac.caltech.edu

6http://arch-http.hq.eso.org/dss/dss