org.janelia.saalfeldlab.n5.hdf5

Class N5HDF5Reader

java.lang.Object

org.janelia.saalfeldlab.n5.hdf5.N5HDF5Reader

All Implemented Interfaces:

Closeable, AutoCloseable, org.janelia.saalfeldlab.n5.GsonN5Reader, org.janelia.saalfeldlab.n5.N5Reader

Direct Known Subclasses:

N5HDF5Writer

public class N5HDF5Reader
extends Object
implements org.janelia.saalfeldlab.n5.GsonN5Reader, Closeable

Best effort N5Reader implementation for HDF5 files.

Attributes are not generally read as JSON but use HDF5 types. That means that HDF5 files that were not generated with this library can be used properly and correctly. Structured attributes for which no appropriate HDF5 attribute type exists are parsed as JSON strings.

Author:

Stephan Saalfeld, Philipp Hanslovsky

Nested Class Summary

Nested classes/interfaces inherited from interface org.janelia.saalfeldlab.n5.N5Reader

org.janelia.saalfeldlab.n5.N5Reader.Version

Field Summary

Fields

Modifier and Type	Field and Description
protected int[]	defaultBlockSize
protected static org.janelia.saalfeldlab.n5.FileSystemKeyValueAccess	FILE_SYSTEM_KEY_VALUE_ACCESS
protected com.google.gson.Gson	gson
protected static String	N5_JSON_ROOT_KEY
protected org.janelia.saalfeldlab.n5.hdf5.N5HDF5Util.OpenDataSetCache	openDataSetCache
protected boolean	overrideBlockSize
protected ch.systemsx.cisd.hdf5.IHDF5Reader	reader
static org.janelia.saalfeldlab.n5.N5Reader.Version	VERSION SemVer version of this N5-HDF5 spec.

Fields inherited from interface org.janelia.saalfeldlab.n5.N5Reader

NO_VERSION, VERSION_KEY

Constructor Summary

Constructors

Constructor and Description
N5HDF5Reader(ch.systemsx.cisd.hdf5.IHDF5Reader reader, boolean overrideBlockSize, com.google.gson.GsonBuilder gsonBuilder, int... defaultBlockSize) Opens an N5HDF5Reader for a given HDF5 file.
N5HDF5Reader(ch.systemsx.cisd.hdf5.IHDF5Reader reader, boolean overrideBlockSize, int... defaultBlockSize) Opens an N5HDF5Reader for a given HDF5 file.
N5HDF5Reader(ch.systemsx.cisd.hdf5.IHDF5Reader reader, int... defaultBlockSize) Opens an N5HDF5Reader for a given HDF5 file.
N5HDF5Reader(String hdf5Path, boolean overrideBlockSize, com.google.gson.GsonBuilder gsonBuilder, int... defaultBlockSize) Opens an N5HDF5Reader for a given HDF5 file.
N5HDF5Reader(String hdf5Path, boolean overrideBlockSize, int... defaultBlockSize) Opens an N5HDF5Reader for a given HDF5 file.
N5HDF5Reader(String hdf5Path, int... defaultBlockSize) Opens an N5HDF5Reader for a given HDF5 file.

Method Summary

