eris_nix_img_stack.c

/* $Id$
 *
 * This file is part of the ERIS Pipeline
 * Copyright (C) 2017 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  02110-1301  USA
 */
 
/*
 * $Author$
 * $Date$
 * $Revision$
 */
 
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
 
/*-----------------------------------------------------------------------------
                                Includes
 -----------------------------------------------------------------------------*/
 
#include <libgen.h>
#include <math.h>
#include <string.h>
 
#include "casu_utils.h"
#include "casu_mods.h"
 
#include "eris_nix_utils.h"
#include "eris_nix_casu_utils.h"
#include "eris_nix_dfs.h"
#include <hdrl.h>
 
#include <cpl.h>
 
/*-----------------------------------------------------------------------------
                            Static variables
 -----------------------------------------------------------------------------*/
 
static const char eris_nix_img_stack_description[] =
"This recipe rebins a set of calibrated ERIS/NIX jitter frames to a\n"
"common grid and stacks them.\n"
"\n"
"Input files:\n"
"\n"
"  DO CATG                         Explanation             Req.  #Frames\n"
"  -------                         -----------             ---   -------\n"
"  "ERIS_NIX_CAL_PHOT_OBJECT_JITTER_PRO_CATG
                                 " calibrated frames        Y      1-n\n"
"                                  to be stacked.\n"
"             or\n"
"  "ERIS_NIX_CAL_PHOT_STD_JITTER_PRO_CATG
                              "    calibrated standard      Y      1-n\n"
"                                  frames to be stacked.\n"
"\n"
"Output files:\n"
"\n"
"  DO CATG                         Explanation \n"
"  -------                         ----------- \n"
"  "ERIS_NIX_IMG_OBS_COMBINED_PRO_CATG
                           "       the stacked image of the target.\n"
"             or\n"
"  "ERIS_NIX_IMG_STD_COMBINED_PRO_CATG
                           "       the stacked image of the standard.\n"
"\n"
"  The output will be FITS files named 'stack.<first input filename>',\n"
"  containing extensions:\n"
"  - DATA, with the stacked target or standard data.\n"
"  - ERR, with the error plane.\n"
"  - DQ, with the stacked image quality\n"
"  - CONFIDENCE, with the target confidence plane.\n"
"\n"
"  The output file can be split into smaller components, see\n"
"  param --split-output-file.\n"
"\n"
"Notes on the method.\n"
" The stacking is done by a CASU routine, the relevant part\n"
" of whose description is:\n"
"  'A list of frames is given. A mean image is stacked by using the\n"
"   given WCS to work out the shift of an input pixel relative to the\n"
"   grid defined by the first image in the list. At first all are\n"
"   stacked using a nearest neighbour algorithm. Any discordant pixels\n"
"   are marked at this stage. If a different stacking algorithm is\n"
"   required, then the images are restacked, but with the discordant\n"
"   pixels found earlier removed.\n"
"\n";
 
#define RECIPE_NAME "eris.eris_nix_img_stack"
 
/*-----------------------------------------------------------------------------
                            Private function prototypes
 -----------------------------------------------------------------------------*/
 
cpl_recipe_define(eris_nix_img_stack, ERIS_BINARY_VERSION, "John Lightfoot",
                  PACKAGE_BUGREPORT, "2017",
                  "Stack calibrated ERIS/NIX jitter frames",
                  eris_nix_img_stack_description);
 
