Doc: some refactoring.

.. File Config.rst

.. include:: global.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.

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:

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.

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::

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.

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.

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

.. include:: global.rst

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

Installing the software

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

Memory requirements depend on the size of the images to be processed.

Processing a single image should typically require about 100MB of memory.

For large images (hundreds of Mpixels or more), or in double-image / weighted

mode, |SExtractor|'s  memory footprint should be around 500MB, and up to 2GB in

the worst cases. Swap-space can be put to contribution, although a strong

performance hit is to be expected.

For large images (hundreds of Mpixels or more), or in double-image / weighted mode, |SExtractor|'s  memory footprint should be around 500MB, and up to 2GB in the worst cases.

Swap-space can be put to contribution, although a strong performance hit is to be expected.

Obtaining |SExtractor|

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

For Linux users, the simplest way to have |SExtractor| up and running is to

install the standard binary package the comes with your Linux distribution.

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>`.

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

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

`the official GitHub repository <https://github.com/astromatic/sextractor>`_ .

One may choose `one of the stable releases

<https://github.com/astromatic/sextractor/releases>`_, or for the fearless,

`a copy of the current master development branch

<https://github.com/astromatic/sextractor/archive/master.zip>`_.

For Linux users, the simplest way to have |SExtractor| up and running is to install the standard binary package the comes with your Linux distribution.

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>`.

However if |SExtractor| is not available in your distribution, or to obtain the most recent version, the |SExtractor| source package can be downloaded from `the official GitHub repository <https://github.com/astromatic/sextractor>`_ .

One may choose `one of the stable releases <https://github.com/astromatic/sextractor/releases>`_, or for the fearless, `a copy of the current master development branch <https://github.com/astromatic/sextractor/archive/master.zip>`_.

Software requirements

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

|SExtractor| has been developed on

`GNU/Linux <http://en.wikipedia.org/wiki/Linux>`_ machines and should compile on

any `POSIX <http://en.wikipedia.org/wiki/POSIX>`_-compliant system (this

includes |OSX|_ and `Cygwin <http://www.cygwin.com>`_ on |Windows|_, at the

price of some difficulties with the configuration), provided that the

*development* packages of the following libraries have been installed:

|SExtractor| has been developed on `GNU/Linux <http://en.wikipedia.org/wiki/Linux>`_ machines and should compile on any `POSIX <http://en.wikipedia.org/wiki/POSIX>`_-compliant system (this includes |OSX|_ and `Cygwin <http://www.cygwin.com>`_ on |Windows|_, at the price of some difficulties with the configuration), provided that the *development* packages of the following libraries have been installed:

