Package nz.org.riskscape.hdf5

Class H5DataSpace

java.lang.Object

nz.org.riskscape.hdf5.H5Object

nz.org.riskscape.hdf5.H5DataSpace

All Implemented Interfaces:

AutoCloseable

public class H5DataSpace
extends H5Object

A dataspace is a handle used to either read from or to a dataset. In the 'read from' case, the dataspace is a read-view into a H5Dataset. The same H5Dataset can support multiple dataspaces reading from it at once. Because the H5Dataspace selects specific elements from the dataset to read, multi-threaded read access should use a separate H5Dataspace for each thread (otherwise one thread can override the elements selected by another thread).

In the 'read to' case, the H5DataSpace represents a 'memory space'. It's a HDF5 handle that describes how many elements you intend to read.

There is no support yet for reading datasets that are comprised of multiple chunks (i.e. non-contiguous datasets).

Field Summary

Fields inherited from class nz.org.riskscape.hdf5.H5Object

ptr

Constructor Summary

Constructors

Constructor	Description
H5DataSpace(long id, H5Dataset dataset)
H5DataSpace(long id, H5Dataset parentDataset, long[] dims)

Method Summary

Modifier and Type	Method	Description
void	close()
static H5DataSpace	createMemSpace(long numElements)	Returns a memory space suitable to use for reading the numElements specified from a one-dimensional dataset.
static H5DataSpace	createMemSpace(long[] dims)	Creates a dataspace handle suitable to use as a 'memory space' in other HDF5 library calls.
long[]	getExtent()
int	numDimensions()
long	numElements()
int	numElementsAsInt()	Same as numElements() but should only be used when you're certain that the number of elements in the dataset will not overflow an integer value.
ByteBuffer	readElements(long[] start, long[] count)	Reads the specified elements from a dataset.
ByteBuffer	readElements(long start, long count)	Reads the specified elements from a one-dimensional dataset.
void	selectElements(long[] start, long[] count)	Selects a hyperslab of elements within the dataspace, using the starting position and number of elements specified.
void	selectElementsAt(long[][] locations)	Select specific elements from arbitrary locations from the dataset by specifying them as points within the n dimensional dataset.

Methods inherited from class nz.org.riskscape.hdf5.H5Object

getPointer

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

H5DataSpace

public H5DataSpace(long id,
 H5Dataset dataset)

H5DataSpace

public H5DataSpace(long id,
 H5Dataset parentDataset,
 long[] dims)

Method Details

createMemSpace

public static H5DataSpace createMemSpace(long[] dims)

Creates a dataspace handle suitable to use as a 'memory space' in other HDF5 library calls. In HDF5 library terms, a memory-space handle is much the same as a data-space handle. For memory-spaces we just use a 'simple' dataspace that's big enough to hold the elements we're interested in. Whereas for file-based dataspaces (what we read from), we use H5Dataset.newDataSpace() to get a handle that relates to the underlying file-based dataset. See also H5.H5Screate_simple(int, long[], long[]) method.

Parameters:

dims - an array of the dimensions, where the nth index gives the size of the nth dimension. To create a 1d memory space that can hold two elements, call createSimple(new long[] {2}). To create a 10x10 dataspace, call createSimple(new long[] {10, 10})

Returns:

a reference to the dataspace - it is your responsibility to close it when you're done

createMemSpace

public static H5DataSpace createMemSpace(long numElements)

Returns a memory space suitable to use for reading the numElements specified from a one-dimensional dataset. Refer {@link #createMemSpace(long[]).</p>

Returns:

an H5DataSpace - it is your responsibility to close it when you're done

numElements

public long numElements()

Returns:

the total number of elements in the dataset, by totalling up the extent (fixed size) for each of the dataset's dimensions

numElementsAsInt

public int numElementsAsInt()

Same as numElements() but should only be used when you're certain that the number of elements in the dataset will not overflow an integer value.

selectElements

public void selectElements(long[] start,
 long[] count)

Selects a hyperslab of elements within the dataspace, using the starting position and number of elements specified.

Clears any previous selection

selectElementsAt

public void selectElementsAt(long[][] locations)

Select specific elements from arbitrary locations from the dataset by specifying them as points within the n dimensional dataset. If the dataset is a 1d list, then you can select the 0th, 5th and 1st elements with selectElementsAt(new long[] {{0}, {5}, {1}}). If the dataset is a 10x10x10 cube, then you could select some of the corners with selectElementsAt(new long[][] {{0, 0, 0}, {0, 9, 0}, {9, 9 9}})

Clears any previous selection

Parameters:

locations - a list of coordinates to select

readElements

public ByteBuffer readElements(long start,
 long count)

Reads the specified elements from a one-dimensional dataset.

Parameters:

start - the index of the first element to read

count - the number of elements to read

Returns:

a ByteBuffer containing the data read

readElements

public ByteBuffer readElements(long[] start,
 long[] count)

Reads the specified elements from a dataset.

For example given a two dimensional datasetreadElements(new long[] {2, 4}, new long[] {10, 1}) would return 10 items made up of the the fifth item on the second dimension, for the 3rd - 13th items on the primary dimension.

Parameters:

start - the index of the first element to read for each dimension

count - the number of elements to read for each dimension

Returns:

a ByteBuffer containing the data read

numDimensions

public int numDimensions()

close

public void close()

Specified by:

close in interface AutoCloseable

Specified by:

close in class H5Object

getExtent

public long[] getExtent()