mediautil.image.jpeg
Class LLJTran

java.lang.Object
  extended by mediautil.gen.BasicIo
      extended by mediautil.image.jpeg.BasicJpegIo
          extended by mediautil.image.jpeg.LLJTran
All Implemented Interfaces:
IterativeReader, IterativeWriter
Direct Known Subclasses:
BasicJpeg

public class LLJTran
extends BasicJpegIo
implements IterativeReader, IterativeWriter

LLJTran is a class for Lossless Jpeg Transformation.

With the help of Supporting classes like Exif it can also be used to change Image Header Information (Exif header) like Date, Thumbnail, Orientation etc.

Following are the key features:


Field Summary
static int COMMENT
          Identifies the comment transformation.
static int CROP
          Identifies the crop transformation
static byte[] dummyExifHeader
          This array contains the data for a Dummy Exif Header.
static int FLIP_H
          Identifies the Horizontal Flip transformation
static int FLIP_V
          Identifies the Vertical Flip transformation
static String FPXR
          Name of the FPXR format
static int IMPERFECT_X
          Flag which specifies that the image width or x coordinate of the crop origin is not okay for a perfect transform.
static int IMPERFECT_Y
          Flag which specifies that the image height or y coordinate of the crop origin is not okay for a perfect transform.
static String JFIF
          Name of the JFIF format
static String JPEG
          Name of the JPEG format
static int NONE
          Identifies the identity transformation or no transformation
static int OPT_DEFAULTS
          Flag containing defaults for convenience.
static int OPT_WRITE_ALL
          Flag containing all OPT_WRITE_XXX flags except OPT_WRITE_OPTIMIZE_HUFF for convenience
static int OPT_WRITE_APPXS
          Flag to specify that the App markers should be written when saving the image
static int OPT_WRITE_COMMENTS
          Flag to specify that Jpeg comments should be written when saving the image
static int OPT_WRITE_OPTIMIZE_HUFF
          Flag to specify that the Huffman tables should be optimized before saving the image.
static int OPT_XFORM_ADJUST_EDGES
          Flag to specifiy that Non Transformable edge blocks should be adjusted accordingly when transforming the image.
static int OPT_XFORM_APPX
          Flag to specifiy that the Image Header information (Exif width, height and resolution) should be adjusted when transforming the image
static int OPT_XFORM_ORIENTATION
          Flag to specify that the Orientation marker in the Image header information (Exif) should be changed to reflect the new Orientation of the image after transformation.
static int OPT_XFORM_THUMBNAIL
          Flag to specifiy that the Thumbnail in the Image Header Information (Exif) should be transformed when transforming the image.
static int OPT_XFORM_TRIM
          Flag to specifiy that Non Transformable edge blocks should be removed when transforming the image.
static String PROGRAMNAME
          Program Name
static int READ_ALL
          Identifies the option to read the entire image while reading
static int READ_HEADER
          Identifies the option to read upto the Image Header including image dimensions, parameters and tables for decoding while reading
static int READ_INFO
          Identifies the option to read upto the Image Header Info while reading
static int READ_NONE
          Identifies that no part of the Image has been read successfully.
static int REMOVE
          Flag indicating that an entity should be removed during xferInfo(..)
static int REPLACE
          Flag indicating that an entity should be replaced with what is there in the LLJTran object during xferInfo(..)
static int RETAIN
          Flag indicating that an entity should be retained during xferInfo(..)
static int ROT_180
          Identifies the Rotate 180 degrees transformation
static int ROT_270
          Identifies the Rotate 270 degrees clockwise transformation
static int ROT_90
          Identifies the Rotate 90 degrees clockwise transformation
static int TRANSPOSE
          Identifies the Transpose transformation
static int TRANSVERSE
          Identifies the Transverse transformation
 
Fields inherited from class mediautil.image.jpeg.BasicJpegIo
M_DHP, M_DHT, M_DNL, M_DQT, M_DRI, M_EXP
 
Fields inherited from class mediautil.gen.BasicIo
FACTOR_ABVS
 
Fields inherited from interface mediautil.gen.directio.IterativeReader
CONTINUE, STOP
 
Constructor Summary
LLJTran(File file)
          Constructor.
LLJTran(InputStream inStream)
          Constructor.
 
