Graphics

Referencing images and other graphics such as embedded SVG and MathML.

Images

Images are very important in any printed material. This section contains information about how you can reference them from your HTML or XML documents.

For HTML, the img tag is recognized as an image without any other styling in your CSS files:

...
<p> And this is the picture of a happy face: <img src="happy.png" />. </p>
...

For XML, you must add CSS rules that pick up the content of an attribute and uses it as a source for an image.

...
<para> And this is the picture of a happy face: <imagedata fileref="happy.png"/>.</para>
...

The following example uses static content on the imagedata before pseudo element:

imagedata[fileref]:before {
    content: attr(fileref, url);
}

It is important to use the url keyword when retrieving the attribute value. It signals that the value is a pointer to an external image.

Setting Image Width and Height

The image size can be determined from the number of pixels of the image, taking the image resolution into account (if available). There are cases where this computed size is not what you need, and you want to specify the size explicitly.

For HTML, it is enough to use the image attributes directly in your document.

<img src="my_image.png" width="300" height="250" />

For an arbitrary XML, you can indicate the image width and height through a rule that matches the element (or its pseudo elements :before or :after) and sets the width and height CSS properties.

imagedata {
    display: inline;
    content: attr(src, url);
    width: attr(width, length);
    height: attr(height, length);
}

Or, if you use an image as a decorator, you can specify fixed dimensions in the CSS:

chapter title:before {
    content: url("my_artwork.png");
    width: 300px;
}
Note: For static content as in the example above, Oxygen PDF Chemistry tries to use the width and height set on the pseudo element, then the ones that are set on the parent element, but only if the static content is composed of a single image. Mixing text and images in the content property disables the width and height specification.

If you want to limit the width of the images to a maximum size, you can use the max-width property. The image will be scaled down to fit the maximum size, if it is larger.

imagedata {
    ...
    content: attr(src, url);
    max-width: attr(width, length); 
    ...
}

Background Images

You can use background images to impose a texture. You can use them to decorate an entire page, or a specific element from your document.

Supported properties:

  • background-image
  • background-repeat
  • background-position

Page Background Images

You can set a background for a page. Usually you do this for the cover page to impose a full page artwork, or to add graphics to the header and footer of the page. Here is an example of how can you do it for the page:

@page cover {
    size:A4;
    margin:1in;    
    background-image:url("images/my_book_cover_artwork.png");
    background-repeat:no-repeat;
}

div.cover {
    page: cover;
}
Note: It is better to use SVG for the page artworks. It does not suffer from pixelation. If you are limited to using raster images, you can fine tune their resolution by using the image-resolution property.
Note: To separate the header and footer from the main content using visual effects (lines, shadows, etc.), you can use a full page size artwork in SVG and set it to the default page:
@page {
    background-image:url("images/my_header_footer_artwork.svg");
    background-repeat:no-repeat;
}

If your artwork is smaller, consider a "DRAFT" watermark (for instance). You should use the background-position to place it where you need:

@page {
    ...
    background-image:url("images/draft.svg");
    background-position: bottom center;
    ...
}

Element Background Images

You can style the background of your elements as you do for web pages:

section {
    background-image: url("my_repeating_pattern.svg");
    background-repeat: repeat-y;
}

Image Resolution

Some raster images (pixels, not vector) may have a default resolution, set by the designer, using an image editing software. Usually the image size and resolution are set to look best on the screen. The advantage of a resolution set in the image itself it is that it will have the same effective size on the screen and on paper. For example, if the image has 144 dots in width, and an embedded resolution of 72dpi, it will be two inches on screen and on paper.

The problems start to arise when the resolution is not set in the image, and the PDF processor has to decide what resolution to use in order to determine the size of the graphic. To solve this, the processor extracts the DPI from:

  • The image-resolution CSS property associated to the element that contains the image.
  • The command line parameter -image-resolution .
  • The built-in fallback resolution of 96 DPI.

The recommended way to change this is by using the CSS Level 4 image-resolution property:

