Doc: Fixed a few things and removed duplicates.

doc/src/Param.rst

@@ -29,35 +29,58 @@ For many catalog parameters, especially those related to flux,
 position, or shape, several variants of the same measurement are
 available:
 
+.. _fluxes_and_magnitudes:
+
 Fluxes and magnitudes
 ~~~~~~~~~~~~~~~~~~~~~
 
-Fluxes may be expressed in linear (ADU) units or as Pogson :cite:`1856MNRAS_17_12P` magnitudes. Flux measurements in ADUs are prefixed with :param:`FLUX_`, for example: :param:`FLUX_AUTO`, :param:`FLUX_ISO`, etc. Magnitudes are prefixed with :param:`MAG_` e.g., :param:`MAG_AUTO`, :param:`MAG_ISO`, ... In
-|SExtractor| the magnitude :math:`m` of a source is derived from the flux
-:math:`f`:
+Fluxes may be expressed in counts (|ADU|\ s) or as Pogson :cite:`1856MNRAS_17_12P` magnitudes.
+Flux measurements in |ADU|\ s are prefixed with :param:`FLUX_`, for example: :param:`FLUX_AUTO`, :param:`FLUX_ISO`, etc.
+Magnitudes are prefixed with :param:`MAG_` e.g., :param:`MAG_AUTO`, :param:`MAG_ISO`, ...
+The ``MAG_ZEROPOINT`` configuration parameter sets the magnitude zero-point of magnitudes:
 
 .. math::
+ :label: mag
 
