.. -*- coding: utf-8 -*-

.. _LDAC_tables:

=================================
 LDAC - Special LDAC Table Names
=================================

.. note::
   The concrete examples on this page use the LDAC catalogue 
   `D1_r_sex.cat <../_static/D1_r_sex.cat>`_.

   A tar archive with the complete set of LDAC Tools example files
   is `here <../_static/LDAC_Tools_Examples.tgz>`_

The LDAC format treats several table names specially. Two pairs are
**very** important for each user of the LDAC tools.

The *LDAC_IMHEAD* - *LDAC_OBJECTS* pair
=======================================
  
The `SExtractor`_ program produces with ``(-CATALOGUE_TYPE FITS_LDAC)``
an LDAC objects catalogue. The objects data are stored in the 
*LDAC_OBJECTS* table. The *LDAC_IMHEAD* table is a large ASCII table
with metadata such as the used SExtractor parameters and the image header. 
It can be displayed, but its individual entries cannot be accessed
easily. ::

  user$ ldacdesc -i D1_r_sex.cat -t LDAC_IMHEAD

  ****** Key #1
	 Key name:...............Field Header Card
	 Key comment:............                                               
	 Key type:...............String
	 Key dimension:..........2 (80 122)
            

  user$ ldactoasc -s -i D1_r_sex.cat -t LDAC_IMHEAD

  #   1 Field Header Card                                                  
  SIMPLE  =                    T / written by IMCAT  
  BITPIX  =                  -32 / 
  NAXIS   =                    2 /  

  .
  .

  SEXFBUFS=                 2048 / Image-buffer height (scanlines)
  SEXMWSCL=      4.345960617e-01 / Measurement-weight re-scaling factor
  SEXDWSCL=      1.078257799e+00 / Detection-weight re-scaling factor      
      
  user$ ldactoasc -s -i D1_r_sex.cat -t LDAC_IMHEAD | fold | grep SEXMINAR

  SEXMINAR=                    4 / Minimum area used for detection (pixels)

Note the necessity of the :command:`fold` command in the last 
:command:`ldactoasc` call if you want to isolate a certain entry!

Within :ref:`THELI` the *LDAC_OBJECTS* - *LDAC_IMHEAD* format is only
used to perform astrometric calibration with Emmanuel Bertins `scamp`_
program. Otherwise, the :command:`ldacconv` program is used to transform
the catalogue to the *FIELDS* - *OBJECTS* pair. 

The *FIELDS* - *OBJECTS* pair
=============================
  
The *FIELDS* - *OBJECTS* pair of LDAC tables contains similar
information as their *LDAC_IMHEAD* - *LDAC_OBJECTS*
cousins. However, the *FIELDS* table is a regular binary table whose
entries can be accessed and used in the standard way: ::

  user$ ldacconv 
  > SYNTAX: ldacconv
		-b camera_number
		-c camera_name 
		-f filter_name 
		-i Catalog1 Catalog2 ... [-o Output_catalog] [options]
   
  user$ ldacconv -i D1_r_sex.cat -o D1_r_ldac.cat -b 1 -c MEGAPRIME -f r

  user$ ldacdesc -i D1_r_ldac.cat 
  ------------------Catalog information----------------
  Filename:..............D1_r_ldac.cat
  Number of segments:....3
  
  .
  .
  
  ****** Table #2
  	 Extension type:.........BINTABLE
     	 Extension name:.........OBJECTS
  .
  .       
  
  ****** Table #3
  	 Extension type:.........BINTABLE
  	 Extension name:.........FIELDS
  .
  .

  user$ ldacdesc -i D1_r_ldac.cat -t FIELDS
  ****** Key #1
	 Key name:...............OBJECT_POS
	 Key comment:............Position of the first object from that field   
	 Key type:...............Long Int
	 Key dimension:..........0 
  .
  .
  ****** Key #98
  	 Key name:...............SEXMWSCL
  	 Key comment:............Measurement-weight re-scaling factor           
  	 Key type:...............Double
  	 Key dimension:..........0 
  ****** Key #99
  	 Key name:...............SEXDWSCL
  	 Key comment:............Detection-weight re-scaling factor             
  	 Key type:...............Double
  	 Key dimension:..........0 

  user$ ldactoasc -i D1_r_ldac.cat -t FIELDS -k SEXSFWHM SEXSATLV
  #   1 SEXSFWHM            Source FWHM used for measurements (arcsec)     
  #   2 SEXSATLV            Saturation level used for flagging (ADU)       
  0.7300000000 50000.00000

.. note::
  #. Traditionally the arguments '-b', '-v' and '-f' **must** be given to
     :command:`ldacconv`. The provided values are transferred to the *FIELDS*
     tablebut, as far as we know, their contents can be chosen arbitrarily. 
  #. Also for traditional reasons, the :command:`ldacconv` program translates
     several **important** keys when converting *LDAC_OBJECTS* to *OBJECTS*. 
     Those are:

       +-----------------------------+-----------+
       | SExtractor / LDAC_OBJECTS   | OBJECTS   |
       +=============================+===========+
       |     NUMBER                  | SeqNr     |
       +-----------------------------+-----------+
       |     X_IMAGE                 | Xpos      |
       +-----------------------------+-----------+
       |     Y_IMAGE                 | Ypos      |
       +-----------------------------+-----------+
       |     A_IMAGE                 | A         |
       +-----------------------------+-----------+
       |     B_IMAGE                 | B         |
       +-----------------------------+-----------+
       |     THETA_IMAGE             | Theta     |
       +-----------------------------+-----------+
       |     ISOAREA_IMAGE           | NPIX      |
       +-----------------------------+-----------+
       |     FLAGS                   | Flag      |
       +-----------------------------+-----------+    

.. warning::
  #. Do not manipulate the *FIELDS* table manually. It is closely linked to
     the *OBJECTS* table and it is used for important, internal bookkeeping!
     Programs that manipulate the *OBJECTS* table in a significant way such
     as :command:`ldacpaste` or :command:`ldacsplit` ensure the integrity
     of *FIELDS*!
  #. Do not use the :command:`ldacrentab` command to rename an LDAC table
     to one with the special names given above, especially **NOT** to
     an *OBJECTS* table! The non-presence of a well formatted *FIELDS* table
     often leads to difficult to spot errors in subsequent processing!
     It is similarily bad to rename special LDAC tables to something else.

.. include:: links.txt