00001 /** @file psImage.h 00002 * 00003 * @brief Contains basic image definitions and operations 00004 * 00005 * This file defines the basic type for an image struct and functions useful 00006 * in manupulating images. 00007 * 00008 * @ingroup Image 00009 * 00010 * @author Robert DeSonia, MHPCC 00011 * @author Ross Harman, MHPCC 00012 * 00013 * @version $Revision: 1.1.1.1 $ $Name: $ 00014 * @date $Date: 2005/09/14 20:42:48 $ 00015 * 00016 * Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii 00017 */ 00018 #ifndef PS_IMAGE_H 00019 #define PS_IMAGE_H 00020 00021 #include <complex.h> 00022 #include <stdio.h> 00023 #include "psType.h" 00024 #include "psArray.h" 00025 #include "psConstants.h" 00026 00027 /// @addtogroup Image 00028 /// @{ 00029 00030 /** enumeration of options in interpolation 00031 * 00032 */ 00033 typedef enum { 00034 PS_INTERPOLATE_FLAT, ///< 'flat' interpolation (nearest pixel) 00035 PS_INTERPOLATE_BILINEAR, ///< bi-linear interpolation 00036 PS_INTERPOLATE_LANCZOS2, ///< Sinc interpolation with 4x4 pixel kernel 00037 PS_INTERPOLATE_LANCZOS3, ///< Sinc interpolation with 6x6 pixel kernel 00038 PS_INTERPOLATE_LANCZOS4, ///< Sinc interpolation with 8x8 pixel kernel 00039 PS_INTERPOLATE_BILINEAR_VARIANCE, ///< Variance version of PS_INTERPOLATE_BILINEAR 00040 PS_INTERPOLATE_LANCZOS2_VARIANCE, ///< Variance version of PS_INTERPOLATE_LANCZOS2 00041 PS_INTERPOLATE_LANCZOS3_VARIANCE, ///< Variance version of PS_INTERPOLATE_LANCZOS3 00042 PS_INTERPOLATE_LANCZOS4_VARIANCE ///< Variance version of PS_INTERPOLATE_LANCZOS4 00043 // PS_INTERPOLATE_NUM_MODES ///< enum end-marker; does not coorespond to a interpolation mode 00044 } psImageInterpolateMode; 00045 00046 /** Basic image data structure. 00047 * 00048 * Struct for maintaining image data of varying types. It also contains 00049 * information about image size, parent images and children images. 00050 * 00051 */ 00052 typedef struct psImage 00053 { 00054 const psMathType type; ///< Image data type and dimension. 00055 const int numCols; ///< Number of columns in image 00056 const int numRows; ///< Number of rows in image. 00057 const int col0; ///< Column position relative to parent. 00058 const int row0; ///< Row position relative to parent. 00059 00060 union { 00061 psU8** U8; ///< Unsigned 8-bit integer data. 00062 psU16** U16; ///< Unsigned 16-bit integer data. 00063 psU32** U32; ///< Unsigned 32-bit integer data. 00064 psU64** U64; ///< Unsigned 64-bit integer data. 00065 psS8** S8; ///< Signed 8-bit integer data. 00066 psS16** S16; ///< Signed 16-bit integer data. 00067 psS32** S32; ///< Signed 32-bit integer data. 00068 psS64** S64; ///< Signed 64-bit integer data. 00069 psF32** F32; ///< Single-precision float data. 00070 psF64** F64; ///< Double-precision float data. 00071 psC32** C32; ///< Single-precision complex data. 00072 psC64** C64; ///< Double-precision complex data. 00073 // psPtr** PTR; ///< Void pointers. 00074 psPtr* V; ///< Pointer to data. 00075 } data; ///< Union for data types. 00076 const struct psImage* parent; ///< Parent, if a subimage. 00077 psArray* children; ///< Children of this region. 00078 00079 psPtr rawDataBuffer; ///< Raw data buffer for Allocating/Freeing Images 00080 void *lock; ///< Optional lock for thread safety 00081 } 00082 psImage; 00083 00084 /** Basic image region structure. 00085 * 00086 * Struct for specifying a rectangular area in an image. 00087 * 00088 */ 00089 typedef struct 00090 { 00091 float x0; ///< the first column of the region. 00092 float x1; ///< the last column of the region. 00093 float y0; ///< the first row of the region. 00094 float y1; ///< the last row of the region. 00095 } 00096 psRegion; 00097 00098 /** Create an image of the specified size and type. 00099 * 00100 * Uses psLib memory allocation functions to create an image struct of the 00101 * specified size and type. 00102 * 00103 * @return psImage* : Pointer to psImage. 00104 * 00105 */ 00106 psImage* psImageAlloc( 00107 int numCols, ///< Number of rows in image. 00108 int numRows, ///< Number of columns in image. 00109 psElemType type ///< Type of data for image. 00110 ) 00111 ; 00112 00113 00114 /** Checks the type of a particular pointer. 00115 * 00116 * Uses the appropriate deallocation function in psMemBlock to check the ptr datatype. 00117 * 00118 * @return bool: True if the pointer matches a psImage structure, false otherwise. 00119 */ 00120 bool psMemCheckImage( 00121 psPtr ptr ///< the pointer whose type to check 00122 ); 00123 00124 00125 /** Create a psRegion with the specified attributes. 00126 * 00127 * @return psRegion : a cooresponding psRegion. 00128 */ 00129 psRegion psRegionSet( 00130 float x0, ///< the first column of the region. 00131 float x1, ///< the last column of the region + 1. 00132 float y0, ///< the first row of the region. 00133 float y1 ///< the last row of the region + 1. 00134 ); 00135 00136 /** Create a psRegion with the attribute values given as a string. 00137 * 00138 * Create a psRegion with the attribute values given as a string. The format 00139 * shall be of the standard IRAF form '[x0:x1,y0:y1]' 00140 * 00141 * @return psRegion: A new psRegion struct, or NULL is not successful. 00142 */ 00143 psRegion psRegionFromString( 00144 const char* region ///< image rectangular region in the form '[x0:x1,y0:y1]' 00145 ); 00146 00147 /** Create a string of the standard IRAF form '[x0:x1,y0:y1]' from a psRegion. 00148 * 00149 * @return psString: A new string representing the psRegion as text, or NULL 00150 * is not successful. 00151 */ 00152 psString psRegionToString( 00153 const psRegion region ///< the psRegion to convert to a string 00154 ); 00155 00156 /** Sets an actual region based on image parameters. 00157 * 00158 * An image region defined with negative upper limits may be rationalized for the bounds of a 00159 * specific image with psRegionForImage. The output of this function is a region with negative 00160 * upper limits replaced by their corrected value appropriate to the given image. In addition, 00161 * the lower and upper limits are foced to lie within the bounds of the image. If the lower- 00162 * limit coordinates are lewss than the lower bound of the image, they are limited to the lower 00163 * bound of the image. Conversely, if the upper-limit coordinates are greater than the upper 00164 * bound of the image, they are truncated to define only valid pixels. If the lower-limit 00165 * coordinates are greater than the upper bounds of the image, or the upper-limit coordinates 00166 * are less than the lower bounds of the image, the coordinates should saturate on those limits. 00167 * 00168 * @return psRegion: A region with negative upper limits replaced by the corrected 00169 */ 00170 psRegion psRegionForImage( 00171 psImage *image, ///< the image for which the region is to be set 00172 psRegion *in ///< the image region limits 00173 ); 00174 00175 /** Defines a region corresponding to the square with center at coordinate x,y 00176 * and with coderadius. The width of the square is 2radius + 1. 00177 * 00178 * @return psRegion: the newly defined psRegion. 00179 */ 00180 psRegion psRegionForSquare( 00181 double x, ///< x coordinate at square-center 00182 double y, ///< y coordinate at square-center 00183 double radius ///< radius of square 00184 ); 00185 00186 /** Initializes the image with the given value. 00187 * 00188 * The input data is cast to match the image datatype. 00189 * 00190 * @return bool: True on success, otherwise false. 00191 */ 00192 bool psImageInit( 00193 psImage *image, ///< the image to be initialized 00194 ... ///< Variable argument list for initialization 00195 ); 00196 00197 /** Resize a given image to the given size/type. 00198 * 00199 * @return psImage* Resized psImage. 00200 */ 00201 psImage* psImageRecycle( 00202 psImage* old, ///< the psImage to recycle by resizing image buffer 00203 int numCols, ///< the desired number of columns in image 00204 int numRows, ///< the desired number of rows in image 00205 const psElemType type ///< the desired datatype of the image 00206 ); 00207 00208 /** Copy an image to a new buffer 00209 * 00210 * @return True if image copied or false if error 00211 */ 00212 bool p_psImageCopyToRawBuffer( 00213 void* buffer, ///< the buffer used to copy the image 00214 const psImage* input, ///< the input image to be copied 00215 psElemType type ///< the datatype of the image to be copied 00216 ); 00217 00218 /** Frees all children of a psImage. 00219 * 00220 * @return int Number of children freed. 00221 */ 00222 int psImageFreeChildren( 00223 psImage* image ///< psImage in which all children shall be deallocated 00224 ); 00225 00226 /** get an element of an image as a psF64. 00227 * 00228 * @return psF64 pixel value at specified location 00229 */ 00230 psF64 p_psImageGetElementF64( 00231 psImage* image, ///< input image 00232 int col, ///< pixel column 00233 int row ///< pixel row 00234 ); 00235 00236 /** print image pixel values. 00237 * 00238 * @return bool TRUE is successful, otherwise FALSE. 00239 */ 00240 bool p_psImagePrint( 00241 int fd, ///< Destination file descriptor 00242 psImage *a, ///< image to print 00243 char *name ///< name of the image (for title) 00244 ); 00245 00246 /** Interpolate image pixel value given floating point coordinates. 00247 * 00248 * @return psF32 Pixel value interpolated from image or unexposedValue if 00249 * given x,y doesn't coorespond to a valid image location 00250 */ 00251 complex psImagePixelInterpolate( 00252 const psImage* input, ///< input image for interpolation 00253 float x, ///< column location to derive value of 00254 float y, ///< row location ot derive value of 00255 const psImage* mask, ///< if not NULL, the mask of the input image 00256 psMaskType maskVal, ///< the mask value 00257 complex unexposedValue, ///< return value if x,y location is not in image. 00258 psImageInterpolateMode mode ///< interpolation mode 00259 ); 00260 00261 #define PIXEL_INTERPOLATE_FCN_PROTOTYPE(SUFFIX, RETURNTYPE) \ 00262 inline RETURNTYPE p_psImagePixelInterpolate##SUFFIX( \ 00263 const psImage* input, /**< input image for interpolation */ \ 00264 float x, /**< column location to derive value of */ \ 00265 float y, /**< row location ot derive value of */ \ 00266 const psImage* mask, /**< if not NULL, the mask of the input image */ \ 00267 psU32 maskVal, /**< the mask value */ \ 00268 RETURNTYPE unexposedValue /**< return value if x,y location is not in image. */ \ 00269 ); 00270 00271 #define PIXEL_INTERPOLATE_FCNS(MODE) \ 00272 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_U8,psF64) \ 00273 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_U16,psF64) \ 00274 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_U32,psF64) \ 00275 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_U64,psF64) \ 00276 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_S8,psF64) \ 00277 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_S16,psF64) \ 00278 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_S32,psF64) \ 00279 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_S64,psF64) \ 00280 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_F32,psF64) \ 00281 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_F64,psF64) \ 00282 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_C32,psC64) \ 00283 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_C64,psC64) 00284 00285 #ifndef SWIG 00286 PIXEL_INTERPOLATE_FCNS(FLAT) 00287 PIXEL_INTERPOLATE_FCNS(BILINEAR) 00288 PIXEL_INTERPOLATE_FCNS(BILINEAR_VARIANCE) 00289 #endif // ! SWIG 00290 00291 #undef PIXEL_INTERPOLATE_FCN_PROTOTYPE 00292 #undef PIXEL_INTERPOLATE_FCNS 00293 00294 /// @} 00295 00296 #endif // PS_IMAGE_H
1.4.2