1 files changed, 472 insertions, 0 deletions
diff --git a/doxygen/dox/LearnHDFView.dox b/doxygen/dox/LearnHDFView.dox
new file mode 100644
index 0000000..b1f632c
--- /dev/null
+++ b/doxygen/dox/LearnHDFView.dox
@@ -0,0 +1,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
+
+*/