PDFlib 8 Windows COM/.NET Tutorial

Note In some situations PDFlib converts multi-strip TIFF images to multiple PDF images which would
be masked individually. Since this is usually not intended, this kind of images will be rejected
both as a mask as well as a masked target image. Also, it is important to not mix the implicit
and explicit cases, i.e., don’t use images with transparent color values as mask.
Note The mask must have the same orientation as the underlying image; otherwise it will be rejected.
Since the orientation depends on the image file format and other factors it is difficult to detect.
For this reason it is recommended to use the same file format and creation software for
both mask and image.
Cookbook A full code sample can be found in the Cookbook topic images/image_mask.
Image masks and soft masks. Image masks are images with a bit depth of 1 (bitmaps)
in which zero bits are treated as transparent: whatever contents already exist on the
page will shine through the transparent parts of the image. 1-bit pixels are colorized
with the current fill color.
Soft masks generalize the concept of image masks to masks with more than 1 bit.
They blend the image against some existing background. PDFlib accepts all kinds of single-channel
(grayscale) images as soft mask. Note that only real gray-scale images are
suitable as a mask, but not images with indexed (palette-based) color. They can be used
the same way as image masks. The following kinds of images can be used as image
masks:
> PNG images
> JBIG2 images
> TIFF images (single- or multi-strip)
> JPEG images (only as soft mask, see below)
> BMP; note that BMP images are oriented differently than other image types. For this
reason BMP images must be mirrored along the x axis before they can be used as a
mask.
> raw image data
Image masks are simply opened with the mask option, and placed on the page after the
desired fill color has been set:
mask = p.load_image("tiff", maskfilename, "mask");
p.setcolor("fill", "rgb", 1.0, 0.0, 0.0, 0.0);
if (mask != -1)
{
p.fit_image(mask, x, y, "");
}
If you want to apply a color to an image without the zero bit pixels being transparent
you must use the colorize option (see Section 7.1.5, »Colorizing Images«, page 186).
7.1.5 Colorizing Images
Similarly to image masks, where a color is applied to the non-transparent parts of an
image, PDFlib supports colorizing an image with a spot color. This feature works for
black and white or grayscale images.
For images with an RGB palette, colorizing is only reasonable when the palette contains
only gray values, and the palette index is identical to the gray value.
186 Chapter 7: Importing Images and PDF Pages (Edition for COM, .NET, and REALbasic)