loci.formats

## Class ImageWriter

- java.lang.Object
- - loci.formats.ImageWriter

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, ICompressedTileWriter, IFormatHandler, IFormatWriter, IMetadataConfigurable, IPyramidHandler

      public class ImageWriter
      extends java.lang.Object
      implements IFormatWriter

  ImageWriter is the master file format writer for all supported formats. It uses one instance of each writer subclass (specified in writers.txt, or other class list source) to identify file formats and write data.
  Author:
    Curtis Rueden ctrueden at wisc.edu

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `current` Current form index.
    `protected java.lang.String` | `currentId` Name of current file.
    `private static ClassList<IFormatWriter>` | `defaultClasses` Default list of writer classes, for use with noargs constructor.
    `private static org.slf4j.Logger` | `LOGGER`
    `private java.lang.String[]` | `suffixes` Valid suffixes for all file format writers.
    `protected IFormatWriter[]` | `writers` List of supported file format writers.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ImageWriter()` Constructs a new ImageWriter with the default list of writer classes from writers.txt.
    `ImageWriter(ClassList<IFormatWriter> classList)` Constructs a new ImageWriter from the given list of writer classes.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `canDoStacks()` Reports whether the writer can save multiple images to a single file.
    `void` | `changeOutputFile(java.lang.String id)` Switch the output file for the current dataset.
    `void` | `close()`
    `Codec` | `getCodec()`
    `CodecOptions` | `getCodecOptions()`
    `java.awt.image.ColorModel` | `getColorModel()` Gets the color model.
    `java.lang.String` | `getCompression()` Gets the current compression type.
    `java.lang.String[]` | `getCompressionTypes()` Gets the available compression types.
    `static ClassList<IFormatWriter>` | `getDefaultWriterClasses()`
    `java.lang.String` | `getFormat()` Gets the name of this file format.
    `java.lang.String` | `getFormat(java.lang.String id)` Gets a string describing the file format for the given file.
    `int` | `getFramesPerSecond()` Gets the frames per second to use when writing.
    `MetadataOptions` | `getMetadataOptions()`
    `MetadataRetrieve` | `getMetadataRetrieve()` Retrieves the current metadata retrieval object for this writer.
    `java.lang.Class<?>` | `getNativeDataType()` Returns the native data type of image planes for this reader, as returned by `IFormatReader.openPlane(int, int, int, int, int)` or `IFormatWriter.savePlane(int, java.lang.Object)`.
    `int[]` | `getPixelTypes()` Gets the supported pixel types.
    `int[]` | `getPixelTypes(java.lang.String codec)` Gets the supported pixel types for the given codec.
    `int` | `getResolution()` Get the current resolution level.
    `int` | `getResolutionCount()` Return the number of resolutions for the current series.
    `java.util.List<Resolution>` | `getResolutions()` Get a list of resolution objects for the current series.
    `int` | `getSeries()` Returns the current series.
    `java.lang.String[]` | `getSuffixes()` Gets the default file suffixes for this file format.
    `java.util.Set<MetadataLevel>` | `getSupportedMetadataLevels()`
    `int` | `getTileSizeX()` Retrieves the current tile width Defaults to 0 if not supported
    `int` | `getTileSizeY()` Retrieves the current tile height Defaults to 0 if not supported
    `IFormatWriter` | `getWriter()` Gets the writer used to save the current file.
    `IFormatWriter` | `getWriter(java.lang.Class<? extends IFormatWriter> c)` Gets the file format writer instance matching the given class.
    `IFormatWriter` | `getWriter(java.lang.String id)` Gets the writer used to save the given file.
    `IFormatWriter[]` | `getWriters()` Gets all constituent file format writers.
    `boolean` | `isInterleaved()` Gets whether or not the channels in an image are interleaved.
    `boolean` | `isSupportedType(int type)` Checks if the given pixel type is supported.
    `boolean` | `isThisType(java.lang.String name)` Checks if the given string is a valid filename for this file format.
    `void` | `saveBytes(int no, byte[] buf)` Saves the given image to the current series in the current file.
    `void` | `saveBytes(int no, byte[] buf, int x, int y, int w, int h)` Saves the given image tile to the current series in the current file.
    `void` | `saveBytes(int no, byte[] buf, loci.common.Region tile)` Saves the given image tile to the current series in the current file.
    `void` | `saveCompressedBytes(int no, byte[] buf, int x, int y, int w, int h)` Save a compressed tile to the current output file.
    `void` | `savePlane(int no, java.lang.Object plane)` Saves the given image plane to the current series in the current file.
    `void` | `savePlane(int no, java.lang.Object plane, int x, int y, int w, int h)` Saves the given image plane to the current series in the current file.
    `void` | `savePlane(int no, java.lang.Object plane, loci.common.Region tile)` Saves the given image plane to the current series in the current file.
    `void` | `setCodecOptions(CodecOptions options)` Sets the codec options.
    `void` | `setColorModel(java.awt.image.ColorModel cm)` Sets the color model.
    `void` | `setCompression(java.lang.String compress)` Sets the current compression type.
    `void` | `setFramesPerSecond(int rate)` Sets the frames per second to use when writing.
    `void` | `setId(java.lang.String id)` Sets the current file name.
    `void` | `setInterleaved(boolean interleaved)` Sets whether or not the channels in an image are interleaved.
    `void` | `setMetadataOptions(MetadataOptions options)`
    `void` | `setMetadataRetrieve(MetadataRetrieve r)` Sets the metadata retrieval object from which to retrieve standardized metadata.
    `void` | `setResolution(int resolution)` Set the resolution level.
    `void` | `setResolutions(java.util.List<Resolution> resolutions)` Specify a list of resolution objects for the current series.
    `void` | `setSeries(int series)` Sets the current series.
    `int` | `setTileSizeX(int tileSize)` Will attempt to set the tile width to the desired value and return the actual value which will be used
    `int` | `setTileSizeY(int tileSize)` Will attempt to set the tile height to the desired value and return the actual value which will be used
    `void` | `setValidBitsPerPixel(int bits)` Sets the number of valid bits per pixel.
    `void` | `setWriteSequentially(boolean sequential)` Sets whether or not we know that planes will be written sequentially.

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

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

- - ### Field Detail

    - #### LOGGER

          private static final org.slf4j.Logger LOGGER

    - #### defaultClasses

          private static ClassList<IFormatWriter> defaultClasses

      Default list of writer classes, for use with noargs constructor.

    - #### writers

          protected IFormatWriter[] writers

      List of supported file format writers.

    - #### suffixes

          private java.lang.String[] suffixes

      Valid suffixes for all file format writers. Populated the first time getSuffixes() is called.

    - #### currentId

          protected java.lang.String currentId

      Name of current file.

    - #### current

          protected int current

      Current form index.

  - ### Constructor Detail

    - #### ImageWriter

          public ImageWriter()

      Constructs a new ImageWriter with the default list of writer classes from writers.txt.

    - #### ImageWriter

          public ImageWriter(ClassList<IFormatWriter> classList)

      Constructs a new ImageWriter from the given list of writer classes.

  - ### Method Detail

    - #### getDefaultWriterClasses

          public static ClassList<IFormatWriter> getDefaultWriterClasses()

    - #### getFormat

          public java.lang.String getFormat(java.lang.String id)
                                     throws FormatException,
                                            java.io.IOException

      Gets a string describing the file format for the given file.
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### getWriter

          public IFormatWriter getWriter(java.lang.String id)
                                  throws FormatException

      Gets the writer used to save the given file.
      Throws:
        `FormatException`

    - #### getWriter

          public IFormatWriter getWriter()

      Gets the writer used to save the current file.

    - #### getWriter

          public IFormatWriter getWriter(java.lang.Class<? extends IFormatWriter> c)

      Gets the file format writer instance matching the given class.

    - #### getWriters

          public IFormatWriter[] getWriters()

      Gets all constituent file format writers.

    - #### getTileSizeX

          public int getTileSizeX()
                           throws FormatException

      Description copied from interface: `IFormatWriter`
      Retrieves the current tile width Defaults to 0 if not supported
      Specified by:
        `getTileSizeX` in interface `IFormatWriter`
      Returns:
        The current tile width being used
      Throws:
        `FormatException` - Image metadata including Pixels Size X must be set prior to calling getTileSizeX()

    - #### setTileSizeX

          public int setTileSizeX(int tileSize)
                           throws FormatException

      Description copied from interface: `IFormatWriter`
      Will attempt to set the tile width to the desired value and return the actual value which will be used
      Specified by:
        `setTileSizeX` in interface `IFormatWriter`
      Parameters:
        `tileSize` - The tile width you wish to use. Setting to 0 will disable tiling
      Returns:
        The tile width which will actually be used, this may differ from the value requested. If the requested value is not supported the writer will return and use the closest appropriate value.
      Throws:
        `FormatException` - Tile size must be greater than or equal to 0 and less than the image width

    - #### getTileSizeY

          public int getTileSizeY()
                           throws FormatException

      Description copied from interface: `IFormatWriter`
      Retrieves the current tile height Defaults to 0 if not supported
      Specified by:
        `getTileSizeY` in interface `IFormatWriter`
      Returns:
        The current tile height being used
      Throws:
        `FormatException` - Image metadata including Pixels Size Y must be set prior to calling getTileSizeY()

    - #### setTileSizeY

          public int setTileSizeY(int tileSize)
                           throws FormatException

      Description copied from interface: `IFormatWriter`
      Will attempt to set the tile height to the desired value and return the actual value which will be used
      Specified by:
        `setTileSizeY` in interface `IFormatWriter`
      Parameters:
        `tileSize` - The tile height you wish to use. Setting to 0 will disable tiling
      Returns:
        The tile height which will actually be used, this may differ from the value requested. If the requested value is not supported the writer will return and use the closest appropriate value.
      Throws:
        `FormatException` - Tile size must be greater than or equal to 0 and less than the image height

    - #### setResolutions

          public void setResolutions(java.util.List<Resolution> resolutions)

      Description copied from interface: `IFormatWriter`
      Specify a list of resolution objects for the current series. If resolutions are specified using this method, then any resolution data supplied via the MetadataRetrieve will be ignored.
      Specified by:
        `setResolutions` in interface `IFormatWriter`

    - #### getResolutions

          public java.util.List<Resolution> getResolutions()

      Description copied from interface: `IFormatWriter`
      Get a list of resolution objects for the current series.
      Specified by:
        `getResolutions` in interface `IFormatWriter`

    - #### getSupportedMetadataLevels

          public java.util.Set<MetadataLevel> getSupportedMetadataLevels()

      Specified by:
        `getSupportedMetadataLevels` in interface `IMetadataConfigurable`

    - #### getMetadataOptions

          public MetadataOptions getMetadataOptions()

      Specified by:
        `getMetadataOptions` in interface `IMetadataConfigurable`

    - #### setMetadataOptions

          public void setMetadataOptions(MetadataOptions options)

      Specified by:
        `setMetadataOptions` in interface `IMetadataConfigurable`
      See Also:
        `IMetadataConfigurable.setMetadataOptions(MetadataOptions)`

    - #### changeOutputFile

          public void changeOutputFile(java.lang.String id)
                                throws FormatException,
                                       java.io.IOException

      Description copied from interface: `IFormatWriter`
      Switch the output file for the current dataset.
      Specified by:
        `changeOutputFile` in interface `IFormatWriter`
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### saveBytes

          public void saveBytes(int no,
                                byte[] buf)
                         throws FormatException,
                                java.io.IOException

      Description copied from interface: `IFormatWriter`
      Saves the given image to the current series in the current file.
      Specified by:
        `saveBytes` in interface `IFormatWriter`
      Parameters:
        `no` - the plane index within the series.
        `buf` - the byte array that represents the image.
      Throws:
        `FormatException` - if one of the parameters is invalid.
        `java.io.IOException` - if there was a problem writing to the file.

    - #### saveBytes

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

      Description copied from interface: `IFormatWriter`
      Saves the given image tile to the current series in the current file.
      Specified by:
        `saveBytes` in interface `IFormatWriter`
      Parameters:
        `no` - the plane index within the series.
        `buf` - the byte array that represents the image tile.
        `x` - the X coordinate of the upper-left corner of the image tile.
        `y` - the Y coordinate of the upper-left corner of the image tile.
        `w` - the width (in pixels) of the image tile.
        `h` - the height (in pixels) of the image tile.
      Throws:
        `FormatException` - if one of the parameters is invalid.
        `java.io.IOException` - if there was a problem writing to the file.

    - #### saveBytes

          public void saveBytes(int no,
                                byte[] buf,
                                loci.common.Region tile)
                         throws FormatException,
                                java.io.IOException

      Description copied from interface: `IFormatWriter`
      Saves the given image tile to the current series in the current file.
      Specified by:
        `saveBytes` in interface `IFormatWriter`
      Parameters:
        `no` - the plane index within the series.
        `buf` - the byte array that represents the image tile.
        `tile` - the Region representing the image tile to be read.
      Throws:
        `FormatException` - if one of the parameters is invalid.
        `java.io.IOException` - if there was a problem writing to the file.

    - #### savePlane

          public void savePlane(int no,
                                java.lang.Object plane)
                         throws FormatException,
                                java.io.IOException

      Description copied from interface: `IFormatWriter`
      Saves the given image plane to the current series in the current file.
      Specified by:
        `savePlane` in interface `IFormatWriter`
      Parameters:
        `no` - the plane index within the series.
        `plane` - the image plane.
      Throws:
        `FormatException` - if one of the parameters is invalid.
        `java.io.IOException` - if there was a problem writing to the file.

    - #### savePlane

          public void savePlane(int no,
                                java.lang.Object plane,
                                int x,
                                int y,
                                int w,
                                int h)
                         throws FormatException,
                                java.io.IOException

      Description copied from interface: `IFormatWriter`
      Saves the given image plane to the current series in the current file.
      Specified by:
        `savePlane` in interface `IFormatWriter`
      Parameters:
        `no` - the plane index within the series.
        `plane` - the image plane.
        `x` - the X coordinate of the upper-left corner of the image tile.
        `y` - the Y coordinate of the upper-left corner of the image tile.
        `w` - the width (in pixels) of the image tile.
        `h` - the height (in pixels) of the image tile.
      Throws:
        `FormatException` - if one of the parameters is invalid.
        `java.io.IOException` - if there was a problem writing to the file.

    - #### savePlane

          public void savePlane(int no,
                                java.lang.Object plane,
                                loci.common.Region tile)
                         throws FormatException,
                                java.io.IOException

      Description copied from interface: `IFormatWriter`
      Saves the given image plane to the current series in the current file.
      Specified by:
        `savePlane` in interface `IFormatWriter`
      Parameters:
        `no` - the plane index within the series.
        `plane` - the image plane.
        `tile` - the Region representing the image tile to be read.
      Throws:
        `FormatException` - if one of the parameters is invalid.
        `java.io.IOException` - if there was a problem writing to the file.

    - #### setSeries

          public void setSeries(int series)
                         throws FormatException

      Description copied from interface: `IFormatWriter`
      Sets the current series.
      Specified by:
        `setSeries` in interface `IFormatWriter`
      Parameters:
        `series` - the series index, starting from 0.
      Throws:
        `FormatException` - if the specified series is invalid.

    - #### getSeries

          public int getSeries()

      Description copied from interface: `IFormatWriter`
      Returns the current series.
      Specified by:
        `getSeries` in interface `IFormatWriter`

    - #### setInterleaved

          public void setInterleaved(boolean interleaved)

      Description copied from interface: `IFormatWriter`
      Sets whether or not the channels in an image are interleaved.
      Specified by:
        `setInterleaved` in interface `IFormatWriter`

    - #### isInterleaved

          public boolean isInterleaved()

      Description copied from interface: `IFormatWriter`
      Gets whether or not the channels in an image are interleaved.
      Specified by:
        `isInterleaved` in interface `IFormatWriter`

    - #### setValidBitsPerPixel

          public void setValidBitsPerPixel(int bits)

      Description copied from interface: `IFormatWriter`
      Sets the number of valid bits per pixel.
      Specified by:
        `setValidBitsPerPixel` in interface `IFormatWriter`

    - #### canDoStacks

          public boolean canDoStacks()

      Description copied from interface: `IFormatWriter`
      Reports whether the writer can save multiple images to a single file.
      Specified by:
        `canDoStacks` in interface `IFormatWriter`

    - #### setMetadataRetrieve

          public void setMetadataRetrieve(MetadataRetrieve r)

      Description copied from interface: `IFormatWriter`
      Sets the metadata retrieval object from which to retrieve standardized metadata.
      Specified by:
        `setMetadataRetrieve` in interface `IFormatWriter`

    - #### getMetadataRetrieve

          public MetadataRetrieve getMetadataRetrieve()

      Description copied from interface: `IFormatWriter`
      Retrieves the current metadata retrieval object for this writer. You can be assured that this method will never return a `null` metadata retrieval object.
      Specified by:
        `getMetadataRetrieve` in interface `IFormatWriter`
      Returns:
        A metadata retrieval object.

    - #### setColorModel

          public void setColorModel(java.awt.image.ColorModel cm)

      Description copied from interface: `IFormatWriter`
      Sets the color model.
      Specified by:
        `setColorModel` in interface `IFormatWriter`

    - #### getColorModel

          public java.awt.image.ColorModel getColorModel()

      Description copied from interface: `IFormatWriter`
      Gets the color model.
      Specified by:
        `getColorModel` in interface `IFormatWriter`

    - #### setFramesPerSecond

          public void setFramesPerSecond(int rate)

      Description copied from interface: `IFormatWriter`
      Sets the frames per second to use when writing.
      Specified by:
        `setFramesPerSecond` in interface `IFormatWriter`

    - #### getFramesPerSecond

          public int getFramesPerSecond()

      Description copied from interface: `IFormatWriter`
      Gets the frames per second to use when writing.
      Specified by:
        `getFramesPerSecond` in interface `IFormatWriter`

    - #### getCompressionTypes

          public java.lang.String[] getCompressionTypes()

      Description copied from interface: `IFormatWriter`
      Gets the available compression types.
      Specified by:
        `getCompressionTypes` in interface `IFormatWriter`

    - #### getPixelTypes

          public int[] getPixelTypes()

      Description copied from interface: `IFormatWriter`
      Gets the supported pixel types.
      Specified by:
        `getPixelTypes` in interface `IFormatWriter`

    - #### getPixelTypes

          public int[] getPixelTypes(java.lang.String codec)

      Description copied from interface: `IFormatWriter`
      Gets the supported pixel types for the given codec.
      Specified by:
        `getPixelTypes` in interface `IFormatWriter`

    - #### isSupportedType

          public boolean isSupportedType(int type)

      Description copied from interface: `IFormatWriter`
      Checks if the given pixel type is supported.
      Specified by:
        `isSupportedType` in interface `IFormatWriter`

    - #### setCompression

          public void setCompression(java.lang.String compress)
                              throws FormatException

      Description copied from interface: `IFormatWriter`
      Sets the current compression type.
      Specified by:
        `setCompression` in interface `IFormatWriter`
      Throws:
        `FormatException`

    - #### getCompression

          public java.lang.String getCompression()

      Description copied from interface: `IFormatWriter`
      Gets the current compression type.
      Specified by:
        `getCompression` in interface `IFormatWriter`

    - #### setWriteSequentially

          public void setWriteSequentially(boolean sequential)

      Description copied from interface: `IFormatWriter`
      Sets whether or not we know that planes will be written sequentially. If planes are written sequentially and this flag is set, then performance will be slightly improved.
      Specified by:
        `setWriteSequentially` in interface `IFormatWriter`

    - #### setCodecOptions

          public void setCodecOptions(CodecOptions options)

      Description copied from interface: `IFormatWriter`
      Sets the codec options.
      Specified by:
        `setCodecOptions` in interface `IFormatWriter`
      Parameters:
        `options` - The options to set.

    - #### saveCompressedBytes

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

      Description copied from interface: `ICompressedTileWriter`
      Save a compressed tile to the current output file. The compression type of the tile should match the compression type set in the writer.
      Specified by:
        `saveCompressedBytes` in interface `ICompressedTileWriter`
      Parameters:
        `no` - plane index
        `buf` - compressed tile bytes
        `x` - pixel X coordinate of the upper-left corner of the tile
        `y` - pixel Y coordinate of the upper-left corner of the tile
        `w` - width in pixels of the compressed tile
        `h` - height in pixels of the compressed tile
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### getCodec

          public Codec getCodec()

      Specified by:
        `getCodec` in interface `ICompressedTileWriter`
      Returns:
        the codec that can be used to compress tiles

    - #### getCodecOptions

          public CodecOptions getCodecOptions()

      Specified by:
        `getCodecOptions` in interface `ICompressedTileWriter`
      Returns:
        the codec options that can be used to compress tiles

    - #### isThisType

          public boolean isThisType(java.lang.String name)

      Description copied from interface: `IFormatHandler`
      Checks if the given string is a valid filename for this file format.
      Specified by:
        `isThisType` in interface `IFormatHandler`

    - #### getFormat

          public java.lang.String getFormat()

      Description copied from interface: `IFormatHandler`
      Gets the name of this file format.
      Specified by:
        `getFormat` in interface `IFormatHandler`

    - #### getSuffixes

          public java.lang.String[] getSuffixes()

      Description copied from interface: `IFormatHandler`
      Gets the default file suffixes for this file format.
      Specified by:
        `getSuffixes` in interface `IFormatHandler`

    - #### getNativeDataType

          public java.lang.Class<?> getNativeDataType()

      Description copied from interface: `IFormatHandler`
      Returns the native data type of image planes for this reader, as returned by `IFormatReader.openPlane(int, int, int, int, int)` or `IFormatWriter.savePlane(int, java.lang.Object)`. For most readers this type will be a byte array; however, some readers call external APIs that work with other types such as `BufferedImage`.
      Specified by:
        `getNativeDataType` in interface `IFormatHandler`

    - #### setId

          public void setId(java.lang.String id)
                     throws FormatException,
                            java.io.IOException

      Description copied from interface: `IFormatHandler`
      Sets the current file name.
      Specified by:
        `setId` in interface `IFormatHandler`
      Throws:
        `FormatException`
        `java.io.IOException`

    - #### close

          public void close()
                     throws java.io.IOException

      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Throws:
        `java.io.IOException`

    - #### getResolutionCount

          public int getResolutionCount()

      Description copied from interface: `IPyramidHandler`
      Return the number of resolutions for the current series. Resolutions are stored in descending order, so the largest resolution is first and the smallest resolution is last.
      Specified by:
        `getResolutionCount` in interface `IPyramidHandler`

    - #### getResolution

          public int getResolution()

      Description copied from interface: `IPyramidHandler`
      Get the current resolution level.
      Specified by:
        `getResolution` in interface `IPyramidHandler`
      See Also:
        `IPyramidHandler.getResolutionCount()`

    - #### setResolution

          public void setResolution(int resolution)

      Description copied from interface: `IPyramidHandler`
      Set the resolution level.
      Specified by:
        `setResolution` in interface `IPyramidHandler`
      See Also:
        `IPyramidHandler.getResolutionCount()`

Copyright © 2026 Open Microscopy Environment