Changeset 3155

Timestamp:

Feb 7, 2005, 6:56:24 PM (21 years ago)

Author:

eugene

Message:

bugzilla changes (psMetadata iterators, pmObject stuff)

Location:

trunk/doc

Files:

• modules/ChangeLogSDRS.tex (modified) (2 diffs)
• modules/ModulesSDRS.tex (modified) (16 diffs)
• pslib/ChangeLogSDRS.tex (modified) (2 diffs)
• pslib/psLibSDRS.tex (modified) (5 diffs)

trunk/doc/modules/ChangeLogSDRS.tex

@@ -1 @@
-%%% $Id: ChangeLogSDRS.tex,v 1.12 2005-01-24 21:56:28 price Exp $
+%%% $Id: ChangeLogSDRS.tex,v 1.13 2005-02-08 04:56:24 eugene Exp $
 
 \subsection{Changes from version 00 to version 01}
@@ -42 +42 @@
 
 \begin{itemize}
+\item changed entries of the form psXXX to pmXXX (object section)
+\item added enum psSourceType
 \item Specified appropriate image types for the phase 2 modules (bug 258).
 \end{itemize}

trunk/doc/modules/ModulesSDRS.tex

@@ -1 @@
-%%% $Id: ModulesSDRS.tex,v 1.29 2005-01-24 21:56:33 price Exp $
+%%% $Id: ModulesSDRS.tex,v 1.30 2005-02-08 04:56:24 eugene Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -1103 +1103 @@
 \begin{verbatim}
 typedef struct {
-  psPeak *peak;            // description of peak pixel
+  pmPeak *peak;            // description of peak pixel
   psImage *pixels;         // rectangular region including object pixels
   psImage *mask;           // mask to mark pixels associated with object in region
-  psMoments *moments;      // basic moments measure for the object
-  psModel *models;         // model parameters and type
-  psSourceType type;       // best identification of object
-} psSource;
+  pmMoments *moments;      // basic moments measure for the object
+  pmModel *models;         // model parameters and type
+  pmSourceType type;       // best identification of object
+} pmSource;
 \end{verbatim}
 
@@ -1120 +1120 @@
   int y;                   // y-coordinate of peak pixel
   float counts;            // value of peak pixel (above sky?)
-  psPeakType class;        // description of peak
-} psPeak;
+  pmPeakType class;        // description of peak
+} pmPeak;
 \end{verbatim}
 
 A peak pixel may have several features which may be determined when
 the peak is found or measured.  These are specified by the
-\code{psPeakType} enum.  \code{PS_PEAK_LONE} represents a single pixel
+\code{pmPeakType} enum.  \code{PM_PEAK_LONE} represents a single pixel
 which is higher than its 8 immediate neighbors.  The
-\code{PS_PEAK_EDGE} represents a peak pixel which touching the image
-edge.  The \code{PS_PEAK_FLAT} represents a peak pixel which has more
+\code{PM_PEAK_EDGE} represents a peak pixel which touching the image
+edge.  The \code{PM_PEAK_FLAT} represents a peak pixel which has more
 than a specific number of neighbors at the same value, within some
 tolarence:
 \begin{verbatim}
 typedef enum {
-  PS_PEAK_LONE;             // isolated peak
-  PS_PEAK_EDGE;             // peak on edge
-  PS_PEAK_FLAT;             // peak has equal-value neighbors
-} psPeakType; 
+  PM_PEAK_LONE;             // isolated peak
+  PM_PEAK_EDGE;             // peak on edge
+  PM_PEAK_FLAT;             // peak has equal-value neighbors
+} pmPeakType; 
 \end{verbatim}
 
@@ -1162 +1162 @@
   float Sky;                // sky level (background)
   int   nPixels;            // number of pixels used
-} psMoments;
+} pmMoments;
 \end{verbatim}
 
@@ -1168 +1168 @@
 function.  The description of the model includes the model parameters
 and their errors, along with the fit $\chi^2$.  The model type is
