The visir_util_convert_pos recipe
===============================================================

.. data:: visir_util_convert_pos

Synopsis
--------

Conversion of object position(s) from matching pairs of nodded object files + sextractor tables

Description
-----------

The files listed in the Set Of Frames (sof-file) must be tagged:
Sextractor-object-file.fits POS_CONVERT
Sextractor-table-file.fits POS_TABLE
The table must include these columns, all with numerical data: XWIN_IMAGE, YWIN_IMAGE, FLUX_AUTO.

Such a table can be created by the source extractor software sextractor.


In addition to containing pairs of object- and table-files the SOF may also contain only object-files.

In this case the object files must be tagged with: POS_CONVERT.


For each input object frame one or more products will be created with updated WCS-ccordinates (CRPIX[12]).

When the object frame is matched with a table-frame, one product will be created for each row in the table.

Such products will be created in order of decreasing object brightness.


When the object frames are pairs of 4-beam-frames, the position (centroid) of the brightest object in the 4-beam-frame will be written into the first product.

The nodding and chopping throw will determine the position written into the second product based on the raw-frame and the position written into the two products based on the matching off-frame.

When the object frames are pairs of 4-beam-frames, the recipe also supports updating the WCS-coordinates of an auxiliary frame (e.g. error map) for each object.


If present these auxiliary frames must be tagged:
Object-auxiliary.fits POS_AUX (optional).


The primary product(s) will have a FITS card
'HIERARCH ESO PRO CATG' with a value of:
IMG_CONVERTED
If created, the auxiliary products will have a FITS card
'HIERARCH ESO PRO CATG' with a value of:
AUX_CONVERTED

Constructor
-----------

.. method:: cpl.Recipe("visir_util_convert_pos")
   :noindex:

   Create an object for the recipe visir_util_convert_pos.

::

   import cpl
   visir_util_convert_pos = cpl.Recipe("visir_util_convert_pos")

Parameters
----------

.. py:attribute:: visir_util_convert_pos.param.eccmax

    The maximum eccentricity allowed in the combination of the three (in  parallel nod/chopping) or four (in perpendicular nod/chopping) beams.  In parallel mode, three perfectly aligned points spaced with the  chopnod throw will have eccentricity 0, while in perpedicular mode a  square with the chopnod throw as the side length will have  eccentricity 0 (float; default: 0.25) [default=0.25].
.. py:attribute:: visir_util_convert_pos.param.naverage

    Number of plains to average before searching for the beam positions.  (long; default: 1) [default=1].
.. py:attribute:: visir_util_convert_pos.param.xcorrelate

    Shift beam positions by cross correlating images. (bool; default:  False) [default=False].
.. py:attribute:: visir_util_convert_pos.param.brightest

    Shift beam positions by brightest pixel. (bool; default: True) [default=True].
.. py:attribute:: visir_util_convert_pos.param.window

    Window around detected beams to use for cross correlation. (long;  default: 64) [default=64].


The following code snippet shows the default settings for the available 
parameters.

::

   import cpl
   visir_util_convert_pos = cpl.Recipe("visir_util_convert_pos")

   visir_util_convert_pos.param.eccmax = 0.25
   visir_util_convert_pos.param.naverage = 1
   visir_util_convert_pos.param.xcorrelate = False
   visir_util_convert_pos.param.brightest = True
   visir_util_convert_pos.param.window = 64


You may also set or overwrite some or all parameters by the recipe 
parameter `param`, as shown in the following example:

::

   import cpl
   visir_util_convert_pos = cpl.Recipe("visir_util_convert_pos")
   [...]
   res = visir_util_convert_pos( ..., param = {"eccmax":0.25, "naverage":1})


.. seealso:: `cpl.Recipe <http://packages.python.org/python-cpl/recipe.html>`_
   for more information about the recipe object.

Bug reports
-----------

Please report any problems to `Lars Lundin <llundin@eso.org>`_. Alternatively, you may 
send a report to the `ESO User Support Department <usd-help@eso.org>`_.

Copyright
---------

This file is part of the VISIR Instrument Pipeline
Copyright (C) 2011 European Southern Observatory

This program 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 2 of the License, or
(at your option) any later version.

This program 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 this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, 
MA  02111-1307  USA

.. codeauthor:: Lars Lundin <llundin@eso.org>
