Index: trunk/doc/dvo/dvo.tex
===================================================================
--- trunk/doc/dvo/dvo.tex	(revision 6033)
+++ trunk/doc/dvo/dvo.tex	(revision 6035)
@@ -19,6 +19,192 @@
 \pagenumbering{arabic}
 
-\tbd{substantial discussion of the photcodes and the photometry
-  transformation process}
+\subsection{Photometric systems and the DVO Photcodes}
+
+One of the major roles of DVO is to relate different photometric
+measurements made with different instruments and detectors together.
+We may have observations made with the same basic filters, but using a
+number of different detectors.  We may have observations from
+different telescopes in similar filters.  We may have reference data
+related to some filter, but obtained and published by other
+observers.  We would like to related these measurements together in
+optimal ways, making use of whatever information we have available.
+DVO provides several mechanisms to enable these relationships.
+
+We identify three distinct types of photometry measurements within
+DVO:
+\begin{itemize}
+\item {\bf reference photometry}  These measurements are provided by
+  external observers.  For reference photometry, we do not have access
+  to very must information used to determine the magnitudes of the
+  objects of interest.  We have the reference magnitudes corresponding
+  to a type of filter, and presumably some information of the error on
+  the measurement.  We might possibly know the epoch of the
+  observations, but not necessarily.  
+\item {\bf detection photometry} This is our primary measurement of
+  interest: the photometry of objects measured from images which we
+  have processed.  More specifically, the detection photometry is an
+  instantaneous measurement from a specific image with well-known
+  properties, such as exposure time, airmass, instrument source, etc.  
+\item {\bf internal photometry} With the application of an appropriate
+  zero point and other calibration terms, any detection photometry can
+  be calibrated to represent a measurement in a well-known photometric
+  system.  The internal photometry measurements are calibrated to be
+  on a photometric system which represents a consistent system for a
+  particular telescope or collection of data, minimizing the
+  calibration transformations necsessary.
+\end{itemize}
+
+Defining the relationships between the different types of measurements
+is part of the process of photometric calibration.  DVO uses the
+concept of the 'photcode' to identify the source of the photometry,
+and to define the relationships between different photometry sources.
+A photcode identifies a photometric system: for the detection
+photometry measurments, each combination of telescope, camera, filter,
+and detector is associated with a unique photcode; there are also
+unique photcodes for the internal photometry systems and any distinct
+external reference source.  
+
+As a concrete example, consider the Pan-STARRS PS-1 system.  There
+will be three different cameras in use at different times: GPC-1,
+TC-3, and the SkyProbe camera.  There are at least 6 filter systems:
+{\it grizy} and {\it w}.  The SkyProbe camera has a single CCD, TC-3
+has 16 different detectors, and GPC-1 has up to 64 different devices.
+Each of these combinations is potentially a different photometric
+system, so a different photcode is defined for each combination.
+These photcodes would have names such as: GPC1.02.r (r filter with the
+GPC1 camera and OTA 02) or SP1.00.g (SkyProbe 1, g filter).  These
+($64 \times 6 + 16 \times 6 + 5 = 485$) photcodes are all identified
+as 'detection' photcodes, specifying that detection photometry is
+associated with them
+
+There are also 6 different internal photometric systems of interest,
+namely those associated with the 6 named filters, {\it grizy} and {\it
+w}. Each of these 6 systems is identified with an internal photcode.
+The internal photcodes are further distinguished as 'primary' or
+'secondary', which specifies how the DVO system stores average
+quantities related to these types of photcodes (see the discussion of
+the tables below).  
+
+Finally, there may be multiple external photometric systems of
+interest, some of which are related to the major internal photometry
+systems, some of which are not.  For example, the Pan-STARRS project
+may refer to photometry from the SDSS secondary standards, the SDSS
+data releases, Johnson photometry from Landolt (1992), observations
+from 2MASS in $JHK$, USNO-B observations, and so forth.  Each of these
+photometric systems is assoiciated with a different photcode; only
+some of these are relevant to the detection or internal photometry
+system.
+
+Within DVO, the detection and internal photcodes each define a
+relationships as well as a specific photometric system.  Associated
+with each of these photcodes are the parameters of the photometry
+transformation from the photometric system of the photcode to another
+photometric system.  For the detection photcodes, the parameters
+define the transformation to the equivalent internal photcode system.
+The currently-defined transformation parameters consist of the
+following photometry equation:
+%
+\[ M_i = M_r + C_r + K_r (\mbox{airmass} - 1) + \sum_{i = 1}^{i < N}
+A_{r,i} (\mbox{color} - \mbox{color}_r)^i 
+\] 
+%
+where $C_r$ represents the zero-point of the transformation, $K_r$
+represents the slope of the airmass trend, $\mbox{airmass}$ is the
+airmass for a given measurement, $\mbox{color}$ is the color of the
+source of interest (as identified below), $\mbox{color}_r$ is the
+reference color for sources in this photometry system, and $A_{r,i}$
+is the coefficient of the $i$ power of the color difference.  Up to
+fourth order color terms are currently allowed.  For any photcode, the
+color is defined as the difference of the measurements in two other
+photcodes, usually two 'internal' photcodes.  The photcode information
+also specified the equivalent photcode to which the transformation corresponds.
+
+For the detection photcodes, the target of the transformation must be
+an internal photcode.  For the internal photcodes, the target of the
+transformation is an external reference photcode system.  This
+restriction implies that the internal photometry may only be
+transformed (and thus compared with) a single external reference.
+This is in fact the best practice as far as photometric calibration is
+concerned: the 'standard' observations from different references
+should always be treated as different photometric systems.  To allow
+for the relationship of the internal photometry to multiple sources of
+reference photometry, an additional set of photcodes are defined which
+identify 'alternative' transformations for the internal photcodes.
+
+It is important to note that not all of the photometry transformation
+parameters identified above are relevant for each of the three major
+types of photcode.  The detection photcodes will in general make use
+of all of these elements, though the order of the color transformation
+will hopefully be limited if the different devices are sufficiently
+similar.  For the transformation from the internal photcodes, which
+are derivative in some way of the detection photcodes, the airmass
+component is invalid: for a single measurement, the
+detection-to-internal transformation has already removed the airmass
+trend; for an averaged internal photometric measurement, no single
+airmass corresponds to the observations.  Finally, no transformation
+parameters are defined for the reference photcodes at this time.
+
+DVO provides methods by which these photometry transforamtions are
+automatically applied.  The specific measurements (detection
+photometry) are stored in the database tables as instrumental
+magnitudes, and any operation which examines these measurements must
+make use of the APIs to convert to an appropriate common system.  A
+further complication to note is that the photcodes defined above are
+static; they do not include any information about changes to the
+system sensitivity.  This information is carried externally to the
+photcode calibration information; the transformations defined by the
+photcodes must be considered the {\em starting point} for any
+photometric analysis.  An additional adjusment can be applied.  
+
+The detections from a specific image may all have a 'calibration'
+offset applied which bring the measured photometry into a common
+relative system.  This calibration offset is associated with the image
+and may be a function of position on the detector.  The tables which
+carry the individual measurements also include the calibration
+magnitude appropriate for each measurement to speed up the application
+of this offset.  In a well-calibrated collection of photometry, all of
+the detection measurements will have a measured calibration magnitude,
+yielding a collection of internal photometry measurements which are
+all consistent.  An additional piece of information is the zero-point
+history, which tracks the system-wide variations in the average
+sensitivity.  The zero-point history can be used to predict the
+calibration magnitudes for any observation which is not tied directly
+via relative photometry to the rest of the photometric observations.
+
+Putting all of these pieces together, the photometry APIs in DVO can
+be used to return any of the following types of photometric
+measurements:
+\begin{itemize}
+\item raw instrumental magnitudes for any detection
+
+\item 'catalog' magnitudes, applying only the airmass and static
+  zero-point calibrations to a detection magnitude; this is useful to
+  test the detector-color transformation.
+
+\item 'system' measurements, applying the complete static
+  transformation for a detection magnitude to the internal photometry
+  system; for photometric weather and no zero-point variations, this
+  would be a measurement in the internal photometry system.
+
+\item 'relative' magnitudes, applying the measured calibration offset
+  to the calibrated detection magnitude determined above; in a
+  well-calibrated system, this represents a consistent internal
+  photometry measurement.
+
+\item 'calibrated' magnitudes, correcting the measure detection
+  photometry by applying the transformation from the internal
+  magnitude system to the external reference magntiude system.
+
+\item 'average' magntiudes, the raw internal photometry magnitudes
+  (note the distinction between the 'average' quantities, which are
+  derived from a collection of detections an the 'relative' quantities
+  which represent an instantenous measurement in the same system).
+
+\item 'reference' magnitudes, in which the 'average' internal
+  photometry values are transformed to the refernce magnitude system.  
+\end{itemize}
+The complexity of these transformations is necessary to allow the
+examination of the trends of actual measurements with external
+parameters.
 
 \section{Overview}