-specified by the enum \code{psObjectModel}, specified below.  We
+specified by the enum \code{pmObjectModel}, specified below.  We
 discuss the details of these models in section~\ref{ObjectModels}.
 
 \begin{verbatim}
 typedef struct {
-  psObjectModel type;       // model to be used
+  pmObjectModel type;       // model to be used
   int Nparams;              // number of parameters
   float *params;            // parameter values
   float *dparams;           // parameter errors
   float chisq;              // fit chisq
-} psModel;
+} pmModel;
 \end{verbatim}
 
 \begin{verbatim}
 typedef enum {
-  PS_MODEL_GAUSS;
-  PS_MODEL_PGAUSS;
-  PS_MODEL_TWIST_GAUSS;
-  PS_MODEL_WAUSS;
-  PS_MODEL_SERSIC;
-  PS_MODEL_SERSIC_CORE;
-} psModelType; 
+  PM_MODEL_GAUSS;
+  PM_MODEL_PGAUSS;
+  PM_MODEL_TWIST_GAUSS;
+  PM_MODEL_WAUSS;
+  PM_MODEL_SERSIC;
+  PM_MODEL_SERSIC_CORE;
+} pmModelType; 
+\end{verbatim}
+
+A given source may be identified as most-likey to be one of several
+source types.  The \code{pmSource} entry \code{pmSourceType} defines
+the current best-guess for this source.  \tbd{The values given below
+are currently illustrative and will require some modification as the
+source classification code is developed.}
+
+\begin{verbatim}
+typedef enum {
+  PM_SOURCE_PSFSTAR;
+  PM_SOURCE_GALAXY;
+  PM_SOURCE_DEFECT;
+  PM_SOURCE_SATSTAR;
+  PM_SOURCE_FAINTSTAR;
+  PM_SOURCE_BRIGHTSTAR;
+} pmSourceType; 
 \end{verbatim}
 
@@ -1233 +1250 @@
 making flat-topped regions have single peaks at the (+x,+y) corner.
 When selecting the peaks, their type must also be set.  The result of
-this function is a list of \code{psPeak} entries.
+this function is a list of \code{pmPeak} entries.
 
 \tbd{do we need a function psVector *psImageRowVector (psImage *image, int row);}
@@ -1248 +1265 @@
 
 \begin{verbatim}
-psSource *pmSourceLocalSky(const psImage *image, const psPeak *peak, float inner_radius, float outer_radius), 
+pmSource *pmSourceLocalSky(const psImage *image, const pmPeak *peak, float inner_radius, float outer_radius), 
 \end{verbatim}
 
@@ -1255 +1272 @@
 specified are used to measure the median \tbd{(clipped mean?)
 (statistic from psStats?)} in the vicinity of the the specified peak
-coordinates.  The resulting sky is applied to the \code{psMoments}
-element of the allocated \code{psSource} structure.  The input
-\code{peak} is also added to the \code{psSource} element, which is
+coordinates.  The resulting sky is applied to the \code{pmMoments}
+element of the allocated \code{pmSource} structure.  The input
+\code{peak} is also added to the \code{pmSource} element, which is
 returned.
 
 \begin{verbatim}
-psSource *pmSourceMoments(psSource *source, const psImage *image, float radius), 
+pmSource *pmSourceMoments(pmSource *source, const psImage *image, float radius), 
 \end{verbatim}
 
@@ -1271 +1288 @@
 
 \begin{verbatim}
-psSource *pmSourceRoughClass(psSource *source, float saturate, float SNlim, const psRegion *valid);
+pmSource *pmSourceRoughClass(pmSource *source, float saturate, float SNlim, const psRegion *valid);
 \end{verbatim}
 
@@ -1303 +1320 @@
 
 \begin{verbatim}
-bool pmSourceSetPixelsCircle(psSource *source, const psImage *image, float radius);
+bool pmSourceSetPixelsCircle(pmSource *source, const psImage *image, float radius);
 \end{verbatim}
 
@@ -1314 +1331 @@
 
 \begin{verbatim}
-bool pmSourceModelGuess(psSource *source, const psImage *image);
+bool pmSourceModelGuess(pmSource *source, const psImage *image);
 \end{verbatim}
 
@@ -1323 +1340 @@
 
 \begin{verbatim}
-psArray *pmSourceContour(const psSource *source, const psImage *image, float level, int mode);
+psArray *pmSourceContour(const pmSource *source, const psImage *image, float level, int mode);
 \end{verbatim}
 
 Find points in a contour for the given source at the given level.  If
-mode is \code{PS_CONTOUR_CRUDE}, the contour is found by starting at
+mode is \code{PM_CONTOUR_CRUDE}, the contour is found by starting at
 the source peak, running along each pixel row until the level is
 crossed, then interpolating to the level coordinate for that row.
@@ -1339 +1356 @@
 
 \begin{verbatim}
-bool pmSourceFitModel(psSource *source, psImage *image);
+bool pmSourceFitModel(pmSource *source, psImage *image);
 \end{verbatim}
 
@@ -1350 +1367 @@
 
 \begin{verbatim}
-bool pmSourceAddModel(psImage *image, psSource *source, bool center);
+bool pmSourceAddModel(psImage *image, pmSource *source, bool center);
 \end{verbatim}
 
@@ -1360 +1377 @@
 
 \begin{verbatim}
-bool pmSourceSubModel(psSource *source);
+bool pmSourceSubModel(pmSource *source);
 \end{verbatim}
 
@@ -1388 +1405 @@
 
 \begin{verbatim}