Method Summary
 void addAppx(byte[] markerData, int startIndex, int len, boolean forImageInfo)
          Adds the Appx marker data at the end.
 int checkPerfect(int op, Rectangle cropBounds)
          Checks if the current image is suitable for a perfect transform.
 void closeInternalInputStream()
          Closes the internal Input Stream in case LLJTran was constructed with a File.
 boolean equals(Object o)
          Checks if JPEG objects are equal TODO: point to the same file can be not sufficient
 void freeMemory()
          This method can be called at anytime the LLJTran object is not required.
 int getAppx(int index, byte[] markerData, int startIndex, int len)
          Copies a portion of or the entire data of an Appx marker.
 int getAppxLen(int index)
          Gets the length of the Appxs marker at the given index.
 int getAppxMarker(int index)
          Gets the Marker Code for the give Appx index.
 String getComment()
          Gets the Jpeg comment present in the image or null if none present.
 String getEncoding()
          Gets the encoding which will be used for comments.
 String getErrorMsg()
          This gets the current error message because of which LLJTran has stopped processing the jpeg input.
 Exception getException()
          Gets the exception if any corresponding an error.
 File getFile()
          Returns the File source or null if reading from a Stream
 int getHeight()
          Gets the Image Height.
 int getHeightInMCU()
          Gets the Image Height in number of MCU blocks.
 int getHSamplingFactor(int componentIndex)
          Returns the Horizontal Sampling factor for the given component.
 AbstractImageInfo getImageInfo()
          Returns an instance of the Image Header Info.
 int getImageInfoAppxIndex()
          Gets the Appx index of the Image Header Information (Exif) Data.
 String getLocationName()
          Gets full path of the File source or null if reading from a stream
 int getMaxHSamplingFactor()
          Gets the Maximum Horizontal Sampling factor, A jpeg compression parameter.
 int getMaxVSamplingFactor()
          Gets the Maximum Vertical Sampling factor, A jpeg compression parameter.
 int getMCUHeight()
          Gets the height of an MCU block which equals 8*getMaxVSamplingFactor().
 int getMCUWidth()
          Gets the width of an MCU block which equals 8*getMaxHSamplingFactor().
 String getName()
          Gets the Name of the Source file.
 int getNumAppxs()
          Gets Number of Application Specific Markers (Appxs) Read.
 int getNumComponents()
          Returns the number of components in Image, which is usually 3 for a RGB color image.
 int getNumQTables()
          Gets the Number of Quantization Tables
 String getPendingErrorMsg()
          Returns pending error message.
 int[] getQTable(int tableIndex)
          Gets a Quantization Table
 int getQTableIndexForComponent(int componentIndex)
          Gets the Quantization Table Index for a given component
 ProgressCallback getReadProgressCallback()
          Gets the current Callback Object for Image Read progress or null if no callback is present.
 int getReadUpto()
          Returns upto what stage the image has been read.
 int getRequestSize(int which)
          Method used for debugging Iterative Read/Writes.
 int getRestartInterval()
          Gets the Restart Interval.
 InputStream getThumbnailAsStream()
          Provides an InputStream to read the Thumbnail Information.
 int getVSamplingFactor(int componentIndex)
          Returns the Vertical Sampling factor for the given component.
 int getWidth()
          Gets the Image Width.
 int getWidthInMCU()
          Gets the Image Width in number of MCU blocks.
 ProgressCallback getWriteProgressCallback()
          Gets the current Callback Object for Image Write progress or null if no callback is present.
 void initRead(int readUpto, boolean keep_appxs, boolean throwException)
          This method is to be used for the Iterative version of the read method.
 IterativeWriter initWrite(OutputStream outStream, int op, int options, Rectangle bounds, int restart_interval)
          This method is to be used for the Iterative version of the transform and save methods.
 IterativeWriter initWrite(OutputStream outStream, int op, int options, Rectangle bounds, int restart_interval, boolean pullDownMode)
          This method is to be used for the Iterative version of the transform and save methods.
 void insertAppx(int index, byte[] markerData, int startIndex, int len, boolean forImageInfo)
          Inserts the Appx marker data at the given index.
 int nextRead(int numBytes)
          Reads atleast the next numBytes bytes.
 int nextWrite(int numBytes)
          Writes atleast the next numBytes bytes.
 void read(boolean keep_appxs)
          Reads the Image from the File or InputStream specified in the Constructor.
 void read(int readUpto, boolean keep_appxs)
          Reads the Image from the File or InputStream specified in the Constructor.
 boolean refreshAppx()
          Refreshes the appx information array corresponding to any changes done in imageinfo.
 void removeAppx(int index)
          Removes the Appx marker data at the given index.
 boolean removeThumbnail()
          Removes the Thumnail image if any from the Image Information Header (Exif).
 void resetInput(File file)
          Resets the input for loading the image.
 void resetInput(InputStream inStream)
          Resets the input for loading the image.
 void save(OutputStream os)
          Saves the current image using OPT_WRITE_ALL option.
 void save(OutputStream os, int options)
          Saves the current image using supplied options.
 void save(OutputStream os, int options, int restart_interval)
          Saves the current image using supplied options and with restart_markers at the specified MCU interval.
 void setAppx(int index, byte[] markerData, int startIndex, int len, boolean forImageInfo)
          Changes the Appx marker data at the given index.
 void setComment(String comment)
          Sets the jpeg comment to be written.
 void setEncoding(String enc)
          Sets the encoding for Jpeg comments.
 void setReadProgressCallback(ProgressCallback callback)
          Sets callback to update the progress of Image read.
 boolean setThumbnail(byte[] newThumbnailData, int startIndex, int len, String thumbnailExt)
          Sets the Thumbnail in the Image Header Information (Exif).
 void setWriteProgressCallback(ProgressCallback callback)
          Sets callback to update the progress of Image write.
 String toString()
          Gets the Name of the Source file.
 void transform(int op)
          Transorms the current image using OPT_DEFAULTS.
 void transform(int op, int options)
          Transorms the current image using supplied options.
 void transform(int op, int options, Rectangle bounds)
          This is a high level method for lossless transformation of JPEG image.
 void transform(OutputStream outStream, int op)
          Saves the current image after transforming it using OPT_DEFAULTS.
 void transform(OutputStream outStream, int op, int options)
          Saves the current image after transforming it using supplied options.
 void transform(OutputStream outStream, int op, int options, Rectangle bounds)
          Saves the current image after transforming it using supplied options.
 void transform(OutputStream outStream, int op, int options, Rectangle bounds, int restart_interval)
          Saves the current image after transforming it using supplied options and with restart_markers at the specified MCU interval.
 void wrapupIterativeWrite(IterativeWriter writer)
          This method should be called when using the initWrite method with nextWrite in writing out the jpeg image.
 int writeThumbnail(OutputStream out)
          Saves the Thumbnail image in the Image Header Information (Exif).
 void xferInfo(InputStream is, OutputStream os, int appxsOption, int commentOption)
          This method is for modifying only the Image Header Information (Exif) without processing the actual image.
 
Methods inherited from class mediautil.gen.BasicIo
asInt, asString, bn2s, bn2s, convertLength, in2s, isSignature, read, read, s2n, skip
 
Methods inherited from class java.lang.Object
getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

JFIF

public static final String JFIF
Name of the JFIF format

See Also:
Constant Field Values

FPXR

public static final String FPXR
Name of the FPXR format

See Also:
Constant Field Values

JPEG

public static final String JPEG
Name of the JPEG format

See Also:
Constant Field Values

NONE

public static final int NONE
Identifies the identity transformation or no transformation

See Also:
Constant Field Values

FLIP_H

public static final int FLIP_H
Identifies the Horizontal Flip transformation

See Also:
Constant Field Values

FLIP_V

public static final int FLIP_V
Identifies the Vertical Flip transformation

See Also:
Constant Field Values

TRANSPOSE

public static final int TRANSPOSE
Identifies the Transpose transformation

See Also:
Constant Field Values

TRANSVERSE

public static final int TRANSVERSE
Identifies the Transverse transformation

See Also:
Constant Field Values

ROT_90

public static final int ROT_90
Identifies the Rotate 90 degrees clockwise transformation

See Also:
Constant Field Values

ROT_180

public static final int ROT_180
Identifies the Rotate 180 degrees transformation

See Also:
Constant Field Values

ROT_270

public static final int ROT_270
Identifies the Rotate 270 degrees clockwise transformation

See Also:
Constant Field Values

CROP

public static final int CROP
Identifies the crop transformation

