Main Page | Class List | Directories | File List | Class Members | File Members
include

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
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
int32 read_scaled_sds (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
int32 read_scaled_sds_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
int32 read_sds (const char *filename, const char *sds_name, void **sds_data, int32 *start, int32 *stride, int32 *edges)
 read the data of one dataset This method is a wrapper to the HDF "SDreaddata" function (
int32 read_sds_by_id (const int32 sd_id, const char *sds_name, void **sds_data, int32 *start, int32 *stride, int32 *edges)
 read the data of one dataset 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 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

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

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

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

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

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

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

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

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

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

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

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

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

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

int32 read_scaled_sds (  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:
0 if successfull, -1 in case of error

int32 read_scaled_sds_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:
0 if successfull, -1 in case of error

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

read the data of one dataset 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:
0 if successfull, -1 in case of error

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

read the data of one dataset 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:
0 if successfull, -1 in case of error

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

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

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

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

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

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

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

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

void free_attr (  ATTR *  attr  ) 
 

properly free the memory used for an attribute

Parameters:
attr [INOUT] the attribute to free

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

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

Generated on Mon Apr 14 16:16:18 2008 for c_hdf_reader by  doxygen 1.4.4