mirror/hdf5
2
0
Fork 0
mirror of https://github.com/HDFGroup/hdf5.git synced 2024-12-21 07:51:46 +08:00
Code Issues Packages Projects Releases Wiki Activity
1054efdaf8
hdf5/doxygen/dox/ViewTools.dox
Dana Robinson 265494b5b9
Remove "the the" from comments and docs (#2865)
2023-05-01 09:06:39 -07:00

1197 lines
40 KiB
Plaintext
Raw Blame History

/** @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/display/support/Download+HDF5">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 <a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> 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 <a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> 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
<a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> 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
<a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> 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
*/
Reference in New Issue View Git Blame Copy Permalink