Content-type: text/html Manpage of cgspec

cgspec

Section: User Commands (1)
Index Return to Main Contents
 

NAME

cgspec - Overlay spectra on images with PGPLOT.  

PERSON RESPONSIBLE

nebk  

CATEGORIES

plotting  

DESCRIPTION

CGSPEC overlays spectra at spatial locations (specified in a text file) on images (displayed via a colour pixel map representation and/or contour plots) on a PGPLOT device.  

PARAMETERS

in
You may input up to 10 images. Some of these are used to make a 2-D spatial display (up to 3 displayed via contours and 1 displayed via a colour pixel map representation). Of the rest, upto 5 may have spectra extracted from them, and 1 may be used as a mask. The pixel map, contour, and mask images must be of identical dimensions and size. Each spectrum image can be of any dimensions, size, and order. The mask image blanking mask is logically ORed to the pixel map and and contour plot image masks before they are displayed. The mask image is not displayed.

These images can be input in any order (see TYPE). Wild card expansion is supported. No default.

type
Specifies the type of each image given, respectively, in the IN keyword. Minimum match is supported (note that "pixel" was formerly "grey" [which is still supported]). Choose from:

"contour" (contour; up to 3 of these) xyv "pixel" (pixel map; up to 1 of these) xyv "spectrum" (spectrum; up to 5 of these) any order "dspectrum" (spectrum derivative ) any order "mask" (mask; up to 1 of these) xyv

The "spectrum" images can be in any order. However, it will be faster to have the spectrum on the first axis if the cube is very large (i.e. the image should be in vxy order. Use REORDER if necessary). The "dspectrum" images are the same as "spectrum" images, except that the derivative of the spectrum with channel is taken by CGSPEC before it is plotted. This is useful for Zeeman enthusiasts. You can have up to 5 "spectrum" and "dspectrum" images in total.

region
Region of interest. This applies only to, and equally to, the pixel map, contour and mask images. All the image planes you select will be averaged before display. Only the bounding box of the selected region is supported.
xybin
Upto 4 values. These give the spatial increment and binning size in pixels for the x and y axes to be applied to the selected region. If the binning size is not unity, it must equal the increment. For example, to bin up the image by 4 pixels in the x direction and to pick out every third pixel in the y direction, set XYBIN=4,4,3,1 Defaults are 1,XYBIN(1),XYBIN(1),XYBIN(3)
slev
Up to 3 pairs of values for each contour image. First value is the type of contour level scale factor; "p" for percentage and "a" for absolute. Second value is the factor to scale LEVS by. Thus, SLEV=p,1 would contour levels at LEVS * 1% of the image peak intensity. Similarly, SLEV=a,1.4e-2 would contour levels at LEVS * 1.4E-2 Default is no additional scaling of LEVS (i.e., "a",1.0)
levs1
The levels to contour for the first specified contour image are LEVS1 times SLEV (either percentage of the image peak or absolute). Defaults try to choose something vaguely useful.
levs2
LEVS for the second contour image.
levs3
LEVS for the third contour image.
grange
4 values. These are the image intensity range to display (min to max), the transfer function type and the colour lookup table for the displayed pixel map image. The transfer function type can be one of "lin" (linear), "sqr" (square root), "log" (logarithmic), and "heq" (histogram equalization). The colour lookup table is an integer from 1 to 8 specifying a lookup table. Valid values are 1 (b&w), 2 (rainbow), 3 (linear pseudo colour), 4 (floating zero colour contours), 5 (fixed zero colour contours), 6 (rgb), 7 (background), 8 (heat), and 9 (absolute b&w). If you enter a negative integer, then the reversed lookup table is displayed.

The transfer function changes available with OPTIONS=FIDDLE are in addition (on top of) to the selections here, but the colour lookup table selections will replace those selected here.

Default is linear between the image minimum and maximum with a b&w lookup table. You can default the intensity range with zeros, viz. "range=0,0,log,-2" say.

vrange
2 values. The velocity range, in km/s, to plot. If the first axis of the spectrum image(s) is not velocity (say Frequency), use the natural units of that axis. Default is min to max from all the spectrum images.
irange
2 values. The intensity range to plot for the spectra. Default is min to max from all the spectrum images.
iscale
Up to 5 values. A factor for each spectrum image by which it is multiplied before plotting. Defaults are all 1.
spsize
2 values. These are the sizes of the spectra, in fractions of the view-port, in the x- and y-directions. Defaults are 0.1, 0.1
stick
2 values. Major tick mark increments on the spectrum axes or frame for labelling purposes. No default.
device
The PGPLOT plot device, such as plot.plt/ps No default.
labtyp
2 values; the spatial label types of the x and y axes. Minimum match is active. Select from:

"hms" the label is in H M S.S (e.g. for RA) "dms" the label is in D M S.S (e.g. for DEC) "arcsec" the label is in arcsecond offsets "arcmin" the label is in arcminute offsets "absdeg" the label is in degrees "reldeg" the label is in degree offsets

          The above assume the pixel increment is in radians
"abspix" the label is in pixels "relpix" the label is in pixel offsets "absnat" the label is in natural coordinates as defined by
          the header.
"relnat" the label is in offset natural coordinates "none" no label and no numbers or ticks on the axis

All offsets are from the reference pixel of the contour/pixel map images. Defaults are "relpix" except if LABTYP(1)="hms" when LABTYP(2) defaults to "dms" (to give RA and DEC).

options
Task enrichment options. Minimum match of all keywords is active.

"blconly" means that if you have asked for some kind of spectrum

  labelling (frame or axes), only draw the frame or axes for
  the spectrum in the bottom left hand corner of the plot
"colour" means make the axes the same colour as the first
  spectrum, else they are white.
"blacklab" means that, if the device is white-background, draw
  the axis labels in black. Default is red.
"fiddle" means enter a routine to allow you to interactively
  change the display lookup table.  You can cycle through a
  variety of colour lookup tables, as well as alter a linear
  transfer function by the cursor location, or by selecting
  predefined transfer functions (linear, square root,
  logarithmic, histogram  equalization)

  For hard copy devices (e.g. postscript), a keyboard driven
  fiddle is offered; you can cycle through different colour
  tables and invoke the predefined transfer functions, but the
  linear fiddler is not available.  In this way you can make
  colour hardcopy plots.
"frame" means draw a frame to the left and bottom of each spectrum
  and put the numeric labels on that frame. The default is no
  frame plotting.
"full" means do full plot annotation with contour levels, pixel
  map intensity range, image names, reference values, etc.
  Otherwise more room for the plot is available.
"grid" means draw a coordinate grid on the plot rather than just
  ticks
"mark" marks the spatial location of the spectrum position with
  a star.  The spectra are plotted so that the centre if the
  frame (which could be drawn with OPTIONS=FRAME) is at the
  specified spatial location.   This positioning is not very
  obvious without the frame.
"mirror" causes all specified contour levels for all contour
  images to be multiplied by -1 and added to the list of
  contours
"naked" means don't write the numeric axis labels on the spectrum
  axes or frame so as to reduce clutter
"noaxes" means don't draw the X=0 and Y=0 axes which would,
  by default, be drawn and have the numeric labels on them.
  If the X=0 or Y=0 axes are not in the X and Y axis ranges of
  your plot, then a FRAME (see above) option will automatically
  be turned on for that axis.
"noblank" means draw the spectra where requested even if all of
  the displayed 2-D images are blanked at that location.  By
  default, a spectrum is not displayed if all of the spatial
  pixels over which the spectrum is averaged are blanked in all
  of the displayed 2-D images.  Otherwise you get to see it.
"noepoch" means don't write the Epoch into the spatial axis
  label strings
"noerase" Don't erase a rectangle into which the "number"
  string is written.
"normalize" This option makes each spectrum come out with a
  peak of 1.0. This normalization is done after application
  of ISCALE, so you could set ISCALE=-1 to make absorption
  look like emssion and then normalize.
"number" writes the number of the spectrum in the corner of
  the box surrounding the spectrum.  The number is just
  just the counter counting how many locations there are in
  the overlay file (see OLAY).
"relax" means issue warnings when image axis descriptors are
  inconsistent (e.g. different pixel increments) instead
  of a fatal error.  Applies to pixel map, contour and
  mask images only.
"solneg1" means make negative contours solid and positive
  contours dashed for the first contour image. The default,
  and usual convention is the reverse.
"solneg2" SOLNEG1 for the second contour image. "solneg3" SOLNEG1 for the third contour image. "unequal" means draw plots with unequal scales in x and y
  so that the plot surface is maximally filled.  The default
  is for equal scales in x and y.
"wedge" means that if you are making a pixel map display, also draw
  and label a wedge to the right of the plot, showing the map
  of intensity to colour
"1sided" means that for a derivative spectrum image, take a
  1-sided derivative instead of the default 2-sided derivative
clines
Up to 3 values. The line widths for each contour image as specified in the order of TYPE. These widths are integer multiples of 1. Defaults are all 1 for interactive devices and 2 for har copy devices.
slines
Up to 5 pairs of values. These are the line widths and types to use for the spectra for each spectrum image. Line types can be 1 -> 5 (solid and a variety of dashed/dotted types). Widths are integer multiples of 1. Defaults are all 1 for interactive devices, and 2,1 for hard copy devices.
blines
Up to 2 values. These are the line widths to use for 1) the border and labels of the contour/pixel map display and 2) the border/axes for the spectra. Widths are integer multiples of 1. Defaults are 1,1 for interactive devices, and 2,2 for hard copy devices.
break
Up to 3 values. The intensity levels for the break between solid and dashed contours for each contour image. Defaults are 0.0,0.0,0.0
csize
Up to two values. Character sizes in units of the PGPLOT default (1, which is ~ 1/40 of the view surface height) for the contour/pixel map labels and the spectrum labels. Defaults try to do something useful.
olay
You can either give one file name, or as many file names as there are spectrum images. These files describe the locations at which the overlay spectra are to be drawn. If you give one file only, the locations described by it are applied to all the input spectrum images. If you give several files, each of these corresponds to the spectrum image in the order they are given in keyword IN.

Wild card expansion is active and there is no default.

Entries in the overlay file can be white space or comma delimitered or both. All lines beginning with # are ignored.

                **** DO NOT USE TABS ****

Double quotes " are used below to indicate a string. The " should not be put in the file. For all the string parameters discussed below, you can abbreviate them with minimum match.

Miriad task "CGCURS" with OPTIONS=LOG,CGSPEC,CURSOR can be used to prepare a file suitable as input to OLAY.

There are two formats, depending upon the first line.

---------------------- CASE 1; GRID LOCATIONS ----------------------

If the first line is

GRID

There should be one further line in the file:

  XINC  YINC  XSIZ  YSIZ

XINC and YINC are the increments across the contour/pixel map image in ARCSEC at which spectra are to be drawn starting from the bottom left corner of the display (defined by the REGION keyword)

XSIZ and YSIZ are the spatial half-sizes in ARCSEC over which each spectrum is spatially averaged. These are optional and default to 0 (no binning, just a spectrum at each spatial pixel)

--------------------------- CASE 2; IRREGULAR LOCATIONS ---------------------------

If the first line is

IRREGULAR

Each successive line describes one overlay spectrum location according to:

  XOTYPE YOTYPE  X   Y   XSIZ  YSIZ

XOTYPE and YOTYPE give the units of the overlay location contained in the file for the x- and y-directions, respectively. Choose from

 "hms", "dms", "hms", "dms", "abspix", "relpix", "arcsec",
 "arcmin", "absdeg", "reldeg", "absnat", and "relnat"  as
  described in the keyword LABTYP.

Note that %OTYPE does not depend upon what you specified for LABTYP.

X,Y defines the center of the overlay in the nominated OTYPE coordinate system (X and Y OTYPE can be different). Note that for coordinate systems other than "hms" and "dms", the coordinates are with respect to the pixel map & contour images axis descriptors, not those from the spectrum images.

For %OTYPE = "abspix ", "relpix", "arcsec", "arcmin", "absnat",

             "relnat", "absdeg", and "reldeg"  X & Y are single
              numbers.

For %OTYPE = "hms" or "dms", the X and/or Y location is/are replaced by three numbers such as HH MM SS.S or DD MM SS.S. Thus if XOTYPE=hms & YOTYPE=dms then the file should have lines like

 hms dms  HH MM SS.S DD MM SS.S

XSIZ and YSIZ are the spatial half-sizes in ARCSEC over which each spectrum is spatially averaged. These are optional and default to 0 (no binning, just a spectrum at each spatial pixel)


 

Index

NAME
PERSON RESPONSIBLE
CATEGORIES
DESCRIPTION
PARAMETERS

This document was created by man2html, using the manual pages.
Time: 18:35:38 GMT, July 05, 2011