img {
    image-resolution: 300dpi;
}
Note: The image-resolution is inheritable, so you can associate it on the root element. It does not apply on the page generated content (margin boxes).
:root {
    image-resolution: 300dpi;
}
To reset the image resolution to the one set in the image itself, you can use the constant from-image instead of a DPI value:
title:before {
    content: url("chapter-decorator.png");
    image-resolution: from-image;
}
Note: To change the resolution for images that appear in a page margin box, set this property on that margin box, or directly on the @page rule, to apply to all page margin boxes:
@page front-page {
    image-resolution: 600dpi;
}

@page {
    @top-center {
        image-resolution: 600dpi;
        content: url("company-logo.png");
    }
}

Supported Image Types

Oxygen PDF Chemistry supports the following raster image types:

  • BMP (Microsoft Windows Bitmap)
  • GIF (Graphics Interchange Format)
  • JPEG (Joint Photographic Experts Group)
  • PNG (Portable Network Graphic)
  • TIFF (Tag Image Format File)

And the following vector images:

  • SVG (Scalable Vector Graphics)
  • WMF (Windows Metafile)
  • PDF (PDF Documents)

PDF Images

You can reference PDF images the same way other image files are referenced:

<img src="my_doc.pdf"/>

To point to a single page from your PDF document, use the following syntax (this example points to page 5):

<img src="my_doc.pdf#page=5"/>

SVG

Oxygen PDF Chemistry supports SVG images. The advantage of using SVG is that the image looks good on paper.

SVG Referenced or Embedded into the Document

These can be either referenced as external resources:

<p> This is an SVG showing a happy face: <img src="happy.svg"/></p>

Or embedded into the document, as SVG fragments:

<p> This is a red circle: 
   <svg xmlns='http://www.w3.org/2000/svg' viewBox="0 0 50 50" width="50" height="50">
       <circle cx="25" cy="25" r="10" fill="#F00" />
   </svg>
</p>
Note: No styling is required to show the embedded SVG in the output. It works automatically for HTML or other XML.
Note: For HTML5, the namespace declaration is not required.

Using SVG for Styling

To use it to decorate an element:

div.note:before {
    content:url("images/note.svg");
}

To set an SVG image as background of a page, or a page margin box:

@page coverpage{
    background-image: url("images/clipart.svg");
    background-repeat:no-repeat;
    background-position:center center;
    
    @top-left {
        background-image: url("images/company.svg");
        background-repeat:no-repeat;
    }
}
Note: The image-resolution CSS property does not apply for SVG vectors.

MathML

MathML equations can be either referenced from the document as external resources (the file should be ending with the "mml" extension):

<p> The quadratic formula: <img src="quadratic.mml"/></p>

Or embedded directly in the document:

  <p> The quadratic formula:
   <math>
    <mi>x</mi>
    <mo>=</mo>
    <mfrac>
     <mrow>
      <mo form="prefix"></mo> <mi>b</mi>
      <mo>±</mo>
      <msqrt>
       <msup> <mi>b</mi> <mn>2</mn> </msup>
       <mo></mo>
       <mn>4</mn> <mo></mo> <mi>a</mi> <mo></mo> <mi>c</mi>
      </msqrt>
     </mrow>
     <mrow>
      <mn>2</mn> <mo></mo> <mi>a</mi>
     </mrow>
    </mfrac>
   </math>
  </p>
Note: No styling is required to show the embedded MathML in the output. It works automatically for HTML or other XML.
Note: For HTML5 the namespace declaration is not required.

Supported Colors

Along with the usual color values, Oxygen PDF Chemistry supports the following special values for all the color properties:

  • rgb - Used to specify red, green, and blue components (for example, color="rgb(255 , 0 , 153)").
  • rbga - Used for transparent colors by specifying each color channel and the transparency. For example, the following would result in the background color being magenta since the red color from the parent div element will be visible through the blue color of the p element:
    div{
      background-color:rgba(255,0,0,0.3)
    }
    p{
      background-color:rgba(0,0,255,0.3)
    }

For more information about color properties, see MDN Web Docs: Color.