README file for FITSplot.pl by Dan Homan, NRAO, dhoman@nrao.edu FITSplot.pl v2.02, October 27, 2002 These scripts come with ABSOLUTELY NO WARRANTY of any kind. ------------------- Most Recent Changes ------------------- -- v2.02 -- A few small bugs have been corrected. The scripts also now automatically attempt to determine the scale (arcmin, arcsec, milli-arcsec) of an image. Of course, this behavior can be turned off by specifing the scale in the usual way. Several people wanted to know how to change the image transfer function. To do this, simply use the "pgsitf(n);" command from PGPLOT. n = 0 for a linear transfer function (default). n = 1 for a log transfer function, and n = 2 for a square-root transfer function. The script "mapview" has been added to provide a very simple way of viewing and manipulating FITS images to get simple statistics. Peak fitting will eventually be added to 'mapview'. To try it out, just type "mapview file.fits" - replacing 'file.fits' with whatever fits file you wish to explore. The script "kntr" has been improved to allowing changing of image transfer function on the command line as well as the brightness and contrast of color/grayscale images. -- v2.00 -- I've recently rewritten the subroutines to assume a number of defaults for common parameters. Of course, these defaults can be changed (see below), but they are very useful for shortening the number of required arguments to the subroutines. Overall, I think this makes the routines easier to use. The only downside is that old scripts based on v1.03 (or earlier) will not work with the new FITSplot.pl file -- I suggest just renaming the old file to something else if you wish to keep it around to run old scripts. See the new "kntr" script for a fast, easy way to generate quick contour and/or color plots of FITS images. Thanks to Bill Cotton for making this command line utility from the FITSplot subroutines. -------- Purpose: -------- FITSplot.pl contains a number of perl subroutines for plotting FITS images using the PGPLOT graphics library. The subroutines are designed to be flexibly combined to make a wide variety of plots... including combining contours, grayscale, color, polarization vectors, etc on a single pane. Multiple images may be easily combined in the same frame either as direct overlays or offset from one another by an arbitrary amount. Images may be rotated or shifted before plotting. Images made to different resolutions (pixel sizes) can be easily plotted together to the same scale. Images can be easily combined mathematically to make images of quantities like fractional polarization, spectral index, and Faraday rotation.... This is great for polarization images in stokes Q and U which can be combined by the scripts to make P and Chi images (see the MakeP subroutine). The subroutines are currently designed and tested on radio FITS images, but they should be easily adapted to other wavebands. We've had success with plotting both X-ray (from Chandra) and Optical (from Hubble) FITS images. We note that the X-ray images we tested needed a fair amount of linear shifting in x and y to center them (of course, this is easily done in the plotting scripts). For the Hubble image we tested, the keyword for specifying the angular size of each pixel seems to be different than that used in the X-ray or radio images (which use CDELT2). Two approaches for making these scripts work with such optical images are to (1) simply change the keyword in the FITS header (we just used a text editor to do this) or (2) modify the routines in FITSplot.pl to accept the alternate keyword. It is important to note that these scripts assume the sky is a simple square grid, which is true to a good approximation for small fields of view. ------------- Requirements: ------------- Perl libraries: PDL (Perl Data Language) "pgperl" (Perl interface to PGPLOT) ------ Files: ------ FITSplot.pl -- This file has all the subroutines. kntr -- A perl script using FITSplot.pl that provides a simple command line interface for making contour and/or color plots (up to 2 images may be overlayed). 3c120.* -- These are example FITS images of the radio source 3c120. These FITS files are included for the examples only, they do not constitute a 'publication' -- if you wish to make scientific use of these images, please contact Dan Homan, dhoman@nrao.edu example1.pl -- Simple example of a total intensity contour plot example2.pl -- Simple example of a polarization contour plot example3.pl -- Total intensity contour superimposed with fractional polarization color example4.pl -- Fancy example with multiple offset images + labels + marked jet component locations *.gif -- output of the above scripts in GIF format README -- This file. ------------- Installation: ------------- Installing these perl scripts is easy... (1) You can simply copy FITSplot.pl to whatever directory you are working in, or (2) you can put FITSplot.pl in some central directory and then tell perl where to find it with the PERL5LIB variable... export PERL5LIB=/users/dhoman/perl/ or the equivalent thing for csh shells. I have a command similar to the above in my .login file. This second method is really preferred as it is the most flexible (and you don't need to think about it again). ----------- How to use: ----------- (1) Simply use the "kntr" command-line script. Just type "kntr" at the prompt, and it will tell you how to use it. (You might need to type "perl kntr", if kntr is not executable.) This routine makes contour and/or color plots. The functionality is essentially identical to the KNTR task in AIPS. (2) Write a script of your own, using the subroutines, to make your plot. This method is by far the more flexible, but it takes a little bit of time. I usually start with one of the 'example' scripts (or another I have written), and can have a functional plot in a couple of minutes. Of course, complicated plots or new types of plots take longer to construct. To use method (2), read on. The best way to learn how to use these subroutines is to examine the four example files. Not all the subroutines in FITSplot.pl are used in these examples, so reading FITSplot.pl is also useful. Here I briefly present some general points. The sections "Defaults" and "Subroutines" below contain more specific information. The basic plan is to read in the FITS image as an array, crop out all but the part of the image we wish to display, do any map arithmetic desired, and finally plot the image array using PGPLOT. The user is assumed to be familiar with the PGPLOT library. Any valid PGPLOT subroutine can be accessed through the pgperl library binding by the same routine name. So pgbeg(0,'?',1,1); is the same command in perl as it is in Fortran (except the ";"). A great benefit of this is that all the flexibility of PGPLOT is available in perl for plotting. Indeed, the provided FITSplot.pl file just organizes some of these commands in a transparent manner for dealing with FITS images... all the others can be called and used as necessary, so the user can plot lines, write text, change properties like background color, foreground color, font, font size, line color, line width, line style, etc, etc... The Perl Data Language (PDL) is used because it handles arrays of numbers very efficiently. It reads a 2-dimensional FITS image into a single variable called a "piddle", say $a. Images can then be manipulated mathematically in a very direct way: $c = $a+$b, where $c, $a, and $b are all images. This makes doing map arithmetic very transparent. See the functions "MakeP" and "MakeF" in FITSplot.pl for examples of how this works (there are some subtleties to maintaining needed header information). Examples of accessing individual elements of the images and accessing the header information (to get info about center of the map, degrees per pixel, etc...) can also be found in FITSplot.pl. The subroutines in FITSplot.pl encapsulate this stuff, but it is useful to know for adding new subroutines. --------- Defaults: --------- At the start of the FITSplot.pl file is a list of default values which are part of the global hash variabile $plot, so $plot{'units'} = 'marcsec'; sets the default units to milli-arcseconds. These defaults are setup to make the subroutines easy to use by limiting the number of arguments needed to run each subroutine. Of course, all of these defaults can be changed - either on a permanent basis by editing the FITSplot.pl file or on a temporary basis by placing a new $plot command in your script. The example scripts show how to do this, but it is same syntax as used to set the defaults in the first place. Here is a list of the default global values (from FITSplot.pl) #------------------------- defining map units ---------------------------# $plot{'units'} = 'auto'; # default map units. # 'auto' means determine automatically # -- choices are 'marcsec' # 'arcsec' # 'arcmin' #---------------- how much of an image should be plotted ----------------# $plot{'image_corners'} = [0,0,0,0]; # x1,x2,y1,y2 for the image # in map units. All zeros means # use full image $plot{'plot_corners'} = [0,0,0,0]; # x1,x2,y1,y2 for the plotting # frame. All zeros means use # the image corners. #------------- how maps should be arranged on 'the page' ----------------# $plot{'offset'} = [0,0]; # offset for placing the plot on # 'the page' in map units $plot{'rotate'} = 0; # amount to rotate image on the page (deg) #------------- how polarization vector should be plotted ----------------# $plot{'tick_sep'} = [3,3]; # interval between pol. ticks (pixels) $plot{'tick_length'} = 1; # scale length of pol. ticks in map units $plot{'tick_rotate'} = 0; # additional rotation of pol. ticks (deg) #-------------------- how the colormap should appear --------------------# $plot{'color_type'} = 'heat'; # color scheme to use # -- see "colors.txt" for a list $plot{'color_reverse'} = 0; # set to one to reverse color ramp $plot{'color_ramp'} = 'ramp'; # type of color ramp # -- see "colors.txt" for a list $plot{'color_contrast'} = 1.0; # contrast level $plot{'color_bright'} = 0.5; # brightness (between 0 and 1) $plot{'pixel_range'} = [0,0]; # min,max range for plotting color/grayscale # All zeros means use full range of image. $plot{'wedge'} = 1; # set to zero for no color wedge $plot{'wedge_side'} = 'T'; # "B","L","T","R" for Bottom, Left, Top, # or Right side where the wedge is plotted $plot{'wedge_disp'} = 0; # displacement of wedge in character heights # from the side indicated above. Negative # values will place the plot inside the # viewport $plot{'wedge_width'} = 3; # width of the color wedge in character heights $plot{'wedge_label'} = ''; # string with a label for the wedge #--------------------- how contour plots should look --------------------# $plot{'contour_range'} = 5e4; # dynamic range of contours produced by # the 'loglevs' function $plot{'contour_negative'} = 2; # whether or not to make an equal number # negative and positive contours. # 0 -> no negative contours # 1 -> just 1 negative contour # 2 -> a negative contour for every # positive one #------------------------ Misc defaults --------------------------------# $plot{'title'} = ''; # title for the plot $plot{'font'} = 2; # default font. 1 = normal, 2 = roman # 3 = italics, 4 = script ------------ Subroutines: ------------ What follows is a brief description of how to run each subroutine in the FITSplot.pl file and basically what each does. For more information please look in the FITSplot.pl file itself. A couple internal subroutines in the FITSplot.pl file are not documented here. Note: Brackets [ ] are used here to denote a group of optional arguments. The brackets are not actually used when calling the function with these arguments. * Load_FITS * ------------- $array = Load_FITS($file, [ $plane1, $plane2 ]); This function loads a FITS file and returns a piddle with the image array. $file is the file name of the FITS image to load and is the only required argument. $plane1 and $plane2 are optional arguments (assumed to be zero) for 3 and 4 dimensional FITS images, and they determine which spectral or polarization plane of the image to return. Images are cut down in size by this function to just the sub-image specified by the $plot{'image_corners'} global variable. * plotbeam * ------------ plotbeam($image, [ \@center ]); This function plots a beam figure. $image is the image piddle for which the beam figure should be plotted and is the only required argument. An optional argument is the center location of where the beam should be located ( @center = (x,y); ). If the center position is omitted, the beam figure is placed in the bottom left-hand corner of the plot. * MakeP * --------- ($P, $Chi) = MakeP($Q, $U); This function creates image piddles $P and $Chi which are polarization intensity and position angle from piddles of $Q and $U which are Stokes Q and U images respectively. * MakeF * --------- $F = MakeF($I, $P, $icut, $pcut); This function creates a fractional polarization image, $F, from image piddles of $I and $P, the total and polarized intensities respectively. $icut and $pcut are lower levels at which to blank the images before dividing them. * MakeAlpha * ------------- $A = MakeAlpha($I1, $I2, $icut1, $icut2); This function returns a spectral index image piddle, $A, created from two image piddles $I1 and $I2. The frequencies of the images are taken from the image headers. An the sign convention is nu^{+alpha} if the first image is at the lower frequency (otherwise the sign convention is reversed). $icut1 and $icut2 are lower levels at which to blank the images before dividing them. Of course, this function assumes the images are in the same units. * Shift * --------- Shift($image, $xshift, $yshift); This function shifts the image piddle, $image, with interpolation along a distance $xshift and $yshift (both in plot units). The image array (piddle) itself is actually shifted here. This may be useful for making spectral index maps (see above). To simply shift where an image appears in the output plot, use the $plot{'offset'} variable instead. * ticks * ---------- ticks($P, $Chi, $pcut, [ $Lengths ]); This function plots 'tick marks' for polarization vectors. It takes a polarization intensity image piddle, $P, a polarization angle image piddle, $Chi, and a cutoff level, $pcut, below which not tick marks are plotted. An optional image pidde, $Lengths, may be included which will specifiy the length of the tick marks at each pixel. This might be a fractional polarization image, for example. The length of the tick marks are either $plot{'tick_length'}; or if a length image is specified ($Lengths argument above), $plot{'tick_length'} times the value of $Lengths at each pixel. * loglevs * ----------- @contours = loglevs($base, $step); This function returns an array of contour levels starting at $base and increasing in multiplicative steps of $istep. The $plot{'contour_range'} and $plot{'contour_negative'} global variables control how many contours to create and how many should be negative respectively. * contour * ----------- contour($image, \@conts, $nlevs); This function plots a contour image of the piddle, $image, using the array of contours, @conts, which is of length, $nlevs. * grayscale * ------------- grayscale($image, [ \@crop ]); This function plots a grayscale image of the piddle, $image. An optional argument is an array of cropping pixels (@crop = (1,1,1,1);) which is the number of pixels to crop in from each edge of the image before plotting. This "crop" argument is largely unnecessary, but at times can be useful due to the way grayscale (and color) images overwrite other graphics. Note that the min and max of the grayscale image is defined by the global variable $plot{'pixel_range'}. * colorscale * -------------- colorscale($image, [ \@crop ]); Syntax and usage is identical to the 'grayscale' functions. There are a wide range of gobal variables to control how the color image appears (see above).