c_hdf_reader.h File Reference

Generic library for reading HDF4 files. More...

#include <stdio.h>
#include <string.h>
#include "mfhdf.h"

Go to the source code of this file.

Classes

struct  ATTR
 represents the available informations about an attribute (either a file or a SDS one) More...
struct  SDS_INFO
 represents the available informations about one SDS : name, rank, dimensions, and list of attributes More...

Functions

int32 open_hdf_file (const char *filename)
 open an hdf file for reading
int32 close_hdf_file (const int32 hdf_id)
 close an opened hdf file
int32 get_file_info (const char *filename, int32 *n_sds, char ***v_sds_name, int32 *n_file_attr, char ***v_file_attr_name)
 retrieve the structure of an HDF file
int32 get_sds_info (const char *filename, const char *sds_name, SDS_INFO *sds_info)
 retrieve informations about an SDS : its name, rank, dimensions, and list of attributes
int32 get_sds_info_by_id (const int32 sd_id, const char *sds_name, SDS_INFO *sds_info)
 retrieve informations about an SDS : its name, rank, dimensions, and list of attributes
void print_sds_info (const SDS_INFO *sds_info)
 print out SDS data type, rank, dimensions and list of attributes
int32 get_file_attr (const char *filename, const char *attr_name, ATTR *attr)
 read a file attribute
int32 get_file_attr_by_id (const int32 sd_id, const char *attr_name, ATTR *attr)
 read a file attribute
int32 get_sds_attr (const char *filename, const char *sds_name, const char *attr_name, ATTR *attr)
 read a sds attribute
int32 get_sds_attr_by_id (const int32 sd_id, const char *sds_name, const char *attr_name, ATTR *attr)
 read a sds attribute
void print_attr (const ATTR *attr)
 print out data type, number of values and value of the given attribute structure
int32 get_obj_attr (const int32 obj_id, const char *attr_name, ATTR *attr)
 retrieve an attribute, either an SDS or a file one This function is a low level one. Prefer get_file_attr, or get_sds_attr functions for a high level usage
int32 get_obj_attr_by_index (const int32 obj_id, const int32 i_attr, ATTR *attr)
 retrieve an attribute, either an SDS or a file one This function is a low level one. Prefer get_file_attr, or get_sds_attr functions for a high level usage
double * read_sds_data (const char *filename, const char *sds_name, double *sds_data, int32 *start, int32 *stride, int32 *edges)
 read the data of one dataset and apply the scaling to it
double * read_sds_data_by_id (const int32 sd_id, const char *sds_name, double *sds_data, int32 *start, int32 *stride, int32 *edges)
 read the data of one dataset and apply the scaling to it
