The <image-properties/> command

PDF bounding boxes

If you decide to include PDF graphic images within a document processed by TopLeaf, it is important to remember that the PDF image may have been originally prepared for rendering on a particular type of medium and may or may not be suitable for use within the target document.

Typical output media include paper product, screen viewing, or a subsequent pre-press process, in which the content of the page is placed on an intermediate medium, such as film or an imposed reproduction plate. The variety of output media means that a PDF page can define as many as five separate boundary types that can be used when rendering an image.

By default, TopLeaf will attempt to use the crop box when sizing a PDF image. If you need to override this setting, then use:

<image-properties pdfusebox="TYPE" />

where :

  • The value of TYPE selects the preferred image bounding box type, and is one of the following: art, bleed, trim, crop, or media.

The effect of this command is limited to the element in which it is called.

When the preferred bounding box type is not defined, TopLeaf applies the following rules to select the best available bounding box:

If this bounding box is not defined... Then use the...
art box crop box
bleed box crop box
trim box crop box
crop box media box

The following example requests that TopLeaf should use the PDF art box when determining the natural size of a PDF page image:

<image-properties pdfusebox="art" />

If the art box is not defined, TopLeaf will attempt to use the crop box to size the PDF image. If the crop box is not defined, then TopLeaf will use the PDF media box to size the PDF page image.

The following example shows how to force the TopLeaf to use the PDF media box when determining the size of a PDF image:

<image-properties pdfusebox="media" />
[Note] Note

The TopLeaf print and page viewer uses GhostScript to convert PDF documents to bitmap images. In the current implementation, TopLeaf is unable to use the artbox to accurately size PDF page content as bitmap images.

Automatic image scaling

The application of bindings between or around successive elements creates an unbreakable object. This is a useful technique that ensures the content of that object is rendered within the same data column. If the vertical depth of an unbreakable object exceeds the maximum depth of a data column or page, the composition engine will attempt to fit the object by automatically scaling the size of all block images within it. A warning will be generated if the total amount of additional scaling exceeds 40%. Automatic scaling may also be applied when processing images within floats.

To adjust the rescaling threshold use the command:

<image-properties max-rescale="SCALE" />

where :

  • The value of SCALE specifies the percentage rescaling threshold. The composition engine will generate a warning if the amount of additional scaling exceeds this threshold.