[ Basic Info | User Guide ]

Basic Information on cgspec


Task: cgspec
Purpose: Overlay spectra on images with PGPLOT.
Categories: plotting

        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.
 

Key: in
        You may input up to 10 images.  Some of these are used to make
        a 2-D spatial display (one displayed via a colour pixel map
        representation up to three displayed via contours and).  Of the
        rest, up to five may have spectra extracted from them, and one
        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.

Key: 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.

Key: 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.

Key: xybin
        Up to four values which 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)

Key: slev
        Up to three 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)

Key: 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.

Key: levs2
        LEVS for the second contour image.

Key: levs3
        LEVS for the third contour image.

Key: grange
        Four values, 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), 9 (absolute b&w), 10-19 (cubehelix).
        Negate the number to reverse the lookup table.
 
        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.

Key: vrange
        Two values, the spectral range to plot, in the natural units of
        the axis, e.g. km/s for velocity, or GHz for frequency.  All
        spectra should be of the same type, use VELSW if necessary.
        Default is min to max from all the spectrum images.

Key: irange
        Two values, the intensity range to plot for the spectra.
        Default is min to max from all the spectrum images.

Key: iscale
        Up to five values, a factor for each spectrum image by which it
        is multiplied before plotting.
        Defaults are all 1.

Key: spsize
        Two values, being the sizes of the spectra, in fractions of the
        view-port, in the x- and y-directions.
        Defaults are 0.1, 0.1

Key: stick
        Two values, major tick mark increments on the spectrum axes or
        frame for labelling purposes.
        No default.

Key: device
        The PGPLOT plot device, such as plot.plt/ps
        No default.

Key: labtyp
        Two 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).
 

Key: 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
 

Key: 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.

Key: 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.

Key: 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.

Key: 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

Key: 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.

Key: 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-
        delimited or both.  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)
 
Revision: 1.19, 2021/06/02 04:45:09 UTC

Generated by miriad@atnf.csiro.au on 02 Jun 2021