Modifier and Type	Method and Description
boolean	blockExists(String pathName, org.janelia.saalfeldlab.n5.DatasetAttributes datasetAttributes, long... gridPosition)
void	close()
protected static boolean	containsEscapeCharacters(String normalizedKey)
protected static void	cropBlockSize(long[] gridPosition, long[] dimensions, int[] blockSize, int[] croppedBlockSize, long[] offset) Crops the dimensions of a DataBlock at a given offset to fit into an interval of given dimensions.
boolean	datasetExists(String pathName)
boolean	doesOverrideBlockSize()
boolean	exists(String pathName)
<T> T	getAttribute(String pathName, String key, Class<T> clazz)
<T> T	getAttribute(String pathName, String key, Type type)
com.google.gson.JsonElement	getAttributes(String pathName)
String	getAttributesKey()
org.janelia.saalfeldlab.n5.DatasetAttributes	getDatasetAttributes(String pathName) Always returns Compression.CompressionType#RAW because I could not yet find a meaningful way to get information about the compression of a dataset.
protected static org.janelia.saalfeldlab.n5.DataType	getDataType(ch.systemsx.cisd.hdf5.HDF5DataSetInformation datasetInfo)
int[]	getDefaultBlockSizeCopy()
File	getFilename()
com.google.gson.Gson	getGson()
URI	getURI()
String[]	list(String pathName)
Map<String,Class<?>>	listAttributes(String pathName) String attributes will be parsed as JSON and classified as 1) An Object[] if it is a JsonArray 2) A String if it is a JsonPrimitive 3) An Object if it is a JsonObject
protected static String	normalizeHdf5PathLocation(String hdf5Path)
<T> org.janelia.saalfeldlab.n5.DataBlock<T>	readBlock(String pathName, org.janelia.saalfeldlab.n5.DatasetAttributes datasetAttributes, long... gridPosition)
<T> org.janelia.saalfeldlab.n5.DataBlock<T>	readChunk(String pathName, org.janelia.saalfeldlab.n5.DatasetAttributes datasetAttributes, long... gridPosition)
protected static void	reorder(int[] array)
protected static void	reorder(long[] array)
String	toString()

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.janelia.saalfeldlab.n5.GsonN5Reader

createDatasetAttributes

Methods inherited from interface org.janelia.saalfeldlab.n5.N5Reader

deepList, deepList, deepList, deepList, deepList, deepListDatasets, deepListDatasets, deepListDatasets, deepListDatasets, deepListHelper, getConvertedDatasetAttributes, getGroupSeparator, getVersion, groupPath, readChunks, readSerializedBlock

Field Detail

gson

protected final com.google.gson.Gson gson

N5_JSON_ROOT_KEY

protected static final String N5_JSON_ROOT_KEY

See Also:

Constant Field Values

FILE_SYSTEM_KEY_VALUE_ACCESS

protected static final org.janelia.saalfeldlab.n5.FileSystemKeyValueAccess FILE_SYSTEM_KEY_VALUE_ACCESS

VERSION

public static final org.janelia.saalfeldlab.n5.N5Reader.Version VERSION

SemVer version of this N5-HDF5 spec.

reader

protected final ch.systemsx.cisd.hdf5.IHDF5Reader reader

defaultBlockSize

protected final int[] defaultBlockSize

overrideBlockSize

protected boolean overrideBlockSize

openDataSetCache

protected final org.janelia.saalfeldlab.n5.hdf5.N5HDF5Util.OpenDataSetCache openDataSetCache

Constructor Detail

N5HDF5Reader

public N5HDF5Reader(ch.systemsx.cisd.hdf5.IHDF5Reader reader,
                    boolean overrideBlockSize,
                    com.google.gson.GsonBuilder gsonBuilder,
                    int... defaultBlockSize)
             throws org.janelia.saalfeldlab.n5.N5Exception

Opens an N5HDF5Reader for a given HDF5 file.

Parameters:

reader - HDF5 reader

overrideBlockSize - true if you want this N5HDF5Reader to use the defaultBlockSize instead of the chunk-size for reading datasets

gsonBuilder - custom GsonBuilder to support custom attributes

defaultBlockSize - for all dimensions > defaultBlockSize.length, and for all dimensions with defaultBlockSize[i] <= 0, the size of the dataset will be used

Throws:

org.janelia.saalfeldlab.n5.N5Exception

N5HDF5Reader

public N5HDF5Reader(ch.systemsx.cisd.hdf5.IHDF5Reader reader,
                    boolean overrideBlockSize,
                    int... defaultBlockSize)

Opens an N5HDF5Reader for a given HDF5 file.

Parameters:

reader - HDF5 reader

overrideBlockSize - true if you want this N5HDF5Reader to use the defaultBlockSize instead of the chunk-size for reading datasets

defaultBlockSize - for all dimensions > defaultBlockSize.length, and for all dimensions with defaultBlockSize[i] <= 0, the size of the dataset will be used

N5HDF5Reader

