loci.formats.in

## Class ND2Reader

- java.lang.Object
- - loci.formats.FormatHandler
  - - loci.formats.FormatReader
    - - loci.formats.SubResolutionFormatReader
      - - loci.formats.in.ND2Reader

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, ICompressedTileReader, IFormatHandler, IFormatReader, IMetadataConfigurable, IPyramidHandler

      public class ND2Reader
      extends SubResolutionFormatReader

  ND2Reader is the file format reader for Nikon ND2 files. The JAI ImageIO library is required to use this reader; it is available from http://jai-imageio.dev.java.net. Note that JAI ImageIO is bundled with a version of the JJ2000 library, so it is important that either: (1) the JJ2000 jar file is *not* in the classpath; or (2) the JAI jar file precedes JJ2000 in the classpath. Thanks to Tom Caswell for additions to the ND2 metadata parsing logic.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `(package private) static class` | `ND2Reader.ChunkMapEntry`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private ND2Handler` | `backupHandler`
    `private static int` | `BUFFER_SIZE`
    `private java.util.Map<java.lang.String,java.lang.Integer>` | `channelColors`
    `private Codec` | `codec` Codec to use when decompressing pixel data.
    `private int[]` | `colors`
    `private java.util.ArrayList<java.lang.Double>` | `exposureTime`
    `private int` | `fieldIndex`
    `(package private) java.lang.String` | `imageMetadataLVOrder`
    `(package private) java.lang.Boolean` | `imageMetadataLVProcessed`
    `private boolean` | `isJPEG` Whether or not the pixel data is compressed using JPEG 2000.
    `private boolean` | `isLossless` Whether or not the pixel data is losslessly compressed.
    `private int` | `lastChannel`
    `private java.lang.Double` | `lensNA`
    `static long` | `ND2_MAGIC_BYTES_1`
    `static long` | `ND2_MAGIC_BYTES_2`
    `private int` | `nXFields`
    `private java.lang.Double` | `objectiveMag`
    `private java.lang.String` | `objectiveModel`
    `private long[][]` | `offsets` Array of image offsets.
    `private long` | `pfsOffset`
    `private long` | `pfsStateOffset`
    `private int` | `positionCount`
    `private java.util.ArrayList<ome.units.quantity.Length>` | `posX`
    `private java.util.ArrayList<ome.units.quantity.Length>` | `posY`
    `private java.util.ArrayList<ome.units.quantity.Length>` | `posZ`
    `private java.lang.Double` | `refractiveIndex`
    `private boolean` | `split`
    `private java.util.ArrayList<java.lang.String>` | `textChannelNames`
    `private boolean` | `textData`
    `private java.util.ArrayList<java.lang.Double>` | `textEmissionWavelengths`
    `private double` | `trueSizeX`
    `private double` | `trueSizeY`
    `private java.lang.Double` | `trueSizeZ`
    `private java.util.ArrayList<java.lang.Double>` | `tsT`
    `static boolean` | `USE_CHUNKMAP_DEFAULT`
    `static java.lang.String` | `USE_CHUNKMAP_KEY`
    `static java.lang.String` | `USE_CHUNKMAP_LEGACY_KEY` Deprecated.
    `private java.lang.Boolean` | `useZ`
    `private long` | `xOffset`
    `private long` | `yOffset`
    `private long` | `zOffset`

    - ### Fields inherited from class loci.formats.SubResolutionFormatReader

      `core`

    - ### Fields inherited from class loci.formats.FormatReader

      `coreIndex, datasetDescription, domains, fillColor, filterMetadata, flattenedResolutions, group, hasCompanionFiles, in, indexedAsRGB, metadata, metadataStore, normalizeData, resolution, saveOriginalMetadata, series, suffixNecessary, suffixSufficient, THUMBNAIL_DIMENSION`

    - ### Fields inherited from class loci.formats.FormatHandler

      `COMPRESSION_SUFFIXES, currentId, format, LOGGER, metadataOptions, suffixes`

    - ### Fields inherited from interface loci.formats.IFormatReader

      `CAN_GROUP, CANNOT_GROUP, MUST_GROUP`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ND2Reader()` Constructs a new ND2 reader.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close(boolean fileOnly)` Closes the currently open file.
    `private void` | `copyPixels(int x, int y, int w, int h, int bpp, int scanlinePad, byte[] pix, byte[] buf, boolean split)`
    `private Codec` | `createCodec(boolean isJPEG)`
    `short[][]` | `get16BitLookupTable()` Gets the 16-bit color lookup table associated with the most recently opened image.
    `byte[][]` | `get8BitLookupTable()` Gets the 8-bit color lookup table associated with the most recently opened image.
    `protected java.util.ArrayList<java.lang.String>` | `getAvailableOptions()` Returns the list of available metadata options.
    `long[][]` | `getOffsets()`
    `private int` | `getScanlinePad()`
    `protected void` | `initFile(java.lang.String id)` Initializes the given file (parsing header information, etc.).
    `boolean` | `isThisType(loci.common.RandomAccessInputStream stream)` Checks if the given stream is a valid stream for this file format.
    `private java.util.ArrayList<java.lang.String>` | `iterateIn(loci.common.RandomAccessInputStream in, java.lang.Long stop)` Function for iterating through ND2 metaAttributes
    `private java.util.ArrayList<java.lang.String>` | `iterateIn(loci.common.RandomAccessInputStream in, java.lang.Long stop, boolean minimal)` Function for iterating through ND2 metaAttributes
    `byte[]` | `openBytes(int no, byte[] buf, int x, int y, int w, int h)` Obtains a sub-image of the specified image plane into a pre-allocated byte array.
    `private void` | `parseText(java.lang.String textString, int offsetCount, boolean useDimensions)`
    `private void` | `populateMetadataStore(ND2Handler handler)`
    `static java.lang.String` | `sanitizeControl(java.lang.String s)` Remove control and invalid characters from the given string.
    `private void` | `setDimensions(int numT, int numZ, int numSeries)`
    `void` | `setOffsets(java.lang.String file, long[][] newOffsets)` Change the underlying file path and pixel data offsets, keeping all other metadata the same.
    `boolean` | `useChunkMap()`

    - ### Methods inherited from class loci.formats.SubResolutionFormatReader

      `coreIndexToSeries, flattenHashtables, getCoreIndex, getCoreMetadataList, getCurrentCore, getResolution, getResolutionCount, getSeries, getSeriesCount, seriesToCoreIndex, setCoreIndex, setResolution, setSeries`

    - ### Methods inherited from class loci.formats.FormatReader

      `addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMetaList, addMeta, addMetaList, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMetaList, close, fileGroupOption, getAcquisitionMode, getAdvancedSeriesUsedFiles, getAdvancedUsedFiles, getArcType, getBinning, getBitsPerPixel, getCompression, getContrastMethod, getCorrection, getCurrentFile, getDatasetStructureDescription, getDetectorType, getDimensionOrder, getDimensionOrder, getDomains, getEffectiveSizeC, getExperimentType, getFilamentType, getFillColor, getFillRule, getFilterType, getFontFamily, getFontStyle, getGlobalMeta, getGlobalMetadata, getIlluminationType, getImageCount, getImmersion, getIndex, getIndex, getLaserMedium, getLaserType, getMarker, getMedium, getMetadataStore, getMetadataStoreRoot, getMetadataValue, getMicrobeamManipulationType, getMicroscopeType, getModuloC, getModuloT, getModuloZ, getNamingConvention, getOptimalTileHeight, getOptimalTileWidth, getPixelType, getPixelType, getPossibleDomains, getPulse, getRequiredDirectories, getRGBChannelCount, getRotationTransform, getSeriesMeta, getSeriesMetadata, getSeriesMetadataValue, getSeriesUsedFiles, getSeriesUsedFiles, getSizeC, getSizeT, getSizeX, getSizeY, getSizeZ, getThumbSizeX, getThumbSizeY, getTileColumns, getTileRows, getUnderlyingReaders, getUsedFiles, getUsedFiles, getZCTCoords, getZCTModuloCoords, hasCompanionFiles, hasFlattenedResolutions, isFalseColor, isGroupFiles, isIndexed, isInterleaved, isInterleaved, isLittleEndian, isMetadataComplete, isMetadataFiltered, isNormalized, isOrderCertain, isOriginalMetadataPopulated, isRGB, isSingleFile, isThisType, isThisType, isThisType, isThumbnailSeries, isUsedFile, makeFilterMetadata, openBytes, openBytes, openBytes, openPlane, openThumbBytes, readPlane, readPlane, readPlane, reopenFile, setFillColor, setFlattenedResolutions, setGroupFiles, setId, setMetadataFiltered, setMetadataStore, setNormalized, setOriginalMetadataPopulated, updateMetadataLists`

    - ### Methods inherited from class loci.formats.FormatHandler

      `checkSuffix, checkSuffix, getFormat, getMetadataOptions, getNativeDataType, getSuffixes, getSupportedMetadataLevels, setMetadataOptions`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface loci.formats.IFormatHandler

      `getFormat, getNativeDataType, getSuffixes`

    - ### Methods inherited from interface loci.formats.IMetadataConfigurable

      `getMetadataOptions, getSupportedMetadataLevels, setMetadataOptions`

    - ### Methods inherited from interface loci.formats.ICompressedTileReader

      `getTileCodec, getTileCodecOptions, openCompressedBytes, openCompressedBytes`

