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()