psPixels.h

Go to the documentation of this file.

/** @file  psPixels.h
 *
 *  @brief Contains psPixel related functions
 *
 *  @ingroup Image
 *
 *  @author Robert DeSonia, MHPCC
 *
 *  @version $Revision: 1.1.1.1 $ $Name:  $
 *  @date $Date: 2005/09/14 20:42:48 $
 *
 *  Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii
 */
#ifndef PS_PIXELS_H
#define PS_PIXELS_H

#include "psImage.h"
#include "psVector.h"

/// @addtogroup Image
/// @{

/** Data structure for storing psPixel coordinates  */
typedef struct
{
    int x;                             ///< x coordinate
    int y;                             ///< y coordinate
}
psPixelCoord;

/** list of pixel coordinates
 *
 *  Usually an image mask is the best way to carry information about what
 *  pixels mean what. However, in the case where the number of pixels in which
 *  we are interested is limited, it is more efficient to simply carry a list
 *  of pixels. An example of this is in the image combination code, where we
 *  want to perform an operation on a relatively small fraction of pixels, and
 *  it is inefficient to go through an entire mask image checking each pixel.
 *
 */
typedef struct
{
    long n;                            ///< Number in usa
    const long nalloc;                 ///< Number allocated
    psPixelCoord* data;                ///< The pixel coordinates
    void *lock;                        ///< Option lock for thread safety
}
psPixels;


/** Allocates a new psPixels structure
 *
 *  @return psPixels*   new psPixels
 */
psPixels* psPixelsAlloc(
    long nalloc                       ///< the size of the coordinate vectors
)
;

/** Checks the type of a particular pointer.
 *
 *  Uses the appropriate deallocation function in psMemBlock to check the ptr datatype.
 *
 *  @return bool:       True if the pointer matches a psPixels structure, false otherwise.
 */
bool psMemCheckPixels(
    psPtr ptr                          ///< the pointer whose type to check
);


/** resizes a psPixels structure
 *
 *  @return psPixels*   resized psPixels
 */
psPixels* psPixelsRealloc(
    psPixels* pixels,                  ///< psPixels to resize, or NULL to create new psPixels
    long nalloc                       ///< the size of the coordinate vectors
);

/** Add a pixel location to a psPixels
 *
 *  @return psPixels*       psPixels with the value appended.
 */
psPixels* p_psPixelsAppend(
    psPixels* pixels,                  ///< psPixels to append new coordinate to.  NULL creates a new one.
    long growth,
    ///< number of elements to grow the psPixels list, if necessary.  if growth < 1, 10 is used.
    int x,                             ///< x coordinate to append
    int y                              ///< y coordinate to append
);

/** Copies a psPixels object
 *
 *  Makes a deep copy of the data in a psPixels object.  Any data in the OUT
 *  parameter will be destroyed and OUT will be resized, if necessary.
 *
 *  @return psPixels*   a new psPixels that is a duplicate to IN
 */
psPixels* psPixelsCopy(
    psPixels* out,                     ///< psPixels struct to recycle, or NULL
    const psPixels* pixels             ///< psPixels struct to copy
);

/** Generate a psImage from a psPixels
 *
 *  psPixelsToMask shall return an image of type U8 with the pixels lying
 *  within the specified region set to the maskVal. The out image shall be
 *  modified if supplied, or allocated and returned if NULL. The size of the
 *  output image shall be region->x1 - region->x0 by region->y1 - region->y0,
 *  with out->x0 = region->x0 and out->y0 = region->y0. In the event that
 *  either of pixels or region are NULL, the function shall generate an
 *  error and return NULL.
 *
 *  @return psImage*    generated mask image
 */
psImage* psPixelsToMask(
    psImage* out,                      ///< psImage to recycle, or NULL
    const psPixels* pixels,            ///< list of pixels to use
    psRegion region,                   ///< region to define the output mask image
    psMaskType maskVal                 ///< the mask bit-values to act upon
);

/** Generate a psPixels from a mask psImage
 *
 *  psMaskToPixels shall return a psPixels consisting of the coordinates in
 *  the mask that match the maskVal. The out pixel list shall be modified if
 *  supplied, or allocated and returned if NULL. In hte event that mask is
 *  NULL, the function shall generate an error and return NULL.
 *
 *  @return psPixels*   generated psPixels pixel list
 */
psPixels* psPixelsFromMask(
    psPixels *out,                     ///< psPixels to recycle, or NULL
    const psImage *mask,               ///< the input mask psImage
    psMaskType maskVal                 ///< the mask bit-values to act upon
);

/** Concatenates two psPixels
 *
 *  psPixelsConcatenate shall concatenate pixels onto out. In the event that
 *  out is NULL, a new psPixels shall be allocated, and the contents of
 *  pixels simply copied in. If pixels is NULL, the function shall generate
 *  an error and return NULL. The function shall take care to ensure that
 *  there are no duplicate pixels in out.
 *
 *  @return psPixels         Concatenated psPixel list
 */
psPixels* psPixelsConcatenate(
    psPixels *out,                     ///< psPixels to recycle, or NULL
    const psPixels *pixels             ///< psPixels to append to OUT
);

/** Prints a psPixels to specified destination.
 *
 *  @return bool:    True if successful.
*/
bool p_psPixelsPrint(
    FILE *fd,                          ///< destination file descriptor
    psPixels* pixels,                  ///< psPixels to print
    const char *name                   ///< printf-style format of header line
);

#endif // #ifndef PS_PIXELS_H

---