See Also:
Constant Field Values

COMMENT

public static final int COMMENT
Identifies the comment transformation. This is not used in LLJTran as of now

See Also:
Constant Field Values

READ_NONE

public static final int READ_NONE
Identifies that no part of the Image has been read successfully. Not a valid option while reading

See Also:
Constant Field Values

READ_INFO

public static final int READ_INFO
Identifies the option to read upto the Image Header Info while reading

See Also:
Constant Field Values

READ_HEADER

public static final int READ_HEADER
Identifies the option to read upto the Image Header including image dimensions, parameters and tables for decoding while reading

See Also:
Constant Field Values

READ_ALL

public static final int READ_ALL
Identifies the option to read the entire image while reading

See Also:
Constant Field Values

OPT_XFORM_APPX

public static final int OPT_XFORM_APPX
Flag to specifiy that the Image Header information (Exif width, height and resolution) should be adjusted when transforming the image

See Also:
Constant Field Values

OPT_XFORM_THUMBNAIL

public static final int OPT_XFORM_THUMBNAIL
Flag to specifiy that the Thumbnail in the Image Header Information (Exif) should be transformed when transforming the image. OPT_XFORM_APPX must be set for this to take effect

See Also:
Constant Field Values

OPT_XFORM_TRIM

public static final int OPT_XFORM_TRIM
Flag to specifiy that Non Transformable edge blocks should be removed when transforming the image. Depending on the transformation the Image width, height or both may be trimmed to the nearest multiple of 8 or 16 pixels before the transform. Please note that this leads to loss of image pixels in the partial edge(es). When this flag is set the flag OPT_XFORM_ADJUST_EDGES is ignored even if set.

More Info: You have partial MCU blocks when the image width is not a multiple of getMCUWidth() or image height is not a multiple of getMCUHeight(). getMCUWidth() or getMCUHeight() are a multiple of 8, usually 8, 16 and sometimes 24.

Below lists the effect of Setting this flag on the Lossles Transformations:

FLIP_H: Image bottom trimmed before transform

FLIP_V: Image right trimmed before transform

TRANSPOSE: No trimming required before transform

TRANSVERSE: Image right and bottom trimmed before transform

ROT_90: Image bottom trimmed before transform

ROT_180: Image right and bottom trimmed before transform

ROT_270: Image right trimmed before transform

CROP: The x and y coordinates of the top-left corner of the crop area is adjusted to the nearest MCU boundary.

See Also:
Constant Field Values

OPT_XFORM_ADJUST_EDGES

public static final int OPT_XFORM_ADJUST_EDGES
Flag to specifiy that Non Transformable edge blocks should be adjusted accordingly when transforming the image. Depending on the transformation either the right strip or the bottom strip of the image or both if present after the nearest MCU boundary maybe adjusted with a different transform.

This option is ignored if OPT_XFORM_TRIM is set. If both these flags are not set the transformation is applied without accounting for partial MCU edges which may result in visual distortion at the edges.

Below lists the effect of Setting this flag on the Lossles Transformations:

FLIP_H: Right partial MCU strip is left unchanged

FLIP_V: Bottom partial MCU strip is left unchanged

TRANSPOSE: No adjustment required

TRANSVERSE: Result is same as ROT_90 followed by FLIP_V using LLJTran. So the right partial MCU strip is rotated 90, bottom rotated 270 and bottom-right corner MCU block transposed.

ROT_90: Bottom partial MCU strip is transposed and comes in the right edge the new image.

ROT_180: Result is the same as if FLIP_H is followed by a FLIP_V using LLJTran. So the bottom partial MCU strip mirrored horizontal, the right strip mirrored vertical and the bottom-right corner MCU block is left unchanged.

ROT_270: Right partial MCU strip is transposed and comes in the bottom edge the new image.

CROP: The x and y coordinates of the top-left corner of the crop area is adjusted to the nearest MCU boundary.

See Also:
Constant Field Values

OPT_XFORM_ORIENTATION

public static final int OPT_XFORM_ORIENTATION
Flag to specify that the Orientation marker in the Image header information (Exif) should be changed to reflect the new Orientation of the image after transformation.

See Also:
Constant Field Values

OPT_WRITE_APPXS

public static final int OPT_WRITE_APPXS
Flag to specify that the App markers should be written when saving the image

See Also:
Constant Field Values

OPT_WRITE_COMMENTS

public static final int OPT_WRITE_COMMENTS
Flag to specify that Jpeg comments should be written when saving the image

See Also:
Constant Field Values

OPT_WRITE_ALL

public static final int OPT_WRITE_ALL
Flag containing all OPT_WRITE_XXX flags except OPT_WRITE_OPTIMIZE_HUFF for convenience

See Also:
Constant Field Values

OPT_WRITE_OPTIMIZE_HUFF

public static final int OPT_WRITE_OPTIMIZE_HUFF
Flag to specify that the Huffman tables should be optimized before saving the image. This leads to a slightly reduced image file size.

See Also:
Constant Field Values

OPT_DEFAULTS

public static final int OPT_DEFAULTS
Flag containing defaults for convenience. Includes OPT_XFORM_APPX, OPT_XFORM_ADJUST_EDGES and OPT_WRITE_ALL flags

See Also:
Constant Field Values

REPLACE

public static final int REPLACE
Flag indicating that an entity should be replaced with what is there in the LLJTran object during xferInfo(..)

See Also:
Constant Field Values

RETAIN

public static final int RETAIN
Flag indicating that an entity should be retained during xferInfo(..)

See Also:
Constant Field Values

REMOVE

public static final int REMOVE
Flag indicating that an entity should be removed during xferInfo(..)

See Also:
Constant Field Values

IMPERFECT_X

public static final int IMPERFECT_X
Flag which specifies that the image width or x coordinate of the crop origin is not okay for a perfect transform.

See Also:
checkPerfect(int, Rectangle), Constant Field Values

IMPERFECT_Y

public static final int IMPERFECT_Y
Flag which specifies that the image height or y coordinate of the crop origin is not okay for a perfect transform.

See Also:
checkPerfect(int, Rectangle), Constant Field Values

dummyExifHeader

public static final byte[] dummyExifHeader
This array contains the data for a Dummy Exif Header. This can be used to create an Exif header for a jpeg image without one.


PROGRAMNAME

public static final String PROGRAMNAME
Program Name

See Also:
Constant Field Values
Constructor Detail

