[svn-r1736] HDF5 Tutorial: First version of Tutorial to be checked in for distribution.
This commit is contained in:
Frank Baker
452
doc/html/Tutor/select.html
Normal file
452
doc/html/Tutor/select.html
Normal file
@@ -0,0 +1,452 @@
|
||||
<HTML><HEAD>
|
||||
<TITLE>HDF5 Tutorial - Selections using H5Sselect_hyperslab
|
||||
</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">Selections using H5Sselect_hyperslab</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/read from with the function
|
||||
H5Sselect_hyperslab.
|
||||
<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 sds.h5. 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>
|
||||
<TABLE BORDER CELLSPACING=1 CELLPADDING=7 WIDTH=172>
|
||||
<TR><TD WIDTH="17%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="17%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="17%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="17%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="17%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="17%" VALIGN="TOP"> </TD>
|
||||
</TR>
|
||||
<TR><TD WIDTH="17%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="17%" VALIGN="TOP"> </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"> </TD>
|
||||
<TD WIDTH="17%" VALIGN="TOP"> </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"> </TD>
|
||||
<TD WIDTH="17%" VALIGN="TOP"> </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"> </TD>
|
||||
<TD WIDTH="17%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="17%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="17%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="17%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="17%" VALIGN="TOP"> </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"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
</TR>
|
||||
<TR><TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
</TR>
|
||||
<TR><TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </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"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </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"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </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"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
</TR>
|
||||
<TR><TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
<TD WIDTH="14%" VALIGN="TOP"> </TD>
|
||||
</TR>
|
||||
</TABLE>
|
||||
<P>
|
||||
[ <A HREF="examples/h5_hyperslab.c">Download h5_hyperslab.c</A> ]
|
||||
<PRE>
|
||||
|
||||
/************************************************************
|
||||
|
||||
This example shows how to write and read a hyperslab. It
|
||||
is derived from the h5_read.c and h5_write.c examples in
|
||||
the "Introduction to HDF5".
|
||||
|
||||
************************************************************/
|
||||
|
||||
#include "hdf5.h"
|
||||
|
||||
#define FILE "sds.h5"
|
||||
#define DATASETNAME "IntArray"
|
||||
#define NX_SUB 3 /* hyperslab dimensions */
|
||||
#define NY_SUB 4
|
||||
#define NX 7 /* output buffer dimensions */
|
||||
#define NY 7
|
||||
#define NZ 3
|
||||
#define RANK 2
|
||||
#define RANK_OUT 3
|
||||
|
||||
#define X 5 /* dataset dimensions */
|
||||
#define Y 6
|
||||
|
||||
int
|
||||
main (void)
|
||||
{
|
||||
hsize_t dimsf[2]; /* dataset dimensions */
|
||||
int data[X][Y]; /* data to write */
|
||||
|
||||
/*
|
||||
* Data and output buffer initialization.
|
||||
*/
|
||||
hid_t file, dataset; /* handles */
|
||||
hid_t dataspace;
|
||||
hid_t memspace;
|
||||
hsize_t dimsm[3]; /* memory space dimensions */
|
||||
hsize_t dims_out[2]; /* dataset dimensions */
|
||||
herr_t status;
|
||||
|
||||
int data_out[NX][NY][NZ ]; /* output buffer */
|
||||
|
||||
hsize_t count[2]; /* size of the hyperslab in the file */
|
||||
hssize_t offset[2]; /* hyperslab offset in the file */
|
||||
hsize_t count_out[3]; /* size of the hyperslab in memory */
|
||||
hssize_t offset_out[3]; /* hyperslab offset in memory */
|
||||
int i, j, k, status_n, rank;
|
||||
|
||||
|
||||
|
||||
/*********************************************************
|
||||
This writes data to the HDF5 file.
|
||||
*********************************************************/
|
||||
|
||||
/*
|
||||
* Data and output buffer initialization.
|
||||
*/
|
||||
for (j = 0; j < X; j++) {
|
||||
for (i = 0; i < Y; i++)
|
||||
data[j][i] = i + j;
|
||||
}
|
||||
/*
|
||||
* 0 1 2 3 4 5
|
||||
* 1 2 3 4 5 6
|
||||
* 2 3 4 5 6 7
|
||||
* 3 4 5 6 7 8
|
||||
* 4 5 6 7 8 9
|
||||
*/
|
||||
|
||||
/*
|
||||
* Create a new file using H5F_ACC_TRUNC access,
|
||||
* the default file creation properties, and the default file
|
||||
* access properties.
|
||||
*/
|
||||
file = H5Fcreate (FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
|
||||
|
||||
/*
|
||||
* Describe the size of the array and create the data space for fixed
|
||||
* size dataset.
|
||||
*/
|
||||
dimsf[0] = X;
|
||||
dimsf[1] = Y;
|
||||
dataspace = H5Screate_simple (RANK, dimsf, NULL);
|
||||
|
||||
/*
|
||||
* Create a new dataset within the file using defined dataspace and
|
||||
* default dataset creation properties.
|
||||
*/
|
||||
dataset = H5Dcreate (file, DATASETNAME, H5T_STD_I32BE, dataspace,
|
||||
H5P_DEFAULT);
|
||||
|
||||
/*
|
||||
* Write the data to the dataset using default transfer properties.
|
||||
*/
|
||||
status = H5Dwrite (dataset, H5T_NATIVE_INT, H5S_ALL, H5S_ALL,
|
||||
H5P_DEFAULT, data);
|
||||
|
||||
/*
|
||||
* Close/release resources.
|
||||
*/
|
||||
H5Sclose (dataspace);
|
||||
H5Dclose (dataset);
|
||||
H5Fclose (file);
|
||||
|
||||
|
||||
/*************************************************************
|
||||
|
||||
This reads the hyperslab from the sds.h5 file just
|
||||
created, into a 2-dimensional plane of the 3-dimensional
|
||||
array.
|
||||
|
||||
************************************************************/
|
||||
|
||||
for (j = 0; j < NX; j++) {
|
||||
for (i = 0; i < NY; i++) {
|
||||
for (k = 0; k < NZ ; k++)
|
||||
data_out[j][i][k] = 0;
|
||||
}
|
||||
}
|
||||
|
||||
/*
|
||||
* Open the file and the dataset.
|
||||
*/
|
||||
file = H5Fopen (FILE, H5F_ACC_RDONLY, H5P_DEFAULT);
|
||||
dataset = H5Dopen (file, DATASETNAME);
|
||||
|
||||
dataspace = H5Dget_space (dataset); /* dataspace handle */
|
||||
rank = H5Sget_simple_extent_ndims (dataspace);
|
||||
status_n = H5Sget_simple_extent_dims (dataspace, dims_out, NULL);
|
||||
printf("\nRank: %d\nDimensions: %lu x %lu \n", rank,
|
||||
(unsigned long)(dims_out[0]), (unsigned long)(dims_out[1]));
|
||||
|
||||
/*
|
||||
* Define hyperslab in the dataset.
|
||||
*/
|
||||
offset[0] = 1;
|
||||
offset[1] = 2;
|
||||
count[0] = NX_SUB;
|
||||
count[1] = NY_SUB;
|
||||
status = H5Sselect_hyperslab (dataspace, H5S_SELECT_SET, offset, NULL,
|
||||
count, NULL);
|
||||
|
||||
/*
|
||||
* Define the memory dataspace.
|
||||
*/
|
||||
dimsm[0] = NX;
|
||||
dimsm[1] = NY;
|
||||
dimsm[2] = NZ;
|
||||
memspace = H5Screate_simple (RANK_OUT, dimsm, NULL);
|
||||
|
||||
/*
|
||||
* Define memory hyperslab.
|
||||
*/
|
||||
offset_out[0] = 3;
|
||||
offset_out[1] = 0;
|
||||
offset_out[2] = 0;
|
||||
count_out[0] = NX_SUB;
|
||||
count_out[1] = NY_SUB;
|
||||
count_out[2] = 1;
|
||||
status = H5Sselect_hyperslab (memspace, H5S_SELECT_SET, offset_out, NULL,
|
||||
count_out, NULL);
|
||||
|
||||
/*
|
||||
* Read data from hyperslab in the file into the hyperslab in
|
||||
* memory and display.
|
||||
*/
|
||||
status = H5Dread (dataset, H5T_NATIVE_INT, memspace, dataspace,
|
||||
H5P_DEFAULT, data_out);
|
||||
printf ("Data:\n ");
|
||||
for (j = 0; j < NX; j++) {
|
||||
for (i = 0; i < NY; i++) printf("%d ", data_out[j][i][0]);
|
||||
printf("\n ");
|
||||
}
|
||||
printf("\n");
|
||||
/*
|
||||
* 0 0 0 0 0 0 0
|
||||
* 0 0 0 0 0 0 0
|
||||
* 0 0 0 0 0 0 0
|
||||
* 3 4 5 6 0 0 0
|
||||
* 4 5 6 7 0 0 0
|
||||
* 5 6 7 8 0 0 0
|
||||
* 0 0 0 0 0 0 0
|
||||
*/
|
||||
|
||||
/*
|
||||
* Close and release resources.
|
||||
*/
|
||||
H5Dclose (dataset);
|
||||
H5Sclose (dataspace);
|
||||
H5Sclose (memspace);
|
||||
H5Fclose (file);
|
||||
|
||||
}
|
||||
</PRE>
|
||||
<A NAME="rem">
|
||||
<H3><U>Remarks</U></H3>
|
||||
<UL>
|
||||
<LI>H5Sselect_hyperslab selects a hyperslab region to add to the current
|
||||
selected region for a specified dataspace.
|
||||
<PRE>
|
||||
herr_t H5Sselect_hyperslab (hid_t space_id, H5S_seloper_t op,
|
||||
const hssize_t *start, const hsize_t *stride,
|
||||
const hsize_t *count, const hsize_t *block )
|
||||
</PRE>
|
||||
<UL>
|
||||
<LI>The first parameter, <I>space_id</I>, is the dataspace identifier for the
|
||||
specified dataspace.
|
||||
<LI>The second parameter, <I>op</I>, can only be set to H5S_SELECT_SET
|
||||
in the current release. It replaces the existing selection with the
|
||||
parameters from this call. Overlapping blocks are not supported.
|
||||
<LI>The <I>start</I> array determines the starting coordinates of the hyperslab to select.
|
||||
<LI>The <I>stride</I> array indicates which elements along a dimension are to
|
||||
be selected.
|
||||
<LI>The <I>count</I> array determines how many positions to select from the
|
||||
dataspace in each dimension.
|
||||
<LI>The <I>block</I> array determines the size of the element block selected
|
||||
by the dataspace.
|
||||
</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>This example introduces the following H5Dget_* functions:
|
||||
<UL>
|
||||
<B>H5Dget_space:</B> returns an identifier for a copy of the dataspace
|
||||
of a dataset.<BR>
|
||||
<B>H5Dget_type:</B> returns an identifier for a copy of the data type
|
||||
of a dataset.<BR>
|
||||
</UL>
|
||||
<P>
|
||||
<LI>This example introduces the following H5Sget_* functions used to
|
||||
obtain information about selections:
|
||||
<UL>
|
||||
<B>H5Sget_simple_extent_dims:</B> returns the size and maximum sizes
|
||||
of each dimension of a dataspace.<BR>
|
||||
<B>H5Sget_simple_extent_ndims:</B> determines the dimensionality
|
||||
(or rank) of a dataspace. <BR>
|
||||
</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> <H6>Last Modified: August 27, 1999</H6><BR>
|
||||
<!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu -->
|
||||
</FONT>
|
||||
<BR>
|
||||
<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> -->
|
||||
|
||||
</BODY>
|
||||
</HTML>
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user