mirror/hdf5
2
0
Fork 0
mirror of https://github.com/HDFGroup/hdf5.git synced 2024-11-21 01:04:10 +08:00
Code Issues Packages Projects Releases Wiki Activity
e5cf05cbef
hdf5/doc/html/Tutor/select.html
Barbara Jones 345e07fc11 [svn-r3563] Add changes to tutorial for Fortran 
Purpose:
    [is this a bug fix? feature? ...]
Description:
    [describe the bug, or describe the new feature, etc]
Solution:
    [details about the changes, algorithm, etc...]
    [Please as detail as you can since your own explanation is
    better than others guessing it from the code.]
Platforms tested:
    [machines you have tested the changed version.  This is absolute
    important.  Test it out on at least two or three different platforms
    such as Big-endian-32bit (SUN/IRIX), little-endian-32(LINUX) and
    64-bit (IRIX64/UNICOS/DEC-ALPHA) would be good.]
2001-03-08 11:47:44 -05:00

314 lines
9.7 KiB
HTML
Raw Blame History

<HTML><HEAD>
<TITLE>HDF5 Tutorial - Hyperslab Selections
</TITLE>
</HEAD>
<body bgcolor="#ffffff">
<!-- BEGIN MAIN BODY -->
<A HREF="http://www.ncsa.uiuc.edu/"><img border=0
src="http://www.ncsa.uiuc.edu/Images/NCSAhome/footerlogo.gif"
width=78 height=27 alt="NCSA"><P></A>
[ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ]
<H1>
<BIG><BIG><BIG><FONT COLOR="#c101cd">Hyperslab Selections</FONT>
</BIG></BIG></BIG></H1>
<hr noshade size=1>
<BODY>
<H2>Contents:</H2>
<UL>
<LI><A HREF="#def">Selecting a Portion of a Dataspace</A>
<LI>Programming Example
<UL>
<LI> <A HREF="#desc">Description</A>
<LI> <A HREF="#rem">Remarks</A>
<!--
<LI> <A HREF="#fc">File Contents</A>
-->
</UL>
</UL>
<HR>
<A NAME="def">
<H2>Selecting a Portion of a Dataspace</H2>
Hyperslabs are portions of datasets. A hyperslab selection can be a
logically contiguous collection of points in a dataspace, or it
can be a regular pattern of points or blocks in a dataspace.
You can select a hyperslab to write to or read from with the function
<CODE>H5Sselect_hyperslab</CODE> / <CODE>h5sselect_hyperslab_f</CODE>.
<P>
<H2> Programming Example</H2>
<A NAME="desc">
<H3><U>Description</U></H3>
This example creates a 5 x 6 integer array in a file called <code>sds.h5</code>
(<code>sdsf.h5</code> in FORTRAN). It
selects a 3 x 4 hyperslab from the dataset as follows (Dimension 0 is
offset by 1 and Dimension 1 is offset by 2):
<P>
<B>5 x 6 array:</B>
<TABLE BORDER CELLSPACING=1 CELLPADDING=7 WIDTH=172>
<TR><TD WIDTH="17%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="17%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="17%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="17%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="17%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="17%" VALIGN="TOP">&nbsp;</TD>
</TR>
<TR><TD WIDTH="17%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="17%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
</TR>
<TR><TD WIDTH="17%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="17%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
</TR>
<TR><TD WIDTH="17%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="17%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
</TR>
<TR><TD WIDTH="17%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="17%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="17%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="17%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="17%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="17%" VALIGN="TOP">&nbsp;</TD>
</TR>
</TABLE>
<P>
Then it reads the hyperslab from this file into a 2-dimensional plane
(size 7 x 7) of a 3-dimensional array (size 7 x 7 x 3), as
follows (with Dimension 0 offset by 3):
<P>
<TABLE BORDER CELLSPACING=1 CELLPADDING=7 WIDTH=201>
<TR><TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
</TR>
<TR><TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
</TR>
<TR><TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
</TR>
<TR><TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
</TR>
<TR><TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
</TR>
<TR><TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
</TR>
<TR><TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
<TD WIDTH="14%" VALIGN="TOP">&nbsp;</TD>
</TR>
</TABLE>
<P>
To obtain the example, download:
<UL>
[ <A HREF="examples/h5_hyperslab.c">C example</A> ]
- <code>h5_hyperslab.c</code><BR>
[ <A HREF="examples/hyperslab.f90">FORTRAN example</A> ]
- <code>hyperslab.f90</code><BR>
[ <A HREF="examples/java/HyperSlab.java">Java example</A> ]
- <code>HyperSlab.java</code>
</UL>
<B>NOTE:</B> To download a tar file of the examples, including a Makefile,
please go to the <A HREF="references.html">References</A> page.
<P>
<A NAME="rem">
<H3><U>Remarks</U></H3>
<UL>
<LI><CODE>H5Sselect_hyperslab</CODE> / <CODE>h5sselect_hyperslab_f</CODE>
selects a hyperslab region to
add to the current selected region for a specified dataspace.
<P>
<I><B>C</B></I>:
<pre>
herr_t H5Sselect_hyperslab (hid_t space_id, H5S_seloper_t operator,
const hssize_t *start, const hsize_t *stride,
const hsize_t *count, const hsize_t *block )
</pre>
<P>
<I><B>FORTRAN</B></I>:
<pre>
h5sselect_hyperslab_f (space_id, operator, start, count, &
hdferr, stride, block)
space_id IN: INTEGER(HID_T)
operator IN: INTEGER
start IN: INTEGER(HSSIZE_T), DIMENSION(*)
count IN: INTEGER(HSIZE_T), DIMENSION(*)
hdferr OUT: INTEGER
stride IN: INTEGER(HSIZE_T), DIMENSION(*), OPTIONAL
block IN: INTEGER(HSIZE_T), DIMENSION(*), OPTIONAL
</pre>
<P>
<UL>
<LI>The parameter <I>space_id</I> is the dataspace identifier for the
specified dataspace.
<P>
<LI>The parameter <I>operator</I> can be set to one of the following:
<dir><DL>
<dt><CODE>H5S_SELECT_SET</CODE> (<CODE>H5S_SELECT_SET_F</CODE> in FORTRAN)
<dd>Replace the existing selection with the parameters from this call.
Overlapping blocks are not supported with this operator.
<dt><CODE>H5S_SELECT_OR</CODE> (<CODE>H5S_SELECT_OR_F</CODE> in FORTRAN)
<dd>Add the new selection to the existing selection.
</DL></dir>
<P>
<LI>The <I>start</I> array determines the starting coordinates of the
hyperslab to select.
<P>
<LI>The <I>stride</I> array indicates which elements along a dimension are to
be selected.
<P>
<LI>The <I>count</I> array determines how many positions to select from the
dataspace in each dimension.
<P>
<LI>The <I>block</I> array determines the size of the element block selected
by the dataspace.
<P>
<LI>In C, a non-negative value is returned if successful, and a negative
value otherwise. In FORTRAN, the return value is returned in <I>hdferr</I>:
0 if successful and -1 otherwise.
</UL>
<P>
The <I>start</I>, <I>stride</I>, <I>count</I>, and <I>block</I> arrays must
be the same size as the rank of the dataspace.
<P>
<LI>The examples introduce the following call:
<dir><dl>
<dt><code>H5Dget_space / h5dget_space_f:</code>
<dd>Returns an identifier for a copy of the dataspace of a dataset.<P>
</dl></dir>
<LI>The C example also introduces the following calls:
<dir><dl>
<dt><code>H5Sget_simple_extent_dims:</code>
<dd>Returns the size and maximum size of each dimension of a dataspace.
<dt><code>H5Sget_simple_extent_ndims:</code>
<dd>Determines the dimensionality (or rank) of a dataspace.
</dl></dir>
<P>
The FORTRAN example does not use these calls, though they
are available as <CODE>h5sget_simple_extent_dims_f</CODE> and
<CODE>h5sget_simple_extent_ndims_f</CODE>.
</UL>
</UL>
</UL>
</PRE>
<P>
<!--
<A NAME="fc">
<H3><U>File Contents</U></H3>
-->
<!-- BEGIN FOOTER INFO -->
<P><hr noshade size=1>
<font face="arial,helvetica" size="-1">
<a href="http://www.ncsa.uiuc.edu/"><img border=0
src="http://www.ncsa.uiuc.edu/Images/NCSAhome/footerlogo.gif"
width=78 height=27 alt="NCSA"><br>
The National Center for Supercomputing Applications</A><br>
<a href="http://www.uiuc.edu/">University of Illinois
at Urbana-Champaign</a><br>
<br>
<!-- <A HREF="helpdesk.mail.html"> -->
<A HREF="mailto:hdfhelp@ncsa.uiuc.edu">
hdfhelp@ncsa.uiuc.edu</A>
<br>
Describes HDF5 Release 1.2.2, June 2000
<BR> <H6>Last Modified: April 5, 2000</H6><BR>
<!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu -->
<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu -->
</FONT>
<BR>
<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> -->
</BODY>
</HTML>
Reference in New Issue View Git Blame Copy Permalink