1SD(3)                 User Contributed Perl Documentation                SD(3)
2
3
4

NAME

6       PDL::IO::HDF::SD - PDL interface to the HDF4 SD library.
7

SYNOPSIS

9         use PDL;
10         use PDL::IO::HDF::SD;
11
12         #
13         # Creating and writing an HDF file
14         #
15
16         # Create an HDF file:
17         my $hdf = PDL::IO::HDF::SD->new("-test.hdf");
18
19         # Define some data
20         my $data = sequence(short, 500, 5);
21
22         # Put data in file as 'myData' dataset with the names
23         #    of dimensions ('dim1' and 'dim2')
24         $hdf->SDput("myData", $data , ['dim1','dim2']);
25
26         # Put some local attributes in 'myData'
27         #
28         # Set the fill value to 0
29         my $res = $hdf->SDsetfillvalue("myData", 0);
30         # Set the valid range from 0 to 2000
31         $res = $hdf->SDsetrange("myData", [0, 2000]);
32         # Set the default calibration for 'myData' (scale factor = 1, other = 0)
33         $res = $hdf->SDsetcal("myData");
34
35         # Set a global text attribute
36         $res = $hdf->SDsettextattr('This is a global text test!!', "myGText" );
37         # Set a local text attribute for 'myData'
38         $res = $hdf->SDsettextattr('This is a local text testl!!', "myLText", "myData" );
39
40         # Set a global value attribute (you can put all values you want)
41         $res = $hdf->SDsetvalueattr( PDL::short( 20 ), "myGValue");
42
43         # Set a local value attribute (you can put all values you want)
44         $res = $hdf->SDsetvalueattr( PDL::long( [20, 15, 36] ), "myLValues", "myData" );
45
46         # Close the file
47         $hdf->close();
48
49         #
50         # Reading from an HDF file:
51         #
52
53         # Open an HDF file in read only mode:
54         my $hdf = PDL::IO::HDF::SD->new("test.hdf");
55
56         # Get a list of all datasets:
57         my @dataset_list = $hdf->SDgetvariablename();
58
59         # Get a list of the names of all global attributes:
60         my @globattr_list = $hdf->SDgetattributenames();
61
62         # Get a list of the names of all local attributes for a dataset:
63         my @locattr_list = $hdf->SDgetattributenames("myData");
64
65         # Get the value of local attribute for a dataset:
66         my $value = $hdf->SDgetattribut("myLText","myData");
67
68         # Get a PDL var of the entire dataset 'myData':
69         my $data = $hdf->SDget("myData");
70
71         # Apply the scale factor of 'myData'
72         $data *= $hdf->SDgetscalefactor("myData");
73
74         # Get the fill value and fill the PDL var in with BAD:
75         $data->inplace->setvaltobad( $hdf->SDgetfillvalue("myData") );
76
77         # Get the valid range of a dataset:
78         my @range = $hdf->SDgetrange("myData");
79
80         #Now you can do what you want with your data
81         $hdf->close();
82

DESCRIPTION

84       This library provides functions to read, write, and manipulate HDF4
85       files with HDF's SD interface.
86
87       For more infomation on HDF4, see http://hdf.ncsa.uiuc.edu/
88
89       There have been a lot of changes starting with version 2.0, and these
90       may affect your code. PLEASE see the 'Changes' file for a detailed
91       description of what has been changed. If your code used to work with
92       the circa 2002 version of this module, and does not work anymore,
93       reading the 'Changes' is your best bet.
94
95       In the documentation, the terms dataset and SDS (Scientific Data Set)
96       are used interchangably.
97

CLASS METHODS

