001: /*
002: * $RCSfile: ConvolveDescriptor.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:32 $
010: * $State: Exp $
011: */
012: package javax.media.jai.operator;
013:
014: import com.sun.media.jai.util.AreaOpPropertyGenerator;
015: import java.awt.RenderingHints;
016: import java.awt.image.RenderedImage;
017: import javax.media.jai.JAI;
018: import javax.media.jai.KernelJAI;
019: import javax.media.jai.OperationDescriptorImpl;
020: import javax.media.jai.ParameterBlockJAI;
021: import javax.media.jai.PropertyGenerator;
022: import javax.media.jai.RenderedOp;
023: import javax.media.jai.registry.RenderedRegistryMode;
024:
025: /**
026: * An <code>OperationDescriptor</code> describing the "Convolve" operation.
027: *
028: * <p> Convolution is a spatial operation that computes each output
029: * sample by multiplying elements of a kernel with the samples
030: * surrounding a particular source sample.
031: *
032: * <p> For each destination sample, the kernel is rotated 180 degrees
033: * and its "key element," or origin, is placed over the source pixel
034: * corresponding with the destination pixel. The kernel elements are
035: * multiplied with the source pixels beneath them, and the resulting
036: * products are summed together to produce the destination sample
037: * value.
038: *
039: * <p> Pseudocode for the convolution operation on a single sample
040: * dst[x][y] is as follows, assuming the kernel is of size width x height
041: * and has already been rotated through 180 degrees. The kernel's Origin
042: * element is located at position (xOrigin, yOrigin):
043: *
044: * <pre>
045: * dst[x][y] = 0;
046: * for (int i = -xOrigin; i < -xOrigin + width; i++) {
047: * for (int j = -yOrigin; j < -yOrigin + height; j++) {
048: * dst[x][y] += src[x + i][y + j]*kernel[xOrigin + i][yOrigin + j];
049: * }
050: * }
051: * </pre>
052: *
053: * <p> Convolution, like any neighborhood operation, leaves a band of
054: * pixels around the edges undefined. For example, for a 3x3 kernel
055: * only four kernel elements and four source pixels contribute to the
056: * convolution pixel at the corners of the source image. Pixels that
057: * do not allow the full kernel to be applied to the source are not
058: * included in the destination image. A "Border" operation may be used
059: * to add an appropriate border to the source image in order to avoid
060: * shrinkage of the image boundaries.
061: *
062: * <p> The kernel may not be bigger in any dimension than the image data.
063: *
064: * It should be noted that this operation automatically adds a
065: * value of <code>Boolean.TRUE</code> for the
066: * <code>JAI.KEY_REPLACE_INDEX_COLOR_MODEL</code> to the given
067: * <code>configuration</code> so that the operation is performed
068: * on the pixel values instead of being performed on the indices into
069: * the color map if the source(s) have an <code>IndexColorModel</code>.
070: * This addition will take place only if a value for the
071: * <code>JAI.KEY_REPLACE_INDEX_COLOR_MODEL</code> has not already been
072: * provided by the user. Note that the <code>configuration</code> Map
073: * is cloned before the new hint is added to it. The operation can be
074: * smart about the value of the <code>JAI.KEY_REPLACE_INDEX_COLOR_MODEL</code>
075: * <code>RenderingHints</code>, i.e. while the default value for the
076: * <code>JAI.KEY_REPLACE_INDEX_COLOR_MODEL</code> is
077: * <code>Boolean.TRUE</code>, in some cases the operator could set the
078: * default.
079: *
080: * <p><table border=1>
081: * <caption>Resource List</caption>
082: * <tr><th>Name</th> <th>Value</th></tr>
083: * <tr><td>GlobalName</td> <td>Convolve</td></tr>
084: * <tr><td>LocalName</td> <td>Convolve</td></tr>
085: * <tr><td>Vendor</td> <td>com.sun.media.jai</td></tr>
086: * <tr><td>Description</td> <td>Performs kernel-based convolution
087: * on an image.</td></tr>
088: * <tr><td>DocURL</td> <td>http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/operator/ConvolveDescriptor.html</td></tr>
089: * <tr><td>Version</td> <td>1.0</td></tr>
090: * <tr><td>arg0Desc</td> <td>The convolution kernel.</td></tr>
091: * </table></p>
092: *
093: * <p><table border=1>
094: * <caption>Parameter List</caption>
095: * <tr><th>Name</th> <th>Class Type</th>
096: * <th>Default Value</th></tr>
097: * <tr><td>kernel</td> <td>javax.media.jai.KernelJAI</td>
098: * <td>NO_PARAMETER_DEFAULT</td>
099: * </table></p>
100: *
101: * @see javax.media.jai.OperationDescriptor
102: * @see javax.media.jai.KernelJAI
103: */
104: public class ConvolveDescriptor extends OperationDescriptorImpl {
105:
106: /**
107: * The resource strings that provide the general documentation and
108: * specify the parameter list for a Convolve operation.
109: */
110: private static final String[][] resources = {
111: { "GlobalName", "Convolve" },
112: { "LocalName", "Convolve" },
113: { "Vendor", "com.sun.media.jai" },
114: { "Description", JaiI18N.getString("ConvolveDescriptor0") },
115: {
116: "DocURL",
117: "http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/operator/ConvolveDescriptor.html" },
118: { "Version", JaiI18N.getString("DescriptorVersion") },
119: { "arg0Desc", JaiI18N.getString("ConvolveDescriptor1") } };
120:
121: /** The parameter names for the Convolve operation. */
122: private static final String[] paramNames = { "kernel" };
123:
124: /** The parameter class types for the Convolve operation. */
125: private static final Class[] paramClasses = { javax.media.jai.KernelJAI.class };
126:
127: /** The parameter default values for the Convolve operation. */
128: private static final Object[] paramDefaults = { NO_PARAMETER_DEFAULT };
129:
130: /** Constructor. */
131: public ConvolveDescriptor() {
132: super (resources, 1, paramClasses, paramNames, paramDefaults);
133: }
134:
135: /**
136: * Returns an array of <code>PropertyGenerators</code> implementing
137: * property inheritance for the "Convolve" operation.
138: *
139: * @return An array of property generators.
140: */
141: public PropertyGenerator[] getPropertyGenerators() {
142: PropertyGenerator[] pg = new PropertyGenerator[1];
143: pg[0] = new AreaOpPropertyGenerator();
144: return pg;
145: }
146:
147: /**
148: * Performs kernel-based convolution on an image.
149: *
150: * <p>Creates a <code>ParameterBlockJAI</code> from all
151: * supplied arguments except <code>hints</code> and invokes
152: * {@link JAI#create(String,ParameterBlock,RenderingHints)}.
153: *
154: * @see JAI
155: * @see ParameterBlockJAI
156: * @see RenderedOp
157: *
158: * @param source0 <code>RenderedImage</code> source 0.
159: * @param kernel The convolution kernel.
160: * @param hints The <code>RenderingHints</code> to use.
161: * May be <code>null</code>.
162: * @return The <code>RenderedOp</code> destination.
163: * @throws IllegalArgumentException if <code>source0</code> is <code>null</code>.
164: * @throws IllegalArgumentException if <code>kernel</code> is <code>null</code>.
165: */
166: public static RenderedOp create(RenderedImage source0,
167: KernelJAI kernel, RenderingHints hints) {
168: ParameterBlockJAI pb = new ParameterBlockJAI("Convolve",
169: RenderedRegistryMode.MODE_NAME);
170:
171: pb.setSource("source0", source0);
172:
173: pb.setParameter("kernel", kernel);
174:
175: return JAI.create("Convolve", pb, hints);
176: }
177: }
|