LLJTran

public LLJTran(File file)
Constructor.

Parameters:
file - File object specifying the file to read image from. An internal input stream is created which is closed when the image is fully read or if an error occurs. The internal input Stream can be closed explicity by calling closeInternalInputStream()

LLJTran

public LLJTran(InputStream inStream)
Constructor.

Parameters:
inStream - Source to read the image. This stream is not closed by LLJTran and it is the callers responsibility to do so.
Method Detail

resetInput

public void resetInput(InputStream inStream)
Resets the input for loading the image. This method is mainly for loading the image after reading upto READ_INFO and closing the input. false can be passed for the keep_appxs param for the read following this to retain the existing Image Header Information (Exif). A Runtime exception results if the image is already read beyond INFO_SECTION.

The method uses inStream as the new input, sets readUpto to READ_NONE and closes any internal Input Stream.

Parameters:
inStream - New Input. If null then the previous input must have been a file which will be used.

resetInput

public void resetInput(File file)
Resets the input for loading the image. This method is mainly for loading the image after reading upto READ_INFO and closing the input. false can be passed for the keep_appxs param for the read following this to retain the existing Image Header Information (Exif). A Runtime exception results if the image is already read beyond INFO_SECTION.

The method uses file as the new input, sets readUpto to READ_NONE and closes any internal Input Stream.

Parameters:
file - New Input file.

setEncoding

public void setEncoding(String enc)
Sets the encoding for Jpeg comments.

Parameters:
enc - Name of a jdk supported Charset or null to use default encoding

getEncoding

public String getEncoding()
Gets the encoding which will be used for comments.

Returns:
Encoding or null to indicate platform default encoding.

getName

public String getName()
Gets the Name of the Source file.

Returns:
Name of the Source file. Returns Unknown/Stream if reading from a stream

toString

public String toString()
Gets the Name of the Source file.

Overrides:
toString in class Object
See Also:
getName()

getFile

public File getFile()
Returns the File source or null if reading from a Stream


equals

public boolean equals(Object o)
Checks if JPEG objects are equal TODO: point to the same file can be not sufficient

Overrides:
equals in class Object
Parameters:
o -
Returns:
True if equal, false otherwise

getErrorMsg

public String getErrorMsg()
This gets the current error message because of which LLJTran has stopped processing the jpeg input. This results in an exception when using regular read methods. However when using initRead and nextRead via classes in mediautil.gen.directio package this method should be called to check for error messages due to which the image was not processed.

Returns:
The error message due to which LLJTran cannot proceed. Null if there is no error message
See Also:
nextRead(int)

getPendingErrorMsg

public String getPendingErrorMsg()
Returns pending error message. This occurs when you read only upto the header section and the jpeg format is unsupported. You can read the Image Header Info (Exif) and jpeg comments but the next call to a read method will give an error. Note that if getErrorMsg() returns a non null error message this will return the same message.

Returns:
pending error message which will cause an exception for the next read call or null if no pending error message

getException

public Exception getException()
Gets the exception if any corresponding an error.

Returns:
The exception if any corresponding to an error message.
See Also:
getErrorMsg()

getImageInfo

public AbstractImageInfo getImageInfo()
Returns an instance of the Image Header Info. The Class of the Object returned is a specific implementation of AbstractImageInfo like Exif. If there is no specific Image Header Information like Exif an instance of JPEG containing basic Image Info is returned.

Returns:
Image Header Information

getComment

public String getComment()
Gets the Jpeg comment present in the image or null if none present.

Returns:
Jpeg comment present in the image or null if none present

setComment

public void setComment(String comment)
Sets the jpeg comment to be written.

Parameters:
comment - Comment to be written or null if none is to be written

getLocationName

public String getLocationName()
Gets full path of the File source or null if reading from a stream

Returns:
Full path of the File source or null if reading from a stream

setReadProgressCallback

public void setReadProgressCallback(ProgressCallback callback)
Sets callback to update the progress of Image read.

Parameters:
callback - Callback to update the progress of read or null for no callback

setWriteProgressCallback

public void setWriteProgressCallback(ProgressCallback callback)
Sets callback to update the progress of Image write.

Parameters:
callback - Callback to update the progress of write or null for no callback

getReadProgressCallback

public ProgressCallback getReadProgressCallback()
Gets the current Callback Object for Image Read progress or null if no callback is present.

Returns:
Current Callback Object for Image Read progress or null if no callback is present

getWriteProgressCallback

public ProgressCallback getWriteProgressCallback()
Gets the current Callback Object for Image Write progress or null if no callback is present.

Returns:
Current Callback Object for Image Write progress or null if no callback is present

checkPerfect

public int checkPerfect(int op,
                        Rectangle cropBounds)
Checks if the current image is suitable for a perfect transform.

Returns:
A bitwise OR (|) of the 2 flags IMPERFECT_X and IMPERFECT_Y.

IMPERFECT_X is set in the return value if the width (x origin in case op is CROP) has to be adjusted/trimmed.

IMPERFECT_Y is set in the return value if the height (y origin in case op is CROP) has to be adjusted/trimmed.

Thus 0 means the transform will be perfect.

Note that though checkPerfect returns 0 depending on op, the transformation operation either or both the image width and height need not be a multiple of the MCU width/height.

See Also:
IMPERFECT_X

transform

public void transform(int op)
Transorms the current image using OPT_DEFAULTS. This method may be called multiple times before saving the image using save. The jpeg image must be fully read by LLJTran first.

Parameters:
op - Specifies the transformation operation like NONE, ROT_90 etc. CROP is treated as NONE.
See Also:
save(OutputStream, int)

transform

public void transform(int op,
                      int options)
Transorms the current image using supplied options. This method may be called multiple times before saving the image using save. The jpeg image must be fully read by LLJTran first.

Parameters:
op - Specifies the transformation like NONE, ROT_90 etc. CROP is treated as NONE.
options - options specifies how to manage exif or other header content including embedded thumbnail transformation. Please pass a bitwise OR (|) of the required set of OPT_XFORM_.. flags.
See Also:
save(OutputStream, int)

transform

public void transform(int op,
                      int options,
                      Rectangle bounds)
This is a high level method for lossless transformation of JPEG image. This method may be called multiple times before saving the image using save. The jpeg image must be fully read by LLJTran first.

Use this method for CROP operation.

