Dataspace (H5S)

R2026b

Dimensionality of dataset

Description

Use the MATLAB^® HDF5 dataspace interface, H5S, to create and handle dataspaces, and access information about them.

An HDF5 dataspace defines the size and shape of the dataset or attribute raw data, and must be defined when the dataset or attribute is created.

Functions

H5S.close

Close dataspace

H5S.close(spaceID) releases and terminates access to the dataspace identifier spaceID.

H5S.copy

Create copy of dataspace

output = H5S.copy(spaceID) creates an identical copy of the dataspace identified by spaceID.

H5S.create

Create new dataspace

spaceID = H5S.create(spacetype) creates a new dataspace identifier of type spacetype.

Details

Input Arguments

spacetype — Datatype of dataspace. Specify spacetype as one of these values:

• "H5S_SCALAR"

• "H5S_SIMPLE"

• "H5S_NULL"

Output Arguments

• spaceID — Identifier of created dataspace.

H5S.create_simple

Create new simple dataspace

spaceID = H5S.create_simple(rank,dims,maxdims) creates a new simple dataspace and opens it for access.

Details

Input Arguments

• rank — Number of dimensions used in the dataspace.

• dims — Numeric array specifying the size of each dimension of the dataset.

• maxdims — Numeric array specifying the upper limit on the size of each dimension. You can also specify maxdims as "H5S_UNLIMITED" for an unlimited dimension.

Output Arguments

• spaceID — Identifier of created simple dataspace.

Note

The HDF5 library uses C-style ordering for multidimensional arrays, while MATLAB uses FORTRAN-style ordering. The dims and maxdims parameters assume C-style ordering. For more information, see Report Data Set Dimensions.

H5S.extent_copy

Copy extent from source to destination dataspace

H5S.extent_copy(destID,srcID) copies the extent from a source dataspace srcID to the destination dataspace destID.

H5S.get_regular_hyperslab

Retrieve a regular hyperslab selection

[start,stride,count,block] = H5S.get_regular_hyperslab(spaceID) retrieves a regular hyperslab selection.

Details

Input Arguments

• spaceID — Identifier of the dataspace.

Output Arguments

• start — Offset of the start of the regular hyperslab.

• stride — Stride of the regular hyperslab.

• count — Number of blocks in the regular hyperslab.

• block — Size of a block in the regular hyperslab.

Note

The HDF5 library uses C-style ordering for multidimensional arrays, while MATLAB uses FORTRAN-style ordering. The start, stride, count, and block parameters assume C-style ordering. For more information, see Report Data Set Dimensions.

H5S.get_select_bounds

Bounding box of dataspace selection

[start,finish] = H5S.get_select_bounds(spaceID) returns the coordinates of the bounding box containing the current selection.

Details

Input Arguments

• spaceID — Dataspace identifier.

Output Arguments

• start — Starting coordinates of the bounding box.

• finish — Coordinates of the diagonally opposite corner.

Note

The HDF5 library uses C-style ordering for multidimensional arrays, while MATLAB uses FORTRAN-style ordering. The start and finish parameters assume C-style ordering. For more information, see Report Data Set Dimensions.

H5S.get_select_elem_npoints

Number of element points in selection

numpoints = H5S.get_select_elem_npoints(spaceID) returns the number of element points in the current dataspace selection.

H5S.get_select_elem_pointlist

Element points in dataspace selection

points = H5S.get_select_elem_pointlist(spaceID,start,numpoints) returns the list of element points in the current dataspace selection.

Details

Input Arguments

• spaceID — Dataspace identifier.

• start — Starting element point.

• numpoints — Two-dimensional array of 0-based values specifying the coordinates of the elements. If m is the rank of the dataspace, then points will have size [m × numpoints].

Note

The ordering of the coordinate points is the same as the HDF5 library C API.

H5S.get_select_hyper_blocklist

List of hyperslab blocks

blocklist = H5S.get_select_hyper_blocklist(spaceID,start,numblocks) returns a list of the hyperslab blocks currently selected.

Details

Input Arguments

• spaceID — Dataspace identifier.

• start — Starting hyperslab block.

• numblocks — Number of hyperslabs to return.

Note

The HDF5 library uses C-style ordering for multidimensional arrays, while MATLAB uses FORTRAN-style ordering. The start and numblocks parameters assume C-style ordering. For more information, see Report Data Set Dimensions.

H5S.get_select_hyper_nblocks

Number of hyperslab blocks

