The H5D_READ function reads the data within a dataset, converting from the HDF5 file datatype into the HDF5 memory datatype, and finally into the corresponding IDL datatype.
Syntax
Result = H5D_READ(Dataset_id [, Datatype_id] [, FILE_SPACE=id] [, MEMORY_SPACE=id] )
Return Value
Returns an IDL variable containing the specified data. The different return types and storage mechanisms are described below.
Note: The dimensions for the Result variable are constructed using the following precedence rules:
If MEMORY_SPACE is specified, then the dimensions of the MEMORY_SPACE are used.
If only FILE_SPACE is specified, then the dimensions of the FILE_SPACE are used.
If neither MEMORY_SPACE nor FILE_SPACE are specified, then the dimensions are taken from the Dataset_id.
Arguments
Dataset_id
A long integer containing the identifier of the dataset to read.
Datatype_id
A long integer containing the identifier of the memory datatype to read. This argument is used only when reading part of a compound dataset. If Datatype_id is not supplied, the entire dataset is read.
Keywords
FILE_SPACE
Set this keyword to the file dataspace identifier that should be used when reading the dataset. The FILE_SPACE keyword may be used to define hyperslabs or elements for subselection within the dataset. The default is zero (in HDF5 this is equivalent to H5S_ALL), which indicates that the entire dataspace should be read.
MEMORY_SPACE
Set this keyword to the memory dataspace identifier that should be used when copying the data from the file into memory. The MEMORY_SPACE keyword may be used to define hyperslabs or elements in which to place the data. The default is zero (in HDF5 this is equivalent to H5S_ALL), which indicates that the memory dataspace is identical to the file dataspace.
Return Type
When reading in HDF5 datasets, the datatype is first set to the native HDF5 type. This native type is then converted to an IDL type as shown in the following table:
HDF5 Class |
HDF5 Datatype |
IDL Type |
H5T_INTEGER
H5T_BITFIELD
H5T_ENUM |
H5T_NATIVE_UINT8
|
Byte |
H5T_NATIVE_INT8 |
Byte |
H5T_NATIVE_INT16
|
Integer |
H5T_NATIVE_UINT16
|
Unsigned integer
|
H5T_NATIVE_INT32
|
Long integer |
H5T_NATIVE_UINT32
|
Unsigned long integer
|
H5T_NATIVE_INT64
|
64-bit integer |
H5T_NATIVE_UINT64
|
Unsigned 64-bit integer
|
H5T_REFERENCE |
H5T_STD_REF_OBJ |
Unsigned 64-bit integer
|
H5T_REF_DSETREG |
Structure |
H5T_FLOAT |
H5T_NATIVE_FLOAT
|
Floating point |
H5T_NATIVE_DOUBLE
|
Double-precision floating
|
H5T_STRING |
H5T_C_S1 |
String |
H5T_TIME |
H5T_C_S1 |
String |
H5T_COMPOUND |
(Member datatypes)
|
Structure |
H5T_ARRAY |
(Super datatype)
|
(Super type) |
Note: IDL does not have a signed 8-bit integer type. For the H5T_NATIVE_INT8 datatype, the values are returned as unsigned bytes. In this case, data values from 0-127 are returned unchanged, while data values from -128 to -1 are wrapped into the range 128-255. To convert an array of byte values into signed (16-bit) integers, the following code snippet may be used:
bytedata = H5D_READ(id)
intdata = FIX(bytedata) - 256*(bytedata ge 128)
Note: Multidimensional datasets are returned in IDL column-major order, with the fastest-varying dimensions listed first. HDF5 uses C row-major order, with the fastest-varying dimensions listed last. In both cases, the memory layout for data elements is identical (i.e., no transpose is needed), and only the order of the dimensions is reversed.
Note: For the H5T_ARRAY datatype, the array dimensions are concatenated with the dataset dimensions, with the array dimensions varying more rapidly.
Note: Structure tag names are constructed from H5T_COMPOUND member names by switching to uppercase and converting all non-alphanumeric characters to underscores.
Version History
5.6 |
Introduced |
6.2 |
Added H5T_STD_REF_DSETREG Datatype (structure IDL type) to the H5T_REFERENCE class
|
6.3 |
Added the Datatype_id argument
|
See Also
H5D_CLOSE, H5D_OPEN, H5D_WRITE, H5S_CREATE_SIMPLE, H5S_SELECT_ELEMENTS, H5S_SELECT_HYPERSLAB