Search manual:

- Main page
- Introduction
- Hello, world!
- Basics
  - How to write the layout
  - Structure of the data file and the layout rules
  - Outputting objects
  - Grid
  - Areas on the page (PositioningArea)
  - File organization
  - Hyphenation / language settings
  - Using fonts
  - Text formats
  - Text formatting
  - Colors
- Programming
- Image inclusion
- Tables
- Advanced topics
  - Bookmarks
  - Creation of XML structures
  - Print output / crop marks
  - Using CSS with the speedata Publisher
  - Groups (virtual objects)
  - Virtual pages
  - Rotation of contents
  - Sorting data
  - Wrap around images
  - Page types
  - Starting the Publisher via the Hotfolder
  - Lua-Filter / pre-processing
  - Schema validation
  - Quality assurance and PDF comparison
  - Troubleshooting / Debugging
  - Server mode (REST API)
  - Control of the layout when calling the Publisher
  - Create and use images with MetaPost
- Cookbook
  - Thumb index
  - Embed multipage PDF files
  - Layout optimization using groups
  - Imitate bulleted lists
  - Automatically generated directories
  - Create table of contents in one go
  - Page numbers: Page x of y
- Installation instructions
- File name in the Publisher
- speedata Publisher defaults
- Running the speedata publisher on the command line
- How to configure the speedata publisher
- Lenghts and units
- XPath- and Layoutfunctions
- Internal variables
- Associate XML editor with schema
  - Visual Studio Code
  - OxygenXML
  - Atom
- Changelog
- Glossary
- Compatibility with other software
- Command reference
  - A
  - Action
  - AddSearchpath
  - AtPageCreation
  - AtPageShipout
  - AttachFile
  - Attribute
  - B
  - Barcode
  - Bold
  - BoldItalic
  - Bookmark
  - Box
  - Br
  - Case
  - Circle
  - ClearPage
  - Color
  - Column
  - Columns
  - Compatibility
  - Contents
  - Copy-of
  - DefineColor
  - DefineColorprofile
  - DefineFontalias
  - DefineFontfamily
  - DefineGraphic
  - DefineMatter
  - DefineTextformat
  - Element
  - Fallback
  - Fontface
  - ForAll
  - Frame
  - Grid
  - Group
  - Groupcontents
  - HSpace
  - Hyphenation
  - I
  - Image
  - Include
  - Initial
  - InsertPages
  - Italic
  - Layout
  - Li
  - LoadDataset
  - LoadFontfile
  - Loop
  - Makeindex
  - Margin
  - Mark
  - Message
  - NewPage
  - NextFrame
  - NextRow
  - NoBreak
  - Ol
  - Options
  - Otherwise
  - Output
  - Overlay
  - Pageformat
  - Pagetype
  - Paragraph
  - PDFOptions
  - PlaceObject
  - Position
  - PositioningArea
  - PositioningFrame
  - ProcessNode
  - Record
  - Regular
  - Rule
  - SaveDataset
  - SavePages
  - SetGrid
  - SetVariable
  - SortSequence
  - Stylesheet
  - Span
  - Sub
  - Sup
  - Switch
  - Table
  - TableNewPage
  - Tablefoot
  - Tablehead
  - Tablerule
  - Td
  - Text
  - Textblock
  - Tr
  - Trace
  - Transformation
  - U
  - Ul
  - Until
  - URL
  - Value
  - VSpace
  - While

Version 4.6.0
Search manual

- Main page
- Introduction
- Hello, world!
- Basics
  - How to write the layout
  - Structure of the data file and the layout rules
  - Outputting objects
  - Grid
  - Areas on the page (PositioningArea)
  - File organization
  - Hyphenation / language settings
  - Using fonts
  - Text formats
  - Text formatting
  - Colors
- Programming
- Image inclusion
- Tables
- Advanced topics
  - Bookmarks
  - Creation of XML structures
  - Print output / crop marks
  - Using CSS with the speedata Publisher
  - Groups (virtual objects)
  - Virtual pages
  - Rotation of contents
  - Sorting data
  - Wrap around images
  - Page types
  - Starting the Publisher via the Hotfolder
  - Lua-Filter / pre-processing
  - Schema validation
  - Quality assurance and PDF comparison
  - Troubleshooting / Debugging
  - Server mode (REST API)
  - Control of the layout when calling the Publisher
  - Create and use images with MetaPost
