Index: /trunk/doc/pslib/ChangeLogSDRS.tex =================================================================== --- /trunk/doc/pslib/ChangeLogSDRS.tex (revision 3774) +++ /trunk/doc/pslib/ChangeLogSDRS.tex (revision 3775) @@ -1,3 +1,3 @@ -%%% $Id: ChangeLogSDRS.tex,v 1.91 2005-04-27 19:59:03 eugene Exp $ +%%% $Id: ChangeLogSDRS.tex,v 1.92 2005-04-27 21:32:24 eugene Exp $ \subsection{Changes from version 00 to version 01} @@ -560,3 +560,18 @@ \item added \code{psVectorExtend} function \item changed inputs to \code{psImageSlice} to use \code{psRegion} -\end{itemize} + +\item changes involving \code{psRegion} +\begin{itemize} + \item moved Image Regions section to beginning of Image Operations + \item dropped psImageSubsection (redundant now) + + \item changed the following functions to use psRegion: + psImageSubset, psImageTrim, psImageSlice, psImageCut + + \item added clarification to meaning of psRegion x0,x1,y0,y1 values. +\end{itemize} + +\item removed psMetadata.ptype as per bug 313, dropped reference in psDB section. +\item clarified the discussion of duplicate keys and the option flags in \code{psMetadata} + +\end{itemize} Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 3774) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 3775) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.209 2005-04-27 20:30:42 eugene Exp $ +%%% $Id: psLibSDRS.tex,v 1.210 2005-04-27 21:32:24 eugene Exp $ \documentclass[panstarrs,spec]{panstarrs} @@ -1884,5 +1884,5 @@ psLookupTable *psLookupTableAlloc(const char *filename, ///< File from which to read const char *format ///< scanf-like format string - int indexCol ///< Column of the index vector (starting at zero) + int indexCol ///< Column of the index vector (starting at zero) ); \end{verbatim} @@ -2564,5 +2564,5 @@ \end{verbatim} -Then \code{psMinimizePowell} shall mimimize the specified function, +Then \code{psMinimizePowell} shall minimize the specified function, \code{func}, using the Powell method: @@ -2631,5 +2631,5 @@ psSpline1D *psVectorFitSpline1D(const psVector *x, const psVector *y - int nKnots); + int nKnots); \end{verbatim} \code{psVectorFitSpline1D} shall return the spline that best fits the @@ -2684,5 +2684,5 @@ the value is added to the image dimensions ($Nx + x1$). Thus a region \code{[0:0,0:0]} refers to the full image array, while -\code{[0:-10,0:-20]} trims the last 10 colums and the last 20 rows. +\code{[0:-10,0:-20]} trims the last 10 columns and the last 20 rows. \subsubsection{Image Structure Manipulation} @@ -2746,12 +2746,12 @@ psVector *psImageSlice(psVector *out, psVector *coords, - const psImage *input, + const psImage *input, const psImage *mask, - unsigned int maskVal, - psRegion region, - psImageCutDirection direction, - const psStats *stats); -\end{verbatim} -Extract pixels from rectlinear region to a vector (array of floats). + unsigned int maskVal, + psRegion region, + psImageCutDirection direction, + const psStats *stats); +\end{verbatim} +Extract pixels from rectilinear region to a vector (array of floats). The output vector contains either \code{region.x1-region.x0} or \code{region.y1-region.y0} elements, based on the value of the @@ -2784,5 +2784,5 @@ const psImage *mask, unsigned int maskVal, - psRegion region, + psRegion region, unsigned int nSamples, psImageInterpolateMode mode); @@ -2926,12 +2926,12 @@ psImage *psImageTransform(psImage *output, psArray **blankPixels, - const psImage *input, + const psImage *input, const psImage *inputMask, - int inputMaskVal, - const psPlaneTransform *outToIn, - const psRegion region, - const psPixels *pixels, - psImageInterpolateMode mode, - double exposedValue); + int inputMaskVal, + const psPlaneTransform *outToIn, + const psRegion region, + const psPixels *pixels, + psImageInterpolateMode mode, + double exposedValue); \end{verbatim} Transform the \code{input} image according the supplied @@ -3125,6 +3125,6 @@ \begin{verbatim} typedef struct { - int x; // x coordinate - int y; // y coordinate + int x; // x coordinate + int y; // y coordinate } psPixelCoord; @@ -3132,5 +3132,5 @@ int n; // Number in use const int nalloc; // Number allocated - psPixelCoord *data; // The pixel coordinates + psPixelCoord *data; // The pixel coordinates } psPixels; \end{verbatim} @@ -3142,5 +3142,5 @@ \code{psPixelsAlloc} and \code{psPixelsRealloc} provide dynamic -allocation and reallocation in a manner analagous to those provided +allocation and reallocation in a manner analogous to those provided by \code{psVectorAlloc} and \code{psVectorRealloc}. @@ -3163,5 +3163,5 @@ coordinates in the \code{mask} that match the \code{maskVal}. The \code{out} pixel list shall be modified if supplied, or allocated and -returned if \code{NULL}. In hte event that \code{mask} is +returned if \code{NULL}. In the event that \code{mask} is \code{NULL}, the function shall generate an error and return \code{NULL}. @@ -3355,5 +3355,5 @@ Finally, we specify two functions to convert between matrices and vectors. This allows the use of vectors in matrix arithmetic, since a -vector can be converted to a matrix, utilised, and the result can be +vector can be converted to a matrix, utilized, and the result can be converted back to a vector if required. This function is specified for data types \code{psF32, psF64}. Input and output data types @@ -3368,5 +3368,5 @@ \subsection{(Fast) Fourier Transforms} -We require the ability to calculate the (fast) fourier transforms of +We require the ability to calculate the (fast) Fourier transforms of floating-point one-dimensional vectors and two-dimensional images. We expect that these will be implemented through wrapping an external @@ -3401,5 +3401,5 @@ We also specify the additional utility functions -\code{psVectorConjuagte} and \code{psVectorPowerSpectrum} which +\code{psVectorConjugate} and \code{psVectorPowerSpectrum} which construct the complex conjugate (\code{psC32}) and the magnitude (\code{psF32}) vectors of the input complex vector (\code{psC32}). @@ -3558,5 +3558,5 @@ We define a \code{psRandom} type, which will allow us to carry around pre-computed random numbers, if required. For the time being, we only -specify a single randon number generator (RNG) in \code{psRandomType} +specify a single random number generator (RNG) in \code{psRandomType} (that provided by \code{gsl_rng_taus}), but we leave this open to expansion in the future, depending upon user requirements. @@ -3724,15 +3724,14 @@ \begin{verbatim} typedef struct { - int id; ///< unique ID for this item + const psS32 id; ///< unique ID for this item char *name; ///< Name of item psMetadataType type; ///< type of this item - psElemType ptype; ///< primitive data type const union { psS32 S32; ///< integer data psF32 F32; ///< floating-point data psF64 F64; ///< double-precision data - void *V; ///< other type psList *list; ///< psList entry psMetadata *md; ///< psMetadata entry + psPtr V; ///< other type } data; ///< value of metadata char *comment; ///< optional comment ("", not NULL) @@ -3753,20 +3752,26 @@ \filbreak \begin{verbatim} -typedef enum { ///< type of item.data is: - PS_META_PRIMITIVE, ///< primitive type: use item.ptype - PS_META_LIST, ///< psList; use item.data.list (used for non-unique data) - PS_META_META, ///< psMetadata: use item.data.list - PS_META_STR, ///< string (item.data.V) - PS_META_MATH, ///< psScalar, psVector, psImage (item.data.V) - PS_META_JPEG, ///< JPEG (item.data) - PS_META_PNG, ///< PNG (item.data) - PS_META_ASTROM, ///< astrometric coefficients (item.data) - PS_META_TIME, ///< psTime (item.data.V) - PS_META_UNKNOWN, ///< other (item.data) - PS_META_NTYPE ///< Number of types; must be last +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_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_UNKNOWN, ///< Other data (Stored as item.data.V). + PS_META_MULTI ///< Used internally, do not create a metadata item of this type. } psMetadataType; \end{verbatim} -If the data is a PSLib primitive data value, the primitive data type -is given by the value of \code{ptype}. +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. A collection of metadata is represented by the \code{psMetadata} structure: @@ -3792,19 +3797,28 @@ \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_LIST}, +with the value of \code{psMetadataType} set to \code{PS_META_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_LIST}, 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_LIST}; in this case the data are added to the -corresponding \code{psMetadataItem.data} list. +called with the type set to \code{PS_META_MULTI}, such a repeated key +is created. In this case, the data value passed to +\code{psMetadataItemAlloc} (the quantity in ellipsis) must be +\code{NULL}. An empty \code{psMetadataItem} with the given keyword is +created to hold future entries of that keyword. \subsubsection{Metadata APIs} + +\begin{verbatim} +psMetadata *psMetadataAlloc(void); +\end{verbatim} + +The constructor for the collection of metadata, \code{psMetadata}, +simply returns an empty metadata container (employing the constructors +for the doubly-linked list and hash table). The destructor needs to +free each of the \code{psMetadataItem}s. + +\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} The allocator for \code{psMetadataItem} returns a full @@ -3821,15 +3835,10 @@ 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} - -The constructor for the collection of metadata, \code{psMetadata}, -simply returns an empty metadata container (employing the constructors -for the doubly-linked list and hash table). The destructor needs to -free each of the \code{psMetadataItem}s using \code{psMetadataItemFree}. -\begin{verbatim} -psMetadata *psMetadataAlloc(void); + +\begin{verbatim} +bool psMetadataAddItem(psMetadata *md, psMetadataItem *item, int location, int mode); +bool psMetadataAdd(psMetadata *md, int location, const char *name, int format, const char *comment, ...); +bool psMetadataAddV(psMetadata *md, int location, const char *name, int format, const char *comment, + va_list list); \end{verbatim} @@ -3846,17 +3855,19 @@ 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 specifies minor variations on the +\code{PS_META_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 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_LIST}). -% -\begin{verbatim} -bool psMetadataAddItem(psMetadata *md, psMetadataItem *item, int location, int mode); -bool psMetadataAdd(psMetadata *md, int location, const char *name, int format, const char *comment, ...); -bool psMetadataAddV(psMetadata *md, int location, const char *name, int format, const char *comment, - va_list list); +appropriate \code{psMetadataType} 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}). +% + +\begin{verbatim} +typedef enum { ///< option flags for psMetadata functions + PS_META_DEFAULT, ///< default behavior (0x0000) for use in mode above + PS_META_REPLACE, ///< allow entry to be replaced + PS_META_DUPLICATE_OK, ///< allow entry to be replaced +} psMetadataFlags; \end{verbatim} @@ -3871,16 +3882,32 @@ place. -\code{PS_META_REPLACE}: If the given metadata item exists in the -metadata list, and is not of type \code{PS_META_LIST} or -\code{PS_META_META} (ie, not a container type), then this entry is -allowed to replace the existing entry. If this mode bit is not set, a -duplicate (non-container-type) entry is an error. - -\begin{verbatim} -typedef enum { ///< option flags for psMetadata functions - PS_META_DEFAULT, ///< default behavior (0x0000) for use in mode above - PS_META_REPLACE, ///< allow entry to be replaced -} psMetadataFlags; -\end{verbatim} +\code{PS_META_REPLACE}: Replace an existing, unique entry. If the +given metadata item exists in the metadata collection, and is not of +type \code{PS_META_MULTI}, then the item replaces the existing entry. + +\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. + +There are several of cases to handle for duplication of an existing +key by a new key, some identified above. The following situations +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, 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). An example of code to use these metadata APIs to generate the @@ -4023,5 +4050,5 @@ formatted string. A \code{NULL} shall be returned on error. The \code{psMetadataConfigWrite} behaves the same as \code{psMetadataConfigFormat} -except that the string is writen out to \code{filename}. \code{false} is +except that the string is written out to \code{filename}. \code{false} is returned on failure. @@ -4079,5 +4106,5 @@ 1.23+4.56i in the future.} -\tbd{May add null, Not-a-Number (NaN), denormalized, underflow, overflow, +\tbd{May add null, Not-a-Number (NaN), de-normalized, underflow, overflow, and/or +/-infinity values for selected types.} @@ -4088,5 +4115,5 @@ in the configuration file as non-unique with a \code{MULTI} declaration. In the form \code{[keyword] MULTI}. No other data may be provided on this line, -though a comment, preceeded by the comment marker, is valid. A warning shall +though a comment, preceded by the comment marker, is valid. A warning shall be produced when a key which has not been specified to be non-unique is repeated; in this case, the former value shall be overwritten if @@ -4140,5 +4167,5 @@ We support a modest tree structure by defining a reserved keyword \code{TYPE}. Any line in the config file which starts with the word \code{TYPE} shall be -interpretted as defining a new valid type. The defined type name follows the +interpreted as defining a new valid type. The defined type name follows the word \code{TYPE}, and is in turn followed by an arbitrary number of words. These words are to be interpreted as the names of an embedded \code{psMetadata} @@ -4257,5 +4284,5 @@ The next pair of functions read from and write to a file descriptor. -The first converts the imcoming data to a complete \code{psXMLDoc} +The first converts the incoming data to a complete \code{psXMLDoc} (also in memory), the second writes the \code{psXMLDoc} to the file descriptor: @@ -4349,14 +4376,14 @@ collection represents a single table field. The name of the field is given by the name of the \code{psMetadataItem} and the data type is -give by the \code{psMetadataItem.type} and \code{psMetadataItem.ptype} -entries. 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 \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 table definition metadata collection. +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 +\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 +table definition metadata collection. Database indexes can be specified setting the \code{comment} field to @@ -4374,5 +4401,5 @@ \begin{verbatim} psArray *psDBSelectColumn(psDB *dbh, const char *tableName, const char *col, const psU64 limit); - psVector *psDBSelectColumnNum(psDB *dbh, const char *tableName, const char *col, psElemType pType, const psU64 limit); + psVector *psDBSelectColumnNum(psDB *dbh, const char *tableName, const char *col, psMetadataType type, const psU64 limit); \end{verbatim} @@ -4381,5 +4408,5 @@ the entire range is returned. The database response is processed and a \code{psArray} of strings is returned. The Num version of the function returns -the data in a \code{psVector}, data cast to \code{pType}. It returns an error +the data in a \code{psVector}, data cast to \code{type}. It returns an error (NULL) if the requested field is not a numerical type. @@ -4422,5 +4449,5 @@ \end{verbatim} -Fetch all columns, as either a psVector or a psArray depnding on whether or not +Fetch all columns, as either a psVector or a psArray depending on whether or not the column is numeric, and return them in a psMetadata structure where psMetadataItem.name contains the column's name. @@ -4596,5 +4623,5 @@ at by the \code{psFits} file pointer. The row number to be read is given by \code{row}. The result is returned as a \code{psMetadata} -collection with elements of the apporpriate types and keys +collection with elements of the appropriate types and keys corresponding to the table column names. The function must apply the needed byte-swapping on the data in the row based on the description @@ -4726,5 +4753,5 @@ \subsubsection{Constructors} -To allocate a new, initalized to zero, \code{psTime}: +To allocate a new, initialized to zero, \code{psTime}: \begin{verbatim} @@ -4748,7 +4775,7 @@ This function may be used to convert between the various \code{psTimeType} time representations. The \code{time} is modified and returned. Conversion between -all of the \emph{SI} length second systems should be implimented by first +all of the \emph{SI} length second systems should be implemented by first converting to TAI and then to the destination system. UT1 is a special case -for conversion as it uses variable length secounds. Conversation to UT1, via +for conversion as it uses variable length seconds. Conversation to UT1, via TAI, is allowed but conversion \emph{from} UT1 is currently forbidden. @@ -4790,5 +4817,5 @@ The following function accepts \code{PS_TIME_UTC} objects and -determines if the time is potentaly a leapsecond, returning +determines if the time is potentially a leapsecond, returning \code{TRUE} if so. @@ -4855,5 +4882,5 @@ Note that in both these functions the difference between two times is -the elapsed number of seconds, inclusing leap seconds. For example, +the elapsed number of seconds, including leap seconds. For example, if we add 30 seconds to 1998-12-31T23:59:45Z, the result is 1999-01-01T00:00:14Z, since a leap second was introduced at @@ -4873,5 +4900,5 @@ $x_p$ and $y_p$, may be determined from table lookups. Tables are available covering different time periods and with different time resolution, and so it -is important to be able to utilise multiple tables. Some tables may be found +is important to be able to utilize multiple tables. Some tables may be found at: @@ -5244,5 +5271,5 @@ Spherical rotations represent coordinate transformation in 3-D, as well as the effects of precession and nutation. We need spherical -rotatations to convert between ICRS, Galactic and Ecliptic +rotations to convert between ICRS, Galactic and Ecliptic coordinates, and to determine Alt-Az coordinates for sources. All of these basic spherical transformations represent rotations of the @@ -5296,5 +5323,5 @@ The following function combines two rotations, to produce a single -rotation which is the equivallent of applying the first rotation and +rotation which is the equivalent of applying the first rotation and then the second. The output rotation may be supplied, or will be allocated if \code{NULL}. @@ -5389,10 +5416,10 @@ Celestial Reference System (GCRS), which uses the earth barycenter as a reference. The transformation between these two includes the -abberation due to the Earth's velocity, the parallax of the object, +aberration due to the Earth's velocity, the parallax of the object, which depends on both the Earth's position and the distance to the object of interest, and the general relativistic correction for the bending of light as it approaches the Earth. -The next set of transformations compenstate for the 3-D rotation of +The next set of transformations compensate for the 3-D rotation of the Earth on various timescales, including the effects of precession, nutation, and simple solid-body rotation. These calculations can be @@ -5400,9 +5427,9 @@ precision. Since the Earth's rotation is constantly affected by stochastic processes (weather, earthquakes, etc), these conversions -are constantly modified by observations reported by authoratative +are constantly modified by observations reported by authoritative sources such as the US Naval Observatory. The target of this transformation is the International Terrestrial Reference System (ITRS), which is fixed with respect to the Earth's crust. This -transformation is subdivided into slow precesion and nutation +transformation is subdivided into slow precession and nutation (yielding the coordinate system CIP/CEO), followed by the Earth's rotation (yielding the coordinate system CIP/TEO), and finally @@ -5719,5 +5746,5 @@ \tbd{This section is to be deferred, and for now consists only of -placeholders, with no functional items.} +place holders, with no functional items.} Photometric observations are performed in an instrumental photometric