Parameters:
op - One of operations, like CROP, or ROT_xxx
options - Options specifies how to manage exif or other header content including embedded thumbnail transformation. Please pass a bitwise OR (|) of the required set of OPT_XFORM_.. flags.
bounds - Crop bounds. This must be passed if op is CROP, ignored otherwise. The x and y values of bounds must be within the image and are adjusted to the closest MCU boundary. The width and height must be positive, but are automatically limited to imageWidth-bounds.x and imageHieght-bounds.y respectively. The bounds Object passed is unchanged.
See Also:
save(OutputStream, int)

transform

public void transform(OutputStream outStream,
                      int op)
               throws IOException
Saves the current image after transforming it using OPT_DEFAULTS. The transformation is applied only while saving the image. The image itself is restored to its original state on completion of the method. This method may be called multiple times. The jpeg image must be fully read by LLJTran first.

Parameters:
outStream - Output Stream to which the jpeg image should be written
op - Specifies the transformation like NONE, ROT_90 etc. CROP is treated as NONE.
Throws:
IOException

transform

public void transform(OutputStream outStream,
                      int op,
                      int options)
               throws IOException
Saves the current image after transforming it using supplied options. The transformation is applied only while saving the image. The image itself is restored to its original state on completion of the method. This method may be called multiple times. The jpeg image must be fully read by LLJTran first.

Parameters:
outStream - Output Stream to which the jpeg image should be written
op - Specifies the transformation like NONE, ROT_90 etc. CROP is treated as NONE.
options - Options specifies how to manage exif or other header content including embedded thumbnail transformation and also the header information to write. Please pass a bitwise OR (|) of the required set of OPT_XFORM_.. and OPT_WRITE_.. flags.
Throws:
IOException

transform

public void transform(OutputStream outStream,
                      int op,
                      int options,
                      Rectangle bounds)
               throws IOException
Saves the current image after transforming it using supplied options. The transformation is applied only while saving the image. The image itself is restored to its original state on completion of the method. This method may be called multiple times. The jpeg image must be fully read by LLJTran first.

Use this method for CROP operation.

Parameters:
outStream - Output Stream to which the jpeg image should be written
op - Specifies the transformation like NONE, ROT_90 etc
options - Options specifies how to manage exif or other header content including embedded thumbnail transformation and also the header information to write. Please pass a bitwise OR (|) of the required set of OPT_XFORM_.. and OPT_WRITE_.. flags.
bounds - Crop bounds. This must be passed if op is CROP, ignored otherwise. The x and y values of bounds must be within the image and are adjusted to the closest MCU boundary. The width and height must be positive, but are automatically limited to imageWidth-bounds.x and imageHieght-bounds.y respectively. The bounds Object passed is unchanged.
Throws:
IOException

transform

public void transform(OutputStream outStream,
                      int op,
                      int options,
                      Rectangle bounds,
                      int restart_interval)
               throws IOException
Saves the current image after transforming it using supplied options and with restart_markers at the specified MCU interval. The transformation is applied only while saving the image. The image itself is restored to its original state on completion of the method. This method may be called multiple times. The jpeg image must be fully read by LLJTran first.

Use this method for CROP operation.

Parameters:
outStream - Output Stream to which the jpeg image should be written
op - Specifies the transformation like NONE, ROT_90 etc
options - Options specifies how to manage exif or other header content including embedded thumbnail transformation and also the header information to write. Please pass a bitwise OR (|) of the required set of OPT_XFORM_.. and OPT_WRITE_.. flags.
bounds - Crop bounds. This must be passed if op is CROP, ignored otherwise. The x and y values of bounds must be within the image and are adjusted to the closest MCU boundary. The width and height must be positive, but are automatically limited to imageWidth-bounds.x and imageHieght-bounds.y respectively. The bounds Object passed is unchanged.
restart_interval - Specifies to write a restart marker every restart_interval MCU block. No restart markers are written if this parameter is passed as 0
Throws:
IOException

initWrite

public IterativeWriter initWrite(OutputStream outStream,
                                 int op,
                                 int options,
                                 Rectangle bounds,
                                 int restart_interval)
                          throws IOException
This method is to be used for the Iterative version of the transform and save methods. The main use of this method is to get an IterativeWriter for use with InStreamFromIterativeWriter class to read the transformed image directly from LLJTran instead of writing it out.

Parameters:
outStream - Output Stream to which the jpeg image should be written
op - Specifies the transformation like NONE, ROT_90 etc
options - Options specifies how to manage exif or other header content including embedded thumbnail transformation and also the header information to write. Please pass a bitwise OR (|) of the required set of OPT_XFORM_.. and OPT_WRITE_.. flags.
bounds - Crop bounds. This must be passed if op is CROP, ignored otherwise. The x and y values of bounds must be within the image and are adjusted to the closest MCU boundary. The width and height must be positive, but are automatically limited to imageWidth-bounds.x and imageHieght-bounds.y respectively. The bounds Object passed is unchanged.
restart_interval - Specifies to write a restart marker every restart_interval MCU block. No restart markers are written if this parameter is passed as 0
Returns:
An instance of IterativeWriter. calls to the nextWrite method of this would write the next few bytes of the image to outStream. Though the return value is currently the LLJTran object(this) the code should use the return value only since it is possible to change it in future to support an LLJTran object writing in multiple threads.
Throws:
IOException
See Also:
InStreamFromIterativeWriter

initWrite

public IterativeWriter initWrite(OutputStream outStream,
                                 int op,
                                 int options,
                                 Rectangle bounds,
                                 int restart_interval,
                                 boolean pullDownMode)
                          throws IOException
This method is to be used for the Iterative version of the transform and save methods. The main use of this method is to get an IterativeWriter for use with InStreamFromIterativeWriter class to read the transformed image directly from LLJTran instead of writing it out.