public N5HDF5Reader(ch.systemsx.cisd.hdf5.IHDF5Reader reader,
                    int... defaultBlockSize)

Opens an N5HDF5Reader for a given HDF5 file.

Parameters:

reader - HDF5 reader

defaultBlockSize - for all dimensions > defaultBlockSize.length, and for all dimensions with defaultBlockSize[i] <= 0, the size of the dataset will be used

N5HDF5Reader

public N5HDF5Reader(String hdf5Path,
                    boolean overrideBlockSize,
                    com.google.gson.GsonBuilder gsonBuilder,
                    int... defaultBlockSize)

Opens an N5HDF5Reader for a given HDF5 file.

Parameters:

hdf5Path - HDF5 file name

overrideBlockSize - true if you want this N5HDF5Reader to use the defaultBlockSize instead of the chunk-size for reading datasets

gsonBuilder - custom GsonBuilder to support custom attributes

defaultBlockSize - for all dimensions > defaultBlockSize.length, and for all dimensions with defaultBlockSize[i] <= 0, the size of the dataset will be used

N5HDF5Reader

public N5HDF5Reader(String hdf5Path,
                    boolean overrideBlockSize,
                    int... defaultBlockSize)

Opens an N5HDF5Reader for a given HDF5 file.

Parameters:

hdf5Path - HDF5 file name

overrideBlockSize - true if you want this N5HDF5Reader to use the defaultBlockSize instead of the chunk-size for reading datasets

defaultBlockSize - for all dimensions > defaultBlockSize.length, and for all dimensions with defaultBlockSize[i] <= 0, the size of the dataset will be used

N5HDF5Reader

public N5HDF5Reader(String hdf5Path,
                    int... defaultBlockSize)

Opens an N5HDF5Reader for a given HDF5 file.

Parameters:

hdf5Path - HDF5 file name

defaultBlockSize - for all dimensions > defaultBlockSize.length, and for all dimensions with defaultBlockSize[i] <= 0, the size of the dataset will be used

Method Detail

getGson

public com.google.gson.Gson getGson()

Specified by:

getGson in interface org.janelia.saalfeldlab.n5.GsonN5Reader

getAttributesKey

public String getAttributesKey()

Specified by:

getAttributesKey in interface org.janelia.saalfeldlab.n5.GsonN5Reader

exists

public boolean exists(String pathName)

Specified by:

exists in interface org.janelia.saalfeldlab.n5.N5Reader

list

public String[] list(String pathName)
              throws org.janelia.saalfeldlab.n5.N5Exception

Specified by:

list in interface org.janelia.saalfeldlab.n5.N5Reader

Throws:

org.janelia.saalfeldlab.n5.N5Exception

normalizeHdf5PathLocation

protected static String normalizeHdf5PathLocation(String hdf5Path)

containsEscapeCharacters

protected static boolean containsEscapeCharacters(String normalizedKey)

getAttribute

public <T> T getAttribute(String pathName,
                          String key,
                          Type type)
                   throws org.janelia.saalfeldlab.n5.N5Exception

Specified by:

getAttribute in interface org.janelia.saalfeldlab.n5.GsonN5Reader

Specified by:

getAttribute in interface org.janelia.saalfeldlab.n5.N5Reader

Throws:

org.janelia.saalfeldlab.n5.N5Exception

getURI

public URI getURI()

Specified by:

getURI in interface org.janelia.saalfeldlab.n5.N5Reader

getAttribute

public <T> T getAttribute(String pathName,
                          String key,
                          Class<T> clazz)
                   throws org.janelia.saalfeldlab.n5.N5Exception

Specified by:

getAttribute in interface org.janelia.saalfeldlab.n5.GsonN5Reader

Specified by:

getAttribute in interface org.janelia.saalfeldlab.n5.N5Reader

Throws:

org.janelia.saalfeldlab.n5.N5Exception

getAttributes

public com.google.gson.JsonElement getAttributes(String pathName)
                                          throws org.janelia.saalfeldlab.n5.N5Exception

Specified by:

getAttributes in interface org.janelia.saalfeldlab.n5.GsonN5Reader

