coyote: CGASINHSCL

Description
This is a utility routine to perform an inverse hyperbolic sine
function intensity transformation on an image. I think of this
as a sort of "tuned" gamma or power-law function. The algorithm,
and notion of "asinh magnitudes", comes from a paper by Lupton,
et. al, in The Astronomical Journal, 118:1406-1410, 1999 September.
I've relied on the implementation of Erin Sheldon, found here::
   http://cheops1.uchicago.edu/idlhelp/sdssidl/plotting/tvasinh.html
I'm also grateful of discussions with Marshall Perrin on the IDL
newsgroup with respect to the meaning of the "softening parameter", beta,
and for finding (and fixing!) small problems with the code.
Essentially this transformation allow linear scaling of noise values,
and logarithmic scaling of signal values, since there is a small
linear portion of the curve and a much large logarithmic portion of
the curve. (See the EXAMPLE section for some tips on how to view this
transformation curve.)
Categories
Image Processing
Examples
Plot various values of beta::
    cgPlot,  cgASinhScl(Indgen(256), Beta=0.0), LineStyle=0
    cgOPlot, cgASinhScl(Indgen(256), Beta=0.1), LineStyle=1
    cgOPlot, cgASinhScl(Indgen(256), Beta=1.0), LineStyle=2
    cgOPlot, cgASinhScl(Indgen(256), Beta=10.), LineStyle=3
    cgOPlot, cgASinhScl(Indgen(256), Beta=100), LineStyle=4
Author
FANNING SOFTWARE CONSULTING::
    David W. Fanning
    1645 Sheely Drive
    Fort Collins, CO 80526 USA
    Phone: 970-221-0438
    E-mail: david@idlcoyote.com
    Coyote's Guide to IDL Programming: http://www.idlcoyote.com
History
Change History::
  Written by:  David W. Fanning, 24 February 2006.
  Removed ALPHA keyword and redefined the BETA keyword to correspond
    to the "softening parameter" of Lupton et. al., following the
    suggestions of Marshall Perrin. 25 April 2006. DWF.
  Renamed cgASinhScl from ASinhScl. 27 March 2015. DWF.
  Missed a couple of retire program name changes in the program. 7 April 2015. DWF.
Copyright
Copyright (c) 2008-2015, Fanning Software Consulting, Inc.
rn the inverse hyperbolic sine of the argument. Taken from the NASA
Astronomy Library and renamed for use in this program. The inverse 
rbolic sine is used for the calculation of asinh magnitudes, see 
on et al. (1999, AJ, 118, 1406). Expression given in  Numerical Recipes, 
s et al. (1992), eq. 5.6.7. Note that asinh(-x) = -asinh(x) and that 
h(0) = 0. and that if y = asinh(x) then x = sinh(y).
Returns
A byte scaled image is returned.
Params
image: in, required
   The image to be scaled. Written for 2D images, but arrays of any size are treated alike.
Keywords
beta: in, optional, type=float, default=3.0
    This keyword corresponds to the "softening parameter" in the Lupon et. al paper.
    This factor determines the input level at which linear behavior sets in. Beta
    should be set approximately equal to the amount of "noise" in the input signal.
    If BETA=0 there is a very small linear portion of the curve; if BETA=200 the
    curve is essentially all linear. The default value of BETA is set to 3, which
    is appropriate for a small amount of noise in your signal. The value is always
    positive.
max: in, optional
     Any value in the input image greater than this value is set to this value
     before scaling.
min: in, optional
     Any value in the input image less than this value is set to this value
     before scaling.
negative, in, optional, type=boolean, default=0
     If set, the "negative" of the result is returned.
omax: in, optional, type=byte, default=255
     The output image is scaled between OMIN and OMAX.
omin: in, optional, type=byte, default=0
     The output image is scaled between OMIN and OMAX.