Meziantou.FrameworkPdfImage Class
An image that PdfContentBuilder.DrawImage draws: an image XObject (ISO 32000-2, 8.9.5). A JPEG file is kept as it is (DCTDecode); another image is stored as samples compressed with FlateDecode, or as JPEG data with PdfImage.FromImageAsJpeg, its alpha channel as a soft mask (11.6.5.3). An ICC profile of the image becomes an ICCBased color space. A bilevel image (PdfImage.FromBilevel) is compressed with CCITTFaxDecode, JBIG2Decode or FlateDecode.
public sealed class PdfImageRemarks
An image does not belong to a document: each document that uses it gets its own objects. Instances are immutable and thread-safe.
Properties
| Name | Description |
|---|---|
| HasSoftMask | Gets a value indicating whether the image has a soft mask (an alpha channel). |
| Height | Gets the height of the image, in samples. |
| Width | Gets the width of the image, in samples. |
HasSoftMask
PdfImage.csHeight
PdfImage.csWidth
PdfImage.csMethods
| Name | Description |
|---|---|
| FromBilevel(ReadOnlySpan<byte>, int, int, PdfBilevelCompression) | Creates a bilevel image (black and white, one bit per pixel in DeviceGray) from its pixels. |
| FromImage(Image) | Creates an image from the first frame of an image of Meziantou.Framework.Imaging, compressed without loss. |
| FromImageAsJpeg(Image, JpegEncoder?) | Creates an image from the first frame of an image of Meziantou.Framework.Imaging, compressed as JPEG (DCTDecode): much smaller than the samples PdfImage.FromImage stores for photos, at the cost of the losses of JPEG. |
| FromJpeg(ReadOnlySpan<byte>) | Creates an image from a JPEG file, kept as it is (DCTDecode). |
| Load(ReadOnlySpan<byte>) | Creates an image from an image file: a JPEG file is kept as it is, another format is decoded by Meziantou.Framework.Imaging. |
| Load(string) | Creates an image from an image file. |
FromBilevel(ReadOnlySpan<byte>, int, int, PdfBilevelCompression)
PdfImage.Bilevel.csCreates a bilevel image (black and white, one bit per pixel in DeviceGray) from its pixels.
public static PdfImage FromBilevel(ReadOnlySpan<byte> pixels, int width, int height, PdfBilevelCompression compression = PdfBilevelCompression.CcittGroup4)Parameters
pixelsReadOnlySpan<byte>- The rows of the image, from top to bottom, each of
(width + 7) / 8bytes: one bit per pixel, the most significant bit of a byte first, a set bit for a black pixel. The bits after the last pixel of a row are ignored. The pixels are compressed when the method is called. widthint- The width of the image, in pixels.
heightint- The height of the image, in pixels.
compressionPdfBilevelCompression- The compression:
PdfBilevelCompression.CcittGroup4by default.
Returns
PdfImage The image.
Exceptions
ArgumentOutOfRangeException- The width or the height is not positive, or the width is larger than 1048576 pixels with
PdfBilevelCompression.CcittGroup4. ArgumentExceptionpixelsis shorter than the rows of the image.
Example
// A 16 x 2 image, one bit per pixel: a set bit is a black pixel
byte[] pixels = [0b1111_0000, 0b0000_1111, 0b1010_1010, 0b0101_0101];
var image = PdfImage.FromBilevel(pixels, width: 16, height: 2, PdfBilevelCompression.CcittGroup4);
var document = new PdfDocument();
document.Pages.Add(PdfSize.A4).CreateContentBuilder().DrawImage(image, 50, 700, 160, 20);
var data = document.ToByteArray();FromImage(Image)
PdfImage.csCreates an image from the first frame of an image of Meziantou.Framework.Imaging, compressed without loss.
Parameters
imageImage- The image. Its pixels are copied.
Returns
PdfImage The image: 8 or 16 bits per component, gray or RGB, with a soft mask when the image has transparent pixels. The packed pixel formats get the precision of their widening: 8 bits for PixelFormat.Bgr565, 16 bits for PixelFormat.Rgba1010102. The samples are compressed with FlateDecode and a PNG predictor when the document is saved with PdfSaveOptions.CompressStreams.
Exceptions
ArgumentException- The image has floating-point pixels, which PDF samples cannot store: convert it to an integer pixel format first.
FromImageAsJpeg(Image, JpegEncoder?)
PdfImage.csCreates an image from the first frame of an image of Meziantou.Framework.Imaging, compressed as JPEG (DCTDecode): much smaller than the samples PdfImage.FromImage stores for photos, at the cost of the losses of JPEG.
public static PdfImage FromImageAsJpeg(Image image, JpegEncoder? encoder = null)Parameters
imageImage- The image. Its pixels are copied.
encoderJpegEncoder?- The settings of the compression (
JpegEncoder.Quality,JpegEncoder.ChromaSubsampling,JpegEncoder.Process...), ornullfor the default settings ofJpegEncoder.
Returns
PdfImage The image: gray or RGB (YCbCr in the JPEG data), 8 bits per component; the samples of 16 bits are rounded to 8 bits. The transparent pixels give a soft mask compressed without loss, as with PdfImage.FromImage, and the ICC profile of the image becomes the color space of the image.
Exceptions
ArgumentException- The image has floating-point pixels: convert it to an integer pixel format first.
FromJpeg(ReadOnlySpan<byte>)
PdfImage.csCreates an image from a JPEG file, kept as it is (DCTDecode).
public static PdfImage FromJpeg(ReadOnlySpan<byte> data)Parameters
dataReadOnlySpan<byte>- The JPEG file: gray, YCbCr or CMYK, 8 bits per sample.
Returns
PdfImage The image.
Exceptions
ArgumentException- The data is not a JPEG file the
DCTDecodefilter supports.
Load overloads
Load(ReadOnlySpan<byte>)
PdfImage.csCreates an image from an image file: a JPEG file is kept as it is, another format is decoded by Meziantou.Framework.Imaging.
public static PdfImage Load(ReadOnlySpan<byte> data)Parameters
dataReadOnlySpan<byte>- The content of the file.
Returns
PdfImage The image.
Exceptions
ArgumentException- The data is not an image the library can read.
Load(string)
PdfImage.csCreates an image from an image file.
Parameters
pathstring- The path of the file.
Returns
PdfImage The image.
Exceptions
ArgumentException- The file is not an image the library can read.