manual/svgfile.rst

   1
   2 .. module:: svgfile
   3
   4 *****************************************
   5 Module :mod:`svgfile`: SVG file inclusion
   6 *****************************************
   7
   8 With the help of the ``svgfile.svgfile`` class, you can easily embed another SVG
   9 file in your canvas, thereby scaling, aligning the content at discretion. The
  10 most simple example looks like
  11
  12    ::
  13
  14       from pyx import *
  15       c = canvas.canvas()
  16       c.insert(svgfile.svgfile(0, 0, "file.svg"))
  17       c.writeSVGfile("output")
  18
  19
  20 All relevant parameters are passed to the ``svgfile.svgfile`` constructor. They
  21 are summarized in the following table:
  22
  23 +---------------------+-----------------------------------------------+
  24 | argument name       | description                                   |
  25 +=====================+===============================================+
  26 | ``x``               | :math:`x`\ -coordinate of position.           |
  27 +---------------------+-----------------------------------------------+
  28 | ``y``               | :math:`y`\ -coordinate of position.           |
  29 +---------------------+-----------------------------------------------+
  30 | ``filename``        | Name of the SVG file.                         |
  31 +---------------------+-----------------------------------------------+
  32 | ``width=None``      | Desired width of SVG graphics or ``None`` for |
  33 |                     | original width.                               |
  34 +---------------------+-----------------------------------------------+
  35 | ``height=None``     | Desired height of SVG graphics or ``None``    |
  36 |                     | for original height.                          |
  37 +---------------------+-----------------------------------------------+
  38 | ``ratio=None``      | For a given width or height set the other     |
  39 |                     | dimension with the given ratio. If ``None``   |
  40 |                     | and either width or height is set, the other  |
  41 |                     | dimension is scaled proportionally, which     |
  42 |                     | is different from a ratio ``1``.              |
  43 +---------------------+-----------------------------------------------+
  44 | ``parsed=False``    | Parsed mode flag, see below.                  |
  45 +---------------------+-----------------------------------------------+
  46 | ``resolution=96``   | SVG resolution in "dpi", see below.           |
  47 +---------------------+-----------------------------------------------+
  48
  49 The parsed mode creates a filled PyX canvas from the SVG data. At the moment
  50 it properly parses paths with styles, transformations, canvas nesting etc. but
  51 no other SVG constructs. While some features might be added in the future, it
  52 will probably always have rather strong limitations, like not being able to
  53 take into account CSS styling and other things. However, on the other hand
  54 parsed mode still has some major advantages. You can access the paths as PyX
  55 paths from the canvas and you can output the parsed SVG data to PostScript and
  56 PDF.
  57
  58 SVG files have a resolution, even though SVG is a vector format. The resolution
  59 defines the unit scale, when no unit like ``pt``, ``in``, ``mm``, or ``cm`` is
  60 used. This user unit is meant to be pixels, thus viewer programs are adviced
  61 and typically use the screen resolution. Tools to SVG files often use 90 dpi as
  62 in the w3.org SVG Recommendation. However, note that Adobe Illustrator (r) uses
  63 72 dpi. In Browsers we found 96 dpi to be used, which we thus took as the
  64 default. However, all this might vary between plattforms and configurations.
  65
  66 Note that the PyX SVG output defines the size of the output in ``pt``. However,
  67 even when reading such a file in un-parsed mode we need to make assumtions on
  68 how the final viewer will insert (i.e. scale and position) the SVG file, thus
  69 needing a resolution. In parsed mode it becomes resolution independent.
  70 Unfortunately it is rather uncommon to store the size of the SVG in coordinates
  71 with units. You then need to provide the correct resolution in both modes,
  72 parsed and unparsed, to get proper alignment.
  73