001    /* ColorConvertOp.java --
002       Copyright (C) 2004, 2006  Free Software Foundation
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package java.awt.image;
040    
041    import gnu.java.awt.Buffers;
042    
043    import java.awt.Graphics2D;
044    import java.awt.Point;
045    import java.awt.RenderingHints;
046    import java.awt.color.ColorSpace;
047    import java.awt.color.ICC_ColorSpace;
048    import java.awt.color.ICC_Profile;
049    import java.awt.geom.Point2D;
050    import java.awt.geom.Rectangle2D;
051    
052    /**
053     * ColorConvertOp is a filter for converting images or rasters between
054     * colorspaces, either through a sequence of colorspaces or just from source to
055     * destination.
056     *
057     * Color conversion is done on the color components without alpha.  Thus
058     * if a BufferedImage has alpha premultiplied, this is divided out before
059     * color conversion, and premultiplication applied if the destination
060     * requires it.
061     *
062     * Color rendering and dithering hints may be applied if specified.  This is
063     * likely platform-dependent.
064     *
065     * @author jlquinn@optonline.net
066     */
067    public class ColorConvertOp implements BufferedImageOp, RasterOp
068    {
069      private RenderingHints hints;
070      private ICC_Profile[] profiles = null;
071      private ColorSpace[] spaces;
072    
073    
074      /**
075       * Convert a BufferedImage through a ColorSpace.
076       *
077       * Objects created with this constructor can be used to convert
078       * BufferedImage's to a destination ColorSpace.  Attempts to convert Rasters
079       * with this constructor will result in an IllegalArgumentException when the
080       * filter(Raster, WritableRaster) method is called.
081       *
082       * @param cspace The target color space.
083       * @param hints Rendering hints to use in conversion, if any (may be null)
084       * @throws NullPointerException if the ColorSpace is null.
085       */
086      public ColorConvertOp(ColorSpace cspace, RenderingHints hints)
087      {
088        if (cspace == null)
089          throw new NullPointerException();
090        spaces = new ColorSpace[]{cspace};
091        this.hints = hints;
092      }
093    
094      /**
095       * Convert from a source colorspace to a destination colorspace.
096       *
097       * This constructor takes two ColorSpace arguments as the source and
098       * destination color spaces.  It is usually used with the
099       * filter(Raster, WritableRaster) method, in which case the source colorspace
100       * is assumed to correspond to the source Raster, and the destination
101       * colorspace with the destination Raster.
102       *
103       * If used with BufferedImages that do not match the source or destination
104       * colorspaces specified here, there is an implicit conversion from the
105       * source image to the source ColorSpace, or the destination ColorSpace to
106       * the destination image.
107       *
108       * @param srcCspace The source ColorSpace.
109       * @param dstCspace The destination ColorSpace.
110       * @param hints Rendering hints to use in conversion, if any (may be null).
111       * @throws NullPointerException if any ColorSpace is null.
112       */
113      public ColorConvertOp(ColorSpace srcCspace, ColorSpace dstCspace,
114                            RenderingHints hints)
115      {
116        if (srcCspace == null || dstCspace == null)
117          throw new NullPointerException();
118        spaces = new ColorSpace[]{srcCspace, dstCspace};
119        this.hints = hints;
120      }
121    
122      /**
123       * Convert from a source colorspace to a destinatino colorspace.
124       *
125       * This constructor builds a ColorConvertOp from an array of ICC_Profiles.
126       * The source will be converted through the sequence of color spaces
127       * defined by the profiles.  If the sequence of profiles doesn't give a
128       * well-defined conversion, an IllegalArgumentException is thrown.
129       *
130       * If used with BufferedImages that do not match the source or destination
131       * colorspaces specified here, there is an implicit conversion from the
132       * source image to the source ColorSpace, or the destination ColorSpace to
133       * the destination image.
134       *
135       * For Rasters, the first and last profiles must have the same number of
136       * bands as the source and destination Rasters, respectively.  If this is
137       * not the case, or there fewer than 2 profiles, an IllegalArgumentException
138       * will be thrown.
139       *
140       * @param profiles An array of ICC_Profile's to convert through.
141       * @param hints Rendering hints to use in conversion, if any (may be null).
142       * @throws NullPointerException if the profile array is null.
143       * @throws IllegalArgumentException if the array is not a well-defined
144       *            conversion.
145       */
146      public ColorConvertOp(ICC_Profile[] profiles, RenderingHints hints)
147      {
148        if (profiles == null)
149          throw new NullPointerException();
150    
151        this.hints = hints;
152        this.profiles = profiles;
153    
154        // Create colorspace array with space for src and dest colorspace
155        // Note that the ICC_ColorSpace constructor will throw an
156        // IllegalArgumentException if the profile is invalid; thus we check
157        // for a "well defined conversion"
158        spaces = new ColorSpace[profiles.length];
159        for (int i = 0; i < profiles.length; i++)
160          spaces[i] = new ICC_ColorSpace(profiles[i]);
161      }
162    
163      /**
164       * Convert from source color space to destination color space.
165       *
166       * Only valid for BufferedImage objects, this Op converts from the source
167       * image's color space to the destination image's color space.
168       *
169       * The destination in the filter(BufferedImage, BufferedImage) method cannot
170       * be null for this operation, and it also cannot be used with the
171       * filter(Raster, WritableRaster) method.
172       *
173       * @param hints Rendering hints to use in conversion, if any (may be null).
174       */
175      public ColorConvertOp(RenderingHints hints)
176      {
177        this.hints = hints;
178        spaces = new ColorSpace[0];
179      }
180    
181      /**
182       * Converts the source image using the conversion path specified in the
183       * constructor.  The resulting image is stored in the destination image if one
184       * is provided; otherwise a new BufferedImage is created and returned.
185       *
186       * The source and destination BufferedImage (if one is supplied) must have
187       * the same dimensions.
188       *
189       * @param src The source image.
190       * @param dst The destination image.
191       * @throws IllegalArgumentException if the rasters and/or color spaces are
192       *            incompatible.
193       * @return The transformed image.
194       */
195      public final BufferedImage filter(BufferedImage src, BufferedImage dst)
196      {
197        // TODO: The plan is to create a scanline buffer for intermediate buffers.
198        // For now we just suck it up and create intermediate buffers.
199    
200        if (dst == null && spaces.length == 0)
201          throw new IllegalArgumentException("Not enough color space information "
202                                             + "to complete conversion.");
203    
204        if (dst != null
205            && (src.getHeight() != dst.getHeight() || src.getWidth() != dst.getWidth()))
206          throw new IllegalArgumentException("Source and destination images have "
207                                             + "different dimensions");
208    
209        // Make sure input isn't premultiplied by alpha
210        if (src.isAlphaPremultiplied())
211          {
212            BufferedImage tmp = createCompatibleDestImage(src, src.getColorModel());
213            copyimage(src, tmp);
214            tmp.coerceData(false);
215            src = tmp;
216          }
217    
218        // Convert through defined intermediate conversions
219        BufferedImage tmp;
220        for (int i = 0; i < spaces.length; i++)
221          {
222            if (src.getColorModel().getColorSpace().getType() != spaces[i].getType())
223              {
224                tmp = createCompatibleDestImage(src,
225                                                createCompatibleColorModel(src,
226                                                                           spaces[i]));
227                copyimage(src, tmp);
228                src = tmp;
229              }
230          }
231    
232        // No implicit conversion to destination type needed; return result from the
233        // last intermediate conversions (which was left in src)
234        if (dst == null)
235          dst = src;
236    
237        // Implicit conversion to destination image's color space
238        else
239          copyimage(src, dst);
240    
241        return dst;
242      }
243    
244      /**
245       * Converts the source raster using the conversion path specified in the
246       * constructor.  The resulting raster is stored in the destination raster if
247       * one is provided; otherwise a new WritableRaster is created and returned.
248       *
249       * This operation is not valid with every constructor of this class; see
250       * the constructors for details.  Further, the source raster must have the
251       * same number of bands as the source ColorSpace, and the destination raster
252       * must have the same number of bands as the destination ColorSpace.
253       *
254       * The source and destination raster (if one is supplied) must also have the
255       * same dimensions.
256       *
257       * @param src The source raster.
258       * @param dest The destination raster.
259       * @throws IllegalArgumentException if the rasters and/or color spaces are
260       *            incompatible.
261       * @return The transformed raster.
262       */
263      public final WritableRaster filter(Raster src, WritableRaster dest)
264      {
265        // Various checks to ensure that the rasters and color spaces are compatible
266        if (spaces.length < 2)
267          throw new IllegalArgumentException("Not enough information about " +
268                "source and destination colorspaces.");
269    
270        if (spaces[0].getNumComponents() != src.getNumBands()
271            || (dest != null && spaces[spaces.length - 1].getNumComponents() != dest.getNumBands()))
272          throw new IllegalArgumentException("Source or destination raster " +
273                "contains the wrong number of bands.");
274    
275        if (dest != null
276            && (src.getHeight() != dest.getHeight() || src.getWidth() != dest.getWidth()))
277          throw new IllegalArgumentException("Source and destination rasters " +
278                "have different dimensions");
279    
280        // Need to iterate through each color space.
281        // spaces[0] corresponds to the ColorSpace of the source raster, and
282        // spaces[spaces.length - 1] corresponds to the ColorSpace of the
283        // destination, with any number (or zero) of intermediate conversions.
284    
285        for (int i = 0; i < spaces.length - 2; i++)
286          {
287            WritableRaster tmp = createCompatibleDestRaster(src, spaces[i + 1],
288                                                            false,
289                                                            src.getTransferType());
290            copyraster(src, spaces[i], tmp, spaces[i + 1]);
291            src = tmp;
292          }
293    
294        // The last conversion is done outside of the loop so that we can
295        // use the dest raster supplied, instead of creating our own temp raster
296        if (dest == null)
297          dest = createCompatibleDestRaster(src, spaces[spaces.length - 1], false,
298                                            DataBuffer.TYPE_BYTE);
299        copyraster(src, spaces[spaces.length - 2], dest, spaces[spaces.length - 1]);
300    
301        return dest;
302      }
303    
304      /**
305       * Creates an empty BufferedImage with the size equal to the source and the
306       * correct number of bands for the conversion defined in this Op. The newly
307       * created image is created with the specified ColorModel, or if no ColorModel
308       * is supplied, an appropriate one is chosen.
309       *
310       * @param src The source image.
311       * @param dstCM A color model for the destination image (may be null).
312       * @throws IllegalArgumentException if an appropriate colormodel cannot be
313       *            chosen with the information given.
314       * @return The new compatible destination image.
315       */
316      public BufferedImage createCompatibleDestImage(BufferedImage src,
317                             ColorModel dstCM)
318      {
319        if (dstCM == null && spaces.length == 0)
320          throw new IllegalArgumentException("Don't know the destination " +
321                "colormodel");
322    
323        if (dstCM == null)
324          {
325            dstCM = createCompatibleColorModel(src, spaces[spaces.length - 1]);
326          }
327    
328        return new BufferedImage(dstCM,
329                                 createCompatibleDestRaster(src.getRaster(),
330                                                            dstCM.getColorSpace(),
331                                                            src.getColorModel().hasAlpha,
332                                                            dstCM.getTransferType()),
333                                 src.isPremultiplied, null);
334      }
335    
336      /**
337       * Creates a new WritableRaster with the size equal to the source and the
338       * correct number of bands.
339       *
340       * Note, the new Raster will always use a BYTE storage size, regardless of
341       * the color model or defined destination; this is for compatibility with
342       * the reference implementation.
343       *
344       * @param src The source Raster.
345       * @throws IllegalArgumentException if there isn't enough colorspace
346       *            information to create a compatible Raster.
347       * @return The new compatible destination raster.
348       */
349      public WritableRaster createCompatibleDestRaster(Raster src)
350      {
351        if (spaces.length < 2)
352          throw new IllegalArgumentException("Not enough destination colorspace " +
353                "information");
354    
355        // Create a new raster with the last ColorSpace in the conversion
356        // chain, and with no alpha (implied)
357        return createCompatibleDestRaster(src, spaces[spaces.length-1], false,
358                                          DataBuffer.TYPE_BYTE);
359      }
360    
361      /**
362       * Returns the array of ICC_Profiles used to create this Op, or null if the
363       * Op was created using ColorSpace arguments.
364       *
365       * @return The array of ICC_Profiles, or null.
366       */
367      public final ICC_Profile[] getICC_Profiles()
368      {
369        return profiles;
370      }
371    
372      /**
373       * Returns the rendering hints for this op.
374       *
375       * @return The rendering hints for this Op, or null.
376       */
377      public final RenderingHints getRenderingHints()
378      {
379        return hints;
380      }
381    
382      /**
383       * Returns the corresponding destination point for a source point.
384       * Because this is not a geometric operation, the destination and source
385       * points will be identical.
386       *
387       * @param src The source point.
388       * @param dst The transformed destination point.
389       * @return The transformed destination point.
390       */
391      public final Point2D getPoint2D(Point2D src, Point2D dst)
392      {
393        if (dst == null)
394          return (Point2D)src.clone();
395    
396        dst.setLocation(src);
397        return dst;
398      }
399    
400      /**
401       * Returns the corresponding destination boundary of a source boundary.
402       * Because this is not a geometric operation, the destination and source
403       * boundaries will be identical.
404       *
405       * @param src The source boundary.
406       * @return The boundaries of the destination.
407       */
408      public final Rectangle2D getBounds2D(BufferedImage src)
409      {
410        return src.getRaster().getBounds();
411      }
412    
413      /**
414       * Returns the corresponding destination boundary of a source boundary.
415       * Because this is not a geometric operation, the destination and source
416       * boundaries will be identical.
417       *
418       * @param src The source boundary.
419       * @return The boundaries of the destination.
420       */
421      public final Rectangle2D getBounds2D(Raster src)
422      {
423        return src.getBounds();
424      }
425    
426      /**
427       * Copy a source image to a destination image, respecting their colorspaces
428       * and performing colorspace conversions if necessary.
429       *
430       * @param src The source image.
431       * @param dst The destination image.
432       */
433      private void copyimage(BufferedImage src, BufferedImage dst)
434      {
435        // This is done using Graphics2D in order to respect the rendering hints.
436        Graphics2D gg = dst.createGraphics();
437    
438        // If no hints are set there is no need to call
439        // setRenderingHints on the Graphics2D object.
440        if (hints != null)
441          gg.setRenderingHints(hints);
442    
443        gg.drawImage(src, 0, 0, null);
444        gg.dispose();
445      }
446    
447      /**
448       * Copy a source raster to a destination raster, performing a colorspace
449       * conversion between the two.  The conversion will respect the
450       * KEY_COLOR_RENDERING rendering hint if one is present.
451       *
452       * @param src The source raster.
453       * @param scs The colorspace of the source raster.
454       * @dst The destination raster.
455       * @dcs The colorspace of the destination raster.
456       */
457      private void copyraster(Raster src, ColorSpace scs, WritableRaster dst, ColorSpace dcs)
458      {
459        float[] sbuf = new float[src.getNumBands()];
460    
461        if (hints != null
462            && hints.get(RenderingHints.KEY_COLOR_RENDERING) ==
463                     RenderingHints.VALUE_COLOR_RENDER_QUALITY)
464        {
465          // use cie for accuracy
466          for (int y = src.getMinY(); y < src.getHeight() + src.getMinY(); y++)
467            for (int x = src.getMinX(); x < src.getWidth() + src.getMinX(); x++)
468              dst.setPixel(x, y,
469                           dcs.fromCIEXYZ(scs.toCIEXYZ(src.getPixel(x, y, sbuf))));
470        }
471        else
472        {
473          // use rgb - it's probably faster
474          for (int y = src.getMinY(); y < src.getHeight() + src.getMinY(); y++)
475            for (int x = src.getMinX(); x < src.getWidth() + src.getMinX(); x++)
476              dst.setPixel(x, y,
477                           dcs.fromRGB(scs.toRGB(src.getPixel(x, y, sbuf))));
478        }
479      }
480    
481      /**
482       * This method creates a color model with the same colorspace and alpha
483       * settings as the source image.  The created color model will always be a
484       * ComponentColorModel and have a BYTE transfer type.
485       *
486       * @param img The source image.
487       * @param cs The ColorSpace to use.
488       * @return A color model compatible with the source image.
489       */
490      private ColorModel createCompatibleColorModel(BufferedImage img, ColorSpace cs)
491      {
492        // The choice of ComponentColorModel and DataBuffer.TYPE_BYTE is based on
493        // Mauve testing of the reference implementation.
494        return new ComponentColorModel(cs,
495                                       img.getColorModel().hasAlpha(),
496                                       img.isAlphaPremultiplied(),
497                                       img.getColorModel().getTransparency(),
498                                       DataBuffer.TYPE_BYTE);
499      }
500    
501      /**
502       * This method creates a compatible Raster, given a source raster, colorspace,
503       * alpha value, and transfer type.
504       *
505       * @param src The source raster.
506       * @param cs The ColorSpace to use.
507       * @param hasAlpha Whether the raster should include a component for an alpha.
508       * @param transferType The size of a single data element.
509       * @return A compatible WritableRaster.
510       */
511      private WritableRaster createCompatibleDestRaster(Raster src, ColorSpace cs,
512                                                        boolean hasAlpha,
513                                                        int transferType)
514      {
515        // The use of a PixelInterleavedSampleModel weas determined using mauve
516        // tests, based on the reference implementation
517    
518        int numComponents = cs.getNumComponents();
519        if (hasAlpha)
520          numComponents++;
521    
522        int[] offsets = new int[numComponents];
523        for (int i = 0; i < offsets.length; i++)
524          offsets[i] = i;
525    
526        DataBuffer db = Buffers.createBuffer(transferType,
527                                             src.getWidth() * src.getHeight() * numComponents,
528                                             1);
529        return new WritableRaster(new PixelInterleavedSampleModel(transferType,
530                                                                  src.getWidth(),
531                                                                  src.getHeight(),
532                                                                  numComponents,
533                                                                  numComponents * src.getWidth(),
534                                                                  offsets),
535                                  db, new Point(src.getMinX(), src.getMinY()));
536      }
537    }