The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

PDL::IO::HDF::SD - An interface librairie for the SD interface of HDF file.

This librairy provide functions to manipulate HDF files with SD interface (reading, writting, ...)

For more infomation on HDF, see http://hdf.ncsa.uiuc.edu/

SYNOPSIS

  use PDL;
  use PDL::IO::HDF::SD;
        
    ### Creating and writing to a HDF file

    #Create an HDF file
    my $HDFobj = PDL::IO::HDF::SD->new("-montest.HDF");

    #Define some data
    my $data = PDL::short( sequence(500,5) );

    #Put data in file as 'myData' dataset
    #with the names of dimensions ('dim1' and 'dim2')
    $HDFobj->SDput("myData", $data , ['dim1','dim2']);

    #Put some local attributs in 'myData'
    #Set the fill value as 0
    my $res = $HDFobj->SDsetfillvalue("myData", 0);
    #Set the valid range from 0 to 2000
    $res = $HDFobj->SDsetrange("myData", [0, 2000]);
    #Set the default calibration for 'myData' (scale factor = 1, other = 0)
    $res = $HDFobj->SDsetcal("myData");

    #Set a global text attribut
    $res = $HDFobj->SDsettextattr('This is a global text test!!', "myGText" );
    #Set a local text attribut for 'myData'
    $res = $HDFobj->SDsettextattr('This is a local text testl!!', "myLText", "myData" );

    #Set a global value attribut (you can put all values you want)
    $res = $HDFobj->SDsetvalueattr( PDL::short( 20 ), "myGValue");

    #Set a local value attribut (you can put all values you want)
    $res = $HDFobj->SDsetvalueattr( PDL::long( [20, 15, 36] ), "myLValues", "myData" );

    #Close the file
    $HDFobj->close;

    ### Reading from a HDF file

    #Open an HDF file in read only mode
    my $HDFobj = PDL::IO::HDF::SD->new("montest.HDF");

    #Get a list of all datasets
    my @dataset_list = $HDFobj->SDgetvariablename();

    #Get a list of all global attributs name
    my @globattr_list = $HDFobj->SDgetattributname();

    #Get a list of local attributs name for a dataset
    my @locattr_list = $HDFobj->SDgetattributname("myData");

    #Get the value of local attribut for a dataset
    my $value = $HDFobj->SDgetattribut("myLText","myData");

    #Get the all dataset 'myData'
    my $data = $HDFobj->SDget("myData");

    #Apply the scale factor of 'myData'
    $data *= $HDFobj->SDgetscalefactor("myData");

    #Get the fill value
    #The fill value corresponding to the BAD value in pdl
    $data->inplace->setvaltobad( $HDFobj->SDgetfillvalue("myData") );

    #Get the valid range of datas
    my @range = $HDFobj->SDgetrange("myData");
 
    #Now you can do what you want with your data
    $HDFobj->close;

DESCRIPTION

This is the description of the PDL::IO::HDF::SD module.

new

        Open or create a new HDF object.
        Arguments:
        1 : the name of the file.
                if you want to write to it, prepend the name with
                the '+' character : "+name.hdf"
                if you want to create it, prepend the name with
                the '-' character : "-name.hdf"
                else the file will be open in read only mode
        return : the hdf object (die on error)
        my $hdfobj = PDL::IO::HDF::SD->new("file.hdf");
        

SDgetvariablename

        get the list of datasets.
        No arguments
        return : the list of dataset or an empty list on error.
        my @DataList = $hdfobj->SDgetvariablename();

SDgetattributname

        get a list of attributs'name, global or corresponding to a dataset.
        Arguments:
        1 : the name of a dataset you want to read attributs name.
                if the function is call without argument, it return
                the global attributs'name list
        return : a list of attributs'name or an empty list on error.
        # for global attributs :
        my @attrList = $hdfobj->SDgetattributname();

        # for local attributs :
        my @attrList = $hdfobj->SDgetattributname("dataset_name");

SDgetattribut

        get an attribut value, global or corresponding to a dataset.
        Arguments:
        1 : the name of the attribut.
        2 : the name of a dataset you want to get the attribut value.
                if the function is call without dataset name, it return
                the global attribut value
        return : an attribut value or undef if error.
        # for global attributs :
        my $attr = $hdfobj->SDgetattribut("attr_name");

        # for local attributs :
        my $attr = $hdfobj->SDgetattribut("attr_name", "dataset_name");

SDgetfillvalue

        get the fill value of a dataset.
        Arguments:
        1 : the name of a dataset you want to get the fill value.
        return : the fill value or undef if error.
        my $fillvalue = $hdfobj->SDgetfillvalue("dataset_name");

SDgetrange

        get the valid range of a dataset.
        Arguments:
        1 : the name of a dataset you want to get the valid range.
        return : a list of two elements [min, max] or an empty list if error.
        my @range = $hdfobj->SDgetrange("dataset_name");

SDgetscalefactor

        get the scale factor of a dataset.
        Arguments:
        1 : the name of a dataset you want to get the scale factor.
        return : the scale factor or undef if error.
        my $scale = $hdfobj->SDgetscalefactor("dataset_name");

SDgetdimsize

        get the dimensions of a dataset.
        Arguments:
        1 : the name of a dataset you want to get the dimensions.
        return : an array of n dimensions with their sizes or an empty list if error.
        my @dim = $hdfobj->SDgetdimsize("dataset_name");

SDgetdimsizeunlimit

        get the real dimensions of a dataset (real size of unlimited dimensions).
        Arguments:
        1 : the name of a dataset you want to get the dimensions.
        return : an array of n dimensions with their sizes or an empty list if error.
        my @dim = $hdfobj->SDgetdimsizeunlimit("dataset_name");

