001: /*
002: * $RCSfile: UnsharpMaskDescriptor.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:46 $
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: * <p>An <code>OperationDescriptor</code> describing the "UnsharpMask" operation.
027: *
028: * <p> Unsharp masking is derived from a photographic technique for
029: * improving the sharpness of images. In its digital form it is implemented
030: * using convolution to create a low-pass filtered version of a source image.
031: * The low-pass image is then subtracted from the original image,
032: * creating a high-pass image. The high pass image is then added back
033: * to the original image, creating enhanced edge contrast. By adjusting
034: * a scaling factor, the degree of high pass add-back can be controlled.
035: *
036: * <p>The operation is implemented algorithmically as follows. At each
037: * original pixel location x,y:
038: *
039: * <pre>
040: * result = original + (original - lowpass) * gainFactor
041: *
042: * where
043: * original = value at position x,y of source image
044: * lowpass = result of convolution with lowpass filter
045: * centered at pixel x,y
046: * gain = controlling parameter for degree of sharpness
047: * gain = 0 : no effect
048: * gain > 0 : sharpening
049: * -1 < gain < 0 : smoothing
050: * </pre>
051: * <p> In general gain factors should be restricted to a range of
052: * [-1, 2], as higher magnitude values are likely to cause
053: * overflows or underflows which must be clamped to the image
054: * data type's range.
055: *
056: * <p> The default gain factor is set to <code>1,0F</code>.
057: *
058: * <p> This operation is widely applied to scanned image enhancement.
059: * The typical gain factor for scanned images takes values in the range
060: * of [1/4, 2] (page 278 in Digital Image Processing by William
061: * K. Pratt, 3rd).
062: *
063: * <p><table border=1>
064: * <caption>Resource List</caption>
065: * <tr><th>Name</th> <th>Value</th></tr>
066: * <tr><td>GlobalName</td> <td>UnsharpMask</td></tr>
067: * <tr><td>LocalName</td> <td>UnsharpMask</td></tr>
068: * <tr><td>Vendor</td> <td>com.sun.media.jai</td></tr>
069: * <tr><td>Description</td> <td>Performs unsharp masking to sharpen or smooth
070: * an image.</td></tr>
071: * <tr><td>DocURL</td> <td>http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/operator/UnsharpMaskDescriptor.html</td></tr>
072: * <tr><td>Version</td> <td>1.1</td></tr>
073: * <tr><td>arg0Desc</td> <td>The convolution kernel.</td></tr>
074: * <tr><td>arg1Desc</td> <td>The gain factor.</td></tr>
075: * </table></p>
076: *
077: * <p><table border=1>
078: * <caption>Parameter List</caption>
079: * <tr><th>Name</th> <th>Class Type</th>
080: * <th>Default Value</th></tr>
081: * <tr><td>kernel</td> <td>javax.media.jai.KernelJAI</td>
082: * <td>3 X 3 average</td>
083: * <tr><td>gain</td> <td>java.lang.Float</td>
084: * <td>1.0F</td>
085: * </table></p>
086: *
087: * @see javax.media.jai.OperationDescriptor
088: * @see javax.media.jai.KernelJAI
089: * @see javax.media.jai.operator.ConvolveDescriptor
090: *
091: * @since JAI 1.1
092: */
093: public class UnsharpMaskDescriptor extends OperationDescriptorImpl {
094:
095: /**
096: * The resource strings that provide the general documentation and
097: * specify the parameter list for a UnsharpMask operation.
098: */
099: private static final String[][] resources = {
100: { "GlobalName", "UnsharpMask" },
101: { "LocalName", "UnsharpMask" },
102: { "Vendor", "com.sun.media.jai" },
103: { "Description",
104: JaiI18N.getString("UnsharpMaskDescriptor0") },
105: {
106: "DocURL",
107: "http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/operator/UnsharpMaskDescriptor.html" },
108: { "Version", JaiI18N.getString("DescriptorVersion") },
109: { "arg0Desc", JaiI18N.getString("UnsharpMaskDescriptor1") },
110: { "arg1Desc", JaiI18N.getString("UnsharpMaskDescriptor2") } };
111:
112: /** The parameter names for the UnsharpMask operation. */
113: private static final String[] paramNames = { "kernel", "gain" };
114:
115: /** The parameter class types for the UnsharpMask operation. */
116: private static final Class[] paramClasses = {
117: javax.media.jai.KernelJAI.class, java.lang.Float.class };
118:
119: /** The parameter default values for the UnsharpMask operation. */
120: private static final Object[] paramDefaults = {
121: new KernelJAI(3, 3, 1, 1, new float[] { 1 / 9F, 1 / 9F,
122: 1 / 9F, 1 / 9F, 1 / 9F, 1 / 9F, 1 / 9F, 1 / 9F,
123: 1 / 9F }), new Float(1.0F) };
124:
125: /** Constructor. */
126: public UnsharpMaskDescriptor() {
127: super (resources, 1, paramClasses, paramNames, paramDefaults);
128: }
129:
130: /**
131: * Returns an array of <code>PropertyGenerators</code> implementing
132: * property inheritance for the "UnsharpMask" operation.
133: *
134: * @return An array of property generators.
135: */
136: public PropertyGenerator[] getPropertyGenerators() {
137: PropertyGenerator[] pg = new PropertyGenerator[1];
138: pg[0] = new AreaOpPropertyGenerator();
139: return pg;
140: }
141:
142: /**
143: * Performs UnsharpMask operation on the image.
144: *
145: * <p>Creates a <code>ParameterBlockJAI</code> from all
146: * supplied arguments except <code>hints</code> and invokes
147: * {@link JAI#create(String,ParameterBlock,RenderingHints)}.
148: *
149: * @see JAI
150: * @see ParameterBlockJAI
151: * @see RenderedOp
152: *
153: * @param source0 <code>RenderedImage</code> source 0.
154: * @param kernel The low-pass convolution kernel.
155: * May be <code>null</code>.
156: * @param gain The sharpening value.
157: * May be <code>null</code>.
158: * @param hints The <code>RenderingHints</code> to use.
159: * May be <code>null</code>.
160: * @return The <code>RenderedOp</code> destination.
161: * @throws IllegalArgumentException if <code>source0</code> is <code>null</code>.
162: */
163: public static RenderedOp create(RenderedImage source0,
164: KernelJAI kernel, Float gain, RenderingHints hints) {
165: ParameterBlockJAI pb = new ParameterBlockJAI("UnsharpMask",
166: RenderedRegistryMode.MODE_NAME);
167:
168: pb.setSource("source0", source0);
169:
170: pb.setParameter("kernel", kernel);
171: pb.setParameter("gain", gain);
172:
173: return JAI.create("UnsharpMask", pb, hints);
174: }
175: }
|