16-bit images in PDF output

📌 Overview

This article explains how to maintain 16-bit images in the PDF output.

🖼️IDOMImage

In Mako, the IDOMImage class represents an image. Images can be loaded from a file:

CPP

const auto mako = IJawsMako::create();
IJawsMako::enableAllFeatures(mako);
...
U8String inputFile = "MyImage.tif";
const auto image = IDOMTIFFImage::create(mako, IInputStream::createFromFile(mako, inputFile));

C#

var mako = IJawsMako.create();
IJawsMako.enableAllFeatures(mako);
...
string inputFile = "MyImage.tif";
var image = IDOMTIFFImage.create(mako, IInputStream.createFromFile(mako, inputFile));

Images are also created by rendering a PDF page. In this example, to a 16 bits-per-sample, CMYK image:

CPP

// Create an input
IPDFInputPtr input = IPDFInput::create(mako);

// Get the assembly from the input
String inputFile = "MyFile.pdf";
IDocumentAssemblyPtr assembly = input->open(inputFile);

// Get the document from the assembly
IDocumentPtr document = assembly->getDocument();

// Get first page
IDOMFixedPagePtr fixedPage = document->getPage(0)->getContent();
	
// Render the page 16bpp, cmyk
IJawsRendererPtr renderer = IJawsRenderer::create(mako);
IDOMImage composite = renderer->render(
    fixedPage,
    renderResolution,
    16,
    IDOMColorSpaceDeviceCMYK::create(mako)
);

// Write a TIFF
IDOMTIFFImage::encode(mako, composite, IOutputStream::createToFile(mako, "render.tif"));

C#

// Create a PDF input
using var input = IPDFInput.create(mako);

// Get the assembly from the input
string inputFile = "MyFile.pdf";
using var assembly = input.open(inputFile);

// Get the document from the assembly
using var document = assembly.getDocument();

// Get the first page
using var fixedPage = document.getPage(0).getContent();

// Render the page to a 16bpp CMYK image
using var renderer = IJawsRenderer.create(mako);
using var colorSpace = IDOMColorSpaceDeviceCMYK.create(mako);
using var composite = renderer.render(
    fixedPage,
    renderResolution,
    16,
    IDOMColorSpaceDeviceCMYK.create(mako)
);

// Write to a TIFF file
using var outputStream = IOutputStream.createToFile(mako, "render.tif");
IDOMTIFFImage.encode(mako, composite, outputStream);

📗 Instructions

Currently, Mako encodes IDOMImages to 8 bits when writing PDF output, even though the IDOMImage may be 16-bit. This limitation can be circumvented by converting to an IDOMPDFImage. An IDOMPDFImage represents the native format for images in PDF. When Mako writes a page that contains such images to a PDF file, they are passed directly into the output without further processing, thereby preserving 16-bit images. This means that compression of the image must be handled when creating an IDOMPDFImage, but this is easily achieved with a stream creator that supports compression. This function shows it in action.

🪜 Steps

Get image particulars: Get the frame, color space, width, height, bps and rawBytes properties.
Compress the image: Use a “flate writer”, created using IOutputStream::createToFlateCompressed() to compress the image.
Create the new image: Use IDOMPDFImage::create() to make the new image which will preserve 16-bit encoding.

⌨️ Sample Code

See the below sample code in C++ and C#.

CPP

/**
 * \brief Create a flate-compressed IDOMPDFImage from an IDOMImage. This allows 16-bit images to be passed to PDF output
 * \param mako Pointer to Mako instance
 * \param image Pointer to IDOMImage
 * \return IDOMPDFImage
 */
