Compressed Image

CompressedImage is an image type that stores raster data in compressed form instead of fully unpacking it into memory.

This feature was introduced primarily to increase the efficiency of getting PDF content in the form of a GraphicsContainer. Previously, images were represented only as Bitmap, which always keeps raster data decompressed in memory. Now both Bitmap and CompressedImage derive from the common base class Image:

Image stores common image parameters.
Bitmap stores fully decoded pixel data in memory.
CompressedImage stores image data as compressed streams.

This approach is especially useful when working with PDF content.

Why use CompressedImage

In most cases, you do not need to create or read CompressedImage objects manually.

The main scenario is PDF processing. When Graphics Mill reads PDF content, it can keep image data as compressed streams whenever possible. These streams remain compressed until you explicitly rasterize them.

This provides two important benefits:

Lower memory usage because image data is not decompressed until needed.
More efficient PDF round-tripping because image streams can be written back to a PDF without unpacking and recompressing them.

If you save such content back to PDF, the original compressed stream can be reused as-is.

When to create a CompressedImage manually

Manual creation of a CompressedImage is an advanced scenario.

Typically, you only need it when you want more control over how images are compressed in generated PDF files.

CompressedImage exposes two separate streams:

ColorStream
AlphaStream

This matches the internal representation used by PDF images, where color and alpha data may be stored separately. In general, these streams may even have different dimensions.

However, if you create a CompressedImage manually, the color and alpha parts always correspond to the same image dimensions.

Create a CompressedImage from a pipeline

Use this approach when you want to build a compressed image from an image source and explicitly choose the compression type.

using (var reader = ImageReader.Create(@"Images\in.jpg"))
{
    var pipeline = new Pipeline();
    pipeline.Add(reader);

    using (var compressedImage = CompressedImage.CreateFromPipeline(pipeline, CompressionType.Zip))
    {
        Console.WriteLine("Image width: " + compressedImage.Width);
        Console.WriteLine("Image height: " + compressedImage.Height);
        Console.WriteLine("Compression: " + compressedImage.ColorStream.Compression);
        Console.WriteLine("Stream size: " + compressedImage.ColorStream.Size);
    }
}

Create a CompressedImage from a file

You can also create a compressed image directly from a file:

using (var compressedImage = CompressedImage.CreateFromFile(@"Images\in.jpg", CompressionType.Zip))
{
    Console.WriteLine("Image width: " + compressedImage.Width);
    Console.WriteLine("Image height: " + compressedImage.Height);
    Console.WriteLine("Compression: " + compressedImage.ColorStream.Compression);
    Console.WriteLine("Stream size: " + compressedImage.ColorStream.Size);

    using (var bitmap = compressedImage.GetBitmap())
    {
        bitmap.Transforms.Resize(500, 500, ResizeInterpolationMode.High, ResizeMode.Fit);
        bitmap.Save(@"Images\Output\out.jpg");
    }
}

What you can do with a CompressedImage

A CompressedImage is intended mainly for inspection and deferred rasterization.

You can:

inspect image properties such as width and height;
inspect compression settings;
check compressed stream sizes;
keep image data compressed until rasterization is actually needed.

This can be useful in preflight and optimization scenarios.

Access pixel data

CompressedImage does not provide direct pixel-level editing. If you need to access or modify pixels, convert it to a Bitmap first:

using (var compressedImage = CompressedImage.CreateFromFile(@"Images\in.jpg", CompressionType.Zip))
using (var bitmap = compressedImage.GetBitmap())
{
    bitmap.Transforms.Resize(500, 500, ResizeInterpolationMode.High, ResizeMode.Fit);
    bitmap.Save(@"Images\Output\out.jpg");
}