/** @page LearnHDFView Learning HDF5 with HDFView Navigate back: \ref index "Main" / \ref GettingStarted

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 Download HDFView page. \li Obtain the storm1.txt 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.

Unable to complete tutorial because fields are greyed out?
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: Bring up HDFView Left-mouse click on the Tools pull-down menu and select User Options. 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. Click on Apply and Close at the bottom of the window. Close down HDFView. Bring HDFView back up and try the tutorial again. 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.

\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.

@ref subsec_learn_hv_topics_file
@ref subsec_learn_hv_topics_image
@ref subsec_learn_hv_topics_attr
@ref subsec_learn_hv_topics_compress
@ref subsec_learn_hv_topics_subset
@ref subsec_learn_hv_topics_table

\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.

Select the File pull-down menu at the top left, and then select New -> HDF5.
Specify a location and type in storm.h5 for the name of your file, and click on the Save button. You will see the storm.h5 file in the TableView:

\image html storm.png
Right click on storm.h5, and select New -> Group.
Enter Data for the name of the group and then click the Ok button. You will see the group Data in the TableView.

\image html DataGroup.png
Right click on the group Data and select New -> Dataset.
A window pops up on the right. Fill in the information as follows, and then click Ok (leave the Datatype information as is):

Dataset Name Storm

Under Dataspace, Current size 57x57

Layout Contiguous (default)
Click to expand the Data group in the tree view to see the Storm dataset:

\image html StormDataset.png
Double left click on the Storm dataset in the tree view. A window with an empty spreadsheet pops open.
Copy the data from the storm1.txt file into the dataset. If you downloaded storm1.txt, then click on the Import/Export Data menu and select Import Data from -> Text File. Specify a location, select storm1.txt and click on the Open button. Answer Yes 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 Paste from the Table menu. The values will be entered into the spreadsheet.

\image html datasetwdata.png
Table -> Close the dataset, and save the data.

Dataset Name	Storm
Under Dataspace, Current size	57x57
Layout	Contiguous (default)

\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.

Right click on Storm in the tree view, and select Open As.
Select the Image button under Display As (near the top) in the Dataset Selection window that pops up. Then click OK at the bottom of the window to display the image.

\image html showasimage.png
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.

\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 /Data:

Click on the /Data folder in the tree view. You will see two tabs, Object Attribute Info and General Object Info, in the pane on the right site of the HDFView window.

\image html noattrs.png
With the left mouse button, select the Add Attribute button.
Select the Add Attribute button to add an attribute with these values:

Name	BatchID
Type	INTEGER
Size (bits)	32

Select the Ok button. The attribute will show up under the Object Attribute Info tab.
Double-click the BatchID attribute line to open the data table for BatchID.
Click in the first cell and enter 3343 followed by the enter key.
Table -> Close, answer Yes in the dialog box that pops up (which asks if you wish to paste the selected data).

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 /Storm dataset:

Left mouse click on the /Storm dataset in the tree view. You will see the Object Attribute Info and General Object Info tabs on the right
In the Object Attribute Info pane select the Add Attribute button and enter an attribute with these values. (Be sure to add a String Length or the string will be truncated to one character!):

Name	Units
Type	STRING
String Length	3

Select the Ok button. The attribute will show up under the Object Attribute Info tab.
Double-click the Units attribute line to open the data table for Units.
Click in the first cell and enter m/s followed by the enter key.
Table -> Close, answer Yes in the dialog box that pops up (which asks if you wish to paste the selected data).

\image html scarletletter.png

\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 chunks 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 Chunking in HDF5 documentation. Also see the HDF5 Tutorial topic on \ref secLBComDsetCreate.

Right click on storm.h5. Select New -> Group.
Enter Image for the name of the group, and click the OK button to create the group.

\image html newgroupimage.png
Right click on the Image group, and select New -> Dataset.
Enter the following information for the dataset. Leave the Datatype as is (INTEGER):

Dataset name Another Storm

Under Dataspace, Current size 57x57

Storage Layout Chunked

Chunk Size 20x20

Compression gzip

Compression Level 9
You will see the Another Storm dataset in the Image group:

\image html hdfview-anthrstrm.png
Double left-mouse click on the Another Storm dataset to display the spreadsheet:

\image html hdfview-anthrstrm-sprdsht.png
Copy the data from the storm1.txt file into the dataset. (See the previous topic for copying storm1.txt into a dataset.)
Table -> Close, and save the data.
Right click on Another Storm, and select Open As.
Select the Image button in the Dataset Selection window that pops up. Click the Ok button at the bottom of the window to view the dataset as an image.

\image html hdfview-anthrstrm-img.png

Dataset name	Another Storm
Under Dataspace, Current size	57x57
Storage Layout	Chunked
Chunk Size	20x20
Compression	gzip
Compression Level	9

\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.

Right click on the Data group and select New -> Image.
A window pops up on the right. Enter the following and then click Ok:

Image name	Storm Image
Height	57
Width	57

Close the dataset.
Expand the Data group to see its contents. You will see the Storm Image dataset.

\image html hdfview-imgicon.png
Add data to the Storm Image dataset as was shown previously:
- Right click on Storm Image, and select Open As to open the Dataset Selection window.
- Click on the Spreadsheet button at the top left of the Dataset Selection window to view the image as a spreadsheet.
- Copy the data from the storm1.txt file into the dataset.
- Close the dataset and save the data.
Left double click on Storm Image to see the image. Close the dataset.
Right click on Storm Image and select Open As to bring up the Data Selection window.
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 Ok.

\image html hdfview-imgsubset.png
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.
Select Image->Write Selection to Image. Enter Subset for the new image name. Click Ok. The Subset image will appear in the tree view on the left.
Left double click on the image Subset to bring it up on the right.

\image html hdfview-newimgsubset.png
Close the Subset image.

\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.

Right button click on the group Data. Select New -> Compound DS.

A window pops up. Only fill in the following fields:

Dataset name	Table
Dataspace (Current size only)	4
Compound Datatype Properties: Number of Members	3
Compound Datatype Properties: Name / Datatype / Size	Description / string / 4 Temperature / float / 1 Pressure / double / 1

\image html hdfview-newcmpd.png

Click Ok at the bottom.
Open the Data group (if it is not open) and double left click on the Table object.

\image html hdfview-table.png
Close the dataset.

Navigate back: \ref index "Main" / \ref GettingStarted */