mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-12-21 07:51:46 +08:00
473 lines
14 KiB
Plaintext
473 lines
14 KiB
Plaintext
/** @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://\DWNURL/hdfview/hdfview3_3_1.html">Download HDFView</a> page.
|
|
\li Obtain the <a href="https://\AEXURL/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://\AEXURL/files/tutorial/storm1.txt">storm1.txt</a> file into the dataset.
|
|
|
|
If you downloaded <a href="https://\AEXURL/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://\AEXURL/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://\DOCURL/chunking_in_hdf5.html">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://\AEXURL/files/tutorial/storm1.txt">storm1.txt</a> file into the dataset. (See the previous topic for copying
|
|
<a href="https://\AEXURL/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://\AEXURL/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
|
|
|
|
*/
|