psImageStructManip.h

Go to the documentation of this file.

/** @file  psImageStructManip.h
*
*  @brief basic image structure manipulation operations
*
*  @author Robert DeSonia, MHPCC
*
*  @version $Revision: 1.5 $ $Name:  $
*  @date $Date: 2007/01/23 22:47:23 $
*  Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii
*/

#ifndef PSIMAGE_STRUCT_MANIP_H
#define PSIMAGE_STRUCT_MANIP_H

/// @addtogroup ImageOps Image Operations
/// @{

#include "psImage.h"
#include "psRegion.h"

/** Create a subimage of the specified area.
 *
 *  Define a subimage of the specified area of the given image. This function must raise an
 *  error if the requested subset area lies outside of the parent image and return NULL. The
 *  argument image is the parent image, region.x0, region.y0 specify the starting pixel of the
 *  subraster, and region.x1,region.y1 specify the extent of the desired subraster. Note that
 *  the row and column of this upper right-hand corner NOT included in the region. In the event
 *  that x1 or y1 are negative, they shall be interpreted as being relative to the size of the
 *  parent image in that dimension. The entire subraster must be contained within the raster of
 *  the parent image. Note that the refCounter for the parent should be incremented.  This
 *  function must be defined for the following types: psU8, psU16, psS8, psS16, psF32, psF64,
 *  psC32, psC64.
 *
 *  @return psImage* : Pointer to psImage.
 *
 */
psImage* psImageSubset(
    psImage* image,                    ///< Parent image.
    psRegion region                    ///< region of subimage
);

/** Makes a copy of a psImage
 *
 * @return psImage* Copy of the input psImage.  This may not be equal to the
 * output parameter
 *
 */
psImage* psImageCopy(
    psImage* output,                   ///< if not NULL, a psImage that could be recycled.
    const psImage* input,              ///< the psImage to copy
    psElemType type                    ///< the desired datatype of the returned copy
);

/** Trim an image
 *
 *  Trim the specified image in-place, which involves shuffling the pixels around in memory.
 *  The pixels in the region [col0:col1,row0:row1] shall consist the output image.  The column
 *  col1 and row row1 are NOT included in the range.  In the event that x1 or y1 are
 *  non-positive, they shall be interpreted as being relative to the size of the parent image
 *  in that dimension.
 *
 *  If the entire specified subimage is not contained within the parent image, an error results
 *  and the return value will be NULL.
 *
 *  N.B. If the input psImage is a child of another psImage, no pixel data will be trimmed,
 *  rather it equivalent to calling psImageSubset.  If the input psImage is, however, a parent
 *  psImage, any children will be obliterated, i.e., freed from memory.
 *
 *  @return psImage*  trimmed image result
 */
psImage* psImageTrim(
    psImage* image,                    ///< image to trim
    psRegion region                    ///< trim region
);

/// @}
#endif // #ifndef PSIMAGE_STRUCT_MANIP_H

---