001: /*
002: * $RCSfile: DilateDescriptor.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:34 $
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 "Dilate" operation.
027: *
028: * Dilation for gray scale images can be charaterized by "slide, add and max",
029: * while for binary images by "slide and set". As always, the kernel
030: * is expected to come with a key position.
031: *
032: * <p> Dilation, unlike convolution and most neighborhood operations,
033: * actually can grow the image region. But to conform with other
034: * image neighborhood operations, the border pixels are set to 0.
035: * For a 3 x 3 kernel with the key point at the center, there will
036: * be a pixel wide 0 stripe around the border.
037: *
038: * <p>When applied to multi-band images the dilation operator processes
039: * each band independently using the methodology which would be applied
040: * to single band images of the same data type.
041: *
042: * <p> <b> Gray scale dilation</b> is a spatial operation that computes
043: * each output sample by adding elements of a kernel to the samples
044: * surrounding a particular source sample and taking the maximum.
045: * A mathematical expression is:
046: *
047: * <p> For a kernel K with a key position (xKey,yKey), the dilation
048: * of image I at (x,y) is given by:
049: * <pre>
050: * max{ I(x-i, y-j) + K(xKey+i, yKey+j): some (i,j) restriction }
051: *
052: * where the (i,j) restriction means:
053: * all possible (i,j) so that both I(x-i,y-j) and K(xKey+i, yKey+j)
054: * are defined, that is, these indices are in bounds.
055: *
056: * </pre>
057: * <p>Intuitively in 2D, the kernel is like
058: * an umbrella and the key point is the handle. When the handle moves
059: * all over the image surface, the upper outbounds of all the umbrella
060: * positions is the dilation. Thus if you want the image to dilate in
061: * the upper right direction, the following kernel would do with
062: * the bold face key position.
063: *
064: * <p><center>
065: * <table border=1>
066: * <tr align=center><td>0</td><td>0</td><td>50</td> </tr>
067: * <tr align=center><td>0</td><td>50</td><td>0</td> </tr>
068: * <tr align=center><td><b>0</b></td><td>0</td><td>0</td> </tr>
069: * </table></center>
070: *
071: * <p> Note also that zero kernel have effects on the dilation!
072: * That is because of the "max" in the add and max process. Thus
073: * a 3 x 1 zero kernel with the key position at the bottom of the kernel
074: * dilates the image upwards.
075: *
076: * <p>
077: * After the kernel is rotated 180 degrees, Pseudo code for dilation operation
078: * is as follows. Of course, you should provide the kernel in its
079: * (unrotated) original form. Assuming the kernel K is of size M rows x N cols
080: * and the key position is (xKey, yKey).
081: *
082: * <pre>
083: * // gray-scale dilation:
084: * for every dst pixel location (x,y){
085: * dst[x][y] = -infinity;
086: * for (i = -xKey; i < M - xKey; i++){
087: * for (j = -yKey; j < N - yKey; j++){
088: * if((x+i, y+j) are in bounds of src &&
089: * (xKey+i, yKey+j) are in bounds of K){
090: * tmp = src[x + i][y + j]+ K[xKey + i][yKey + j];
091: * dst[x][y] = max{tmp, dst[x][y]};
092: * }
093: * }
094: * }
095: * }
096: * </pre>
097: *
098: * <p> The kernel cannot be bigger in any dimension than the image data.
099: *
100: * <p> <b>Binary Image Dilation</b>
101: * requires the kernel K to be binary, that is, have values 0 or 1
102: * for all kernel entries.
103: * Intuitively, starting from dst image being a duplicate of src,
104: * binary dilation slides the kernel K to place the key position
105: * at every non-zero point (x,y) in src image and set dst positions
106: * under ones of K to 1.
107: *
108: * <p> After the kernel is rotated 180 degrees, the pseudo code for
109: * dilation operation is as follows. (Of course, you should provide
110: * the kernel in its original unrotated form.)
111: *
112: * <pre>
113: *
114: * // binary dilation
115: * for every dst pixel location (x,y){
116: * dst[x][y] = src[x][y];
117: * for (i = -xKey; i < M - xKey; i++){
118: * for (j = -yKey; j < N - yKey; j++){
119: * if(src[x+i,y+i]==1 && Key(xKey+i, yKey+j)==1){
120: * dst[x][y] = 1; break;
121: * }
122: * }
123: * }
124: * }
125: *
126: * It should be noted that this operation automatically adds a
127: * value of <code>Boolean.TRUE</code> for the
128: * <code>JAI.KEY_REPLACE_INDEX_COLOR_MODEL</code> to the given
129: * <code>configuration</code> so that the operation is performed
130: * on the pixel values instead of being performed on the indices into
131: * the color map if the source(s) have an <code>IndexColorModel</code>.
132: * This addition will take place only if a value for the
133: * <code>JAI.KEY_REPLACE_INDEX_COLOR_MODEL</code> has not already been
134: * provided by the user. Note that the <code>configuration</code> Map
135: * is cloned before the new hint is added to it. The operation can be
136: * smart about the value of the <code>JAI.KEY_REPLACE_INDEX_COLOR_MODEL</code>
137: * <code>RenderingHints</code>, i.e. while the default value for the
138: * <code>JAI.KEY_REPLACE_INDEX_COLOR_MODEL</code> is
139: * <code>Boolean.TRUE</code>, in some cases the operator could set the
140: * default.
141: *
142: * <p><table border=1>
143: * <caption>Resource List</caption>
144: * <tr><th>Name</th> <th>Value</th></tr>
145: * <tr><td>GlobalName</td> <td>Dilate</td></tr>
146: * <tr><td>LocalName</td> <td>Dilate</td></tr>
147: * <tr><td>Vendor</td> <td>com.sun.media.jai</td></tr>
148: * <tr><td>Description</td> <td>Performs kernel based Dilate on
149: * an image.</td></tr>
150: * <tr><td>DocURL</td> <td>http://java.sun.com/products/java-media/jai/forD
151: evelopers/jai-apidocs/javax/media/jai/operator/DilateDescriptor.html</td
152: ></tr>
153: * <tr><td>Version</td> <td>1.1</td></tr>
154: * <tr><td>arg0Desc</td> <td>The dilate kernel.</td></tr>
155: * </table></p>
156: *
157: * <p><table border=1>
158: * <caption>Parameter List</caption>
159: * <tr><th>Name</th> <th>Class Type</th>
160: * <th>Default Value</th></tr>
161: * <tr><td>kernel</td> <td>javax.media.jai.KernelJAI</td>
162: * <td>NO_PARAMETER_DEFAULT</td>
163: * </table></p>
164: *
165: * </pre>
166: * <p> Reference: An Introduction to Nonlinear Image Processing,
167: * by Edward R. Bougherty and Jaakko Astola,
168: * Spie Optical Engineering Press, 1994.
169: *
170: * @see javax.media.jai.OperationDescriptor
171: * @see javax.media.jai.KernelJAI
172: * @see javax.media.jai.operator.ErodeDescriptor
173: *
174: * @since JAI 1.1
175: */
176: public class DilateDescriptor extends OperationDescriptorImpl {
177:
178: /**
179: * The resource strings that provide the general documentation and
180: * specify the parameter list for a Dilate operation.
181: */
182: private static final String[][] resources = {
183: { "GlobalName", "Dilate" },
184: { "LocalName", "Dilate" },
185: { "Vendor", "com.sun.media.jai" },
186: { "Description", JaiI18N.getString("DilateDescriptor0") },
187: {
188: "DocURL",
189: "http://java.sun.com/products/java-media/jai/forDevelopers/jaiapi/<br>javax.media.jai.operator.DilateDescriptor.html" },
190: { "Version", JaiI18N.getString("DescriptorVersion") },
191: { "arg0Desc", JaiI18N.getString("DilateDescriptor1") } };
192:
193: /** The parameter names for the Dilate operation. */
194: private static final String[] paramNames = { "kernel" };
195:
196: /** The parameter class types for the Dilate operation. */
197: private static final Class[] paramClasses = { javax.media.jai.KernelJAI.class };
198:
199: /** The parameter default values for the Dilate operation. */
200: private static final Object[] paramDefaults = { NO_PARAMETER_DEFAULT };
201:
202: /** Constructor. */
203: public DilateDescriptor() {
204: super (resources, 1, paramClasses, paramNames, paramDefaults);
205: }
206:
207: /**
208: * Returns an array of <code>PropertyGenerators</code> implementing
209: * property inheritance for the "Dilate" operation.
210: *
211: * @return An array of property generators.
212: */
213: public PropertyGenerator[] getPropertyGenerators() {
214: PropertyGenerator[] pg = new PropertyGenerator[1];
215: pg[0] = new AreaOpPropertyGenerator();
216: return pg;
217: }
218:
219: /**
220: * Performs binary kernel based Dilate operation on the image.
221: *
222: * <p>Creates a <code>ParameterBlockJAI</code> from all
223: * supplied arguments except <code>hints</code> and invokes
224: * {@link JAI#create(String,ParameterBlock,RenderingHints)}.
225: *
226: * @see JAI
227: * @see ParameterBlockJAI
228: * @see RenderedOp
229: *
230: * @param source0 <code>RenderedImage</code> source 0.
231: * @param kernel The binary convolution kernel.
232: * @param hints The <code>RenderingHints</code> to use.
233: * May be <code>null</code>.
234: * @return The <code>RenderedOp</code> destination.
235: * @throws IllegalArgumentException if <code>source0</code> is <code>null</code>.
236: * @throws IllegalArgumentException if <code>kernel</code> is <code>null</code>.
237: */
238: public static RenderedOp create(RenderedImage source0,
239: KernelJAI kernel, RenderingHints hints) {
240: ParameterBlockJAI pb = new ParameterBlockJAI("Dilate",
241: RenderedRegistryMode.MODE_NAME);
242:
243: pb.setSource("source0", source0);
244:
245: pb.setParameter("kernel", kernel);
246:
247: return JAI.create("Dilate", pb, hints);
248: }
249: }
|