* |ATLAS|_ V3.6 and above [#atlas_install]_,

* |FFTw|_ V3.0 and above [#fftw_install]_, 

On Fedora/Redhat distributions for instance, the development packages above are

available as ``atlas-devel`` and ``fftw-devel``. Note that |ATLAS| and |FFTw|

are not necessary if |SExtractor| is linked with |Intel|'s |MKL|_ library.

On Fedora/Redhat distributions for instance, the development packages above are available as ``atlas-devel`` and ``fftw-devel``.

Note that |ATLAS| and |FFTw| are not necessary if |SExtractor| is linked with |Intel|'s |MKL|_ library.

Installation

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

To install from the |GitHub| source package, you must first uncompress the

archive:

To install from the |GitHub| source package, you must first uncompress the archive:

.. code-block:: console

  $ unzip sextractor-<version>.zip

A new directory called :file:`sextractor-<version>` should now appear at the

current location on your disk. Enter the directory and generate the files

required by the `autotools <http://en.wikipedia.org/wiki/GNU_Build_System>`_,

which the package relies on:

A new directory called :file:`sextractor-<version>` should now appear at the current location on your disk.

Enter the directory and generate the files required by the `autotools <http://en.wikipedia.org/wiki/GNU_Build_System>`_, which the package relies on:

.. code-block:: console

  $ cd sextractor-<version>

  $ sh autogen.sh

A :program:`configure` script is created. This script has many options, which

may be listed with the ``--help`` option:

A :program:`configure` script is created.

This script has many options, which may be listed with the ``--help`` option:

.. code-block:: console

  $ ./configure --help

No options are required for compiling with the default GNU C compiler

(:program:`gcc`) if all the required libraries are installed at their default

locations:

No options are required for compiling with the default GNU C compiler (:program:`gcc`) if all the required libraries are installed at their default locations:

.. code-block:: console

  $ ./configure

Compared to :program:`gcc` and the librairies above, the combination of the

|Intel| compiler (:program:`icc`) and the |MKL|_ libraries can give the

|SExtractor| executable a strong boost in performance, thanks to better

vectorized code. If :program:`icc` and the |MKL| are installed on your system

[#geticc]_ , you can take advantage of them using

Compared to :program:`gcc` and the librairies above, the combination of the |Intel| compiler (:program:`icc`) and the |MKL|_ libraries can give the |SExtractor| executable a strong boost in performance, thanks to better vectorized code.

If :program:`icc` and the |MKL| are installed on your system [#geticc]_ , you can take advantage of them using

.. code-block:: console

  $ ./configure --enable-mkl

Additionally, if the |SExtractor| binary is to be run on a different machine

that does not have :program:`icc` and the |MKL| installed (e.g., a cluster

computing node), you must configure a partially statically linked executable

using

Additionally, if the |SExtractor| binary is to be run on a different machine that does not have :program:`icc` and the |MKL| installed (e.g., a cluster computing node), you must configure a partially statically linked executable using

.. code-block:: console

  $ make -j

An :file:`src/sex` executable is created. For system-wide installation, run

the usual

An :file:`src/sex` executable is created. For system-wide installation, run the usual

.. code-block:: console

  $ sudo make install

You may now check that the software is properly installed by simply

typing in your shell:

You may now check that the software is properly installed by simply typing in your shell:

.. code-block:: console

  $ sex

which will return the version number and other basic information (note that

some shells require the :program:`rehash` command to be run before making a

freshly installed executable accessible in the execution path).

which will return the version number and other basic information (note that some shells require the :program:`rehash` command to be run before making a freshly installed executable accessible in the execution path).

.. [#mac_install] Mac OS X |.dmg|_ packages should be available soon.

.. [#atlas_install] Use the ``--with-atlas`` and/or

   ``--with-atlas-incdir`` options of the |SExtractor| :command:`configure`

   script to specify the |ATLAS| library and include paths if |ATLAS| files are 

   installed at unusual locations.

.. [#fftw_install] Make sure that |FFTW| has been compiled with

   :command:`configure` options ``--enable-threads --enable-float``.

.. [#geticc] The Linux versions of the |Intel| compiler and |MKL| are

   `available for free to academic researchers, students, educators and open

   source contributors <http://software.intel.com/qualify-for-free-software>`_.

.. include:: keys.rst

.. [#atlas_install] Use the ``--with-atlas`` and/or ``--with-atlas-incdir`` options of the |SExtractor| :command:`configure` script to specify the |ATLAS| library and include paths if |ATLAS| files are  installed at unusual locations.

.. [#fftw_install] Make sure that |FFTW| has been compiled with :command:`configure` options ``--enable-threads --enable-float``.

.. [#geticc] The Linux versions of the |Intel| compiler and |MKL| are `available for free to academic researchers, students, educators and open source contributors <http://software.intel.com/qualify-for-free-software>`_.

.. File Introduction.rst

.. include:: global.rst

Introduction

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

|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:

|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:

* Support for multi-extension FITS (|MEF|_)

* Speed: up to about 50 Mpixel/s or 10,000 sources/s with a 3 GHz processor

* Built-in catalog cross-identification.

* Special mode for photographic scans.

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

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

  regular web browser.

.. include:: keys.rst

* |XSLT|_ filter sheet provided for convenient access to metadata from a regular web browser.

.. File License.rst

.. include:: global.rst

License

=======

|SExtractor|_ *is free software: you can redistribute it and/or modify it under

the terms of the GNU General Public License as published by the Free

Software Foundation, either version 3 of the License, or (at your

option) any later version.* |SExtractor| *is distributed in the hope that it will

be useful, but WITHOUT ANY WARRANTY; without even the implied warranty

of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

General Public License for more details. You should have received a copy

of the GNU General Public License along with* |SExtractor|. *If not, see*

`www.gnu.org/licenses/ <http://www.gnu.org/licences/>`_.

|SExtractor|_ *is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.*

|SExtractor| *is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with* |SExtractor|. *If not, see* `www.gnu.org/licenses/ <http://www.gnu.org/licences/>`_.

.. include:: keys.rst

Measurements

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

Once sources have been detected and deblended, they enter the measurement phase. |SExtractor| performs three categories of measurements: isophotal, full, and model-fitting.

.. include:: global.rst

Once sources have been detected and deblended, they enter the measurement phase.

|SExtractor| performs three categories of measurements: isophotal, full, and model-fitting.

.. _isophotal_measurements:

Isophotal

  Measurements are made on the isophotal object footprints, which are defined on the filtered detection image. Only pixels with values above the threshold set with ``ANALYSIS_THRESH`` are considered [#thresh]_, which makes the analysis extremely fast, but obviously strongly dependent on the threshold itself. This is an issue particularly when the amplitude of the bakground noise varies over the image. Many of the isophotal measurements (e.g., ``X_IMAGE``, ``Y_IMAGE``, ``FLUX_ISO``) are necessary for the internal operations of |SExtractor| and are therefore executed even if they are not requested.

  Measurements are made on the isophotal object footprints, which are defined on the filtered detection image. Only pixels with values above the threshold set with ``ANALYSIS_THRESH`` are considered [#thresh]_, which makes the analysis extremely fast, but obviously strongly dependent on the threshold itself. This is an issue particularly when the amplitude of the bakground noise varies over the image. Many of the isophotal measurements (e.g., :param:`X_IMAGE`, :param:`Y_IMAGE`, :param:`FLUX_ISO`) are necessary for the internal operations of |SExtractor| and are therefore executed even if they are not requested.

Full

  Measurements have access to all pixels of the image. These measurements are generally more sophisticated, less affected by variable biases induced by the detection threshold, and still reasonably fast. They are done at a later stage of the processing, after CLEANing and MASKing.

.. [#thresh] Pixel values also have to exceed the local detection threshold set with ``DETECT_THRESH``.

.. [#psf_models] PSF models be computed using the |PSFEx|_ package.

.. include:: keys.rst