Package org.faceless.pdf2

Class DeviceNColorSpace

  • All Implemented Interfaces:
    java.io.Serializable
    Direct Known Subclasses:
    SpotColorSpace
    public class DeviceNColorSpace
extends java.awt.color.ColorSpace

    This class represents a "Device N" ColorSpace, which is a ColorSpace with N individual inks - the SpotColorSpace class is a special case of this class where there is only one ink. This class has no public constructor, as it is not normally something that would be created by a user of this API. The class itself is public primarily for preflighting: an instance of this ColorSpace may be passed in to OutputProfiler.ColorAction.changeColor(org.faceless.pdf2.OutputProfiler, java.awt.color.ColorSpace, float[], float[], boolean, int).

    Note that unlike "process" ColorSpaces, colors in this space can be converted from this space to RGB or XYZ, but not the other way - these spaces are not constructed in a way that makes it easy to map an RGB value to a Color in this class (nor would it be useful). Consequently the fromRGB(float[]) and fromCIEXYZ(float[]) methods throw an UnsupportedOperationException

    Since:
    2.18

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  DeviceNColorSpace.Builder
      The Builder subclass allows the creation of a custom DeviceN ColorSpace, by specifying first the fallback ColorSpace, then the individual inks.

    • Field Summary

      • Fields inherited from class java.awt.color.ColorSpace

        CS_CIEXYZ, CS_GRAY, CS_LINEAR_RGB, CS_PYCC, CS_sRGB, TYPE_2CLR, TYPE_3CLR, TYPE_4CLR, TYPE_5CLR, TYPE_6CLR, TYPE_7CLR, TYPE_8CLR, TYPE_9CLR, TYPE_ACLR, TYPE_BCLR, TYPE_CCLR, TYPE_CMY, TYPE_CMYK, TYPE_DCLR, TYPE_ECLR, TYPE_FCLR, TYPE_GRAY, TYPE_HLS, TYPE_HSV, TYPE_Lab, TYPE_Luv, TYPE_RGB, TYPE_XYZ, TYPE_YCbCr, TYPE_Yxy

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean equals​(java.lang.Object o)  
      float[] fromCIEXYZ​(float[] xyz)
      Theoretically transforms a color value assumed to be in the XYZ ColorSpace into values in this ColorSpace.
      float[] fromRGB​(float[] rgb)
      Theoretically transforms a color value assumed to be in the sRGB ColorSpace into values in this ColorSpace.
      java.awt.Color getColor​(float[] comps, float alpha)  
      java.awt.image.BufferedImageOp getColorConvertOp​(java.awt.color.ColorSpace outcs, java.lang.Object... options)
      Return a BufferedImageOp which will convert from an image in this ColorSpace to an image in the supplied ColorSpace.
      SpotColorSpace getComponentColorSpace​(int comp)
      Get the Component ColorSpace for an individual spot color in the ColorSpace.
      java.awt.color.ColorSpace getFallbackColorSpace()
      Get the ColorSpace which defines the "fallback" color, which must be a process ColorSpace (i.e.
      float getMaxValue​(int i)  
      float getMinValue​(int i)  
      java.lang.String getName​(int comp)
      Returns the name of the specified component
      java.util.List<java.lang.String> getNames()
      Return the names of all the components as an unmodifiable List
      int getNumComponents()
      Returns the number of components of this ColorSpace.
      int hashCode()  
      boolean isAdditive()
      Return true if this ColorSpace is additive (like RGB), as opposed to subtractive (like CMYK).
      boolean isProcessComponent​(int component)
      Return true if the specified component in this color is a "process" component, false if it's a "spot" component.
      DeviceNColorSpace remap​(java.awt.color.ColorSpace newfallback)
      Attempt to convert this DeviceNColorSpace to an equavalent one, but with a different fallback ColorSpace.
      float[] toCIEXYZ​(float[] colorvalue)
      Transforms a color value assumed to be in this ColorSpace into the CIEXYZ values.
      float[] toFallback​(float[] input)
      Convert the color components in this color to the components in the fallback ColorSpace
      float[] toRGB​(float[] colorvalue)
      Transforms a color value assumed to be in this ColorSpace into a value in the default CS_sRGB color space.
      java.lang.String toString()  

      • Methods inherited from class java.awt.color.ColorSpace

        getInstance, getType, isCS_sRGB

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    • Method Detail

      • getName

        public java.lang.String getName​(int comp)
        Returns the name of the specified component
        Overrides:
        getName in class java.awt.color.ColorSpace
        Parameters:
        comp - the component index
        Returns:
        the name of the component at the specified index
        Since:
        2.11.26

      • getNames

        public java.util.List<java.lang.String> getNames()
        Return the names of all the components as an unmodifiable List
        Since:
        2.28.3

      • getMinValue

        public float getMinValue​(int i)
        Overrides:
        getMinValue in class java.awt.color.ColorSpace

      • getMaxValue

        public float getMaxValue​(int i)
        Overrides:
        getMaxValue in class java.awt.color.ColorSpace

      • isProcessComponent

        public boolean isProcessComponent​(int component)
        Return true if the specified component in this color is a "process" component, false if it's a "spot" component.
        Parameters:
        component - the component, from 0..getNumComponents();
        Since:
        2.28.3

      • getNumComponents

        public int getNumComponents()
        Returns the number of components of this ColorSpace.
        Overrides:
        getNumComponents in class java.awt.color.ColorSpace
        Returns:
        the number of components in this ColorSpace

      • getFallbackColorSpace

        public java.awt.color.ColorSpace getFallbackColorSpace()
        Get the ColorSpace which defines the "fallback" color, which must be a process ColorSpace (i.e. RGB, CMYK etc)

      • getComponentColorSpace

        public SpotColorSpace getComponentColorSpace​(int comp)
        Get the Component ColorSpace for an individual spot color in the ColorSpace. Note that prior to 2.28.4 this method returned null for process components, which is no longer the case.
        Parameters:
        comp - the component index
        Since:
        2.24.3

      • isAdditive

        public boolean isAdditive()
        Return true if this ColorSpace is additive (like RGB), as opposed to subtractive (like CMYK). DeviceN spaces are intended for print so will almost always be subtractive, but its possible to subvert this.

      • getColor

        public java.awt.Color getColor​(float[] comps,
                               float alpha)

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • toFallback

        public float[] toFallback​(float[] input)
        Convert the color components in this color to the components in the fallback ColorSpace
        Parameters:
        input - the array of components in this ColorSpace
        Returns:
        the array of components in the fallback ColorSpace

      • toRGB

        public float[] toRGB​(float[] colorvalue)

        Transforms a color value assumed to be in this ColorSpace into a value in the default CS_sRGB color space. Calls toRGB on the fallback colorspace.

        Specified by:
        toRGB in class java.awt.color.ColorSpace
        Parameters:
        colorvalue - a float array with length of at least the number of components in this ColorSpace
        Returns:
        a float array of length 3

      • toCIEXYZ

        public float[] toCIEXYZ​(float[] colorvalue)

        Transforms a color value assumed to be in this ColorSpace into the CIEXYZ values. Calls toCIEXYZ on the fallback colorspace.

        Specified by:
        toCIEXYZ in class java.awt.color.ColorSpace
        Parameters:
        colorvalue - a float array with length of at least the number of components in this ColorSpace
        Returns:
        a float array of length 3

      • fromRGB

        public float[] fromRGB​(float[] rgb)

        Theoretically transforms a color value assumed to be in the sRGB ColorSpace into values in this ColorSpace. In practice this can't easily be done and isn't useful, so throws an UnsupportedOperationException.

        Specified by:
        fromRGB in class java.awt.color.ColorSpace
        Parameters:
        rgb - a float array with length of at least 3

      • fromCIEXYZ

        public float[] fromCIEXYZ​(float[] xyz)

        Theoretically transforms a color value assumed to be in the XYZ ColorSpace into values in this ColorSpace. In practice this can't easily be done and isn't useful, so throws an UnsupportedOperationException.

        Specified by:
        fromCIEXYZ in class java.awt.color.ColorSpace
        Parameters:
        xyz - a float array with length of at least 3

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • remap

        public final DeviceNColorSpace remap​(java.awt.color.ColorSpace newfallback)
        Attempt to convert this DeviceNColorSpace to an equavalent one, but with a different fallback ColorSpace. The equivalent space will be as close as possible to the original, but may not be identical, as colors may be out of gamut. For some DeviceN spaces this process may not be possible - spaces are remapped with a lookup table function requiring mn samples where n is the number of inks
        Since:
        2.17.1

      • getColorConvertOp

        public java.awt.image.BufferedImageOp getColorConvertOp​(java.awt.color.ColorSpace outcs,
                                                        java.lang.Object... options)

        Return a BufferedImageOp which will convert from an image in this ColorSpace to an image in the supplied ColorSpace.

        This can be used to convert a multi-channel image to
        • an RGB image - just pass in (eg)Color.red.getColorSpace()
        • the process colorspace used as a fallback for this space: pass in getFallbackColorSpace()
        • to extract a single separation from this image, pass in a SpotColorSpace with the specified component, retrieved from #getComponentColorSpace(). The resulting image will have a single component where 0 means "no ink" and 1 means "100% ink". This is mathematically correct but looked inverted when displayed as a bitmap, so passing an option of "invert" will invert this so white means no ink, black means 100% ink. Alternatively an option of "index" will return an indexed image where a value of 0 is transparent, and a value of 1 is the RGB value of the ink. Finally, an option of "gray" will return an image in a grayscale ColorSpace where 0 is white.

        This method will mostly be used with the BufferedImage returned from PagePainter.getImage() when the ColorModel supplied to that method is PDFParser.SEPARATIONS. Here is an example showing this 

          PDFParser pdfparser = new PDFParser(pdf);
  PagePainter painter = pdfparser.getPagePainter(pdf.getPage(0));
  BufferedImage image = painter.getImage(200, PDFParser.SEPARATIONS);
  // "image" is a multi-channel image based on a DeviceNColorSpace.
  // To collapse it down to RGB
  DeviceNColorSpace cs = (DeviceNColorSpace)image.getColorModel().getColorSpace();
  ColorSpace sRGB = ColorSpace.getInstance(ColorSpace.CS_sRGB);
  BufferedImageOp op = cs.getColorConvertOp(sRGB);
  BufferedImage rgbimage = op.filter(image, null);
  // "rgbimage" is an RGB version of the same, which can be saved as PNG etc.

        Note - ideally this method would return a ColorConvertOp, but that class is broken to the point of being non-functional, and as most of the methods are final we have to return a BufferedImageOp instead.

        Since:
        2.28.3
        See Also:
        PDFParser.SEPARATIONS