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/10/14 00:32:52 $ 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 int col0; ///< Column position relative to parent. 00058 int row0; ///< Row position relative to parent. 00059 00060 union { 00061 psS8** S8; ///< Signed 8-bit integer data. 00062 psS16** S16; ///< Signed 16-bit integer data. 00063 psS32** S32; ///< Signed 32-bit integer data. 00064 psS64** S64; ///< Signed 64-bit integer data. 00065 psU8** U8; ///< Unsigned 8-bit integer data. 00066 psU16** U16; ///< Unsigned 16-bit integer data. 00067 psU32** U32; ///< Unsigned 32-bit integer data. 00068 psU64** U64; ///< Unsigned 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* V; ///< Pointer to data. 00074 } data; ///< Union for data types. 00075 const struct psImage* parent; ///< Parent, if a subimage. 00076 psPtr p_rawDataBuffer; ///< Raw data buffer for Allocating/Freeing Images; private 00077 psArray* children; ///< Children of this region. 00078 void *lock; ///< Optional lock for thread safety 00079 } 00080 psImage; 00081 00082 /** Basic image region structure. 00083 * 00084 * Struct for specifying a rectangular area in an image. 00085 * 00086 */ 00087 typedef struct 00088 { 00089 float x0; ///< the first column of the region. 00090 float x1; ///< the last column of the region. 00091 float y0; ///< the first row of the region. 00092 float y1; ///< the last row of the region. 00093 } 00094 psRegion; 00095 00096 /** Create an image of the specified size and type. 00097 * 00098 * Uses psLib memory allocation functions to create an image struct of the 00099 * specified size and type. 00100 * 00101 * @return psImage* : Pointer to psImage. 00102 * 00103 */ 00104 psImage* psImageAlloc( 00105 int numCols, ///< Number of rows in image. 00106 int numRows, ///< Number of columns in image. 00107 psElemType type ///< Type of data for image. 00108 ) 00109 ; 00110 00111 /** Checks the type of a particular pointer. 00112 * 00113 * Uses the appropriate deallocation function in psMemBlock to check the ptr datatype. 00114 * 00115 * @return bool: True if the pointer matches a psImage structure, false otherwise. 00116 */ 00117 bool psMemCheckImage( 00118 psPtr ptr ///< the pointer whose type to check 00119 ); 00120 00121 00122 /** Create a psRegion with the specified attributes. 00123 * 00124 * @return psRegion : a cooresponding psRegion. 00125 */ 00126 psRegion psRegionSet( 00127 float x0, ///< the first column of the region. 00128 float x1, ///< the last column of the region + 1. 00129 float y0, ///< the first row of the region. 00130 float y1 ///< the last row of the region + 1. 00131 ); 00132 00133 /** Create a psRegion with the attribute values given as a string. 00134 * 00135 * Create a psRegion with the attribute values given as a string. The format 00136 * shall be of the standard IRAF form '[x0:x1,y0:y1]' 00137 * 00138 * @return psRegion: A new psRegion struct, or NULL is not successful. 00139 */ 00140 psRegion psRegionFromString( 00141 const char* region ///< image rectangular region in the form '[x0:x1,y0:y1]' 00142 ); 00143 00144 /** Create a string of the standard IRAF form '[x0:x1,y0:y1]' from a psRegion. 00145 * 00146 * @return psString: A new string representing the psRegion as text, or NULL 00147 * is not successful. 00148 */ 00149 psString psRegionToString( 00150 const psRegion region ///< the psRegion to convert to a string 00151 ); 00152 00153 /** Sets an actual region based on image parameters. 00154 * 00155 * An image region defined with negative upper limits may be rationalized for the bounds of a 00156 * specific image with psRegionForImage. The output of this function is a region with negative 00157 * upper limits replaced by their corrected value appropriate to the given image. In addition, 00158 * the lower and upper limits are foced to lie within the bounds of the image. If the lower- 00159 * limit coordinates are lewss than the lower bound of the image, they are limited to the lower 00160 * bound of the image. Conversely, if the upper-limit coordinates are greater than the upper 00161 * bound of the image, they are truncated to define only valid pixels. If the lower-limit 00162 * coordinates are greater than the upper bounds of the image, or the upper-limit coordinates 00163 * are less than the lower bounds of the image, the coordinates should saturate on those limits. 00164 * 00165 * @return psRegion: A region with negative upper limits replaced by the corrected 00166 */ 00167 psRegion psRegionForImage( 00168 psImage *image, ///< the image for which the region is to be set 00169 psRegion in ///< the image region limits 00170 ); 00171 00172 /** Defines a region corresponding to the square with center at coordinate x,y 00173 * and with coderadius. The width of the square is 2radius + 1. 00174 * 00175 * @return psRegion: the newly defined psRegion. 00176 */ 00177 psRegion psRegionForSquare( 00178 double x, ///< x coordinate at square-center 00179 double y, ///< y coordinate at square-center 00180 double radius ///< radius of square 00181 ); 00182 00183 /** Initializes the image with the given value. 00184 * 00185 * The input data is cast to match the image datatype. 00186 * 00187 * @return bool: True on success, otherwise false. 00188 */ 00189 bool psImageInit( 00190 psImage *image, ///< the image to be initialized 00191 ... ///< Variable argument list for initialization 00192 ); 00193 00194 /** Sets the value of the image at the specified x,y position to value. 00195 * 00196 * A negative value for the x or y positions means index from the end. 00197 * 00198 * @return bool: True on success, otherwise false. 00199 */ 00200 bool psImageSet( 00201 const psImage *image, ///< the image to set 00202 int x, ///< x-position 00203 int y, ///< y-position 00204 complex value ///< specified value to set 00205 ); 00206 00207 /** Returns the value of the image at the specified x,y position. 00208 * 00209 * A negative value for the x or y positions means index from the end. 00210 * 00211 * @return complex: The value at the specified x,y position. 00212 */ 00213 complex psImageGet( 00214 const psImage *image, ///< the image from which to get 00215 int x, ///< x-position 00216 int y ///< y-position 00217 ); 00218 00219 /** Resize a given image to the given size/type. 00220 * 00221 * @return psImage* Resized psImage. 00222 */ 00223 psImage* psImageRecycle( 00224 psImage* old, ///< the psImage to recycle by resizing image buffer 00225 int numCols, ///< the desired number of columns in image 00226 int numRows, ///< the desired number of rows in image 00227 const psElemType type ///< the desired datatype of the image 00228 ); 00229 00230 /** Copy an image to a new buffer 00231 * 00232 * @return True if image copied or false if error 00233 */ 00234 bool p_psImageCopyToRawBuffer( 00235 void* buffer, ///< the buffer used to copy the image 00236 const psImage* input, ///< the input image to be copied 00237 psElemType type ///< the datatype of the image to be copied 00238 ); 00239 00240 /** Frees all children of a psImage. 00241 * 00242 * @return int Number of children freed. 00243 */ 00244 int psImageFreeChildren( 00245 psImage* image ///< psImage in which all children shall be deallocated 00246 ); 00247 00248 /** get an element of an image as a psF64. 00249 * 00250 * @return psF64 pixel value at specified location 00251 */ 00252 psF64 p_psImageGetElementF64( 00253 psImage* image, ///< input image 00254 int col, ///< pixel column 00255 int row ///< pixel row 00256 ); 00257 00258 /** print image pixel values. 00259 * 00260 * @return bool TRUE is successful, otherwise FALSE. 00261 */ 00262 bool p_psImagePrint( 00263 int fd, ///< Destination file descriptor 00264 psImage *a, ///< image to print 00265 char *name ///< name of the image (for title) 00266 ); 00267 00268 /** Interpolate image pixel value given floating point coordinates. 00269 * 00270 * @return psF32 Pixel value interpolated from image or unexposedValue if 00271 * given x,y doesn't coorespond to a valid image location 00272 */ 00273 complex psImagePixelInterpolate( 00274 const psImage* input, ///< input image for interpolation 00275 float x, ///< column location to derive value of 00276 float y, ///< row location ot derive value of 00277 const psImage* mask, ///< if not NULL, the mask of the input image 00278 psMaskType maskVal, ///< the mask value 00279 complex unexposedValue, ///< return value if x,y location is not in image. 00280 psImageInterpolateMode mode ///< interpolation mode 00281 ); 00282 00283 #define PIXEL_INTERPOLATE_FCN_PROTOTYPE(SUFFIX, RETURNTYPE) \ 00284 inline RETURNTYPE p_psImagePixelInterpolate##SUFFIX( \ 00285 const psImage* input, /**< input image for interpolation */ \ 00286 float x, /**< column location to derive value of */ \ 00287 float y, /**< row location ot derive value of */ \ 00288 const psImage* mask, /**< if not NULL, the mask of the input image */ \ 00289 psU32 maskVal, /**< the mask value */ \ 00290 RETURNTYPE unexposedValue /**< return value if x,y location is not in image. */ \ 00291 ); 00292 00293 #define PIXEL_INTERPOLATE_FCNS(MODE) \ 00294 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_U8,psF64) \ 00295 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_U16,psF64) \ 00296 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_U32,psF64) \ 00297 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_U64,psF64) \ 00298 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_S8,psF64) \ 00299 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_S16,psF64) \ 00300 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_S32,psF64) \ 00301 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_S64,psF64) \ 00302 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_F32,psF64) \ 00303 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_F64,psF64) \ 00304 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_C32,psC64) \ 00305 PIXEL_INTERPOLATE_FCN_PROTOTYPE(MODE##_C64,psC64) 00306 00307 #ifndef SWIG 00308 PIXEL_INTERPOLATE_FCNS(FLAT) 00309 PIXEL_INTERPOLATE_FCNS(BILINEAR) 00310 PIXEL_INTERPOLATE_FCNS(BILINEAR_VARIANCE) 00311 #endif // ! SWIG 00312 00313 #undef PIXEL_INTERPOLATE_FCN_PROTOTYPE 00314 #undef PIXEL_INTERPOLATE_FCNS 00315 00316 /// @} 00317 00318 #endif // PS_IMAGE_H
1.4.2