Index: trunk/doc/pslib/psLibSDRS.tex =================================================================== --- trunk/doc/pslib/psLibSDRS.tex (revision 4239) +++ trunk/doc/pslib/psLibSDRS.tex (revision 4242) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.275 2005-06-13 22:41:59 price Exp $ +%%% $Id: psLibSDRS.tex,v 1.276 2005-06-14 02:19:36 price Exp $ \documentclass[panstarrs,spec]{panstarrs} @@ -790,4 +790,96 @@ \subsubsection{Type information} +We need to be able to specify two different sorts of types. + +The first, for use with math structures (\S\ref{sec:mathStructures}), +defines a numerical type; e.g., short integer, double-precision +floating point, etc: + +\begin{datatype} +typedef enum { + PS_TYPE_S8, ///< Character + PS_TYPE_S16, ///< Short integer + PS_TYPE_S32, ///< Integer + PS_TYPE_S64, ///< Long integer + PS_TYPE_U8, ///< Unsigned character + PS_TYPE_U16, ///< Unsigned short integer + PS_TYPE_U32, ///< Unsigned integer + PS_TYPE_U64, ///< Unsigned long integer + PS_TYPE_F32, ///< Floating point + PS_TYPE_F64, ///< Double-precision floating point + PS_TYPE_C32, ///< Complex numbers consisting of floats + PS_TYPE_C64, ///< Complex numbers consisting of doubles + PS_TYPE_BOOL ///< Boolean value +} psElemType; +\end{datatype} + + +The second, primarily for use with the metadata +(\S\ref{sec:metadata}), defines a data structure; e.g., list, array, +FITS file: + +\begin{datatype} +typedef enum { ///< type of item.data is: + PS_DATA_S32 = PS_TYPE_S32, ///< psS32 + PS_DATA_F32 = PS_TYPE_F32, ///< psF32 + PS_DATA_F64 = PS_TYPE_F64, ///< psF64 + PS_DATA_BOOL = PS_TYPE_BOOL, ///< psBool + PS_DATA_STRING = 0x10000, ///< String (char *) + PS_DATA_ARRAY, ///< psArray + PS_DATA_BITSET, ///< psBitSet + PS_DATA_CELL, ///< psCell + PS_DATA_CHIP, ///< psChip + PS_DATA_CUBE, ///< psCube + PS_DATA_FITS, ///< psFits + PS_DATA_HASH, ///< psHash + PS_DATA_HISTOGRAM, ///< psHistogram + PS_DATA_IMAGE, ///< psImage + PS_DATA_KERNEL, ///< psKernel + PS_DATA_LIST, ///< psList + PS_DATA_LOOKUPTABLE, ///< psLookupTable + PS_DATA_METADATA, ///< psMetadata + PS_DATA_METADATAITEM, ///< psMetadataItem + PS_DATA_MINIMIZATION, ///< psMinimization + PS_DATA_PIXELS, ///< psPixels + PS_DATA_PLANE, ///< psPlane + PS_DATA_PLANEDISTORT, ///< psPlaneDistort + PS_DATA_PLANETRANSFORM, ///< psPlaneTransform + PS_DATA_POLYNOMIAL1D, ///< psPolynomial1D + PS_DATA_POLYNOMIAL2D, ///< psPolynomial2D + PS_DATA_POLYNOMIAL3D, ///< psPolynomial3D + PS_DATA_POLYNOMIAL4D, ///< psPolynomial4D + PS_DATA_PROJECTION, ///< psProjection + PS_DATA_READOUT, ///< psReadout + PS_DATA_REGION, ///< psRegion + PS_DATA_SCALAR, ///< psScalar + PS_DATA_SPHERE, ///< psSphere + PS_DATA_SPHERETRANSFORM, ///< psSphereTransform + PS_DATA_SPLINE1D, ///< psSpline1D + PS_DATA_STATS, ///< psStats + PS_DATA_TIME, ///< psTime + PS_DATA_VECTOR, ///< psVector + PS_DATA_UNKNOWN, ///< Other data of an unknown type + PS_DATA_METADATA_MULTI ///< Used internally for metadata; not a 'real' type +} psDataType; +\end{datatype} + +Here we have not included every type of structure used in PSLib, but +only those we expect will be frequently carried around in containers. +We include \code{PS_DATA_S32, PS_DATA_F32, PS_DATA_F64} and +\code{PS_DATA_BOOL} since the metadata use these, and we set them to +the same values as in \code{psElemType}. + +The other values are offset from these ``primitive'' types so that +they can be identified easily. A macro, +\code{PS_DATA_IS_PRIMITIVE(type)}, shall return \code{true} if the +type is one of the numerical data types (S32, F32, F64, bool). In +such a case, the data value is directly available from the metadata. +Otherwise, a pointer to the data is available. + +\code{PS_DATA_METADATA_MULTI} is used by the metadata, so the user +should not use this type. + +\subsubsection{Type checking} + Several of the collections contain data using a \code{void*} pointer. This makes it difficult to ensure that data coming off a collection is @@ -802,4 +894,7 @@ \begin{prototype} +psDataType psMemGetType(psPtr ptr); +\end{prototype} + bool psMemCheckArray(psPtr ptr); bool psMemCheckBitSet(psPtr ptr); @@ -842,8 +937,10 @@ \begin{prototype} -bool psMemCheckType(psType type, psPtr ptr); -\end{prototype} - -\tbd{Need to define psType.} +bool psMemCheckType(psDataType type, psPtr ptr); +\end{prototype} + +The reason for having functions that check the type instead of +returning the type is that the check is quick and the result is clean, +while returning the type involves descending through a case statement. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -2072,5 +2169,5 @@ const psS32 id; ///< unique ID for this item char *name; ///< Name of item - psMetadataType type; ///< type of this item + psDataType type; ///< type of this item const union { psS32 S32; ///< integer data @@ -2094,32 +2191,5 @@ \code{comment}. The \code{type} entry specifies how to interpret the type of the data being represented, given by the enumerated type -\code{psMetadataType}: -% -\filbreak -\begin{datatype} -typedef enum { ///< type of item.data is: - PS_META_S32 = PS_TYPE_S32, ///< psS32 primitive data. - PS_META_F32 = PS_TYPE_F32, ///< psF32 primitive data. - PS_META_F64 = PS_TYPE_F64, ///< psF64 primitive data. - PS_META_BOOL = PS_TYPE_BOOL, ///< psBool primitive data. - PS_META_LIST = 0x10000, ///< List data (Stored as item.data.list). - PS_META_STR, ///< String data (Stored as item.data.V). - PS_META_META, ///< Metadata (Stored as item.data.md). - PS_META_VEC, ///< Vector data (Stored as item.data.V). - PS_META_IMG, ///< Image data (Stored as item.data.V). - PS_META_HASH, ///< Hash data (Stored as item.data.V). - PS_META_LOOKUPTABLE, ///< Lookup table data (Stored as item.data.V). - PS_META_JPEG, ///< JPEG data (Stored as item.data.V). - PS_META_PNG, ///< PNG data (Stored as item.data.V). - PS_META_ASTROM, ///< Astrometric coefficients (Stored as item.data.V). - PS_META_TIME, ///< psTime object (Stored as item.data.V). - PS_META_UNKNOWN, ///< Other data (Stored as item.data.V). - PS_META_MULTI ///< Used internally, do not create a metadata item of this type. -} psMetadataType; -\end{datatype} -The macro \code{PS_META_IS_PRIMITIVE(psMetadataType.type)} returns -true if the type is one of the primitive data types (S32, F64, etc). -In such a case, the data value is directly available. Otherwise, a -pointer to the data is available. +\code{psDataType}. A collection of metadata is represented by the \code{psMetadata} structure: @@ -2146,8 +2216,8 @@ \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_MULTI}, +with the value of \code{psDataType} set to \code{PS_DATA_METADATA_MULTI}, and the \code{psMetadataItem.data} element pointing to a \code{psList} containing the actual entries. If \code{psMetadataItemAlloc} is -called with the type set to \code{PS_META_MULTI}, such a repeated key +called with the type set to \code{PS_DATA_METADATA_MULTI}, such a repeated key is created. In this case, the data value passed to \code{psMetadataItemAlloc} (the quantity in ellipsis) must be @@ -2163,5 +2233,5 @@ psMetadataItem* psMetadataItemAllocS32(const char* name, const char* comment, psS32 value); psMetadataItem* psMetadataItemAllocBool(const char* name, const char* comment, bool value); -psMetadataItem* psMetadataItemAllocPtr(const char* name, psMetadataType type, const char* comment, psPtr value); +psMetadataItem* psMetadataItemAllocPtr(const char* name, psDataType type, const char* comment, psPtr value); \end{prototype} @@ -2178,6 +2248,6 @@ \begin{prototype} -psMetadataItem *psMetadataItemAlloc(const char *name, psMetadataType type, const char *comment, ...); -psMetadataItem *psMetadataItemAllocV(const char *name, psMetadataType type, const char *comment, va_list list); +psMetadataItem *psMetadataItemAlloc(const char *name, psDataType type, const char *comment, ...); +psMetadataItem *psMetadataItemAllocV(const char *name, psDataType type, const char *comment, va_list list); \end{prototype} @@ -2215,11 +2285,11 @@ the \code{psList}. The entry \code{mode} for \code{psMetadataAddItem} is a bit mask constructed by OR-ing the allowed option flags (eg, -\code{PS_META_REPLACE}) which specify minor variations on the +\code{PS_DATA_REPLACE}) which specify minor variations on the behavior. The \code{format} entry, which specifies both the metadata type and the optional flags, is constructed by bit-wise OR-ing the -appropriate \code{psMetadataType} and allowed option flags. Care +appropriate \code{psDataType} and allowed option flags. Care should be taken not to leak memory when appending an item for which the key already exists in the metadata (and is not -\code{PS_META_MULTI}). +\code{PS_DATA_METADATA_MULTI}). % @@ -2235,10 +2305,10 @@ The functions above take option flags which modify the behavior when metadata items are added to the metadata list. These flags must be -bit-exclusive of those used above for the \code{psMetadataTypes}. The +bit-exclusive of those used above for the \code{psDataTypes}. The flags have the following meanings: \code{PS_META_DEFAULT}: This is the zero bit mask, to allow the default behavior for \code{psMetadataAddItem} above. If this is OR-ed -with a \code{psMetadataType}, the result is as if no OR-ing took +with a \code{psDataType}, the result is as if no OR-ing took place. @@ -2248,16 +2318,18 @@ \code{PS_META_DUPLICATE_OK}: Allow the new metadata item key to be a -duplicate (ie, \code{PS_META_MULTI}). If an existing item with the -same key is already \code{PS_META_MULTI}, the new item is added to the -\code{PS_META_MULTI} list. If the existing item is not -\code{PS_META_MULTI}, a \code{PS_META_MULTI} list is created to -contain both the existing item and the new item. The original entry's -location on the psMetadata.list must be maintained. - -\code{PS_META_NULL}: Indicates that \code{psMetadataItem.data} should be -ignored and that the the current value is ``NULL'' or undefined. The -\code{psMetadataItem} must have a proper \code{type} set and it's \code{data} -field shall have a valid value. e.g. A \code{type} of \code{PS_META_STR} would -require that 's \code{data} is set to \code{NULL}. +duplicate (ie, \code{PS_DATA_METADATA_MULTI}). If an existing item +with the same key is already \code{PS_DATA_METADATA_MULTI}, the new +item is added to the \code{PS_DATA_METADATA_MULTI} list. If the +existing item is not \code{PS_DATA_METADATA_MULTI}, a +\code{PS_DATA_METADATA_MULTI} list is created to contain both the +existing item and the new item. The original entry's location on the +psMetadata.list must be maintained. + +\code{PS_META_NULL}: Indicates that \code{psMetadataItem.data} should +be ignored and that the the current value is ``NULL'' or undefined. +The \code{psMetadataItem} must have a proper \code{type} set and it's +\code{data} field shall have a valid value. e.g. A \code{type} of +\code{PS_DATA_STR} would require that its \code{data} is set to +\code{NULL}. There are several of cases to handle for duplication of an existing @@ -2265,16 +2337,18 @@ must also be handled: -If the new key already exists, but is not \code{PS_META_MULTI}, and -the new item is not flagged as either \code{PS_META_DUPLICATE_OK} or -\code{PS_META_REPLACE}, an error is raised. +If the new key already exists, but is not +\code{PS_DATA_METADATA_MULTI}, and the new item is not flagged as +either \code{PS_META_DUPLICATE_OK} or \code{PS_META_REPLACE}, an error +is raised. If the new key already exists, and the existing item is -\code{PS_META_MULTI}, the new item is added to the MULTI list. Note -that if the new item is also of type \code{PS_META_MULTI}, no action -is taken, but a successful exit status is returned (the action of -adding a \code{PS_META_MULTI} item to the metadata is equivalent to -setting that key to be tagged as \code{PS_META_MULTI}. If it is -{\em already} \code{PS_META_MULTI}, this effect has already been -achieved). +\code{PS_DATA_METADATA_MULTI}, the new item is added to the MULTI +list. Note that if the new item is also of type +\code{PS_DATA_METADATA_MULTI}, no action is taken, but a successful +exit status is returned (the action of adding a +\code{PS_DATA_METADATA_MULTI} item to the metadata is equivalent to +setting that key to be tagged as \code{PS_DATA_METADATA_MULTI}. If it +is {\em already} \code{PS_DATA_METADATA_MULTI}, this effect has +already been achieved). An example of code to use these metadata APIs to generate the @@ -2284,29 +2358,29 @@ md = psMetadataAlloc(); -psMetadataAdd(md, PS_LIST_TAIL, "SIMPLE", PS_META_BOOL, "basic fits", TRUE); -psMetadataAdd(md, PS_LIST_TAIL, "BLANK", PS_META_S32, "invalid pixel data", -32768); -psMetadataAdd(md, PS_LIST_TAIL, "DATE-OBS", PS_META_STR, "observing date UT", " 2004-6-16"); -psMetadataAdd(md, PS_LIST_TAIL, "COMMENT", PS_META_LIST, "head of comment block", NULL); -psMetadataAdd(md, PS_LIST_TAIL, "COMMENT", PS_META_STR, "", "DATA"); -psMetadataAdd(md, PS_LIST_TAIL, "COMMENT", PS_META_STR, "", "PARAMS"); -psMetadataAdd(md, PS_LIST_TAIL, "EXPTIME", PS_META_F32, "exposure time (sec)", 1.05); -psMetadataAdd(md, PS_LIST_TAIL, "COMMENT", PS_META_STR, "", "FOO"); +psMetadataAdd(md, PS_LIST_TAIL, "SIMPLE", PS_DATA_BOOL, "basic fits", TRUE); +psMetadataAdd(md, PS_LIST_TAIL, "BLANK", PS_DATA_S32, "invalid pixel data", -32768); +psMetadataAdd(md, PS_LIST_TAIL, "DATE-OBS", PS_DATA_STR, "observing date UT", " 2004-6-16"); +psMetadataAdd(md, PS_LIST_TAIL, "COMMENT", PS_DATA_LIST, "head of comment block", NULL); +psMetadataAdd(md, PS_LIST_TAIL, "COMMENT", PS_DATA_STR, "", "DATA"); +psMetadataAdd(md, PS_LIST_TAIL, "COMMENT", PS_DATA_STR, "", "PARAMS"); +psMetadataAdd(md, PS_LIST_TAIL, "EXPTIME", PS_DATA_F32, "exposure time (sec)", 1.05); +psMetadataAdd(md, PS_LIST_TAIL, "COMMENT", PS_DATA_STR, "", "FOO"); cell = psMetadataAlloc(); -psMetadataAdd(cell, PS_LIST_TAIL, "EXTNAME", PS_META_STR, "", "CCD00"); -psMetadataAdd(cell, PS_LIST_TAIL, "BIASNAME", PS_META_STR, "", "BSEC-00"); -psMetadataAdd(cell, PS_LIST_TAIL, "CHIP", PS_META_STR, "", "CHIP.00"); -psMetadataAdd(md, PS_LIST_TAIL, "CELL.00", PS_META_META, "", cell); +psMetadataAdd(cell, PS_LIST_TAIL, "EXTNAME", PS_DATA_STR, "", "CCD00"); +psMetadataAdd(cell, PS_LIST_TAIL, "BIASNAME", PS_DATA_STR, "", "BSEC-00"); +psMetadataAdd(cell, PS_LIST_TAIL, "CHIP", PS_DATA_STR, "", "CHIP.00"); +psMetadataAdd(md, PS_LIST_TAIL, "CELL.00", PS_DATA_META, "", cell); cell = psMetadataAlloc(); -psMetadataAdd(cell, PS_LIST_TAIL, "EXTNAME", PS_META_STR, "", "CCD01"); -psMetadataAdd(cell, PS_LIST_TAIL, "BIASNAME", PS_META_STR, "", "BSEC-01"); -psMetadataAdd(cell, PS_LIST_TAIL, "CHIP", PS_META_STR, "", "CHIP.01"); -psMetadataAdd(md, PS_LIST_TAIL, "CELL.01", PS_META_META, "", cell); +psMetadataAdd(cell, PS_LIST_TAIL, "EXTNAME", PS_DATA_STR, "", "CCD01"); +psMetadataAdd(cell, PS_LIST_TAIL, "BIASNAME", PS_DATA_STR, "", "BSEC-01"); +psMetadataAdd(cell, PS_LIST_TAIL, "CHIP", PS_DATA_STR, "", "CHIP.01"); +psMetadataAdd(md, PS_LIST_TAIL, "CELL.01", PS_DATA_META, "", cell); \end{verbatim} The following code shows how to use the APIs to replace one of these values: \begin{verbatim} -psMetadataAdd(md, PS_LIST_TAIL, "EXPTIME", PS_META_F32 | PS_REPLACE, "new exposure time (sec)", 2.05); +psMetadataAdd(md, PS_LIST_TAIL, "EXPTIME", PS_DATA_F32 | PS_REPLACE, "new exposure time (sec)", 2.05); \end{verbatim} @@ -2320,5 +2394,5 @@ bool psMetadataAddF64(psMetadata* md, psS32 location, const char* name, const char* comment, psF64 value); bool psMetadataAddBool(psMetadata* md, psS32 location, const char* name, const char* comment, bool value); -bool psMetadataAddPtr(psMetadata* md, psS32 location, const char* name, psMetadataType type, +bool psMetadataAddPtr(psMetadata* md, psS32 location, const char* name, psDataType type, const char* comment, psPtr value); \end{prototype} @@ -2383,5 +2457,5 @@ with \code{IPP.machines.detector}. The iterator should iterate over every item in the metadata list, even those that are contained in a -\code{PS_META_LIST}. The value \code{iterator} specifies the iterator +\code{PS_DATA_LIST}. The value \code{iterator} specifies the iterator to be used. In setting the iterator, the position of the iterator is defined by \code{location}, which follows the conventions of the @@ -2586,5 +2660,5 @@ should construct a \code{psMetadata} container and fill it with \code{psMetadataItems} having the names \code{EXTNAME, BIASSEC, CHIP}, -with type \code{PS_META_STR}, but data allocated. When it next +with type \code{PS_DATA_STR}, but data allocated. When it next encounters an entry of type \code{CELL}, it should then use the given name (e.g., \code{CELL.00}) for the \code{psMetadataItem}, and copy @@ -2766,4 +2840,5 @@ \section{Mathematical Structures} +\label{sec:mathStructures} Throughout PSLib, we require a variety of structures which correspond @@ -2798,14 +2873,12 @@ determine the type of the data on the basis of the data. Supported data types must be defined by a structure in which -the first element is always of type \code{psType}: +the first element is always of type \code{psMathType}: \begin{datatype} typedef struct { psDimen dimen; ///< The dimensionality - psElemType type; ///< The type -} psType; -\end{datatype} -where \code{psDimen dimen} defines the dimensionality of the data and -\code{psElemType type} defines the data type of each element. These -two variable types are defined as: + psElemType type; ///< The type +} psMathType; +\end{datatype} +where \code{psDimen dimen} defines the dimensionality of the data: \begin{datatype} typedef enum { @@ -2817,23 +2890,8 @@ } psDimen; \end{datatype} -and -\begin{datatype} -typedef enum { - PS_TYPE_S8, ///< Character - PS_TYPE_S16, ///< Short integer - PS_TYPE_S32, ///< Integer - PS_TYPE_S64, ///< Long integer - PS_TYPE_U8, ///< Unsigned character - PS_TYPE_U16, ///< Unsigned short integer - PS_TYPE_U32, ///< Unsigned integer - PS_TYPE_U64, ///< Unsigned long integer - PS_TYPE_F32, ///< Floating point - PS_TYPE_F64, ///< Double-precision floating point - PS_TYPE_C32, ///< Complex numbers consisting of floats - PS_TYPE_C64, ///< Complex numbers consisting of doubles - PS_TYPE_BOOL ///< Boolean value -} psElemType; -\end{datatype} -We discuss the application of \code{psType} in more detail in +\code{psElemType type}, which defines the data type of each element, has +already been defined + +We discuss the application of \code{psMathType} in more detail in section~\ref{sec:arithmetic}. @@ -2849,5 +2907,5 @@ \begin{datatype} typedef struct { - psType type; ///< data type information + psMathType type; ///< data type information } psMath; \end{datatype} @@ -2863,5 +2921,5 @@ \begin{datatype} typedef struct { - psType type; ///< data type information + psMathType type; ///< data type information union { psS8 S8; ///< bye value entry @@ -2882,6 +2940,6 @@ psScalar *psScalarCopy(const psScalar *value); \end{prototype} -The first creates a \code{psType}-ed structure from a constant value, -casting it as appropriate based on the \code{type}. The second +The first creates a \code{psMathType}-ed structure from a constant +value, casting it as appropriate based on the \code{type}. The second copies the provided \code{psScalar} value. This latter function is necessary to keep a copy of an existing \code{psScalar} value, since @@ -2900,5 +2958,5 @@ \begin{datatype} typedef struct { - psType type; ///< vector data type and dimension + psMathType type; ///< vector data type and dimension long n; ///< size of vector const long nalloc; ///< allocated data block @@ -2926,8 +2984,8 @@ union \code{data} which consists of pointers to each of the defined primitive data types. Note the parallelism in the names of the types, -union elements, and the psElemType names. This parallelism allows us -to use automatic construction mechanisms effectively. The data type -is defined by the first element, \code{psType}. The structure is -associated with a constructor and reallocator: +union elements, and the \code{psElemType} names. This parallelism +allows us to use automatic construction mechanisms effectively. The +data type is defined by the first element, \code{psMathType}. The +structure is associated with a constructor and reallocator: % \begin{prototype} @@ -3012,5 +3070,5 @@ \begin{datatype} typedef struct psImage { - psType type; ///< image data type and dimension + psMathType type; ///< image data type and dimension const psU32 numCols; ///< Number of columns in image const psU32 numRows; ///< Number of rows in image. @@ -3039,22 +3097,22 @@ This structure represents an image consisting of a 2-D array of -pixels. The size of this array is given by the elements \code{(numRows, -numCols)}. The data type of the pixel is defined in the \code{psType -type} entry (specifically, the \code{psElemType} member, \code{type}; -see \ref{sec:arithmetic}). (n.b. that for FITS images, these values -are restricted to the datatypes equivalent to the valid BITPIX values -8, 16, 32, -32, -64). The image represented in the data structure may -represent a subset of the pixels in a complete array, in which case -the image is considered to be the child of that parent array. The -offset of the \code{(0,0)} pixel in this array relative to the parent -array is given by the elements \code{(col0,row0)}: \code{col0} is the -starting column number in the parent image while \code{row0} is the -starting row number. The structure may include references to -subrasters (\code{children}) 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 -is allocated in a contiguous block. We define the following -supporting functions, which are valid for data types \code{psS8, -psS16, psU8, psU16, psF32, psF64, psC32, psC64}. +pixels. The size of this array is given by the elements +\code{(numRows, numCols)}. The data type of the pixel is defined in +the \code{psMathType type} entry (specifically, the +\code{psElemType} member, \code{type}; see \ref{sec:arithmetic}). +(n.b. that for FITS images, these values are restricted to the +datatypes equivalent to the valid BITPIX values 8, 16, 32, -32, -64). +The image represented in the data structure may represent a subset of +the pixels in a complete array, in which case the image is considered +to be the child of that parent array. The offset of the \code{(0,0)} +pixel in this array relative to the parent array is given by the +elements \code{(col0,row0)}: \code{col0} is the starting column number +in the parent image while \code{row0} is the starting row number. The +structure may include references to subrasters (\code{children}) +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 is allocated in a contiguous block. We define +the following supporting functions, which are valid for data types +\code{psS8, psS16, psU8, psU16, psF32, psF64, psC32, psC64}. \begin{prototype} @@ -3073,5 +3131,5 @@ psU32 numCols, ///< the desired number of columns in image psU32 numRows, ///< the desired number of rows in image - const psElemType type ///< the desired datatype of the image + const psElemType type ///< the desired datatype of the image ); \end{prototype} @@ -3239,7 +3297,7 @@ \begin{datatype} - typedef struct { - MYSQL *mysql; - } psDB; +typedef struct { + MYSQL *mysql; +} psDB; \end{datatype} @@ -3247,22 +3305,13 @@ \begin{prototype} - // wraps mysql_init() & mysql_real_connect() - psDB *psDBInit(const char *host, const char *user, const char *passwd, const char *dbname); - - // wraps mysql_close() - void psDBCleanup(psDB *dbh); - - // wraps mysql_create_db() - bool psDBCreate(psDB *dbh, const char *dbname); - - // wraps mysql_select_db() - bool psDBChange(psDB *dbh, const char *dbname); - - // wraps mysql_drop_db() - bool psDBDrop(psDB *dbh, const char *dbname); -\end{prototype} - -For MySQL support, \code{psDBInit()} wraps \code{mysql_init()} and -\code{mysql_real_connect()} in order to initialize a psDB structure and +psDB *psDBInit(const char *host, const char *user, const char *passwd, const char *dbname); +void psDBCleanup(psDB *dbh); +bool psDBCreate(psDB *dbh, const char *dbname); +bool psDBChange(psDB *dbh, const char *dbname); +bool psDBDrop(psDB *dbh, const char *dbname); +\end{prototype} + +For MySQL support, \code{psDBInit} wraps \code{mysql_init} and +\code{mysql_real_connect} in order to initialize a psDB structure and establish a database connection. A null pointer should be returned on failure. @@ -3272,4 +3321,9 @@ would be ignored while \code{dbname} would specify the path to the SQLite db file. + +\code{psDBCleanup} shall wrap \code{mysql_close}. \code{psDBCreate} +shall wrap \code{mysql_create_db}. \code{psDBChange} shall wrap +\code{mysql_select_db}. \code{psDBDrop} shall wrap +\code{mysql_drop_db}. \subsubsection{Interacting with Database Tables} @@ -3287,5 +3341,5 @@ \begin{prototype} - bool psDBCreateTable(psDB *dbh, const char *tableName, const psMetadata *md); +bool psDBCreateTable(psDB *dbh, const char *tableName, const psMetadata *md); \end{prototype} @@ -3297,11 +3351,11 @@ given by the \code{psMetadataItem.type} entry. A lookup table should be used to convert from PSLib types into MySQL compatible SQL data -types. For example, a \code{PS_META_STR} would map to an SQL99 -varchar. If the value of \code{type} is \code{PS_META_STR} then the +types. For example, a \code{PS_DATA_STR} would map to an SQL99 +varchar. If the value of \code{type} is \code{PS_DATA_STR} then the \code{psMetadataItem.data} element is set to a string with the length for the field written as a text string. The value of the \code{psMetadataItem.data} element is unused for the -\code{PS_META_PRIMITIVE} types. Other metadata types beyond -\code{PS_META_STR} and \code{PS_META_PRIMITIVE} are not allowed in a +\code{PS_DATA_PRIMITIVE} types. Other metadata types beyond +\code{PS_DATA_STR} and \code{PS_DATA_PRIMITIVE} are not allowed in a table definition metadata collection. @@ -3314,5 +3368,5 @@ \begin{prototype} - bool psDBDropTable(psDB *dbh, const char *tableName); +bool psDBDropTable(psDB *dbh, const char *tableName); \end{prototype} @@ -3320,5 +3374,5 @@ \begin{prototype} - bool p_psDBRunQuery(psDB *dbh, const char *query); +bool p_psDBRunQuery(psDB *dbh, const char *query); \end{prototype} @@ -3328,6 +3382,7 @@ \begin{prototype} - psArray *psDBSelectColumn(psDB *dbh, const char *tableName, const char *col, unsigned long limit); - psVector *psDBSelectColumnNum(psDB *dbh, const char *tableName, const char *col, psElemType type, unsigned long limit); +psArray *psDBSelectColumn(psDB *dbh, const char *tableName, const char *col, unsigned long limit); +psVector *psDBSelectColumnNum(psDB *dbh, const char *tableName, const char *col, + psElemType type, unsigned long limit); \end{prototype} @@ -3340,5 +3395,5 @@ \begin{prototype} - psArray *psDBSelectRows(psDB *dbh, const char *tableName, const psMetadata *where, unsigned long limit); +psArray *psDBSelectRows(psDB *dbh, const char *tableName, const psMetadata *where, unsigned long limit); \end{prototype} @@ -3353,5 +3408,5 @@ \begin{prototype} - bool psDBInsertOneRow(psDB *dbh, const char *tableName, const psMetadata *row); +bool psDBInsertOneRow(psDB *dbh, const char *tableName, const psMetadata *row); \end{prototype} @@ -3361,5 +3416,5 @@ \begin{prototype} - bool psDBInsertRows(psDB *dbh, const char *tableName, const psArray *rowSet); +bool psDBInsertRows(psDB *dbh, const char *tableName, const psArray *rowSet); \end{prototype} @@ -3368,5 +3423,5 @@ \begin{prototype} - psArray *psDBDumpRows(psDB *dbh, const char *tableName); +psArray *psDBDumpRows(psDB *dbh, const char *tableName); \end{prototype} @@ -3374,5 +3429,5 @@ \begin{prototype} - psMetadata *psDBDumpCols(psDB *dbh, const char *tableName); +psMetadata *psDBDumpCols(psDB *dbh, const char *tableName); \end{prototype} @@ -3382,5 +3437,6 @@ \begin{prototype} -psS64 psDBUpdateRows(psDB *dbh, const char *tableName, const psMetadata *where, const psMetadata *values); +psS64 psDBUpdateRows(psDB *dbh, const char *tableName, const psMetadata *where, + const psMetadata *values); \end{prototype} @@ -3393,5 +3449,5 @@ \begin{prototype} - psS64 psDBDeleteRows(psDB *dbh, const char *tableName, const psMetadata *where); +psS64 psDBDeleteRows(psDB *dbh, const char *tableName, const psMetadata *where); \end{prototype} @@ -3922,5 +3978,5 @@ typedef struct { psPolynomialType type; ///< Polynomial type - psElemType ctype; ///< Polynomial precision + psElemType ctype; ///< Polynomial precision int n; ///< Number of terms union { @@ -3940,13 +3996,13 @@ typedef struct { psPolynomialType type; ///< Polynomial type - psElemType ctype; ///< Polynomial precision + psElemType ctype; ///< Polynomial precision int nX, nY; ///< Number of terms in x and y union { - psF32 **F32; ///< Coefficients - psF64 **F64; ///< Coefficients + psF32 **F32; ///< Coefficients + psF64 **F64; ///< Coefficients } coeff; union { - psF32 **F32; ///< Error in coefficients - psF64 **F64; ///< Error in coefficients + psF32 **F32; ///< Error in coefficients + psF64 **F64; ///< Error in coefficients } coeffErr; char *mask; ///< Coefficient mask @@ -4887,11 +4943,11 @@ \begin{prototype} -psType *psBinaryOp(psPtr out, const psPtr in1, const char *op, const psPtr in2); -psType *psUnaryOp(psPtr out, const psPtr in, const char *op); +psMathType *psBinaryOp(psPtr out, const psPtr in1, const char *op, const psPtr in2); +psMathType *psUnaryOp(psPtr out, const psPtr in, const char *op); \end{prototype} These functions determine the type of the operands on the basis of -their \code{psType} elements, which always are the first elements. +their \code{psMathType} elements, which always are the first elements. Note that these functions return a pointer to the appropriate type for -the operation. Since the result may be cast to \code{psType}, the +the operation. Since the result may be cast to \code{psMathType}, the resulting type may be determined by examining the return value. It is expected that the implementation of these functions will employ