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 In parsed mode a filled PyX canvas containing the SVG data is created. At the
  50 moment the parser handles paths with styles, transformations, canvas nesting
  51 etc. but no other SVG constructs. While some features might be added in the
  52 future, the parsed mode will probably always have limitations, like not being
  53 able to take into account CSS styling and other things. On the other hand the
  54 parsed mode has some major advantages. You can access the paths as PyX paths
  55 within the canvas and you can output the parsed SVG data to PostScript and PDF.
  56
  57 Even though SVG is a vector format, inserting an SVG file depends on a
  58 resolution most of the time. This resolution defines the unit scale, when no
  59 unit like ``pt``, ``in``, ``mm``, or ``cm`` is used. This user unit is meant to
  60 be pixels, thus viewer programs are adviced to use the screen resolution. Tools
  61 to SVG files often use 90 dpi as in the w3.org SVG Recommendation. However,
  62 note that Adobe (R) Illustrator (R) uses 72 dpi. In browsers 96 dpi is commonly
  63 used, which is thus set as the default. However, all this might vary between
  64 plattforms and configurations.
  65
  66 Note that the SVG output of PyX defines the its size using units. Still, when
  67 reading such a file in un-parsed mode PyX need to make assumtions on how the
  68 final viewer will insert (i.e. scale and position) the SVG file, thus needing a
  69 resolution. Only in parsed mode it becomes resolution independent.
  70
  71 Unfortunately it is rather uncommon to store the size of the SVG in coordinates
  72 with units. You then need to provide the correct resolution in both modes,
  73 parsed and unparsed, to get proper alignment.
  74