; RGBMP
;---------------------------------------------------------------
;! Task to create an RGB image from the 3rd dim of an image
;# TASK TV
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2002, 2006
;;  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
;-----------------------------------------------------------------------
RGBMP     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
RGBMP:  Task to create an RGB image from the 3rd dim of an image
USERID     -32000.0     32000.0    User ID.  0 => current user,
                                     32000 => any user.
INNAME                             Input name(name).
INCLASS                            Input name(class).
INSEQ           0.0      9999.0    Input name(seq. #). 0=> high
INDISK          0.0         9.0    Input disk drive #. 0=> any
OUTNAME                            Output name(name).
OUTCLASS                           Output name(class).
OUTSEQ         -1.0      9999.0    Output name(seq. #).
                                     0 => highest unique
OUTDISK         0.0         9.0    Output image disk drive #
                                     0 => highest with space
BLC                                Bottom left corner of input
TRC                                Top right corner of input
OPTYPE                             Allows experimental summing
                                   algorithms, else additive
FUNCTYPE                           Image intensity transfer func
                                     'L2' Very logarithmic
                                     'LG' Logarithmic
                                     'SQ' Square root
                                     else linear
PIXRANGE                           Image intensity extrema
                                   allowed
FACTOR         0.0          10.0   Scale "optical depths"
----------------------------------------------------------------
RGBMP
Type: Task
Use:  RGBMP will create a new cube with 3 planes from the weighted
      planes of an input cube.  The 3 planes can then be used to
      display the 3rd dimension as color on the TV or with display
      tasks such as GREYS, PCNTR, and KNTR.
      There are a number of experimental algorithms for summing the
      images into the 3 colors.  The default is a simple sum, weighted
      by "triangles in color:
              1 *---------------------------*
                | *                       * |
                |   *                   *   |
                |     *     Green     *     |
                |       *           *       |
                |  Blue   *       *   Red   |
                |           *   *           |
              0 |-------------*--------------
       where the Green is weighted down by ~1/2 since ~2 times as many
       channels contribute.  All other algorithms use this basic
       color weighting and adjust other parameters,
       If the third axis has a positive increment, then the first
       channel on that axis is the most blue as shown above.  Else,
       the last channel is the most blue.  If the axis type begins
       with FREQ, this convention is reversed.
Adverbs:
  USERID......User ID of owner of image.  0 => current user,
                32000 => any user.
  INNAME......Input name of image(name).     Standard defaults.
  INCLASS.....Input name of image(class).    Standard defaults.
  INSEQ.......Input name of image(seq. #).   0 => highest.
  INDISK......Disk drive # of image.         0 => any.
  OUTNAME.....Output name of image(name).    Standard defaults.
  OUTCLASS....Output name of image(class).   Standard defaults.
  OUTSEQ......Output name of image(seq. #).  0 => highest unique
  OUTDISK.....Disk drive # of Output image.  0 => highest with
              space.
  BLC.........The bottom left-hand pixel of the input image
              which becomes the bottom left corner of the
              new image.  The value (0,0) means (1,1).
  TRC.........The top right-hand pixel of the input image
              which becomes the top right corner of the
              new image.  The value (0,0) means take the top
              right hand corner of the image.
*******  Experimental algorithm parameters  ***********
  OPTYPE......Other than for the special values below, the output is
              the simple sum of the channel weights times the image at
              each channel.
              Current special values are 'CLIP', 'CLIS', 'OPTD',
              'OPT2', 'POPT', and 'POP2'.  See EXPLAIN.
  FUNCTYPE....'SQ' square root, 'LG' logarithmic [log10(1+9*x)],
              'L2' [0.5*log(1+99*X)] else linear to scale the image
              intensities in PIXRANGE to 0-1.  Used only if OPTYPE is
              a special value.
  PIXRANGE....Clip image values below PIXRANGE(1) and above
              PIXRANGE(2) in converting the scale.  Used only if
              OPTYPE is a special value.
  FACTOR......The "optical depth" is the scaled image values times
              FACTOR.  Used only if OPTYPE is a special value.
----------------------------------------------------------------

In order to offer a variety of ways to sum the image planes, a number
of experimental algorithms are available under control of OPTYPE,
enhanced with adverbs FUNCTYPE, PIXRANGE, and FACTOR. Current special
values for OPTYPE are 'CLIP', 'CLIS', 'OPTD', 'OPT2', 'POPT', and
'POP2'.  All of the special algorithms can produce good RGB images and
all can prduce useless ones.

If the input image at each plane of the cube is
       Bi (x,y)
then for all OPTYPEs other than the special value
       Ti(x,y) = Bi(x,y)
while for all special OPTYPEs, the clipped image is
       Ci(x,y) = MAX (PIXRANGE(1), MIN (PIXRANGE(2), Bi(x,y)))

For OPTYPE 'CLIP' when PIXRANGE(1) > 0,
       if Ci(x,y)=PIXRANGE(1) then Ti(x,y) = 0
                              else Ti(x,y) = Ci(x,y)

For all special OPTYPEs except CLIP, the image is then scaled and
warped to values between zero and one by
       z(x,y) = (Ci(x,y)-PIXRANGE(1)) / (PIXRANGE(2)-PIXRANGE(1))
       z(x,y) = min (1.0, max (0.0, z(x,y)))
       Si(x,y) = F[z]
where if FUNCTYPE='LN'  F(z) = z
                  'SQ'  F(z) = sqrt (z)
                  'LG'  F(z) = log10 (9*z + 1.0)
                  'L2'  F(z) = 0.5 * log10 (99*z + 1.0)
For OPTYPE = 'CLIS', Ti(x,y) = Si(x,y).

The "optical depth" associated with Si(x,y) is then
       t(x,y) = FACTOR * Si(x,y)

OPTYPEs 'POPT' and 'OPTD' then compute
       Ti(x,y) = Si(x,y) * (1 - exp(-t(x,y)))
while OPTYPEs 'POP2' and 'OPT2' then compute
       Ti(x,y) = Bi(x,y) * (1 - exp(-t(x,y)))

For all OPTYPEs except 'OPTD' and 'OPT2', the Ti(x,y)  computed above
and then weighted by the channel/color weight is summed:
       SUM(i) = Wi Ti(x,y) + SUM(i-1)

For OPTYPEs 'OPTD' and 'OPT2' however, the previous sum is "absorbed"
by the current optical depth:
       SUM(i) = Wi Ti(x,y) + SUM(i-1) * exp(-t(x,y))
Clearly, in this case, the order in which the channels are summed is
important and may be changed by running TRANS with TRANSCODE='12-3'.

