001: /*
002: * $RCSfile: TIFFDescriptor.java,v $
003: *
004: * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved.
005: *
006: * Use is subject to license terms.
007: *
008: * $Revision: 1.1 $
009: * $Date: 2005/02/11 04:57:45 $
010: * $State: Exp $
011: */
012: package javax.media.jai.operator;
013:
014: import com.sun.media.jai.codec.SeekableStream;
015: import com.sun.media.jai.codec.TIFFDecodeParam;
016: import java.awt.RenderingHints;
017: import java.awt.image.RenderedImage;
018: import java.awt.image.renderable.ParameterBlock;
019: import javax.media.jai.JAI;
020: import javax.media.jai.OperationDescriptorImpl;
021: import javax.media.jai.ParameterBlockJAI;
022: import javax.media.jai.RenderedOp;
023: import javax.media.jai.registry.RenderedRegistryMode;
024:
025: /**
026: * An <code>OperationDescriptor</code> describing the "TIFF" operation.
027: *
028: * <p> The "TIFF" operation reads TIFF data from a <code>SeekableStream</code>.
029: *
030: * <p><a href="http://partners.adobe.com/asn/developer/PDFS/TN/TIFF6.pdf">
031: * TIFF version 6.0</a> was finalized in June, 1992. Since that time
032: * there have been two technical notes extending the specification.
033: * There are also a number of
034: * <a href="http://home.earthlink.net/~ritter/tiff/#extensions">
035: * TIFF Extensions</a> including
036: * <a href="http://www.remotesensing.org/geotiff/geotiff.html">
037: * GeoTIFF</a>.
038: *
039: * <p> The TIFF format consists of a short header that points to a
040: * linked list of Image File Directories (IFDs). An IFD is
041: * essentially a list of fields. The <code>TIFFDirectory</code> class
042: * encapsulates a set of common operations performed on an IFD; an instance
043: * of the <code>TIFFField</code> class corresponds to a field in an IFD.
044: * Each field has numeric value or <i>tag</i>, a data type, and a byte offset
045: * at which the field's data may be found. This mechanism allows TIFF
046: * files to contain multiple images, each with its own IFD, and to order
047: * its contents flexibly since (apart from the header) nothing is required to
048: * appear at a fixed offset.
049: *
050: * <p> An image generated by the "TIFF" operation will have a property
051: * named "tiff_directory" the value of which will be a <code>TIFFDirectory</code>
052: * corresponding to the IFD of the image. JAI's property inheritance mechanism
053: * provides a mechanism by which the field information of the IFD may be
054: * made available to applications in a straightforward way. This mechanism
055: * may be utilized by setting a <code>PropertyGenerator</code> on this
056: * <code>OperationDescriptor</code> which extracts <code>TIFFField</code>s
057: * from the <code>TIFFDirectory</code>-valued property and returns them either
058: * as <code>TIFFField</code> instances or as some user-defined object
059: * initialized from a <code>TIFFField</code>. In the latter case application
060: * code would be insulated from the uncommitted <code>TIFFField</code> class.
061: *
062: * <p> The second parameter contains an instance of
063: * <code>TIFFDecodeParam</code> to be used during the decoding.
064: * It may be set to <code>null</code> in order to perform default
065: * decoding, or equivalently may be omitted.
066: *
067: * <p> Some TIFF extensions make use of a mechanism known as "private
068: * IFDs." A private IFD is one that is not referenced by the standard
069: * linked list of IFDs that starts in the file header. To a standard
070: * TIFF reader, it appears as an unreferenced area in the file.
071: * However, the byte offset of the private IFD is stored as the value
072: * of a private tag, allowing readers that understand the tag to
073: * locate and interpret the IFD. The "TIFF" operation may read the data
074: * at an arbitrary IFD by supplying the offset of the IFD via the
075: * <code>setIFDOffset()</code> method of the <code>TIFFDecodeParam</code>
076: * parameter.
077: *
078: * <p> The third parameter specifies which page of the TIFF data to
079: * read. This permits loading of multi-page TIFF files. The value
080: * provided is zero-relative and so may be interpreted as the index
081: * of the IFD after the first IFD in the stream with zero of course
082: * indicating the first IFD. The default value is zero.
083: *
084: * <p> All pages of a multi-page TIFF stream may also be read by doing the
085: * following:
086: * <pre>
087: * SeekableStream s; // initialization omitted
088: * ParameterBlock pb = new ParameterBlock();
089: * pb.add(s);
090: *
091: * TIFFDecodeParam param = new TIFFDecodeParam();
092: * pb.add(param);
093: *
094: * java.util.ArrayList images = new ArrayList();
095: * long nextOffset = 0;
096: * do {
097: * RenderedOp op = JAI.create("tiff", pb);
098: * images.add(op);
099: * TIFFDirectory dir = (TIFFDirectory)op.getProperty("tiff_directory");
100: * nextOffset = dir.getNextIFDOffset();
101: * if(nextOffset != 0) {
102: * param.setIFDOffset(nextOffset);
103: * }
104: * } while(nextOffset != 0);
105: * </pre>
106: *
107: * <p><b> The classes in the <code>com.sun.media.jai.codec</code>
108: * package are not a committed part of the JAI API. Future releases
109: * of JAI will make use of new classes in their place. This
110: * class will change accordingly.</b>
111: *
112: * <p><table border=1>
113: * <caption>Resource List</caption>
114: * <tr><th>Name</th> <th>Value</th></tr>
115: * <tr><td>GlobalName</td> <td>TIFF</td></tr>
116: * <tr><td>LocalName</td> <td>TIFF</td></tr>
117: * <tr><td>Vendor</td> <td>com.sun.media.jai</td></tr>
118: * <tr><td>Description</td> <td>Reads a TIFF 6.0 file.</td></tr>
119: * <tr><td>DocURL</td> <td>http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/operator/TIFFDescriptor.html</td></tr>
120: * <tr><td>Version</td> <td>1.0</td></tr>
121: * <tr><td>arg0Desc</td> <td>The SeekableStream to read from.</td></tr>
122: * <tr><td>arg1Desc</td> <td>The TIFFDecodeParam to use.</td></tr>
123: * <tr><td>arg2Desc</td> <td>The page to be decoded.</td></tr>
124: * </table></p>
125: * <p><table border=1>
126: * <caption>Parameter List</caption>
127: * <tr><th>Name</th> <th>Class Type</th>
128: * <th>Default Value</th></tr>
129: * <tr><td>stream</td> <td>com.sun.media.jai.codec.SeekableStream</td>
130: * <td>NO_PARAMETER_DEFAULT</td>
131: * <tr><td>param</td> <td>com.sun.media.jai.codec.TIFFDecodeParam</td>
132: * <td>null</td>
133: * <tr><td>page</td> <td>java.lang.Integer</td>
134: * <td>0</td>
135: * </table></p>
136: *
137: * @see com.sun.media.jai.codec.SeekableStream
138: * @see com.sun.media.jai.codec.TIFFDecodeParam
139: * @see com.sun.media.jai.codec.TIFFDirectory
140: * @see com.sun.media.jai.codec.TIFFEncodeParam
141: * @see com.sun.media.jai.codec.TIFFField
142: * @see javax.media.jai.OperationDescriptor
143: * @see javax.media.jai.operator.EncodeDescriptor
144: */
145: public class TIFFDescriptor extends OperationDescriptorImpl {
146:
147: /**
148: * The resource strings that provide the general documentation and
149: * specify the parameter list for the "TIFF" operation.
150: */
151: private static final String[][] resources = {
152: { "GlobalName", "TIFF" },
153: { "LocalName", "TIFF" },
154: { "Vendor", "com.sun.media.jai" },
155: { "Description", JaiI18N.getString("TIFFDescriptor0") },
156: {
157: "DocURL",
158: "http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/operator/TIFFDescriptor.html" },
159: { "Version", JaiI18N.getString("DescriptorVersion") },
160: { "arg0Desc", JaiI18N.getString("TIFFDescriptor1") },
161: { "arg1Desc", JaiI18N.getString("TIFFDescriptor2") },
162: { "arg2Desc", JaiI18N.getString("TIFFDescriptor3") } };
163:
164: /** The parameter names for the "TIFF" operation. */
165: private static final String[] paramNames = { "stream", "param",
166: "page" };
167:
168: /** The parameter class types for the "TIFF" operation. */
169: private static final Class[] paramClasses = {
170: com.sun.media.jai.codec.SeekableStream.class,
171: com.sun.media.jai.codec.TIFFDecodeParam.class,
172: java.lang.Integer.class };
173:
174: /** The parameter default values for the "TIFF" operation. */
175: private static final Object[] paramDefaults = {
176: NO_PARAMETER_DEFAULT, null, new Integer(0) };
177:
178: /** Constructor. */
179: public TIFFDescriptor() {
180: super (resources, 0, paramClasses, paramNames, paramDefaults);
181: }
182:
183: /**
184: * Reads TIFF 6.0 data from an SeekableStream.
185: *
186: * <p>Creates a <code>ParameterBlockJAI</code> from all
187: * supplied arguments except <code>hints</code> and invokes
188: * {@link JAI#create(String,ParameterBlock,RenderingHints)}.
189: *
190: * @see JAI
191: * @see ParameterBlockJAI
192: * @see RenderedOp
193: *
194: * @param stream The SeekableStream to read from.
195: * @param param The TIFFDecodeParam to use.
196: * May be <code>null</code>.
197: * @param page The page to be decoded.
198: * May be <code>null</code>.
199: * @param hints The <code>RenderingHints</code> to use.
200: * May be <code>null</code>.
201: * @return The <code>RenderedOp</code> destination.
202: * @throws IllegalArgumentException if <code>stream</code> is <code>null</code>.
203: */
204: public static RenderedOp create(SeekableStream stream,
205: TIFFDecodeParam param, Integer page, RenderingHints hints) {
206: ParameterBlockJAI pb = new ParameterBlockJAI("TIFF",
207: RenderedRegistryMode.MODE_NAME);
208:
209: pb.setParameter("stream", stream);
210: pb.setParameter("param", param);
211: pb.setParameter("page", page);
212:
213: return JAI.create("TIFF", pb, hints);
214: }
215: }
|