- - ### Field Detail

    - #### ND2_MAGIC_BYTES_1

          public static final long ND2_MAGIC_BYTES_1

      See Also:
        Constant Field Values

    - #### ND2_MAGIC_BYTES_2

          public static final long ND2_MAGIC_BYTES_2

      See Also:
        Constant Field Values

    - #### BUFFER_SIZE

          private static final int BUFFER_SIZE

      See Also:
        Constant Field Values

    - #### USE_CHUNKMAP_LEGACY_KEY

          @Deprecated
          public static final java.lang.String USE_CHUNKMAP_LEGACY_KEY

      Deprecated.
      Legacy chunkmap option key will be removed in Bio-Formats 8.0.0.
      See Also:
        Constant Field Values

    - #### USE_CHUNKMAP_KEY

          public static final java.lang.String USE_CHUNKMAP_KEY

      See Also:
        Constant Field Values

    - #### USE_CHUNKMAP_DEFAULT

          public static final boolean USE_CHUNKMAP_DEFAULT

      See Also:
        Constant Field Values

    - #### offsets

          private long[][] offsets

      Array of image offsets.

    - #### isJPEG

          private boolean isJPEG

      Whether or not the pixel data is compressed using JPEG 2000.

    - #### codec

          private Codec codec

      Codec to use when decompressing pixel data.

    - #### isLossless

          private boolean isLossless

      Whether or not the pixel data is losslessly compressed.

    - #### tsT

          private java.util.ArrayList<java.lang.Double> tsT

    - #### positionCount

          private int positionCount

    - #### fieldIndex

          private int fieldIndex

    - #### xOffset

          private long xOffset

    - #### yOffset

          private long yOffset

    - #### zOffset

          private long zOffset

    - #### pfsOffset

          private long pfsOffset

    - #### pfsStateOffset

          private long pfsStateOffset

    - #### posX

          private java.util.ArrayList<ome.units.quantity.Length> posX

    - #### posY

          private java.util.ArrayList<ome.units.quantity.Length> posY

    - #### posZ

          private java.util.ArrayList<ome.units.quantity.Length> posZ

    - #### exposureTime

          private java.util.ArrayList<java.lang.Double> exposureTime

    - #### channelColors

          private java.util.Map<java.lang.String,java.lang.Integer> channelColors

    - #### split

          private boolean split

    - #### lastChannel

          private int lastChannel

    - #### colors

          private int[] colors

    - #### useZ

          private java.lang.Boolean useZ

    - #### nXFields

          private int nXFields

    - #### backupHandler

          private ND2Handler backupHandler

    - #### trueSizeX

          private double trueSizeX

    - #### trueSizeY

          private double trueSizeY

    - #### trueSizeZ

          private java.lang.Double trueSizeZ

    - #### textChannelNames

          private java.util.ArrayList<java.lang.String> textChannelNames

    - #### textEmissionWavelengths

          private java.util.ArrayList<java.lang.Double> textEmissionWavelengths

    - #### textData

          private boolean textData

    - #### refractiveIndex

          private java.lang.Double refractiveIndex

    - #### imageMetadataLVProcessed

          java.lang.Boolean imageMetadataLVProcessed

    - #### imageMetadataLVOrder

          java.lang.String imageMetadataLVOrder

    - #### lensNA

          private transient java.lang.Double lensNA

    - #### objectiveMag

          private transient java.lang.Double objectiveMag

    - #### objectiveModel

          private transient java.lang.String objectiveModel

  - ### Constructor Detail

    - #### ND2Reader

          public ND2Reader()

      Constructs a new ND2 reader.

  - ### Method Detail

    - #### useChunkMap

          public boolean useChunkMap()

    - #### isThisType

          public boolean isThisType(loci.common.RandomAccessInputStream stream)
                             throws java.io.IOException

      Description copied from interface: `IFormatReader`
      Checks if the given stream is a valid stream for this file format. The number of bytes read is format-dependent.
      Specified by:
        `isThisType` in interface `IFormatReader`
      Overrides:
        `isThisType` in class `FormatReader`
      Parameters:
        `stream` - A RandomAccessInputStream representing the file to check. The first byte in the stream is assumed to be the first byte in the file.
      Returns:
        true if the file represented by the stream can be read by this reader; false otherwise.
      Throws:
        `java.io.IOException`

    - #### get8BitLookupTable

          public byte[][] get8BitLookupTable()

      Description copied from interface: `IFormatReader`
      Gets the 8-bit color lookup table associated with the most recently opened image. If no image planes have been opened, or if `IFormatReader.isIndexed()` returns false, then this may return null. Also, if `IFormatReader.getPixelType()` returns anything other than `FormatTools.INT8` or `FormatTools.UINT8`, this method will return null.
      Specified by:
        `get8BitLookupTable` in interface `IFormatReader`
      Overrides:
        `get8BitLookupTable` in class `FormatReader`

    - #### get16BitLookupTable

          public short[][] get16BitLookupTable()

      Description copied from interface: `IFormatReader`
      Gets the 16-bit color lookup table associated with the most recently opened image. If no image planes have been opened, or if `IFormatReader.isIndexed()` returns false, then this may return null. Also, if `IFormatReader.getPixelType()` returns anything other than `FormatTools.INT16` or `FormatTools.UINT16`, this method will return null.
      Specified by:
        `get16BitLookupTable` in interface `IFormatReader`
      Overrides:
        `get16BitLookupTable` in class `FormatReader`

    - #### openBytes

          public byte[] openBytes(int no,
                                  byte[] buf,
                                  int x,
                                  int y,
                                  int w,
                                  int h)
                           throws FormatException,
                                  java.io.IOException

      Description copied from interface: `IFormatReader`
      Obtains a sub-image of the specified image plane into a pre-allocated byte array.
      Specified by:
        `openBytes` in interface `IFormatReader`
      Specified by:
        `openBytes` in class `FormatReader`
      Parameters:
        `no` - the plane index within the current series.
        `buf` - a pre-allocated buffer.
        `x` - X coordinate of the upper-left corner of the sub-image
        `y` - Y coordinate of the upper-left corner of the sub-image
        `w` - width of the sub-image
        `h` - height of the sub-image
      Returns:
        the pre-allocated buffer `buf` for convenience.
      Throws:
        `FormatException` - if there was a problem parsing the metadata of the file.
        `java.io.IOException` - if there was a problem reading the file.
      See Also:
        `IFormatReader.openBytes(int, byte[], int, int, int, int)`

    - #### close

          public void close(boolean fileOnly)
                     throws java.io.IOException

      Description copied from interface: `IFormatReader`
      Closes the currently open file. If the flag is set, this is all that happens; if unset, it is equivalent to calling `Closeable.close()`.
      Specified by:
        `close` in interface `IFormatReader`
      Overrides:
        `close` in class `SubResolutionFormatReader`
      Throws:
        `java.io.IOException`

    - #### getAvailableOptions

          protected java.util.ArrayList<java.lang.String> getAvailableOptions()

      Description copied from class: `FormatReader`
      Returns the list of available metadata options.
      Overrides:
        `getAvailableOptions` in class `FormatReader`

    - #### initFile

          protected void initFile(java.lang.String id)
                           throws FormatException,
                                  java.io.IOException

      Description copied from class: `SubResolutionFormatReader`
      Initializes the given file (parsing header information, etc.). Most subclasses should override this method to perform initialization operations such as parsing metadata.
      Overrides:
        `initFile` in class `SubResolutionFormatReader`
      Throws:
        `FormatException` - if a parsing error occurs processing the file.
        `java.io.IOException` - if an I/O error occurs processing the file

    - #### iterateIn

          private java.util.ArrayList<java.lang.String> iterateIn(loci.common.RandomAccessInputStream in,
                                                                  java.lang.Long stop)

      Function for iterating through ND2 metaAttributes
      Parameters:
        `in` - stream of bytes from file
        `stop` - position where to stop
      Returns:
        text info values, if found

    - #### iterateIn

          private java.util.ArrayList<java.lang.String> iterateIn(loci.common.RandomAccessInputStream in,
                                                                  java.lang.Long stop,
                                                                  boolean minimal)

      Function for iterating through ND2 metaAttributes
      Parameters:
        `in` - stream of bytes from file
        `stop` - position where to stop
        `minimal` - true if values should be read with no additional metadata parsing
      Returns:
        text info values, if found

    - #### populateMetadataStore

          private void populateMetadataStore(ND2Handler handler)
                                      throws FormatException

      Throws:
        `FormatException`

    - #### createCodec

          private Codec createCodec(boolean isJPEG)

    - #### copyPixels

          private void copyPixels(int x,
                                  int y,
                                  int w,
                                  int h,
                                  int bpp,
                                  int scanlinePad,
                                  byte[] pix,
                                  byte[] buf,
                                  boolean split)
                           throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### sanitizeControl

          public static java.lang.String sanitizeControl(java.lang.String s)

      Remove control and invalid characters from the given string.

    - #### getScanlinePad

          private int getScanlinePad()

    - #### parseText

          private void parseText(java.lang.String textString,
                                 int offsetCount,
                                 boolean useDimensions)

    - #### setDimensions

          private void setDimensions(int numT,
                                     int numZ,
                                     int numSeries)

    - #### getOffsets

          public long[][] getOffsets()

      Returns:
        offsets to pixel data

    - #### setOffsets

          public void setOffsets(java.lang.String file,
                                 long[][] newOffsets)
                          throws java.io.IOException

      Change the underlying file path and pixel data offsets, keeping all other metadata the same.
      Throws:
        `java.io.IOException`

Copyright © 2026 Open Microscopy Environment