Parameters:
outStream - Output Stream to which the jpeg image should be written
op - Specifies the transformation like NONE, ROT_90 etc
options - Options specifies how to manage exif or other header content including embedded thumbnail transformation and also the header information to write. Please pass a bitwise OR (|) of the required set of OPT_XFORM_.. and OPT_WRITE_.. flags.
bounds - Crop bounds. This must be passed if op is CROP, ignored otherwise. The x and y values of bounds must be within the image and are adjusted to the closest MCU boundary. The width and height must be positive, but are automatically limited to imageWidth-bounds.x and imageHieght-bounds.y respectively. The bounds Object passed is unchanged.
restart_interval - Specifies to write a restart marker every restart_interval MCU block. No restart markers are written if this parameter is passed as 0
pullDownMode - If this parameter is true then memory is freed as the jpeg is written making the LLJTran useless after the call. This option can be used in case the Object reading the image allocates memory in increments so that the maximum memory requirement would come down which is not the case with java's ImageReader which allocates the Buffered memory in one stroke. Also using this option for operations which change the orientation by 90 degrees (ROT_90, ROT_270, TRANSPOSE and TRANSVERSE) is illegal and results in a Runtime Exception.
Returns:
An instance of IterativeWriter. calls to the nextWrite method of this would write the next few bytes of the image to outStream. Though the return value is currently the LLJTran object(this) the code should use the return value only since it is possible this may change in future to support an LLJTran object writing in multiple threads.
Throws:
IOException
See Also:
InStreamFromIterativeWriter

wrapupIterativeWrite

public void wrapupIterativeWrite(IterativeWriter writer)
This method should be called when using the initWrite method with nextWrite in writing out the jpeg image. It ensures that the state of the image is restored.

Parameters:
writer - The writer that was obtained from the initWriter call

save

public void save(OutputStream os)
          throws IOException
Saves the current image using OPT_WRITE_ALL option. The jpeg image must be fully read by LLJTran first and can then be transformed zero or more times using the transform.

Parameters:
os - Output Stream to which the jpeg image should be written
Throws:
IOException
See Also:
transform(int)

save

public void save(OutputStream os,
                 int options)
          throws IOException
Saves the current image using supplied options. The jpeg image must be fully read by LLJTran first and can then be transformed zero or more times using the transform.

Parameters:
os - Output Stream to which the jpeg image should be written
options - Options specifies the header information to write. Please pass a bitwise OR (|) of the required set of OPT_WRITE_.. flags.
Throws:
IOException
See Also:
transform(int)

save

public void save(OutputStream os,
                 int options,
                 int restart_interval)
          throws IOException
Saves the current image using supplied options and with restart_markers at the specified MCU interval. The jpeg image must be fully read by LLJTran first and can then be transformed zero or more times using the transform.

Parameters:
os - Output Stream to which the jpeg image should be written
options - Options specifies the header information to write. Please pass a bitwise OR (|) of the required set of OPT_WRITE_.. flags.
restart_interval - Specifies to write a restart marker every restart_interval MCU block. No restart markers are written if this parameter is passed as 0
Throws:
IOException

writeThumbnail

public int writeThumbnail(OutputStream out)
                   throws IOException
Saves the Thumbnail image in the Image Header Information (Exif).

Parameters:
out - Output Stream to save the Thumbnail. This is not flushed or closed.
Returns:
Number of bytes written. This will be zero if Image Header Information is not present or was not read during read.
Throws:
IOException

getThumbnailAsStream

public InputStream getThumbnailAsStream()
Provides an InputStream to read the Thumbnail Information.

Returns:
InputStream to read the Thumbnail from. Null if there is not Thumbnail information. Caller can close the returned Stream.

setThumbnail

public boolean setThumbnail(byte[] newThumbnailData,
                            int startIndex,
                            int len,
                            String thumbnailExt)
                     throws IOException
Sets the Thumbnail in the Image Header Information (Exif). This works currenlty only if the Image has an Exif header which has been read.

Parameters:
newThumbnailData - The new Thumbnail image
startIndex - start index of the image in newThumbnailData
len - Length of the Thumbnail
thumbnailExt - File extension of the Thumbnail as specified in ImageResources. Currently works only for jpeg/bmp Thumbnails for Exif headers.
Returns:
True if successful in setting the Thumbnail false otherwise.
Throws:
IOException

refreshAppx

public boolean refreshAppx()
Refreshes the appx information array corresponding to any changes done in imageinfo. This method is to be used only if making any changes to the Image Information Header (Exif) apart from changing the Thumbnail. Currently only Exif is supported.

Returns:
True on success, false otherwise
See Also:
getImageInfo(), Exif

removeThumbnail

public boolean removeThumbnail()
Removes the Thumnail image if any from the Image Information Header (Exif). Currently only Exif is supported.

Returns:
True on success, false otherwise.

nextWrite

public int nextWrite(int numBytes)
              throws IOException
Writes atleast the next numBytes bytes. initWrite should have been called before. Usually this method will be called via the IterativeWriter interface and need not be called directly on an LLJTran object. 750 bytes is a good value of the minimum number of bytes that would be written and also for the writeCushion by which the actual number of bytes written may exceed numBytes. The application appx markers are split while writing to take care of the numBytes passed but not the comments. So long jpeg comments may cause a large number of bytes to be written.

Specified by:
nextWrite in interface IterativeWriter
Parameters:
numBytes - Number of bytes to write. This is only indicative. The implementor may write more or less. Writing too less impacts performance due to repeated nextWrite calls. Writing too much more than numBytes leads to performance impact due to buffer reallocation.

The OutputStream returned for use by an IterativeWriter by directio's classes implement ByteCounter which can help in keeping track of the number of bytes written or remaining during a nextWrite call.

Returns:
IterativeReader.CONTINUE in case the writing is not complete. Returns IterativeReader.STOP on completion of write.
Throws:
IOException - in case of any errors.
See Also:
initWrite(OutputStream,int,int,Rectangle,int), InStreamFromIterativeWriter

freeMemory

public void freeMemory()
This method can be called at anytime the LLJTran object is not required. Frees internal structures for Garbage collection by setting them to null and also closes any open Internal Input Stream.


read

public void read(boolean keep_appxs)
          throws LLJTranException
Reads the Image from the File or InputStream specified in the Constructor.

Parameters:
keep_appxs - Specifies if Image Information Header (Exif) is to be retained. This should be passed as true if it is later required to be written out. Note that if this is passed as false existing Image Information Header is unchanged.
Throws:
LLJTranException - If a fatal error is encountered.

initRead

public void initRead(int readUpto,
                     boolean keep_appxs,
                     boolean throwException)
              throws LLJTranException
This method is to be used for the Iterative version of the read method. The main use of this method is to get an IterativeReader for use with SplitInputStream and OutStreamToIterativeReader classes to Share the Image File with another Object while reading or to save an image from another Object (Say BufferedImage) directly to an LLJTran Object thus reducing disk io.

