XMM-Newton SAS Home Page
XMM-Newton Science Analysis System

implot (implot-2.20.1) [xmmsas_20230412_1735-21.0.0]

Detailed description.

This task takes FITS image datasets, eg those arising from EPIC or OM observations, and produces image files in any of the file formats supported by the local version of PGPLOT. This can be set by the user via the parameter device. The default value of device is /XS (Xserver), but alternative outputs (depending on what drivers have been installed with PGPLOT) can be used, for example /XW for x-windows, /GIF, /JPEG, /PS for Postscript, and /CPS for Colour Postscript. The Data Products ICD specifies that graphics products should be in PNG format, but this may not be supported by available versions of PGPLOT. A temporary fix is to produce GIF images and convert these to PNG using a separate utility.

The FITS image is first scaled and (optionally) truncated in intensity and size. Either a colour-coded image or a contour map image can be produced, depending on the value of imagestyle.

The scaling or image transfer function is controled by the parameter zscaletype, which can have values `linear', `log' or `sqrt'.

If it is desired to truncate the brightest and faintest values in the image, the user should set withzclip=yes (the default). The truncation values are submitted via the parameters zhistolo and zhistohi, each of which is restricted to the range 0 to 1. The way these work is perhaps best conveyed by an example. Suppose zhistohi is set to 0.85. The brightness values are sorted and the brightness level that separates the fainter 85% of the pixels is calculated. This level is then defined as the maximum brightness to be displayed, and all brighter pixels are set to this level. The working of zhistolo is similar but of course inverted.

A new feature in implot 2.0 is the ability to show only a subset of the image. The previous versions `cut away' any blank border area, showing only those rows and columns of the image which contained at least 1 non-zero-valued pixel; this facility is retained, although it is now controllable via the parameter trimborder. The default for this is `yes' however and I imagine that the user could comfortably forget about it except in exceptional circumstances. The image may now be further truncated in $x$ and $y$ via the parameters withxyclip, xfraclo, xfrachi, yfraclo and yfrachi. If withxyclip=yes, the task shows (filling the whole field available) only that fraction of the image (minus its blank borders, if trimborder has been left at `yes') between xfraclo and xfrachi etc is displayed. This amounts to a zoom facility.

The colour map (for colour-coded image output, imagestyle=`image') is choosable via the parameter colourmap. Its valid values are as follows:

Note that 0 is not a valid colour map index.

The default colour map is number 7 which is a rainbow with the addition of black for the very lowest level, shading into white at the highest levels.

If imagestyle=`contour' has been chosen the output is a contour map. The spacing between contours may be controlled in one of two ways, either by specifying that separation directly (contourstyle=`separation', contourseparation) or by specifying the number of contours between mininum and maximum image values (contourstyle=`number', ncontours).

Images may be annotated with various ancillary information, all of which can be controlled with input parameters. The available annotations are:

  1. Frame and text information: each image can be labeled with the FITS keywords reporting the instrument, observation, exposure, target, date, and principal investigator, if the appropriate information can be found in the file. This facility is invoked via the parameter withframe.

  2. Coordinate Grid: if selected with gridstyle=`grid', a sky coordinates (RA, DEC) grid is plotted over the image; gridstyle=`ticks' causes only the RA and Dec tick marks around the edge of the plot to be drawn. Note that, for these annotations to be possible, the image must contain the appropriate WCS keywords.

  3. Annotated sources: if withsrclisttab=y (the default) and the appropriate source-list dataset+table (containing columns RA and DEC, with the values in decimal degrees) is specified using srclisttab, a small circle or ellipse is drawn around the position of each selected source. The interface is now fairly versatile: a subset of sources can be selected for plotting; the radii of the circles can be varied in several ways; and labels can be added to the circles. These facilities are described in more detail in the following subsections.

XMM-Newton SOC -- 2023-04-16