psImageStructManip.h

Go to the documentation of this file.

/** @file  psImageStructManip.h
*
*  @brief Contains basic image structure manipulation operations, as specified
*         in the PSLIB SDRS sections "Image Structure Manipulation".
*
*  @ingroup Image
*
*  @author Robert DeSonia, MHPCC
*
*  @version $Revision: 1.4 $ $Name: rel12 $
*  @date $Date: 2006/04/17 22:00:03 $
*
*  Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii
*/

#ifndef PSIMAGE_STRUCT_MANIP_H
#define PSIMAGE_STRUCT_MANIP_H

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

/// @addtogroup Image
/// @{

/** 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” are 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

---