Static
XImageIO
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
Object
public final class XImageIO
Extensions to the set of static methods provided in the standard ImageIO class.
The methods defined in this XImageIO class fetch an ImageReader or an
ImageWriter for a given input, output, suffix, format name or mime type. They
are equivalent in purpose to the methods defined in ImageIO except that:
ImageReader or ImageWriter instead than an iterator.IIOException if no reader or writer is found.For example, the standard Java API provides the following method:
while this class provides the following equivalent API:ImageIO.getImageReadersBySuffix(String)withsuffixargument
getReaderBySuffix(String, Object, Boolean, Boolean)withsuffix,input,seekForwardOnlyandignoreMetadataarguments.
Note: WhyXImageIOmethods expect an optional input argument: The standardImageIOmethods do not take input argument because the Java Image I/O framework expects everyImageReaders to accept anImageInputStream. Actually,ImageIOcreates image input streams unconditionally, without checking whatever it was necessary or not.However, some plugins used by the Geotk library can not work with streams. Some plugins (e.g. the HDF format) open the file in native C/C++ code. Those libraries can not work with Java streams - they require a plain filename. Even in pure Java code, sometime a filename or URL is required. For example the Geotk
WorldFileImageReaderneeds to open many files for the same image. Consequently if the user wants to read an image from aFile, it is preferable to check if anImageReaderaccepts directly suchFileinput before to create anImageInputStream.
How the input/output is defined in the returned reader/writer
The ImageReader and ImageWriter returned by the methods in this class will have
their input or output set. This is different than the standard ImageIO API (which returns
uninitialized readers or writers) and is done that way because the input or output may be different
than the one specified by the caller if it was necessary to create an ImageInputStream or
ImageOutputStream. If such stream has been created, then it is the caller responsibility
to close it after usage. The close(ImageReader) and close(ImageWriter)
convenience methods can be used for this purpose.
The output in the returned image writer is defined by a call to the
ImageWriter.setOutput(Object) method. The input in the returned
image reader is defined by a call to the ImageReader.setInput(Object),
setInput(Object, boolean) or
setInput(Object, boolean, boolean)
method depending on whatever the seekForwardOnly and ignoreMetadata arguments
are non-null or not. For example if those two Boolean arguments are null, then the
setInput(Object) flavor is invoked. This is usually equivalent to setting the two
boolean argument to false, but this behavior could have been overridden by the plugin.
Example
The following example reads a TIFF image. Because we use an input of type File
instead than ImageInputStream, the WorldFileImageReader can be used.
Consequently the metadata associated with the TIFF image can contain geolocalization
information if a ".tfw" file was found together with the ".tiff" file.
File input = new File("my_image.tiff");
ImageReader reader = XImageIO.getReaderBySuffix(input, true, false);
IIOMetadata metadata = reader.getImageMetadata(0);
BufferedImage image = reader.read(0);
XImageIO.close(reader);
reader.dispose();
Mandatory and optional arguments
Every methods defined in this class expect exactly one mandatory argument, which is always
the first argument. All other arguments are optional and can be null.
| coverage/geotk-coverageio (download) | View source code for this class |
| Method Summary | |
|---|---|
static void |
close(ImageReader reader)
Closes the input stream of the given reader, and sets the input to null. |
static void |
close(ImageWriter writer)
Closes the output stream of the given writer, and sets the output to null. |
static String[] |
getFormatNamesByMimeType(String mime,
boolean read,
boolean write)
Returns the format names of all ImageReaderSpi and/or ImageWriterSpi
instances registered for the given MIME type. |
static ImageReader |
getReader(Object input,
Boolean seekForwardOnly,
Boolean ignoreMetadata)
Creates a new reader for the given input. |
static ImageReader |
getReaderByFormatName(String name,
Object input,
Boolean seekForwardOnly,
Boolean ignoreMetadata)
Creates a new reader for the given optional input, considering only the readers of the given format name. |
static ImageReader |
getReaderByMIMEType(String mime,
Object input,
Boolean seekForwardOnly,
Boolean ignoreMetadata)
Creates a new reader for the given optional input, considering only the readers for the given MIME type. |
static ImageReader |
getReaderBySuffix(Object input,
Boolean seekForwardOnly,
Boolean ignoreMetadata)
Creates a new reader for the given input, considering only the readers that claim to decode files having the suffix found in the input. |
static ImageReader |
getReaderBySuffix(String suffix,
Object input,
Boolean seekForwardOnly,
Boolean ignoreMetadata)
Creates a new reader for the given optional input, considering only the readers that claim to decode files having the given suffix. |
static ImageReaderSpi |
getReaderSpiByFormatName(String format)
Returns the image reader provider for the given format name. |
static ImageWriter |
getWriterByFormatName(String name,
Object output,
RenderedImage image)
Creates a new writer for the given output, considering only the writers of the given format name. |
static ImageWriter |
getWriterByMIMEType(String mime,
Object output,
RenderedImage image)
Creates a new writer for the given output, considering only the writers for the given MIME type. |
static ImageWriter |
getWriterBySuffix(Object output,
RenderedImage image)
Creates a new writer for the given output, considering only the writers that claim to encode files having the suffix of the given output. |
static ImageWriter |
getWriterBySuffix(String suffix,
Object output,
RenderedImage image)
Creates a new writer for the given output, considering only the writers that claim to encode files having the given suffix. |
static ImageWriterSpi |
getWriterSpiByFormatName(String format)
Returns the image writer provider for the given format name. |
| Methods inherited from class Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Method Detail |
|---|
public static ImageReader getReader(Object input,
Boolean seekForwardOnly,
Boolean ignoreMetadata)
throws IOException
input argument is mandatory and will be
used for initializing the reader by a call to one of the ImageReader.setInput(Object)
methods. The method invoked depends on whatever the seekForwardOnly and
ignoreMetadata parameters are null or non-null.
input - The mandatory input to be given to the new reader instance.seekForwardOnly - Optional parameter to be given (if non-null) to the
setInput method: if true,
images and metadata may only be read in ascending order from the input source.
If false, they may be read in any order. If null, this parameter
is not given to the reader which is free to use a plugin-dependent default
(usually false).ignoreMetadata - Optional parameter to be given (if non-null) to the
setInput method:
if true, metadata may be ignored during reads. If false, metadata
will be parsed. If null, this parameter is not given to the reader which
is free to use a plugin-dependent default (usually false).
IOException - If no suitable image reader has been found, or if an error occurred
while creating it.ImageIO.getImageReaders(Object)
public static ImageReader getReaderBySuffix(Object input,
Boolean seekForwardOnly,
Boolean ignoreMetadata)
throws IOException
input argument is mandatory and will
be used for initializing the reader as documented in the getReader(...)
method.
If this method doesn't know how to get the suffix from the given input (for example
if the input is an instance of ImageInputStream), then this method delegates
to getReader(Object, Boolean, Boolean).
input - The mandatory input to be given to the new reader instance.seekForwardOnly - Optional parameter to be given (if non-null) to the
setInput method.ignoreMetadata - Optional parameter to be given (if non-null) to the
setInput method.
IOException - If no suitable image reader has been found, or if an error occurred
while creating it.ImageIO.getImageReadersBySuffix(String)
public static ImageReader getReaderBySuffix(String suffix,
Object input,
Boolean seekForwardOnly,
Boolean ignoreMetadata)
throws IOException
suffix argument is mandatory. The
other ones are optional and will be used (if non-null) for initializing the reader as
documented in the getReader(...) method.
suffix - The file suffix for which we want a reader.input - An optional input to be given to the new reader instance, or null if none.seekForwardOnly - Optional parameter to be given (if non-null) to the
setInput method.ignoreMetadata - Optional parameter to be given (if non-null) to the
setInput method.
input is not null).
IOException - If no suitable image reader has been found, or if an error occurred
while creating it.ImageIO.getImageReadersBySuffix(String)
public static ImageReader getReaderByFormatName(String name,
Object input,
Boolean seekForwardOnly,
Boolean ignoreMetadata)
throws IOException
name argument is mandatory. The other ones are optional and
will be used (if non-null) for initializing the reader as documented in the
getReader(...) method.
name - The name of the format looked for.input - An optional input to be given to the new reader instance, or null if none.seekForwardOnly - Optional parameter to be given (if non-null) to the
setInput method.ignoreMetadata - Optional parameter to be given (if non-null) to the
setInput method.
input is not null).
IOException - If no suitable image reader has been found, or if an error occurred
while creating it.ImageIO.getImageReadersByFormatName(String)
public static ImageReader getReaderByMIMEType(String mime,
Object input,
Boolean seekForwardOnly,
Boolean ignoreMetadata)
throws IOException
mime argument is mandatory. The other ones are optional
and will be used (if non-null) for initializing the reader as documented in the
getReader(...) method.
mime - The MIME type of the format looked for.input - An optional input to be given to the new reader instance, or null if none.seekForwardOnly - Optional parameter to be given (if non-null) to the
setInput method.ignoreMetadata - Optional parameter to be given (if non-null) to the
setInput method.
input is not null).
IOException - If no suitable image reader has been found, or if an error occurred
while creating it.ImageIO.getImageReadersByMIMEType(String)
public static void close(ImageReader reader)
throws IOException
null.
reader - The reader for which to close the input stream.
IOException - If an error occurred while closing the stream.
public static ImageWriter getWriterBySuffix(Object output,
RenderedImage image)
throws IOException
setOutput method.
output - A mandatory output to be given to the new writer instance.image - The image to encode, or null if unknown.
IOException - If no suitable image writer has been found, or if an error occurred
while creating it.ImageIO.getImageWritersBySuffix(String)
public static ImageWriter getWriterBySuffix(String suffix,
Object output,
RenderedImage image)
throws IOException
setOutput method.
suffix - The file suffix for which we want a writer.output - An optional output to be given to the new writer instance, or null if none.image - The image to encode, or null if unknown.
output is not null).
IOException - If no suitable image writer has been found, or if an error occurred
while creating it.ImageIO.getImageWritersBySuffix(String)
public static ImageWriter getWriterByFormatName(String name,
Object output,
RenderedImage image)
throws IOException
setOutput
method.
name - The format name for which we want a writer.output - An optional output to be given to the new writer instance, or null if none.image - The image to encode, or null if unknown.
output is not null).
IOException - If no suitable image writer has been found, or if an error occurred
while creating it.ImageIO.getImageWritersByFormatName(String)
public static ImageWriter getWriterByMIMEType(String mime,
Object output,
RenderedImage image)
throws IOException
setOutput
method.
mime - The MIME type for which we want a writer.output - An optional output to be given to the new writer instance, or null if none.image - The image to encode, or null if unknown.
output is not null).
IOException - If no suitable image writer has been found, or if an error occurred
while creating it.ImageIO.getImageWritersByMIMEType(String)
public static void close(ImageWriter writer)
throws IOException
null.
writer - The writer for which to close the output stream.
IOException - If an error occurred while closing the stream.public static ImageReaderSpi getReaderSpiByFormatName(String format)
format - The name of the provider to fetch.
IllegalArgumentException - If no provider is found for the given format.public static ImageWriterSpi getWriterSpiByFormatName(String format)
format - The name of the provider to fetch.
IllegalArgumentException - If no provider is found for the given format.
public static String[] getFormatNamesByMimeType(String mime,
boolean read,
boolean write)
ImageReaderSpi and/or ImageWriterSpi
instances registered for the given MIME type. If there is many format names for the
same MIME type, then the most frequently used names will be sorted first.
mime - The MIME type to search for.read - true if the format name is required to be supported by at least one ImageReader.write - true if the format name is required to be supported by at least one ImageWriter.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||