-float psMinLM_PseudoGauss2D(psVector *deriv, psVector *params, psVector *x);
+float pmMinLM_PseudoGauss2D(psVector *deriv, psVector *params, psVector *x);
 \end{verbatim}
 

trunk/doc/pslib/ChangeLogSDRS.tex

@@ -1 @@
-%%% $Id: ChangeLogSDRS.tex,v 1.61 2005-01-26 00:04:52 price Exp $
+%%% $Id: ChangeLogSDRS.tex,v 1.62 2005-02-08 04:56:24 eugene Exp $
 
 \subsection{Changes from version 00 to version 01}
@@ -446 +446 @@
 \item Added \code{region} and \code{nSamples} to
   \code{psPlaneTransformCombine} and specified the algorithm.
-\end{itemize}
+\item re-added psMetadata iterators, modified the APIs somewhat
+\item added the mode entry to psMetadataAddItem 
+\item clarified the 'format' entry in psMetadataAdd
+\item added the function psMetadataAddV
+\item added the option flags \code{psMetadataFlags}
+\end{itemize}

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.173 2005-01-28 21:37:57 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.174 2005-02-08 04:56:24 eugene Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -3901 +3901 @@
 \code{psMetadataItem} ready for insertion into the \code{psMetadata}.
 The \code{name} entry specifies the name to use for this metadata
-item, and may include \code{sprintf}-stype formating codes.  The
-\code{format} entry, which specifies both the metadata type and the
-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 metadata data
-and the arguments to the \code{name} formatting codes are passed, in
-that order (metadata pointer first), to \code{psMetadataItemAlloc} as
+item, and may include \code{sprintf}-type formating codes.  The
+\code{comment} entry is a fixed string which is used 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},
@@ -3915 +3913 @@
 \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);
+psMetadataItem *psMetadataItemAllocV(const char *name, psMetadataType type, const char *comment, va_list list);
 \end{verbatim}
 
@@ -3933 +3930 @@
 (\code{true}) or failure of the operation.  The second function,
 \code{psMetadataAdd} takes a pointer or value which is interpreted by
-the function using variadic argument interpretation.  Both functions
-take an parameter \code{location} which specifies where in the list to
-place the element, following the conventions for the \code{psList}.
-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);
+the function using variadic argument interpretation.  The third
+version is the \code{va_list} version of the second function.  All
+three functions take a parameter, \code{location}, which specifies
+where in the list to place the element, following the conventions for
+the \code{psList}.  The entry \code{mode} for \code{psMetadataAddItem}
+is a bit mask constructed by OR-ing the allowed option flags (eg,
+PS_META_REPLACE) which specifies 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, ...);
+\end{verbatim}
+
+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
+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
+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}
+
+An example of code to use these metadata APIs to generate the
+structure seen in Figure~\ref{fig:metadata} is given below.
+
+\begin{verbatim}
+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");
+
+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);
+
+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);
+\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);
 \end{verbatim}
 
@@ -3983 +4043 @@
 \end{verbatim}
 
-The metadata may be iterated over by (re-)setting a particular
-\code{iterator}, to a location in the \code{psMetadata} list, and
-getting the previous or next item.  \code{psMetadataGetNext} has the
-ability to match the beginning of a key, e.g., if the user only wants
-to iterate through \code{IPP.machines.sky} and doesn't want to bother
-with \code{IPP.machines.detector}.  The iterator should iterate over
-every item of metadata --- even those that are non-unique.  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 \code{psList} iterators.
-\begin{verbatim}
-bool psMetadataSetIterator(psMetadata *md, int iterator, int location);
-psMetadataItem *psMetadataGetNext(psMetadata *md, const char *match, int iterator);
-psMetadataItem *psMetadataGetPrevious(psMetadata *md, const char *match, int iterator);
+The metadata list component may be iterated over by using a
+\code{psListIterator} in a fashion equivalent to the usage for
+\code{psList}.  The iterator may be set to a location in the
+\code{psMetadata} list, and the user may get the previous or next item
+in the list relative to that location.  \code{psMetadataGetNext} has
+the ability to match the key using a POSIX regex, e.g., if the user
+only wants to iterate through \code{IPP.machines.sky} and doesn't want
+to bother 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 to be used.  In setting the iterator, the
+position of the iterator is defined by \code{location}, which follows
+the conventions of the \code{psList} iterators.
+\begin{verbatim}
+psListIterator *psMetadataIteratorAlloc(psMetadata *md, int location, bool mutable);
+bool psMetadataIteratorSet(psListIterator *iterator, int location);
+psMetadataItem *psMetadataGetAndIncrement(psListIterator *iterator, const char *regex);
+psMetadataItem *psMetadataGetAndDecrement(psListIterator *iterator, const char *regex);
 \end{verbatim}