numblocks = H5S.get_select_hyper_nblocks(spaceID) returns the number of hyperslab blocks in the current dataspace selection.

H5S.get_select_npoints

Number of elements in dataspace selection

numpoints = H5S.get_select_npoints(spaceID) returns the number of elements in the current dataspace selection.

H5S.get_select_type

Type of dataspace selection

selection = H5S.get_select_type(spaceID) returns the selection type.

Details

Output Arguments

• selection — Selection type, interpreted as one of these:

  • "H5S_SEL_NONE" — No selection is defined. The numeric equivalent is 0.

  • "H5S_SEL_POINTS" — A sequence of points is selected. The numeric equivalent is 1.

  • "H5S_SEL_HYPERSLABS" — A hyperslab or compound hyperslab is selected. The numeric equivalent is 2.

  • "H5S_SEL_ALL" — The entire dataset is selected. The numeric equivalent is 3.

H5S.get_simple_extent_dims

Dataspace size and maximum size

[numdims,dimsize,maxdims] = H5S.get_simple_extent_dims(spaceID) returns the number of dimensions in the dataspace, the size of each dimension, and the maximum size of each dimension.

Details

Note

The HDF5 library uses C-style ordering for multidimensional arrays, while MATLAB uses FORTRAN-style ordering. The dimsize and maxdims assume C-style ordering. For more information, see Report Data Set Dimensions.

H5S.get_simple_extent_ndims

Dataspace rank

output = H5S.get_simple_extent_ndims(spaceID) returns the dimensionality, also known as the rank, of a dataspace.

H5S.get_simple_extent_npoints

Number of elements in dataspace

output = H5S.get_simple_extent_npoints(spaceID) returns the number of elements in the dataspace specified by spaceID.

H5S.get_simple_extent_type

Dataspace class

spacetype = H5S.get_simple_extent_type(spaceID) returns the class of the dataspace specified by spaceID.

H5S.is_regular_hyperslab

Determine whether a hyperslab selection is regular

output = H5S.is_regular_hyperslab(spaceID) returns a positive value if the hyperslab selection associated with spaceID is regular, and 0 if it is not.

H5S.is_simple

Determine if dataspace is simple

output = H5S.is_simple(spaceID) returns a positive value if the dataspace specified by spaceID is a simple dataspace, and 0 if it is not.

H5S.offset_simple

Set offset of simple dataspace

H5S.offset_simple(spaceID,offset) specifies the offset of the simple dataspace specified by spaceID. This function allows the same shaped selection to be moved to different locations within a dataspace without requiring it to be redefined.

Details

Note

The HDF5 library uses C-style ordering for multidimensional arrays, while MATLAB uses FORTRAN-style ordering. The offset parameter assumes C-style ordering. For more information, see Report Data Set Dimensions.

H5S.select_all

Select entire extent of dataspace

H5S.select_all(spaceID) selects the entire extent of the dataspace specified by spaceID.

H5S.select_elements

Specify coordinates to include in selection

H5S.select_elements(spaceID,op,coord) selects array elements to include in the selection for the dataspace specified by spaceID.

Details

Input Arguments

• spaceID — Dataspace identifier.

• op — Flag that determines how the new selection is to be combined with the previously existing selection for the dataspace. Specify op as one of these values:

  • "H5S_SELECT_SET"

  • "H5S_SELECT_APPEND"

  • "H5S_SELECT_PREPEND"

• coord — Array array of 0-based values specifying the coordinates of elements to be selected. If M is the rank of the dataspace and if N is the number of points, then coord should be an M-by-N array.

Note

The HDF5 library uses C-style ordering for multidimensional arrays, while MATLAB uses FORTRAN-style ordering. The coord parameter assumes coordinates have C-style ordering. For more information, see Report Data Set Dimensions.

H5S.select_hyperslab

Select hyperslab region

H5S.select_hyperslab(spaceID,op,start,stride,count,block) selects a hyperslab region to add to the current selected region for the dataspace specified by spaceID.

Details

Input Arguments

• spaceID — Dataspace identifier.

• op — Flag that determines how the new selection is to be combined with the previously existing selection for the dataspace. Specify op as one of these values:

  • "H5S_SELECT_SET"

  • "H5S_SELECT_OR"

  • "H5S_SELECT_AND"

  • "H5S_SELECT_XOR"

  • "H5S_SELECT_NOTA"

  • "H5S_SELECT_NOTB"

• start — Starting coordinates of the hyperslab to select.

