/*****************************************************************************
*                                                                            *
*   GETRGB.SPL   Copyright (C) 1998-2020 DSP Development Corporation         *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Returns separate RGB components of an image                 *
*                                                                            *
*   Revisions:    8 Jun 1998  RRR  Creation                                  *
*                10 Sep 2004  RRR  (r,g,b) = getcolormap(m) returns rbg      *
*                17 Jun 2009  RRR  composite RGB conversion                  *
*                20 May 2020  RRR  alpha channel                             *
*                                                                            *
*****************************************************************************/

#if @HELP_GETRGB

    GETRGB

    Purpose: Returns the separate RGB components of an image

    Syntax:  (r, g, b) = GETRGB(image, imbits)
             (r, g, b, alpha) = GETRGB(image, imbits)

              image  - an array, the input image

              imbits - Optional. An integer, the rgb mode:

                         0: return the current image shading (default)
                         1: return the original image rgb values

    Returns: Up to three arrays with the same size as the input.

             (r, g, b) = GETRGB(image, imbits) returns the r, g, b
             values as three separate series.

             (r, g, b, alpha) = GETRGB(image, imbits) returns the r, g, b
             and alpha transparency values as four separate series.

    Example:
             W1: readimage(gethome + "\data\mandrill.bmp")
             (r, g, b) = getrgb(w1);
             g *= 1.2;
             W2: rgbimage(r, g, b);

             W2 contains a new RGB image formed by increasing the green
             component of W1 by 20%.

    Example:
             W1: readimage(gethome + "\data\mandrill.bmp")
             W2: ((demean(xvals(W1))^2) + (demean(yvals(W1)')'^2)) > (50)^2;setplottype(2)
             W3: (r, g, b, a) = getrgb(w1);rgbimage(r*w2, g*w2, b*w2, w2)
             W4: gnorm(1000, 1);overlay(w3);focus(2);setxy(-50, 300, -60, 300)

             W1 contains the original bitmap image.

             W2 uses the X and Y values of the image to construct a circular
             region.

             W3 creates a new image by masking the original RGB and alpha
             values with the circular mask, The image is formed with
             the masked components. The new image is the original image
             with a transparent "hole" at the center.

             W4 displays a series overlayed with the new image. The series
             values appear in the transparent hole.

    Example:
             W1: readimage(gethome + "\data\kasha.jpg");rainbow
             W2: (r1, g1, b1) = getrgb(w1);rgbimage(r1, g1, b1)
             W3: (r2, g2, b2) = getrgb(w1, 1);rgbimage(r2, g2, b2)

             W1 contains a 24 bit bitmap image shaded with the "rainbow"
             colormap.

             W2 contains an RGB image obtain from the "rainbow" shading of
             the source image.

             W3 contains an RGB obtained from the orignal RGB values of
             the source image.

    Remarks:
             Each RGB value ranges from 0.0 to 1.0.

             If the input is a scalar, GETRGB assumes the value is a 
             24 bit RGB value and returns the separate R, G, and B
             values ranging from 0 to 255.

             An ALPHA value of 0 indicates full transparency and a value
             of 255 indicates full opacity.

             If IMBITS is 0, the RGB values of the current shading are
             returned.

             If IMBITS is 1, the original RGB values of the image are returned
             regardless of the image shading.

    See Also:
             Getcolormap
             Image24
             Rgbimage
             Readbmp
#endif


/* get separate rgb components as arrays */
getrgb(s, imbits)
{
        local r, g, b, a;

        if (argc < 2)
        {
                if (argc < 1) error("getrgb - input image required");

                imbits = 0;
        }

        if (isarray(s) && numcols(s) > 1)
        {
                /* getcolormap can do it all */
                (r, g, b, a) = getcolormap(s, imbits);
        }
        else
        {
                /* convert a composite rgb value */
                r = s & 0xFF;
                g = (s >> 8) & 0xFF;
                b = (s >> 16) & 0xFF;
                a = ~(s >> 24) & 0xFF;

                if (isscalar(s))
                {
                        r = castint(r);
                        g = castint(g);
                        b = castint(b);
                        a = castint(a);
                }
        }

        return(r, g, b, a);
}