"Fossies" - the Fresh Open Source Software Archive

Member "fimex-1.4.1/include/fimex/c_fimex.h" (30 Oct 2019, 15464 Bytes) of package /linux/privat/fimex-1.4.1.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "c_fimex.h" see the Fossies "Dox" file reference documentation.

    1 /*
    2  * Fimex, c_fimex.h
    3  *
    4  * (C) Copyright 2009, met.no
    5  *
    6  * Project Info:  https://wiki.met.no/fimex/start
    7  *
    8  * This library is free software; you can redistribute it and/or modify it
    9  * under the terms of the GNU Lesser General Public License as published by
   10  * the Free Software Foundation; either version 2.1 of the License, or
   11  * (at your option) any later version.
   12  *
   13  * This library is distributed in the hope that it will be useful, but
   14  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
   15  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
   16  * License for more details.
   17  *
   18  * You should have received a copy of the GNU Lesser General Public
   19  * License along with this library; if not, write to the Free Software
   20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
   21  * USA.
   22  *
   23  *  Created on: Oct 19, 2009
   24  *      Author: Heiko Klein
   25  */
   26 
   27 #ifndef C_FIMEX_H_
   28 #define C_FIMEX_H_
   29 
   30 #include <stddef.h>
   31 #include "fimex/CDMconstants.h"
   32 
   33 /**
   34  * @headerfile fimex/c_fimex.h
   35  */
   36 /**
   37  * This is the public C-Api for fimex. It is a wrapper api for the underlying C++ api.
   38  */
   39 
   40 #ifdef __cplusplus
   41 extern "C" {
   42 #endif
   43 
   44 typedef struct mifi_cdm_reader mifi_cdm_reader;
   45 typedef struct mifi_slicebuilder mifi_slicebuilder;
   46 
   47 /**
   48  * Function pointer as used for the get_double_dataslice callback function
   49  * @return 0 on success, error otherwise
   50  */
   51 typedef int (*doubleDatasliceCallbackPtr)(mifi_cdm_reader* reader, const char* varName, size_t unLimDimPos, double* scaledData, size_t dataSize);
   52 
   53 /**
   54  * Free the reader. This won't free the resources immediately, but reduce the reference counter.
   55  * It is therefore possible to free a reader, while it still is used within another part of the fimex-chain.
   56  */
   57 extern void mifi_free_cdm_reader(mifi_cdm_reader* reader);
   58 
   59 /**
   60  * Get a new reader from a file.
   61  * @param file_type #mifi_filetype constant. To get a CDMReaderWriter, use MIFI_FILETYPE_NETCDF|MIFI_FILETYPE_RW.
   62  * @param filename name of the felt-file
   63  * @param configFile configuration file for the felt-file
   64  * @return the reader object-pointer, use #mifi_free_cdm_reader to free, or NULL on error.
   65  */
   66 extern mifi_cdm_reader* mifi_new_io_reader(const char* file_type, const char* filename, const char* configFile);
   67 
   68 /**
   69  * Modify a reader using a ncml file.
   70  * @param reader the data/cdm source
   71  * @param ncmlFile name of the ncml config file
   72  * @return the reader object-pointer, use #mifi_free_cdm_reader to free, or NULL on error.
   73  */
   74 extern mifi_cdm_reader* mifi_new_ncml_modifier(mifi_cdm_reader* reader, const char* ncmlFile);
   75 
   76 /**
   77  * Write the content of the reader to the filename.
   78  * @param reader the data source
   79  * @param filetype the type of the file to write
   80  * @param filename the name of the netcdf-file to write
   81  * @param configFile an optional configFile, use "" or 0 if not needed
   82  * @return 0 on success.
   83  */
   84 extern int mifi_writer(mifi_cdm_reader* reader, const char* filetype, const char* filename, const char* configFile);
   85 
   86 /**
   87  * @brief change the projection of the reader to this new projection
   88  *
   89  * @param reader the original data-source
   90  * @param method Interpolation method
   91  * @param proj_input input-string for proj4, used as output projection
   92  * @param out_x_axis config-string for x_axis, either '1,2,...,5' or 'auto' or 'auto,distance=3.5'
   93  * @param out_y_axis config-string for y_axis, either '1,2,...,5' or 'auto' or 'auto,distance=3.5'
   94  * @param out_x_axis_unit unit of the output x-axis
   95  * @param out_y_axis_unit unit of the output y-axis
   96  * @return the reader object-pointer, use #mifi_free_cdm_reader to free, or NULL on error.
   97  */
   98 extern mifi_cdm_reader* mifi_new_cdminterpolator(mifi_cdm_reader* reader, int method, const char* proj_input, const char* out_x_axis, const char* out_y_axis, const char* out_x_axis_unit, const char* out_y_axis_unit);
   99 
  100 /**
  101  * @brief change the projection of the reader to this new projection
  102  *
  103  * @param reader the original data-source
  104  * @param method Interpolation method
  105  * @param n number of latitude-longitude points
  106  * @param lonVals array of size n with longitude positions
  107  * @param latVals array of size n with latitude positions
  108  * @return the reader object-pointer, use #mifi_free_cdm_reader to free, or NULL on error.
  109  */
  110 extern mifi_cdm_reader* mifi_new_lonlat_interpolator(mifi_cdm_reader* reader, int method, int n, const double* lonVals, const double* latVals);
  111 
  112 
  113 /**
  114  * Get a new reader which allows setting c-callback functions.
  115  * @param reader the original data-source
  116  * @return the reader object-pointer, use #mifi_free_cdm_reader to free, or NULL on error.
  117  */
  118 extern mifi_cdm_reader* mifi_new_c_reader(mifi_cdm_reader* reader);
  119 
  120 /**
  121  * Add a callback for a variable. The variable will be converted to datatype double.
  122  * @param c_reader the reader as created by #mifi_new_c_reader
  123  * @param varName the name of the variable
  124  * @param callback a function-ptr to the callback function
  125  * @return 0 on success, else error
  126  *
  127  * @warning the callback function will only be able to modify data which is available
  128  * in the reader. It cannot change any information the writer request, but the reader doesn't
  129  * now about. This data will continue to be undefined!
  130  */
  131 extern int mifi_set_callback_double(mifi_cdm_reader* c_reader, const char* varName, doubleDatasliceCallbackPtr callback);
  132 
  133 
  134 /**
  135  * Get the number of the variables from the reader.
  136  * @param reader the data source
  137  * @return the number of variables
  138  */
  139 extern size_t mifi_get_variable_number(mifi_cdm_reader* reader);
  140 /**
  141  * Get the name of a variable from the reader.
  142  * @param reader the data source
  143  * @param pos the position number of the variable, should be between 0 and size-1
  144  * @return the variable name, or "" on failure
  145  */
  146 extern const char* mifi_get_variable_name(mifi_cdm_reader* reader, size_t pos);
  147 
  148 /**
  149  * Get the MetNoFimex::CDMDataType datatype for a variable.
  150  * @param reader the data source
  151  * @param varName name of the variable
  152  * @return datatype, or CDM_NAT=0 on error
  153  */
  154 extern unsigned int mifi_get_variable_type(mifi_cdm_reader* reader, const char* varName);
  155 
  156 /**
  157  * Get the number of the dimensions from the reader.
  158  * @param reader the data source
  159  * @return the number of dimension
  160  */
  161 extern size_t mifi_get_dimension_number(mifi_cdm_reader* reader);
  162 /**
  163  * Get the name of a dimension from the reader.
  164  * @param reader the data source
  165  * @param pos the position number of the dimensin, should be between 0 and size-1
  166  * @return the dimension name, or "" on failure
  167  */
  168 extern const char* mifi_get_dimension_name(mifi_cdm_reader* reader, size_t pos);
  169 /**
  170  * Get the size of a dimension
  171  * @param reader the data source
  172  * @param dimName the name of the dimension
  173  * @return the size of the dimension, or 0 if dimension does not exist
  174  */
  175 extern size_t mifi_get_dimension_size(mifi_cdm_reader* reader, const char* dimName);
  176 
  177 /**
  178  * Get the name of the unlimited dimension
  179  * @param reader
  180  * @return name of unlimited dimension, or ""
  181  */
  182 extern const char* mifi_get_unlimited_dimension_name(mifi_cdm_reader* reader);
  183 
  184 /**
  185  * Get the name of the longitude variable belonging to a parameter. The longitude
  186  * variable might be a dimension (1D), or an 2D field.
  187  * @param reader
  188  * @param varName The name of a parameter.
  189  * @return longitude-variable name, which must be free'd, or NULL
  190  */
  191 extern char* mifi_get_var_longitude(mifi_cdm_reader* reader, const char* varName);
  192 
  193 /**
  194  * Get the name of the latitude variable belonging to a parameter. This function is similar
  195  * to mifi_get_var_longitude, except that the name is copied to lonName which is expected to
  196  * have a capacity of n.
  197  * @param reader
  198  * @param varName The name of a parameter.
  199  * @param lonName The place to copy the longitude name to.
  200  * @param n The capacity of lonName -- 10 means at most 9 characters plus a final 0 byte.
  201  * @return -1 if no longitude-latitude variables found; 0 if n is too small, else the
  202  *         number of characters copied to lonName, including final NUL.
  203  */
  204 extern int mifi_get_var_longitude_cpy(mifi_cdm_reader* reader, const char* varName, char* lonName, int n);
  205 
  206 /**
  207  * Get the name of the latitude variable belonging to a parameter. The latitude
  208  * variable might be a dimension (1D), or an 2D field.
  209  * @param reader
  210  * @param varName The name of a parameter.
  211  * @return latitude-variable name, which must be free'd, or NULL
  212  */
  213 extern char* mifi_get_var_latitude(mifi_cdm_reader* reader, const char* varName);
  214 
  215 /**
  216  * Get the name of the latitude variable belonging to a parameter. This function is similar
  217  * to mifi_get_var_longitude, except that the name is copied to lonName which is expected to
  218  * have a capacity of n.
  219  * @param reader
  220  * @param varName The name of a parameter.
  221  * @param latName The place to copy the longitude name to.
  222  * @param n The capacity of latName -- 10 means at most 9 characters plus a final 0 byte.
  223  * @return -1 if no longitude-latitude variables found; 0 if n is too small, else the
  224  *         number of characters copied to latName, including final NUL.
  225  */
  226 extern int mifi_get_var_latitude_cpy(mifi_cdm_reader* reader, const char* varName, char* latName, int n);
  227 
  228 
  229 /**
  230  * Create a new slice_builder for the reader and the variable. It
  231  * will try to attach a coordinate-system if possible
  232  * @param reader
  233  * @param varName
  234  * @return a slicebuilder handle
  235  */
  236 extern mifi_slicebuilder* mifi_new_slicebuilder(mifi_cdm_reader* reader, const char* varName);
  237 /**
  238  * Check if the slicebuilder is connected to a coordinate-system.
  239  * @param sb
  240  * @return 1 on success, 0 on failure
  241  */
  242 extern int mifi_slicebuilder_has_CS(mifi_slicebuilder* sb);
  243 
  244 /**
  245  * Get the projection of the slicebuilder, if it belongs to a
  246  * coordinate-system with projection.
  247  * @param sb
  248  * @return proj4 string or empty string, which both must be free'd
  249  */
  250 extern const char* mifi_slicebuilder_get_proj4(mifi_slicebuilder* sb);
  251 
  252 /**
  253  * Get the projection of the slicebuilder. This function is similar to
  254  * mifi_slicebuilder_get_proj4, except that the name is copied to proj4 which
  255  * is expected to have a capacity of n.
  256  * @param sb
  257  * @param proj4 The place to copy the projection information to.
  258  * @param n The capacity of proj4 -- 10 means at most 9 characters plus a final 0 byte.
  259  * @return 0 if n is too small, else the number of characters copied to proj4, including final NUL.
  260  */
  261 extern int mifi_slicebuilder_get_proj4_cpy(mifi_slicebuilder* sb, char* proj4, int n);
  262 
  263 /**
  264  * Get the number of dimensions (i.e. the rank) of the slicebuilder.
  265  * @param sb
  266  * @return rank
  267  */
  268 extern int mifi_slicebuilder_ndims(mifi_slicebuilder* sb);
  269 /**
  270  * Get the name of the dimension of the slicebuilder at a certain
  271  * position.
  272  * @param sb
  273  * @param pos
  274  * @return dimension's name or empty string, which both must be free'd
  275  */
  276 extern const char* mifi_slicebuilder_dimname(mifi_slicebuilder* sb, int pos);
  277 
  278 /**
  279  * Get the projection of the slicebuilder. This function is similar to
  280  * mifi_slicebuilder_get_proj4, except that the name is copied to proj4 which
  281  * is expected to have a capacity of n.
  282  * @param sb
  283  * @param pos
  284  * @param dimName The place to copy the dimension name to.
  285  * @param n The capacity of dimName -- 10 means at most 9 characters plus a final 0 byte.
  286  * @return 0 if n is too small, else the number of characters copied to dimName, including final NUL.
  287  */
  288 extern int mifi_slicebuilder_dimname_cpy(mifi_slicebuilder* sb, int pos, char* dimName, int n);
  289 
  290 /**
  291  * Get the current start positions and dimension-sizes for all dimensions.
  292  * @param sb
  293  * @param start pre-allocated array of size ndims
  294  * @param size pre-allocated array of size ndims
  295  * @return 0 on success, < 0 on failure
  296  */
  297 extern int mifi_slicebuilder_get_start_size(mifi_slicebuilder* sb, unsigned int* start, unsigned int* size);
  298 
  299 extern int mifi_slicebuilder_get_axistype(mifi_slicebuilder* sb, int* axistype);
  300 
  301 
  302 /**
  303  * Set the start-position (starting with 0) and size of a named dimension.
  304  * @param sb
  305  * @param dimName
  306  * @param start
  307  * @param size
  308  * @return 0 on success, < 0 on failure
  309  */
  310 extern int mifi_slicebuilder_set_dim_start_size(mifi_slicebuilder* sb, const char* dimName, unsigned int start, unsigned int size);
  311 /**
  312  * Free the memory allocated for the slicebuilder.
  313  * @param sb
  314  */
  315 extern void mifi_free_slicebuilder(mifi_slicebuilder* sb);
  316 
  317 
  318 
  319 /**
  320  * get a slice of data from the dataReader
  321  * @param reader dataReader to read the data from
  322  * @param varName variable name associated with the data
  323  * @param unLimDimPos unlimited dimension of the slice
  324  * @param data: the returned data. It will be allocated automatically, it is the task of the user to <b>free</b> it. Undefined values will be NaN.
  325  * @param size: the size of the returned data.
  326  * @return 0 on success
  327  */
  328 extern int mifi_get_double_dataslice(mifi_cdm_reader* reader, const char* varName, size_t unLimDimPos, double** data, size_t* size);
  329 
  330 /**
  331  * get all the data from the dataReader
  332  * @param reader dataReader to read the data from
  333  * @param varName variable name associated with the data
  334  * @param data: the returned data. It will be allocated automatically, it is the task of the user to <b>free</b> it. Undefined values will be NaN.
  335  * @param size: the size of the returned data.
  336  * @return 0 on success
  337  */
  338 extern int mifi_get_double_data(mifi_cdm_reader* reader, const char* varName, double** data, size_t* size);
  339 
  340 /**
  341  * Read information from the readers variable to the pre-allocated
  342  * data-variable.
  343  *
  344  * @param reader the data-source
  345  * @param varName variable-name to read
  346  * @param sb The slicebuilder to restrict dimensions. It is possible to reuse a slicebuilder for several variables with the same dimensions.
  347  * @param units Units of the data. Scaling and unit-conversion will be done automatically. Use units = "" if you don't want any units-conversion. Units need to be udunits-compatible.
  348  * @param data Preallocated data. The total size must be identical to the slicebuilders total size.
  349  * @param size The actually read data. This might be <= the requested data if data not available.
  350  * @return 0 on success
  351  */
  352 extern int mifi_fill_scaled_double_dataslice(mifi_cdm_reader* reader, const char* varName, mifi_slicebuilder* sb, const char* units, double* data, size_t* size);
  353 
  354 /**
  355  * Write data to the variable on disk
  356  *
  357  * @param rwreader the data-sink, should be opened with mifi_new_io_reader() with MIFI_FILETYPE_RW|MIFI_FILETYPE_NETCDF
  358  * @param varName variable-name to read
  359  * @param sb The slicebuilder to restrict dimensions. It is possible to reuse a slicebuilder for several variables with the same dimensions.
  360  * @param units Units of the data. Scaling and unit-conversion will be done automatically. Use units = "" if you don't want any units-conversion. Units need to be udunits-compatible.
  361  * @param data Preallocated data. The total size must be identical to the slicebuilders total size.
  362  * @param size The size of data.
  363  * @return 0 on success
  364  */
  365 extern int mifi_write_scaled_double_dataslice(mifi_cdm_reader* rwreader, const char* varName, mifi_slicebuilder* sb, const char* units, double* data, size_t size);
  366 
  367 
  368 /**
  369  * get the unique forecast reference time in a unit
  370  * @param reader
  371  * @param units a unit for point in time, e.g. "seconds since 1970-01-01"
  372  * @return time in the given unit, or NaN
  373  */
  374 double mifi_get_unique_forecast_reference_time(mifi_cdm_reader* reader, const char* units);
  375 
  376 
  377 #ifdef __cplusplus
  378 }
  379 #endif
  380 
  381 #endif /* C_FIMEX_H_ */