Image

This document is about how to set up and use an Image object.

Table of contents

First steps

Set up an Image object like that:

<?php 

use IDML\Content\Image\Image;

$image = new Image(); 

If you want to set your own unique identifier, set up the Image like that: new Image('UniqueName');

Size and Position

Add a size and a position like that:

<?php

$image
    ->setSize(100, 200)
    ->setPosition(0, 0)
    ->setSrc('myImage.tif')
;

Add Unit::MILLIMETERS as third parameter of each method if you prefer numbers in millimeters.

The two first methods define image properties inside a Rectangle. So if we set the size wider than the Rectangle's size, the image will reach outside the Rectangle. When we define the position, the Image will move inside the Rectangle.

If the height should be in the same ratio depending on the width, it's allow the set the height to null.

To calculate the ratio of an image, IDML-Creator needs to be able to read it.

Adding to a Rectangle

To add an image, you need to set up an Rectangle object and add it then:

<?php

$rectangle->setImage($image);

QR Codes

InDesign knows five different kinds of QR Codes:

  • An email QR Code, which we call EmailQRCode
  • A hyperlink QR Code, which we call HyperlinkQRCode
  • A plain text QR Code, which we call PlainTextQRCode
  • A text message QR Code, which we call TextMessageQRCode
  • A QR Code for vCards, which we call VCardQRCode

From a technical view, QR Codes behave like the content of an EPS image. Therefore, they need to be added into an EPS and the EPS into a rectangle.

<?php

use IDML\Content\Enum\Unit;
use IDML\Content\Image\EPS;
use IDML\Content\Image\QRCode;
use IDML\Content\Image\QR\HyperlinkQRCode;
use IDML\Content\Rectangle;

$qrCode = new QRCode(
    new HyperlinkQRCode('https://www.bitandblack.com'),
    $color
);

$eps = new EPS();
$eps
    ->setPosition(0, 0)
    ->setSize(20, 20, Unit::MILLIMETERS)
    ->setQRCode($qrCode)
;

$rectangle = new Rectangle();
$rectangle
    ->setSize(20, 20, Unit::MILLIMETERS)
    ->setImage($eps)
;

Confused about the $color? Read more about colors here.

Placing PDFs

The IDML-Creator is able to place PDF files. They behave like images but have some more options. That's why we use the PDF class here:

<?php

use IDML\Content\Enum\Image\PDFCrop;
use IDML\Content\Image\PDF;
use IDML\Content\Rectangle;

$pDFImage = new PDF(); 
$pDFImage
    ->setPosition(0, 0)
    ->setSize(100, 200)
    ->setSrc('myPDFFile.pdf')
    ->setPageNumber(2)
    ->setPDFCrop(PDFCrop::BLEED)
    ->setTransparentBackground(true)
;

$rectangle = new Rectangle();
$rectangle
    ->setImage($pDFImage)
;

Page Number

To place a PDF, you need to specify the page number, that is what setPageNumber is for.

PDF Crop

A PDF may have different page boxes, for example, the trimbox or the bleedbox. They can be accessed with the PDFCrop Enum.

Transparent Background

If you want to embed a PDF with a transparent background, call setTransparentBackground(true).

Caching

IDML-Creator needs to read the width and height of an image to handle it correctly. This can have a negative impact on performance in projects with a large number of images. For this reason, a cache function can be used to make reading the image information significantly faster.

<?php 

use BitAndBlack\ImageInformation\Cache\Cache;
use IDML\Content\Image\Image;

$image = new Image(
    cache: new Cache()
); 

Per default, the cache class uses a file system cache, but this can be customized as desired.