KMOS Pipeline Reference Manual  1.3.11
kmo_fits_stack.c
00001 /*
00002  * This file is part of the KMOS Pipeline
00003  * Copyright (C) 2002,2003 European Southern Observatory
00004  *
00005  * This program is free software; you can redistribute it and/or modify
00006  * it under the terms of the GNU General Public License as published by
00007  * the Free Software Foundation; either version 2 of the License, or
00008  * (at your option) any later version.
00009  *
00010  * This program is distributed in the hope that it will be useful,
00011  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00012  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00013  * GNU General Public License for more details.
00014  *
00015  * You should have received a copy of the GNU General Public License
00016  * along with this program; if not, write to the Free Software
00017  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
00018  */
00019 
00020 #ifdef HAVE_CONFIG_H
00021 #include <config.h>
00022 #endif
00023 
00024 /*-----------------------------------------------------------------------------
00025  *                              Includes
00026  *----------------------------------------------------------------------------*/
00027 
00028 #include <cpl.h>
00029 
00030 #include "kmo_utils.h"
00031 #include "kmo_dfs.h"
00032 #include "kmo_priv_fits_stack.h"
00033 #include "kmo_error.h"
00034 
00035 /*-----------------------------------------------------------------------------
00036  *                          Functions prototypes
00037  *----------------------------------------------------------------------------*/
00038 
00039 static int kmo_fits_stack_create(cpl_plugin *);
00040 static int kmo_fits_stack_exec(cpl_plugin *);
00041 static int kmo_fits_stack_destroy(cpl_plugin *);
00042 static int kmo_fits_stack(cpl_parameterlist *, cpl_frameset *);
00043 
00044 /*-----------------------------------------------------------------------------
00045  *                          Static variables
00046  *----------------------------------------------------------------------------*/
00047 
00048 static char kmo_fits_stack_description[] =
00049 "     #############################################\n"
00050 "     ### INTENDED FOR PIPELINE DEVELOPERS ONLY ###\n"
00051 "     #############################################\n"
00052 "\n"
00053 "FITS files to be processed by the KMOS pipeline have to meet certain condi-\n"
00054 "tions. This recipe is intended to provide to the user a simple way to test the\n"
00055 "pipeline with own data, which wasn't produced by KMOS itself.\n"
00056 "\n"
00057 "The input set of frame is checked for integrity (do all the frames have the\n"
00058 "same size, do they correspond to the desired output type, is there the correct\n"
00059 "number of files). Then an empty main header is written with desired keywords.\n"
00060 "A keyword consists of the name, data type and value.\n"
00061 "Additional keywords can be added either to the empty primary header or to all\n"
00062 "sub headers. \n"
00063 "\n"
00064 "BASIC PARAMETERS:\n"
00065 "-----------------\n"
00066 "--type\n"
00067 "Depending on the type of the FITS file to create different combinations of\n"
00068 "frames have to be provided:\n"
00069 "   * RAW\n"
00070 "     exactly 3 files tagged as STACK_DATA\n"
00071 "   * F2D\n"
00072 "     exactly 3 files tagged as STACK_DATA or\n"
00073 "     exactly 6 files tagged alternating as STACK_DATA and STACK_NOISE\n"
00074 "     (beginning with DATA)\n"
00075 "   * B2D\n"
00076 "     exactly 3 files tagged as STACK_BADPIX\n"
00077 "   * F1I, F2I, F3I\n"
00078 "     as many DATA frames as wanted (at least one) or\n"
00079 "     as many DATA and NOISE frames as wanted (at least one of each, the number\n"
00080 "     of STACK_DATA frames has to match the one of STACK_NOISE frames)\n"
00081 "   * F1S\n"
00082 "     exactly 1 file tagged as STACK_DATA\n"
00083 "   * F1L\n"
00084 "     exactly 1 file tagged as STACK_DATA (either plain text or binary fits\n"
00085 "     table)\n"
00086 "   * F2L\n"
00087 "     exactly 1 file tagged as STACK_DATA (either plain text or binary fits)\n"
00088 "     table)\n"
00089 "\n"
00090 "--mainkey\n"
00091 "--subkey\n"
00092 "Additional keywords can be added either to the empty primary header or to all\n"
00093 "sub headers. Provided keywords must have following form:\n"
00094 "   \"keyword;type;value;keyword;type;value\" (no spaces inbetween!)\n"
00095 "Allowed values for type are: string, int, float, double, bool\n"
00096 "\n"
00097 "--valid\n"
00098 "With the –valid parameter one can specifiy which values should be handled as\n"
00099 "invalid by the pipeline. The keyword ESO OCS ARMi NOTUSED will be set accor-\n"
00100 "dingly. When it is set to \"none\" nothing will be added.\n"
00101 "\n"
00102 "-------------------------------------------------------------------------------\n"
00103 "  Input files:\n"
00104 "\n"
00105 "   DO                    KMOS                                                  \n"
00106 "   category              Type   Explanation                    Required #Frames\n"
00107 "   --------              -----  -----------                    -------- -------\n"
00108 "   STACK_DATA            <none> >= 1 plain FITS files             Y       1-n  \n"
00109 "   STACK_NOISE                  >= 1 plain FITS files             N       0,1-n\n"
00110 "   or                                                                          \n"
00111 "   STACK_BADPIXEL               3 plain FITS files                Y        3   \n"
00112 "\n"
00113 "  Output files:\n"
00114 "\n"
00115 "   DO                     KMOS\n"
00116 "   category               Type    Explanation\n"
00117 "   --------               -----   -----------\n"
00118 "   FITS_STACK             RAW or  Stacked KMOS FITS file             \n"
00119 "                          F1D or                                     \n"
00120 "                          F2D or                                     \n"
00121 "                          B2D or                                     \n"
00122 "                          F1I or                                     \n"
00123 "                          F2I or                                     \n"
00124 "                          F3I or                                     \n"
00125 "                          F1S or                                     \n"
00126 "                          F1L or                                     \n"
00127 "                          F2L                                        \n"
00128 "-------------------------------------------------------------------------------\n"
00129 "\n";
00130 
00131 /*-----------------------------------------------------------------------------
00132  *                              Functions code
00133  *----------------------------------------------------------------------------*/
00134 
00151 int cpl_plugin_get_info(cpl_pluginlist *list)
00152 {
00153     cpl_recipe *recipe = cpl_calloc(1, sizeof *recipe);
00154     cpl_plugin *plugin = &recipe->interface;
00155 
00156     cpl_plugin_init(plugin,
00157                         CPL_PLUGIN_API,
00158                         KMOS_BINARY_VERSION,
00159                         CPL_PLUGIN_TYPE_RECIPE,
00160                         "kmo_fits_stack",
00161                         "Creates KMOS conform fits-files",
00162                         kmo_fits_stack_description,
00163                         "Alex Agudo Berbel",
00164                         "usd-help@eso.org",
00165                         kmos_get_license(),
00166                         kmo_fits_stack_create,
00167                         kmo_fits_stack_exec,
00168                         kmo_fits_stack_destroy);
00169 
00170     cpl_pluginlist_append(list, plugin);
00171 
00172     return 0;
00173 }
00174 
00182 static int kmo_fits_stack_create(cpl_plugin *plugin)
00183 {
00184     cpl_recipe *recipe;
00185     cpl_parameter *p;
00186 
00187     /* Check that the plugin is part of a valid recipe */
00188     if (cpl_plugin_get_type(plugin) == CPL_PLUGIN_TYPE_RECIPE) 
00189         recipe = (cpl_recipe *)plugin;
00190     else
00191         return -1;
00192 
00193     /* Create the parameters list in the cpl_recipe object */
00194     recipe->parameters = cpl_parameterlist_new();
00195 
00196     /* Fill the parameters list */
00197     /* --type */
00198     p = cpl_parameter_new_value("kmos.kmo_fits_stack.type",
00199                                 CPL_TYPE_STRING,
00200                                 "The KMOS data format type (either \"RAW\", "
00201                                 "\"F1D\", \"F2D\", \"F1I\", \"F2I\", \"F3I\", "
00202                                 "\"F1S\", \"F1L\", \"F2L\")",
00203                                 "kmos.kmo_fits_stack",
00204                                 "");
00205     cpl_parameter_set_alias(p, CPL_PARAMETER_MODE_CLI, "type");
00206     cpl_parameter_disable(p, CPL_PARAMETER_MODE_ENV);
00207     cpl_parameterlist_append(recipe->parameters, p);
00208 
00209     /* --format */
00210     p = cpl_parameter_new_value("kmos.kmo_fits_stack.format",
00211                                 CPL_TYPE_STRING,
00212                                 "The format of the columns for \"F1L\" and "
00213                                 "\"F2L\" frames: e.g. \"%f;%f;%s\"",
00214                                 "kmos.kmo_fits_stack",
00215                                 "");
00216     cpl_parameter_set_alias(p, CPL_PARAMETER_MODE_CLI, "format");
00217     cpl_parameter_disable(p, CPL_PARAMETER_MODE_ENV);
00218     cpl_parameterlist_append(recipe->parameters, p);
00219 
00220     /* --title */
00221     p = cpl_parameter_new_value("kmos.kmo_fits_stack.title",
00222                                 CPL_TYPE_STRING,
00223                                 "The titles of the columns for \"F1L\" and "
00224                                 "\"F2L\" frames: e.g. \"wavelength;strength\"",
00225                                 "kmos.kmo_fits_stack",
00226                                 "");
00227     cpl_parameter_set_alias(p, CPL_PARAMETER_MODE_CLI, "title");
00228     cpl_parameter_disable(p, CPL_PARAMETER_MODE_ENV);
00229     cpl_parameterlist_append(recipe->parameters, p);
00230 
00231     /* --filename */
00232     p = cpl_parameter_new_value("kmos.kmo_fits_stack.filename",
00233                                 CPL_TYPE_STRING,
00234                                 "Optional: The output filename (.fits will be "
00235                                                             "added as postfix)",
00236                                 "kmos.kmo_fits_stack",
00237                                 FITS_STACK);
00238     cpl_parameter_set_alias(p, CPL_PARAMETER_MODE_CLI, "filename");
00239     cpl_parameter_disable(p, CPL_PARAMETER_MODE_ENV);
00240     cpl_parameterlist_append(recipe->parameters, p);
00241 
00242     /* --mainkey */
00243     p = cpl_parameter_new_value("kmos.kmo_fits_stack.mainkey",
00244                              CPL_TYPE_STRING,
00245                              "Optional: Additional keywords for primary header",
00246                              "kmos.kmo_fits_stack",
00247                              "");
00248     cpl_parameter_set_alias(p, CPL_PARAMETER_MODE_CLI, "mainkey");
00249     cpl_parameter_disable(p, CPL_PARAMETER_MODE_ENV);
00250     cpl_parameterlist_append(recipe->parameters, p);
00251 
00252     /* --subkey */
00253     p = cpl_parameter_new_value("kmos.kmo_fits_stack.subkey",
00254                                 CPL_TYPE_STRING,
00255                                 "Optional: Additional keywords for sub headers"
00256                                 "(This is ignored when category=TRUE)",
00257                                 "kmos.kmo_fits_stack",
00258                                 "");
00259     cpl_parameter_set_alias(p, CPL_PARAMETER_MODE_CLI, "subkey");
00260     cpl_parameter_disable(p, CPL_PARAMETER_MODE_ENV);
00261     cpl_parameterlist_append(recipe->parameters, p);
00262 
00263     /* --valid */
00264     p = cpl_parameter_new_value("kmos.kmo_fits_stack.valid",
00265                                 CPL_TYPE_STRING,
00266                                 "Optional: Specify which IFUs are active. "
00267                                 "Either empty string or string with 24 elements"
00268                                 " (ones or zeros) e.g: [1;0;1;0;0;...;1]",
00269                                 "kmos.kmo_fits_stack",
00270                                 "");
00271     cpl_parameter_set_alias(p, CPL_PARAMETER_MODE_CLI, "valid");
00272     cpl_parameter_disable(p, CPL_PARAMETER_MODE_ENV);
00273     cpl_parameterlist_append(recipe->parameters, p);
00274 
00275     /* --category */
00276     p = cpl_parameter_new_value("kmos.kmo_fits_stack.category",
00277                                 CPL_TYPE_BOOL,
00278                                 "Optional: IF a PRO.CATG should be added.",
00279                                 "kmos.kmo_fits_stack",
00280                                 0);
00281     cpl_parameter_set_alias(p, CPL_PARAMETER_MODE_CLI, "category");
00282     cpl_parameter_disable(p, CPL_PARAMETER_MODE_ENV);
00283     cpl_parameterlist_append(recipe->parameters, p);
00284 
00285     /* --input */
00286     p = cpl_parameter_new_value("kmos.kmo_fits_stack.input",
00287                                 CPL_TYPE_STRING,
00288                                 "Optional: input file",
00289                                 "kmos.kmo_fits_stack",
00290                                 "");
00291     cpl_parameter_set_alias(p, CPL_PARAMETER_MODE_CLI, "input");
00292     cpl_parameter_disable(p, CPL_PARAMETER_MODE_ENV);
00293     cpl_parameterlist_append(recipe->parameters, p);
00294 
00295     return 0;
00296 }
00297 
00303 static int kmo_fits_stack_exec(cpl_plugin *plugin)
00304 {
00305     cpl_recipe  *recipe;
00306 
00307     /* Get the recipe out of the plugin */
00308     if (cpl_plugin_get_type(plugin) == CPL_PLUGIN_TYPE_RECIPE) 
00309         recipe = (cpl_recipe *)plugin;
00310     else return -1;
00311 
00312     return kmo_fits_stack(recipe->parameters, recipe->frames);
00313 }
00314 
00320 static int kmo_fits_stack_destroy(cpl_plugin *plugin)
00321 {
00322     cpl_recipe *recipe;
00323 
00324     /* Get the recipe out of the plugin */
00325     if (cpl_plugin_get_type(plugin) == CPL_PLUGIN_TYPE_RECIPE) 
00326         recipe = (cpl_recipe *)plugin;
00327     else return -1 ;
00328 
00329     cpl_parameterlist_delete(recipe->parameters);
00330     return 0 ;
00331 }
00332 
00347 static int kmo_fits_stack(cpl_parameterlist *parlist, cpl_frameset *frameset)
00348 {
00349     int ret_val = 0;
00350 
00351     KMO_TRY
00352     {
00353         ret_val = kmo_priv_fits_stack(parlist, frameset);
00354         KMO_TRY_CHECK_ERROR_STATE();
00355     }
00356     KMO_CATCH
00357     {
00358         KMO_CATCH_MSG();
00359 
00360         ret_val = -1;
00361     }
00362 
00363     return ret_val;
00364 }
00365