- Cookbook
  - Thumb index
  - Embed multipage PDF files
  - Layout optimization using groups
  - Imitate bulleted lists
  - Automatically generated directories
  - Create table of contents in one go
  - Page numbers: Page x of y
- Installation instructions
- File name in the Publisher
- speedata Publisher defaults
- Running the speedata publisher on the command line
- How to configure the speedata publisher
- Lenghts and units
- XPath- and Layoutfunctions
- Internal variables
- Associate XML editor with schema
  - Visual Studio Code
  - OxygenXML
  - Atom
- Changelog
- Glossary
- Compatibility with other software
- Command reference
  - A
  - Action
  - AddSearchpath
  - AtPageCreation
  - AtPageShipout
  - AttachFile
  - Attribute
  - B
  - Barcode
  - Bold
  - BoldItalic
  - Bookmark
  - Box
  - Br
  - Case
  - Circle
  - ClearPage
  - Color
  - Column
  - Columns
  - Compatibility
  - Contents
  - Copy-of
  - DefineColor
  - DefineColorprofile
  - DefineFontalias
  - DefineFontfamily
  - DefineGraphic
  - DefineMatter
  - DefineTextformat
  - Element
  - Fallback
  - Fontface
  - ForAll
  - Frame
  - Grid
  - Group
  - Groupcontents
  - HSpace
  - Hyphenation
  - I
  - Image
  - Include
  - Initial
  - InsertPages
  - Italic
  - Layout
  - Li
  - LoadDataset
  - LoadFontfile
  - Loop
  - Makeindex
  - Margin
  - Mark
  - Message
  - NewPage
  - NextFrame
  - NextRow
  - NoBreak
  - Ol
  - Options
  - Otherwise
  - Output
  - Overlay
  - Pageformat
  - Pagetype
  - Paragraph
  - PDFOptions
  - PlaceObject
  - Position
  - PositioningArea
  - PositioningFrame
  - ProcessNode
  - Record
  - Regular
  - Rule
  - SaveDataset
  - SavePages
  - SetGrid
  - SetVariable
  - SortSequence
  - Stylesheet
  - Span
  - Sub
  - Sup
  - Switch
  - Table
  - TableNewPage
  - Tablefoot
  - Tablehead
  - Tablerule
  - Td
  - Text
  - Textblock
  - Tr
  - Trace
  - Transformation
  - U
  - Ul
  - Until
  - URL
  - Value
  - VSpace
  - While

- Dieses Handbuch auf Deutsch

# Image inclusion

Inserting images into the PDF is very easy, a short command is enough:

    <Record element="data">
      <PlaceObject>
        <Image file="_samplea.pdf" width="5cm"/>
      </PlaceObject>
    </Record>

The image `_samplea.pdf` is (like `_sampleb.pdf`) part of the Publisher and can be used for testing purposes. As image formats PDF, PNG and JPEG are possible. Other formats must be converted into one of these formats before processing. If the program inkscape is installed, it is used to automatically convert SVG files to PDF (check the section about the configuration for setting the command line parameters for inkscape). The format that causes the least problems in practice is PDF. Here, color profiles can also be embedded.

The images are not changed during processing in the Publisher, i.e. they retain their original (file) size, among other things. With very large images, the processing speed is lower and the size of the resulting PDF file naturally increases. Therefore it may be worthwhile to have special versions with smaller file sizes available for processing.

## Width and height of the images

If you include images, it is always useful to include a size specification. Otherwise the natural size of the image is taken. What the natural size is, is not always clear. Usually there is a DPI specification in the image file. This is often set arbitrarily by the image processing program. For example, if it says 72 DPI, a 720 pixel wide image is 10 inches wide; at 300 DPI, it is only 2.4 inches wide.

