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
- 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.10.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
- 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

Includes an external Graphic. Allowed graphic formats are PDF (.pdf), PNG (.png) and JPEG (.jpg). See below for a limitation on the number of included PDF files.

## Child elements

`Value`

## Parent elements

`A`, `B`, `Case`, `Fontface`, `ForAll`, `Frame`, `I`, `Li`, `While`

## Attributes

`bleed` (optional, since version 2.9.5)

  Should the image size increase by the amount of bleed setting (Options)?

  `auto`

    If the image touches a paper edge, extend the image in that direction.

  `no`

    Do not extend the image.

`class` (text, optional, since version 2.5.11)

  CSS class for this element.

`clip` (optional)

  When yes, the image keeps its aspect ratio if both width and hight is given. To be able to fit the image into the given dimensions, the image gets clipped.

  `yes`

    Keep the aspect ratio and cut off left/right or top/bottom edges.

  `no`

    Distort the image to make it fit in the given area.

`dpiwarn` (number, optional)

  Warn if the image gets lower resolution than given.

`fallback` (optional, since version 2.3.77)

  The filename of the replacement image if the file is not found. If none given, a red 'file not found' image will gets displayed.

`file` (text, optional)

  Filename of the image. Can be a file in the search path, an absolute file name, a file-URI for absolute paths (e.g. `file:///path/to/image.pdf`) or a location on the web (http, https).

`height` (number or length, optional)

  Image height. One of 'auto' (default, take image width), length (such as '3cm') or number (in grid cells).

`id` (text, optional, since version 2.5.11)

  CSS id for this element.

`imageshape` (yes or no, optional, since version 4.9.8)

  Try to load an image shape. Defaults to no.

`imagetype` (optional, since version 3.9.1)

  Set the converter to be used for the enclosed image (if any).

`maxheight` (number or length, optional)

  The maximum height of the image. Only used when clip="no". Value is a number (grid cells) or a length.

`maxwidth` (number or length, optional)

  The maximum width of the image. Only used when clip="no". Value is a number (grid cells), a length or the value »100%« for full width image.

`minheight` (number or length, optional)

  The minimum height of the image. Only used when clip="no". Value is a number (grid cells) or a length.

`minwidth` (number or length, optional)

  The minimum width of the image. Only used when clip="no". Value is a number (grid cells), a length or the value »100%« for full width image.

`opacity` (number, optional, since version 4.3.15)

  Set image opacity (0-100, 100=fully opaque).

`padding` (length, optional, since version 2.9.5)

  Set padding for all four sides.

`padding-bottom` (length, optional, CSS property: padding-bottom, since version 2.5.11)

  Set the inner distance (width between contents and the border) to the bottom edge.

`padding-left` (length, optional, CSS property: padding-left, since version 2.5.11)

  Set the inner distance (width between contents and the border) to the left edge.

`padding-right` (length, optional, CSS property: padding-right, since version 2.5.11)

  Set the inner distance (width between contents and the border) to the right edge.

`padding-top` (length, optional, CSS property: padding-top, since version 2.5.11)

  Set the inner distance (width between contents and the border) to the top edge.

`page` (number, optional)

  The page number from the PDF. Default is 1 (include the first page).

`rotate` (number, optional)

  Rotate the image in steps of 90°. The amount of movement is defined by the specified angle; if positive, the movement will be clockwise, if negative, it will be counter-clockwise.

`stretch` (yes or no, optional, since version 4.3.8)

  Stretch image until one of maximum width and maximum height is reached. Useful if images should be as large as possible but should not use more than the given space.

`visiblebox` (optional)

  The PDF box that represents the visible area of the included image. Default is “cropbox”.

  `artbox`

    Use the artbox as the visible area. The artbox is usually not contained in a PDF.

  `bleedbox`

    Use the bleedbox of the included PDF.

  `cropbox`

    Use the cropbox of the included PDF (default).

  `mediabox`

    Use the mediabox of the included PDF. This is the largest box.

  `trimbox`

    Use the trimbox of the includes PDF. The trimbox is the final paper size. For example, the trim box of an A4 PDF is 210mm x 297mm.

`width` (number or length, optional)

  Image width. One of 'auto' (default, take image width), '100%' (whole area width), length (such as '3cm') or number (in grid cells).

## Remarks

The values of the attributes naturalsize and maxsize can be ‘artbox’, ‘bleedbox’, ‘cropbox’, ‘mediabox’ and ‘trimbox’. These two values are used to enlarge the image for the bleed. In the second example below the designated view port of the image is defined in the artbox, but the image has a larger area (the cropbox) that is used for bleeding.

## Example

    <Record element="productdata">
      <PlaceObject column="{ $column }">
        <Image width="10" file="{ string(.) }"/>
      </PlaceObject>
    </Record>

Takes the file name of the image from the contents of the current element in the data file (here: productdata). Sample data XML:

    <productdata>image.pdf</productdata>

## Info

The number of pages in a PDF file can be determined with the XPath function `sd:number-of-pages(<filename or URI>).`

Attention. The number of PDF files that can be included in a document is limited. This limit can be increased in is system dependant. On Mac OS X it can be queried with `ulimit -a` and set for example with `ulimit -n 1024`.

## See also

The section about `<Image>` in the basics chapter, File organization

- I
- Include