loci.formats

## Class FormatWriter

- java.lang.Object
- - loci.formats.FormatHandler
  - - loci.formats.FormatWriter

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, ICompressedTileWriter, IFormatHandler, IFormatWriter, IMetadataConfigurable, IPyramidHandler
  Direct Known Subclasses:
    APNGWriter, AVIWriter, CellH5Writer, DicomWriter, EPSWriter, ICSWriter, ImageIOWriter, JavaWriter, JPEG2000Writer, OMEXMLWriter, QTWriter, TiffWriter, V3DrawWriter

      public abstract class FormatWriter
      extends FormatHandler
      implements IFormatWriter

  Abstract superclass of all biological file format writers.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.awt.image.ColorModel` | `cm` Default color model.
    `protected java.lang.String` | `compression` Current compression type.
    `protected java.lang.String[]` | `compressionTypes` Available compression types.
    `protected int` | `fps` Frame rate to use when writing in frames per second, if applicable.
    `protected boolean[][]` | `initialized` Whether each plane in each series of the current file has been prepped for writing.
    `protected boolean` | `interleaved` Whether the channels in an RGB image are interleaved.
    `protected MetadataRetrieve` | `metadataRetrieve` Current metadata retrieval object.
    `protected CodecOptions` | `options` The options if required.
    `protected loci.common.RandomAccessOutputStream` | `out` Current file.
    `protected int` | `resolution` Current pyramid resolution.
    `protected java.util.List<java.util.List<Resolution>>` | `resolutionData`
    `protected boolean` | `sequential` Whether or not we are writing planes sequentially.
    `protected int` | `series` Current series.
    `protected int` | `validBits` The number of valid bits per pixel.

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

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

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FormatWriter(java.lang.String format, java.lang.String suffix)` Constructs a format writer with the given name and default suffix.
    `FormatWriter(java.lang.String format, java.lang.String[] suffixes)` Constructs a format writer with the given name and default suffixes.

  - ### Method Summary

    All 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.
    `protected void` | `checkParams(int no, byte[] buf, int x, int y, int w, int h)` Ensure that the arguments that are being passed to saveBytes(...) are valid.
    `void` | `close()`
    `protected loci.common.RandomAccessOutputStream` | `createOutputStream()` Create an output stream for the current file path.
    `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.
    `int` | `getFramesPerSecond()` Gets the frames per second to use when writing.
    `MetadataRetrieve` | `getMetadataRetrieve()` Retrieves the current metadata retrieval object for this writer.
    `int[]` | `getPixelTypes()` Gets the supported pixel types.
    `int[]` | `getPixelTypes(java.lang.String codec)` Gets the supported pixel types for the given codec.
    `protected int` | `getPlaneCount()` Retrieve the total number of planes in the current series.
    `protected int` | `getPlaneCount(int series)` Retrieve the total number of planes in given series.
    `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.
    `protected int` | `getSamplesPerPixel()` Retrieve the number of samples per pixel for the current series.
    `protected int` | `getSamplesPerPixel(int series)` Retrieve the number of samples per pixel for given series.
    `int` | `getSeries()` Returns the current series.
    `protected int` | `getSizeX()`
    `protected int` | `getSizeY()`
    `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
    `protected boolean` | `hasResolutions()`
    `protected boolean` | `isFullPlane(int x, int y, int w, int h)` Returns true if the given rectangle coordinates correspond to a full image in the given series.
    `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.
    `void` | `saveBytes(int no, byte[] buf)` Saves the given image 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` | `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.
    `protected void` | `seekToPlaneOffset(long baseOffset, int x, int y)` Seek to the given (x, y) coordinate of the image that starts at the given offset.
    `void` | `setCodecOptions(CodecOptions options)` Sets the codec options.
    `void` | `setColorModel(java.awt.image.ColorModel model)` 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)` Initializes a writer from the input file name.
    `void` | `setInterleaved(boolean interleaved)` Sets whether or not the channels in an image are interleaved.
    `void` | `setMetadataRetrieve(MetadataRetrieve retrieve)` 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 loci.formats.FormatHandler

      `checkSuffix, checkSuffix, getFormat, getMetadataOptions, getNativeDataType, getSuffixes, getSupportedMetadataLevels, isThisType, 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.IFormatWriter

      `saveBytes`

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

      `getFormat, getNativeDataType, getSuffixes, isThisType`

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

      `getMetadataOptions, getSupportedMetadataLevels, setMetadataOptions`

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

      `getCodec, saveCompressedBytes`

- - ### Field Detail

    - #### fps

          protected int fps

      Frame rate to use when writing in frames per second, if applicable.

    - #### cm

          protected java.awt.image.ColorModel cm

      Default color model.

    - #### compressionTypes

          protected java.lang.String[] compressionTypes

      Available compression types.

    - #### compression

          protected java.lang.String compression

      Current compression type.

    - #### options

          protected CodecOptions options

      The options if required.

    - #### initialized

          protected boolean[][] initialized

      Whether each plane in each series of the current file has been prepped for writing.

    - #### interleaved

          protected boolean interleaved

      Whether the channels in an RGB image are interleaved.

    - #### validBits

          protected int validBits

      The number of valid bits per pixel.

    - #### series

          protected int series

      Current series.

    - #### sequential

          protected boolean sequential

      Whether or not we are writing planes sequentially.

    - #### metadataRetrieve

          protected MetadataRetrieve metadataRetrieve

      Current metadata retrieval object. Should never be accessed directly as the semantics of `getMetadataRetrieve()` prevent "null" access.

    - #### out

          protected loci.common.RandomAccessOutputStream out

      Current file.

    - #### resolution

          protected int resolution

      Current pyramid resolution.

    - #### resolutionData

          protected java.util.List<java.util.List<Resolution>> resolutionData

  - ### Constructor Detail

    - #### FormatWriter

          public FormatWriter(java.lang.String format,
                              java.lang.String suffix)

      Constructs a format writer with the given name and default suffix.

    - #### FormatWriter

          public FormatWriter(java.lang.String format,
                              java.lang.String[] suffixes)

      Constructs a format writer with the given name and default suffixes.

  - ### Method Detail

    - #### 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,
                                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 retrieve)

      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 model)

      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`

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

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

    - #### getCodecOptions

          public CodecOptions getCodecOptions()

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

    - #### getCompression

          public java.lang.String getCompression()

      Description copied from interface: `IFormatWriter`
      Gets the current compression type.
      Specified by:
        `getCompression` 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`

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

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

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

    - #### setId

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

      Initializes a writer from the input file name. Initializes a `RandomAccessOutputStream` for the output file and initializes the metadata for all the series using `setSeries(int)`.
      Specified by:
        `setId` in interface `IFormatHandler`
      Parameters:
        `id` - a `String` specifying the path to the file
      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`

    - #### checkParams

          protected void checkParams(int no,
                                     byte[] buf,
                                     int x,
                                     int y,
                                     int w,
                                     int h)
                              throws FormatException

      Ensure that the arguments that are being passed to saveBytes(...) are valid.
      Throws:
        `FormatException` - if any of the arguments is invalid.

    - #### seekToPlaneOffset

          protected void seekToPlaneOffset(long baseOffset,
                                           int x,
                                           int y)
                                    throws java.io.IOException

      Seek to the given (x, y) coordinate of the image that starts at the given offset.
      Throws:
        `java.io.IOException`

    - #### isFullPlane

          protected boolean isFullPlane(int x,
                                        int y,
                                        int w,
                                        int h)
                                 throws FormatException

      Returns true if the given rectangle coordinates correspond to a full image in the given series.
      Throws:
        `FormatException`

    - #### getSamplesPerPixel

          protected int getSamplesPerPixel()

      Retrieve the number of samples per pixel for the current series.

    - #### getSamplesPerPixel

          protected int getSamplesPerPixel(int series)

      Retrieve the number of samples per pixel for given series.

    - #### getPlaneCount

          protected int getPlaneCount()

      Retrieve the total number of planes in the current series.

    - #### getPlaneCount

          protected int getPlaneCount(int series)

      Retrieve the total number of planes in given series.

    - #### createOutputStream

          protected loci.common.RandomAccessOutputStream createOutputStream()
                                                                     throws java.io.IOException

      Create an output stream for the current file path. If the file path's parent directory does not exist, it will be created.
      Returns:
        an open RandomAccessOuputStream for the current file
      Throws:
        `java.io.IOException` - if the directory or output stream creation fails

    - #### getSizeX

          protected int getSizeX()
                          throws FormatException

      Throws:
        `FormatException`

    - #### getSizeY

          protected int getSizeY()
                          throws FormatException

      Throws:
        `FormatException`

    - #### hasResolutions

          protected boolean hasResolutions()

Copyright © 2026 Open Microscopy Environment