IDOMPDFImagePtr getAsPdfImage(const IJawsMakoPtr& mako, const IDOMImagePtr& image)
{
    // Get image particulars
    const auto frame = image->getImageFrame(mako);
    const auto colorSpace = frame->getColorSpace();
    const auto width = frame->getWidth();
    const auto height = frame->getHeight();
    const auto bps = frame->getBPS();
    const auto rawBytes = frame->getRawBytesPerRow();

    // Compress the image
    IRAInputStreamPtr reader;
    IRAOutputStreamPtr writer;
    mako->getTempStore()->createTemporaryReaderWriterPair(reader, writer);
    {
        const auto flateWriter = IOutputStream::createToFlateCompressed(mako, writer, 5, false);
        if (!flateWriter->open())
        {
            throw std::runtime_error("Failed to create flate stream");
        }

        const uint32 actualStride = (width * colorSpace->getNumComponents() * bps + 7) / 8;
        if (actualStride > rawBytes)
        {
            throw std::runtime_error("Failed to calculate stride correctly");
        }

        CEDLVector<uint8> rowBuffer(rawBytes);
        for (uint32 y = 0; y < height; y++)
        {
            frame->readScanLine(&rowBuffer[0], rawBytes);
            if (!flateWriter->completeWrite(&rowBuffer[0], static_cast<int32>(actualStride)))
            {
                throwEDLError(EDL_ERR_IMAGE_DECODE_FAILURE);
            }
        }
        if (!flateWriter->flush())
        {
            throw std::runtime_error("Failed to flush flate stream");
        }
        flateWriter->close();
    }

    // Create the new image
    return IDOMPDFImage::create(mako, reader, eDITFlate, IDOMPDFImage::FlateLZWParams::create(), colorSpace, width, height, bps);
}

C#

/**
* \brief Create a flate-compressed IDOMPDFImage from an IDOMImage. This allows 16-bit images to be passed to PDF output
* \param mako Pointer to Mako instance
* \param image Pointer to IDOMImage
* \return IDOMPDFImage
*/
public static IDOMPDFImage getAsPdfImage(IJawsMako mako, IDOMImage image)
{
    // Get image particulars
    using var frame = image.getImageFrame(mako);
    using var colorSpace = frame.getColorSpace();
    uint width = frame.getWidth();
    uint height = frame.getHeight();
    uint bps = frame.getBPS();
    uint rawBytes = frame.getRawBytesPerRow();

    // Create temporary streams
    IRAInputStream reader;
    IRAOutputStream writer;
    var pair = mako.getTempStore().createTemporaryReaderWriterPair();
    reader = pair.inputStream;
    writer = pair.outputStream;

    // Compress the image
    using (var flateWriter = IOutputStream.createToFlateCompressed(mako, writer, 5, false))
    {
        if (!flateWriter.open())
            throw new Exception("Failed to create flate stream");

        uint actualStride = (uint)((width * colorSpace.getNumComponents() * bps + 7) / 8);
        if (actualStride > rawBytes)
            throw new Exception("Failed to calculate stride correctly");

        byte[] rowBuffer = new byte[rawBytes];
        for (uint y = 0; y < height; y++)
        {
            frame.readScanLine(rowBuffer, rawBytes);
            if (!flateWriter.completeWrite(rowBuffer, (int)actualStride))
                throwEDLError((uint)EDLErrorCode.EDL_ERR_IMAGE_DECODE_FAILURE);
        }

        if (!flateWriter.flush())
            throw new Exception("Failed to flush flate stream");

        flateWriter.close();
    }

    // Create and return the new compressed PDF image
    return IDOMPDFImage.create(mako, reader, eDOMImageType.eDITFlate, IDOMPDFImage.FlateLZWParams.create(), colorSpace, width, height, (byte)bps);
}

☑️ Conclusion

Handling 16-bit images in PDF output with Mako involves converting IDOMImages to IDOMPDFImages to preserve their bit depth. By following the outlined steps, users can ensure that their images maintain their quality and integrity when included in PDF files. The provided sample code demonstrates how to achieve this using flate compression, ensuring efficient and effective image handling.

📚 Additional Resources

If you need additional help, see our API documentation for detailed information on class/method usage, or raise a support ticket via our customer portal.