Using.rst

Using SExtractor
================

|SExtractor| is run from the shell with the following syntax:

.. code-block:: console

 $ sex Image1 [Image2] -c configuration-file [-Parameter1 Value1 -Parameter2 Value2 ...]

The parts enclosed within brackets are optional.
Any `-Parameter Value` statement in the command-line overrides the corresponding definition in the configuration-file or any default value (see below).

Output files
------------

Diagnostic files
~~~~~~~~~~~~~~~~

Two types of files can be generated by |SExtractor|, providing diagnostics
about the source extraction process:

* "Check-images" are FITS files containing raster images such as maps of the
  background model, apertures, etc.. The configuration parameters
  ``CHECKIMAGE_TYPE`` and ``CHECKIMAGE_NAME`` allow the user to provide a list
  of check-image types and file names, respectively, to be produced by
  |SExtractor|. A complete list of available check-image types is given in
  §[chap:paramlist].
* An |XML|_ file providing a processing summary and various statistics in
  |VOTable|_ format is written if the ``WRITE_XML`` switch is set to ``Y``
  (the default). The ``XML_NAME`` parameter can be used to change the default
  file name :file:`sex.xml`. The |XML| file can be displayed with any recent
  web browser; the |XSLT| stylesheet installed together with |SExtractor| will
  automatically translate it into a dynamic, user-friendly web-page.
  For more advanced usages (e.g., access from a
  remote web server), alternative |XSLT| translation URLs may be specified
  using the ``XSL_URL`` configuration parameter.


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