Since the specification cannot be relied upon, size specifications are required for the output. This can be either the desired height or width of the image, or both together. In the example above, the image has a width of five centimeters. The specification can also be made as a number of grid cells. Specifying `width="100%"` means that the entire available width should be used (currently other percentages are not supported). The specification auto is like omitting the specification and is only available for CSS compatibility.

If both proportions are specified (width and height), there are two modes: keep aspect ratio (`clip="yes"`) or stretch or shrink (`clip="no"`) the output.

    <PlaceObject>
        <Image file="ocean.pdf" width="10" height="3" clip="no"/>
    </PlaceObject>

The image is stretched horizontally.
If clip is set to 'no', the image is distorted.

With `clip="yes"` the image is cropped so that the maximum dimensions are taken on one side.

    <PlaceObject>
        <Image file="ocean.pdf" width="10" height="3" clip="yes"/>
    </PlaceObject>

If clip is set to 'yes', only a section is shown.

The size of images can be determined with the two XPath functions `sd:imagewidth(<filename>)` and `sd:imageheight(<filename>)`. The result is in grid cells. Caution, here the natural size is taken, which may be without significance (see above).

## Maximum height and width, minimum height and width

To use the natural size, but specify restrictions, there are four combinations of min/max and width/height. The image in the following example will be no wider than 10 grid cells and no higher than 3. The aspect ratio is preserved:

    <PlaceObject>
        <Image file="forest.jpg" maxwidth="10" maxheight="3" />
    </PlaceObject>

The image is limited to the height of three grid cells.

If the natural image size is smaller than the given `maxwidth` and `maxheight`, you can set the attribute `stretch` to `yes` to increase the size of the image until one of the given constraints are reached.

## Rotating images

With the rotate attribute you can rotate images in 90 degree steps (positive values: clockwise). The following example rotates an image 90 degrees counterclockwise if it is a portrait image. With the XPath command `sd:aspectratio(<filename>)` you can determine the aspect ratio of an image. If it is greater than 1, then it is a landscape image.

    <data>
      <img file="_samplea.pdf" />
      <img file="_sampleb.pdf" />
    </data>

Data

    <Layout xmlns:sd="urn:speedata:2009/publisher/functions/en"
      xmlns="urn:speedata.de:2009/publisher/en">

      <Record element="data">
        <ForAll select="img">
          <PlaceObject>
            <Image file="{@file}" width="5"
              rotate="{if ( sd:aspectratio(@file) &lt; 1 ) then '-90' else '0'}"/>
          </PlaceObject>
        </ForAll>
      </Record>
    </Layout>

The image is rotated 90 degrees if it is a portrait image.
The second image is rotated by 90° because it is in portrait format.

| The curly brackets at file and rotate mean that the system jumps to XPath mode to evaluate the XPath expressions (access to the file attribute and the if-then query). See the XPath- and Layoutfunctions for more information.

Note: if the image in the argument of `sd:aspectratio()` is not available in the filesystem, the value is taken from the placeholder image (chapter Image not found?). To check if an image is available at all, you can use the command `sd:file-exists(<filename>)`.

## Location of the image files

Usually the images are stored in the file system or in a DAM (digital asset management). In the file system they can be addressed either with an absolute path:

    <Image file="file:///path/to/the/image.pdf"  />

or as a file in one of the subdirectories of the search path, as in the examples above. For example, the images can be located in the subdirectory images. See the section on File organization.

The images can also be loaded from a web server using http(s) protocol. The syntax is analogous to the absolute path, for example:

    <Layout xmlns="urn:speedata.de:2009/publisher/en" >

      <Record element="data">
        <PlaceObject>
          <Image file="http://placekitten.com/g/400/300" width="5"/>
        </PlaceObject>
      </Record>
    </Layout>

## Caching

The images that are loaded via http and https are cached on the hard disk. With each request, the system checks whether the image is still up-to-date and, if necessary, does not download it. If the image is deleted on the server, it is also deleted in the local system.

With `sp --cache=fast` you can use the fast caching method, which downloads the image from the server only once and then does not check if it is still up-to-date.

The `sp clearcache` command deletes the cache.