Parameters:
readUpto - The section upto which to read. You can pass READ_ALL to read the entire image or READ_INFO to read only the Image Header Information (Exif) to modify and rewrite using xferInfo(..) or READ_HEADER to read the header information and decoding tables but not the image data. You can make subsequent calls to read/initRead,nextReads with READ_ALL to complete reading the image provided you are not reading using directio classes like SplitInputStream.
keep_appxs - Specifies if Image Information Header (Exif) is to be retained. This should be passed as true if it is later required to be written out. Note that if this is passed as false existing Image Information Header is unchanged.
throwException - Specifies if an exception is to be thrown on encountering an error during a call of nextRead(). If this parameter is passed as true then an IOException is thrown which gets propogated. This option is useful for use with OutStreamToIterativeReader where there is no point in continuing to write without anybody to read. If this parameter is passed as false then then on encountering an error the nextRead() call sets the error message and returns IterativeReader.STOP. The error can be retrieved later using getErrorMsg() call. This option may be useful for use with SplitInputStream where the main Reader can continue to read data even if the LLJTran subReader errors out.
Throws:
LLJTranException - If there is an error in the readUpto parameter passed.
See Also:
IterativeReader, SplitInputStream, OutStreamToIterativeReader

read

public void read(int readUpto,
                 boolean keep_appxs)
          throws LLJTranException
Reads the Image from the File or InputStream specified in the Constructor.

Parameters:
readUpto - The section upto which to read. You can pass READ_ALL to read the entire image or READ_INFO to read only the Image Header Information (Exif) to modify and rewrite using xferInfo(..) or READ_HEADER to read the header information and decoding tables but not the image data. You can make subsequent calls to read/initRead,nextReads with READ_ALL to complete reading the image provided you are not reading using directio classes like SplitInputStream.
keep_appxs - Specifies if Image Information Header (Exif) is to be retained. This should be passed as true if it is later required to be written out. Note that if this is passed as false existing Image Information Header is unchanged.
Throws:
LLJTranException

getReadUpto

public int getReadUpto()
Returns upto what stage the image has been read.

Returns:
One of the READ_.. flags including READ_NONE if nothing has been read successfully.

nextRead

public int nextRead(int numBytes)
             throws IOException
Reads atleast the next numBytes bytes. initRead should have been called before. Usually this method will be called via the IterativeReader interface. 750 bytes is a good value of the minimum number of bytes that would be read and also for the readCushion by which the actual number of bytes read may exceed numBytes. The application appx markers are split while reading to take care of the numBytes passed but not the comments. So long jpeg comments may cause a large number of bytes to be read.

Specified by:
nextRead in interface IterativeReader
Parameters:
numBytes - Number of bytes to read. This is only indicative. The implementor may read more or less. Reading too less impacts performance due to repeated nextRead calls. Reading too much more than numBytes leads to performance impact due to buffer reallocation in case of SplitInputStream and an IOException due to Empty Buffer in an OutStreamToIterativeReader.

The InputStream returned for use by an IterativeReader by directio's classes implement ByteCounter which can help in keeping track of the number of bytes read or remaining during a nextRead call.

Returns:
IterativeReader.CONTINUE in case the reading is not complete. Returns IterativeReader.STOP on completion of read or in case of an error. getErrorMsg() should be called to check for errors.
Throws:
IOException - If there is an error and throwException was initialized as true.
See Also:
initRead(int,boolean,boolean), SplitInputStream, OutStreamToIterativeReader

xferInfo

public void xferInfo(InputStream is,
                     OutputStream os,
                     int appxsOption,
                     int commentOption)
              throws LLJTranException
This method is for modifying only the Image Header Information (Exif) without processing the actual image. If you read the image fully and write it back the jpeg decoding tables and the DCT coefficients will be read into memory and then written back which is not the case with this method.

For using this method you first read the image upto READ_INFO or if you want to process the jpeg comments also it would be better to read upto READ_HEADER since jpeg comments sometimes appear after the decoding tables. Then you make the necessary changes to the imageInfo and call refreshAppx after which you call xferInfo to read the image again and write it out with the changed header and or comments. Also note that since READ_HEADER defers the errors due to unsupported jpeg formats like Progressive jpeg you can use this method to process the Image Header Information (Exif) and/or jpeg comments for those files as well.

Parameters:
is - Image input to change the Image Header Information. The image marker sections are read one by one and copied to the output except the Image Header Information and/or comments which can be either copied, replaced by what is present in the LLJTran Object or removed. Once the header is read the rest of the image is copied as it is.

This parameter can be null to indicate that LLJTran continue to read from the internal input stream where it had stopped. Below are the restrictions when passing it as null:

  • The image should have been read only upto READ_INFO so that all the decoding tables can be copied as it is.
  • Since You can only read upto READ_INFO, in this case trying to modify the comments is not fool proof since the comments may not have been read.
  • You cannot pass RETAIN for the parameters appxsOption or commentOption since they have already been read.
  • If you pass REPLACE for the parameters appxsOption or commentOption and comments and appx headers are encountered in the internal input they are also written (It is quite possible to encounter comments after READ_INFO since comments might come after decoding tables, but should not be the case with appx markers. But still..)
  • The LLJTran Object cannot be used after this method the input is already consumed.
os - Output to write the image to.
appxsOption - One of RETAIN, REPLACE or REMOVE indicating whether the application specific markers (appxs) including Image Header Information like Exif are to be retained from the input is or replaced with what is there in the LLJTran Object or be removed.
commentOption - One of RETAIN, REPLACE or REMOVE indicating whether the jpeg comment section is to be retained from the input is or replaced with what is there in the LLJTran Object or be removed.
Throws:
LLJTranException
See Also:
read(int,boolean), getImageInfo(), Exif

closeInternalInputStream

public void closeInternalInputStream()
Closes the internal Input Stream in case LLJTran was constructed with a File. Note that This does not close the InputStream if passed in the constructor.


getWidth

public int getWidth()
Gets the Image Width. The image should have been successfully read upto READ_HEADER.

Returns:
Image Width in pixels

getHeight

public int getHeight()
Gets the Image Height. The image should have been successfully read upto READ_HEADER.

Returns:
Image Height in pixels

getWidthInMCU

public int getWidthInMCU()
Gets the Image Width in number of MCU blocks. The image should have been successfully read upto READ_HEADER.

Returns:
Image Width in MCU blocks

getHeightInMCU