99   new
100           Open or create a new HDF object.
101
102           Arguments:
103               1 : The name of the file.
104                   if you want to write to it, prepend the name with the '+' character : "+name.hdf"
105                   if you want to create it, prepend the name with the '-' character : "-name.hdf"
106                   otherwise the file will be open in read only mode
107
108           Returns the hdf object (die on error)
109
110           my $hdf = PDL::IO::HDF::SD->new("file.hdf");
111
112   Chunking
113           Accessor for the chunking mode on this HDF file.
114
115           'Chunking' is an internal compression and tiling the HDF library can
116               perform on an SDS.
117
118           This variable only affects they way SDput() works, and is ON by default.
119
120           The code modifications enabled by this flag automatically partition the
121               dataset to chunks of at least 100x100 values in size. The logic on this
122               is pretty fancy, and would take a while to doc out here. If you
123               _really_ have to know how it auto-partitions the data, then look at
124               the code.
125
126           Someday over the rainbow, I'll add some features for better control of the
127               chunking parameters, if the need arises. For now, it's just stupid easy
128               to use.
129
130           Arguments:
131               1 (optional): new value for the chunking flag.
132
133           # See if chunking is currently on for this file:
134           my $chunkvar = $hdf->Chunking();
135
136           # Turn the chunking off:
137           my $newvar = $hdf->Chunking( 0 );
138
139           # Turn the chunking back on:
140           my $newvar = $hdf->Chunking( 1 );
141
142   SDgetvariablenames
143           get the list of datasets.
144
145           No arguments
146           Returns the list of dataset or undef on error.
147
148           my @DataList = $hdfobj->SDgetvariablenames();
149
150   SDgetattributenames
151           Get a list of the names of the global or SDS attributes.
152
153           Arguments:
154               1 (optional) : The name of the SD dataset from which you want to get
155                   the attributes. This arg is optional, and without it, it will
156                   return the list of global attribute names.
157
158           Returns a list of names or undef on error.
159
160           # For global attributes :
161           my @attrList = $hdf->SDgetattributenames();
162
163           # For SDS attributes :
164           my @attrList = $hdf->SDgetattributenames("dataset_name");
165
166   SDgetattribute
167           Get a global or SDS attribute value.
168
169           Arguments:
170               1 : The name of the attribute.
171               2 (optional): The name of the SDS from which you want to get the attribute
172                   value. Without this arg, it returns the global attribute value of that name.
173
174           Returns an attribute value or undef on error.
175
176           # for global attributs :
177           my $attr = $hdf->SDgetattribute("attr_name");
178
179           # for local attributs :
180           my $attr = $hdf->SDgetattribute("attr_name", "dataset_name");
181
182   SDgetfillvalue
183           Get the fill value of an SDS.
184
185           Arguments:
186               1 : The name of the SDS from which you want to get the fill value.
187
188           Returns the fill value or undef on error.
189
190           my $fillvalue = $hdf->SDgetfillvalue("dataset_name");
191
192   SDgetrange
193           Get the valid range of an SDS.
194
195           Arguments:
196               1 : the name of the SDS from which you want to get the valid range.
197
198           Returns a list of two elements [min, max] or undef on error.
199
200           my @range = $hdf->SDgetrange("dataset_name");
201
202   SDgetscalefactor
203           Get the scale factor of an SDS.
204
205           Arguments:
206               1 : The name of the SDS from which you want to get the scale factor.
207
208           Returns the scale factor or undef on error.
209
210           my $scale = $hdf->SDgetscalefactor("dataset_name");
211
212   SDgetdimsize
213           Get the dimensions of a dataset.
214
215           Arguments:
216               1 : The name of the SDS from which you want to get the dimensions.
217
218           Returns an array of n dimensions with their sizes or undef on error.
219
220           my @dim = $hdf->SDgetdimsize("dataset_name");
221
222   SDgetunlimiteddimsize
223           Get the actual dimensions of an SDS with 'unlimited' dimensions.
224
225           Arguments:
226               1 : The name of the SDS from which you want to the dimensions.
227
228           Returns an array of n dimensions with the dim sizes or undef on error.
229
230           my @dims = $hdf->SDgetunlimiteddimsize("dataset_name");
231
232   SDgetdimnames
233           Get the names of the dimensions of a dataset.
234
235           Arguments:
236               1 : the name of a dataset you want to get the dimensions'names .
237
238           Returns an array of n dimensions with their names or an empty list if error.
239
240           my @dim_names = $hdf->SDgetdimnames("dataset_name");
241
242   SDgetcal
243           Get the calibration factor from an SDS.
244
245           Arguments:
246               1 : The name of the SDS
247
248           Returns (scale factor, scale factor error, offset, offset error, data type), or undef on error.
249
250           my ($cal, $cal_err, $off, $off_err, $d_type) = $hdf->SDgetcal("dataset_name");
251
252   SDget
253           Get a the data from and SDS, or just a slice of that SDS.
254
255           Arguments:
256               1 : The name of the SDS you want to get.
257               2 (optional): The start array ref of the slice.
258               3 (optional): The size array ref of the slice (HDF calls this the 'edge').
259               4 (optional): The stride array ref of the slice.
260
261           Returns a PDL of data if ok, PDL::null on error.
262
263           If the slice arguements are not given, this function will read the entire
264               SDS from the file.
265
266           The type of the returned PDL variable is the PDL equivalent of what was
267               stored in the HDF file.
268
269           # Get the entire SDS:
270           my $pdldata = $hdf->SDget("dataset_name");
271
272           # get a slice of the dataset
273           my $start = [10,50,10];  # the start position of the slice is [10, 50, 10]
274           my $edge = [20,20,20];   # read 20 values on each dimension from @start
275           my $stride = [1, 1, 1];  # Don't skip values
276           my $pdldata = $hdf->SDget( "dataset_name", $start, $edge, $stride );
277
278   SDsetfillvalue
279           Set the fill value for an SDS.
280
281           Arguments:
282               1 : The name of the SDS.
283               2 : The fill value.
284
285           Returns true on success, undef on error.
286
287           my $res = $hdf->SDsetfillvalue("dataset_name",$fillvalue);
288
289   SDsetrange
290           Set the valid range of an SDS.
291
292           Arguments:
293               1 : The name of the SDS
294               2 : an anonymous array of two elements : [min, max].
295
296           Returns true on success, undef on error.
297
298           my $res = $hdf->SDsetrange("dataset_name", [$min, $max]);
299
300   SDsetcal
301           Set the HDF calibration for an SDS.
302
303           In HDF lingo, this means to define:
304               scale factor
305               scale factor error
306               offset
307               offset error
308
309           Arguments:
310               1 : The name of the SDS.
311               2 (optional): the scale factor (default is 1)
312               3 (optional): the scale factor error (default is 0)
313               4 (optional): the offset (default is 0)
314               5 (optional): the offset error (default is 0)
315
316           Returns true on success, undef on error.
317
318           NOTE: This is not required to make a valid HDF SDS, but is there if you want to use it.
319
320           # Create the dataset:
321           my $res = $hdf->SDsetcal("dataset_name");
322
323           # To just set the scale factor:
324           $res = $hdf->SDsetcal("dataset_name", $scalefactor);
325
326           # To set all calibration parameters:
327           $res = $hdf->SDsetcal("dataset_name", $scalefactor, $scale_err, $offset, $off_err);
328
329   SDsetcompress
330           Set the internal compression on an SDS.
331
332           Arguments:
333               1 : The name of the SDS.
334               2 (optional): The gzip compression level ( 1 - 9 ). If not
335                   specified, then 6 is used.
336
337           Returns true on success, undef on failure.
338
339           WARNING: This is a fairly buggy feature with many version of the HDF library.
340           Please just use the 'Chunking' features instead, as they work far better, and
341           are more reliable.
342
343           my $res = $hdf->SDsetfillvalue("dataset_name",$deflate_value);
344
345   SDsettextattr
346           Add a text HDF attribute, either globally, or to an SDS.
347
348           Arguments:
349               1 : The text you want to add.
350               2 : The name of the attribute
351               3 (optional): The name of the SDS.
352
353           Returns true on success, undef on failure.
354
355           # Set a global text attribute:
356           my $res = $hdf->SDsettextattr("my_text", "attribut_name");
357
358           # Set a local text attribute for 'dataset_name':
359           $res = $hdf->SDsettextattr("my_text", "attribut_name", "dataset_name");
360
361   SDsetvalueattr
362           Add a non-text HDF attribute, either globally, or to an SDS.
363
364           Arguments:
365               1 : A pdl of value(s) you want to store.
366               2 : The name of the attribute.
367               3 (optional): the name of the SDS.
368
369           Returns true on success, undef on failure.
370
371           my $attr = sequence( long, 4 );
372
373           # Set a global attribute:
374           my $res = $hdf->SDsetvalueattr($attribute, "attribute_name");
375
376           # Set a local attribute for 'dataset_name':
377           $res = $hdf->SDsetvalueattr($attribute, "attribute_name", "dataset_name");
378
379   SDsetdimname
380           Set or rename the dimensions of an SDS.
381
382           Arguments:
383               1 : The name of the SDS.
384               2 : An anonymous array with the dimensions names. For dimensions you want
385                   to leave alone, leave 'undef' placeholders.
386
387           Returns true on success, undef on failure.
388
389           # Rename all dimensions
390           my $res = $hdf->SDsetdimname("dataset_name", ['dim1','dim2','dim3']);
391
392           # Rename some dimensions
393           $res = $hdf->SDsetdimname("dataset_name", ['dim1', undef ,'dim3']);
394
395   SDput
396           Write to a SDS in an HDF file or create and write to it if it doesn't exist.
397
398           Arguments:
399               1 : The name of the SDS.
400               2 : A pdl of data.
401               3 (optional): An anonymous array of the dim names (only for creation)
402               4 (optional): An anonymous array of the start of the slice to store
403                   (only for putting a slice)
404
405           Returns true on success, undef on failure.
406
407           The datatype of the SDS in the HDF file will match the PDL equivalent as
408               much as possible.
409
410           my $data = sequence( float, 10, 20, 30 ); #any value you want
411
412           # Simple case: create a new dataset with a $data pdl
413           my $result = $hdf->SDput("dataset_name", $data);
414
415           # Above, but also naming the dims:
416           $res = $hdf->SDput("dataset_name", $data, ['dim1','dim2','dim3']);
417
418           # Just putting a slice in there:
419           my $start = [x,y,z];
420           $res = $hdf->SDput("dataset_name", $data->slice("..."), undef, $start);
421
422   close
423           Close an HDF file.
424
425           No arguments.
426
427           my $result = $hdf->close();
428

CURRENT AUTHOR & MAINTAINER

430       Judd Taylor, Orbital Systems, Ltd.  judd dot t at orbitalsystems dot
431       com
432

PREVIOUS AUTHORS

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

SEE ALSO

438       perl(1), PDL(1), PDL::IO::HDF(1).
439
440
441
442perl v5.12.3                      2011-03-31                             SD(3)
Impressum