The location of the image cache can be controlled either by tempdir (command line and configuration file) or by the imagecache key in the configuration file (not on the command line).

## Image not found?

What happens if an image is not found? The normal behavior is to output an error message and a placeholder image indicating the missing image:

    <PlaceObject>
        <Image file="doesnotexist" width="5"/>
    </PlaceObject>

It should be immediately obvious that the image file was not found.

Another possibility is to use fallback to determine a placeholder image yourself:

    <PlaceObject>
        <Image file="doesnotexist" fallback="......" width="5"/>
    </PlaceObject>

You can also set whether it is an error when a placeholder image is selected or only a warning.

    <Options imagenotfound="error"/>

or `warning` for a warning.

## Special features for PDF files

PDF files have some peculiarities: they can contain several pages and the individual pages have different boxes that mark the visible area and other areas. Some of the boxes are important for printing, some for viewing in the PDF viewer. The box that is to be displayed with the specified sizes is determined with the visiblebox attribute:

    <Image file="page.pdf" visiblebox="artbox" width="210mm" height="297mm" />

means that the "artbox" is displayed in the size 210mm × 297mm

The `page` attribute is also described in the section Embed multipage PDF files. It is used to select the page when a PDF file is embedded. With `sd:number-of-pages('filename')` it can be determined how many pages a PDF file contains.

## External Conversion Tools

The Publisher usually only processes PDF, PNG and JPEG files. In order to use other formats, you have to convert them into one of the three formats. This can be done in advance, but also during the runtime of the Publisher.

    <Layout xmlns="urn:speedata.de:2009/publisher/en"
      xmlns:sd="urn:speedata:2009/publisher/functions/en">

      <Record element="data">
        <PlaceObject>
          <!-- tiff can only be used with an external converter -->
          <Image file="rhslogo.tiff"/>
        </PlaceObject>
      </Record>
    </Layout>

To use the conversion, you have to enter the program calls in the configuration file. Here the program convert from ImageMagick is used:

    imagehandler="tiffimage:(convert %%input%% %%output%%.pdf)"
    extensionhandler="tiff:tiffimage"

The file name extension `.tiff` is assigned to the handler `tiffimage` (line 2). In the first line, the handler `tiffimage` is assigned to the program `convert %%input%% %%output%%%.pdf`, whereby the file names are replaced at runtime.

## Images from textual descriptions

There are countless picture description languages in which pictures are not drawn or painted with an external program, but are described textually. For example “draw a square with an edge length of 4cm” or “create a pie chart with the following values: …​”. These graphics are then converted from the description language into various formats, usually as PNG or PDF. With the Publisher it is possible to embed such descriptions since version 3.9.1:

    <Layout xmlns="urn:speedata.de:2009/publisher/en"
       xmlns:sd="urn:speedata:2009/publisher/functions/en">

       <Record element="data">
          <PlaceObject>
            <!-- we need to specify the imagetype -->
            <Image width="7cm" imagetype="mermaid" >
              <Value>sequenceDiagram
                participant Alice
                participant Bob
                Alice->>John: Hello John, how are you?
                loop Healthcheck
                    John->>John: Fight against hypochondria
                end
                Note right of John: Rational thoughts &lt;br/>prevail!
                John-->>Alice: Great!
                John->>Bob: How about you?
                Bob-->>John: Jolly good!
              </Value>
            </Image>
          </PlaceObject>
        </Record>
    </Layout>

Necessary is of course the configuration how the external converter is called. This works similar to the TIFF example in the previous section:

    imagehandler="mermaid:(/usr/bin/mmdc -i %%input%% -o %%output%%.pdf)"

The result is a sequence diagram, created by mermaid and converted to PDF.

Of course it is also possible to extract the image description from the data. For this purpose the image command must be structured as follows.

    <PlaceObject>
      <Image width="7cm" imagetype="mermaid" >
         <Value select="imagedata" />
      </Image>
    </PlaceObject>

## Other parameters

- You can use the padding-* specifications to define how much distance the image should have from the corresponding border.
- With dpiwarn you can issue a warning if the actual number of pixels per inch is less than the default.

- Programming
- Tables