epr_api.h

Insar图像处理软件

     * The geophysical unit for the band's pixel values
     */
    char* unit;

    /**
     * A short description of the band's contents
     */
    char* description;

    /**
     * If true (=1) lines will be mirrored (flipped) after read into a raster
     * in order to ensure a pixel ordering in raster X direction from 
     * WEST to EAST.
     */
    boolean lines_mirrored; 
};

/**
 * Represents a binary time value field in ENVISAT records.
 *
 * <p> Refer to ENVISAT documentation for the exact definition of
 * this data type.
 */
struct EPR_Time
{
    long  days;
    ulong seconds;
    ulong microseconds;
};


/*************************************************************************/
/********************************* FUNCTIONS *****************************/
/*************************************************************************/

/**
 * ============================ (1) Initialisation ==========================
 */

/**
 * Initializes the ENVISAT product reader API.
 * 
 *
 * @param log_level the log level. All logging messages with a log level lower 
 *        than the given one, will be supressed 
 * @param log_handler the log handler function pointer which
 *        will be used for logging, can be <code>NULL</code>, 
 *        if logging shall be disabled
 * @param err_handler the new error handler (function pointer),
 *         can be <code>NULL</code>, if errors shall not be reported
 * @return zero for success, an error code otherwise
 *
 * @author Norman Fomferra
 */
int epr_init_api(EPR_ELogLevel   log_level,
                 EPR_FLogHandler log_handler,
                 EPR_FErrHandler err_handler);


/**
 * Closes the ENVISAT product reader API by releasing all
 * resources allocated by the API.
 *
 * @author Norman Fomferra
 */
void epr_close_api();



/*
 * ============================ (2) Logging ============================
 */

/**
 * Sets the log level for the ENVISAT API. All logging
 * messages with a log level lower than the given one, will
 * be supressed, thus the log handler will not be called
 * for such messages.
 *
 * @param log_level the new log level. All logging messages with a log level lower 
 *        than the given one, will be supressed 
 * @return zero for success, an error code otherwise
 */
int epr_set_log_level(EPR_ELogLevel log_level);

/**
 * Sets the log handler for the ENVISAT API.
 *
 * @param log_handler the log handler function pointer which
 *        will be used for logging, can be NULL, if logging shall 
 *        be disabled
 *
 * @see epr_log_message
 */
void epr_set_log_handler(EPR_FLogHandler log_handler);

/**
 * A default implementation for a logging function to be passed into
 * the <code>epr_init()</code> function. The function writes to 
 * <code>stdout</code>, the format is: <i>log_level date time log_message</i>.
 * 
 * @param log_level the log level
 * @param log_message the log message
 */
void epr_log_message(EPR_ELogLevel log_level, const char* log_message);

/*
 * ========================= (3) Error Handling ==========================
 */

/**
 * Sets the error handler for the ENVISAT API.
 *
 * @param err_handler the new error handler (function pointer),
 *         can be NULL, if errors shall not be reported
 */
void epr_set_err_handler(EPR_FErrHandler err_handler);

/**
 * Gets the error code of the error that occured during 
 * the last API function call.
 *
 * @return the error code, <code>e_err_none</code> or zero if no error occured
 */
EPR_EErrCode epr_get_last_err_code();

/**
 * Gets the error message of the error that occured during 
 * the last API function call.
 *
 * @return the error message, <code>NULL</code> if no error occured
 */
const char* epr_get_last_err_message();

/**
 * Clears the last error. After calling this function, calling
 * <code>epr_get_last_err_code</code> returns <code>e_err_none</code> or zero and 
 * <code>epr_get_last_err_message</code> returns <code>NULL</code>.
 */
void epr_clear_err();

/*
 * ========================== (4) Input / Output ============================
 *
 * ======================= (4.1) Product File Access ==========================
 */

/**
 * Opens the ENVISAT product file with the given file path, 
 * <br>reads MPH, SPH and all DSDs, <br>organized the table with 
 * parameter of line length and tie points number; 
 * <br>returns a file identifier for the product.
 *
 * <p>The ENVISAT product reader API must be initialized before.
 *
 * @param product_file_path the path to the ENVISAT product file
 * @return the product identifier, or <code>NULL</code> if the file
 *         could not be opened. <code>epr_get_error_code()</code> should
 *         be called in this case in order to obtain the error code.
 */
EPR_SProductId* epr_open_product(const char* product_file_path);

/**
 * Closes the ENVISAT product file determined by the given product identifier.
 * 
 * @param product_id the product identifier, if <code>NULL</code> the function
 *        immediately returns zero.
 * @return zero for success, an error code otherwise
 */
int epr_close_product(EPR_SProductId* product_id);

/**
 * Gets the product's scene width in pixels.
 *
 * @param product_id the product identifier, must not be <code>NULL</code>
 * @return the product's total scene width in pixels, or <code>0</code> 
 *         if an error occured.
 */
ulong epr_get_scene_width(const EPR_SProductId* product_id);

/**
 * Gets the product's scene height in pixels.
 *
 * @param product_id the product identifier, must not be <code>NULL</code>
 * @return the product's total scene height in pixels, or <code>0</code> 
 *         if an error occured.
 */
ulong epr_get_scene_height(const EPR_SProductId* product_id);

/*
 * ================= (4.2) Writing to a file or standard output =================
 */

/** 
 * This group of functions is for writing an object to a file 
 * or standard output.
 *
 * <p>An object can be 
 * <ul><li> record</li><li>field</li><li>field element</li></ul>
 * if <code>FILE* istream</code> is given, the ASCII file will be outputed,
 * <br>else printed to standard output device.
 * 
 * <p>In case <i>record and/or field</i>:
 * @param record the record, must not be <code>NULL</code>
 * @param field the field, must not be <code>NULL</code>
 *
 * <p>In case <i>field element</i>:
 * @param record the record, must not be <code>NULL</code>
 * @param field_index the index of field in the given record
 * @param element_index the index of element in the given field
 *
 * @param ostream the identifier of the output file.
 *
 */