SDgetdimname

        get the dimensions name of a dataset.
        Arguments:
        1 : the name of a dataset you want to get the dimensions'names .
        return : an array of n dimensions with their names or an empty list if error.
        my @dim = $hdfobj->SDgetdimname("dataset_name");

SDgetcal

        Get all calibration factor of a dataset
        Arguments:
        1 : the name of the dataset
        return : (scale factor, scale factor error, offset, offset error, data type)if ok, undef if not ok.
        #get calibration
        my ($cal, $cal_err, $off, $off_err, $d_type) = $hdfobj->SDgetcal("dataset_name");

SDget

        get a dataset or a slice of a dataset.
        Arguments:
        1 : the name of a dataset with you want to get.
        2 : the start array of the slice.
        3 : the size array of the slice.
                the parameters 2 & 3 are optionnals.
        return : a PDL::double of data if ok, PDL::null if not.
        # simple use, get all the dataset
        my $pdldata = $hdfobj->SDget("dataset_name");

        # get a slice of the dataset
        my @start = [10,50,10]; # the start position of the slice is [10, 50, 10]
        my @lenght = [20,20,20]; # read 20 values on each dimension from @start
        my $pdldata = $hdfobj->SDget("dataset_name", @start, @lenght);

        #to get data in an other type than PDL::double
        my $pdldata = PDL::short( $hdfobj->SDget("dataset_name") );

        #another example: apply scale factor on data
        my $pdldata = $hdfobj->SDget("dataset_name") * $hdfobj->SDgetscalefactor("dataset_name");

                

SDsetfillvalue

        set the fill value for a dataset.
        Arguments:
        1 : the name of a dataset you want to set the fill value.
        2 : the fill value.
        return : 1 if ok, 0 if not ok.
        my $result = $hdfobj->SDsetfillvalue("dataset_name",$fillvalue);

SDsetcompress

        Compress a dataset. (only gzip methode)
        Arguments:
        1 : the name of a dataset you want to compress.
        2 : the deflate gzip option. (a value between 1 and 9)
        return : 1 if ok, 0 if not ok.
        my $result = $hdfobj->SDsetfillvalue("dataset_name",$deflate_value);

SDsetrange

        set the valid range of a dataset.
        Arguments:
        1 : the name of a dataset you want to set the range.
        2 : an array of two elements : @[min, max].
        return : 1 if ok, 0 if not ok.
        my $result = $hdfobj->SDsetrange("dataset_name", [$min, $max]);

SDsetcal

        calibrate a dataset.
        this mean define the scale factor, the scale factor error, the
        offset and the offset error.
        Arguments:
        1 : the name of a dataset you want to calibrate.
                other parameters are optionnels
        2 : the scale factor (default is 1)
        3 : the scale factor error (default is 0)
        4 : the offset (default is 0)
        5 : the offset error (default is 0)
        return : 1 if ok, 0 if not ok.
        #simple exemple: if the dataset have no scale factor or other calibration
        my $result = $hdfobj->SDsetcal("dataset_name");

        #to just set the scale factor
        my $result = $hdfobj->SDsetcal("dataset_name", $scalefactor);

        #to set all calibration parameters
        my $result = $hdfobj->SDsetcal("dataset_name", $scalefactor, $scale_err, $offset, $off_err);

SDsettextattr

        add a global or local attribut of type text
        Arguments:
        1 : the text you want to add.
        2 : the name of the attribut
        3 : the name of the dataset (optionnel)
        return : 1 if ok, 0 if not ok.
        #set a global text attribut
        my $result = $hdfobj->SDsettextattr("my_text", "attribut_name");

        #set a local text attribut
        my $result = $hdfobj->SDsettextattr("my_text", "attribut_name", "dataset_name");

SDsetvalueattr

        add a global or local attribut of any type
        Arguments:
        1 : a pdl of value(s) you want to store.
        2 : the name of the attribut
        3 : the name of the dataset (optionnel)
        return : 1 if ok, 0 if not ok.
        my $attribut = pdl ( ...... );

        #set a global attribut
        my $result = $hdfobj->SDsetvalueattr($attribut, "attribut_name");

        #set a local attribut
        my $result = $hdfobj->SDsetvalueattr($attribut, "attribut_name", "dataset_name");

SDsetdimname

        rename the dimensions of a dataset
        Arguments:
        1 : the name of the dataset
        2 : an array with the dimensions names
        return : 1 if ok, 0 if not ok.
        #rename all dimensions
        my $result = $hdfobj->SDsetdimname("dataset_name", ['dim1','dim2','dim3']);

        #rename some dimensions
        my $result = $hdfobj->SDsetdimname("dataset_name", ['dim1', undef ,'dim3']);

SDput

        put a new (or a slice of) dataset
        Arguments:
        1 : the name of the dataset.
        2 : a pdl of data (data are store white the type of the pdl)
        3 : the dimansions names (only for creating dataset)
        4 : the start of the slice to store (only for putting a slice)
        return : 1 if ok, 0 if not ok.
        my $data = pdl ( [ [x,x,x],[x,x,x],[x,x,x] ] ); #any value you want

        #simple use: create a new dataset with a $data pdl
        my $result = $hdfobj->SDput("dataset_name", $data);

        #the same with the name of the dimensions
        my $result = $hdfobj->SDput("dataset_name", $data, ['dim1','dim2','dim3']);

        #to just put a pdl (a slice) from @start in an existing dataset
        my @start = [x,y,z];
        my $result = $hdfobj->SDput("dataset_name", $SliceOfData, undef, @start);

close

        close a HDF file.
        no arguments
        my $result = $hdfobj->close();

AUTHOR

Patrick Leilde patrick.leilde@ifremer.fr contribs of Olivier Archer olivier.archer@ifremer.fr

SEE ALSO

perl(1), PDL(1).