Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 1567) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 1568) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.78 2004-08-19 00:26:42 price Exp $ +%%% $Id: psLibSDRS.tex,v 1.79 2004-08-19 01:04:08 eugene Exp $ \documentclass[panstarrs,spec]{panstarrs} @@ -381,13 +381,23 @@ \begin{verbatim} - void p_psSetFreeFcn(void* ptr); - ///< sets the fcn pointer to the appropriate ps*Free function. If NULL, - ///< then a generic free functionality is used (i.e., the old psFree - ///< functionality). - - freeFcn p_psGetFreeFcn(void* ptr); - ///< retrieves the function pointer to the higher-level free function to be - ///< used. If NULL, then the traditional psFree functionality shall be used. -\end{verbatim} +void p_psMemSetDeallocator(void* ptr, psFreeFcn freeFcn); +psFreeFcn p_psMemGetDeallocator(void* ptr); +\end{verbatim} + +A free function handles any deallocation procedures of an object +referred to by a pointer, excluding the freeing of the memory block of +the pointer reference itself. If the pointer refers to an object that +references other memory blocks this free function would insure the +freeing of any encapsulated memory block references. For example, +\code{psList} references a series of node objects of a linked list, so +its free function would free these node objects and the node object's +free function would free the data element references they may contain. + +The fucntion \code{p_psSetFreeFcn} is used to associated a free +function to a memory block, while \code{p_psGetFreeFcn} retrieves the +last free function set. To remove a free function from a memory +block, the \code{psSetFreeFcn} should be invoked with \code{NULL}. If +no free function is set, \code{p_psGetFreeFcn} shall return +\code{NULL}. \subsubsection{Callback Routines} @@ -497,5 +507,5 @@ typedef long (*psMemFreeCallback)(const psMemBlock *ptr); psMemFreeCallback psMemFreeCallbackSet(psMemFreeCallback func); -long psMemGetId(void); +psMemoryId psMemGetId(void); \end{verbatim} % @@ -573,5 +583,5 @@ % \begin{verbatim} -int psMemGetRefCounter(void *vptr); +psReferenceCount psMemGetRefCounter(void *vptr); void *psMemIncrRefCounter(void *vptr); void *psMemDecrRefCounter(void *vptr); @@ -1284,6 +1294,6 @@ } data; const struct psImage *parent; ///< parent, if a subimage - int Nchildren; ///< number of subimages - struct psImage **children; ///< children of this region (Nchildren total) + int nChildren; ///< number of subimages + struct psImage **children; ///< children of this region (nChildren total) } psImage; \end{verbatim} @@ -1302,5 +1312,5 @@ starting column number in the parent image while \code{y0} is the starting row number. The structure may include references to -subrasters (\code{children, Nchildren}) and/or to a containing array +subrasters (\code{children, nChildren}) and/or to a containing array (\code{parent}). Unless this image is a child of another image (represents a subset of the pixels of another image), the image data @@ -2335,11 +2345,9 @@ Create a copy of the specified image, converting the type in the process. If the output target pointer is not \code{NULL}, place the -result in the specified structure. If the output target pointer is -\code{NULL}, the original data type must be maintained. The output -image data must be allocated as a single, contiguous block of memory. -The output image may not be the input image. This function must be -defined for the following types: \code{psU8}, \code{psU16}, -\code{psS8}, \code{psS16}, \code{psF32}, \code{psF64}, \code{psC32}, -\code{psC64}. +result in the specified structure. The output image data must be +allocated as a single, contiguous block of memory. The output image +may not be the input image. This function must be defined for the +following types: \code{psU8}, \code{psU16}, \code{psS8}, \code{psS16}, +\code{psF32}, \code{psF64}, \code{psC32}, \code{psC64}. \begin{verbatim} @@ -2363,9 +2371,15 @@ } psImageCutDirection; -psVector *psImageSlice(psVector *out, const psImage *input, +psVector *psImageSlice(psVector *out, + psVector *coords, + const psImage *restrict input, const psImage *restrict mask, unsigned int maskVal, - int x, int y, int nx, int ny, - psImageCutDirection direction, const psStats *stats); + unsigned int x, + unsigned int y, + unsigned int nx, + unsigned int ny, + psImageCutDirection direction, + const psStats *stats); \end{verbatim} Extract pixels from rectlinear region to a vector (array of floats). @@ -2376,8 +2390,10 @@ output vectors is derived from the statistics of the pixels at that direction coordinate. The statistic used to derive the output vector -value is specified by \code{stats}. Only one of the statistics -choices may be specified, otherwise the function must return an error. -This function must be defined for the following types: \code{psS8}, -\code{psU16}, \code{psF32}, \code{psF64}. +value is specified by \code{stats}. If \code{coords} is not +\code{NULL}, the calculated coordinates along the slice are returned +in this vector. Only one of the statistics choices may be specified, +otherwise the function must return an error. This function must be +defined for the following types: \code{psS8}, \code{psU16}, +\code{psF32}, \code{psF64}. \begin{verbatim} @@ -2422,4 +2438,16 @@ \subsubsection{Image Geometry Manipulation} + +Several functions which manipulate the image geometry require the +specification of the interpolation scheme to be used. This +information is carried by the following enum: +\begin{verbatim} +typedef enum { + PS_INTERPOLATE_FLAT, + PS_INTERPOLATE_BILINEAR, + PS_INTERPOLATE_BICUBIC, + PS_INTERPOLATE_SINC +} psImageInterpolateMode mode; +\end{verbatim} \begin{verbatim} @@ -2447,11 +2475,5 @@ \begin{verbatim} psImage *psImageResample(psImage *out, const psImage *in, - int scale, psImageResampleMode mode); -typedef enum { - PS_RESAMPLE_FLAT, - PS_RESAMPLE_BILINEAR, - PS_RESAMPLE_BICUBIC, - PS_RESAMPLE_SINC -} psImageResampleMode mode; + int scale, psImageInterpolateMode mode); \end{verbatim} Resample image to new scale. A new image is constructed in which the @@ -2463,19 +2485,19 @@ \begin{verbatim} -psImage *psImageRotate(psImage *out, const psImage *input, float angle, float exposed); +psImage *psImageRotate(psImage *out, const psImage *input, float angle, psC64 exposed, psImageInterpolateMode mode); \end{verbatim} Rotate the input image by given angle, specified in degrees. The output image must contain all of the pixels from the input image in their new frame. Pixels in the output image which do not map to input -pixels should be set to \code{exposed}. The center of rotation is -always the center pixel of the image. The rotation is specified in -the sense that a positive angle is an anti-clockwise rotation. This -function must be defined for the following types: \code{psU8}, -\code{psU16}, \code{psS8}, \code{psS16}, \code{psF32}, \code{psF64}, -\code{psC32}, \code{psC64}. +pixels should be set to \code{exposed}, cast to the same type as the +image. The center of rotation is always the center pixel of the +image. The rotation is specified in the sense that a positive angle +is an anti-clockwise rotation. This function must be defined for the +following types: \code{psU8}, \code{psU16}, \code{psS8}, \code{psS16}, +\code{psF32}, \code{psF64}, \code{psC32}, \code{psC64}. \begin{verbatim} psImage *psImageShift(psImage *out, const psImage *input, - float dx, float dy, float exposed); + float dx, float dy, psC64 exposed, psImageInterpolateMode mode); \end{verbatim} Shift image by an arbitrary number of pixels (\code{dx,dy}) in either @@ -2484,8 +2506,8 @@ image has the same dimensions as the input image. Pixels which fall off the edge of the output image are lost. Newly exposed pixels are -set to the value given by \code{exposed}. This function must be -defined for the following types: \code{psU8}, \code{psU16}, -\code{psS8}, \code{psS16}, \code{psF32}, \code{psF64}, \code{psC32}, -\code{psC64}. +set to the value given by \code{exposed}, cast to the same type as the +image. This function must be defined for the following types: +\code{psU8}, \code{psU16}, \code{psS8}, \code{psS16}, \code{psF32}, +\code{psF64}, \code{psC32}, \code{psC64}. \begin{verbatim} @@ -2541,6 +2563,8 @@ following types: \code{psS8}, \code{psU16}, \code{psF32}, \code{psF64}. -\begin{verbatim} -float psImagePixelInterpolate (psImage *input, float x, float y, psImageResampleMode mode); +\tbd{does this need to define the mask?} + +\begin{verbatim} +psF64 psImagePixelInterpolate (const psImage *input, float x, float y, psC64 unexposedValue, psImageInterpolateMode mode); \end{verbatim} Perform interpolation of image pixel values to the given fractional @@ -3224,4 +3248,9 @@ \subsubsection{Metadata Representation} +\begin{figure} +\psfig{file=Metadata.ps,width=6.5in} +\caption{Metadata Structures\label{fig:metadata}} +\end{figure} + This section addresses the question of how \PS{} metadata should be represented in memory, not how it should be represented on disk. @@ -3233,5 +3262,4 @@ char *restrict name; ///< Name of item psMetadataType type; ///< type of this item - psMetadataFlags flags; ///< flags associated with this item const union { psS32 S32; ///< integer value @@ -3247,10 +3275,8 @@ The \code{id} is a unique identifier for this item of metadata; experience shows that such tags are useful. The entry \code{name} -specifies the name of the metadata item. Metadata naming conventions -for the Pan-STARRS IPP are specified in the IPP Software Requirements -Specification (PSDC-430-005). The value of the metadata is given by -the union \code{data}, and may be of type \code{psS32}, \code{psF32}, -\code{psF64}, or an arbitrary rich structure pointed at by the -\code{void} pointer \code{void}. A character string comment +specifies the name of the metadata item. The value of the metadata is +given by the union \code{data}, and may be of type \code{psS32}, +\code{psF32}, \code{psF64}, or an arbitrary rich structure pointed at +by the \code{void} pointer \code{void}. A character string comment associated with this metadata item may be stored in the element \code{comment}. The \code{type} entry specifies the type of the data @@ -3271,13 +3297,4 @@ } psMetadataType; \end{verbatim} -The \code{flags} entry specifies some optional characteristics of the -metadata type, given by the enumerated type \code{psMetadataFlags}: -\begin{verbatim} -typedef enum { - PS_META_TYPE_MASK = 0xffff, ///< the type enum must fit in this mask - PS_META_UNIQUE = 0x10000, ///< the name must be unique (default) - PS_META_NON_UNIQUE = 0x20000, ///< the name may be repeated -} psMetadataFlags; -\end{verbatim} A collection of metadata is represented by the \code{psMetadata} structure: @@ -3299,12 +3316,23 @@ Certain metadata names (such as the FITS keywords \code{COMMENT} and \code{HISTORY} in a FITS header) may be repeated with different -values. The \code{psMetadataAdd} routine is required to check that -all metadata names are unique unless the type is qualified as -\code{PS_META_NON_UNIQUE}; in this case a unique integer must be added -to each name specified. +values. In such a case, the \code{psMetadata.list} structure contains +the entries in their original sequence with duplicate keys. The +\code{psMetadata.hash} entries, which are required to have unique +keys, would have a single entry with the keyword of the repeated key, +with the value of \code{psMetadataType} set to +\code{PS_META_ITEM_SET}, and the \code{psMetadataItem.items} element +pointing to a \code{psList} pointing to the actual entries. If +\code{psMetadataItemAlloc} is called with the type set to +\code{PS_META_ITEM_SET}, such a repeated key is created. If the data +value passed to \code{psMetadataItemAlloc} (the quantity in ellipsis) +is \code{NULL}, then an empty \code{psMetadataItem} with the given +keyword is created to hold future entries of that keyword. + +The \code{psMetadataAdd} routine is required to check that all +metadata names are unique unless the type is already qualified as +\code{PS_META_NON_UNIQUE}; in this case the data are added to the +corresponding \code{psMetadataItem.items} list. \subsubsection{Metadata APIs} - -In this section, we explain the metadata APIs more fully. The allocator for \code{psMetadataItem} returns a full @@ -3315,14 +3343,15 @@ optional flags, is constructed by bit-wise or'ing the appropriate type and flag. The \code{comment} entry is a fixed string which is used -for the comment associated with this metadata item. The arguments to -the \code{name} formatting codes and the metadata data itself are -passed to \code{psMetadataItemAlloc} as arguments following the -comment string. The data must be a pointer for any data types which -are stored in the element \code{data.void}, while other data types are -passed as numeric values. The argument list must be interpreted -appropriately by the \code{va_list} operators in the function. -\begin{verbatim} -psMetadataItem *psMetadataItemAlloc(const char *name, int format, const char *comment, ...); -psMetadataItem *psMetadataItemAllocV(const char *name, int format, const char *comment, va_list list); +for the comment associated with this metadata item. The metadata data +and the arguments to the \code{name} formatting codes are passed, in +that order (metadata pointer first), to \code{psMetadataItemAlloc} as +arguments following the comment string. The data must be a pointer +for any data types which are stored in the element \code{data.void}, +while other data types are passed as numeric values. The argument +list must be interpreted appropriately by the \code{va_list} operators +in the function. +\begin{verbatim} +psMetadataItem *psMetadataItemAlloc(const char *name, psMetadataType type, const char *comment, ...); +psMetadataItem *psMetadataItemAllocV(const char *name, psMetadataType type, const char *comment, va_list list); \end{verbatim}