You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by da...@apache.org on 2012/06/26 21:32:24 UTC
svn commit: r1354188 [2/2] - in
/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging: ./
common/ formats/tiff/
Modified: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/Imaging.java
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/Imaging.java?rev=1354188&r1=1354187&r2=1354188&view=diff
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/Imaging.java (original)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/Imaging.java Tue Jun 26 19:32:21 2012
@@ -40,52 +40,80 @@ import org.apache.commons.imaging.icc.Ic
import org.apache.commons.imaging.util.Debug;
/**
- * The primary interface to the Imaging library.
- * <p>
- * Almost all of the Imaging library's core functionality can be accessed
- * through it's methods.
- * <p>
- * All of Imaging's methods are static.
+ * The primary application programming interface (API) to the Imaging library.
* <p>
+
+ * <h3>Application Notes</h3>
+ * <h4>Using this class</h4>
+ * Almost all of the Apache Commons Imaging library's core functionality can
+ * be accessed through the methods provided by this class.
+ * The use of the Imaging class is similar to the Java API's ImageIO class,
+ * though Imaging supports formats and options not included in the standard
+ * Java API.
+ * <p>All of methods provided by the Imaging class are declared static.
+ * <p>The Apache Commons Imaging package is a pure Java implementation.
+ * <h4>Format support</h4>
+ * While the Apache Commons Imaging package handles a number of different
+ * graphics formats, support for some formats is not yet complete.
+ * For the most recent information on support for specific formats, refer to
+ * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+ * at the main project development web site.
+ * <h4>Optional parameters for image reading and writing</h4>
+ * Some of the methods provided by this class accept an optional
+ * <strong>params</strong> argument that permits the application to specify
+ * elements for special handling. If these specifications are not required by
+ * the application, the params argument may be omitted (as appropriate) or
+ * a null argument may be provided. In image-writing operations, the option
+ * parameters may include options such as data-compression type (if any),
+ * color model, or other format-specific data representations. The parameters
+ * map may also be used to provide EXIF Tags and other metadata to those
+ * formats that support them. In image-reading operations,
+ * the parameters may include information about special handling in reading
+ * the image data.
+ * <p>Optional parameters are specified using a Map object (typically,
+ * a Java HashMap) to specify a set of keys and values for input.
+ * The specification for support keys is provided by the ImagingConstants
+ * interface as well as by format-specific interfaces such as
+ * JpegContants or TiffConstants.
+ * <h4>Example code</h4>
* See the source of the SampleUsage class and other classes in the
* org.apache.commons.imaging.examples package for examples.
*
* @see <a
* href="https://svn.apache.org/repos/asf/commons/proper/imaging/trunk/src/test/java/org/apache/commons/imaging/examples/SampleUsage.java">org.apache.commons.imaging.examples.SampleUsage</a>
+ * @see <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
*/
public abstract class Imaging implements ImagingConstants {
/**
- * Tries to guess whether a file contains an image based on its file
- * extension.
- * <p>
- * Returns true if the file has a file extension associated with a file
- * format, such as .jpg or .gif.
- * <p>
- *
- * @param file
- * File which may contain an image.
- * @return true if the file has an image format file extension.
+ * Attempts to determine if a file contains an image recorded in
+ * a supported graphics format based on its file-name extension
+ * (for example ".jpg", ".gif", ".png", etc.).
+ *
+ * @param file A valid File object providing a reference to
+ * a file that may contain an image.
+ * @return true if the file-name includes a supported image
+ * format file extension; otherwise, false.
*/
public static boolean hasImageFileExtension(File file) {
- if (!file.isFile())
+ if (file==null || !file.isFile())
return false;
return hasImageFileExtension(file.getName());
}
/**
- * Tries to guess whether a filename represents an image based on its file
- * extension.
- * <p>
- * Returns true if the filename has a file extension associated with a file
- * format, such as .jpg or .gif.
- * <p>
+ * Attempts to determine if a file contains an image recorded in
+ * a supported graphics format based on its file-name extension
+ * (for example ".jpg", ".gif", ".png", etc.).
*
- * @param filename
- * String representing name of file which may contain an image.
+ * @param filename A valid string representing name of file
+ * which may contain an image.
* @return true if the filename has an image format file extension.
*/
public static boolean hasImageFileExtension(String filename) {
+ if(filename==null)
+ return false;
+
filename = filename.toLowerCase();
ImageParser imageParsers[] = ImageParser.getAllImageParsers();
@@ -104,15 +132,19 @@ public abstract class Imaging implements
}
/**
- * Tries to guess what the image type (if any) of data based on the file's
- * "magic numbers," the first bytes of the data.
- * <p>
+ * Attempts to determine the image format of a file based on its
+ * "magic numbers," the first bytes of the data.
+ * <p>Many graphics format specify identifying byte
+ * values that appear at the beginning of the data file. This method
+ * checks for such identifying elements and returns a ImageFormat
+ * enumeration indicating what it detects. Note that this
+ * method can return "false positives" in cases where non-image files
+ * begin with the specified byte values.
*
- * @param bytes
- * Byte array containing an image file.
+ * @param bytes Byte array containing an image file.
* @return An ImageFormat, such as ImageFormat.IMAGE_FORMAT_JPEG. Returns
* ImageFormat.IMAGE_FORMAT_UNKNOWN if the image type cannot be
- * guessed.
+ * determined.
*/
public static ImageFormat guessFormat(byte bytes[])
throws ImageReadException, IOException {
@@ -120,15 +152,19 @@ public abstract class Imaging implements
}
/**
- * Tries to guess what the image type (if any) of a file based on the file's
- * "magic numbers," the first bytes of the file.
- * <p>
+ * Attempts to determine the image format of a file based on its
+ * "magic numbers," the first bytes of the data.
+ * <p>Many graphics formats specify identifying byte
+ * values that appear at the beginning of the data file. This method
+ * checks for such identifying elements and returns a ImageFormat
+ * enumeration indicating what it detects. Note that this
+ * method can return "false positives" in cases where non-image files
+ * begin with the specified byte values.
*
- * @param file
- * File containing image data.
+ * @param file File containing image data.
* @return An ImageFormat, such as ImageFormat.IMAGE_FORMAT_JPEG. Returns
* ImageFormat.IMAGE_FORMAT_UNKNOWN if the image type cannot be
- * guessed.
+ * determined.
*/
public static ImageFormat guessFormat(File file) throws ImageReadException,
IOException {
@@ -161,8 +197,32 @@ public abstract class Imaging implements
return (a[0] == b[0]) && (a[1] == b[1]);
}
+
+ /**
+ * Attempts to determine the image format of a file based on its
+ * "magic numbers," the first bytes of the data.
+ * <p>Many graphics formats specify identifying byte
+ * values that appear at the beginning of the data file. This method
+ * checks for such identifying elements and returns a ImageFormat
+ * enumeration indicating what it detects. Note that this
+ * method can return "false positives" in cases where non-image files
+ * begin with the specified byte values.
+ *
+ * @param byteSource a valid ByteSource object potentially supplying
+ * data for an image.
+ * @return An ImageFormat, such as ImageFormat.IMAGE_FORMAT_JPEG. Returns
+ * ImageFormat.IMAGE_FORMAT_UNKNOWN if the image type cannot be
+ * determined.
+ * @throws ImageReadException in the event of an unsuccessful
+ * attempt to read the image data
+ * @throws IOException in the event of an unrecoverable I/O condition.
+ */
public static ImageFormat guessFormat(ByteSource byteSource)
throws ImageReadException, IOException {
+
+ if(byteSource==null)
+ return ImageFormat.IMAGE_FORMAT_UNKNOWN;
+
InputStream is = null;
try {
@@ -252,7 +312,7 @@ public abstract class Imaging implements
* @param bytes
* Byte array containing an image file.
* @return An instance of ICC_Profile or null if the image contains no ICC
- * profile..
+ * profile.
*/
public static ICC_Profile getICCProfile(byte bytes[])
throws ImageReadException, IOException {
@@ -267,7 +327,7 @@ public abstract class Imaging implements
* @param bytes
* Byte array containing an image file.
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return An instance of ICC_Profile or null if the image contains no ICC
* profile..
*/
@@ -303,7 +363,7 @@ public abstract class Imaging implements
* @param filename
* Filename associated with image data (optional).
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return An instance of ICC_Profile or null if the image contains no ICC
* profile..
*/
@@ -335,7 +395,7 @@ public abstract class Imaging implements
* @param file
* File containing image data.
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return An instance of ICC_Profile or null if the image contains no ICC
* profile..
*/
@@ -391,7 +451,7 @@ public abstract class Imaging implements
* @param bytes
* Byte array containing an image file.
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return A byte array.
* @see IccProfileParser
* @see ICC_Profile
@@ -431,7 +491,7 @@ public abstract class Imaging implements
* @param file
* File containing image data.
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return A byte array.
* @see IccProfileParser
* @see ICC_Profile
@@ -462,7 +522,7 @@ public abstract class Imaging implements
* @param bytes
* Byte array containing an image file.
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return An instance of ImageInfo.
* @see ImageInfo
*/
@@ -527,7 +587,7 @@ public abstract class Imaging implements
* @param filename
* Filename associated with image data (optional).
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return An instance of ImageInfo.
* @see ImageInfo
*/
@@ -567,7 +627,7 @@ public abstract class Imaging implements
* @param bytes
* Byte array containing an image file.
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return An instance of ImageInfo.
* @see ImageInfo
*/
@@ -588,7 +648,7 @@ public abstract class Imaging implements
* @param file
* File containing image data.
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return An instance of ImageInfo.
* @see ImageInfo
*/
@@ -625,7 +685,7 @@ public abstract class Imaging implements
return imageInfo;
}
- private static final ImageParser getImageParser(ByteSource byteSource)
+ private static ImageParser getImageParser(ByteSource byteSource)
throws ImageReadException, IOException {
ImageFormat format = guessFormat(byteSource);
if (!format.equals(ImageFormat.IMAGE_FORMAT_UNKNOWN)) {
@@ -679,7 +739,7 @@ public abstract class Imaging implements
* @param filename
* Filename associated with image data (optional).
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return The width and height of the image.
*/
public static Dimension getImageSize(InputStream is, String filename,
@@ -707,7 +767,7 @@ public abstract class Imaging implements
* @param bytes
* Byte array containing an image file.
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return The width and height of the image.
*/
public static Dimension getImageSize(byte bytes[], Map params)
@@ -735,7 +795,7 @@ public abstract class Imaging implements
* @param file
* File containing image data.
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return The width and height of the image.
*/
public static Dimension getImageSize(File file, Map params)
@@ -774,7 +834,7 @@ public abstract class Imaging implements
* @param filename
* Filename associated with image data (optional).
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return Xmp Xml as String, if present. Otherwise, returns null.
*/
public static String getXmpXml(InputStream is, String filename, Map params)
@@ -802,7 +862,7 @@ public abstract class Imaging implements
* @param bytes
* Byte array containing an image file.
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return Xmp Xml as String, if present. Otherwise, returns null.
*/
public static String getXmpXml(byte bytes[], Map params)
@@ -830,7 +890,7 @@ public abstract class Imaging implements
* @param file
* File containing image data.
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return Xmp Xml as String, if present. Otherwise, returns null.
*/
public static String getXmpXml(File file, Map params)
@@ -845,7 +905,7 @@ public abstract class Imaging implements
* @param byteSource
* File containing image data.
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return Xmp Xml as String, if present. Otherwise, returns null.
*/
public static String getXmpXml(ByteSource byteSource, Map params)
@@ -894,7 +954,7 @@ public abstract class Imaging implements
* @param bytes
* Byte array containing an image file.
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return An instance of IImageMetadata.
* @see IImageMetadata
*/
@@ -946,7 +1006,7 @@ public abstract class Imaging implements
* @param filename
* Filename associated with image data (optional).
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return An instance of IImageMetadata.
* @see IImageMetadata
*/
@@ -994,7 +1054,7 @@ public abstract class Imaging implements
* @param file
* File containing image data.
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @return An instance of IImageMetadata.
* @see IImageMetadata
*/
@@ -1011,14 +1071,15 @@ public abstract class Imaging implements
}
/**
- * Returns a description of the image's structure.
- * <p>
- * Useful for exploring format-specific details of image files.
- * <p>
- *
- * @param bytes
- * Byte array containing an image file.
- * @return A description of the image file's structure.
+ * Write the ImageInfo and format-specific information for the image
+ * content of the specified byte array to a string.
+ * @param bytes A valid array of bytes.
+ * @return A valid string.
+ * @throws ImageReadException In the event that the the specified
+ * content does not conform to the format of the specific parser
+ * implementation.
+ * @throws IOException In the event of unsuccessful read or
+ * access operation.
*/
public static String dumpImageFile(byte bytes[]) throws ImageReadException,
IOException {
@@ -1026,14 +1087,15 @@ public abstract class Imaging implements
}
/**
- * Returns a description of the image file's structure.
- * <p>
- * Useful for exploring format-specific details of image files.
- * <p>
- *
- * @param file
- * File containing image data.
- * @return A description of the image file's structure.
+ * Write the ImageInfo and format-specific information for the image
+ * content of the specified file to a string.
+ * @param file A valid file reference.
+ * @return A valid string.
+ * @throws ImageReadException In the event that the the specified
+ * content does not conform to the format of the specific parser
+ * implementation.
+ * @throws IOException In the event of unsuccessful read or
+ * access operation.
*/
public static String dumpImageFile(File file) throws ImageReadException,
IOException {
@@ -1047,11 +1109,31 @@ public abstract class Imaging implements
return imageParser.dumpImageFile(byteSource);
}
+ /**
+ * Attempts to determine the image format of the specified data and
+ * evaluates its format compliance. This method
+ * returns a FormatCompliance object which includes information
+ * about the data's compliance to a specific format.
+ * @param bytes a valid array of bytes containing image data.
+ * @return if successful, a valid FormatCompliance object.
+ * @throws ImageReadException in the event of unreadable data.
+ * @throws IOException in the event of an unrecoverable I/O condition.
+ */
public static FormatCompliance getFormatCompliance(byte bytes[])
throws ImageReadException, IOException {
return getFormatCompliance(new ByteSourceArray(bytes));
}
+ /**
+ * Attempts to determine the image format of the specified data and
+ * evaluates its format compliance. This method
+ * returns a FormatCompliance object which includes information
+ * about the data's compliance to a specific format.
+ * @param file valid file containing image data
+ * @return if successful, a valid FormatCompliance object.
+ * @throws ImageReadException in the event of unreadable data.
+ * @throws IOException in the event of an unrecoverable I/O condition.
+ */
public static FormatCompliance getFormatCompliance(File file)
throws ImageReadException, IOException {
return getFormatCompliance(new ByteSourceFile(file));
@@ -1065,17 +1147,15 @@ public abstract class Imaging implements
}
/**
- * Returns all images contained in an image.
- * <p>
- * Useful for image formats such as GIF and ICO in which a single file may
- * contain multiple images.
- * <p>
- *
- * @param is
- * InputStream from which to read image data.
- * @param filename
- * Filename associated with image data (optional).
- * @return A vector of BufferedImages.
+ * Gets all images specified by the InputStream (some
+ * formats may include multiple images within a single data source).
+ * @param is A valid InputStream
+ * @return A valid (potentially empty) list of BufferedImage objects.
+ * @throws ImageReadException In the event that the the specified
+ * content does not conform to the format of the specific parser
+ * implementation.
+ * @throws IOException In the event of unsuccessful read or
+ * access operation.
*/
public static List<BufferedImage> getAllBufferedImages(InputStream is,
String filename) throws ImageReadException, IOException {
@@ -1083,37 +1163,38 @@ public abstract class Imaging implements
}
/**
- * Returns all images contained in an image.
- * <p>
- * Useful for image formats such as GIF and ICO in which a single file may
- * contain multiple images.
- * <p>
- *
- * @param bytes
- * Byte array containing an image file.
- * @return A vector of BufferedImages.
+ * Gets all images specified by the byte array (some
+ * formats may include multiple images within a single data source).
+ * @param bytes a valid array of bytes
+ * @return A valid (potentially empty) list of BufferedImage objects.
+ * @throws ImageReadException In the event that the the specified
+ * content does not conform to the format of the specific parser
+ * implementation.
+ * @throws IOException In the event of unsuccessful read or
+ * access operation.
*/
public static List<BufferedImage> getAllBufferedImages(byte bytes[])
throws ImageReadException, IOException {
return getAllBufferedImages(new ByteSourceArray(bytes));
}
- /**
- * Returns all images contained in an image file.
- * <p>
- * Useful for image formats such as GIF and ICO in which a single file may
- * contain multiple images.
- * <p>
- *
- * @param file
- * File containing image data.
- * @return A vector of BufferedImages.
+ /**
+ * Gets all images specified by the file (some
+ * formats may include multiple images within a single data source).
+ * @param file A reference to a valid data file.
+ * @return A valid (potentially empty) list of BufferedImage objects.
+ * @throws ImageReadException In the event that the the specified
+ * content does not conform to the format of the specific parser
+ * implementation.
+ * @throws IOException In the event of unsuccessful read or
+ * access operation.
*/
public static List<BufferedImage> getAllBufferedImages(File file)
throws ImageReadException, IOException {
return getAllBufferedImages(new ByteSourceFile(file));
}
+
private static List<BufferedImage> getAllBufferedImages(
ByteSource byteSource) throws ImageReadException, IOException {
ImageParser imageParser = getImageParser(byteSource);
@@ -1121,71 +1202,49 @@ public abstract class Imaging implements
return imageParser.getAllBufferedImages(byteSource);
}
- // public static boolean extractImages(byte bytes[], File dstDir,
- // String dstRoot, ImageParser encoder) throws ImageReadException,
- // IOException, ImageWriteException
- // {
- // return extractImages(new ByteSourceArray(bytes), dstDir, dstRoot,
- // encoder);
- // }
- //
- // public static boolean extractImages(File file, File dstDir, String
- // dstRoot,
- // ImageParser encoder) throws ImageReadException, IOException,
- // ImageWriteException
- // {
- // return extractImages(new ByteSourceFile(file), dstDir, dstRoot, encoder);
- // }
- //
- // public static boolean extractImages(ByteSource byteSource, File dstDir,
- // String dstRoot, ImageParser encoder) throws ImageReadException,
- // IOException, ImageWriteException
- // {
- // ImageParser imageParser = getImageParser(byteSource);
- //
- // return imageParser.extractImages(byteSource, dstDir, dstRoot, encoder);
- // }
/**
- * Reads the first image from an InputStream as a BufferedImage.
- * <p>
- * (TODO: elaborate here.)
+ * Reads the first image from an InputStream.
* <p>
- * Sanselan can only read image info, metadata and ICC profiles from all
- * image formats. However, note that the library cannot currently read or
- * write JPEG image data. PSD (Photoshop) files can only be partially read
- * and cannot be written. All other formats (PNG, GIF, TIFF, BMP, etc.) are
- * fully supported.
- * <p>
- *
- * @param is
- * InputStream to read image data from.
- * @return A BufferedImage.
- * @see ImagingConstants
+ * For the most recent information on support for specific formats, refer to
+ * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+ * at the main project development web site. While the Apache Commons
+ * Imaging package does not fully support all formats, it can read
+ * image info, metadata and ICC profiles from all image formats that
+ * provide this data.
+ * @param is a valid ImageStream from which to read data.
+ * @return if successful, a valid buffered image
+ * @throws ImageReadException in the event of a processing error
+ * while reading an image (i.e. a format violation, etc.).
+ * @throws IOException in the event of an unrecoverable I/O exception.
*/
+
public static BufferedImage getBufferedImage(InputStream is)
throws ImageReadException, IOException {
return getBufferedImage(is, null);
}
+
+
/**
- * Reads the first image from an InputStream as a BufferedImage.
- * <p>
- * (TODO: elaborate here.)
- * <p>
- * Sanselan can only read image info, metadata and ICC profiles from all
- * image formats. However, note that the library cannot currently read or
- * write JPEG image data. PSD (Photoshop) files can only be partially read
- * and cannot be written. All other formats (PNG, GIF, TIFF, BMP, etc.) are
- * fully supported.
- * <p>
- *
- * @param is
- * InputStream to read image data from.
- * @param params
- * Map of optional parameters, defined in SanselanConstants.
- * @return A BufferedImage.
- * @see ImagingConstants
+ * Reads the first image from an InputStream
+ * using data-processing options specified through a parameters
+ * map. Options may be configured using the ImagingContants
+ * interface or the various format-specific implementations provided
+ * by this package.
+ * <p>
+ * For the most recent information on support for specific formats, refer to
+ * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+ * at the main project development web site. While the Apache Commons
+ * Imaging package does not fully support all formats, it can read
+ * image info, metadata and ICC profiles from all image formats that
+ * provide this data.
+ * @param is a valid ImageStream from which to read data.
+ * @param params an optional parameters map specifying options
+ * @return if successful, a valid buffered image
+ * @throws ImageReadException in the event of a processing error
+ * while reading an image (i.e. a format violation, etc.).
+ * @throws IOException in the event of an unrecoverable I/O exception.
*/
public static BufferedImage getBufferedImage(InputStream is, Map params)
throws ImageReadException, IOException {
@@ -1196,97 +1255,103 @@ public abstract class Imaging implements
}
/**
- * Reads the first image from an image file as a BufferedImage.
- * <p>
- * (TODO: elaborate here.)
- * <p>
- * Sanselan can only read image info, metadata and ICC profiles from all
- * image formats. However, note that the library cannot currently read or
- * write JPEG image data. PSD (Photoshop) files can only be partially read
- * and cannot be written. All other formats (PNG, GIF, TIFF, BMP, etc.) are
- * fully supported.
+ * Reads the first image from a byte array.
* <p>
- *
- * @param bytes
- * Byte array containing an image file.
- * @return A BufferedImage.
- * @see ImagingConstants
+ * For the most recent information on support for specific formats, refer to
+ * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+ * at the main project development web site. While the Apache Commons
+ * Imaging package does not fully support all formats, it can read
+ * image info, metadata and ICC profiles from all image formats that
+ * provide this data.
+ * @param bytes a valid array of bytes from which to read data.
+ * @return if successful, a valid buffered image
+ * @throws ImageReadException in the event of a processing error
+ * while reading an image (i.e. a format violation, etc.).
+ * @throws IOException in the event of an unrecoverable I/O exception.
*/
public static BufferedImage getBufferedImage(byte bytes[])
throws ImageReadException, IOException {
return getBufferedImage(new ByteSourceArray(bytes), null);
}
+
/**
- * Reads the first image from an image file as a BufferedImage.
- * <p>
- * (TODO: elaborate here.)
- * <p>
- * Sanselan can only read image info, metadata and ICC profiles from all
- * image formats. However, note that the library cannot currently read or
- * write JPEG image data. PSD (Photoshop) files can only be partially read
- * and cannot be written. All other formats (PNG, GIF, TIFF, BMP, etc.) are
- * fully supported.
- * <p>
- *
- * @param bytes
- * Byte array containing an image file.
- * @param params
- * Map of optional parameters, defined in SanselanConstants.
- * @return A BufferedImage.
- * @see ImagingConstants
- */
+ * Reads the first image from a byte array
+ * using data-processing options specified through a parameters
+ * map. Options may be configured using the ImagingContants
+ * interface or the various format-specific implementations provided
+ * by this package.
+ * <p>
+ * For the most recent information on support for specific formats, refer to
+ * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+ * at the main project development web site. While the Apache Commons
+ * Imaging package does not fully support all formats, it can read
+ * image info, metadata and ICC profiles from all image formats that
+ * provide this data.
+ * @param bytes a valid array of bytes from which to read data.
+ * @param params an optional parameters map specifying options.
+ * @return if successful, a valid buffered image
+ * @throws ImageReadException in the event of a processing error
+ * while reading an image (i.e. a format violation, etc.).
+ * @throws IOException in the event of an unrecoverable I/O exception.
+ */
+
+
public static BufferedImage getBufferedImage(byte bytes[], Map params)
throws ImageReadException, IOException {
return getBufferedImage(new ByteSourceArray(bytes), params);
}
+
+
+
/**
- * Reads the first image from an image file as a BufferedImage.
- * <p>
- * (TODO: elaborate here.)
+ * Reads the first image from a file.
* <p>
- * Sanselan can only read image info, metadata and ICC profiles from all
- * image formats. However, note that the library cannot currently read or
- * write JPEG image data. PSD (Photoshop) files can only be partially read
- * and cannot be written. All other formats (PNG, GIF, TIFF, BMP, etc.) are
- * fully supported.
- * <p>
- *
- * @param file
- * File containing image data.
- * @return A BufferedImage.
- * @see ImagingConstants
+ * For the most recent information on support for specific formats, refer to
+ * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+ * at the main project development web site. While the Apache Commons
+ * Imaging package does not fully support all formats, it can read
+ * image info, metadata and ICC profiles from all image formats that
+ * provide this data.
+ * @param file a valid reference to a file containing image data.
+ * @return if successful, a valid buffered image
+ * @throws ImageReadException in the event of a processing error
+ * while reading an image (i.e. a format violation, etc.).
+ * @throws IOException in the event of an unrecoverable I/O exception.
*/
public static BufferedImage getBufferedImage(File file)
throws ImageReadException, IOException {
return getBufferedImage(new ByteSourceFile(file), null);
}
+
/**
- * Reads the first image from an image file as a BufferedImage.
- * <p>
- * (TODO: elaborate here.)
- * <p>
- * Sanselan can only read image info, metadata and ICC profiles from all
- * image formats. However, note that the library cannot currently read or
- * write JPEG image data. PSD (Photoshop) files can only be partially read
- * and cannot be written. All other formats (PNG, GIF, TIFF, BMP, etc.) are
- * fully supported.
- * <p>
- *
- * @param file
- * File containing image data.
- * @param params
- * Map of optional parameters, defined in SanselanConstants.
- * @return A BufferedImage.
- * @see ImagingConstants
+ * Reads the first image from a file
+ * using data-processing options specified through a parameters
+ * map. Options may be configured using the ImagingContants
+ * interface or the various format-specific implementations provided
+ * by this package.
+ * <p>
+ * For the most recent information on support for specific formats, refer to
+ * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+ * at the main project development web site. While the Apache Commons
+ * Imaging package does not fully support all formats, it can read
+ * image info, metadata and ICC profiles from all image formats that
+ * provide this data.
+ * @param file a valid reference to a file containing image data.
+ * @return if successful, a valid buffered image
+ * @throws ImageReadException in the event of a processing error
+ * while reading an image (i.e. a format violation, etc.).
+ * @throws IOException in the event of an unrecoverable I/O exception.
*/
public static BufferedImage getBufferedImage(File file, Map params)
throws ImageReadException, IOException {
return getBufferedImage(new ByteSourceFile(file), params);
}
+
+
private static BufferedImage getBufferedImage(ByteSource byteSource,
Map params) throws ImageReadException, IOException {
ImageParser imageParser = getImageParser(byteSource);
@@ -1315,9 +1380,35 @@ public abstract class Imaging implements
* @param format
* The ImageFormat to use.
* @param params
- * Map of optional parameters, defined in SanselanConstants.
+ * Map of optional parameters, defined in ImagingConstants.
* @see ImagingConstants
*/
+
+
+
+ /**
+ * Writes the content of a BufferedImage to a file using the specified
+ * image format. Specifications for storing the file (such as data compression,
+ * color models, metadata tags, etc.) may be specified using an optional
+ * parameters map. These specifications are defined in the ImagingConstants
+ * interface or in various format-specific implementations.
+ * <p>
+ * Image writing is not supported for all graphics formats.
+ * For the most recent information on support for specific formats, refer to
+ * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+ * at the main project development web site. While the Apache Commons
+ * Imaging package does not fully support all formats, it can read
+ * image info, metadata and ICC profiles from all image formats that
+ * provide this data.
+ * @param src a valid BufferedImage object
+ * @param file the file to which the output image is to be written
+ * @param format the format in which the output image is to be written
+ * @param params an optional parameters map (nulls permitted)
+ * @throws ImageWriteException in the event of a format violation,
+ * unsupported image format, etc.
+ * @throws IOException in the event of an unrecoverable I/O exception.
+ * @see ImagingConstants
+ */
public static void writeImage(BufferedImage src, File file,
ImageFormat format, Map params) throws ImageWriteException,
IOException {
@@ -1338,27 +1429,30 @@ public abstract class Imaging implements
}
}
+
/**
- * Writes a BufferedImage to a byte array.
- * <p>
- * (TODO: elaborate here.)
- * <p>
- * Sanselan can only read image info, metadata and ICC profiles from all
- * image formats. However, note that the library cannot currently read or
- * write JPEG image data. PSD (Photoshop) files can only be partially read
- * and cannot be written. All other formats (PNG, GIF, TIFF, BMP, etc.) are
- * fully supported.
- * <p>
- *
- * @param src
- * The BufferedImage to be written.
- * @param format
- * The ImageFormat to use.
- * @param params
- * Map of optional parameters, defined in SanselanConstants.
- * @return A byte array containing the image file.
+ * Writes the content of a BufferedImage to a byte array using the specified
+ * image format. Specifications for storing the file (such as data compression,
+ * color models, metadata tags, etc.) may be specified using an optional
+ * parameters map. These specifications are defined in the ImagingConstants
+ * interface or in various format-specific implementations.
+ * <p>
+ * Image writing is not supported for all graphics formats.
+ * For the most recent information on support for specific formats, refer to
+ * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+ * at the main project development web site. While the Apache Commons
+ * Imaging package does not fully support all formats, it can read
+ * image info, metadata and ICC profiles from all image formats that
+ * provide this data.
+ * @param src a valid BufferedImage object
+ * @param format the format in which the output image is to be written
+ * @param params an optional parameters map (nulls permitted)
+ * @return if successful, a valid array of bytes.
+ * @throws ImageWriteException in the event of a format violation,
+ * unsupported image format, etc.
+ * @throws IOException in the event of an unrecoverable I/O exception.
* @see ImagingConstants
- */
+ */
public static byte[] writeImageToBytes(BufferedImage src,
ImageFormat format, Map params) throws ImageWriteException,
IOException {
@@ -1369,28 +1463,30 @@ public abstract class Imaging implements
return os.toByteArray();
}
- /**
- * Writes a BufferedImage to an OutputStream.
- * <p>
- * (TODO: elaborate here.)
- * <p>
- * Sanselan can only read image info, metadata and ICC profiles from all
- * image formats. However, note that the library cannot currently read or
- * write JPEG image data. PSD (Photoshop) files can only be partially read
- * and cannot be written. All other formats (PNG, GIF, TIFF, BMP, etc.) are
- * fully supported.
- * <p>
- *
- * @param src
- * The BufferedImage to be written.
- * @param os
- * The OutputStream to write to.
- * @param format
- * The ImageFormat to use.
- * @param params
- * Map of optional parameters, defined in SanselanConstants.
+
+ /**
+ * Writes the content of a BufferedImage to an OutputStream using the specified
+ * image format. Specifications for storing the file (such as data compression,
+ * color models, metadata tags, etc.) may be specified using an optional
+ * parameters map. These specifications are defined in the ImagingConstants
+ * interface or in various format-specific implementations.
+ * <p>
+ * Image writing is not supported for all graphics formats.
+ * For the most recent information on support for specific formats, refer to
+ * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+ * at the main project development web site. While the Apache Commons
+ * Imaging package does not fully support all formats, it can read
+ * image info, metadata and ICC profiles from all image formats that
+ * provide this data.
+ * @param src a valid BufferedImage object
+ * @param os the OutputStream to which the output image is to be written
+ * @param format the format in which the output image is to be written
+ * @param params an optional parameters map (nulls permitted)
+ * @throws ImageWriteException in the event of a format violation,
+ * unsupported image format, etc.
+ * @throws IOException in the event of an unrecoverable I/O exception.
* @see ImagingConstants
- */
+ */
public static void writeImage(BufferedImage src, OutputStream os,
ImageFormat format, Map params) throws ImageWriteException,
IOException {
Modified: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImagingConstants.java
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImagingConstants.java?rev=1354188&r1=1354187&r2=1354188&view=diff
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImagingConstants.java (original)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImagingConstants.java Tue Jun 26 19:32:21 2012
@@ -16,6 +16,13 @@
*/
package org.apache.commons.imaging;
+/**
+ * Defines constants that may be used in passing options to
+ * ImageParser read/write implementations, the utility routines
+ * implemented in the Imaging class, and throughout the
+ * Apache Commons Imaging package. Individual ImageParser
+ * implementations may define their own format-specific options.
+ */
public interface ImagingConstants {
/**
* Parameter key. Applies to read and write operations.
Modified: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImagingException.java
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImagingException.java?rev=1354188&r1=1354187&r2=1354188&view=diff
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImagingException.java (original)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImagingException.java Tue Jun 26 19:32:21 2012
@@ -16,6 +16,10 @@
*/
package org.apache.commons.imaging;
+/**
+ * The base class for implementing custom exceptions in the
+ * Apache Commons Imaging package.
+ */
public class ImagingException extends Exception {
private static final long serialVersionUID = -1L;
Modified: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/PixelDensity.java
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/PixelDensity.java?rev=1354188&r1=1354187&r2=1354188&view=diff
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/PixelDensity.java (original)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/PixelDensity.java Tue Jun 26 19:32:21 2012
@@ -16,6 +16,10 @@
*/
package org.apache.commons.imaging;
+/**
+ * Used to specify pixel density and physical dimensions when reading or
+ * storing image information.
+ */
public class PixelDensity {
private double horizontalDensity;
private double verticalDensity;
Added: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/common/package.html
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/common/package.html?rev=1354188&view=auto
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/common/package.html (added)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/common/package.html Tue Jun 26 19:32:21 2012
@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>Apache Commons Imaging</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ </head>
+ <body>
+ Provides utility classes that are employed across multiple
+ image formats and sub-packages.
+ </body>
+</html>
Propchange: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/common/package.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/formats/tiff/package.html
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/formats/tiff/package.html?rev=1354188&view=auto
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/formats/tiff/package.html (added)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/formats/tiff/package.html Tue Jun 26 19:32:21 2012
@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>Apache Commons Imaging</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ </head>
+ <body>
+ Provides classes and methods for reading and writing
+ Tagged Image File Format (TIFF) files. Tiff files are
+ widely used in applications for which supplemental
+ metadata is added to images in the form of "tags".
+ </body>
+</html>
Propchange: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/formats/tiff/package.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/package.html
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/package.html?rev=1354188&view=auto
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/package.html (added)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/package.html Tue Jun 26 19:32:21 2012
@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>Apache Commons Imaging</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ </head>
+ <body>
+ The main package for Apache Commons Imaging.
+ </body>
+</html>
Propchange: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/package.html
------------------------------------------------------------------------------
svn:eol-style = native