ColorSpace


1   /*
2    * @(#)ColorSpace.java  1.40 05/10/26
3    *
4    * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   /**********************************************************************
9    **********************************************************************
10   **********************************************************************
11   *** COPYRIGHT (c) Eastman Kodak Company, 1997                      ***
12   *** As  an unpublished  work pursuant to Title 17 of the United    ***
13   *** States Code.  All rights reserved.                             ***
14   **********************************************************************
15   **********************************************************************
16   **********************************************************************/
17  
18  package java.awt.color;
19  
20  import sun.awt.color.CMM;
21  
22  
23  /**
24   * This abstract class is used to serve as a color space tag to identify the
25   * specific color space of a Color object or, via a ColorModel object,
26   * of an Image, a BufferedImage, or a GraphicsDevice.  It contains
27   * methods that transform colors in a specific color space to/from sRGB
28   * and to/from a well-defined CIEXYZ color space.
29   * <p>
30   * For purposes of the methods in this class, colors are represented as
31   * arrays of color components represented as floats in a normalized range
32   * defined by each ColorSpace.  For many ColorSpaces (e.g. sRGB), this
33   * range is 0.0 to 1.0.  However, some ColorSpaces have components whose
34   * values have a different range.  Methods are provided to inquire per
35   * component minimum and maximum normalized values.
36   * <p>
37   * Several variables are defined for purposes of referring to color
38   * space types (e.g. TYPE_RGB, TYPE_XYZ, etc.) and to refer to specific
39   * color spaces (e.g. CS_sRGB and CS_CIEXYZ).
40   * sRGB is a proposed standard RGB color space.  For more information,
41   * see <A HREF="http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html">
42   * http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html
43   * </A>.
44   * <p>
45   * The purpose of the methods to transform to/from the well-defined
46   * CIEXYZ color space is to support conversions between any two color
47   * spaces at a reasonably high degree of accuracy.  It is expected that
48   * particular implementations of subclasses of ColorSpace (e.g.
49   * ICC_ColorSpace) will support high performance conversion based on
50   * underlying platform color management systems.
51   * <p>
52   * The CS_CIEXYZ space used by the toCIEXYZ/fromCIEXYZ methods can be
53   * described as follows:
54  <pre>
55  
56  &nbsp;     CIEXYZ
57  &nbsp;     viewing illuminance: 200 lux
58  &nbsp;     viewing white point: CIE D50
59  &nbsp;     media white point: "that of a perfectly reflecting diffuser" -- D50 
60  &nbsp;     media black point: 0 lux or 0 Reflectance
61  &nbsp;     flare: 1 percent
62  &nbsp;     surround: 20percent of the media white point
63  &nbsp;     media description: reflection print (i.e., RLAB, Hunt viewing media)
64  &nbsp;     note: For developers creating an ICC profile for this conversion
65  &nbsp;           space, the following is applicable.  Use a simple Von Kries
66  &nbsp;           white point adaptation folded into the 3X3 matrix parameters
67  &nbsp;           and fold the flare and surround effects into the three
68  &nbsp;           one-dimensional lookup tables (assuming one uses the minimal
69  &nbsp;           model for monitors).
70  
71  </pre>
72   *
73   * <p>
74   * @see ICC_ColorSpace
75   * @version 10 Feb 1997
76   */
77  
78  
79  
80  public abstract class ColorSpace implements java.io.Serializable   {
81  
82      static final long serialVersionUID = -409452704308689724L;
83  
84      private int type;
85      private int numComponents;
86  
87      // Cache of singletons for the predefined color spaces.
88      private static ColorSpace   sRGBspace;
89      private static ColorSpace   XYZspace;
90      private static ColorSpace   PYCCspace;
91      private static ColorSpace   GRAYspace;
92      private static ColorSpace   LINEAR_RGBspace;
93      
94      /**
95       * Any of the family of XYZ color spaces.
96       */
97      public static final int TYPE_XYZ = 0;
98  
99      /**
100      * Any of the family of Lab color spaces.
101      */
102     public static final int TYPE_Lab = 1;
103 
104     /**
105      * Any of the family of Luv color spaces.
106      */
107     public static final int TYPE_Luv = 2;
108 
109     /**
110      * Any of the family of YCbCr color spaces.
111      */
112     public static final int TYPE_YCbCr = 3;
113 
114     /**
115      * Any of the family of Yxy color spaces.
116      */
117     public static final int TYPE_Yxy = 4;
118 
119     /**
120      * Any of the family of RGB color spaces.
121      */
122     public static final int TYPE_RGB = 5;
123 
124     /**
125      * Any of the family of GRAY color spaces.
126      */
127     public static final int TYPE_GRAY = 6;
128 
129     /**
130      * Any of the family of HSV color spaces.
131      */
132     public static final int TYPE_HSV = 7;
133 
134     /**
135      * Any of the family of HLS color spaces.
136      */
137     public static final int TYPE_HLS = 8;
138 
139     /**
140      * Any of the family of CMYK color spaces.
141      */
142     public static final int TYPE_CMYK = 9;
143 
144     /**
145      * Any of the family of CMY color spaces.
146      */
147     public static final int TYPE_CMY = 11;
148 
149     /**
150      * Generic 2 component color spaces.
151      */
152     public static final int TYPE_2CLR = 12;
153 
154     /**
155      * Generic 3 component color spaces.
156      */
157     public static final int TYPE_3CLR = 13;
158 
159     /**
160      * Generic 4 component color spaces.
161      */
162     public static final int TYPE_4CLR = 14;
163 
164     /**
165      * Generic 5 component color spaces.
166      */
167     public static final int TYPE_5CLR = 15;
168 
169     /**
170      * Generic 6 component color spaces.
171      */
172     public static final int TYPE_6CLR = 16;
173 
174     /**
175      * Generic 7 component color spaces.
176      */
177     public static final int TYPE_7CLR = 17;
178 
179     /**
180      * Generic 8 component color spaces.
181      */
182     public static final int TYPE_8CLR = 18;
183 
184     /**
185      * Generic 9 component color spaces.
186      */
187     public static final int TYPE_9CLR = 19;
188 
189     /**
190      * Generic 10 component color spaces.
191      */
192     public static final int TYPE_ACLR = 20;
193 
194     /**
195      * Generic 11 component color spaces.
196      */
197     public static final int TYPE_BCLR = 21;
198 
199     /**
200      * Generic 12 component color spaces.
201      */
202     public static final int TYPE_CCLR = 22;
203 
204     /**
205      * Generic 13 component color spaces.
206      */
207     public static final int TYPE_DCLR = 23;
208 
209     /**
210      * Generic 14 component color spaces.
211      */
212     public static final int TYPE_ECLR = 24;
213 
214     /**
215      * Generic 15 component color spaces.
216      */
217     public static final int TYPE_FCLR = 25;
218 
219     /**
220      * The sRGB color space defined at
221      * <A HREF="http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html">
222      * http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html
223      * </A>.
224      */
225     public static final int CS_sRGB = 1000;
226 
227     /**
228      * A built-in linear RGB color space.  This space is based on the
229      * same RGB primaries as CS_sRGB, but has a linear tone reproduction curve.
230      */
231     public static final int CS_LINEAR_RGB = 1004;
232 
233     /**
234      * The CIEXYZ conversion color space defined above.
235      */
236     public static final int CS_CIEXYZ = 1001;
237 
238     /**
239      * The Photo YCC conversion color space.
240      */
241     public static final int CS_PYCC = 1002;
242 
243     /**
244      * The built-in linear gray scale color space.
245      */
246     public static final int CS_GRAY = 1003;
247 
248 
249     /**
250      * Constructs a ColorSpace object given a color space type
251      * and the number of components.
252      * @param type one of the <CODE>ColorSpace</CODE> type constants
253      * @param numcomponents the number of components in the color space
254      */
255     protected ColorSpace (int type, int numcomponents) {
256         this.type = type;
257         this.numComponents = numcomponents;
258     }
259 
260 
261     /**
262      * Returns a ColorSpace representing one of the specific
263      * predefined color spaces.
264      * @param colorspace a specific color space identified by one of
265      *        the predefined class constants (e.g. CS_sRGB, CS_LINEAR_RGB,
266      *        CS_CIEXYZ, CS_GRAY, or CS_PYCC)
267      * @return the requested <CODE>ColorSpace</CODE> object
268      */
269     // NOTE: This method may be called by privileged threads.
270     //       DO NOT INVOKE CLIENT CODE ON THIS THREAD!
271     public static ColorSpace   getInstance (int colorspace)
272     {
273     ColorSpace      theColorSpace;
274 
275         switch (colorspace) {
276         case CS_sRGB:
277             synchronized(ColorSpace  .class) {
278                 if (sRGBspace == null) {
279                     ICC_Profile   theProfile = ICC_Profile.getInstance (CS_sRGB);
280                     sRGBspace = new ICC_ColorSpace   (theProfile);
281                 }
282 
283                 theColorSpace = sRGBspace;
284             }
285             break;
286         
287         case CS_CIEXYZ:
288             synchronized(ColorSpace  .class) {
289                 if (XYZspace == null) {
290                     ICC_Profile   theProfile = 
291                         ICC_Profile.getInstance (CS_CIEXYZ);
292                     XYZspace = new ICC_ColorSpace   (theProfile);
293                 }
294 
295                 theColorSpace = XYZspace;
296             }
297             break;
298         
299         case CS_PYCC:
300             synchronized(ColorSpace  .class) {
301                 if (PYCCspace == null) {
302                     ICC_Profile   theProfile = ICC_Profile.getInstance (CS_PYCC);
303                     PYCCspace = new ICC_ColorSpace   (theProfile);
304                 }
305 
306                 theColorSpace = PYCCspace;
307             }
308             break;
309         
310 
311         case CS_GRAY:
312             synchronized(ColorSpace  .class) {
313                 if (GRAYspace == null) {
314                     ICC_Profile   theProfile = ICC_Profile.getInstance (CS_GRAY);
315                     GRAYspace = new ICC_ColorSpace   (theProfile);
316                     /* to allow access from java.awt.ColorModel */
317                     CMM.GRAYspace = GRAYspace;
318                 }
319 
320                 theColorSpace = GRAYspace;
321             }
322             break;
323         
324 
325         case CS_LINEAR_RGB:
326             synchronized(ColorSpace  .class) {
327                 if (LINEAR_RGBspace == null) {
328                     ICC_Profile   theProfile = 
329                         ICC_Profile.getInstance(CS_LINEAR_RGB);
330                     LINEAR_RGBspace = new ICC_ColorSpace   (theProfile);
331                     /* to allow access from java.awt.ColorModel */
332                     CMM.LINEAR_RGBspace = LINEAR_RGBspace;
333                 }
334 
335                 theColorSpace = LINEAR_RGBspace;
336             }
337             break;
338         
339 
340         default:
341             throw new IllegalArgumentException   ("Unknown color space");
342         }
343         
344         return theColorSpace;
345     }
346 
347 
348     /**
349      * Returns true if the ColorSpace is CS_sRGB.
350      * @return <CODE>true</CODE> if this is a <CODE>CS_sRGB</CODE> color 
351      *         space, <code>false</code> if it is not
352      */
353     public boolean isCS_sRGB () {
354         /* REMIND - make sure we know sRGBspace exists already */
355         return (this == sRGBspace);
356     }
357     
358     /**
359      * Transforms a color value assumed to be in this ColorSpace
360      * into a value in the default CS_sRGB color space.
361      * <p>
362      * This method transforms color values using algorithms designed
363      * to produce the best perceptual match between input and output
364      * colors.  In order to do colorimetric conversion of color values,
365      * you should use the <code>toCIEXYZ</code>
366      * method of this color space to first convert from the input 
367      * color space to the CS_CIEXYZ color space, and then use the 
368      * <code>fromCIEXYZ</code> method of the CS_sRGB color space to 
369      * convert from CS_CIEXYZ to the output color space. 
370      * See {@link #toCIEXYZ(float[]) toCIEXYZ} and
371      * {@link #fromCIEXYZ(float[]) fromCIEXYZ} for further information.
372      * <p>
373      * @param colorvalue a float array with length of at least the number
374      *        of components in this ColorSpace
375      * @return a float array of length 3
376      * @throws ArrayIndexOutOfBoundsException if array length is not
377      *         at least the number of components in this ColorSpace
378      */
379     public abstract float[] toRGB(float[] colorvalue);
380 
381 
382     /**
383      * Transforms a color value assumed to be in the default CS_sRGB
384      * color space into this ColorSpace.
385      * <p>
386      * This method transforms color values using algorithms designed
387      * to produce the best perceptual match between input and output
388      * colors.  In order to do colorimetric conversion of color values,
389      * you should use the <code>toCIEXYZ</code>
390      * method of the CS_sRGB color space to first convert from the input
391      * color space to the CS_CIEXYZ color space, and then use the
392      * <code>fromCIEXYZ</code> method of this color space to
393      * convert from CS_CIEXYZ to the output color space.
394      * See {@link #toCIEXYZ(float[]) toCIEXYZ} and
395      * {@link #fromCIEXYZ(float[]) fromCIEXYZ} for further information.
396      * <p>
397      * @param rgbvalue a float array with length of at least 3
398      * @return a float array with length equal to the number of
399      *         components in this ColorSpace
400      * @throws ArrayIndexOutOfBoundsException if array length is not
401      *         at least 3
402      */
403     public abstract float[] fromRGB(float[] rgbvalue);
404 
405 
406     /**
407      * Transforms a color value assumed to be in this ColorSpace
408      * into the CS_CIEXYZ conversion color space.
409      * <p>
410      * This method transforms color values using relative colorimetry,
411      * as defined by the International Color Consortium standard.  This
412      * means that the XYZ values returned by this method are represented
413      * relative to the D50 white point of the CS_CIEXYZ color space.
414      * This representation is useful in a two-step color conversion
415      * process in which colors are transformed from an input color
416      * space to CS_CIEXYZ and then to an output color space.  This
417      * representation is not the same as the XYZ values that would
418      * be measured from the given color value by a colorimeter.
419      * A further transformation is necessary to compute the XYZ values
420      * that would be measured using current CIE recommended practices.
421      * See the {@link ICC_ColorSpace#toCIEXYZ(float[]) toCIEXYZ} method of
422      * <code>ICC_ColorSpace</code> for further information.
423      * <p>
424      * @param colorvalue a float array with length of at least the number
425      *        of components in this ColorSpace
426      * @return a float array of length 3
427      * @throws ArrayIndexOutOfBoundsException if array length is not
428      *         at least the number of components in this ColorSpace.
429      */
430     public abstract float[] toCIEXYZ(float[] colorvalue);
431 
432 
433     /**
434      * Transforms a color value assumed to be in the CS_CIEXYZ conversion
435      * color space into this ColorSpace.
436      * <p>
437      * This method transforms color values using relative colorimetry,
438      * as defined by the International Color Consortium standard.  This
439      * means that the XYZ argument values taken by this method are represented
440      * relative to the D50 white point of the CS_CIEXYZ color space.
441      * This representation is useful in a two-step color conversion
442      * process in which colors are transformed from an input color
443      * space to CS_CIEXYZ and then to an output color space.  The color
444      * values returned by this method are not those that would produce
445      * the XYZ value passed to the method when measured by a colorimeter.
446      * If you have XYZ values corresponding to measurements made using
447      * current CIE recommended practices, they must be converted to D50
448      * relative values before being passed to this method.
449      * See the {@link ICC_ColorSpace#fromCIEXYZ(float[]) fromCIEXYZ} method of
450      * <code>ICC_ColorSpace</code> for further information.
451      * <p>
452      * @param colorvalue a float array with length of at least 3
453      * @return a float array with length equal to the number of
454      *         components in this ColorSpace
455      * @throws ArrayIndexOutOfBoundsException if array length is not
456      *         at least 3
457      */
458     public abstract float[] fromCIEXYZ(float[] colorvalue);
459 
460     /**
461      * Returns the color space type of this ColorSpace (for example
462      * TYPE_RGB, TYPE_XYZ, ...).  The type defines the
463      * number of components of the color space and the interpretation,
464      * e.g. TYPE_RGB identifies a color space with three components - red,
465      * green, and blue.  It does not define the particular color
466      * characteristics of the space, e.g. the chromaticities of the
467      * primaries.
468      *
469      * @return the type constant that represents the type of this 
470      *         <CODE>ColorSpace</CODE>
471      */
472     public int getType() {
473         return type;
474     }
475 
476     /**
477      * Returns the number of components of this ColorSpace.
478      * @return The number of components in this <CODE>ColorSpace</CODE>.
479      */
480     public int getNumComponents() {
481         return numComponents;
482     }
483 
484     /**
485      * Returns the name of the component given the component index.
486      *
487      * @param idx the component index
488      * @return the name of the component at the specified index
489      * @throws IllegalArgumentException if <code>idx</code> is
490      *         less than 0 or greater than numComponents - 1
491      */
492     public String   getName (int idx) {
493         /* REMIND - handle common cases here */
494         if ((idx < 0) || (idx > numComponents - 1)) {
495             throw new IllegalArgumentException  (
496                 "Component index out of range: " + idx);
497         }
498         return new String  ("Unnamed color component("+idx+")");
499     }
500 
501     /**
502      * Returns the minimum normalized color component value for the
503      * specified component.  The default implementation in this abstract
504      * class returns 0.0 for all components.  Subclasses should override
505      * this method if necessary.
506      *
507      * @param component the component index
508      * @return the minimum normalized component value
509      * @throws IllegalArgumentException if component is less than 0 or
510      *         greater than numComponents - 1
511      * @since 1.4
512      */
513     public float getMinValue(int component) {
514         if ((component < 0) || (component > numComponents - 1)) {
515             throw new IllegalArgumentException  (
516                 "Component index out of range: " + component);
517         }
518         return 0.0f;
519     }
520 
521     /**
522      * Returns the maximum normalized color component value for the
523      * specified component.  The default implementation in this abstract
524      * class returns 1.0 for all components.  Subclasses should override
525      * this method if necessary.
526      *
527      * @param component the component index
528      * @return the maximum normalized component value
529      * @throws IllegalArgumentException if component is less than 0 or
530      *         greater than numComponents - 1
531      * @since 1.4
532      */
533     public float getMaxValue(int component) {
534         if ((component < 0) || (component > numComponents - 1)) {
535             throw new IllegalArgumentException  (
536                 "Component index out of range: " + component);
537         }
538         return 1.0f;
539     }
540 
541     /* Returns true if cspace is the XYZspace.
542      */
543     static boolean isCS_CIEXYZ(ColorSpace   cspace) {
544         return (cspace == XYZspace);
545     }
546 }
547
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags