1SD(3) User Contributed Perl Documentation SD(3)
2
6 PDL::IO::HDF::SD - PDL interface to the HDF4 SD library.
7
9 use PDL;
10 use PDL::IO::HDF::SD;
11 #
13 # Creating and writing an HDF file
14 #
15 # Create an HDF file:
17 my $hdf = PDL::IO::HDF::SD->new("-test.hdf");
18 # Define some data
20 my $data = sequence(short, 500, 5);
21 # Put data in file as 'myData' dataset with the names
23 # of dimensions ('dim1' and 'dim2')
24 $hdf->SDput("myData", $data , ['dim1','dim2']);
25 # 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 # 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 # Set a global value attribute (you can put all values you want)
41 $res = $hdf->SDsetvalueattr( PDL::short( 20 ), "myGValue");
42 # Set a local value attribute (you can put all values you want)
44 $res = $hdf->SDsetvalueattr( PDL::long( [20, 15, 36] ), "myLValues", "myData" );
45 # Close the file
47 $hdf->close();
48 #
50 # Reading from an HDF file:
51 #
52 # Open an HDF file in read only mode:
54 my $hdf = PDL::IO::HDF::SD->new("test.hdf");
55 # Get a list of all datasets:
57 my @dataset_list = $hdf->SDgetvariablename();
58 # Get a list of the names of all global attributes:
60 my @globattr_list = $hdf->SDgetattributenames();
61 # Get a list of the names of all local attributes for a dataset:
63 my @locattr_list = $hdf->SDgetattributenames("myData");
64 # Get the value of local attribute for a dataset:
66 my $value = $hdf->SDgetattribut("myLText","myData");
67 # Get a PDL var of the entire dataset 'myData':
69 my $data = $hdf->SDget("myData");
70 # Apply the scale factor of 'myData'
72 $data *= $hdf->SDgetscalefactor("myData");
73 # Get the fill value and fill the PDL var in with BAD:
75 $data->inplace->setvaltobad( $hdf->SDgetfillvalue("myData") );
76 # Get the valid range of a dataset:
78 my @range = $hdf->SDgetrange("myData");
79 #Now you can do what you want with your data
81 $hdf->close();
82
84 This library provides functions to read, write, and manipulate HDF4
85 files with HDF's SD interface.
86 For more infomation on HDF4, see http://hdf.ncsa.uiuc.edu/
88 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 In the documentation, the terms dataset and SDS (Scientific Data Set)
96 are used interchangably.
97
99 new
100 Open or create a new HDF object.
101 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 Returns the hdf object (die on error)
109 my $hdf = PDL::IO::HDF::SD->new("file.hdf");
111 Chunking
113 Accessor for the chunking mode on this HDF file.
114 'Chunking' is an internal compression and tiling the HDF library can
116 perform on an SDS.
117 This variable only affects they way SDput() works, and is ON by default.
119 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 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 Arguments:
131 1 (optional): new value for the chunking flag.
132 # See if chunking is currently on for this file:
134 my $chunkvar = $hdf->Chunking();
135 # Turn the chunking off:
137 my $newvar = $hdf->Chunking( 0 );
138 # Turn the chunking back on:
140 my $newvar = $hdf->Chunking( 1 );
141 SDgetvariablenames
143 get the list of datasets.
144 No arguments
146 Returns the list of dataset or undef on error.
147 my @DataList = $hdfobj->SDgetvariablenames();
149 SDgetattributenames
151 Get a list of the names of the global or SDS attributes.
152 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 Returns a list of names or undef on error.
159 # For global attributes :
161 my @attrList = $hdf->SDgetattributenames();
162 # For SDS attributes :
164 my @attrList = $hdf->SDgetattributenames("dataset_name");
165 SDgetattribute
167 Get a global or SDS attribute value.
168 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 Returns an attribute value or undef on error.
175 # for global attributs :
177 my $attr = $hdf->SDgetattribute("attr_name");
178 # for local attributs :
180 my $attr = $hdf->SDgetattribute("attr_name", "dataset_name");
181 SDgetfillvalue
183 Get the fill value of an SDS.
184 Arguments:
186 1 : The name of the SDS from which you want to get the fill value.
187 Returns the fill value or undef on error.
189 my $fillvalue = $hdf->SDgetfillvalue("dataset_name");
191 SDgetrange
193 Get the valid range of an SDS.
194 Arguments:
196 1 : the name of the SDS from which you want to get the valid range.
197 Returns a list of two elements [min, max] or undef on error.
199 my @range = $hdf->SDgetrange("dataset_name");
201 SDgetscalefactor
203 Get the scale factor of an SDS.
204 Arguments:
206 1 : The name of the SDS from which you want to get the scale factor.
207 Returns the scale factor or undef on error.
209 my $scale = $hdf->SDgetscalefactor("dataset_name");
211 SDgetdimsize
213 Get the dimensions of a dataset.
214 Arguments:
216 1 : The name of the SDS from which you want to get the dimensions.
217 Returns an array of n dimensions with their sizes or undef on error.
219 my @dim = $hdf->SDgetdimsize("dataset_name");
221 SDgetunlimiteddimsize
223 Get the actual dimensions of an SDS with 'unlimited' dimensions.
224 Arguments:
226 1 : The name of the SDS from which you want to the dimensions.
227 Returns an array of n dimensions with the dim sizes or undef on error.
229 my @dims = $hdf->SDgetunlimiteddimsize("dataset_name");
231 SDgetdimnames
233 Get the names of the dimensions of a dataset.
234 Arguments:
236 1 : the name of a dataset you want to get the dimensions'names .
237 Returns an array of n dimensions with their names or an empty list if error.
239 my @dim_names = $hdf->SDgetdimnames("dataset_name");
241 SDgetcal
243 Get the calibration factor from an SDS.
244 Arguments:
246 1 : The name of the SDS
247 Returns (scale factor, scale factor error, offset, offset error, data type), or undef on error.
249 my ($cal, $cal_err, $off, $off_err, $d_type) = $hdf->SDgetcal("dataset_name");
251 SDget
253 Get a the data from and SDS, or just a slice of that SDS.
254 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 Returns a PDL of data if ok, PDL::null on error.
262 If the slice arguements are not given, this function will read the entire
264 SDS from the file.
265 The type of the returned PDL variable is the PDL equivalent of what was
267 stored in the HDF file.
268 # Get the entire SDS:
270 my $pdldata = $hdf->SDget("dataset_name");
271 # 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 SDsetfillvalue
279 Set the fill value for an SDS.
280 Arguments:
282 1 : The name of the SDS.
283 2 : The fill value.
284 Returns true on success, undef on error.
286 my $res = $hdf->SDsetfillvalue("dataset_name",$fillvalue);
288 SDsetrange
290 Set the valid range of an SDS.
291 Arguments:
293 1 : The name of the SDS
294 2 : an anonymous array of two elements : [min, max].
295 Returns true on success, undef on error.
297 my $res = $hdf->SDsetrange("dataset_name", [$min, $max]);
299 SDsetcal
301 Set the HDF calibration for an SDS.
302 In HDF lingo, this means to define:
304 scale factor
305 scale factor error
306 offset
307 offset error
308 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 Returns true on success, undef on error.
317 NOTE: This is not required to make a valid HDF SDS, but is there if you want to use it.
319 # Create the dataset:
321 my $res = $hdf->SDsetcal("dataset_name");
322 # To just set the scale factor:
324 $res = $hdf->SDsetcal("dataset_name", $scalefactor);
325 # To set all calibration parameters:
327 $res = $hdf->SDsetcal("dataset_name", $scalefactor, $scale_err, $offset, $off_err);
328 SDsetcompress
330 Set the internal compression on an SDS.
331 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 Returns true on success, undef on failure.
338 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 my $res = $hdf->SDsetfillvalue("dataset_name",$deflate_value);
344 SDsettextattr
346 Add a text HDF attribute, either globally, or to an SDS.
347 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 Returns true on success, undef on failure.
354 # Set a global text attribute:
356 my $res = $hdf->SDsettextattr("my_text", "attribut_name");
357 # Set a local text attribute for 'dataset_name':
359 $res = $hdf->SDsettextattr("my_text", "attribut_name", "dataset_name");
360 SDsetvalueattr
362 Add a non-text HDF attribute, either globally, or to an SDS.
363 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 Returns true on success, undef on failure.
370 my $attr = sequence( long, 4 );
372 # Set a global attribute:
374 my $res = $hdf->SDsetvalueattr($attribute, "attribute_name");
375 # Set a local attribute for 'dataset_name':
377 $res = $hdf->SDsetvalueattr($attribute, "attribute_name", "dataset_name");
378 SDsetdimname
380 Set or rename the dimensions of an SDS.
381 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 Returns true on success, undef on failure.
388 # Rename all dimensions
390 my $res = $hdf->SDsetdimname("dataset_name", ['dim1','dim2','dim3']);
391 # Rename some dimensions
393 $res = $hdf->SDsetdimname("dataset_name", ['dim1', undef ,'dim3']);
394 SDput
396 Write to a SDS in an HDF file or create and write to it if it doesn't exist.
397 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 Returns true on success, undef on failure.
406 The datatype of the SDS in the HDF file will match the PDL equivalent as
408 much as possible.
409 my $data = sequence( float, 10, 20, 30 ); #any value you want
411 # Simple case: create a new dataset with a $data pdl
413 my $result = $hdf->SDput("dataset_name", $data);
414 # Above, but also naming the dims:
416 $res = $hdf->SDput("dataset_name", $data, ['dim1','dim2','dim3']);
417 # Just putting a slice in there:
419 my $start = [x,y,z];
420 $res = $hdf->SDput("dataset_name", $data->slice("..."), undef, $start);
421 close
423 Close an HDF file.
424 No arguments.
426 my $result = $hdf->close();
428
430 Judd Taylor, Orbital Systems, Ltd. judd dot t at orbitalsystems dot
431 com
432
434 Patrick Leilde patrick.leilde@ifremer.fr contribs of Olivier Archer
435 olivier.archer@ifremer.fr
436
438 perl(1), PDL(1), PDL::IO::HDF(1).
439perl v5.12.3 2011-03-31 SD(3)