Throws:

org.janelia.saalfeldlab.n5.N5Exception

getDataType

protected static org.janelia.saalfeldlab.n5.DataType getDataType(ch.systemsx.cisd.hdf5.HDF5DataSetInformation datasetInfo)

reorder

protected static void reorder(long[] array)

reorder

protected static void reorder(int[] array)

cropBlockSize

protected static void cropBlockSize(long[] gridPosition,
                                    long[] dimensions,
                                    int[] blockSize,
                                    int[] croppedBlockSize,
                                    long[] offset)

Crops the dimensions of a DataBlock at a given offset to fit into an interval of given dimensions. Fills long and int version of cropped block size. Also calculates the grid raster position assuming that the offset is divisible by block size without remainder.

Parameters:

gridPosition - the coordinate of the block

dimensions - the dataset dimensions

blockSize - the block size

croppedBlockSize - the cropped block size to be filled

offset - the offset to be filled

getDatasetAttributes

public org.janelia.saalfeldlab.n5.DatasetAttributes getDatasetAttributes(String pathName)

Always returns Compression.CompressionType#RAW because I could not yet find a meaningful way to get information about the compression of a dataset.

Specified by:

getDatasetAttributes in interface org.janelia.saalfeldlab.n5.GsonN5Reader

Specified by:

getDatasetAttributes in interface org.janelia.saalfeldlab.n5.N5Reader

Parameters:

pathName - the group or dataset path

Returns:

the DatasetAttributes

readChunk

public <T> org.janelia.saalfeldlab.n5.DataBlock<T> readChunk(String pathName,
                                                             org.janelia.saalfeldlab.n5.DatasetAttributes datasetAttributes,
                                                             long... gridPosition)
                                                      throws org.janelia.saalfeldlab.n5.N5Exception

Specified by:

readChunk in interface org.janelia.saalfeldlab.n5.N5Reader

Throws:

org.janelia.saalfeldlab.n5.N5Exception

readBlock

public <T> org.janelia.saalfeldlab.n5.DataBlock<T> readBlock(String pathName,
                                                             org.janelia.saalfeldlab.n5.DatasetAttributes datasetAttributes,
                                                             long... gridPosition)
                                                      throws org.janelia.saalfeldlab.n5.N5Exception

Specified by:

readBlock in interface org.janelia.saalfeldlab.n5.N5Reader

Throws:

org.janelia.saalfeldlab.n5.N5Exception

blockExists

public boolean blockExists(String pathName,
                           org.janelia.saalfeldlab.n5.DatasetAttributes datasetAttributes,
                           long... gridPosition)
                    throws org.janelia.saalfeldlab.n5.N5Exception

Specified by:

blockExists in interface org.janelia.saalfeldlab.n5.N5Reader

Throws:

org.janelia.saalfeldlab.n5.N5Exception

datasetExists

public boolean datasetExists(String pathName)

Specified by:

datasetExists in interface org.janelia.saalfeldlab.n5.N5Reader

listAttributes

public Map<String,Class<?>> listAttributes(String pathName)
                                    throws org.janelia.saalfeldlab.n5.N5Exception

String attributes will be parsed as JSON and classified as 1) An Object[] if it is a JsonArray 2) A String if it is a JsonPrimitive 3) An Object if it is a JsonObject

Specified by:

listAttributes in interface org.janelia.saalfeldlab.n5.GsonN5Reader

Specified by:

listAttributes in interface org.janelia.saalfeldlab.n5.N5Reader

Throws:

org.janelia.saalfeldlab.n5.N5Exception

close

public void close()

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Specified by:

close in interface org.janelia.saalfeldlab.n5.N5Reader

getFilename

public File getFilename()

Returns:

file name of HDF5 file this reader is associated with

getDefaultBlockSizeCopy

public int[] getDefaultBlockSizeCopy()

Returns:

a copy of the default block size of this reader

doesOverrideBlockSize

public boolean doesOverrideBlockSize()

Returns:

true if this reader overrides block size found in an HDF5 dataset, false otherwise

toString

public String toString()

Overrides:

toString in class Object