/*-----------------------------------------------------------------------------
                                Function code
 -----------------------------------------------------------------------------*/
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
static cpl_error_code eris_nix_img_stack_fill_parameterlist(
  cpl_parameterlist * self) {
 
    if (cpl_error_get_code() != CPL_ERROR_NONE) return cpl_error_get_code();
 
    hdrl_parameter    * catalogue_defaults = NULL;
    cpl_parameterlist * catalogue_parlist = NULL;
    cpl_parameter     * p = NULL;
 
    /* The lower rejection threshold to be used during stacking */
 
    p = cpl_parameter_new_range(RECIPE_NAME".stk_lthr", CPL_TYPE_DOUBLE,
                                "Low rejection threshold", RECIPE_NAME,
                                5.0, 1.0e-6, 1.0e10);
    cpl_parameter_set_alias(p, CPL_PARAMETER_MODE_CLI, "stk-lthr");
    cpl_parameterlist_append(self, p);
 
    /* The upper rejection threshold to be used during stacking */
 
    p = cpl_parameter_new_range(RECIPE_NAME".stk_hthr", CPL_TYPE_DOUBLE,
                                "Upper rejection threshold", RECIPE_NAME,
                                5.0, 1.0e-6, 1.0e10);
    cpl_parameter_set_alias(p, CPL_PARAMETER_MODE_CLI, "stk-hthr");
    cpl_parameterlist_append(self, p);
 
    /* Stacking method */
 
    p = cpl_parameter_new_enum(RECIPE_NAME".stk_method", CPL_TYPE_STRING,
                               "The interpolation method", RECIPE_NAME,
                               "bi-linear", 2, "nearest neighbour",
                               "bi-linear");
    cpl_parameter_set_alias(p, CPL_PARAMETER_MODE_CLI, "stk-method");
    cpl_parameterlist_append(self, p);
 
    /* Stacking speed method */
 
    p = cpl_parameter_new_enum(RECIPE_NAME".stk_fast", CPL_TYPE_STRING,
                               "Use fast stacking? The fast algorithm "
                               "uses much more memory", RECIPE_NAME,
                               "auto", 3, "fast", "slow", "auto");
    cpl_parameter_set_alias(p, CPL_PARAMETER_MODE_CLI, "stk-fast");
    cpl_parameterlist_append(self, p);
 
    /* Number of frames above which we use the slow algorithm in auto mode */
 
    p = cpl_parameter_new_value(RECIPE_NAME".stk_nfst", CPL_TYPE_INT,
                                "nframes limit beyond which 'slow' "
                                "stacking is enforced", RECIPE_NAME, 30);
    cpl_parameter_set_alias(p, CPL_PARAMETER_MODE_CLI, "stk-nfst");
    cpl_parameterlist_append(self, p);
 
    /* tidy up */
 
    hdrl_parameter_delete(catalogue_defaults);
    cpl_parameterlist_delete(catalogue_parlist);
 
    return 0;
}
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
static int eris_nix_img_stack(cpl_frameset * frameset,
                              const cpl_parameterlist * parlist) {
 
    located_imagelist    * cal_jitters = NULL; 
    located_imagelist    * cal_object_jitters = NULL; 
    located_imagelist    * cal_std_jitters = NULL; 
    hdrl_parameter       * cat_params = NULL;
    const char           * funcid = "eris_nix_img_stack";
    mef_extension_list   * mefs = NULL;
    const cpl_parameter  * p = NULL;
    located_image        * stack = NULL;
    hdrl_image           * stack_image = NULL;
    cpl_frameset         * used = NULL;
 
    enu_check_error_code("%s():%d: An error is already set: %s",
      cpl_func, __LINE__, cpl_error_get_where());
 
    /* Check input parameters */
 
    cpl_ensure_code(frameset, CPL_ERROR_NULL_INPUT);
    cpl_ensure_code(parlist, CPL_ERROR_NULL_INPUT);
 
    /* Set the msg verbosity level from environment variable CPL_MSG_LEVEL
       - not working, so set manually for now */
 
    cpl_msg_set_level_from_env();
    cpl_msg_severity severity = cpl_msg_get_level();
    cpl_msg_info(funcid, "level %d", (int) severity);
 
    /* Retrieve input parameters */
 
    p = cpl_parameterlist_find_const(parlist, RECIPE_NAME".stk_lthr");
    const double stk_lthr = cpl_parameter_get_double(p);
    p = cpl_parameterlist_find_const(parlist, RECIPE_NAME".stk_hthr");
    const double stk_hthr = cpl_parameter_get_double(p);
    p = cpl_parameterlist_find_const(parlist, RECIPE_NAME".stk_method");
    const char * stk_method = cpl_parameter_get_string(p);
    p = cpl_parameterlist_find_const(parlist, RECIPE_NAME".stk_fast");
    const char * stk_fast_setting = cpl_parameter_get_string(p);
    p = cpl_parameterlist_find_const(parlist, RECIPE_NAME".stk_nfst");
    const int stk_nfst = cpl_parameter_get_int(p);
    enu_check_error_code("Could not retrieve input parameters");
 
    /* Identify the RAW and CALIB frames in the input frameset */
 
    eris_nix_dfs_set_groups(frameset);
    enu_check_error_code("Could not identify RAW and CALIB frames");    
 
    /* read the input frameset */
 
    used = cpl_frameset_new();
    cal_object_jitters = enu_limlist_load_from_frameset(frameset,
                  ERIS_NIX_CAL_PHOT_OBJECT_JITTER_PRO_CATG, used);
    cpl_msg_info(funcid, "read %d %s frames", (int) cal_object_jitters->size,
                 ERIS_NIX_CAL_PHOT_OBJECT_JITTER_PRO_CATG);
    cal_std_jitters = enu_limlist_load_from_frameset(frameset,
                      ERIS_NIX_CAL_PHOT_STD_JITTER_PRO_CATG, used);
    cpl_msg_info(funcid, "read %d %s frames", (int) cal_std_jitters->size,
                 ERIS_NIX_CAL_PHOT_STD_JITTER_PRO_CATG);
 
    /* is this a target object or standard? */
 
    enu_check(!(cal_object_jitters->size > 0 && cal_std_jitters->size > 0),
              CPL_ERROR_ILLEGAL_INPUT, 
              "SoF cannot contain data for both target and standard");
    enu_check(!(cal_object_jitters->size == 0 && cal_std_jitters->size == 0),
              CPL_ERROR_DATA_NOT_FOUND,
              "SoF contains no data");
    if(cal_object_jitters->size > 0) {
        cal_jitters = cal_object_jitters;
    } else {
        cal_jitters = cal_std_jitters;
    } 
 
    /* Set CASU stk_fast parameter appropriately */
 
    int stk_fast = 1;
    if (!strcmp(stk_fast_setting, "auto") && cal_jitters->size > stk_nfst) {
        stk_fast = 0;
    } else if (!strcmp(stk_fast_setting, "slow")) {
        stk_fast = 0;
    }
 
    /* Stack the jitter images */
 
    enu_stack(cal_jitters, stk_lthr, stk_hthr, stk_method, stk_fast,
              &stack);
    enu_check_error_code("error set after image stacking");
 
    /* generate name of file with stacked image */
 
    char * proto = cpl_strdup(cpl_frame_get_filename((cal_jitters->limages[0])->
                              frame);
    char * stack_fname = cpl_sprintf("stack.%s", basename(proto_copy));
 
    /* construct provenance frameset */
 
    cpl_frameset * provenance = cpl_frameset_new();
    for (cpl_size j=0; j<cal_jitters->size; j++) {
        cpl_frameset_insert(provenance, cpl_frame_duplicate(
                            cal_jitters->limages[j]->frame));        
    }
 
    /* update PRO.CATG and stack info */
 
    const char * out_tag = NULL;
    if (cal_object_jitters->size >0) {
        out_tag = ERIS_NIX_IMG_OBS_COMBINED_PRO_CATG;
    } else {
        out_tag = ERIS_NIX_IMG_STD_COMBINED_PRO_CATG;
    }
    cpl_propertylist_update_string(stack->plist, CPL_DFS_PRO_CATG, out_tag);
 
    int ncombine = cal_jitters->size;
    double total_exptime = 100.0;
    double mjd_start = 10000.0;
    double mjd_end = 11000.0;
    cpl_vector * obsid = cpl_vector_new(cal_jitters->size);
    for (cpl_size j=0; j < cal_jitters->size; j++) {
        cpl_vector_set(obsid, j, (double)j);
    }
    cpl_propertylist_update_int(stack->plist, "NCOMBINE", ncombine);
    cpl_propertylist_update_double(stack->plist, "TEXPTIME", total_exptime);
    cpl_propertylist_update_double(stack->plist, "MJD-OBS", mjd_start);
    cpl_propertylist_update_double(stack->plist, "MJD-END", mjd_end);
    for (cpl_size j = 0; j < cal_jitters->size; ++j) {
        char * pname = cpl_sprintf("OBID%.0i", (int)(j+1));
        cpl_msg_info(cpl_func, "%d %s", (int)j, pname);
        cpl_propertylist_update_int(stack->plist, pname,
                                    (int)cpl_vector_get(obsid, j));
        cpl_free(pname);
    }
 
    enu_limage_save(stack_fname, 
                    CPL_TRUE,
                    stack,
                    stack->frame,
                    stack->plist,
                    frameset,
                    RECIPE_NAME,
                    parlist,
                    used,
                    provenance);
 
    cpl_free(proto);
    cpl_free(stack_fname);
    cpl_frameset_delete(provenance);
 
cleanup:
    enu_located_imagelist_delete(cal_jitters);
    hdrl_parameter_delete(cat_params);
    enu_mef_extension_list_delete(mefs);
    hdrl_image_delete(stack_image);
    cpl_frameset_delete(used);
 
    return (int)cpl_error_get_code();
}