summaryrefslogtreecommitdiffstats
path: root/doxygen/dox/LearnHDFView.dox
blob: b1f632caed22d4dcf7f4c7f34bccaed05bb0b929 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
/** @page LearnHDFView Learning HDF5 with HDFView

Navigate back: \ref index "Main" / \ref GettingStarted
<hr>

This tutorial enables you to get a feel for HDF5 by using the HDFView browser. It does NOT require
any programming experience.

\section sec_learn_hv_install HDFView Installation
\li Download and install HDFView. It can be downloaded from the <a href="https://portal.hdfgroup.org/display/support/Download+HDFView">Download HDFView</a> page.
\li Obtain the  <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/storm1.txt">storm1.txt</a> text file, used in the tutorial.

\section sec_learn_hv_begin Begin Tutorial
Once you have HDFView installed, bring it up and you are ready to begin the tutorial.

<table style="background-color:#FAFAD2">
<caption>
Unable to complete tutorial because fields are greyed out?
</caption>
<tr>
<td>
This tutorial requires that the default HDFView File Access Mode be Read / Write. If fields are greyed out so that you cannot select them, then the File Access Mode is Read Only.

To change the File Access Mode follow these steps:
<ul>
<li>Bring up HDFView</li>
<li>Left-mouse click on the Tools pull-down menu and select User Options.</li>
<li>A Preferences window pops up with the General Settings tab selected.
About half-way down you will see Default File Access Mode.
Select Read / Write.</li>
<li>Click on Apply and Close at the bottom of the window.</li>
<li>Close down HDFView.</li>
<li>Bring HDFView back up and try the tutorial again.</li>
PLEASE BE AWARE that selecting a File Access Mode of Read / Write can result in changes to the timestamp of HDF files that are viewed with HDFView. In general, a File Access Mode
of Read Only should be used to ensure that this does not occur.
</ul>
</td>
</tr>
</table>

\subsection subsec_learn_hv_begin_topics Topics Covered
Following are the topics covered in the tutorial. The first topic creates the file that is used in
the subsequent topics.
<ul>
<li>@ref subsec_learn_hv_topics_file</li>
<li>@ref subsec_learn_hv_topics_image</li>
<li>@ref subsec_learn_hv_topics_attr</li>
<li>@ref subsec_learn_hv_topics_compress</li>
<li>@ref subsec_learn_hv_topics_subset</li>
<li>@ref subsec_learn_hv_topics_table</li>
</ul>

\section sec_learn_hv_topics Topics

\subsection subsec_learn_hv_topics_file Creating a New HDF5 File with a Contiguous Dataset
The steps below describe how to create a file (storm.h5), group (/Data), and a contiguous dataset
(/Data/Storm) using HDFView. A group is an HDF5 object that allows objects to be collected together.
A dataset is an array of data values. A contiguous dataset is one that is stored as a single block
in the HDF5 file.
<ul>
<li>Select the <em>File</em> pull-down menu at the top left, and then select <em>New -> HDF5</em>.</li>
<li>Specify a location and type in <em>storm.h5</em> for the name of your file, and click on the <em>Save</em> button.
You will see the <em>storm.h5</em> file in the TableView:
<table>
<tr>
<td>
\image html storm.png 
</td>
</tr>
</table>
</li>
<li>Right click on <em>storm.h5</em>, and select <em>New -> Group</em>.</li>
<li>Enter <em>Data</em> for the name of the group and then click the <em>Ok</em> button. You will see the group <em>Data</em> in the TableView.
<table>
<tr>
<td>
\image html DataGroup.png 
</td>
</tr>
</table>
</li>
<li>Right click on the group <em>Data</em> and select <em>New -> Dataset</em>.</li>
<li>A window pops up on the right. Fill in the information as follows, and then click <em>Ok</em> (leave the
Datatype information as is):
<table>
<tr>
<th>Dataset Name
</th>
<td><em>Storm</em>
</td>
</tr>
<tr>
<th>Under Dataspace, Current size
</th>
<td>57x57
</td>
</tr>
<tr>
<th>Layout
</th>
<td><em>Contiguous</em> (default)
</td>
</tr>
</table>
</li>
<li>Click to expand the <em>Data</em> group in the tree view to see the <em>Storm</em> dataset:
<table>
<tr>
<td>
\image html StormDataset.png 
</td>
</tr>
</table>
</li>
<li>Double left click on the <em>Storm</em> dataset in the tree view. A window with an empty spreadsheet pops open.</li>
<li>Copy the data from the <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/storm1.txt">storm1.txt</a> file into the dataset.

If you downloaded <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/storm1.txt">storm1.txt</a>,
then click on the <em>Import/Export Data</em> menu and select <em>Import Data from -> Text File</em>.
Specify a location, select <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/storm1.txt">storm1.txt</a>
and click on the <em>Open</em> button. Answer <em>Yes</em> in the dialog box that
pops up (which asks if you wish to paste the selected data).

Alternately, you can copy/paste directly. Select and copy the data in a separate window. Position your
cursor at (0,0) in your table, and select <em>Paste</em> from the <em>Table</em> menu.

The values will be entered into the spreadsheet.
<table>
<tr>
<td>
\image html datasetwdata.png 
</td>
</tr>
</table>
</li>
<li><em>Table -> Close</em> the dataset, and save the data.</li>
</ul>

\subsection subsec_learn_hv_topics_image Displaying a Dataset as an Image
Any dataset can be viewed as an image in HDFView. Below are the steps that demonstrate this.
<ul>
<li>Right click on <em>Storm</em> in the tree view, and select <em>Open As</em>.</li>
<li>Select the <em>Image</em> button under <em>Display As</em> (near the top) in the Dataset Selection window that pops
up. Then click <em>OK</em> at the bottom of the window to display the image.
<table>
<tr>
<td>
\image html showasimage.png 
</td>
</tr>
</table>
</li>
<li>The rainbow icon brings you to the Image Palette window. Click on that to play with the palette
(GrayWave probably is the best choice). Close.</li>
</ul>

\subsection subsec_learn_hv_topics_attr Creating Attributes
Additional information to describe an object can be stored in attributes. An attribute can be
added to a group or dataset with HDFView.

The following illustrates how to add an attribute to the group <em>/Data</em>:
<ul>
<li>Click on the <em>/Data</em> folder in the tree view. You will see two tabs, <em>Object Attribute Info</em> and
<em>General Object Info</em>, in the pane on the right site of the HDFView window.
<table>
<tr>
<td>
\image html noattrs.png 
</td>
</tr>
</table>
</li>
<li>With the left mouse button, select the <em>Add Attribute</em> button.</li>
<li>Select the <em>Add Attribute</em> button to add an attribute with these values:</li>
<table>
<tr>
<th>Name
</th>
<td><em>BatchID</em>
</td>
</tr>
<tr>
<th>Type
</th>
<td>INTEGER
</td>
</tr>
<tr>
<th>Size (bits)
</th>
<td>32
</td>
</table>
<li>Select the <em>Ok</em> button. The attribute will show up under the <em>Object Attribute Info</em> tab.</li>
<li>Double-click the BatchID attribute line to open the data table for BatchID.</li>
<li>Click in the first cell and enter <em>3343</em> followed by the enter key.</li>
<li><em>Table -> Close</em>, answer <em>Yes</em> in the dialog box that
pops up (which asks if you wish to paste the selected data).</li>
</ul>
Adding an attribute to a dataset is very similar to adding an attribute to a group. For example,
the following adds an attribute to the <em>/Storm</em> dataset:
<ul>
<li>Left mouse click on the <em>/Storm</em> dataset in the tree view. You will see the <em>Object Attribute
Info</em> and <em>General Object Info</em> tabs on the right</li>
<li>In the <em>Object Attribute Info</em> pane select the <em>Add Attribute</em> button and enter an attribute with
these values. (Be sure to add a <em>String Length</em> or the string will be truncated to one character!):</li>
<table>
<tr>
<th>Name
</th>
<td><em>Units</em>
</td>
</tr>
<tr>
<th>Type
</th>
<td>STRING
</td>
</tr>
<tr>
<th>String Length
</th>
<td>3
</td>
</table>
<li>Select the <em>Ok</em> button. The attribute will show up under the <em>Object Attribute Info</em> tab.</li>
<li>Double-click the Units attribute line to open the data table for Units.</li>
<li>Click in the first cell and enter <em>m/s</em> followed by the enter key.</li>
<li><em>Table -> Close</em>, answer <em>Yes</em> in the dialog box that
pops up (which asks if you wish to paste the selected data).
<table>
<tr>
<td>
\image html scarletletter.png 
</td>
</tr>
</table>
</li>
</ul>

\subsection subsec_learn_hv_topics_compress Creating a Compressed and Chunked Dataset
A chunked and compressed dataset can be created using HDFView. A compressed dataset is a dataset
whose size has been compressed to take up less space. In order to compress an HDF5 dataset, the
dataset must be stored with a chunked dataset layout (as multiple <em>chunks</em> that are stored separately
in the file).

Please note that the chunk sizes used in this topic are for demonstration purposes only. For
information on chunking and specifying an appropriate chunk size, see the
<a href="https://confluence.hdfgroup.org/display/HDF5/Chunking+in+HDF5">Chunking in HDF5</a> documentation.

Also see the HDF5 Tutorial topic on \ref secLBComDsetCreate.
<ul>
<li>Right click on storm.h5. Select <em>New -> Group</em>.</li>
<li>Enter <em>Image</em> for the name of the group, and click the <em>OK</em> button to create the group.
<table>
<tr>
<td>
\image html newgroupimage.png 
</td>
</tr>
</table>
</li>
<li>Right click on the <em>Image</em> group, and select <em>New -> Dataset</em>.</li>
<li>Enter the following information for the dataset. Leave the <em>Datatype</em> as is (INTEGER):
<table>
<tr>
<th>Dataset name
</th>
<td><em>Another Storm</em>
</td>
</tr>
<tr>
<th>Under Dataspace, Current size
</th>
<td>57x57
</td>
</tr>
<tr>
<th>Storage Layout
</th>
<td>Chunked
</td>
</tr>
<tr>
<th>Chunk Size
</th>
<td>20x20
</td>
</tr>
<tr>
<th>Compression
</th>
<td>gzip
</td>
</tr>
<tr>
<th>Compression Level
</th>
<td>9
</td>
</table>
You will see the <em>Another Storm</em> dataset in the <em>Image</em> group:
<table>
<tr>
<td>
\image html hdfview-anthrstrm.png 
</td>
</tr>
</table>
</li>
<li>Double left-mouse click on the <em>Another Storm</em> dataset to display the spreadsheet:
<table>
<tr>
<td>
\image html hdfview-anthrstrm-sprdsht.png 
</td>
</tr>
</table>
</li>
<li>Copy the data from the <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/storm1.txt">storm1.txt</a> file into the dataset. (See the previous topic for copying
<a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/storm1.txt">storm1.txt</a> into a dataset.)</li>
<li><em>Table -> Close</em>, and save the data.</li>
<li>Right click on <em>Another Storm</em>, and select <em>Open As</em>.</li>
<li>Select the <em>Image</em> button in the Dataset Selection window that pops up. Click the <em>Ok</em> button at the
bottom of the window to view the dataset as an image.
<table>
<tr>
<td>
\image html hdfview-anthrstrm-img.png 
</td>
</tr>
</table>
</li>
</ul>

\subsection subsec_learn_hv_topics_subset Creating an Image and a Subset
A previous topic demonstrated how to view any dataset as an image in HDFView. With HDFView you can also
create an image to begin with, as is shown below.
<ul>
<li>Right click on the <em>Data</em> group and select <em>New -> Image</em>.</li>
<li>A window pops up on the right. Enter the following and then click <em>Ok</em>:</li>
<table>
<tr>
<th>Image name
</th>
<td><em>Storm Image</em>
</td>
</tr>
<tr>
<th>Height
</th>
<td>57
</td>
</tr>
<tr>
<th>Width
</th>
<td>57
</td>
</table>

<li>Close the dataset.</li>
<li>Expand the <em>Data</em> group to see its contents. You will see the <em>Storm Image</em> dataset.
<table>
<tr>
<td>
\image html hdfview-imgicon.png 
</td>
</tr>
</table>
</li>
<li>
Add data to the <em>Storm Image</em> dataset as was shown previously:
<ul>
<li>Right click on <em>Storm Image</em>, and select <em>Open As</em> to open the Dataset Selection window.</li>
<li>Click on the <em>Spreadsheet</em> button at the top left of the Dataset Selection window to view the image
as a spreadsheet.</li>
<li>Copy the data from the <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/storm1.txt">storm1.txt</a> file into the dataset.</li>
<li>Close the dataset and save the data.</li>
</ul>
</li>
<li>Left double click on <em>Storm Image</em> to see the image. Close the dataset.</li>
<li>Right click on <em>Storm Image</em> and select <em>Open As</em> to bring up the Data Selection window.</li>
<li>Select a subset by clicking the left mouse on the image in the window and dragging the mouse.
Notice that the Height and Width values change. Select to display it as an image. Click <em>Ok</em>.
<table>
<tr>
<td>
\image html hdfview-imgsubset.png 
</td>
</tr>
</table>
</li>
<li>Position the cursor in the middle of the image. Press Shift+Left Mouse button and hold, and then
drag the mouse to select another subset.</li>
<li>Select <em>Image->Write Selection to Image</em>. Enter <em>Subset</em> for the new image name. Click <em>Ok</em>. The <em>Subset</em>
image will appear in the tree view on the left.</li>
<li>Left double click on the image <em>Subset</em> to bring it up on the right.
<table>
<tr>
<td>
\image html hdfview-newimgsubset.png 
</td>
</tr>
</table>
</li>
<li>Close the <em>Subset</em> image.</li>
</ul>

\subsection subsec_learn_hv_topics_table Creating a Table (Compound Dataset)
A dataset with a compound datatype contains data elements that consist of multiple fields. If the
dataspace for the compound dataset is one-dimensional, then the dataset can be viewed as a table in
HDFView, as is shown below.
<ul>
<li>Right button click on the group <em>Data</em>. Select <em>New -> Compound DS</em>.</li>
<li>A window pops up. Only fill in the following fields:
<table>
<tr>
<th>Dataset name
</th>
<td>Table
</td>
</tr>
<tr>
<th>Dataspace (Current size only)
</th>
<td>4
</td>
</tr>
<tr>
<th>Compound Datatype Properties:
<br />Number of Members
</th>
<td>3
</td>
</tr>
<tr>
<th>Compound Datatype Properties:
<br /><em>Name</em> / Datatype / Size
</th>
<td><em>Description</em> / string / 4
<br /><em>Temperature</em> / float / 1
<br /><em>Pressure</em> / double / 1
</td>
</tr>
</table>

<table>
<tr>
<td>
\image html hdfview-newcmpd.png 
</td>
</tr>
</table>
</li>
<li>Click Ok at the bottom.</li>
<li>Open the Data group (if it is not open) and double left click on the Table object.
<table>
<tr>
<td>
\image html hdfview-table.png 
</td>
</tr>
</table>
</li>
<li>Close the dataset.</li>
</ul>

<hr>
Navigate back: \ref index "Main" / \ref GettingStarted

*/