mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-12-21 07:51:46 +08:00
817175e6e3
Fixes GH-3881 partially. There are pages that need to be recreated.
1197 lines
40 KiB
Plaintext
1197 lines
40 KiB
Plaintext
/** @page ViewTools Tools for Viewing and Editing HDF5 Files
|
|
|
|
Navigate back: \ref index "Main" / \ref GettingStarted
|
|
<hr>
|
|
|
|
\section secToolsBasic Basic Facts about HDF5
|
|
The following are basic facts about HDF5 files to keep in mind while completing these tutorial topics:
|
|
\li All HDF5 files contain a root group "/".
|
|
\li There are two primary objects in HDF5, a group and a dataset:<br />
|
|
Groups allow objects to be organized into a group structure, such as a tree.<br />
|
|
Datasets contain raw data values.
|
|
\li Additional information about an HDF5 object may optionally be stored in attributes attached to the object.
|
|
|
|
\section secToolsTopics Tutorial Topics
|
|
<table>
|
|
<tr>
|
|
<th>Tutorial Topic</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
@ref LearnHDFView
|
|
</td>
|
|
<td>Use HDFView to create, edit and view files.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
@ref ViewToolsCommand
|
|
</td>
|
|
<td>Use the HDF5 command-line tools for viewing, editing, and comparing HDF5 files.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>@ref ViewToolsJPSS
|
|
</td>
|
|
<td>Use HDF5 tools to examine and work with JPSS NPP files.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<hr>
|
|
Navigate back: \ref index "Main" / \ref GettingStarted
|
|
|
|
@page ViewToolsCommand Command-line Tools
|
|
Navigate back: \ref index "Main" / \ref GettingStarted
|
|
<hr>
|
|
|
|
\section secViewToolsCommandObtain Obtain Tools and Files (Optional)
|
|
Pre-built binaries for Linux and Windows are distributed within the respective HDF5 binary release
|
|
packages, which can be obtained from the <a href="https://portal.hdfgroup.org/downloads/index.html">Download HDF5</a> page.
|
|
|
|
HDF5 files can be obtained from various places such as \ref HDF5Examples and <a href="http://www.hdfeos.org/">HDF-EOS and Tools and
|
|
Information Center</a>. Specifically, the following examples are used in this tutorial topic:
|
|
\li HDF5 Files created from compiling the \ref LBExamples
|
|
\li HDF5 Files on the \ref ExAPI page
|
|
\li NPP JPSS files, <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5.gz">SVM01_npp.. (gzipped)</a>
|
|
and <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5.gz">SVM09_npp.. (gzipped)</a>
|
|
\li HDF-EOS <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/OMI-Aura.he5">OMI-Aura file</a>
|
|
|
|
\section secViewToolsCommandTutor Tutorial Topics
|
|
A variety of command-line tools are included in the HDF5 binary distribution. There are tools to view,
|
|
edit, convert and compare HDF5 files. This tutorial discusses the tools by their functionality. It
|
|
does not cover all of the HDF5 tools.
|
|
|
|
<table>
|
|
<tr>
|
|
<th>Tool Category</th>
|
|
<th>Topic</th>
|
|
<th>Tools Used</th>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>@ref ViewToolsView</strong></td>
|
|
<td>@ref secViewToolsViewContent</td>
|
|
<td>h5dump and h5ls
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>@ref secViewToolsViewDset</td>
|
|
<td>h5dump and h5ls
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>@ref secViewToolsViewGrps</td>
|
|
<td>h5dump and h5ls
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>@ref secViewToolsViewAttr</td>
|
|
<td>h5dump
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>@ref secViewToolsViewSub</td>
|
|
<td>h5dump
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>@ref secViewToolsViewDtypes</td>
|
|
<td>h5dump
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>@ref ViewToolsEdit</td>
|
|
<td>@ref secViewToolsEditRemove</td>
|
|
<td>h5repack
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>@ref secViewToolsEditChange</td>
|
|
<td>h5repack
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>@ref secViewToolsEditApply</td>
|
|
<td>h5repack
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>@ref secViewToolsEditCopy</td>
|
|
<td>h5copy
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>@ref secViewToolsEditAdd</td>
|
|
<td>h5jam and h5unjam
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>@ref ViewToolsConvert</td>
|
|
<td>@ref secViewToolsConvertASCII</td>
|
|
<td>h5dump
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>@ref secViewToolsConvertBinary</a></td>
|
|
<td>h5dump
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>@ref secViewToolsConvertExport</td>
|
|
<td>h5dump and h5import
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<hr>
|
|
Navigate back: \ref index "Main" / \ref GettingStarted
|
|
|
|
@page ViewToolsView Command-line Tools For Viewing HDF5 Files
|
|
Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand
|
|
<hr>
|
|
|
|
\section secViewToolsViewTOC Contents
|
|
<ul>
|
|
<li>\ref secViewToolsViewContent</li>
|
|
<li>\ref secViewToolsViewDset</li>
|
|
<li>\ref secViewToolsViewGrps</li>
|
|
<li>\ref secViewToolsViewAttr</li>
|
|
<li>\ref secViewToolsViewSub</li>
|
|
<li>\ref secViewToolsViewDtypes</li>
|
|
</ul>
|
|
|
|
\section secViewToolsViewContent File Content and Structure
|
|
The h5dump and h5ls tools can both be used to view the contents of an HDF5 file. The tools are discussed below:
|
|
<ul>
|
|
<li>\ref subsecViewToolsViewContent_h5dump</li>
|
|
<li>\ref subsecViewToolsViewContent_h5ls</li>
|
|
</ul>
|
|
|
|
\subsection subsecViewToolsViewContent_h5dump h5dump
|
|
The h5dump tool dumps or displays the contents of an HDF5 file (textually). By default if you specify no options,
|
|
h5dump will display the entire contents of a file. There are many h5dump options for examining specific details
|
|
of a file. To see all of the available h5dump options, specify the <code style="background-color:whitesmoke;">-h</code>
|
|
or <code style="background-color:whitesmoke;">--help</code> option:
|
|
\code
|
|
h5dump -h
|
|
\endcode
|
|
|
|
The following h5dump options can be helpful in viewing the content and structure of a file:
|
|
<table>
|
|
<tr>
|
|
<th>Option</th>
|
|
<th>Description</th>
|
|
<th>Comment</th>
|
|
</tr>
|
|
<tr>
|
|
<td>-n, --contents
|
|
</td>
|
|
<td>Displays a list of the objects in a file
|
|
</td>
|
|
<td>See @ref subsubsecViewToolsViewContent_h5dumpEx1
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>-n 1, --contents=1
|
|
</td>
|
|
<td>Displays a list of the objects and attributes in a file
|
|
</td>
|
|
<td>See @ref subsubsecViewToolsViewAttr_h5dumpEx6
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>-H, --header
|
|
</td>
|
|
<td>Displays header information only (no data)
|
|
</td>
|
|
<td>See @ref subsubsecViewToolsViewContent_h5dumpEx2
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>-A 0, --onlyattr=0
|
|
</td>
|
|
<td>Suppresses the display of attributes
|
|
</td>
|
|
<td>See @ref subsubsecViewToolsViewContent_h5dumpEx2
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>-N P, --any_path=P
|
|
</td>
|
|
<td>Displays any object or attribute that matches path P
|
|
</td>
|
|
<td>See @ref subsubsecViewToolsViewAttr_h5dumpEx6
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
\subsubsection subsubsecViewToolsViewContent_h5dumpEx1 Example 1
|
|
The following command displays a list of the objects in the file OMI-Aura.he5 (an HDF-EOS5 file):
|
|
\code
|
|
h5dump -n OMI-Aura.he5
|
|
\endcode
|
|
|
|
As shown in the output below, the objects (groups, datasets) are listed to the left, followed by their
|
|
names. You can see that this file contains two root groups, HDFEOS and HDFEOS INFORMATION:
|
|
\code
|
|
HDF5 "OMI-Aura.he5" {
|
|
FILE_CONTENTS {
|
|
group /
|
|
group /HDFEOS
|
|
group /HDFEOS/ADDITIONAL
|
|
group /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES
|
|
group /HDFEOS/GRIDS
|
|
group /HDFEOS/GRIDS/OMI Column Amount O3
|
|
group /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields
|
|
dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/ColumnAmountO3
|
|
dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/RadiativeCloudFraction
|
|
dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle
|
|
dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/ViewingZenithAngle
|
|
group /HDFEOS INFORMATION
|
|
dataset /HDFEOS INFORMATION/StructMetadata.0
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
\subsubsection subsubsecViewToolsViewContent_h5dumpEx2 Example 2
|
|
The file structure of the OMI-Aura.he5 file can be seen with the following command. The -A 0 option suppresses the display of attributes:
|
|
\code
|
|
h5dump -H -A 0 OMI-Aura.he5
|
|
\endcode
|
|
|
|
Output of this command is shown below:
|
|
\code
|
|
HDF5 "OMI-Aura.he5" {
|
|
GROUP "/" {
|
|
GROUP "HDFEOS" {
|
|
GROUP "ADDITIONAL" {
|
|
GROUP "FILE_ATTRIBUTES" {
|
|
}
|
|
}
|
|
GROUP "GRIDS" {
|
|
GROUP "OMI Column Amount O3" {
|
|
GROUP "Data Fields" {
|
|
DATASET "ColumnAmountO3" {
|
|
DATATYPE H5T_IEEE_F32LE
|
|
DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
|
|
}
|
|
DATASET "RadiativeCloudFraction" {
|
|
DATATYPE H5T_IEEE_F32LE
|
|
DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
|
|
}
|
|
DATASET "SolarZenithAngle" {
|
|
DATATYPE H5T_IEEE_F32LE
|
|
DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
|
|
}
|
|
DATASET "ViewingZenithAngle" {
|
|
DATATYPE H5T_IEEE_F32LE
|
|
DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
GROUP "HDFEOS INFORMATION" {
|
|
DATASET "StructMetadata.0" {
|
|
DATATYPE H5T_STRING {
|
|
STRSIZE 32000;
|
|
STRPAD H5T_STR_NULLTERM;
|
|
CSET H5T_CSET_ASCII;
|
|
CTYPE H5T_C_S1;
|
|
}
|
|
DATASPACE SCALAR
|
|
}
|
|
}
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
\subsection subsecViewToolsViewContent_h5ls h5ls
|
|
The h5ls tool by default just displays the objects in the root group. It will not display
|
|
items in groups beneath the root group unless specified. Useful h5ls options for viewing
|
|
file content and structure are:
|
|
<table>
|
|
<tr>
|
|
<th>Option</th>
|
|
<th>Description</th>
|
|
<th>Comment</th>
|
|
</tr>
|
|
<tr>
|
|
<td>-r
|
|
</td>
|
|
<td>Lists all groups and objects recursively
|
|
</td>
|
|
<td>See @ref subsubsecViewToolsViewContent_h5lsEx3
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>-v
|
|
</td>
|
|
<td>Generates verbose output (lists dataset properties, attributes
|
|
and attribute values, but no dataset values)
|
|
</td>
|
|
<td>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
\subsubsection subsubsecViewToolsViewContent_h5lsEx3 Example 3
|
|
The following command shows the contents of the HDF-EOS5 file OMI-Aura.he5. The output is similar to h5dump, except that h5ls also shows dataspace information for each dataset:
|
|
\code
|
|
h5ls -r OMI-Aura.he5
|
|
\endcode
|
|
|
|
The output is shown below:
|
|
\code
|
|
/ Group
|
|
/HDFEOS Group
|
|
/HDFEOS/ADDITIONAL Group
|
|
/HDFEOS/ADDITIONAL/FILE_ATTRIBUTES Group
|
|
/HDFEOS/GRIDS Group
|
|
/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3 Group
|
|
/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields Group
|
|
/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ColumnAmountO3 Dataset {720, 1440}
|
|
/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/RadiativeCloudFraction Dataset {720, 1440}
|
|
/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/SolarZenithAngle Dataset {720, 1440}
|
|
/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ViewingZenithAngle Dataset {720, 1440}
|
|
/HDFEOS\ INFORMATION Group
|
|
/HDFEOS\ INFORMATION/StructMetadata.0 Dataset {SCALAR}
|
|
\endcode
|
|
|
|
\section secViewToolsViewDset Datasets and Dataset Properties
|
|
Both h5dump and h5ls can be used to view specific datasets.
|
|
<ul>
|
|
<li>\ref subsecViewToolsViewDset_h5dump</li>
|
|
<li>\ref subsecViewToolsViewDset_h5ls</li>
|
|
</ul>
|
|
|
|
\subsection subsecViewToolsViewDset_h5dump h5dump
|
|
Useful h5dump options for examining specific datasets include:
|
|
<table>
|
|
<tr>
|
|
<th>Option</th>
|
|
<th>Description</th>
|
|
<th>Comment</th>
|
|
</tr>
|
|
<tr>
|
|
<td>-d D, --dataset=D
|
|
</td>
|
|
<td>Displays dataset D
|
|
</td>
|
|
<td>See @ref subsubsecViewToolsViewDset_h5dumpEx4
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td> -H, --header
|
|
</td>
|
|
<td>Displays header information only
|
|
</td>
|
|
<td>See @ref subsubsecViewToolsViewDset_h5dumpEx4
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>-p, --properties
|
|
</td>
|
|
<td>Displays dataset filters, storage layout, and fill value properties
|
|
</td>
|
|
<td>See @ref subsubsecViewToolsViewDset_h5dumpEx5
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>-A 0, --onlyattr=0
|
|
</td>
|
|
<td>Suppresses the display of attributes
|
|
</td>
|
|
<td>See @ref subsubsecViewToolsViewContent_h5dumpEx2
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>-N P, --any_path=P
|
|
</td>
|
|
<td>Displays any object or attribute that matches path P
|
|
</td>
|
|
<td>See @ref subsubsecViewToolsViewAttr_h5dumpEx6
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
\subsubsection subsubsecViewToolsViewDset_h5dumpEx4 Example 4
|
|
A specific dataset can be viewed with <code style="background-color:whitesmoke;">h5dump</code> using the <code style="background-color:whitesmoke;">-d D</code> option and specifying the entire
|
|
path and name of the dataset for <code style="background-color:whitesmoke;">D</code>. The path is important in identifying the correct dataset,
|
|
as there can be multiple datasets with the same name. The path can be determined by looking at
|
|
the objects in the file with <code style="background-color:whitesmoke;">h5dump -n</code>.
|
|
|
|
The following example uses the <code style="background-color:whitesmoke;">groups.h5</code> file that is created by the
|
|
\ref LBExamples
|
|
example <code style="background-color:whitesmoke;">h5_crtgrpar.c</code>. To display <code style="background-color:whitesmoke;">dset1</code> in the <code style="background-color:whitesmoke;">groups.h5</code> file below, specify dataset
|
|
<code style="background-color:whitesmoke;">/MyGroup/dset1</code>. The <code style="background-color:whitesmoke;">-H</code> option is used to suppress printing of the data values:
|
|
|
|
<em>Contents of groups.h5</em>
|
|
\code
|
|
$ h5dump -n groups.h5
|
|
HDF5 "groups.h5" {
|
|
FILE_CONTENTS {
|
|
group /
|
|
group /MyGroup
|
|
group /MyGroup/Group_A
|
|
dataset /MyGroup/Group_A/dset2
|
|
group /MyGroup/Group_B
|
|
dataset /MyGroup/dset1
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
<em>Display dataset "dset1"</em>
|
|
\code
|
|
$ h5dump -d "/MyGroup/dset1" -H groups.h5
|
|
HDF5 "groups.h5" {
|
|
DATASET "/MyGroup/dset1" {
|
|
DATATYPE H5T_STD_I32BE
|
|
DATASPACE SIMPLE { ( 3, 3 ) / ( 3, 3 ) }
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
\subsubsection subsubsecViewToolsViewDset_h5dumpEx5 Example 5
|
|
The <code style="background-color:whitesmoke;">-p</code> option is used to examine the dataset filters, storage layout, and fill value properties of a dataset.
|
|
|
|
This option can be useful for checking how well compression works, or even for analyzing performance
|
|
and dataset size issues related to chunking. (The smaller the chunk size, the more chunks that HDF5
|
|
has to keep track of, which increases the size of the file and potentially affects performance.)
|
|
|
|
In the file shown below the dataset <code style="background-color:whitesmoke;">/DS1</code> is both chunked and compressed:
|
|
\code
|
|
$ h5dump -H -p -d "/DS1" h5ex_d_gzip.h5
|
|
HDF5 "h5ex_d_gzip.h5" {
|
|
DATASET "/DS1" {
|
|
DATATYPE H5T_STD_I32LE
|
|
DATASPACE SIMPLE { ( 32, 64 ) / ( 32, 64 ) }
|
|
STORAGE_LAYOUT {
|
|
CHUNKED ( 4, 8 )
|
|
SIZE 5278 (1.552:1 COMPRESSION)
|
|
}
|
|
FILTERS {
|
|
COMPRESSION DEFLATE { LEVEL 9 }
|
|
}
|
|
FILLVALUE {
|
|
FILL_TIME H5D_FILL_TIME_IFSET
|
|
VALUE 0
|
|
}
|
|
ALLOCATION_TIME {
|
|
H5D_ALLOC_TIME_INCR
|
|
}
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
You can obtain the <code style="background-color:whitesmoke;">h5ex_d_gzip.c</code> program that created this file, as well as the file created,
|
|
from the \ref ExAPI page.
|
|
|
|
\subsection subsecViewToolsViewDset_h5ls h5ls
|
|
Specific datasets can be specified with <code style="background-color:whitesmoke;">h5ls</code> by simply adding the dataset path and dataset after the
|
|
file name. As an example, this command displays dataset <code style="background-color:whitesmoke;">dset2</code> in the <code style="background-color:whitesmoke;">groups.h5</code>
|
|
file used in @ref subsubsecViewToolsViewDset_h5dumpEx4 :
|
|
\code
|
|
h5ls groups.h5/MyGroup/Group_A/dset2
|
|
\endcode
|
|
|
|
Just the dataspace information gets displayed:
|
|
\code
|
|
dset2 Dataset {2, 10}
|
|
\endcode
|
|
|
|
The following options can be used to see detailed information about a dataset.
|
|
<table>
|
|
<tr>
|
|
<th>Option</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>-v, --verbose
|
|
</td>
|
|
<td>Generates verbose output (lists dataset properties, attributes
|
|
and attribute values, but no dataset values)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>-d, --data
|
|
</td>
|
|
<td>Displays dataset values
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
The output of using <code style="background-color:whitesmoke;">-v</code> is shown below:
|
|
\code
|
|
$ h5ls -v groups.h5/MyGroup/Group_A/dset2
|
|
Opened "groups.h5" with sec2 driver.
|
|
dset2 Dataset {2/2, 10/10}
|
|
Location: 1:3840
|
|
Links: 1
|
|
Storage: 80 logical bytes, 80 allocated bytes, 100.00% utilization
|
|
Type: 32-bit big-endian integer
|
|
\endcode
|
|
|
|
The output of using <code style="background-color:whitesmoke;">-d</code> is shown below:
|
|
\code
|
|
$ h5ls -d groups.h5/MyGroup/Group_A/dset2
|
|
dset2 Dataset {2, 10}
|
|
Data:
|
|
(0,0) 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
|
|
\endcode
|
|
|
|
\section secViewToolsViewGrps Groups
|
|
Both h5dump and h5ls can be used to view specific groups in a file.
|
|
<ul>
|
|
<li>\ref subsecViewToolsViewGrps_h5dump</li>
|
|
<li>\ref subsecViewToolsViewGrps_h5ls</li>
|
|
</ul>
|
|
|
|
\subsection subsecViewToolsViewGrps_h5dump h5dump
|
|
The <code style="background-color:whitesmoke;">h5dump</code> options that are useful for examining groups are:
|
|
<table>
|
|
<tr>
|
|
<th>Option</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>-g G, --group=G
|
|
</td>
|
|
<td>Displays group G and its members
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>-H, --header
|
|
</td>
|
|
<td>Displays header information only
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>-A 0, --onlyattr=0
|
|
</td>
|
|
<td>Suppresses the display of attributes
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
To view the contents of the <code style="background-color:whitesmoke;">HDFEOS</code> group in the OMI file mentioned previously, you can specify the path and name of the group as follows:
|
|
\code
|
|
h5dump -g "/HDFEOS" -H -A 0 OMI-Aura.he5
|
|
\endcode
|
|
|
|
The <code style="background-color:whitesmoke;">-A 0</code> option suppresses attributes and <code style="background-color:whitesmoke;">-H</code> suppresses printing of data values:
|
|
\code
|
|
HDF5 "OMI-Aura.he5" {
|
|
GROUP "/HDFEOS" {
|
|
GROUP "ADDITIONAL" {
|
|
GROUP "FILE_ATTRIBUTES" {
|
|
}
|
|
}
|
|
GROUP "GRIDS" {
|
|
GROUP "OMI Column Amount O3" {
|
|
GROUP "Data Fields" {
|
|
DATASET "ColumnAmountO3" {
|
|
DATATYPE H5T_IEEE_F32LE
|
|
DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
|
|
}
|
|
DATASET "RadiativeCloudFraction" {
|
|
DATATYPE H5T_IEEE_F32LE
|
|
DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
|
|
}
|
|
DATASET "SolarZenithAngle" {
|
|
DATATYPE H5T_IEEE_F32LE
|
|
DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
|
|
}
|
|
DATASET "ViewingZenithAngle" {
|
|
DATATYPE H5T_IEEE_F32LE
|
|
DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
\subsection subsecViewToolsViewGrps_h5ls h5ls
|
|
You can view the contents of a group with <code style="background-color:whitesmoke;">h5ls</code>/ by specifying the group after the file name.
|
|
To use <code style="background-color:whitesmoke;">h5ls</code> to view the contents of the <code style="background-color:whitesmoke;">/HDFEOS</code> group in the <code style="background-color:whitesmoke;">OMI-Aura.he5</code> file, type:
|
|
\code
|
|
h5ls -r OMI-Aura.he5/HDFEOS
|
|
\endcode
|
|
|
|
The output of this command is:
|
|
\code
|
|
/ADDITIONAL Group
|
|
/ADDITIONAL/FILE_ATTRIBUTES Group
|
|
/GRIDS Group
|
|
/GRIDS/OMI\ Column\ Amount\ O3 Group
|
|
/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields Group
|
|
/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ColumnAmountO3 Dataset {720, 1440}
|
|
/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/RadiativeCloudFraction Dataset {720, 1440}
|
|
/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/SolarZenithAngle Dataset {720, 1440}
|
|
/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ViewingZenithAngle Dataset {720, 1440}
|
|
\endcode
|
|
|
|
If you specify the <code style="background-color:whitesmoke;">-v</code> option, you can also see the attributes and properties of the datasets.
|
|
|
|
\section secViewToolsViewAttr Attributes
|
|
|
|
\subsection subsecViewToolsViewAttr_h5dump h5dump
|
|
Attributes are displayed by default if using <code style="background-color:whitesmoke;">h5dump</code>. Some files contain many attributes, which
|
|
can make it difficult to examine the objects in the file. Shown below are options that can help
|
|
when using <code style="background-color:whitesmoke;">h5dump</code> to work with files that have attributes.
|
|
|
|
\subsubsection subsubsecViewToolsViewAttr_h5dumpEx6 Example 6
|
|
The <code style="background-color:whitesmoke;">-a</code> A option will display an attribute. However, the path to the attribute must be included
|
|
when specifying this option. For example, to see the <code style="background-color:whitesmoke;">ScaleFactor</code> attribute in the <code style="background-color:whitesmoke;">OMI-Aura.he5</code> file, type:
|
|
\code
|
|
h5dump -a "/HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle/ScaleFactor" OMI-Aura.he5
|
|
\endcode
|
|
|
|
This command displays:
|
|
\code
|
|
HDF5 "OMI-Aura.he5" {
|
|
ATTRIBUTE "ScaleFactor" {
|
|
DATATYPE H5T_IEEE_F64LE
|
|
DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
|
|
DATA {
|
|
(0): 1
|
|
}
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
How can you determine the path to the attribute? This can be done by looking at the file contents with the <code style="background-color:whitesmoke;">-n 1</code> option:
|
|
\code
|
|
h5dump -n 1 OMI-Aura.he5
|
|
\endcode
|
|
|
|
Below is a portion of the output for this command:
|
|
\code
|
|
HDF5 "OMI-Aura.he5" {
|
|
FILE_CONTENTS {
|
|
group /
|
|
group /HDFEOS
|
|
group /HDFEOS/ADDITIONAL
|
|
group /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES
|
|
attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/EndUTC
|
|
attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleDay
|
|
attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleDayOfYear
|
|
attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleMonth
|
|
attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleYear
|
|
attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/InstrumentName
|
|
attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/OrbitNumber
|
|
attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/OrbitPeriod
|
|
attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/PGEVersion
|
|
attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/Period
|
|
attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/ProcessLevel
|
|
attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/StartUTC
|
|
attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/TAI93At0zOfGranule
|
|
|
|
...
|
|
\endcode
|
|
|
|
There can be multiple objects or attributes with the same name in a file. How can you make sure
|
|
you are finding the correct object or attribute? You can first determine how many attributes
|
|
there are with a specified name, and then examine the paths to them.
|
|
|
|
The <code style="background-color:whitesmoke;">-N</code> option can be used to display all objects or attributes with a given name.
|
|
For example, there are four attributes with the name <code style="background-color:whitesmoke;">ScaleFactor</code> in the <code style="background-color:whitesmoke;">OMI-Aura.he5</code> file,
|
|
as can be seen below with the <code style="background-color:whitesmoke;">-N</code> option:
|
|
\code
|
|
h5dump -N ScaleFactor OMI-Aura.he5
|
|
\endcode
|
|
|
|
It outputs:
|
|
\code
|
|
HDF5 "OMI-Aura.he5" {
|
|
ATTRIBUTE "ScaleFactor" {
|
|
DATATYPE H5T_IEEE_F64LE
|
|
DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
|
|
DATA {
|
|
(0): 1
|
|
}
|
|
}
|
|
ATTRIBUTE "ScaleFactor" {
|
|
DATATYPE H5T_IEEE_F64LE
|
|
DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
|
|
DATA {
|
|
(0): 1
|
|
}
|
|
}
|
|
ATTRIBUTE "ScaleFactor" {
|
|
DATATYPE H5T_IEEE_F64LE
|
|
DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
|
|
DATA {
|
|
(0): 1
|
|
}
|
|
}
|
|
ATTRIBUTE "ScaleFactor" {
|
|
DATATYPE H5T_IEEE_F64LE
|
|
DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
|
|
DATA {
|
|
(0): 1
|
|
}
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
\subsection subsecViewToolsViewAttr_h5ls h5ls
|
|
If you include the <code style="background-color:whitesmoke;">-v</code> (verbose) option for <code style="background-color:whitesmoke;">h5ls</code>, you will see all of the attributes for the
|
|
specified file, dataset or group. You cannot display individual attributes.
|
|
|
|
\section secViewToolsViewSub Dataset Subset
|
|
|
|
\subsection subsecViewToolsViewSub_h5dump h5dump
|
|
If you have a very large dataset, you may wish to subset or see just a portion of the dataset.
|
|
This can be done with the following <code style="background-color:whitesmoke;">h5dump</code> options.
|
|
<table>
|
|
<tr>
|
|
<th>Option</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>-d D, --dataset=D
|
|
</td>
|
|
<td>Dataset D
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>-s START, --start=START
|
|
</td>
|
|
<td>Offset or start of subsetting selection
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>-S STRIDE, --stride=STRIDE
|
|
</td>
|
|
<td>Stride (sampling along a dimension). The default (unspecified, or 1) selects
|
|
every element along a dimension, a value of 2 selects every other element,
|
|
a value of 3 selects every third element, ...
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>-c COUNT, --count=COUNT
|
|
</td>
|
|
<td>Number of blocks to include in the selection
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>-k BLOCK, --block=BLOCK
|
|
</td>
|
|
<td>Size of the block in a hyperslab. The default (unspecified, or 1) is for
|
|
the block size to be the size of a single element.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
The <code style="background-color:whitesmoke;">START (s)</code>, <code style="background-color:whitesmoke;">STRIDE (S)</code>, <code style="background-color:whitesmoke;">COUNT (c)</code>, and <code style="background-color:whitesmoke;">BLOCK (k)</code> options
|
|
define the shape and size of the selection. They are arrays with the same number of dimensions as the rank
|
|
of the dataset's dataspace, and they all work together to define the selection. A change to one of
|
|
these arrays can affect the others.
|
|
|
|
When specifying these h5dump options, a comma is used as the delimiter for each dimension in the
|
|
option value. For example, with a 2-dimensional dataset, the option value is specified as "H,W",
|
|
where H is the height and W is the width. If the offset is 0 for both dimensions, then
|
|
<code style="background-color:whitesmoke;">START</code> would be specified as follows:
|
|
\code
|
|
-s "0,0"
|
|
\endcode
|
|
|
|
There is also a shorthand way to specify these options with brackets at the end of the dataset name:
|
|
\code
|
|
-d DATASETNAME[s;S;c;k]
|
|
\endcode
|
|
|
|
Multiple dimensions are separated by commas. For example, a subset for a 2-dimensional dataset would be specified as follows:
|
|
\code
|
|
-d DATASETNAME[s,s;S,S;c,c;k,k]
|
|
\endcode
|
|
|
|
For a detailed understanding of how selections works, see the #H5Sselect_hyperslab API in the \ref RM.
|
|
|
|
The dataset SolarZenithAngle in the OMI-Aura.he5 file can be used to illustrate these options. This
|
|
dataset is a 2-dimensional dataset of size 720 (height) x 1440 (width). Too much data will be displayed
|
|
by simply viewing the specified dataset with the <code style="background-color:whitesmoke;">-d</code> option:
|
|
\code
|
|
h5dump -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" OMI-Aura.he5
|
|
\endcode
|
|
|
|
Subsetting narrows down the output that is displayed. In the following example, the first
|
|
15x10 elements (-c "15,10") are specified, beginning with position (0,0) (-s "0,0"):
|
|
\code
|
|
h5dump -A 0 -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" -s "0,0" -c "15,10" -w 0 OMI-Aura.he5
|
|
\endcode
|
|
|
|
If using the shorthand method, specify:
|
|
\code
|
|
h5dump -A 0 -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle[0,0;;15,10;]" -w 0 OMI-Aura.he5
|
|
\endcode
|
|
|
|
Where, the <code style="background-color:whitesmoke;">-d</code> option must be specified
|
|
before subsetting options (if not using the shorthand method).
|
|
|
|
The <code style="background-color:whitesmoke;">-A 0</code> option suppresses the printing of attributes.
|
|
|
|
The <code style="background-color:whitesmoke;">-w 0</code> option sets the number of columns of output to the maximum allowed value (65535).
|
|
This ensures that there are enough columns specified for displaying the data.
|
|
|
|
Either command displays:
|
|
\code
|
|
HDF5 "OMI-Aura.he5" {
|
|
DATASET "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" {
|
|
DATATYPE H5T_IEEE_F32LE
|
|
DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
|
|
SUBSET {
|
|
START ( 0, 0 );
|
|
STRIDE ( 1, 1 );
|
|
COUNT ( 15, 10 );
|
|
BLOCK ( 1, 1 );
|
|
DATA {
|
|
(0,0): 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403,
|
|
(1,0): 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071,
|
|
(2,0): 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867,
|
|
(3,0): 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632,
|
|
(4,0): 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429,
|
|
(5,0): 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225,
|
|
(6,0): 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021,
|
|
(7,0): 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715,
|
|
(8,0): 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511,
|
|
(9,0): 77.658, 77.658, 77.658, 77.307, 77.307, 77.307, 77.307, 77.307, 77.307, 77.307,
|
|
(10,0): 77.556, 77.556, 77.556, 77.556, 77.556, 77.556, 77.556, 77.556, 77.102, 77.102,
|
|
(11,0): 78.408, 78.408, 78.408, 78.408, 78.408, 78.408, 78.408, 78.408, 77.102, 77.102,
|
|
(12,0): 76.34, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413,
|
|
(13,0): 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 77.195,
|
|
(14,0): 78.005, 78.005, 78.005, 78.005, 78.005, 78.005, 76.991, 76.991, 76.991, 76.991
|
|
}
|
|
}
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
What if we wish to read three rows of three elements at a time (-c "3,3"), where each element
|
|
is a 2 x 3 block (-k "2,3") and we wish to begin reading from the second row (-s "1,0")?
|
|
|
|
You can do that with the following command:
|
|
\code
|
|
h5dump -A 0 -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle"
|
|
-s "1,0" -S "2,3" -c "3,3" -k "2,3" -w 0 OMI-Aura.he5
|
|
\endcode
|
|
|
|
In this case, the stride must be specified as 2 by 3 (or larger) to accommodate the reading of 2 by 3 blocks.
|
|
If it is smaller, the command will fail with the error,
|
|
\code
|
|
h5dump error: wrong subset selection; blocks overlap.
|
|
\endcode
|
|
|
|
The output of the above command is shown below:
|
|
\code
|
|
HDF5 "OMI-Aura.he5" {
|
|
DATASET "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" {
|
|
DATATYPE H5T_IEEE_F32LE
|
|
DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
|
|
SUBSET {
|
|
START ( 1, 0 );
|
|
STRIDE ( 2, 3 );
|
|
COUNT ( 3, 3 );
|
|
BLOCK ( 2, 3 );
|
|
DATA {
|
|
(1,0): 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071,
|
|
(2,0): 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867,
|
|
(3,0): 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632,
|
|
(4,0): 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429,
|
|
(5,0): 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225,
|
|
(6,0): 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021
|
|
}
|
|
}
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
\section secViewToolsViewDtypes Datatypes
|
|
|
|
\subsection subsecViewToolsViewDtypes_h5dump h5dump
|
|
The following datatypes are discussed, using the output of <code style="background-color:whitesmoke;">h5dump</code> with HDF5 files from the
|
|
\ref ExAPI page:
|
|
<ul>
|
|
<li>@ref subsubsecViewToolsViewDtypes_array</li>
|
|
<li>@ref subsubsecViewToolsViewDtypes_objref</li>
|
|
<li>@ref subsubsecViewToolsViewDtypes_regref</li>
|
|
<li>@ref subsubsecViewToolsViewDtypes_string</li>
|
|
</ul>
|
|
|
|
\subsubsection subsubsecViewToolsViewDtypes_array Array
|
|
Users have been confused by the difference between an Array datatype (#H5T_ARRAY) and a dataset that
|
|
(has a dataspace that) is an array.
|
|
|
|
Typically, these users want a dataset that has a simple datatype (like integer or float) that is an
|
|
array, like the following dataset <code style="background-color:whitesmoke;">/DS1</code>. It has a datatype of #H5T_STD_I32LE (32-bit Little-Endian Integer)
|
|
and is a 4 by 7 array:
|
|
\code
|
|
$ h5dump h5ex_d_rdwr.h5
|
|
HDF5 "h5ex_d_rdwr.h5" {
|
|
GROUP "/" {
|
|
DATASET "DS1" {
|
|
DATATYPE H5T_STD_I32LE
|
|
DATASPACE SIMPLE { ( 4, 7 ) / ( 4, 7 ) }
|
|
DATA {
|
|
(0,0): 0, -1, -2, -3, -4, -5, -6,
|
|
(1,0): 0, 0, 0, 0, 0, 0, 0,
|
|
(2,0): 0, 1, 2, 3, 4, 5, 6,
|
|
(3,0): 0, 2, 4, 6, 8, 10, 12
|
|
}
|
|
}
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
Contrast that with the following dataset that has both an Array datatype and is an array:
|
|
\code
|
|
$ h5dump h5ex_t_array.h5
|
|
HDF5 "h5ex_t_array.h5" {
|
|
GROUP "/" {
|
|
DATASET "DS1" {
|
|
DATATYPE H5T_ARRAY { [3][5] H5T_STD_I64LE }
|
|
DATASPACE SIMPLE { ( 4 ) / ( 4 ) }
|
|
DATA {
|
|
(0): [ 0, 0, 0, 0, 0,
|
|
0, -1, -2, -3, -4,
|
|
0, -2, -4, -6, -8 ],
|
|
(1): [ 0, 1, 2, 3, 4,
|
|
1, 1, 1, 1, 1,
|
|
2, 1, 0, -1, -2 ],
|
|
(2): [ 0, 2, 4, 6, 8,
|
|
2, 3, 4, 5, 6,
|
|
4, 4, 4, 4, 4 ],
|
|
(3): [ 0, 3, 6, 9, 12,
|
|
3, 5, 7, 9, 11,
|
|
6, 7, 8, 9, 10 ]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
In this file, dataset <code style="background-color:whitesmoke;">/DS1</code> has a datatype of
|
|
\code
|
|
H5T_ARRAY { [3][5] H5T_STD_I64LE }
|
|
\endcode
|
|
and it also has a dataspace of
|
|
\code
|
|
SIMPLE { ( 4 ) / ( 4 ) }
|
|
\endcode
|
|
In other words, it is an array of four elements, in which each element is a 3 by 5 array of #H5T_STD_I64LE.
|
|
|
|
This dataset is much more complex. Also note that subsetting cannot be done on Array datatypes.
|
|
|
|
See this <a href="https://portal.hdfgroup.org/display/knowledge/H5T_ARRAY+Datatype">FAQ</a> for more information on the Array datatype.
|
|
|
|
\subsubsection subsubsecViewToolsViewDtypes_objref Object Reference
|
|
An Object Reference is a reference to an entire object (dataset, group, or named datatype).
|
|
A dataset with an Object Reference datatype consists of one or more Object References.
|
|
An Object Reference dataset can be used as an index to an HDF5 file.
|
|
|
|
The <code style="background-color:whitesmoke;">/DS1</code> dataset in the following file (<code style="background-color:whitesmoke;">h5ex_t_objref.h5</code>) is an Object Reference dataset.
|
|
It contains two references, one to group <code style="background-color:whitesmoke;">/G1</code> and the other to dataset <code style="background-color:whitesmoke;">/DS2</code>:
|
|
\code
|
|
$ h5dump h5ex_t_objref.h5
|
|
HDF5 "h5ex_t_objref.h5" {
|
|
GROUP "/" {
|
|
DATASET "DS1" {
|
|
DATATYPE H5T_REFERENCE { H5T_STD_REF_OBJECT }
|
|
DATASPACE SIMPLE { ( 2 ) / ( 2 ) }
|
|
DATA {
|
|
(0): GROUP 1400 /G1 , DATASET 800 /DS2
|
|
}
|
|
}
|
|
DATASET "DS2" {
|
|
DATATYPE H5T_STD_I32LE
|
|
DATASPACE NULL
|
|
DATA {
|
|
}
|
|
}
|
|
GROUP "G1" {
|
|
}
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
\subsubsection subsubsecViewToolsViewDtypes_regref Region Reference
|
|
A Region Reference is a reference to a selection within a dataset. A selection can be either
|
|
individual elements or a hyperslab. In <code style="background-color:whitesmoke;">h5dump</code> you will see the name of the dataset along with
|
|
the elements or slab that is selected. A dataset with a Region Reference datatype consists of
|
|
one or more Region References.
|
|
|
|
An example of a Region Reference dataset (<code style="background-color:whitesmoke;">h5ex_t_regref.h5</code>) can be found on the
|
|
\ref ExAPI page,
|
|
under Datatypes. If you examine this dataset with <code style="background-color:whitesmoke;">h5dump</code> you will see that <code style="background-color:whitesmoke;">/DS1</code> is a
|
|
Region Reference dataset as indicated by its datatype, highlighted in bold below:
|
|
\code
|
|
$ h5dump h5ex_t_regref.h5
|
|
HDF5 "h5ex_t_regref.h5" {
|
|
GROUP "/" {
|
|
DATASET "DS1" {
|
|
DATATYPE H5T_REFERENCE { H5T_STD_REF_DSETREG }
|
|
DATASPACE SIMPLE { ( 2 ) / ( 2 ) }
|
|
DATA {
|
|
DATASET /DS2 {(0,1), (2,11), (1,0), (2,4)},
|
|
DATASET /DS2 {(0,0)-(0,2), (0,11)-(0,13), (2,0)-(2,2), (2,11)-(2,13)}
|
|
}
|
|
}
|
|
DATASET "DS2" {
|
|
DATATYPE H5T_STD_I8LE
|
|
DATASPACE SIMPLE { ( 3, 16 ) / ( 3, 16 ) }
|
|
DATA {
|
|
(0,0): 84, 104, 101, 32, 113, 117, 105, 99, 107, 32, 98, 114, 111, 119,
|
|
(0,14): 110, 0,
|
|
(1,0): 102, 111, 120, 32, 106, 117, 109, 112, 115, 32, 111, 118, 101,
|
|
(1,13): 114, 32, 0,
|
|
(2,0): 116, 104, 101, 32, 53, 32, 108, 97, 122, 121, 32, 100, 111, 103,
|
|
(2,14): 115, 0
|
|
}
|
|
}
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
It contains two Region References:
|
|
\li A selection of four individual elements in dataset <code style="background-color:whitesmoke;">/DS2 : (0,1), (2,11), (1,0), (2,4)</code>
|
|
See the #H5Sselect_elements API in the \ref UG for information on selecting individual elements.
|
|
\li A selection of these blocks in dataset <code style="background-color:whitesmoke;">/DS2 : (0,0)-(0,2), (0,11)-(0,13), (2,0)-(2,2), (2,11)-(2,13)</code>
|
|
See the #H5Sselect_hyperslab API in the \ref UG for how to do hyperslab selection.
|
|
|
|
|
|
If you look at the code that creates the dataset (<code style="background-color:whitesmoke;">h5ex_t_regref.c</code>) you will see that the
|
|
first reference is created with these calls:
|
|
\code
|
|
status = H5Sselect_elements (space, H5S_SELECT_SET, 4, coords[0]);
|
|
status = H5Rcreate (&wdata[0], file, DATASET2, H5R_DATASET_REGION, space);
|
|
\endcode
|
|
|
|
where the buffer containing the coordinates to select is:
|
|
\code
|
|
coords[4][2] = { {0, 1},
|
|
{2, 11},
|
|
{1, 0},
|
|
{2, 4} },
|
|
\endcode
|
|
|
|
The second reference is created by calling,
|
|
\code
|
|
status = H5Sselect_hyperslab (space, H5S_SELECT_SET, start, stride, count, block);
|
|
status = H5Rcreate (&wdata[1], file, DATASET2, H5R_DATASET_REGION, space);
|
|
\endcode
|
|
where start, stride, count, and block have these values:
|
|
\code
|
|
start[2] = {0, 0},
|
|
stride[2] = {2, 11},
|
|
count[2] = {2, 2},
|
|
block[2] = {1, 3};
|
|
\endcode
|
|
|
|
These start, stride, count, and block values will select the elements shown in bold in the dataset:
|
|
\code
|
|
84 104 101 32 113 117 105 99 107 32 98 114 111 119 110 0
|
|
102 111 120 32 106 117 109 112 115 32 111 118 101 114 32 0
|
|
116 104 101 32 53 32 108 97 122 121 32 100 111 103 115 0
|
|
\endcode
|
|
|
|
If you use <code style="background-color:whitesmoke;">h5dump</code> to select a subset of dataset
|
|
<code style="background-color:whitesmoke;">/DS2</code> with these start, stride, count, and block values, you will see that the same elements are selected:
|
|
\code
|
|
$ h5dump -d "/DS2" -s "0,0" -S "2,11" -c "2,2" -k "1,3" h5ex_t_regref.h5
|
|
HDF5 "h5ex_t_regref.h5" {
|
|
DATASET "/DS2" {
|
|
DATATYPE H5T_STD_I8LE
|
|
DATASPACE SIMPLE { ( 3, 16 ) / ( 3, 16 ) }
|
|
SUBSET {
|
|
START ( 0, 0 );
|
|
STRIDE ( 2, 11 );
|
|
COUNT ( 2, 2 );
|
|
BLOCK ( 1, 3 );
|
|
DATA {
|
|
(0,0): 84, 104, 101, 114, 111, 119,
|
|
(2,0): 116, 104, 101, 100, 111, 103
|
|
}
|
|
}
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
For more information on selections, see the tutorial topic on
|
|
@ref LBDsetSubRW. Also see the
|
|
\ref secViewToolsViewSub tutorial topic on using <code style="background-color:whitesmoke;">h5dump</code> to view a subset.
|
|
|
|
\subsubsection subsubsecViewToolsViewDtypes_string String
|
|
There are two types of string data, fixed length strings and variable length strings.
|
|
|
|
Below is the <code style="background-color:whitesmoke;">h5dump</code> output for two files that have the same strings written to them. In one file,
|
|
the strings are fixed in length, and in the other, the strings have different sizes (and are variable in size).
|
|
|
|
<em>Dataset of Fixed Length Strings</em>
|
|
\code
|
|
HDF5 "h5ex_t_string.h5" {
|
|
GROUP "/" {
|
|
DATASET "DS1" {
|
|
DATATYPE H5T_STRING {
|
|
STRSIZE 7;
|
|
STRPAD H5T_STR_SPACEPAD;
|
|
CSET H5T_CSET_ASCII;
|
|
CTYPE H5T_C_S1;
|
|
}
|
|
DATASPACE SIMPLE { ( 4 ) / ( 4 ) }
|
|
DATA {
|
|
(0): "Parting", "is such", "sweet ", "sorrow."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
<em>Dataset of Variable Length Strings</em>
|
|
\code
|
|
HDF5 "h5ex_t_vlstring.h5" {
|
|
GROUP "/" {
|
|
DATASET "DS1" {
|
|
DATATYPE H5T_STRING {
|
|
STRSIZE H5T_VARIABLE;
|
|
STRPAD H5T_STR_SPACEPAD;
|
|
CSET H5T_CSET_ASCII;
|
|
CTYPE H5T_C_S1;
|
|
}
|
|
DATASPACE SIMPLE { ( 4 ) / ( 4 ) }
|
|
DATA {
|
|
(0): "Parting", "is such", "sweet", "sorrow."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
You might wonder which to use. Some comments to consider are included below.
|
|
\li In general, a variable length string dataset is more complex than a fixed length string. If you don't
|
|
specifically need a variable length type, then just use the fixed length string.
|
|
\li A variable length dataset consists of pointers to heaps in different locations in the file. For this
|
|
reason, a variable length dataset cannot be compressed. (Basically, the pointers get compressed and
|
|
not the actual data!) If compression is needed, then do not use variable length types.
|
|
\li If you need to create an array of of different length strings, you can either use fixed length strings
|
|
along with compression, or use a variable length string.
|
|
|
|
<hr>
|
|
Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand
|
|
|
|
*/
|