1.11. Images and Figures

1.11.1. SVG Graphics only

All vector graphics or diagrams should be SVG files. This helps us keep our graphic conversion tooling simple, and generally results in higher-quality representation. SVG graphics with an parameterized opacity (transparency) should be possible as well as an animated SVG, see Figure 1.1 and Figure 1.2.

Figure 1.1 Example of transparent SVG 1

Figure 1.2 Example of animated SVG 2

Whenever possible, you should generate your graphics as SVG rather than converting to SVG from another format. That avoids bitmap raster images embedded in a SVG container. The goal of SVG usage is to hold vector graphic as long as possible, from the editor up to the presentation. If you have to start in another vector graphic format use lossless vector formats whenever possible. These include EPS/PS, AI, DXF, EMF/EMZ, WMF/WMZ or some special XML vector graphics schemes. In any case avoid embedded bitmaps, as this is a lossy format for vector informations that does not replicate scaling very well. Figure 1.3 demonstrates differences between bitmapped raster and vector graphics. The bitmap raster is composed of a fixed set of pixels, while the vector is composed of a fixed set of shapes. In the picture, scaling the bitmap reveals the pixels while scaling the vector image preserves the shapes.

Figure 1.3 Demonstration of differences between bitmapped raster and vector images. 3

Bitmap raster images are good for photographic images or screenshots but not for stencils, sketches, diagrams or graphs and often they do not support transparency.

—Superuser - JPEG vs. PNG vs. BMP vs. GIF vs. SVG

Raster graphics are resolution dependent, meaning they cannot scale up to an arbitrary resolution without loss of apparent quality. This property contrasts with the capabilities of vector graphics, which easily scale up to the quality of the device rendering them. Raster graphics deal more practically than vector graphics with photographs and photo-realistic images, while vector graphics often serve better for typesetting or for graphic design.

—Wikipedia - Raster graphics

Vector graphics have the unique advantage over raster graphics in that the points, lines, and curves may be scaled up or down to any resolution with no aliasing.

—Wikipedia - Vector graphics

Footnotes

1

Indication of provenance: STEAMcoded.org: atom1.svg (public domain for teachers and students learning to code)

2

Indication of provenance: STEAMcoded.org: atom.svg (public domain for teachers and students learning to code)

3

Indication of provenance: Wikimedia: 6/6b/Bitmap_VS_SVG.svg (licensed under CC-BY-SA-2.5)

1.11.2. PNG Images only

All still bitmap raster images or photos should be PNG files. This helps us keep our image compression tooling simple, and generally results in higher-quality screenshots. PNG images with an 8-bit transparency channel should be possible as well as an animated PNG, see Figure 1.4 and Figure 1.5.

Figure 1.4 Example of transparent PNG 4

Figure 1.5 Example of animated PNG 5

Whenever possible, you should generate your images as PNG rather than converting to PNG from another format. If you have to start in another format, use lossless formats whenever possible. These include BMP/DIB, GIF, and TIFF. Avoid JPEG/JFIF if possible, as this is a lossy format that does not replicate screenshots very well. Figure 1.6 comparing lossy compression in JPEG with lossless compression in PNG: the JPEG artifacts can be easily visible in the background of this kind of image data, where the PNG image has solid color.

Figure 1.6 Demonstration of differences between lossy encoding and lossless method. 6

JPEG is good for photographic images but not for sharp transitions and does not support transparency.

—Wikipedia - PNG comparison with JPEG

The JPEG format can produce a smaller file than PNG for photographic (and photo-like) images, since JPEG uses a lossy encoding method specifically designed for photographic image data. Using PNG instead of a high-quality JPEG for such images would result in a large increase in file size with negligible gain in quality. In comparison, when storing images that contain text, line art, or graphics – images with sharp transitions and large areas of solid color – the PNG format can compress image data more than JPEG can. Additionally, PNG is lossless, while JPEG produces visual artifacts around high-contrast areas.

JPEG’s lossy compression also suffers from generation loss, where repeatedly decoding and re-encoding an image to save it again causes a loss of information each time, degrading the image. This does not happen with repeated viewing or copying, but only if the file is edited and saved over again. Because PNG is lossless, it is suitable for storing images to be edited.

Where an image contains both sharp transitions and photographic parts, a choice must be made between the two effects:

Footnotes

4

Indication of provenance: Wikimedia: 4/47/PNG_transparency_demonstration_1.png (licensed under CC-BY-SA-3.0)

5

Indication of provenance: Wikimedia: 1/14/Animated_PNG_example_bouncing_beach_ball.png (released into the public domain by its author, Holger Will)

6

Indication of provenance: Superuser: a/55706, http://lbrandy.com/assets/jpg_vs_png2.png (licensed under CC-BY-SA-3.0)

1.11.3. Inserting

To place an graphic or image in a document, use the .. image:: directive (see Image).

.. image:: /img/{absolut-document-subdirectory}/{file}.svg
  :alt: Alt text. Every image should have descriptive alt text.

.. image:: {relative-document-subdirectory}/{file}.*
  :alt: Alt text. Every image should have descriptive alt text.

Note the literal asterisk (*) at the end, in place of a file extension. Use the asterisk, and omit the file extension (see reStructuredText Primer, section Images).

.. image::

The example

.. image:: /_images/lpn.svg
   :alt: The Li-Pro.Net logo. (explicitely as SVG)
   :height: 32px
   :width: 32px

.. image:: /_images/lpn.*
   :alt: The Li-Pro.Net logo. (scaled to the half)
   :scale: 50 %
   :align: right

Which gives

1.11.4. Inserting with Captions

Use .. figure:: directive to markup a graphic or image with a caption (see Figure).

.. figure:: {file-with-directory-same-as-for image}.*
  :alt: Alt text. Every image should have descriptive alt text.

  The rest of the indented content will be the (optional) caption.
  This can be a short sentence or multiline paragraph.

Captions can contain any other complex reStructuredText markup. Further paragraphs after the caption will be the (optional) legend which are also arbitrary body elements.

.. figure::

The example

.. figure:: /_images/lpn.*
   :name: the-lpn-logo
   :alt: The Li-Pro.Net logo.
   :figclass: align-center
   :align: center
   :scale: 75 %

   The |ghlpn|_ logo.

   Legend of all elements you can see in the graphic:

   .. list-table:: The legend for the |ghlpn|_ logo.
      :widths: 10 40
      :width: 50 %
      :align: center
      :header-rows: 1
      :stub-columns: 1

      * - Letter
        - Meaning
      * - L (in blue)
        - Li
      * - P (in blue)
        - Pro
      * - N (in red)
        - Net

.. |ghlpn| unicode:: Li U+02013 Pro.Net U+0040 GitHub
.. _`ghlpn`: https://github.com/lipro

Which gives

Figure 1.7 The Li–Pro.Net@GitHub logo.

Legend of all elements you can see in the graphic:

Table 1.3 The legend for the Li–Pro.Net@GitHub logo.

Letter	Meaning
L (in blue)	Li
P (in blue)	Pro
N (in red)	Net

1.11.5. Inserting Inline

To information on creating inline images, see Inline Image.