KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > awt > color > 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 JavaDoc {
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 JavaDoc sRGBspace;
89     private static ColorSpace JavaDoc XYZspace;
90     private static ColorSpace JavaDoc PYCCspace;
91     private static ColorSpace JavaDoc GRAYspace;
92     private static ColorSpace JavaDoc 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 JavaDoc getInstance (int colorspace)
272     {
273     ColorSpace JavaDoc theColorSpace;
274
275         switch (colorspace) {
276         case CS_sRGB:
277             synchronized(ColorSpace JavaDoc.class) {
278                 if (sRGBspace == null) {
279                     ICC_Profile JavaDoc theProfile = ICC_Profile.getInstance (CS_sRGB);
280                     sRGBspace = new ICC_ColorSpace JavaDoc (theProfile);
281                 }
282
283                 theColorSpace = sRGBspace;
284             }
285             break;
286         
287         case CS_CIEXYZ:
288             synchronized(ColorSpace JavaDoc.class) {
289                 if (XYZspace == null) {
290                     ICC_Profile JavaDoc theProfile =
291                         ICC_Profile.getInstance (CS_CIEXYZ);
292                     XYZspace = new ICC_ColorSpace JavaDoc (theProfile);
293                 }
294
295                 theColorSpace = XYZspace;
296             }
297             break;
298         
299         case CS_PYCC:
300             synchronized(ColorSpace JavaDoc.class) {
301                 if (PYCCspace == null) {
302                     ICC_Profile JavaDoc theProfile = ICC_Profile.getInstance (CS_PYCC);
303                     PYCCspace = new ICC_ColorSpace JavaDoc (theProfile);
304                 }
305
306                 theColorSpace = PYCCspace;
307             }
308             break;
309         
310
311         case CS_GRAY:
312             synchronized(ColorSpace JavaDoc.class) {
313                 if (GRAYspace == null) {
314                     ICC_Profile JavaDoc theProfile = ICC_Profile.getInstance (CS_GRAY);
315                     GRAYspace = new ICC_ColorSpace JavaDoc (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 JavaDoc.class) {
327                 if (LINEAR_RGBspace == null) {
328                     ICC_Profile JavaDoc theProfile =
329                         ICC_Profile.getInstance(CS_LINEAR_RGB);
330                     LINEAR_RGBspace = new ICC_ColorSpace JavaDoc (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 JavaDoc ("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 JavaDoc getName (int idx) {
493         /* REMIND - handle common cases here */
494         if ((idx < 0) || (idx > numComponents - 1)) {
495             throw new IllegalArgumentException JavaDoc(
496                 "Component index out of range: " + idx);
497         }
498         return new String JavaDoc("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 JavaDoc(
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 JavaDoc(
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 JavaDoc cspace) {
544         return (cspace == XYZspace);
545     }
546 }
547
Popular Tags