loci.formats

Class FormatWriter

java.lang.Object

loci.formats.FormatHandler

loci.formats.FormatWriter

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, IFormatHandler, IFormatWriter, IMetadataConfigurable, IPyramidHandler

Direct Known Subclasses:

APNGWriter, AVIWriter, CellH5Writer, EPSWriter, ICSWriter, ImageIOWriter, JavaWriter, JPEG2000Writer, LegacyQTWriter, OMEXMLWriter, QTWriter, TiffWriter, V3DrawWriter, WlzWriter

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

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

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 image index within the current file, starting from 0.

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 image index within the current file, starting from 0.

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 image index within the current file, starting from 0.

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 image index within the current file, starting from 0.

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 image index within the current file, starting from 0.

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.

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