Converts the image from one color space to another.

 

   

Syntax
 

[C#]
void Recolor(ColorSpace space)
void Recolor(ColorSpace space, RenderingIntent intent)

[Visual Basic]
Sub Recolor(space As ColorSpace)
Sub Recolor(space As ColorSpace, intent As RenderingIntent)

Throws Exceptions may throw Exception()

 

   

Params
 
Name Description
space The destination color space.
intent The rendering intent enumeration. If no intent is provided the default for the image (typically RelativeColorimetric) is used.

 

   

Notes
 

Converts the image from one color space to another.

Calling this method results in the pixels within the PixMap image being mapped from the current color space to the new color space. The new ColorSpace is then assigned to the PixMap and (if it is not already there) added to the PixMap ObjectSoup.

Colors can only be sensibly mapped from one color space to another if we know something about the characteristics of the color space. If your color spaces do not contain this information (e.g. if they are device color spaces) then ABCpdf will use a default color profile.

An exception will be thrown if the operation is not possible. This may happen if the PixMap is not in an ObjectSoup or if the ColorSpace object is in some way invalid.

If the ImageMask property is true the image has no color space and is implicitly black and white. Image masks cannot be anything other than black and white so trying to convert an image mask to another color space will result in an exception being raised.

The rendering intent determines how out of gamut colors are handled. The following options are available:

  • Perceptual
  • RelativeColorimetric
  • Saturation
  • AbsoluteColorimetric

The perceptual model maps the entire gamut of the source color space into the destination one and is good for photographic type images. The saturation model is good for diagrams, cartoons or posterized images where distinctiveness of color is more important than precise color fidelity. The colorimetric methods remap only those colors which are out of gamut. The relative one keeps the color values the same while allowing the brightness to vary. The absolute colorimetric method uses the closest color at the gamut boundary.

In general you will want to use a perceptual intent when mapping from a large gamut color space (e.g. RGB) to a narrow one (e.g. CMYK). In general you will want to use a relative colorimetric intent when mapping between similar color spaces (e.g. RGB to RGB or CMYK to CMYK).

After the PixMap has been Recolored it is no longer compressed and will have a BitsPerComponent of eight or sixteen. You may wish to compress it using the StreamObject.Compress method.

 

   

Example
 

Here we change all the images in a document to CMYK.

[C#]
Doc theDoc = new Doc();
theDoc.Read(Server.MapPath("../Rez/spaceshuttle.pdf"));
List<PixMap> theList = new List<PixMap>();
// find all the PixMap objects in the soup
foreach (IndirectObject obj in theDoc.ObjectSoup) {
  PixMap p = obj as PixMap;
  if (p != null)
    theList.Add(p);
}
// add our destination color space
ColorSpace cs = new ColorSpace(theDoc.ObjectSoup);
cs.IccProfile = new IccProfile(theDoc.ObjectSoup, Server.MapPath("../Rez/abccmyk.icc"));
// convert images to our color space
for (int i = 0; i < theList.Count; i++) {
  PixMap p = theList[i];
  p.Recolor(cs, RenderingIntent.Perceptual);
  p.CompressJpeg(75);
}
theDoc.Save(Server.MapPath("pixmaprecolor.pdf"));
theDoc.Clear();

[Visual Basic]
Dim theDoc As New Doc()
theDoc.Read(Server.MapPath("../Rez/spaceshuttle.pdf"))
Dim theList As New List(Of PixMap)
' find all the PixMap objects in the soup
Dim obj As IndirectObject
Dim p As PixMap
For Each obj In theDoc.ObjectSoup
  p = TryCast(obj, PixMap)
  If p IsNot Nothing Then
    theList.Add(p)
  End If
Next ' add our destination color space
Dim cs As New ColorSpace(theDoc.ObjectSoup)
cs.IccProfile = New IccProfile(theDoc.ObjectSoup, Server.MapPath("../Rez/abccmyk.icc"))
' convert images to our color space
For i As Integer = 0 To theList.Count - 1
  p = theList(i)
  p.Recolor(cs, RenderingIntent.Perceptual)
  p.CompressJpeg(75)
Next
theDoc.Save(Server.MapPath("pixmaprecolor.pdf"))
theDoc.Clear()


spaceshuttle.pdf [page 1]


pixmaprecolor.pdf [page 1]