; PROFL
;---------------------------------------------------------------
;! Generates plot file for a profile display.
;# Task PLOT TV IMAGE
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2009, 2011, 2014, 2020
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
PROFL     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
PROFL:  Task to generate a plot file for a profile display
USERID     -32000.0     32000.0    User ID ignored
INNAME                             Image name (name)
INCLASS                            Image name (class)
INSEQ           0.0      9999.0    Image name (seq. #)
INDISK          0.0         9.0    Disk drive #
BLC             0.0      4096.0    Bottom left corner of image
                                     0=>entire image
TRC             0.0      4096.0    Top right corner of image
                                     0=>entire image
XYRATIO         0.0        10.0    X to Y axis plot ratio. 0 =>
                                   header inc or window ratio
ZXRATIO         0.0         5.0    The ratio (Z/X) between the
                                   length of the unrotated X
                                   axis and the max Z axis.
ROTATE       -360.0       360.0    The rotation in degrees of
                                   the X - Y plane (countr clkw)
SKEW            0.0        90.0    The rotation (deg) of the X-Y
                                   plane away from the observer.
DIST            0.0      9999.0    Distance  from center of map
                                   image in X-axis lengths
XINC            0.0        99.0    Draw a line every XINCth col.
                                   0=>do not draw along columns.
YINC            0.0        99.0    Draw a line every YINCth row.
                                   0=>do not draw along rows.
PIXRANGE                           Range of image intensity
LTYPE        -410.0       410.0    Type of labeling: 1 border,
                                   2 no ticks, 3 standard, 4 rel
                                   to center, 5 rel to subim cen
                                   6 pixels, 7-10 as 3-6 with
                                   only tick labels
                                   <0 -> no date/time
DOCIRCLE       -1.0         1.0    > 0 => extend ticks to form
                                   coordinate grid
STVERS         -1.0     46655.0    STar file version number.
STFACTOR    -9999.0      9999.0    Scale star sizes: 0 => none.
                                   > 0 crosses with no labels
                                   < 0 crosses with labels
DOTV           -1.0         1.0    > 0 Do plot on the TV, else
                                   make a plot file
GRCHAN          0.0         8.0    Graphics channel 0 => 1.
TVCORN          0.0      2048.0    TV pixel location of bottom
                                   left corner of image 0=> self
                                   scale, non 0 => pixel scale.
----------------------------------------------------------------
PROFL
Type: Task
Use:  PROFL will write commands to a plot file for the execution
      of a profile plot (3D projection) for a cataloged image
      file.  The image plane is the X-Y plane and the image
      intensity is on the Z-axis.

      The algorithm for blanking hidden lines is fairly good,
      but can get into trouble with extremes of parameters such
      as ROTATE.  The algorithm handles the X and Y axes
      differently.  So, if the blanking is failing for some
      rotations, you should try transposing the image (task
      TRANS) and trying with a rotation reduced by 90 degrees.
Adverbs:
  USERID......The ID of the owner of the image.  Ignored.
  INNAME......Image name (name).       Standard defaults.
  INCLASS.....Image name (class).      Standard defaults.
  INSEQ.......Image name (seq. #).     0 => highest.
  INDISK......Disk unit #.             0 => any.
  BLC.........Bottom Left Corner of image to contour.
              (0,0) means entire image.
  TRC.........Top Right Corner of image to contour.
              (0,0) means entire image.
  XYRATIO.....The ratio of the X-axis to Y-axis pixel
              pixel separations. 0 => use ratio of axis
              increments or windows.
  ZXRATIO.....The ratio (Z/X) between the length of the
              unrotated (but scaled) X-axis and the max Z-axis.
              Use this as an intensity scaling factor.
  ROTATE......The rotation in deg of th X-Y plane (counter clkw)
  SKEW........The rotation (deg) of the X-Y plane away from the
              observer.
  DIST........The distance from center of the image in X-axis
              lengths (unrotated, but scaled by XYRATIO).
              For DIST=100, the profile plot is flat.
  XINC........Draw a line every XINCth column.  0 => do not draw
              along the columns.  Use 0 for the first try.
  YINC........Draw a line every YINCth row.  O => do not draw
              along the rows.  Use 1, 2 or 3 for the first try.
  PIXRANGE....Min,Max of Image intensity.  0=>entire range
  LTYPE.......Labelling type, see HELP LTYPE for details:
              1 = border, 2 = no ticks, 3 or 7 = standard, 4 or 8 =
              relative to ref. pixel, 5 or 9 = relative to subimage
              (BLC, TRC) center, 6 or 10 = pixels.  7-10 all labels
              other than tick numbers and axis type are omitted.
              Less than 0 is the same except that the plot file
              version number and create time are omitted.
              Add n * 100 to alter the metric scaling.
  DOCIRCLE....False (<= 0) means that tick marks are short lines
              extending inward from the plot borders.  True (>0)
              requests that a full coordinate grid be drawn.
  STVERS......Version number of ST (star position) file to be
              used to plot star positions.   0 => highest,
              < 0 => no star positions plotted.
  STFACTOR....Scale factor used to multiply star sizes in file
              for plotting. > 0 => scale star size
                            = 0 => don't plot stars.
                            < 0 => scale by abs(STFACTOR) and
                                   show any star label
  DOTV........> 0 => plot directly on the TV device, otherwise
              make a plot file for later display on one or
              more devices (including the TV if desired).
  GRCHAN......Graphics channel (1 - 7) to use for line drawing.
              0 => 1.
  TVCORN......TV pixel location (X,Y) where the bottom left-
              corner of the plot is to be placed. If either is
              zero, use the largest possible self scaling, else
              use pixel scaling with specified origin on the TV.
----------------------------------------------------------------
PROFL: Task to generate a plot file for a profile display.
DOCUMENTOR: E.B.Fomalont NRAO/VLA
RELATED PROGRAMS : PLROW, LWPLA, TKPL, TVPL, CNTR, GREYS, SLICE

                          PURPOSE

      Profile plots consist of vertical and/or horizontal line
profiles in which the height above the image plane, drawn in
perspective, is proportional to the intensity.  This display
type is also called an isometric plot and each line profile is
called a slice plot.  Profile plots give a good three-
dimensional representation of a radio source.  Negative features
are well-depicted and extended features are more obvious than on
contour plots or in gray-scale plots.
     The task PROFL is very general and the user can control
the perspective geometry associated with this display.  For the
most simple use of this task in which no perspective is used,
set DIST=100 and leave the other adverbs in their defaulted
values.  If no perspective is desired, the task PLROW is easier
to use and faster.  For large maps it is best to set YINC=5 and
XINC=0 for a first look without spending much execution time.

                          COMMENTS

XYRATIO:
     This is the ratio between the separation of an X-pixel and
a Y-pixel.  The default is normally a good choice unless the map
window is very rectangular.

ZXRATIO:
     This parameter is proportional to the x-pixel separation
ratio and height of the maximum value in the display as given by
PIXRANGE.  The value 1.0 means that the maximum intensity value
will be drawn about equal to the size of the full X-axis;
therefore the value of 0.2 is reasonable.  Some adjustment of
the intensity scale can be made using this adverb. If the map is
dominated by a point component of high amplitude, it is best to
use PIXRANGE to limit the intensity range to be plotted.  The
profile plot always self-scale in order to fit the entire plot
on one page.  If the point source dominates, the X-Y plane will
be suitably reduced in size.

ROTATE:
     The rotation of the X-Y plane about the Z-plane in degrees
(positive rotation is counter-clock-wise).

SKEW:
     The rotation in degrees of the X-Y plane with respect to
the observer.  It is nominally 45 deg, which is satisfactory in
most usage.  A value of 90 deg means the X-Y plane is seen
edge-on.  A value of 0 deg means the X-Y plane is seen face on
and the intensity profiles are invisible.  The amplitude of an
intensity feature on the plot varies as SIN(SKEW).

DISTANCE:
     The distance from the center of the X-axis to the observer.
 The default distance of 3 gives a nice 3-D projective display.
Set DISTANCE to 100 in order to give a flat-plane appearance
similar to Westerbork Style line plots.  (Use PLROW for a truely
flat display.)

XINC,YINC:
     The default values generally produce a plot which is more
complicated than needed.  As a first try set YINC=5 and XINC=0
and go from there.

PIXRANGE:
     Profile plots do not display more than about 30 to 1 ranges
of intensity very well.  Use PIXRANGE to limit the intensity
range as desired.

LTYPE:
     Note that character strings surrounding the plot use up a
fair amount of real estate.  Consider negative LTYPEs to get rid
of the plot file version number plus date/time string.  Consider
LTYPEs 7-10 to eliminate all but the tick numbers and X and Y
axis types.

STFACTOR:
     You can use STarFACTOR to add crosses or other symbols to
your plot to denote the postions of stars or other objects.
First you must read the postions into a ST table using STARS.
Then set INVER to the table version number.  You can scale the
sizes of the crosses be setting STFACTOR > 0.  Set STFACTOR to
1.0 for no scaling (use the star sizes in the ST table).  You
can label the crosses with a character string to help identify
them by setting STFACTOR < 0.  The label is the text string
entered when creating the ST table.  The star sizes in this case
will be scaled by ABS(STFACTOR).  Note that you can also rotate
the crosses through an angle by specifying a positon angle when
you create the ST table in STARS (see STARS for more
information).

DISPLAY OF PROFILES:
     As with most plotting programs in AIPS, a subsequent task
is used to display the output of PROFL on a device.  The tasks
TVPL or TKPL are useful for quick looks. LWPLA gives the best
hard copy.

QUALITY OF PLOT:
     On termination of PROFL, the messiness of the plot can be
judged by looking at the message on the monitor:

      GFINIS:  NUMBER RECORDS GUESSED NNN  USED MMM

If MMM is greater than about 2000, the plot is probably too
messy to be useful.  If MMM is less than about 20, nothing much,
except borders, etc., was produced.

EXECUTION TIMES:
     For a 100 x 100 map with YINC=1, XINC=0, the execution time
is about 20 sec and about 200 records are produced.  For XINC=1
as well, the execution time increases by a factor of 4.  Further
scaling of execution times goes with map area.
