irplib_utils.h

00001 /* $Id: irplib_utils.h,v 1.53 2011/05/09 07:51:18 llundin Exp $
00002  *
00003  * This file is part of the irplib package
00004  * Copyright (C) 2002,2003 European Southern Observatory
00005  *
00006  * This program is free software; you can redistribute it and/or modify
00007  * it under the terms of the GNU General Public License as published by
00008  * the Free Software Foundation; either version 2 of the License, or
00009  * (at your option) any later version.
00010  *
00011  * This program is distributed in the hope that it will be useful,
00012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00014  * GNU General Public License for more details.
00015  *
00016  * You should have received a copy of the GNU General Public License
00017  * along with this program; if not, write to the Free Software
00018  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02111-1307  USA
00019  */
00020 
00021 /*
00022  * $Author: llundin $
00023  * $Date: 2011/05/09 07:51:18 $
00024  * $Revision: 1.53 $
00025  * $Name: visir-3_4_4 $
00026  * $Log: irplib_utils.h,v $
00027  * Revision 1.53  2011/05/09 07:51:18  llundin
00028  * irplib_dfs_save_image_(): Modified from cpl_dfs_save_image(). irplib_dfs_save_image(): Use irplib_dfs_save_image_()
00029  *
00030  * Revision 1.52  2010/03/23 07:57:59  kmirny
00031  * DFS08552, Documentation for irplib_frameset_sort
00032  *
00033  * Revision 1.51  2009/12/16 14:59:30  cgarcia
00034  * Avoid name clash with index function
00035  *
00036  * Revision 1.50  2009/08/17 15:10:16  kmirny
00037  *
00038  * DFS07454 DFS07437
00039  *
00040  */
00041 
00042 #ifndef IRPLIB_UTILS_H
00043 #define IRPLIB_UTILS_H
00044 
00045 /*-----------------------------------------------------------------------------
00046                                    Includes
00047  -----------------------------------------------------------------------------*/
00048 
00049 #include <stdarg.h>
00050 
00051 #include <cpl.h>
00052 
00053 /*-----------------------------------------------------------------------------
00054                                    Define
00055  -----------------------------------------------------------------------------*/
00056 
00057 #define IRPLIB_XSTRINGIFY(TOSTRING) #TOSTRING
00058 #define IRPLIB_STRINGIFY(TOSTRING) IRPLIB_XSTRINGIFY(TOSTRING)
00059 
00060 /* FIXME: Remove when no longer used by any irplib-based pipelines */
00061 /* Useful for debugging */
00062 #define irplib_trace()  do if (cpl_error_get_code()) { \
00063     cpl_msg_debug(cpl_func, __FILE__ " at line %d: ERROR '%s' at %s", \
00064          __LINE__, cpl_error_get_message(), cpl_error_get_where()); \
00065   } else { \
00066     cpl_msg_debug(cpl_func, __FILE__ " at line %d: OK", __LINE__); \
00067   } while (0)
00068 
00069 #define irplib_error_recover(ESTATE, ...)                                      \
00070     do if (!cpl_errorstate_is_equal(ESTATE)) {                                 \
00071         cpl_msg_warning(cpl_func, __VA_ARGS__);                                \
00072         cpl_msg_indent_more();                                                 \
00073         cpl_errorstate_dump(ESTATE, CPL_FALSE, irplib_errorstate_warning);     \
00074         cpl_msg_indent_less();                                                 \
00075         cpl_errorstate_set(ESTATE);                                            \
00076     } while (0)
00077 
00078 
00079 
00080 /*----------------------------------------------------------------------------*/
00081 /*
00082   @brief Declare a function suitable for use with irplib_dfs_table_convert()
00083   @param  table_set_row    The name of the function to declare
00084   @see irplib_dfs_table_convert(), irplib_table_read_from_frameset()
00085 
00086 */
00087 /*----------------------------------------------------------------------------*/
00088 #define IRPLIB_UTIL_SET_ROW(table_set_row)                      \
00089     cpl_boolean table_set_row(cpl_table *,                      \
00090                               const char *,                     \
00091                               int,                              \
00092                               const cpl_frame *,                \
00093                               const cpl_parameterlist *)
00094 
00095 
00096 /*----------------------------------------------------------------------------*/
00097 /*
00098   @brief Declare a function suitable for use with irplib_dfs_table_convert()
00099   @param  table_check    The name of the function to declare
00100   @see irplib_dfs_table_convert()
00101 
00102 */
00103 /*----------------------------------------------------------------------------*/
00104 #define IRPLIB_UTIL_CHECK(table_check)                          \
00105     cpl_error_code table_check(cpl_table *,                     \
00106                                const cpl_frameset *,            \
00107                                const cpl_parameterlist *)
00108 
00109 
00110 /*----------------------------------------------------------------------------*/
00111 /*
00112   @brief   Conditional skip to the (unqiue) return point of the function
00113   @param   CONDITION    The condition to check
00114   @see cpl_error_ensure()
00115 
00116   skip_if() takes one argument, which is a logical expression.
00117   If the logical expression is false skip_if() takes no action and
00118   program execution continues.
00119   If the logical expression is true this indicates an error. In this case
00120   skip_if() will set the location of the error to the point where it
00121   was invoked in the recipe code (unless the error location is already in the
00122   recipe code). If no error code had been set, then skip_if() will set one.
00123   Finally, skip_if() causes program execution to skip to the macro 'end_skip'.
00124   The macro end_skip is located towards the end of the function, after
00125   which all resource deallocation and the function return is located.
00126 
00127   The use of skip_if() assumes the following coding practice:
00128   1) Pointers used for dynamically allocated memory that they "own" shall always
00129      point to either NULL or to allocated memory (including CPL-objects).
00130   2) Such pointers may not be reused to point to memory whose deallocation
00131      requires calls to different functions.
00132   3) Pointers of type FILE should be set NULL when not pointing to an open
00133      stream and their closing calls (fclose(), freopen(), etc.) following the
00134      'end_skip' should be guarded against such NULL pointers.
00135 
00136   Error checking with skip_if() is encouraged due to the following advantages:
00137   1) It ensures that a CPL-error code is set.
00138   2) It ensures that the location of the error in the _recipe_ code is noted.
00139   3) The error checking may be confined to a single concise line.
00140   4) It is not necessary to replicate memory deallocation for every error
00141      condition.
00142   5) If more extensive error reporting/handling is required it is not precluded
00143      by the use of skip_if().
00144   6) It allows for a single point of function return.
00145   7) It allows for optional, uniformly formatted debugging/tracing information
00146      at each macro invocation.
00147 
00148   The implementation of skip_if() uses a goto/label construction.
00149   According to Kerningham & Ritchie, The C Programming Language, 2nd edition,
00150   Section 3.8:
00151   "This organization is handy if the error-handling code is non-trivial,
00152   and if errors can occur in several places."
00153 
00154   The use of goto for any other purpose should be avoided.
00155 
00156 */
00157 /*----------------------------------------------------------------------------*/
00158 #define skip_if(CONDITION)                                                     \
00159     do {                                                                       \
00160         cpl_error_ensure(!cpl_error_get_code(), cpl_error_get_code(),          \
00161                          goto cleanup, "Propagating a pre-existing error");    \
00162         cpl_error_ensure(!(CONDITION), cpl_error_get_code(),                   \
00163                          goto cleanup, "Propagating error");\
00164     } while (0)
00165 
00166 /*----------------------------------------------------------------------------*/
00167 /*
00168   @brief   Skip if A < B
00169   @param   A   The 1st double to compare
00170   @param   B   The 2nd double to compare
00171   @param   MSG The message to use on failure
00172   @see skip_if()
00173   @note A and B are evaluated exactly once
00174 */
00175 /*----------------------------------------------------------------------------*/
00176 #define skip_if_lt(A, B, MSG)                                                  \
00177     do {                                                                       \
00178         const double tmpa = (double)(A);                                       \
00179         const double tmpb = (double)(B);                                       \
00180                                                                                \
00181         cpl_error_ensure(!cpl_error_get_code(), cpl_error_get_code(),          \
00182                          goto cleanup, "Propagating a pre-existing error");    \
00183         cpl_error_ensure(tmpa >= tmpb, CPL_ERROR_DATA_NOT_FOUND,               \
00184                          goto cleanup, "Need at least %g (not %g) %s",         \
00185                          tmpb, tmpa, MSG);                                     \
00186     } while (0)
00187 
00188 /*----------------------------------------------------------------------------*/
00189 /*
00190   @brief   Conditional skip on coding bug
00191   @param   CONDITION    The condition to check
00192   @see skip_if()
00193   @note unlike assert() this check cannot be disabled
00194  */
00195 /*----------------------------------------------------------------------------*/
00196 #define bug_if(CONDITION)                                                      \
00197     do {                                                                       \
00198         cpl_error_ensure(!cpl_error_get_code(), cpl_error_get_code(),          \
00199                          goto cleanup, "Propagating an unexpected error, "     \
00200                          "please report to " PACKAGE_BUGREPORT);               \
00201         cpl_error_ensure(!(CONDITION), CPL_ERROR_UNSPECIFIED,                  \
00202                          goto cleanup, "Internal error, please report to "     \
00203                          PACKAGE_BUGREPORT);                                   \
00204     } while (0)
00205 
00206 /*----------------------------------------------------------------------------*/
00207 /*
00208   @brief   Conditional skip with error creation
00209   @param   CONDITION    The condition to check
00210   @param   ERROR        The error code to set
00211   @param   MSG          A printf-style error message. As a matter of
00212                         user-friendliness the message should mention any
00213                         value that caused the @em CONDITION to fail.
00214   @see skip_if()
00215   @note unlike assert() this check cannot be disabled
00216  */
00217 /*----------------------------------------------------------------------------*/
00218 #define error_if(CONDITION, ERROR, ...)                                 \
00219     cpl_error_ensure(cpl_error_get_code() == CPL_ERROR_NONE &&          \
00220                      !(CONDITION), ERROR, goto cleanup,  __VA_ARGS__)
00221 
00222 /*----------------------------------------------------------------------------*/
00223 /*
00224   @brief   Propagate a preexisting error, if any
00225   @param   MSG          A printf-style error message.
00226   @see skip_if()
00227  */
00228 /*----------------------------------------------------------------------------*/
00229 #define any_if(...)                                                     \
00230     cpl_error_ensure(!cpl_error_get_code(), cpl_error_get_code(),       \
00231                      goto cleanup,  __VA_ARGS__)
00232 
00233 /*----------------------------------------------------------------------------*/
00234 /*
00235   @brief   Define the single point of resource deallocation and return
00236   @see skip_if()
00237   @note end_skip should be used exactly once in functions that use skip_if() etc
00238 */
00239 /*----------------------------------------------------------------------------*/
00240 #define end_skip \
00241     do {                                                                     \
00242         cleanup:                                                             \
00243         if (cpl_error_get_code())                                            \
00244             cpl_msg_debug(cpl_func, "Cleanup in " __FILE__ " line %u with "  \
00245                           "error '%s' at %s", __LINE__,                      \
00246                           cpl_error_get_message(), cpl_error_get_where());   \
00247         else                                                                 \
00248             cpl_msg_debug(cpl_func, "Cleanup in " __FILE__ " line %u",       \
00249                           __LINE__);                                         \
00250     } while (0)
00251 
00252 
00253 /*----------------------------------------------------------------------------*/
00265 /*----------------------------------------------------------------------------*/
00266 #define irplib_ensure(CONDITION, ec, ...)                                      \
00267     cpl_error_ensure(CONDITION, ec, goto cleanup,  __VA_ARGS__)
00268 
00269 /*----------------------------------------------------------------------------*/
00299 /*----------------------------------------------------------------------------*/
00300 
00301 #define irplib_check(COMMAND, ...)                                             \
00302   do {                                                                         \
00303     cpl_errorstate irplib_check_prestate = cpl_errorstate_get();               \
00304     skip_if(0);                                                                \
00305     COMMAND;                                                                   \
00306         irplib_trace(); \
00307     irplib_ensure(cpl_errorstate_is_equal(irplib_check_prestate),              \
00308                   cpl_error_get_code(), __VA_ARGS__);                          \
00309         irplib_trace(); \
00310   } while (0)
00311 
00312 /*-----------------------------------------------------------------------------
00313                                    Function prototypes
00314  -----------------------------------------------------------------------------*/
00315 
00316 cpl_error_code irplib_dfs_save_image(cpl_frameset            *,
00317                                      const cpl_parameterlist *,
00318                                      const cpl_frameset      *,
00319                                      const cpl_image         *,
00320                                      cpl_type_bpp             ,
00321                                      const char              *,
00322                                      const char              *,
00323                                      const cpl_propertylist  *,
00324                                      const char              *,
00325                                      const char              *,
00326                                      const char              *);
00327 
00328 
00329 cpl_error_code irplib_dfs_save_propertylist(cpl_frameset            *,
00330                                             const cpl_parameterlist *,
00331                                             const cpl_frameset      *,
00332                                             const char              *,
00333                                             const char              *,
00334                                             const cpl_propertylist  *,
00335                                             const char              *,
00336                                             const char              *,
00337                                             const char              *);
00338 
00339 cpl_error_code irplib_dfs_save_imagelist(cpl_frameset            *,
00340                                          const cpl_parameterlist *,
00341                                          const cpl_frameset      *,
00342                                          const cpl_imagelist     *,
00343                                          cpl_type_bpp             ,
00344                                          const char              *,
00345                                          const char              *,
00346                                          const cpl_propertylist  *,
00347                                          const char              *,
00348                                          const char              *,
00349                                          const char              *);
00350 
00351 cpl_error_code irplib_dfs_save_table(cpl_frameset            *,
00352                                      const cpl_parameterlist *,
00353                                      const cpl_frameset      *,
00354                                      const cpl_table         *,
00355                                      const cpl_propertylist  *,
00356                                      const char              *,
00357                                      const char              *,
00358                                      const cpl_propertylist  *,
00359                                      const char              *,
00360                                      const char              *,
00361                                      const char              *);
00362 
00363 cpl_error_code irplib_dfs_save_image_(cpl_frameset            *,
00364                                       cpl_propertylist        *,
00365                                       const cpl_parameterlist *,
00366                                       const cpl_frameset      *,
00367                                       const cpl_frame         *,
00368                                       const cpl_image         *,
00369                                       cpl_type                 ,
00370                                       const char              *,
00371                                       const cpl_propertylist  *,
00372                                       const char              *,
00373                                       const char              *,
00374                                       const char              *);
00375 
00376 void irplib_reset(void);
00377 int irplib_compare_tags(cpl_frame *, cpl_frame *);
00378 const char * irplib_frameset_find_file(const cpl_frameset *, const char *);
00379 const cpl_frame * irplib_frameset_get_first_from_group(const cpl_frameset *,
00380                                                        cpl_frame_group);
00381 
00382 cpl_error_code irplib_apertures_find_max_flux(const cpl_apertures *, int *,
00383                                               int);
00384 
00385 int irplib_isinf(double value);
00386 int irplib_isnan(double value);
00387 
00388 void irplib_errorstate_warning(unsigned, unsigned, unsigned);
00389 
00390 cpl_error_code
00391 irplib_dfs_table_convert(cpl_table *, cpl_frameset *, const cpl_frameset *,
00392                          int, char, const char *, const char *,
00393                          const cpl_parameterlist *, const char *,
00394                          const cpl_propertylist *, const cpl_propertylist *,
00395                          const char *, const char *, const char *,
00396                          cpl_boolean (*)(cpl_table *, const char *, int,
00397                                             const cpl_frame *,
00398                                             const cpl_parameterlist *),
00399                          cpl_error_code (*)(cpl_table *,
00400                                             const cpl_frameset *,
00401                                             const cpl_parameterlist *));
00402 
00403 cpl_error_code irplib_table_read_from_frameset(cpl_table *,
00404                                                const cpl_frameset *,
00405                                                int,
00406                                                char,
00407                                                const cpl_parameterlist *,
00408                                                cpl_boolean (*)
00409                                                (cpl_table *, const char *,
00410                                                 int, const cpl_frame *,
00411                                                 const cpl_parameterlist *));
00412 
00413 cpl_error_code irplib_image_split(const cpl_image *,
00414                                   cpl_image *, cpl_image *, cpl_image *,
00415                                   double, cpl_boolean,
00416                                   double, cpl_boolean,
00417                                   double, double,
00418                                   cpl_boolean, cpl_boolean, cpl_boolean);
00419 
00420 void irplib_errorstate_dump_warning(unsigned, unsigned, unsigned);
00421 void irplib_errorstate_dump_info(unsigned, unsigned, unsigned);
00422 void irplib_errorstate_dump_debug(unsigned, unsigned, unsigned);
00423 /* wrapper for replace deprecated function cpl_polynomial_fit_1d_create*/
00424 cpl_polynomial * irplib_polynomial_fit_1d_create(
00425         const cpl_vector    *   x_pos,
00426         const cpl_vector    *   values,
00427         int                     degree,
00428         double              *   mse
00429         );
00430 cpl_polynomial * irplib_polynomial_fit_1d_create_chiq(
00431         const cpl_vector    *   x_pos,
00432         const cpl_vector    *   values,
00433         int                     degree,
00434         double              *   rechiq
00435         );
00436 /*----------------------------------------------------------------------------*/
00444 cpl_error_code irplib_frameset_sort(
00445         const cpl_frameset *  self,
00446         int* iindex,
00447         double* exptime);
00448 
00449 #endif

Generated on Thu May 12 12:12:19 2011 for VISIR Pipeline Reference Manual by  doxygen 1.4.7