.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SD 3pm"
.TH SD 3pm "2023-06-17" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDL::IO::HDF::SD \- PDL interface to the HDF4 SD library.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use PDL;
\&  use PDL::IO::HDF::SD;
\&  
\&  #      
\&  # Creating and writing an HDF file
\&  #
\&
\&  # Create an HDF file:
\&  my $hdf = PDL::IO::HDF::SD\->new("\-test.hdf");
\&
\&  # Define some data
\&  my $data = sequence(short, 500, 5);
\&
\&  # Put data in file as \*(AqmyData\*(Aq dataset with the names 
\&  #    of dimensions (\*(Aqdim1\*(Aq and \*(Aqdim2\*(Aq)
\&  $hdf\->SDput("myData", $data , [\*(Aqdim1\*(Aq,\*(Aqdim2\*(Aq]);
\&
\&  # Put some local attributes in \*(AqmyData\*(Aq
\&  #
\&  # Set the fill value to 0
\&  my $res = $hdf\->SDsetfillvalue("myData", 0);
\&  # Set the valid range from 0 to 2000
\&  $res = $hdf\->SDsetrange("myData", [0, 2000]);
\&  # Set the default calibration for \*(AqmyData\*(Aq (scale factor = 1, other = 0)
\&  $res = $hdf\->SDsetcal("myData");
\&
\&  # Set a global text attribute
\&  $res = $hdf\->SDsettextattr(\*(AqThis is a global text test!!\*(Aq, "myGText" );
\&  # Set a local text attribute for \*(AqmyData\*(Aq
\&  $res = $hdf\->SDsettextattr(\*(AqThis is a local text testl!!\*(Aq, "myLText", "myData" );
\&
\&  # Set a global value attribute (you can put all values you want)
\&  $res = $hdf\->SDsetvalueattr( PDL::short( 20 ), "myGValue");
\&
\&  # Set a local value attribute (you can put all values you want)
\&  $res = $hdf\->SDsetvalueattr( PDL::long( [20, 15, 36] ), "myLValues", "myData" );
\&
\&  # Close the file
\&  $hdf\->close();
\&
\&  #
\&  # Reading from an HDF file:
\&  #
\&
\&  # Open an HDF file in read only mode:
\&  my $hdf = PDL::IO::HDF::SD\->new("test.hdf");
\&
\&  # Get a list of all datasets:
\&  my @dataset_list = $hdf\->SDgetvariablename();
\&
\&  # Get a list of the names of all global attributes:
\&  my @globattr_list = $hdf\->SDgetattributenames();
\&
\&  # Get a list of the names of all local attributes for a dataset:
\&  my @locattr_list = $hdf\->SDgetattributenames("myData");
\&
\&  # Get the value of local attribute for a dataset:
\&  my $value = $hdf\->SDgetattribut("myLText","myData");
\&
\&  # Get a PDL var of the entire dataset \*(AqmyData\*(Aq:
\&  my $data = $hdf\->SDget("myData");
\&
\&  # Apply the scale factor of \*(AqmyData\*(Aq
\&  $data *= $hdf\->SDgetscalefactor("myData");
\&
\&  # Get the fill value and fill the PDL var in with BAD:
\&  $data\->inplace\->setvaltobad( $hdf\->SDgetfillvalue("myData") );
\&
\&  # Get the valid range of a dataset:
\&  my @range = $hdf\->SDgetrange("myData");
\& 
\&  #Now you can do what you want with your data
\&  $hdf\->close();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This library provides functions to read, write, and manipulate
\&\s-1HDF4\s0 files with \s-1HDF\s0's \s-1SD\s0 interface.
.PP
For more information on \s-1HDF4,\s0 see http://hdf.ncsa.uiuc.edu/
.PP
There have been a lot of changes starting with version 2.0, and these may affect 
your code. \s-1PLEASE\s0 see the 'Changes' file for a detailed description of what 
has been changed. If your code used to work with the circa 2002 version of this
module, and does not work anymore, reading the 'Changes' is your best bet.
.PP
In the documentation, the terms dataset and \s-1SDS\s0 (Scientific Data Set) are used
interchangeably.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.SS "new"
.IX Subsection "new"
.Vb 1
\&    Open or create a new HDF object.
.Ve
.PP
.Vb 5
\&    Arguments:
\&        1 : The name of the file.
\&            if you want to write to it, prepend the name with the \*(Aq+\*(Aq character : "+name.hdf"
\&            if you want to create it, prepend the name with the \*(Aq\-\*(Aq character : "\-name.hdf"
\&            otherwise the file will be open in read only mode
\&    
\&    Returns the hdf object (die on error)
.Ve
.PP
.Vb 1
\&    my $hdf = PDL::IO::HDF::SD\->new("file.hdf");
.Ve
.SS "Chunking"
.IX Subsection "Chunking"
.Vb 1
\&    Accessor for the chunking mode on this HDF file.
\&    
\&    \*(AqChunking\*(Aq is an internal compression and tiling the HDF library can
\&        perform on an SDS.
\&        
\&    This variable only affects they way SDput() works, and is ON by default.
\&    
\&    The code modifications enabled by this flag automatically partition the 
\&        dataset to chunks of at least 100x100 values in size. The logic on this
\&        is pretty fancy, and would take a while to doc out here. If you
\&        _really_ have to know how it auto\-partitions the data, then look at
\&        the code.
\&    
\&    Someday over the rainbow, I\*(Aqll add some features for better control of the
\&        chunking parameters, if the need arises. For now, it\*(Aqs just stupid easy 
\&        to use.
.Ve
.PP
.Vb 2
\&    Arguments:
\&        1 (optional): new value for the chunking flag.
.Ve
.PP
.Vb 2
\&    # See if chunking is currently on for this file:
\&    my $chunkvar = $hdf\->Chunking();
\&
\&    # Turn the chunking off:
\&    my $newvar = $hdf\->Chunking( 0 );
\&    
\&    # Turn the chunking back on:
\&    my $newvar = $hdf\->Chunking( 1 );
.Ve
.SS "SDgetvariablenames"
.IX Subsection "SDgetvariablenames"
.Vb 1
\&    get the list of datasets.
.Ve
.PP
.Vb 2
\&    No arguments
\&    Returns the list of dataset or undef on error.
.Ve
.PP
.Vb 1
\&    my @DataList = $hdfobj\->SDgetvariablenames();
.Ve
.SS "SDgetattributenames"
.IX Subsection "SDgetattributenames"
.Vb 1
\&    Get a list of the names of the global or SDS attributes.
.Ve
.PP
.Vb 4
\&    Arguments:
\&        1 (optional) : The name of the SD dataset from which you want to get 
\&            the attributes. This arg is optional, and without it, it will 
\&            return the list of global attribute names.
\&        
\&    Returns a list of names or undef on error.
.Ve
.PP
.Vb 2
\&    # For global attributes :
\&    my @attrList = $hdf\->SDgetattributenames();
\&
\&    # For SDS attributes :
\&    my @attrList = $hdf\->SDgetattributenames("dataset_name");
.Ve
.SS "SDgetattribute"
.IX Subsection "SDgetattribute"
.Vb 1
\&    Get a global or SDS attribute value.
.Ve
.PP
.Vb 4
\&    Arguments:
\&        1 : The name of the attribute.
\&        2 (optional): The name of the SDS from which you want to get the attribute
\&            value. Without this arg, it returns the global attribute value of that name.
\&    
\&    Returns an attribute value or undef on error.
.Ve
.PP
.Vb 2
\&    # for global attributs :
\&    my $attr = $hdf\->SDgetattribute("attr_name");
\&
\&    # for local attributs :
\&    my $attr = $hdf\->SDgetattribute("attr_name", "dataset_name");
.Ve
.SS "SDgetfillvalue"
.IX Subsection "SDgetfillvalue"
.Vb 1
\&    Get the fill value of an SDS.
.Ve
.PP
.Vb 2
\&    Arguments:
\&        1 : The name of the SDS from which you want to get the fill value.
\&    
\&    Returns the fill value or undef on error.
.Ve
.PP
.Vb 1
\&    my $fillvalue = $hdf\->SDgetfillvalue("dataset_name");
.Ve
.SS "SDgetrange"
.IX Subsection "SDgetrange"
.Vb 1
\&    Get the valid range of an SDS.
.Ve
.PP
.Vb 2
\&    Arguments:
\&        1 : the name of the SDS from which you want to get the valid range.
\&    
\&    Returns a list of two elements [min, max] or undef on error.
.Ve
.PP
.Vb 1
\&    my @range = $hdf\->SDgetrange("dataset_name");
.Ve
.SS "SDgetscalefactor"
.IX Subsection "SDgetscalefactor"
.Vb 1
\&    Get the scale factor of an SDS.
.Ve
.PP
.Vb 2
\&    Arguments:
\&        1 : The name of the SDS from which you want to get the scale factor.
\&    
\&    Returns the scale factor or undef on error.
.Ve
.PP
.Vb 1
\&    my $scale = $hdf\->SDgetscalefactor("dataset_name");
.Ve
.SS "SDgetdimsize"
.IX Subsection "SDgetdimsize"
.Vb 1
\&    Get the dimensions of a dataset.
.Ve
.PP
.Vb 2
\&    Arguments:
\&        1 : The name of the SDS from which you want to get the dimensions.
\&        
\&    Returns an array of n dimensions with their sizes or undef on error.
.Ve
.PP
.Vb 1
\&    my @dim = $hdf\->SDgetdimsize("dataset_name");
.Ve
.SS "SDgetunlimiteddimsize"
.IX Subsection "SDgetunlimiteddimsize"
.Vb 1
\&    Get the actual dimensions of an SDS with \*(Aqunlimited\*(Aq dimensions.
.Ve
.PP
.Vb 2
\&    Arguments:
\&        1 : The name of the SDS from which you want to the dimensions.
\&    
\&    Returns an array of n dimensions with the dim sizes or undef on error.
.Ve
.PP
.Vb 1
\&    my @dims = $hdf\->SDgetunlimiteddimsize("dataset_name");
.Ve
.SS "SDgetdimnames"
.IX Subsection "SDgetdimnames"
.Vb 1
\&    Get the names of the dimensions of a dataset.
.Ve
.PP
.Vb 2
\&    Arguments:
\&        1 : the name of a dataset you want to get the dimensions\*(Aqnames .
\&    
\&    Returns an array of n dimensions with their names or an empty list if error.
.Ve
.PP
.Vb 1
\&    my @dim_names = $hdf\->SDgetdimnames("dataset_name");
.Ve
.SS "SDgetcal"
.IX Subsection "SDgetcal"
.Vb 1
\&    Get the calibration factor from an SDS.
.Ve
.PP
.Vb 2
\&    Arguments:
\&        1 : The name of the SDS
\&    
\&    Returns (scale factor, scale factor error, offset, offset error, data type), or undef on error.
.Ve
.PP
.Vb 1
\&    my ($cal, $cal_err, $off, $off_err, $d_type) = $hdf\->SDgetcal("dataset_name");
.Ve
.SS "SDget"
.IX Subsection "SDget"
.Vb 1
\&    Get a the data from and SDS, or just a slice of that SDS.
.Ve
.PP
.Vb 5
\&    Arguments:
\&        1 : The name of the SDS you want to get.
\&        2 (optional): The start array ref of the slice.
\&        3 (optional): The size array ref of the slice (HDF calls this the \*(Aqedge\*(Aq).
\&        4 (optional): The stride array ref of the slice.
\&    
\&    Returns a PDL of data if ok, PDL::null on error.
\&    
\&    If the slice arguments are not given, this function will read the entire
\&        SDS from the file.
\&    
\&    The type of the returned PDL variable is the PDL equivalent of what was
\&        stored in the HDF file.
.Ve
.PP
.Vb 2
\&    # Get the entire SDS:
\&    my $pdldata = $hdf\->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 $edge = [20,20,20];   # read 20 values on each dimension from @start
\&    my $stride = [1, 1, 1];  # Don\*(Aqt skip values
\&    my $pdldata = $hdf\->SDget( "dataset_name", $start, $edge, $stride );
.Ve
.SS "SDsetfillvalue"
.IX Subsection "SDsetfillvalue"
.Vb 1
\&    Set the fill value for an SDS.
.Ve
.PP
.Vb 3
\&    Arguments:
\&        1 : The name of the SDS.
\&        2 : The fill value.
\&    
\&    Returns true on success, undef on error.
.Ve
.PP
.Vb 1
\&    my $res = $hdf\->SDsetfillvalue("dataset_name",$fillvalue);
.Ve
.SS "SDsetrange"
.IX Subsection "SDsetrange"
.Vb 1
\&    Set the valid range of an SDS.
.Ve
.PP
.Vb 3
\&    Arguments:
\&        1 : The name of the SDS
\&        2 : an anonymous array of two elements : [min, max].
\&    
\&    Returns true on success, undef on error.
.Ve
.PP
.Vb 1
\&    my $res = $hdf\->SDsetrange("dataset_name", [$min, $max]);
.Ve
.SS "SDsetcal"
.IX Subsection "SDsetcal"
.Vb 1
\&    Set the HDF calibration for an SDS.
\&    
\&    In HDF lingo, this means to define:
\&        scale factor
\&        scale factor error
\&        offset
\&        offset error
.Ve
.PP
.Vb 6
\&    Arguments:
\&        1 : The name of the SDS.
\&        2 (optional): the scale factor (default is 1)
\&        3 (optional): the scale factor error (default is 0)
\&        4 (optional): the offset (default is 0)
\&        5 (optional): the offset error (default is 0)
\&    
\&    Returns true on success, undef on error.
\&    
\&    NOTE: This is not required to make a valid HDF SDS, but is there if you want to use it.
.Ve
.PP
.Vb 2
\&    # Create the dataset:
\&    my $res = $hdf\->SDsetcal("dataset_name");
\&
\&    # To just set the scale factor:
\&    $res = $hdf\->SDsetcal("dataset_name", $scalefactor);
\&
\&    # To set all calibration parameters:
\&    $res = $hdf\->SDsetcal("dataset_name", $scalefactor, $scale_err, $offset, $off_err);
.Ve
.SS "SDsetcompress"
.IX Subsection "SDsetcompress"
.Vb 1
\&    Set the internal compression on an SDS.
.Ve
.PP
.Vb 4
\&    Arguments:
\&        1 : The name of the SDS.
\&        2 (optional): The gzip compression level ( 1 \- 9 ). If not
\&            specified, then 6 is used.
\&    
\&    Returns true on success, undef on failure.
\&    
\&    WARNING: This is a fairly buggy feature with many version of the HDF library.
\&    Please just use the \*(AqChunking\*(Aq features instead, as they work far better, and
\&    are more reliable.
.Ve
.PP
.Vb 1
\&    my $res = $hdf\->SDsetfillvalue("dataset_name",$deflate_value);
.Ve
.SS "SDsettextattr"
.IX Subsection "SDsettextattr"
.Vb 1
\&    Add a text HDF attribute, either globally, or to an SDS.
.Ve
.PP
.Vb 4
\&    Arguments:
\&        1 : The text you want to add.
\&        2 : The name of the attribute
\&        3 (optional): The name of the SDS.
\&        
\&    Returns true on success, undef on failure.
.Ve
.PP
.Vb 2
\&    # Set a global text attribute:
\&    my $res = $hdf\->SDsettextattr("my_text", "attribut_name");
\&
\&    # Set a local text attribute for \*(Aqdataset_name\*(Aq:
\&    $res = $hdf\->SDsettextattr("my_text", "attribut_name", "dataset_name");
.Ve
.SS "SDsetvalueattr"
.IX Subsection "SDsetvalueattr"
.Vb 1
\&    Add a non\-text HDF attribute, either globally, or to an SDS.
.Ve
.PP
.Vb 4
\&    Arguments:
\&        1 : A pdl of value(s) you want to store.
\&        2 : The name of the attribute.
\&        3 (optional): the name of the SDS.
\&    
\&    Returns true on success, undef on failure.
.Ve
.PP
.Vb 1
\&    my $attr = sequence( long, 4 );
\&
\&    # Set a global attribute:
\&    my $res = $hdf\->SDsetvalueattr($attribute, "attribute_name");
\&
\&    # Set a local attribute for \*(Aqdataset_name\*(Aq:
\&    $res = $hdf\->SDsetvalueattr($attribute, "attribute_name", "dataset_name");
.Ve
.SS "SDsetdimname"
.IX Subsection "SDsetdimname"
.Vb 1
\&    Set or rename the dimensions of an SDS.
.Ve
.PP
.Vb 4
\&    Arguments:
\&        1 : The name of the SDS.
\&        2 : An anonymous array with the dimensions names. For dimensions you want
\&            to leave alone, leave \*(Aqundef\*(Aq placeholders.
\&    
\&    Returns true on success, undef on failure.
.Ve
.PP
.Vb 2
\&    # Rename all dimensions
\&    my $res = $hdf\->SDsetdimname("dataset_name", [\*(Aqdim1\*(Aq,\*(Aqdim2\*(Aq,\*(Aqdim3\*(Aq]);
\&
\&    # Rename some dimensions
\&    $res = $hdf\->SDsetdimname("dataset_name", [\*(Aqdim1\*(Aq, undef ,\*(Aqdim3\*(Aq]);
.Ve
.SS "SDput"
.IX Subsection "SDput"
.Vb 1
\&    Write to a SDS in an HDF file or create and write to it if it doesn\*(Aqt exist.
.Ve
.PP
.Vb 6
\&    Arguments:
\&        1 : The name of the SDS.
\&        2 : A pdl of data.
\&        3 (optional): An anonymous array of the dim names (only for creation)
\&        4 (optional): An anonymous array of the start of the slice to store 
\&            (only for putting a slice)
\&
\&    Returns true on success, undef on failure.
\&    
\&    The datatype of the SDS in the HDF file will match the PDL equivalent as 
\&        much as possible.
.Ve
.PP
.Vb 1
\&    my $data = sequence( float, 10, 20, 30 ); #any value you want
\&
\&    # Simple case: create a new dataset with a $data pdl
\&    my $result = $hdf\->SDput("dataset_name", $data);
\&
\&    # Above, but also naming the dims:
\&    $res = $hdf\->SDput("dataset_name", $data, [\*(Aqdim1\*(Aq,\*(Aqdim2\*(Aq,\*(Aqdim3\*(Aq]);
\&
\&    # Just putting a slice in there:
\&    my $start = [x,y,z];
\&    $res = $hdf\->SDput("dataset_name", $data\->slice("..."), undef, $start);
.Ve
.SS "close"
.IX Subsection "close"
.Vb 1
\&    Close an HDF file.
.Ve
.PP
.Vb 1
\&    No arguments.
.Ve
.PP
.Vb 1
\&    my $result = $hdf\->close();
.Ve
.SH "CURRENT AUTHOR & MAINTAINER"
.IX Header "CURRENT AUTHOR & MAINTAINER"
Judd Taylor, Orbital Systems, Ltd.
judd dot t at orbitalsystems dot com
.SH "PREVIOUS AUTHORS"
.IX Header "PREVIOUS AUTHORS"
Patrick Leilde patrick.leilde@ifremer.fr
contribs of Olivier Archer olivier.archer@ifremer.fr
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), \s-1\fBPDL\s0\fR\|(1), \s-1\fBPDL::IO::HDF\s0\fR\|(1).