• stride — Number of elements to move in each dimension. If you specify stride as [], then H5S.select_hyperslab selects a contiguous hyperslab.

• count — Number of blocks to select from the dataspace in each dimension. If you specify count as [], then H5S.select_hyperslab selects one block along each dimension.

• block — Size of the element block selected from the dataspace. If you specify block as [], then H5S.select_hyperslab sets the block size to a single element in each dimension.

Note

The HDF5 library uses C-style ordering for multidimensional arrays, while MATLAB uses FORTRAN-style ordering. The start, stride, count, and block parameters assume C-style ordering. For more information, see Report Data Set Dimensions.

H5S.select_none

Reset selection region to include no elements

H5S.select_none(spaceID) resets the selection region for the dataspace spaceID to include no elements.

H5S.select_valid

Determine validity of selection

tf = H5S.select_valid(spaceID) returns a positive value if the selection of the dataspace specified by spaceID is within the extent of that dataspace, and 0 if it is not. A negative return value indicates a failure.

H5S.set_extent_none

Remove extent from dataspace

H5S.set_extent_none(spaceID) removes the extent from a dataspace and sets the type to H5S_NO_CLASS.

H5S.set_extent_simple

Set size of dataspace

H5S.set_extent_simple(spaceID,rank,dims,maxdims) sets the size of the dataspace identified by spaceID.

Details

Input Arguments

• spaceID — Dataspace identifier.

• rank — Number of dimensions used in the dataspace.

• dims — Numeric array specifying the size of each dimension of the dataset.

• maxdims — Numeric array specifying the upper limit on the size of each dimension. You can also specify maxdims as "H5S_UNLIMITED" for an unlimited dimension.

Note

The HDF5 library uses C-style ordering for multidimensional arrays, while MATLAB uses FORTRAN-style ordering. The dims and maxdims parameters assume C-style ordering. For more information, see Report Data Set Dimensions.

Examples

Information About Dimensions of Dataspace

Use the H5S.get_simple_extent_dims function to get information about the dimensions of the dataspace.

fid = H5F.open("example.h5");
dsID = H5D.open(fid,"/g2/dset2.2");
spaceID = H5D.get_space(dsID);
[ndims,h5_dims] = H5S.get_simple_extent_dims(spaceID);
matlab_dims = fliplr(h5_dims);
H5S.close(spaceID)
H5D.close(dsID)
H5F.close(fid)

Get Coordinates of Bounding Box

Select a hyperslab with the H5S.select_hyperslab function, and use the H5S.get_select_bounds function to get the coordinates of the selection within the dataspace identified by spaceID.

Create a new simple dataspace and select the hyperslab.

dims = [100 200];
h5_dims = fliplr(dims);
spaceID = H5S.create_simple(2,h5_dims,h5_dims);
start = fliplr([10 20]); block = fliplr([20 30]);
H5S.select_hyperslab(spaceID,"H5S_SELECT_SET",start,[],[],block);
offset = fliplr([3 5]);
H5S.offset_simple(spaceID,offset)

Query the bounding box of the current selection.

[start,finish] = H5S.get_select_bounds(spaceID);
start = fliplr(start);
finish = fliplr(finish);
H5S.close(spaceID)

Select Corner Points of Dataspace

Select the corner points of a dataspace. In this case, h5_coord should have size 2-by-4.

dims = [100 200];
h5_dims = fliplr(dims);
spaceID = H5S.create_simple(2,h5_dims,h5_dims);
coords = [0 0; 0 199; 99 0; 99 199];
h5_coords = fliplr(coords);
h5_coords = h5_coords';
H5S.select_elements(spaceID,"H5S_SELECT_SET",h5_coords)
H5S.close(spaceID)

Set Size of Dataspace

Use the H5S.set_extent_simple function to set the dimensions of the dataspace.

spaceID = H5S.create("H5S_SIMPLE");
dims = [100 200];
h5_dims = fliplr(dims);
maxdims = [100 H5ML.get_constant_value("H5S_UNLIMITED")];
h5_maxdims = fliplr(maxdims);
H5S.set_extent_simple(spaceID,2,h5_dims, h5_maxdims)
H5S.close(spaceID)

Version History

Introduced before R2006a

R2021b: Work with hyperslabs in Virtual Datasets (VDS)

You can use H5S.get_regular_hyperslab to retrieve a regular hyperslab selection and H5S.is_regular_hyperslab to determine whether a hyperslab selection is regular.