void * read_sds_binary_data (const char *filename, const char *sds_name, void *sds_data, int32 *start, int32 *stride, int32 *edges)
 read the binary data of one dataset, without scaling it This method is a wrapper to the HDF "SDreaddata" function (
void * read_sds_binary_data_by_id (const int32 sd_id, const char *sds_name, void *sds_data, int32 *start, int32 *stride, int32 *edges)
 read the binary data of one dataset, without scaling it using a SD interface identifier This method is a wrapper to the HDF "SDreaddata" function (
int32 get_sds_calibration (const char *filename, const char *sds_name, float64 *cal, float64 *cal_err, float64 *offset, float64 *offset_err, int32 *data_type)
 read the calibration informations of an sds
int32 get_sds_calibration_by_id (const int32 sd_id, const char *sds_name, float64 *cal, float64 *cal_err, float64 *offset, float64 *offset_err, int32 *data_type)
 read the calibration informations of an sds using a SD interface identifier This method is a wrapper to the HDF "SDgetcal" function (
int16 get_data_type_size (const int32 data_type)
 return the size in byte(s) of the HDF data type code given as parameter
void print_data_type_description (const int32 data_type)
 display a description of the HDF data type code given as parameter
int32 get_sds_id (const int32 sd_id, const char *sds_name)
 retrieve the identifier of an sds LOW LEVEL FUNCTION INTERNAL USAGE
int32 set_start_stride_edge (const int32 sd_id, const char *sds_name, int32 **start, const int32 *stride, int32 **edges)
 guess the start and the number of values to read in a SDS if they are set to NULL INNER FUNCTION user should not have to use this function
int32 scale_data (const void *unscaled_data, const int32 unscaled_data_type, const int32 nb_data, const double scale_factor, const double offset, double *scaled_data)
 apply a scaling y = scale_factor * ( x + offset ) to an unscaled data buffer
void * allocate_data (const int32 data_type, const int32 data_size)
 allocate a generic buffer with the given HDF type and size
void free_typed_data (void *data, const int32 data_type)
 free the given void buffer with the good type
void free_attr (ATTR *attr)
 properly free the memory used for an attribute
void free_sds_info (SDS_INFO *sds_info)
 properly free the memory used for a sds_info structure
void free_v_string (char ***v_string, const int32 n_string)
 free a vector of strings
int32 array_cast (const double *indata, const int32 nb_data, const int32 typecode, void *outdata)
 cast the values in the double array indata and put them in outdata typed as given by typecode
int32 value_cast (const double inval, const int32 typecode, void *outval)
 cast a double input value to an output one typed as given by typecode


Detailed Description

Generic library for reading HDF4 files.

Author:
Nicolas PASCAL (nicolas.pascal@icare.univ-lille1.fr), (C) Centre de Gestion et de Traitement de Données (CGTD) ICARE 2008
Version:
0.0.0
Date:
2008/02/25
Copyright: See COPYING file that comes with this distribution

History : v0.0.0 : creation


Function Documentation

void* allocate_data ( const int32  data_type,
const int32  data_size 
) [inline]

allocate a generic buffer with the given HDF type and size

Parameters:
data_type [IN] an HDF type code
data_size [IN] number of values
Returns:
a pointer to the start of the allocated buffer. NULL if case of error

References get_data_type_size().

Referenced by array_cast().

int32 array_cast ( const double *  indata,
const int32  nb_data,
const int32  typecode,
void *  outdata 
)

cast the values in the double array indata and put them in outdata typed as given by typecode

Parameters:
indata [IN] input data array (double typed)
nb_data [IN] number of values in indata
typecode [IN] The HDF type code of outdata
outdata [OUT] output data array, typed as typecode. If NUL, the method manages the allocation
Returns:
0 if successfull, -1 in case of error

References allocate_data(), get_data_type_size(), and value_cast().

int32 close_hdf_file ( const int32  hdf_id  ) 

close an opened hdf file

Parameters:
hdf_id [IN] hdf id used to access the file
Returns:
0 if successfull, -1 in case of error

Referenced by get_file_attr(), get_file_info(), get_sds_attr(), get_sds_calibration(), get_sds_info(), get_v_input_files(), read_sds_binary_data(), and read_sds_data().

void free_attr ( ATTR attr  ) 

properly free the memory used for an attribute

Parameters:
attr [INOUT] the attribute to free

References ATTR::data_type, and ATTR::value.

Referenced by free_sds_info(), get_obj_attr_by_index(), and get_v_input_files_by_id().

void free_sds_info ( SDS_INFO sds_info  ) 

properly free the memory used for a sds_info structure

Parameters:
sds_info [INOUT] the sds_info to free

References free_attr(), SDS_INFO::n_attr, and SDS_INFO::v_attr.

Referenced by get_sds_info_by_id(), read_custom_scale_sds_data_by_id(), read_sds_binary_data_by_id(), read_sds_data_by_id(), and set_start_stride_edge().

void free_typed_data ( void *  data,
const int32  data_type 
)

free the given void buffer with the good type

Parameters:
data [INOUT] the memory buffer to free
data_type [IN] an HDF type code

Referenced by read_custom_scale_sds_data_by_id(), and read_sds_data_by_id().

void free_v_string ( char ***  v_string,
const int32  n_string 
)

free a vector of strings

Parameters:
v_string the vector of strings to free
n_string number of string contained by the vector

int16 get_data_type_size ( const int32  data_type  ) 

return the size in byte(s) of the HDF data type code given as parameter

Parameters:
data_type an HDF type code
Returns:
the size of the type in bytes. -1 is the type is unknown

Referenced by allocate_data(), array_cast(), custom_scale_data(), get_obj_attr_by_index(), and read_sds_binary_data_by_id().

int32 get_file_attr ( const char *  filename,
const char *  attr_name,
ATTR attr 
)

read a file attribute

Parameters:
filename [IN] the full path to the file to read
attr_name [IN] name of the attribute to read
attr [OUT] an ATTR structure that will contain the read informations (type, number of values) and the attribute value
Returns:
0 if successfull, -1 in case of error

References close_hdf_file(), get_obj_attr(), and open_hdf_file().

int32 get_file_attr_by_id ( const int32  sd_id,
const char *  attr_name,
ATTR attr 
)

read a file attribute

Parameters:
sd_id [IN] an SD id as returned by the open_hdf_file function
attr_name [IN] name of the attribute to read
attr [OUT] buffer that will contain the attribute value. If NULL, the function manages the allocation. If not, the caller has the responsability to do it
Returns:
0 if successfull, -1 in case of error

References get_obj_attr().

Referenced by get_v_input_files_by_id().

int32 get_file_info ( const char *  filename,
int32 *  n_sds,
char ***  v_sds_name,
int32 *  n_file_attr,
char ***  v_file_attr_name 
)

retrieve the structure of an HDF file

Parameters:
filename [IN] the full path to the file to be read
n_sds [OUT] number of SDS of the file
v_sds_name [OUT] list of SDS names. If NULL, the function manages the allocation. If not, the caller has the repsonbility to do it
n_file_attr [OUT] number of attributes of the file
v_file_attr_name [OUT] list of file attributes names. If NULL, the function manages the allocation. If not, the caller has the responsability to do it
Returns:
0 if successfull, -1 in case of error

References close_hdf_file(), and open_hdf_file().

int32 get_obj_attr ( const int32  obj_id,
const char *  attr_name,
ATTR attr 
)

retrieve an attribute, either an SDS or a file one This function is a low level one. Prefer get_file_attr, or get_sds_attr functions for a high level usage

Parameters:
obj_id [IN] identifier of the object
attr_name [IN] name of the attribute to read
attr [OUT] Structure that will contain the attribute informations and its value
Returns:
0 if successfull, -1 in case of error

References get_obj_attr_by_index().

Referenced by get_file_attr(), get_file_attr_by_id(), and get_sds_attr_by_id().

int32 get_obj_attr_by_index ( const int32  obj_id,
const int32  i_attr,
ATTR attr 
)

retrieve an attribute, either an SDS or a file one This function is a low level one. Prefer get_file_attr, or get_sds_attr functions for a high level usage

Parameters:
obj_id [IN] identifier of the object
i_attr [IN] index of the attribute to read
attr [OUT] Structure that will contain the attribute informations and its value
Returns:
0 if successfull, -1 in case of error

References ATTR::data_type, free_attr(), get_data_type_size(), ATTR::n_val, ATTR::name, and ATTR::value.

Referenced by get_obj_attr(), and get_sds_info_by_id().

int32 get_sds_attr ( const char *  filename,
const char *  sds_name,
const char *  attr_name,
ATTR attr 
)

read a sds attribute

Parameters:
filename [IN] the full path to the file to read
sds_name [IN] name of the sds to read
attr_name [IN] name of the attribute to read
attr [OUT] buffer that will contain the attribute value. If NULL, the function manages the allocation. If not, the caller has the responsability to do it
Returns:
0 if successfull, -1 in case of error

References close_hdf_file(), get_sds_attr_by_id(), and open_hdf_file().

int32 get_sds_attr_by_id ( const int32  sd_id,
const char *  sds_name,
const char *  attr_name,
ATTR attr 
)

read a sds attribute

Parameters:
sd_id [IN] an SD id as returned by the open_hdf_file function
sds_name [IN] name of the sds to read
attr_name [IN] name of the attribute to read
attr [OUT] buffer that will contain the attribute value. If NULL, the function manages the allocation. If not, the caller has the responsability to do it
Returns:
0 if successfull, -1 in case of error

References get_obj_attr(), and get_sds_id().

Referenced by get_sds_attr().

int32 get_sds_calibration ( const char *  filename,
const char *  sds_name,
float64 *  cal,
float64 *  cal_err,
float64 *  offset,
float64 *  offset_err,
int32 *  data_type 
)

read the calibration informations of an sds

Parameters:
filename [IN] the full path to the file to read
sds_name [IN] name of the sds to read
cal [OUT] Calibration factor
cal_err [OUT] Calibration error
offset [OUT] Uncalibrated offset
offset_err [OUT] Uncalibrated offset error
data_type [OUT] Data type of uncalibrated data (
See also:
http://hdf.ncsa.uiuc.edu/old/RefMan41r3_html/DataTypeTable.fm.html for data_type table)
Returns:
0 if successfull, -1 in case of error

References close_hdf_file(), get_sds_calibration_by_id(), and open_hdf_file().

int32 get_sds_calibration_by_id ( const int32  sd_id,
const char *  sds_name,
float64 *  cal,
float64 *  cal_err,
float64 *  offset,
float64 *  offset_err,
int32 *  data_type 
)

read the calibration informations of an sds using a SD interface identifier This method is a wrapper to the HDF "SDgetcal" function (

See also:
http://hdf.ncsa.uiuc.edu/old/RefMan41r3_html/RM_Section_II_SD8.html#441065)
Parameters:
sd_id [IN] a SD interface id as returned by the open_hdf_file function
sds_name [IN] name of the sds to read
cal [OUT] Calibration factor
cal_err [OUT] Calibration error
offset [OUT] Uncalibrated offset
offset_err [OUT] Uncalibrated offset error
data_type [OUT] Data type of uncalibrated data (
See also:
http://hdf.ncsa.uiuc.edu/old/RefMan41r3_html/DataTypeTable.fm.html for data_type table)
Returns:
0 if successfull, -1 in case of error

Referenced by get_sds_calibration(), read_custom_scale_sds_data_by_id(), and read_sds_data_by_id().

int32 get_sds_id ( const int32  sd_id,
const char *  sds_name 
)

retrieve the identifier of an sds LOW LEVEL FUNCTION INTERNAL USAGE

Parameters:
sd_id SD interface identifier
sds_name name of the SDS to read
Returns:
a SDS identifier if successfull, -1 in case of error

Referenced by get_sds_attr_by_id(), get_sds_info_by_id(), and read_sds_binary_data_by_id().

int32 get_sds_info ( const char *  filename,
const char *  sds_name,
SDS_INFO sds_info 
)

retrieve informations about an SDS : its name, rank, dimensions, and list of attributes

Parameters:
filename [IN] the full path to the file to be read
sds_name [IN] name of the sds to read
sds_info [OUT] a SDS_INFO structure that stores the read informations
Returns:
0 if successfull, -1 in case of error

References close_hdf_file(), get_sds_info_by_id(), and open_hdf_file().

int32 get_sds_info_by_id ( const int32  sd_id,
const char *  sds_name,
SDS_INFO sds_info 
)

retrieve informations about an SDS : its name, rank, dimensions, and list of attributes

Parameters:
sd_id [IN] an SD id as returned by the open_hdf_file function
sds_name [IN] name of the sds to read
sds_info [OUT] a SDS_INFO structure that stores the read informations
Returns:
0 if successfull, -1 in case of error

References SDS_INFO::data_type, SDS_INFO::dim_size, free_sds_info(), get_obj_attr_by_index(), get_sds_id(), SDS_INFO::n_attr, SDS_INFO::name, SDS_INFO::rank, SDS_INFO::v_attr, and ATTR::value.

Referenced by get_sds_info(), read_custom_scale_sds_data_by_id(), read_sds_binary_data_by_id(), read_sds_data_by_id(), and set_start_stride_edge().

int32 open_hdf_file ( const char *  filename  ) 

open an hdf file for reading

Parameters:
filename [IN] the full path to the file to be read
Returns:
an hdf id (>0) used to access the file. -1 in case of error

Referenced by get_file_attr(), get_file_info(), get_sds_attr(), get_sds_calibration(), get_sds_info(), get_v_input_files(), read_sds_binary_data(), and read_sds_data().

void print_attr ( const ATTR attr  ) 

print out data type, number of values and value of the given attribute structure

Parameters:
attr attribute to print

References ATTR::data_type, ATTR::n_val, ATTR::name, print_data_type_description(), and ATTR::value.

Referenced by print_sds_info().

void print_data_type_description ( const int32  data_type  ) 

display a description of the HDF data type code given as parameter

Parameters:
data_type an HDF type code

Referenced by print_attr(), and print_sds_info().

void print_sds_info ( const SDS_INFO sds_info  ) 

print out SDS data type, rank, dimensions and list of attributes

Parameters:
sds_info SDS_INFO to print

References SDS_INFO::data_type, SDS_INFO::dim_size, SDS_INFO::n_attr, SDS_INFO::name, print_attr(), print_data_type_description(), SDS_INFO::rank, and SDS_INFO::v_attr.

void* read_sds_binary_data ( const char *  filename,
const char *  sds_name,
void *  sds_data,
int32 *  start,
int32 *  stride,
int32 *  edges 
)

read the binary data of one dataset, without scaling it This method is a wrapper to the HDF "SDreaddata" function (

See also:
http://hdf.ncsa.uiuc.edu/old/RefMan41r3_html/RM_Section_II_SD24.html#430848 for more details)
Warning:
if the caller delegate the allocation of the data buffer (sds_data) to the funtion by setting it to NULL, the data will be accessed lineary. So, if the dataset has 2 dimensions, to access the value at (i,j) you will do sds_data[j*dim_x+i] instead of the usual sds_data[j][i] (with dim_x the size of the x dimension). If you want to use an indexation as [j][i], the caller must manage the allocation
Parameters:
filename [IN] the full path to the file to read
sds_name [IN] name of the sds to read
sds_data [OUT] the buffer where is stored the read data. If set to NULL, the method will manage the memory allocation
start [IN] Array specifying the starting location from where data is read. Set it to NULL to read all the dataset
stride [IN] Array specifying the interval between the values that will be read along each dimension. Set it to NULL to read all the contigous data
edges [IN] Array specifying the number of values to be read along each dimension. Set it to NULL to read all the dataset
Returns:
a pointer to the eventually allocate data buffer if successfull, NULL in case of error

References close_hdf_file(), open_hdf_file(), and read_sds_binary_data_by_id().

void* read_sds_binary_data_by_id ( const int32  sd_id,
const char *  sds_name,
void *  sds_data,
int32 *  start,
int32 *  stride,
int32 *  edges 
)

read the binary data of one dataset, without scaling it using a SD interface identifier This method is a wrapper to the HDF "SDreaddata" function (

See also:
http://hdf.ncsa.uiuc.edu/old/RefMan41r3_html/RM_Section_II_SD24.html#430848 for more details)
Warning:
if the caller delegate the allocation of the data buffer (sds_data) to the funtion by setting it to NULL, the data will be accessed lineary. So, if the dataset has 2 dimensions, to access the value at (i,j) you will do sds_data[j*dim_x+i] instead of the usual sds_data[j][i] (with dim_x the size of the x dimension). If you want to use an indexation as [j][i], the caller must manage the allocation
Parameters:
sd_id [IN] an SD id as returned by the open_hdf_file function
sds_name [IN] name of the sds to read
sds_data [OUT] the buffer where is stored the read data. Allocation must be done by the caller with the right type
start [IN] Array specifying the starting location from where data is read
stride [IN] Array specifying the interval between the values that will be read along each dimension. Set it to NULL to read all the contigous data
edges [IN] Array specifying the number of values to be read along each dimension
Returns:
a pointer to the eventually allocate data buffer if successfull, NULL in case of error

References SDS_INFO::data_type, free_sds_info(), get_data_type_size(), get_sds_id(), get_sds_info_by_id(), SDS_INFO::rank, set_start_stride_edge(), and SDS_INFO::v_attr.

Referenced by read_custom_scale_sds_data_by_id(), read_sds_binary_data(), and read_sds_data_by_id().

double* read_sds_data ( const char *  filename,
const char *  sds_name,
double *  sds_data,
int32 *  start,
int32 *  stride,
int32 *  edges 
)

read the data of one dataset and apply the scaling to it

Warning:
if the caller delegate the allocation of the data buffer (sds_data) to the funtion by setting it to NULL, the data will be accessed lineary. So, if the dataset has 2 dimensions, to access the value at (i,j) you will do sds_data[j*dim_x+i] instead of the usual sds_data[j][i] (with dim_x the size of the x dimension). If you want to use an indexation as [j][i], the caller must manage the allocation
Parameters:
filename [IN] the full path to the file to read
sds_name [IN] name of the sds to read
sds_data [OUT] the buffer where is stored the read data. If set to NULL, the method will manage the memory allocation
start [IN] Array specifying the starting location from where data is read. Set it to NULL to read all the dataset
stride [IN] Array specifying the interval between the values that will be read along each dimension. Set it to NULL to read all the contigous data
edges [IN] Array specifying the number of values to be read along each dimension. Set it to NULL to read all the dataset
Returns:
a pointer to the eventually allocate data buffer if successfull, NULL in case of error

References close_hdf_file(), open_hdf_file(), and read_sds_data_by_id().

double* read_sds_data_by_id ( const int32  sd_id,
const char *  sds_name,
double *  sds_data,
int32 *  start,
int32 *  stride,
int32 *  edges 
)

read the data of one dataset and apply the scaling to it

Warning:
if the caller delegate the allocation of the data buffer (sds_data) to the funtion by setting it to NULL, the data will be accessed lineary. So, if the dataset has 2 dimensions, to access the value at (i,j) you will do sds_data[j*dim_x+i] instead of the usual sds_data[j][i] (with dim_x the size of the x dimension). If you want to use an indexation as [j][i], the caller must manage the allocation
Parameters:
sd_id [IN] an SD id as returned by the open_hdf_file function
sds_name [IN] name of the sds to read
sds_data [OUT] the buffer where is stored the read data. If set to NULL, the method will manage the memory allocation
start [IN] Array specifying the starting location from where data is read. Set it to NULL to read all the dataset
stride [IN] Array specifying the interval between the values that will be read along each dimension. Set it to NULL to read all the contigous data
edges [IN] Array specifying the number of values to be read along each dimension. Set it to NULL to read all the dataset
Returns:
a pointer to the eventually allocate data buffer if successfull, NULL in case of error

References SDS_INFO::data_type, free_sds_info(), free_typed_data(), get_sds_calibration_by_id(), get_sds_info_by_id(), SDS_INFO::rank, read_sds_binary_data_by_id(), scale_data(), set_start_stride_edge(), and SDS_INFO::v_attr.

Referenced by read_sds_data().

int32 scale_data ( const void *  unscaled_data,
const int32  unscaled_data_type,
const int32  nb_data,
const double  scale_factor,
const double  offset,
double *  scaled_data 
)

apply a scaling y = scale_factor * ( x + offset ) to an unscaled data buffer

Parameters:
unscaled_data [IN] unscaled data buffer
unscaled_data_type [IN] HDF type code of unscaled data
nb_data [IN] number of data contained in the buffer
scale_factor [IN] calibration factor
offset [IN] unscaled data offset
scaled_data [OUT] scaled data buffer
Returns:
0 if successfull, -1 in case of error

Referenced by read_sds_data_by_id().

int32 set_start_stride_edge ( const int32  sd_id,
const char *  sds_name,
int32 **  start,
const int32 *  stride,
int32 **  edges 
)

guess the start and the number of values to read in a SDS if they are set to NULL INNER FUNCTION user should not have to use this function

Parameters:
sd_id [IN] SD interface identifier
sds_name [IN] name of the sds to read
start [OUT] Array specifying the starting location from where data is read. Unchanged if not NULL
stride [IN] Array specifying the interval between the values that will be read along each dimension
edges [OUT] Array specifying the number of values to be read along each dimension. Unchanged if not NULL
Returns:
0 if successfull, -1 in case of error

References SDS_INFO::dim_size, free_sds_info(), get_sds_info_by_id(), SDS_INFO::rank, and SDS_INFO::v_attr.

Referenced by read_custom_scale_sds_data_by_id(), read_sds_binary_data_by_id(), and read_sds_data_by_id().

int32 value_cast ( const double  inval,
const int32  typecode,
void *  outval 
)

cast a double input value to an output one typed as given by typecode

Parameters:
inval [IN] input value (double typed)
typecode [IN] The HDF type code of outval
outval [OUT] output value, typed as typecode.
Returns:
0 if successfull, -1 in case of error

Referenced by array_cast().


Generated on Wed Sep 2 15:04:31 2009 for caltrack_reader.kdevelop by  doxygen 1.5.8