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.

PDF page selection

By default, only the first page of a PDF can be used as an image. To enable the selection of other pages, use:

<image-properties pdfpagesep="CHAR" />

The argument value is a single character. When used at the end of an image path it is followed by the page number to use. For example, consider the following custom content:

<image-properties pdfpagesep="#" />
<Image href="images/example.pdf#5" />

In this case the 5th page of images/example.pdf will be inserted as an image.

The effect of this command is limited to the element in which it is called. Use it in $document to apply it to the whole document.

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.

Image padding

By default, TopLeaf inserts a small amount of vertical space when processing an image in the context of a data block, float, note, or running head. To adjust the depth of the image bottom padding use the command:

<image-properties bottom-padding="DEPTH" />

The argument value is a non-negative measure. The following example sets the image bottom padding to zero:

<image-properties bottom-padding="0" />

If not specified, the image bottom padding defaults to 2.0 pt.