/*****************************************************************************
*                                                                            *
*   IMHIST.SPL   Copyright (C) 2026 DSP Development Corporation              *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Creates a histogram of an image                             *
*                                                                            *
*   Revisions:   22 Jul 2026  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_IMHIST

    IMHIST

    Purpose: Computes the intensity histogram of an image.

    Syntax:  IMHIST(image, nbins)

             image - An array, the input grayscale or RGB image.

             nbins - Optional. An integer, the number of histogram bins.
                     Defaults to 256.

    Returns: A series representing bin counts.

    Example:
             W1: readimage(gethome + "\data\siblings.tif", "Gray8"); scalesoff; label("Original")
             W2: histeq(W1); setaspect(-1); scalesoff; label("Equalized")
             W3: imhist(W1); label("Original Histogram")
             W4: imhist(W2); label("Equalized Histogram")

             W1 loads an 8-bit grayscale image with pixel intensity values 
             ranging from 0 to 255.

             W2 performs histogram equalization to improve image contrast.

             W3 displays the histogram of the original image.

             W4 displays the histogram of the equalized image, illustrating 
             the resulting uniform intensity distribution.

    Example:
             W1: readimage(gethome + "\data\kasha.jpg"); scalesoff; label("Original")
             W2: imhist(W1, 64); label("64-Bin Histogram")

             W1 loads a full color JPEG image.

             W2 computes and displays a 64-bin histogram representing the combined 
             RGB channel intensity distribution.

    Remarks:
             IMHIST computes the frequency distribution of pixel intensities for 
             a grayscale image.

             If the input is an RGB color image, histograms are calculated across 
             the R, G, and B channels independently and summed into a single series.

             See HISTEQ to modify an image's contrast using its histogram.

    See Also:
             Ampdist
             Histogram
             Histeq
             Image24
             Imcombine
             Partsum
             Readimage
             Rgb2hsv
             Rgb2mono

#endif


/* histogram of image */
imhist(img, nbins = -1)
{
        local r, g, b, hr, hg, hb, h, dx;

        if (argc < 1)
        {
                error(sprintf("%s - input image required", __FUNC__));
        }

        nbins = (nbins <= 0) ? 256 : nbins;
        dx    = 255 / (nbins - 1);

        if (rgbimage(img))
        {
                /* separate RGB components */
                (r, g, b) = getrgb(img);

                hr = hist(unravel(int(255 * r)), nbins, dx, 0.0, "round");
                hg = hist(unravel(int(255 * g)), nbins, dx, 0.0, "round");
                hb = hist(unravel(int(255 * b)), nbins, dx, 0.0, "round");

                /* combine RGB histograms */
                h = hr + hg + hb;

                sethunits(h, "RGB");

                /* spacing */
                setdeltax(h, 1);
        }
        else
        {
                if (numcols(img) > 1)
                {
                        if (max(img) <= 1.0 || max(img) > 255 || min(img) < 0)
                        {
                                /* density */
                                dx = 1.0 / (nbins - 1);
                        }

                        /* histogram of intensity values */
                        h = hist(unravel(img), nbins, dx, 0.0, "round");
        
                        /* spacing */
                        setdeltax(h, 1);
                }
                else
                {
                        /* regular series histogram with natural spacing */
                        h = hist(unravel(img), nbins);
                }
        }

        /* set to lines */
        setplotstyle(h, 0);

        return(h);
}