public int getHeightInMCU()
Gets the Image Height in number of MCU blocks. The image should have been successfully read upto READ_HEADER.

Returns:
Image Height in MCU blocks

getMaxHSamplingFactor

public int getMaxHSamplingFactor()
Gets the Maximum Horizontal Sampling factor, A jpeg compression parameter. The image should have been successfully read upto READ_HEADER.

Returns:
Max Horizontal Sampling Factor

getMaxVSamplingFactor

public int getMaxVSamplingFactor()
Gets the Maximum Vertical Sampling factor, A jpeg compression parameter. The image should have been successfully read upto READ_HEADER.

Returns:
Max Vertical Sampling Factor

getMCUWidth

public int getMCUWidth()
Gets the width of an MCU block which equals 8*getMaxHSamplingFactor(). The image should have been successfully read upto READ_HEADER.

Returns:
Width in pixels of an MCU block

getMCUHeight

public int getMCUHeight()
Gets the height of an MCU block which equals 8*getMaxVSamplingFactor(). The image should have been successfully read upto READ_HEADER.

Returns:
Height in pixels of an MCU block

getNumComponents

public int getNumComponents()
Returns the number of components in Image, which is usually 3 for a RGB color image.

Returns:
Number of Components

getHSamplingFactor

public int getHSamplingFactor(int componentIndex)
Returns the Horizontal Sampling factor for the given component.

Parameters:
componentIndex - Index of the component which should be between 0 and getNumComponents()-1
Returns:
Horizontal Sampling Factor of the Component

getVSamplingFactor

public int getVSamplingFactor(int componentIndex)
Returns the Vertical Sampling factor for the given component.

Parameters:
componentIndex - Index of the component which should be between 0 and getNumComponents()-1
Returns:
Vertical Sampling Factor of the Component

getRestartInterval

public int getRestartInterval()
Gets the Restart Interval.

Returns:
Restart Interval of Restart Markers or 0 if there are no restart markers.

getNumQTables

public int getNumQTables()
Gets the Number of Quantization Tables

Returns:
Number of Quantization Tables

getQTable

public int[] getQTable(int tableIndex)
Gets a Quantization Table

Parameters:
tableIndex - Table Index. Note that this could be different from the componentIndex.
Returns:
Quantization Table for the given tableIndex
See Also:
getQTableIndexForComponent(int)

getQTableIndexForComponent

public int getQTableIndexForComponent(int componentIndex)
Gets the Quantization Table Index for a given component

Parameters:
componentIndex - Component Index for which Quantization Table Index is required
Returns:
The Quantization Table Index for the given Component Index

getNumAppxs

public int getNumAppxs()
Gets Number of Application Specific Markers (Appxs) Read.

Returns:
Number of Application Specific Markers (Appxs) Read

getAppxMarker

public int getAppxMarker(int index)
Gets the Marker Code for the give Appx index.

Parameters:
index - Index of the Marker (0 to getNumAppxs()-1)
Returns:
The Marker Code for the give Appx index

getAppxLen

public int getAppxLen(int index)
Gets the length of the Appxs marker at the given index.

Parameters:
index - Index of the Marker (0 to getNumAppxs()-1)
Returns:
The Length of the Appxs marker at the given index. This includes the 2 bytes for the 0xFF and markerCode.

getAppx

public int getAppx(int index,
                   byte[] markerData,
                   int startIndex,
                   int len)
Copies a portion of or the entire data of an Appx marker.

Parameters:
index - Index of the Marker (0 to getNumAppxs()-1)
markerData - Array to copy the markerData. The array must be large enough.
startIndex - Index in markerData to start copying from
len - Length to be copied. This must be <= getAppxLen(index)

getImageInfoAppxIndex

public int getImageInfoAppxIndex()
Gets the Appx index of the Image Header Information (Exif) Data. The actual appx can be retrieved using this index.

Returns:
The Appx index of the Image Header Information (Exif) Data. Returns -1 if No Image Header Information Appx marker is identified.

setAppx

public void setAppx(int index,
                    byte[] markerData,
                    int startIndex,
                    int len,
                    boolean forImageInfo)
Changes the Appx marker data at the given index.

Parameters:
index - Index of the Marker (0 to getNumAppxs()-1)
markerData - Array to copy the markerData.
startIndex - Index in markerData to start copying from
len - Length to be copied
forImageInfo - If this parameter is passed as true it means the Appx marker contains Image Header Information such as Exif. The data is attempted to be parsed. If successfull the imageInfo is updated. Otherwise an instance of JPEG is created for basic image information.

insertAppx

public void insertAppx(int index,
                       byte[] markerData,
                       int startIndex,
                       int len,
                       boolean forImageInfo)
Inserts the Appx marker data at the given index.

Parameters:
index - Index where to insert the new Marker (0 to getNumAppxs())
markerData - Array to copy the markerData.
startIndex - Index in markerData to start copying from
len - Length to be copied
forImageInfo - If this parameter is passed as true it means the Appx marker contains Image Header Information such as Exif. The data is attempted to be parsed. If successfull the imageInfo is updated. Otherwise an instance of JPEG is created for basic image information.

addAppx

public void addAppx(byte[] markerData,
                    int startIndex,
                    int len,
                    boolean forImageInfo)
Adds the Appx marker data at the end. Equivalent to calling insertAppx(getNumAppxs(), markerData, startIndex, len, forImageInfo);

Parameters:
markerData - Array to copy the markerData.
startIndex - Index in markerData to start copying from
len - Length to be copied
forImageInfo - If this parameter is passed as true it means the Appx marker contains Image Header Information such as Exif. The data is attempted to be parsed. If successfull the imageInfo is updated. Otherwise an instance of JPEG is created for basic image information.

removeAppx

public void removeAppx(int index)
Removes the Appx marker data at the given index. In case the appx to be removed contains Image Header Information (Exif) the imageInfo is replaced with a JPEG instance containing basic Image Information.

Parameters:
index - Index of the marker to remove (0 to getNumAppxs())

getRequestSize

public int getRequestSize(int which)
Method used for debugging Iterative Read/Writes.

Parameters:
which - Identifies what RequestSize to return. 0: minReadRequest, 1: maxReadRequest, 2: minWriteRequest, 3: maxWriteRequest
Returns:
Corresponding numBytes requestSize to nextRead/nextWrite
See Also:
IterativeReader.nextRead(int), IterativeWriter.nextWrite(int)