Class ImageCodec
- Direct Known Subclasses:
BMPCodec
,GIFCodec
,IFFCodec
,JPEGCodec
,PalmCodec
,PCDCodec
,PNGCodec
,PNMCodec
,PSDCodec
,RASCodec
,TIFFCodec
Usage
The codecs differ quite a bit in what they support. But here are two code snippets that demonstrate how to do loading and saving in general.Load image
ImageCodec codec = new BMPCodec(); // BMPCodec is just an example codec.setFile("image.bmp", CodecMode.LOAD); codec.process(); PixelImage image = codec.getImage();
Save image
PixelImage image = ...; // the image to be saved ImageCodec codec = new BMPCodec(); // BMPCodec is just an example codec.setFile("image.bmp", CodecMode.SAVE); codec.setImage(image); codec.process();
I/O objects
There are several set and get methods for I/O objects, including DataInput, DataOutput, InputStream, OutputStream and RandomAccessFile. If you are just using the codec (and not developing one) make it easier for yourself and usesetFile(String, CodecMode)
.
That way the picking of the right type of I/O class and the creation of a
buffered stream wrapper is done automatically.
Codecs have different requirements concerning I/O objects.
If an image is to be loaded, it's enough for some formats to linearly read
from an InputStream
to load the image.
However, some formats (like TIFF) require random access.
When implementing a codec, take care that as many I/O classes as possible can be used.
If possible, call getInputAsDataInput()
when loading and getOutputAsDataOutput()
when saving.
That way, input / output streams, RandomAccessFiles and arbitrary DataInput / DataOutput objects
can be used.
Mode
Codecs can be used to save images or load them, or both. As was g; by default, no mode (of enumeration typeCodecMode
)
is specified and getMode()
returns null
.
Mode only has two possible values, CodecMode.LOAD
and
CodecMode.SAVE
.
In some cases, the codec can find out whether to load or save from the I/O objects
that were given to it; if it has an input stream, something must be loaded,
if it has an output stream, something is to be saved.
If a codec demands a RandomAccessFile
, there is no way to find out
the mode automatically, that is why setRandomAccessFile(java.io.RandomAccessFile, net.sourceforge.jiu.codecs.CodecMode)
also has an
argument of type CodecMode
.
Bounds; to load or save only part of an image.
Defining bounds is optional; by default, the complete image is loaded
or saved (no bounds).
Using setBounds(int, int, int, int)
, one can specify the
rectangle which will be loaded or saved.
PixelImage object; get and set methods for the image which is to be loaded or saved. If an image is to be loaded, a PixelImage object can optionally be specified so that the image will be written to that object; image type and resolution must of course match the image from input. Normally, the codec will create the appropriate image object itself. If an image is to be saved, an image object must be provided, otherwise there is nothing to do.
Image index; the index of the image that is to be loaded (int value, default
is 0). For image formats that support more than one image in one stream, the index of the
image to be loaded (zero-based) can be specified using setImageIndex(int)
.
Textual comments
Some file formats allow for the inclusion of textual comments, to store a description, creator, copyright owner or anything else within the image file without actually drawing that text on the image itself. Some codecs support reading and writing of comments.Other methods
Each file format must be able to return its name (getFormatName()
) and
file extensions that are typical for it (getFileExtensions()
).
A related method suggests a file extension for a given PixelImage object (suggestFileExtension(PixelImage)
).
That method need not be implemented, the default version returns simply null
.
However, it is encouraged that codec implementors provide this method as well.
Most file formats only have one typical extension (e. g. .bmp
).
However, for a file format like PNM, the extension depends on the image type (a grayscale
image would end in .pgm
, a color image in .ppm
).
- Author:
- Marco Schmidt
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate boolean
private int
private int
private int
private int
private int
private int
private Vector
private DataInput
private DataOutput
private int
private int
private PixelImage
private int
private InputStream
private CodecMode
private OutputStream
private RandomAccessFile
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
appendComment
(String comment) Appends a comment to the internal list of comments.void
checkBounds
(int width, int height) If bounds were defined for this codec, this method tests if the bounds rectangle fits into the rectangle(0, 0) / (width - 1, height - 1)
.void
If an image object was provided to be used for loading viasetImage(net.sourceforge.jiu.data.PixelImage)
, this method checks if its resolution is the same as the bounds' resolution.void
close()
Calls the close method of all input and output I/O objects that were given to this object.int
Returns the height of the rectangle specified by bounds.int
Returns the width of the rectangle specified by bounds.int
Returns x coordinate of the upper left corner of the bounds.int
Returns x coordinate of the lower right corner of the bounds.int
Returns y coordinate of the upper left corner of the bounds.int
Returns y coordinate of the lower right corner of the bounds.getComment
(int index) Returns a comment from the internal list of comments.int
getDpiX()
Returns the horizontal physical resolution of the image associated with this codec.int
getDpiY()
Returns the vertical physical resolution of the image associated with this codec.String[]
Returns all file extensions that are typical for this file format.abstract String
Returns the name of the file format supported by this codec.getImage()
Returns the image object stored in this codec.int
Returns the zero-based index of the image to be loaded.Returns aDataInput
object if one was specified usingsetDataInput(DataInput)
, or creates aDataInputStream
if anInputStream
was specified, or returns aRandomAccessFile
if one was specified (RandomAccessFile implements DataInput).Returns anInputStream
object that was given to this codec viasetInputStream(InputStream)
(ornull
otherwise).abstract String[]
Return the MIME (Multipurpose Internet Mail Extensions) type strings for this format, ornull
if none are available.getMode()
Returns the mode this codec is in.int
Returns the current number of comments in the internal comment list.Attempts to return an output object as aDataOutput
object.Returns anOutputStream
object that was given to this codec viasetOutputStream(OutputStream)
(ornull
otherwise).Returns aRandomAccessFile
object that was given to this codec viasetRandomAccessFile(RandomAccessFile, CodecMode)
(ornull
otherwise).boolean
Returns if bounds have been specified.protected void
abstract boolean
Returns if this codec is able to load images in the file format supported by this codec.boolean
isRowRequired
(int row) Returns if an image row given by its number (zero-based) must be loaded in the context of the current bounds.abstract boolean
Returns if this codec is able to save images in the file format supported by this codec.boolean
isTileRequired
(int x1, int y1, int x2, int y2) Returns if the tile formed by the argument coordinates form a rectangle that overlaps with the bounds.void
Removes all entries from the internal list of comments.void
If bounds were set usingsetBounds(int, int, int, int)
, these bounds are no longer regarded after the call to this method.void
setBounds
(int x1, int y1, int x2, int y2) Sets the bounds of a rectangular part of the image that is to be loaded or saved, instead of the complete image.void
setBoundsIfNecessary
(int width, int height) If no bounds have been set (hasBounds()
returnsfalse
), this method will set the bounds to0, 0, width - 1, height - 1
.void
setDataInput
(DataInput dataInput) Specifies a DataInput object to be used for loading.void
setDataOutput
(DataOutput dataOutput) Sets aDataOutput
object to be used for saving an image.void
setDpi
(int horizontalDpi, int verticalDpi) Sets the DPI values to be stored in the file to the argument values.void
Gives a File object and a codec mode to this codec and attempts to initialize the appropriate I/O objects.void
Gives a file name and codec mode to the codec which will then try to create the corresponding I/O object.void
setImage
(PixelImage img) Give an image to this codec to be used for loading an image into it or saving the image.void
setImageIndex
(int index) Sets the index of the image to be loaded to the argument value (which must be zero or larger).void
setInputStream
(InputStream inputStream) AnInputStream
can be given to this codec using this method.void
setOutputStream
(OutputStream outputStream) A method to give anOutputStream
to this codec to be used for saving an image.void
setRandomAccessFile
(RandomAccessFile randomAccessFile, CodecMode codecMode) A method to give aRandomAccessFile
to this codec to be used for loading or saving an image.suggestFileExtension
(PixelImage image) Attempts to suggest a filename extension.Methods inherited from class net.sourceforge.jiu.ops.Operation
addProgressListener, addProgressListeners, getAbort, process, removeProgressListener, setAbort, setProgress, setProgress
-
Field Details
-
boundsX1
private int boundsX1 -
boundsY1
private int boundsY1 -
boundsX2
private int boundsX2 -
boundsY2
private int boundsY2 -
boundsAvail
private boolean boundsAvail -
boundsWidth
private int boundsWidth -
boundsHeight
private int boundsHeight -
comments
-
dpiX
private int dpiX -
dpiY
private int dpiY -
din
-
dout
-
image
-
imageIndex
private int imageIndex -
in
-
mode
-
out
-
raf
-
-
Constructor Details
-
ImageCodec
public ImageCodec()This constructor will be called by descendants. The bounds state is initialized to no bounds.
-
-
Method Details
-
appendComment
Appends a comment to the internal list of comments. If the argument comment is non-null, it will be added to the internal list of comment strings.- Parameters:
comment
- the comment to be added
-
checkBounds
If bounds were defined for this codec, this method tests if the bounds rectangle fits into the rectangle(0, 0) / (width - 1, height - 1)
. If the bounds are incorrect, aWrongParameterException
is thrown, otherwise nothing happens. To be used within codecs that support the bounds concept.- Throws:
WrongParameterException
-
checkImageResolution
If an image object was provided to be used for loading viasetImage(net.sourceforge.jiu.data.PixelImage)
, this method checks if its resolution is the same as the bounds' resolution. If the two differ, aWrongParameterException
is thrown.- Throws:
WrongParameterException
- if image resolution and bounds dimension differ
-
close
public void close()Calls the close method of all input and output I/O objects that were given to this object. Catches and ignores any IOException objects that may be thrown in the process. Note that not all I/O objects have a close method (e.g.DataInput
andDataOutput
have not). -
getBoundsX1
public int getBoundsX1()Returns x coordinate of the upper left corner of the bounds. Bounds must have been specified usingsetBounds(int, int, int, int)
, otherwise the return value is undefined.- Returns:
- x coordinate of the upper left corner of the bounds
-
getBoundsX2
public int getBoundsX2()Returns x coordinate of the lower right corner of the bounds. Bounds must have been specified usingsetBounds(int, int, int, int)
, otherwise the return value is undefined.- Returns:
- x coordinate of the lower right corner of the bounds
-
getBoundsY1
public int getBoundsY1()Returns y coordinate of the upper left corner of the bounds. Bounds must have been specified usingsetBounds(int, int, int, int)
, otherwise the return value is undefined.- Returns:
- y coordinate of the upper left corner of the bounds
-
getBoundsY2
public int getBoundsY2()Returns y coordinate of the lower right corner of the bounds. Bounds must have been specified usingsetBounds(int, int, int, int)
, otherwise the return value is undefined.- Returns:
- y coordinate of the lower right corner of the bounds
-
getBoundsHeight
public int getBoundsHeight()Returns the height of the rectangle specified by bounds. Bounds must have been specified usingsetBounds(int, int, int, int)
, otherwise the return value is undefined. This equalsgetBoundsY2()
-getBoundsY1()
+ 1.- Returns:
- height of bounds rectangle
-
getBoundsWidth
public int getBoundsWidth()Returns the width of the rectangle specified by bounds. Bounds must have been specified usingsetBounds(int, int, int, int)
, otherwise the return value is undefined. This equalsgetBoundsX2()
-getBoundsX1()
+ 1.- Returns:
- width of bounds rectangle
-
getComment
Returns a comment from the internal list of comments.- Parameters:
index
- the index of the comment to be returned, must be from0
togetNumComments()
- 1
; if this is not the case,null
will be returned- See Also:
-
getDataInput
- Returns:
- the DataInput object
-
getDataOutput
- Returns:
- the DataInput object
-
getDpiX
public int getDpiX()Returns the horizontal physical resolution of the image associated with this codec. This resolution value was either retrieved from an image file or set viasetDpi(int, int)
.- Returns:
- horizontal physical resolution in dpi
- See Also:
-
getDpiY
public int getDpiY()Returns the vertical physical resolution of the image associated with this codec. This resolution value was either retrieved from an image file or set viasetDpi(int, int)
.- Returns:
- horizontal physical resolution in dpi
- See Also:
-
getFileExtensions
Returns all file extensions that are typical for this file format. The default implementation in ImageCodec returnsnull
. The file extension strings should include a leading dot and are supposed to be lower case (if that is allowed for the given file format). Example:{".jpg", ".jpeg"}
for the JPEG file format.- Returns:
- String array with typical file extensions
-
getFormatName
Returns the name of the file format supported by this codec. All classes extendingImageCodec
must override this method. When overriding, leave out any words in a particular language so that this format name can be understood by everyone. Usually it is enough to return the format creator plus a typical abbreviation, e.g.Microsoft BMP
orPortable Anymap (PNM)
.- Returns:
- name of the file format supported by this codec
-
getImage
Returns the image object stored in this codec. This is either an image given to this object viasetImage(PixelImage)
or it was created by the codec itself during a loading operation.- Returns:
- PixelImage object stored in this codec
-
getImageIndex
public int getImageIndex()Returns the zero-based index of the image to be loaded. Default is zero.- Returns:
- zero-based image index value
-
getInputAsDataInput
Returns aDataInput
object if one was specified usingsetDataInput(DataInput)
, or creates aDataInputStream
if anInputStream
was specified, or returns aRandomAccessFile
if one was specified (RandomAccessFile implements DataInput). If neither of those has been given to this object,null
is returned.- Returns:
- DataInput object or
null
-
getInputStream
Returns anInputStream
object that was given to this codec viasetInputStream(InputStream)
(ornull
otherwise).- Returns:
- InputStream object
-
getMimeTypes
Return the MIME (Multipurpose Internet Mail Extensions) type strings for this format, ornull
if none are available.- Returns:
- MIME type strings or null
-
getMode
Returns the mode this codec is in. Can benull
, so that the codec will have to find out itself what to do.- Returns:
- codec mode (load or save)
-
getNumComments
public int getNumComments()Returns the current number of comments in the internal comment list.- Returns:
- number of comments in the internal comment list
-
getOutputAsDataOutput
Attempts to return an output object as aDataOutput
object.- Returns:
- a DataOutput object or null if that was not possible
-
getOutputStream
Returns anOutputStream
object that was given to this codec viasetOutputStream(OutputStream)
(ornull
otherwise).- Returns:
- OutputStream object
-
getRandomAccessFile
Returns aRandomAccessFile
object that was given to this codec viasetRandomAccessFile(RandomAccessFile, CodecMode)
(ornull
otherwise).- Returns:
- RandomAccessFile object
-
hasBounds
public boolean hasBounds()Returns if bounds have been specified.- Returns:
- if bounds have been specified
- See Also:
-
initModeFromIOObjects
- Throws:
MissingParameterException
-
isLoadingSupported
public abstract boolean isLoadingSupported()Returns if this codec is able to load images in the file format supported by this codec. Iftrue
is returned this does not necessarily mean that all files in this format can be read, but at least some.- Returns:
- if loading is supported
-
isSavingSupported
public abstract boolean isSavingSupported()Returns if this codec is able to save images in the file format supported by this codec. Iftrue
is returned this does not necessarily mean that all types files in this format can be written, but at least some.- Returns:
- if saving is supported
-
isRowRequired
public boolean isRowRequired(int row) Returns if an image row given by its number (zero-based) must be loaded in the context of the current bounds.Example: if vertical bounds have been set to 34 and 37, image rows 34 to 37 as arguments to this method would result in
true
, anything else (e.g. 12 or 45) would result infalse
.- Parameters:
row
- the number of the row to be checked- Returns:
- if row must be loaded, regarding the current bounds
-
isTileRequired
public boolean isTileRequired(int x1, int y1, int x2, int y2) Returns if the tile formed by the argument coordinates form a rectangle that overlaps with the bounds. If no bounds were defined, returnstrue
.- Parameters:
x1
-y1
-x2
-y2
-- Returns:
- if the argument tile is required
-
removeAllComments
public void removeAllComments()Removes all entries from the internal list of comments. -
removeBounds
public void removeBounds()If bounds were set usingsetBounds(int, int, int, int)
, these bounds are no longer regarded after the call to this method. -
setBounds
public void setBounds(int x1, int y1, int x2, int y2) Sets the bounds of a rectangular part of the image that is to be loaded or saved, instead of the complete image. -
setBoundsIfNecessary
public void setBoundsIfNecessary(int width, int height) If no bounds have been set (hasBounds()
returnsfalse
), this method will set the bounds to0, 0, width - 1, height - 1
. By calling this method somewhere in the codec, no distinction has to be made for the two cases bounds have been defined and bounds have not been defined.- Parameters:
width
- width of the image to be loaded or savedheight
- height of the image to be loaded or saved
-
setDataInput
Specifies a DataInput object to be used for loading.- Parameters:
dataInput
- DataInput object to be used for loading an image
-
setDataOutput
Sets aDataOutput
object to be used for saving an image.- Parameters:
dataOutput
- the object to be used for output
-
setDpi
public void setDpi(int horizontalDpi, int verticalDpi) Sets the DPI values to be stored in the file to the argument values. -
setFile
public void setFile(File file, CodecMode codecMode) throws IOException, UnsupportedCodecModeException Gives a File object and a codec mode to this codec and attempts to initialize the appropriate I/O objects. Simply callssetFile(String, CodecMode)
with the absolute path of the File object.- Parameters:
file
- File object for the file to be usedcodecMode
- defines whether an image is to be loaded from or saved to the file- Throws:
IOException
UnsupportedCodecModeException
-
setFile
public void setFile(String fileName, CodecMode codecMode) throws IOException, UnsupportedCodecModeException Gives a file name and codec mode to the codec which will then try to create the corresponding I/O object. The default implementation in ImageCodec creates a DataInputStream object wrapped around a BufferedInputStream wrapped around a FileInputStream for CodecMode.LOAD. Similar for CodecMode.SAVE: a DataOutputStream around a BufferedOutputStream object around a FileOutputStream object. Codecs that need different I/O objects must override this method (some codecs may need random access and thus require a RandomAccessFile object).- Parameters:
fileName
- name of the file to be used for loading or savingcodecMode
- defines whether file is to be used for loading or saving- Throws:
IOException
UnsupportedCodecModeException
-
setImage
Give an image to this codec to be used for loading an image into it or saving the image.- Parameters:
img
- image object to save or to load data into
-
setImageIndex
public void setImageIndex(int index) Sets the index of the image to be loaded to the argument value (which must be zero or larger).- Parameters:
index
- int index value (zero-based) of the image to be loaded- Throws:
IllegalArgumentException
- if the argument is negative
-
setInputStream
AnInputStream
can be given to this codec using this method.- Parameters:
inputStream
- InputStream object to read from
-
setOutputStream
A method to give anOutputStream
to this codec to be used for saving an image.- Parameters:
outputStream
- the output stream to be used by this codec
-
setRandomAccessFile
A method to give aRandomAccessFile
to this codec to be used for loading or saving an image. It is not possible to determine from a RandomAccessFile object whether it was opened in read-only or read-and-write mode. To let the codec know whether the object is to be used for loading or saving the second argument is of type CodecMode.- Parameters:
randomAccessFile
- the file to be used for loading or savingcodecMode
- tells the codec whether the file is to be used for loading or saving
-
suggestFileExtension
Attempts to suggest a filename extension. The type of the argument image will be taken into consideration, although this will be necessary for some file formats only (as an example, PNM has different extensions for different image types, seePNMCodec
). This default implementation always returnsnull
.- Parameters:
image
- the image that is to be written to a file- Returns:
- the file extension, including a leading dot, or
null
if no file extension can be recommended
-