-   m = \left\{\begin{array}{ll}
-   m_{ZP} -2.5 \log_{10} f\ &\mbox{if } f > 0\\
-   99.0 &\mbox{otherwise},
+   {\tt MAG} = \left\{\begin{array}{ll}
+   \mathrm{MAG\_ZEROPOINT} - 2.5 \log_{10} {\tt FLUX}\ &\mbox{if } {\tt FLUX} > 0\\
+   99.0\ &\mbox{otherwise},
    \end{array}\right.
 
-where :math:`m_{ZP}` is the magnitude zero-point set with the
-``MAG_ZEROPOINT`` configuration parameter.
-
 Flux and magnitude uncertainties
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Flux uncertainties follow a scheme similar to that of fluxes. Flux uncertainties are prefixed with :param:`FLUXERR_`, as in :param:`FLUXERR_AUTO` or :param:`FLUXERR_ISO`. Magnitude uncertainties start with :param:`MAGERR_`, for instance: :param:`MAGERR_AUTO`, :param:`MAGERR_ISO`,... Magnitude uncertainties :math:`\sigma_m` are derived from the estimated 1-\ :math:`\sigma` flux error :math:`\sigma_f`:
+Flux uncertainties (error estimates) follow a scheme similar to that of fluxes.
+They are prefixed with :param:`FLUXERR_`, as in :param:`FLUXERR_AUTO` or :param:`FLUXERR_ISO`.
+Magnitude uncertainties start with :param:`MAGERR_`, for instance: :param:`MAGERR_AUTO`, :param:`MAGERR_ISO`,...
+They are computed using
 
 .. math::
+ :label: magerr
 
-   \sigma_m = \left\{\begin{array}{ll}
-   (2.5/\ln 10) (\sigma_f/f)\ &\mbox{if } f > 0\\
-   99.0 &\mbox{otherwise}.
+   {\tt MAGERR} = \left\{\begin{array}{ll}
+   \frac{2.5}{\ln 10}({\tt FLUXERR}/{\tt FLUX})\ &\mbox{if } {\tt FLUX} > 0\\
+   99.0\ &\mbox{otherwise}.
    \end{array}\right.
 
+Pixel values and Surface brightnesses
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Pixel values (averaged or not) :math:`p` are expressed in counts (|ADU|\ s).
+There is no specific prefix (:param:`THRESHOLD`, :param:`BACKGROUND`, :param:`FLUX_MAX`, etc.).
+Surface brightnesses are given in magnitudes per square arcsecond, and prefixed with :param:`MU_` e.g., :param:`MU_THRESHOLD`, :param:`MU_MAX`, ...
+The conversion to surface brightness relies on the ``MAG_ZEROPOINT`` and the ``PIXEL_SCALE`` configuration parameters:
+
+.. math::
+ :label: mu
+
+   {\tt MU} = \left\{\begin{array}{ll}
+   \mathrm{MAG\_ZEROPOINT} - 2.5 \log_{10} (p \times {\rm PIXEL\_SCALE}\,^2)\ &\mbox{if } p > 0\\
+   99.0\ &\mbox{otherwise}.
+   \end{array}\right.
+
+Setting ``PIXEL_SCALE`` to 0 instructs |SExtractor| to compute the pixel scale from the local Jacobian of the astrometric deprojection, based on the celestial |WCS| info in the |FITS| image header, if available.
+
 .. _coord_suffix:
 
 Positions and shapes

doc/src/Photom.rst

@@ -8,21 +8,7 @@ Photometry
 ==========
 
 Besides |PSF| and :ref:`model-fitting <models_def>` flux estimates, |SExtractor| can currently perform four types of flux measurements: :ref:`isophotal <flux_iso_def>`, :ref:`corrected-isophotal <mag_isocor_def>`, :ref:`fixed-aperture <flux_aper_def>` and :ref:`adaptive-aperture <flux_auto_def>`.
-For every :param:`FLUX_` measurement, an error estimate :param:`FLUXERR_`, a magnitude :param:`MAG_` and a magnitude error estimate :param:`MAGERR_` are also available.
-The ``MAG_ZEROPOINT`` configuration parameter sets the magnitude zero-point
-of magnitudes:
-
-.. math::
- :label: mag
-
-   {\tt MAG} = \mathrm{MAG\_ZEROPOINT} - 2.5 \log_{10} {\tt FLUX}
-
-Magnitude uncertainties (error estimates) are computed using
-
-.. math::
- :label: magerr
-
-   {\tt MAGERR} = \frac{2.5}{\ln 10}\frac{\tt FLUXERR}{\tt FLUX}
+For every :param:`FLUX_` measurement, an error estimate :param:`FLUXERR_`, a magnitude :param:`MAG_` and a magnitude error estimate :param:`MAGERR_` are also available: see :ref:`fluxes_and_magnitudes`.
 
 An estimate of the error is available for each type of flux.
 For aperture fluxes, the flux uncertainty is computed using
@@ -30,7 +16,7 @@ For aperture fluxes, the flux uncertainty is computed using
 .. math::
   :label: fluxerr
 
-  {\rm FLUXERR} = \sqrt{\sum_{i\in{\cal A}}\, (\sigma_i^2 + \frac{p_i}{g_i})}
+  {\tt FLUXERR} = \sqrt{\sum_{i\in{\cal A}}\, (\sigma_i^2 + \frac{p_i}{g_i})}
 
 where :math:`{\cal A}` is the set of pixels defining the photometric aperture, and :math:`\sigma_i`, :math:`p_i`, :math:`g_i` respectively the standard deviation of noise (in ADU) estimated from the local background, :math:`p_i` the measurement image pixel value subtracted from the background, and :math:`g_i` the effective detector gain in :math:`e^- / \mbox{ADU}` at pixel :math:`i`. Note that this error estimate provides a lower limit of the true uncertainty, as it only takes into account photon and detector noise.
 
@@ -204,6 +190,8 @@ The Petrosian flux is the sum of pixel values from the measurement image, subtra
 
   {\tt FLUX\_PETRO} = \sum_{i\in\cal P} p_i.
 
+.. [#petro_radius]
+   Some authors prefer to define the Petrosian radius as :math:`r_{\rm P}` instead of :math:`N_{\rm P}r_{\rm P}`.
 
 Photographic photometry
 -----------------------
@@ -259,6 +247,4 @@ However in practice the ``BACKPHOTO_TYPE LOCAL`` option has not proven as being
 
 In both ``LOCAL`` and ``GLOBAL`` modes, the :param:`BACKGROUND` catalog parameter gives the value of the background estimated at the centroid of the object.
 
-.. [#petro_radius]
-   Some authors prefer to define the Petrosian radius as :math:`r_{\rm P}` instead of :math:`N_{\rm P}r_{\rm P}`.
 

doc/src/keys.rst

+.. |ADU| replace:: :abbr:`ADU (Analog-to-Digital Unit)`
+.. _ADU: https://en.wikipedia.org/wiki/Analog-to-digital_converter
+
 .. |ATLAS| replace:: :program:`ATLAS`
 .. _ATLAS: http://math-atlas.sourceforge.net