Doc: Added description of WIN positions and two figures.

.. File Config.rst

The configuration file

======================

Each time it is run, |SExtractor| looks for a configuration file. If no

configuration file is specified in the command-line, it is assumed to be

called :file:`default.sex` and to reside in the current directory. If no

configuration file is found, |SExtractor| will use its own internal

default configuration.

Creating a configuration file

-----------------------------

SExtractor can generate an ASCII dump of its internal default

configuration, using the ``-d`` option. By redirecting the standard output

of SExtractor to a file, one creates a configuration file that can

easily be modified afterwards:

.. code-block:: console

  $ sex -d > default.sex

A more extensive dump with less commonly used parameters can be

generated by using the ``-dd`` option.

Format of the configuration file

--------------------------------

The format is ASCII. There must be only one parameter set per line,

following the form::

 Config-parameter      Value(s)

Extra spaces or linefeeds are ignored. Comments must begin with a ``#``

and end with a linefeed. Values can be of different types: strings (can

be enclosed between double quotes), floats, integers, keywords or

Boolean (`Y`/`y` or `N`/`n`). Some parameters accept zero or several values,

which must then be separated by commas. Integers can be given as

decimals, in octal form (preceded by digit O), or in hexadecimal

(preceded by `0x`). The hexadecimal format is particularly convenient for

writing multiplexed bit values such as binary masks. Environment

variables, written as ``$HOME`` or ``${HOME}`` are expanded.

.. _param_list:

Configuration parameter list

----------------------------

Here is a complete list of all the configuration parameters known to

|SExtractor|. Please refer to the next sections for a detailed description

of their meaning.

.. include:: keys.rst

.. File Installing.rst

***********************

Installing the software

=======================

***********************

Hardware requirements

---------------------

=====================

|SExtractor| runs in (ANSI) text-mode from a shell. A graphical environment

is not necessary to operate the software.

Run, e.g., ``apt-get sextractor`` (on Debian) or ``dnf sextractor`` (Fedora) as

root and |SExtractor|, as well as all its dependencies, will automatically be

installed. If you decided to install the package this way you may skip the

following and move straight to the :ref:`next section <using_sextractor>`.

following and move straight to the :ref:`next section <Using Sextractor>`.

However if |SExtractor| is not available in your distribution, or to obtain the

most recent version, the |SExtractor| source package can be downloaded from

Introduction

============

|SExtractor|_ (Source-Extractor) is a program that builds a catalogue

|SExtractor|_ (Source-Extractor) is a program that builds a catalog

of objects from an astronomical image. It is particularly oriented

towards the reduction of large scale galaxy-survey data, but it also performs

well on moderately crowded star fields. Its main features are:

  thanks to buffered image access

* Real-time filtering of images to improve detectability

* Robust deblending of overlapping extended objects

* Flexible catalogue output of desired parameters only

* Flexible catalog output of desired parameters only

* Pixel-to-pixel photometry in dual-image mode

* Fast and accurate Point-Spread-Function and galaxy model fitting.

* Handling of weight maps and flag maps.

* Optimum handling of images with variable SNR.

* Built-in catalogue cross-identification.

* Built-in catalog cross-identification.

* Special mode for photographic scans.

* |XML|_ |VOTable|_-compliant catalogue output.

* |XML|_ |VOTable|_-compliant catalog output.

* |XSLT|_ filter sheet provided for convenient access to metadata from a

  regular web browser.

Measurements

============

Once sources have been detected and deblended, they enter the

measurement phase. |SExtractor| performs two categories of measurements.

Measurements from the first category are made on the isophotal object

profiles. Only pixels above the detection threshold are considered. Many

of these isophotal measurements (like ``X_IMAGE``, ``Y_IMAGE``, etc.) are

necessary for the internal operations of |SExtractor| and are therefore

executed even if they are not requested. Measurements from the second

category have access to all pixels of the image. These measurements are

generally more sophisticated and are done at a later stage of the

processing (after CLEANing and MASKing).

.. toctree::

   :numbered:

   :maxdepth: 2

  Position

  PositionWin

.. include:: keys.rst

.. File Param.rst

The catalog parameter file

============================

In addition to the configuration file detailed above, |SExtractor| requires a

file containing the list of parameters that will be listed in the output

catalog for every detection. This allows the software to compute only

catalog parameters that are needed. The name of this

catalog-parameter file is traditionally suffixed with ``.param``, and must

be specified using the ``PARAMETERS_NAME`` config parameter. The full set

of parameters can be queried with the command

.. code-block:: console

 $ sex -dp

Format

------

The format of the catalog parameter list is ASCII, and there must be

*a single keyword per line*. Presently two kinds of keywords are

recognized by |SExtractor|: scalars and vectors. Scalars, like ``X_IMAGE``,

produce single numbers in the output catalog. Vectors, like ``MAG_APER(4)``

or ``VIGNET(15,15)``, produce arrays of numbers. The ordering of measurements

in the output catalog is identical to that of the keywords in the parameter

list. Comments are allowed, they must begin with a ``#``.

Variants

--------

For many catalog parameters, especially those related to flux,

position, or shape, several variants of the same measurement are

available:

Fluxes

~~~~~~

may be expressed in linear (ADU) units or as Pogson

:cite:`1856MNRAS..17...12P` magnitudes. Flux measurements in ADUs

are prefixed with ``FLUX_``, for example: ``FLUX_AUTO``, ``FLUX_ISO``, etc.

Magnitudes are prefixed with ``MAG_`` e.g., ``MAG_AUTO``, ``MAG_ISO``, ... In

|SExtractor| the magnitude :math:`m` of a source is derived from the flux

:math:`f`:

.. math::

   m = \left\{\begin{array}{ll}

   m_{ZP} -2.5 \log_{10} f\ &\mbox{if } f > 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 uncertainties

~~~~~~~~~~~~~~~~~~

They follow a scheme similar to that of fluxes. Flux uncertainties are

prefixed with ``FLUXERR_``, as in ``FLUXERR_AUTO`` or ``FLUXERR_ISO``. Magnitude

uncertainties start with ``MAGERR_``, for instance: ``MAGERR_AUTO``,

``MAGERR_ISO``,... Magnitude uncertainties :math:`\sigma_m` are derived

from the estimated 1-\ :math:`\sigma` flux error :math:`\sigma_f`:

.. math::

   \sigma_m = \left\{\begin{array}{ll}

   (2.5/\ln 10) (\sigma_f/f)\ &\mbox{if } f > 0\\

   99.0 &\mbox{otherwise}.

   \end{array}\right.

Positions

~~~~~~~~~

Positions and distances can be expressed in image pixels, world coordinates,

or in celestial coordinates. Measurements in units of image pixels are

indicated by the suffix ``_IMAGE``, for example: ``Y_IMAGE``,

``ERRAWIN_IMAGE``, ... Following the FITS convention, in SExtractor the

center of the first image pixel has coordinates (1.0,1.0). Positions and

small distances may also be expressed in so-called “world coordinates”,

if World Coordinate System (WCS) metadata :cite:`2002A&A...395.1061G` are

present in the FITS image header.

.. include:: keys.rst