loci.formats.in

## Class IM3Reader

- java.lang.Object
- - loci.formats.FormatHandler
  - - loci.formats.FormatReader
    - - loci.formats.in.IM3Reader

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

      public class IM3Reader
      extends FormatReader

  Author:
    Lee Kamentsky This is a FormatReader for the Perkin-Elmer Nuance line of multispectral imaging microscopes' .im3 file format. The .im3 format stores 63 planes representing intensity measurements taken on separate spectral bands. The pixel intensity at a single band might be used as a proxy for fluorophore presence, but the best results are obtained if the whole spectrum is used to synthesize an intensity. The most efficient strategy is to use IM3Reader.openRaw() to fetch the entire image which may then be scanned sequentially to create one planar image per desired signal. IM3Reader may be run as a Java application to dump a per-record description of the file to standard output

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `IM3Reader.BooleanIM3Record` A record containing boolean values
    `protected static class` | `IM3Reader.ContainerRecord`
    `protected static class` | `IM3Reader.FloatIM3Record`
    `protected static class` | `IM3Reader.IM3Record`
    `protected static class` | `IM3Reader.IntIM3Record`
    `static class` | `IM3Reader.Spectrum`
    `protected static class` | `IM3Reader.StringIM3Record`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private static int` | `COOKIE` First 4 bytes of file is "1985"
    `private byte[]` | `data`
    `private java.util.List<IM3Reader.ContainerRecord>` | `dataSets`
    `private static java.lang.String` | `EMPTY_STRING`
    `private static java.lang.String` | `FIELD_AUX_FLAGS`
    `private static java.lang.String` | `FIELD_BAND_INDEX`
    `private static java.lang.String` | `FIELD_BANDS`
    `private static java.lang.String` | `FIELD_CLASS_ID`
    `private static java.lang.String` | `FIELD_DATA`
    `private static java.lang.String` | `FIELD_DATA_SET`
    `private static java.lang.String` | `FIELD_EXPOSURE`
    `private static java.lang.String` | `FIELD_FILE_VERSION`
    `private static java.lang.String` | `FIELD_FILTER_PAIR`
    `private static java.lang.String` | `FIELD_FIXED_FILTER`
    `private static java.lang.String` | `FIELD_HOMOGENEOUS`
    `private static java.lang.String` | `FIELD_MAGNITUDES`
    `private static java.lang.String` | `FIELD_MANUFACTURER`
    `private static java.lang.String` | `FIELD_MILLIMETERS_PER_PIXEL`
    `private static java.lang.String` | `FIELD_NAME`
    `private static java.lang.String` | `FIELD_NUANCE_FLAGS`
    `private static java.lang.String` | `FIELD_OBJECTIVE`
    `private static java.lang.String` | `FIELD_PART_NUMBER`
    `private static java.lang.String` | `FIELD_PROTOCOL`
    `private static java.lang.String` | `FIELD_PROXY_PARENT_FILE_NAME`
    `private static java.lang.String` | `FIELD_SAMPLE_ID`
    `private static java.lang.String` | `FIELD_SHAPE`
    `private static java.lang.String` | `FIELD_SOURCE_FILE_NAME`
    `private static java.lang.String` | `FIELD_SPECTRA`
    `private static java.lang.String` | `FIELD_SPECTRAL_BASIS_INFO`
    `private static java.lang.String` | `FIELD_SPECTRAL_LIBRARY`
    `private static java.lang.String` | `FIELD_SPECTRUM`
    `private static java.lang.String` | `FIELD_THUMBNAIL`
    `private static java.lang.String` | `FIELD_TIMESTAMP`
    `private static java.lang.String` | `FIELD_TYPE_ID`
    `private static java.lang.String` | `FIELD_USER_COMMENTS`
    `private static java.lang.String` | `FIELD_VALUES`
    `private static java.lang.String` | `FIELD_WAVELENGTH`
    `private static java.lang.String` | `FIELD_WAVELENGTHS`
    `private static org.slf4j.Logger` | `LOGGER` Logger for outputting summary diagnostics.
    `private static int` | `REC_BOOLEAN`
    `private static int` | `REC_CONTAINER` A record that is a container of other records.
    `private static int` | `REC_FLOAT`
    `private static int` | `REC_IMAGE` Image format int: pixel type? 3 = RGBA int: width int: height int: depth data bytes follow
    `private static int` | `REC_INT` 32-bit integer values
    `private static int` | `REC_NESTED` A nested record of records
    `private static int` | `REC_STRING` A string int: ? int: length 8-byte characters follow
    `private java.util.List<IM3Reader.IM3Record>` | `records`
    `private java.util.List<IM3Reader.Spectrum>` | `spectra`

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

      `core, 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, metadataOptions, suffixes`

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

      `CAN_GROUP, CANNOT_GROUP, MUST_GROUP`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `IM3Reader()` Construct an uninitialized reader of .im3 files.

  - ### 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.
    `java.util.List<IM3Reader.Spectrum>` | `getSpectra()` If a Nuance file is a spectral library set (.csl) file, there is a spectral library inside that contains a profile of spectral bin magnitudes for each of several measured fluorophores (or auto fluorescence).
    `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.
    `static void` | `main(java.lang.String[] args)` Write a summary of each record to STDOUT
    `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.
    `byte[]` | `openRaw()` Open the current series in raw-mode, returning the interleaved image bytes.
    `private static IM3Reader.IM3Record` | `parseRecord(loci.common.IRandomAccess is)` Parse an IM3 record at the current file pointer location
    `protected static java.lang.String` | `parseString(loci.common.IRandomAccess is)` Parse a string from the IM3 file at the current file pointer loc
    `void` | `setSeries(int no)` Activates the specified series.
    `void` | `writeSummary()` Write a summary of each field in the IM3 file to the writer

    - ### 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, coreIndexToSeries, fileGroupOption, flattenHashtables, get16BitLookupTable, get8BitLookupTable, getAcquisitionMode, getAdvancedSeriesUsedFiles, getAdvancedUsedFiles, getArcType, getAvailableOptions, getBinning, getBitsPerPixel, getCompression, getContrastMethod, getCoreIndex, getCoreMetadataList, getCorrection, getCurrentCore, 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, getResolution, getResolutionCount, getRGBChannelCount, getRotationTransform, getSeries, getSeriesCount, 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, seriesToCoreIndex, setCoreIndex, setFillColor, setFlattenedResolutions, setGroupFiles, setId, setMetadataFiltered, setMetadataStore, setNormalized, setOriginalMetadataPopulated, setResolution, 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

    - #### LOGGER

          private static final org.slf4j.Logger LOGGER

      Logger for outputting summary diagnostics.

    - #### COOKIE

          private static final int COOKIE

      First 4 bytes of file is "1985"
      See Also:
        Constant Field Values

    - #### REC_CONTAINER

          private static final int REC_CONTAINER

      A record that is a container of other records.
      See Also:
        Constant Field Values

    - #### REC_IMAGE

          private static final int REC_IMAGE

      Image format int: pixel type? 3 = RGBA int: width int: height int: depth data bytes follow
      See Also:
        Constant Field Values

    - #### REC_NESTED

          private static final int REC_NESTED

      A nested record of records
      See Also:
        Constant Field Values

    - #### REC_INT

          private static final int REC_INT

      32-bit integer values
      See Also:
        Constant Field Values

    - #### REC_FLOAT

          private static final int REC_FLOAT

      See Also:
        Constant Field Values

    - #### REC_BOOLEAN

          private static final int REC_BOOLEAN

      See Also:
        Constant Field Values

    - #### REC_STRING

          private static final int REC_STRING

      A string int: ? int: length 8-byte characters follow
      See Also:
        Constant Field Values

    - #### FIELD_DATA_SET

          private static final java.lang.String FIELD_DATA_SET

      See Also:
        Constant Field Values

    - #### FIELD_TIMESTAMP

          private static final java.lang.String FIELD_TIMESTAMP

      See Also:
        Constant Field Values

    - #### FIELD_AUX_FLAGS

          private static final java.lang.String FIELD_AUX_FLAGS

      See Also:
        Constant Field Values

    - #### FIELD_NUANCE_FLAGS

          private static final java.lang.String FIELD_NUANCE_FLAGS

      See Also:
        Constant Field Values

    - #### FIELD_SPECTRA

          private static final java.lang.String FIELD_SPECTRA

      See Also:
        Constant Field Values

    - #### FIELD_VALUES

          private static final java.lang.String FIELD_VALUES

      See Also:
        Constant Field Values

    - #### FIELD_PROTOCOL

          private static final java.lang.String FIELD_PROTOCOL

      See Also:
        Constant Field Values

    - #### FIELD_OBJECTIVE

          private static final java.lang.String FIELD_OBJECTIVE

      See Also:
        Constant Field Values

    - #### FIELD_SPECTRAL_BASIS_INFO

          private static final java.lang.String FIELD_SPECTRAL_BASIS_INFO

      See Also:
        Constant Field Values

    - #### FIELD_FILTER_PAIR

          private static final java.lang.String FIELD_FILTER_PAIR

      See Also:
        Constant Field Values

    - #### FIELD_FIXED_FILTER

          private static final java.lang.String FIELD_FIXED_FILTER

      See Also:
        Constant Field Values

    - #### FIELD_BANDS

          private static final java.lang.String FIELD_BANDS

      See Also:
        Constant Field Values

    - #### FIELD_SPECTRAL_LIBRARY

          private static final java.lang.String FIELD_SPECTRAL_LIBRARY

      See Also:
        Constant Field Values

    - #### FIELD_SPECTRUM

          private static final java.lang.String FIELD_SPECTRUM

      See Also:
        Constant Field Values

    - #### FIELD_THUMBNAIL

          private static final java.lang.String FIELD_THUMBNAIL

      See Also:
        Constant Field Values

    - #### FIELD_DATA

          private static final java.lang.String FIELD_DATA

      See Also:
        Constant Field Values

    - #### FIELD_FILE_VERSION

          private static final java.lang.String FIELD_FILE_VERSION

      See Also:
        Constant Field Values

    - #### FIELD_CLASS_ID

          private static final java.lang.String FIELD_CLASS_ID

      See Also:
        Constant Field Values

    - #### FIELD_TYPE_ID

          private static final java.lang.String FIELD_TYPE_ID

      See Also:
        Constant Field Values

    - #### FIELD_SHAPE

          private static final java.lang.String FIELD_SHAPE

      See Also:
        Constant Field Values

    - #### FIELD_BAND_INDEX

          private static final java.lang.String FIELD_BAND_INDEX

      See Also:
        Constant Field Values

    - #### FIELD_NAME

          private static final java.lang.String FIELD_NAME

      See Also:
        Constant Field Values

    - #### FIELD_SAMPLE_ID

          private static final java.lang.String FIELD_SAMPLE_ID

      See Also:
        Constant Field Values

    - #### FIELD_USER_COMMENTS

          private static final java.lang.String FIELD_USER_COMMENTS

      See Also:
        Constant Field Values

    - #### FIELD_SOURCE_FILE_NAME

          private static final java.lang.String FIELD_SOURCE_FILE_NAME

      See Also:
        Constant Field Values

    - #### FIELD_PROXY_PARENT_FILE_NAME

          private static final java.lang.String FIELD_PROXY_PARENT_FILE_NAME

      See Also:
        Constant Field Values

    - #### FIELD_MANUFACTURER

          private static final java.lang.String FIELD_MANUFACTURER

      See Also:
        Constant Field Values

    - #### FIELD_PART_NUMBER

          private static final java.lang.String FIELD_PART_NUMBER

      See Also:
        Constant Field Values

    - #### FIELD_MILLIMETERS_PER_PIXEL

          private static final java.lang.String FIELD_MILLIMETERS_PER_PIXEL

      See Also:
        Constant Field Values

    - #### FIELD_EXPOSURE

          private static final java.lang.String FIELD_EXPOSURE

      See Also:
        Constant Field Values

    - #### FIELD_WAVELENGTH

          private static final java.lang.String FIELD_WAVELENGTH

      See Also:
        Constant Field Values

    - #### FIELD_WAVELENGTHS

          private static final java.lang.String FIELD_WAVELENGTHS

      See Also:
        Constant Field Values

    - #### FIELD_MAGNITUDES

          private static final java.lang.String FIELD_MAGNITUDES

      See Also:
        Constant Field Values

    - #### FIELD_HOMOGENEOUS

          private static final java.lang.String FIELD_HOMOGENEOUS

      See Also:
        Constant Field Values

    - #### records

          private java.util.List<IM3Reader.IM3Record> records

    - #### dataSets

          private java.util.List<IM3Reader.ContainerRecord> dataSets

    - #### spectra

          private java.util.List<IM3Reader.Spectrum> spectra

    - #### data

          private byte[] data

    - #### EMPTY_STRING

          private static final java.lang.String EMPTY_STRING

  - ### Constructor Detail

    - #### IM3Reader

          public IM3Reader()

      Construct an uninitialized reader of .im3 files.

  - ### Method Detail

    - #### 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.

    - #### openRaw

          public byte[] openRaw()
                         throws java.io.IOException

      Open the current series in raw-mode, returning the interleaved image bytes. The data format for a pixel is a run of 63 unsigned short little endian values.
      Returns:
        a byte array containing the data organized by spectral channel, then x, then y. Returns null if, for some incomprehensible reason, the DATA block was missing.
      Throws:
        `java.io.IOException`

    - #### getSpectra

          public java.util.List<IM3Reader.Spectrum> getSpectra()

      If a Nuance file is a spectral library set (.csl) file, there is a spectral library inside that contains a profile of spectral bin magnitudes for each of several measured fluorophores (or auto fluorescence). This method finds the spectral library and returns the spectra inside.
      Returns:
        a list of the Spectrum records contained in the library

    - #### initFile

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

      Description copied from class: `FormatReader`
      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 `FormatReader`
      Throws:
        `FormatException` - if a parsing error occurs processing the file.
        `java.io.IOException` - if an I/O error occurs processing the file

    - #### parseString

          protected static java.lang.String parseString(loci.common.IRandomAccess is)
                                                 throws java.io.IOException

      Parse a string from the IM3 file at the current file pointer loc
      Parameters:
        `is` - stream to read from
      Returns:
        parsed string or null for string of zero length
      Throws:
        `java.io.IOException`

    - #### parseRecord

          private static IM3Reader.IM3Record parseRecord(loci.common.IRandomAccess is)
                                                  throws java.io.IOException

      Parse an IM3 record at the current file pointer location
      Parameters:
        `is` - random access stream, pointing at the record's start (the length-quadword of the record's tag name)
      Returns:
        an IM3Record or subclass depending on the record's type
      Throws:
        `java.io.IOException` - on file misparsing leading to overrun and other

    - #### 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`

    - #### setSeries

          public void setSeries(int no)

      Description copied from interface: `IFormatReader`
      Activates the specified series. This also resets the resolution to 0.
      Specified by:
        `setSeries` in interface `IFormatReader`
      Overrides:
        `setSeries` in class `FormatReader`

    - #### 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 `FormatReader`
      Throws:
        `java.io.IOException`

    - #### writeSummary

          public void writeSummary()
                            throws java.io.IOException

      Write a summary of each field in the IM3 file to the writer
      Throws:
        `java.io.IOException`

    - #### main

          public static void main(java.lang.String[] args)
                           throws java.io.IOException

      Write a summary of each record to STDOUT
      Parameters:
        `args` -
      Throws:
        `java.io.IOException`

Copyright © 2026 Open Microscopy Environment