/*@{*/ 
void epr_print_record(const EPR_SRecord* record, FILE* ostream);
void epr_print_field(const EPR_SField* field, FILE* ostream);
void epr_print_element(const EPR_SRecord* record, uint field_index, uint element_index, FILE* ostream);
void epr_dump_record(const EPR_SRecord* record);
void epr_dump_field(const EPR_SField* field);
void epr_dump_element(const EPR_SRecord* record, uint field_index, uint element_index);
/*@}*/

/*
 * ======================= (5) Basic Data Access =========================
 *
 * ============================ (5.1) Dataset ==============================
 */


/**
 * Gets the number off all datasets contained in a product.
 *
 * @param product_id the product identifier, must not be <code>NULL</code>
 * @return the number off all dataset
 */
uint epr_get_num_datasets(EPR_SProductId* product_id);

/**
 * Gets the dataset_id at the specified position within the product.
 *
 * @param product_id the product identifier, must not be <code>NULL</code>
 * @param index the index identifying the position of the dataset, starting with 0, 
 * must not be negative
 * @return the requested dataset_id
 */
EPR_SDatasetId* epr_get_dataset_id_at(EPR_SProductId* product_id, uint index);

/**
 * Gets the dataset_id coresponding to the specified dataset name.
 *
 * @param product_id the product identifier, must not be <code>NULL</code>
 * @param dataset_name the dataset name, must not be <code>NULL</code>
 * @return the requested dataset_id
 */
EPR_SDatasetId* epr_get_dataset_id(EPR_SProductId* product_id, const char* dataset_name);

/**
 * Gets the name of the dataset for the given dataset ID.
 *
 * @param dataset_id the dataset identifier, must not be <code>NULL</code>
 * @return the name of the dataset.
 */
const char* epr_get_dataset_name(EPR_SDatasetId* dataset_id);

/**
 * Gets the name of the dsd for the given dataset ID.
 *
 * @param dataset_id the dataset identifier, must not be <code>NULL</code>
 * @return the name of the dsd.
 */
const char* epr_get_dsd_name(const EPR_SDatasetId* dataset_id);

/**
 * Gets the MPH record from the given <code>product_id</code>. 
 *
 * @param product_id the product identifier, must not be <code>NULL</code>
 * @return the MPH record or <code>NULL</code> if an error occured.
 */
EPR_SRecord* epr_get_mph(const EPR_SProductId* product_id);

/**
 * Gets the SPH record from the given <code>product_id</code>. 
 *
 * @param product_id the product identifier, must not be <code>NULL</code>
 * @return the SPH record or <code>NULL</code> if an error occured.
 */
EPR_SRecord* epr_get_sph(const EPR_SProductId* product_id);

/**
 * Gets the dataset descriptor (DSD) for the dataset specified by <code>dataset_id</code>. 
 *
 * @param dataset_id the dataset identifier, must not be <code>NULL</code>
 * @return the pointer at the dsd or <code>NULL</code> if an error occured.
 */
const EPR_SDSD* epr_get_dsd(const EPR_SDatasetId* dataset_id);

/**
 * Gets the number of records of the dataset specified by <code>dataset_id</code>. 
 *
 * @param dataset_id the dataset identifier, must not be <code>NULL</code>
 * @return the number of records or <code>0</code> if an error occured.
 */
uint epr_get_num_records(const EPR_SDatasetId* dataset_id);


uint epr_get_num_dsds(const EPR_SProductId* product_id);
EPR_SDSD* epr_get_dsd_at(const EPR_SProductId* product_id, uint dsd_index);

/*
 * ================================= (5.2) Records ============================
 */

/**
 * Creates a new, empty record with a structure compatible with the dataset specified 
 * by dataset_id. Such a record is typically used in subsequent calls to epr_read_record.
 * 
 * @param dataset_id the dataset identifier, must not be <code>NULL</code>
 * @return the new record instance
 *         or <code>NULL</code> if an error occured.
 */
EPR_SRecord* epr_create_record(EPR_SDatasetId* dataset_id);

/**
 * Reads a record of a dataset specified by dataset_id. 
 * <p>
 * The record is identified through the given dataset identifier and the given 
 * zero-based record index. In order to reduce memory reallocation, a 
 * record (pre-) created by the function <code>epr_create_record</code> 
 * can be passed to this function. Data is then read into this given record.
 * If no record (<code>NULL</code>) is given, the function initiates a new 
 * one. In both cases, the record in which the data is read into will be 
 * returned.
 * 
 * @param dataset_id the dataset identifier, must not be <code>NULL</code>
 * @param record_index the zero-based record index
 * @param record a pre-created record to reduce memory reallocation,
 *        can be <code>NULL</code> to let the function allocate a new record
 * @return the record in which the data has been read into
 *         or <code>NULL</code> if an error occured.
 */
EPR_SRecord* epr_read_record(EPR_SDatasetId* dataset_id,
                             uint record_index,
                             EPR_SRecord* record);

/**
 * Frees the memory allocated through the given record.
 *
 * <p> After calling this function the given record pointer becomes
 * invalid and should not be used anymore.
 * 
 */
void epr_free_record(EPR_SRecord* record);

/*
 * =========================== (5.3) Field Access =============================
 */
/**
 * Gets a field from the given record. 
 *
 * <p> The field is here identified through the given name. 
 * <br>It contains the field info and all corresponding values.
 * 
 * @param record the record identifier, must not be <code>NULL</code>
 * @param field_name the the name of required field, must not be <code>NULL</code>.