← Back to branch summary

~ubuntu-branches/debian/sid/pyx/sid

« back to all changes in this revision

Viewing changes to manual/graphics.rst

  • Committer: Package Import Robot
  • Author(s): Stuart Prescott
  • Date: 2012-12-17 13:45:12 UTC
  • mfrom: (1.1.4)
  • mto: This revision was merged to the branch mainline in revision 10.
  • Revision ID: package-import@ubuntu.com-20121217134512-u0w6lrgdowsc1sfu
Tags: 0.12.1-1
* New upstream release
* Update maintainer address.
* Update copyright format URL.
* Bump standards version to 3.9.4 (no changes required).
* Drop postinst that was needed for lenny->squeeze upgrades.

Show diffs side-by-side

added added

removed removed

Lines of Context:
manual/graphics.rst
 
1
 
1
2
.. _graphics:
2
3
 
3
4
**************
16
17
curves. Such a path does not have to be connected but may also comprise several
17
18
disconnected segments, which will be called *subpaths* in the following.
18
19
 
19
 
XXX example for paths and subpaths (figure)
 
20
.. todo::
 
21
 
 
22
   example for paths and subpaths (figure)
20
23
 
21
24
Usually, a path is constructed by passing a list of the path primitives
22
25
:class:`moveto`, :class:`lineto`, :class:`curveto`, etc., to the constructor of
73
76
                     path.moveto(1, 0), path.lineto(0, 0))
74
77
 
75
78
which would construct a rectangle out of four disconnected subpaths (see Fig.
76
 
:ref:`fig_rects`\ a). In a better solution (see Fig. :ref:`fig_rects`\ b), the
 
79
:ref:`fig_rects` a). In a better solution (see Fig. :ref:`fig_rects` b), the
77
80
pen is not lifted between the first and the last point:
78
81
 
79
82
.. _fig_rects:
90
93
                     path.lineto(1, 1), path.lineto(1, 0),
91
94
                     path.lineto(0, 0))
92
95
 
93
 
However, as one can see in the lower left corner of Fig. :ref:`fig_rects`\ b,
 
96
However, as one can see in the lower left corner of Fig. :ref:`fig_rects` b,
94
97
the rectangle is still incomplete.  It needs to be closed, which can  be done
95
98
explicitly by using for the last straight line of the rectangle (from the point
96
99
:math:`(0, 1)` back to the origin at :math:`(0, 0)`) the :class:`closepath`
103
106
The :class:`closepath` directive adds a straight line from the current point to
104
107
the first point of the current subpath and furthermore *closes* the sub path,
105
108
i.e., it joins the beginning and the end of the line segment. This results in
106
 
the intended rectangle shown in Fig. :ref:`fig_rects`\ c. Note that filling the
 
109
the intended rectangle shown in Fig. :ref:`fig_rects` c. Note that filling the
107
110
path implicitly closes every open subpath, as is shown for a single subpath in
108
 
Fig. :ref:`fig_rects`\ d), which results from  ::
 
111
Fig. :ref:`fig_rects` d), which results from  ::
109
112
 
110
 
   c.stroke(rect2, [deco.filled([color.grey(0.95)])])
 
113
   c.stroke(rect2, [deco.filled([color.grey(0.5)])])
111
114
 
112
115
Here, we supply as second argument of the :meth:`stroke` method a list which in
113
116
the present case only consists of a single element, namely the so called
114
 
decorator :class:`deco.filled`. As it name says, this decorator specifies that
 
117
decorator :class:`deco.filled`. As its name says, this decorator specifies that
115
118
the path is not only being stroked but also filled with the given color. More
116
119
information about decorators, styles and other attributes which can be passed as
117
120
elements of the list can be found in Sect. :ref:`graphics_attributes`.  More
149
152
.. figure:: radii.*
150
153
   :align:  center
151
154
 
152
 
   Example: Intersection of circle with line yielding two radii.
 
155
   Example: Intersection of circle with line yielding two radii
153
156
 
154
157
Here, the basic elements, a circle around the point :math:`(0, 0)` with radius
155
158
:math:`2` and a straight line, are defined. Then, passing the *line*, to the
183
186
.. figure:: radii2.*
184
187
   :align:  center
185
188
 
186
 
   Example: Intersection of circle with line yielding radii and circle segment.
 
189
   Example: Intersection of circle with line yielding radii and circle segment
187
190
 
188
191
Here, we first split the circle using the :meth:`split` method passing the list
189
192
of parameters obtained above. Since the circle is closed, this yields two arc
209
212
circle consists just of one :class:`arc` together with a :class:`closepath`
210
213
element. However, this is not the case: the actual range is much larger. The
211
214
reason for this behaviour lies in the internal path handling of PyX: Before
212
 
performing any non-trivial geometrical operation with a path, it will
 
215
performing any non-trivial geometrical operation on a path, it will
213
216
automatically be converted into an instance of the :class:`normpath` class (see
214
217
also Sect. :class:`path.normpath`). These so generated paths are already separated
215
218
in their subpaths and only contain straight lines and Bézier curve segments.
216
 
Thus, as is easily imaginable, they are much simpler to deal with.
217
 
 
218
219
XXX explain normpathparams and things like p.begin(), p.end()-1,
219
220
 
220
221
A more geometrical way of accessing a point on the path is to use the arc length
233
234
will draw a straight line from a point at angle :math:`180` degrees (in radians
234
235
:math:`\pi`) to another point at angle :math:`270` degrees (in radians
235
236
:math:`3\pi/2`) on a circle with radius :math:`r=2`. Note however, that the
236
 
mapping arc length :math:`\to` point is in general discontinuous at the begin
 
237
mapping from an arc length to a point is in general discontinuous at the beginning
237
238
and the end of a subpath, and thus PyX does not guarantee any particular result
238
239
for this boundary case.
239
240
 
240
 
More information on the available path methods can be found  in Sect.
241
 
:class:`path.path`.
 
241
More information on the available path methods can be found in Sect. :ref:`postscript_like_paths`.
242
242
 
243
243
 
244
244
.. _graphics_attributes:
247
247
==================================
248
248
 
249
249
Attributes define properties of a given object when it is being used. Typically,
250
 
there are different kind of attributes which are usually orthogonal to each
 
250
there are different kinds of attributes which are usually orthogonal to each
251
251
other, while for one type of attribute, several choices are possible. An example
252
252
is the stroking of a path. There, linewidth and linestyle are different kind of
253
 
attributes. The linewidth might be normal, thin, thick, etc, and the linestyle
 
253
attributes. The linewidth might be thin, normal, thick, etc., and the linestyle
254
254
might be solid, dashed etc.
255
255
 
256
256
Attributes always occur in lists passed as an optional keyword argument to a
264
264
attributes useful default values are stored as member variables of the actual
265
265
attribute. For instance, ``style.linewidth.Thick`` is equivalent to
266
266
``style.linewidth(0.04, type="w", unit="cm")``, that is :math:`0.04` width cm
267
 
(see Sect. :mod:`unit` for more information about PyX's unit system).
 
267
(see Sect. :ref:`module_unit` for more information about PyX's unit system).
268
268
 
269
269
Another important feature of PyX attributes is what is call attributed merging.
270
270
A trivial example is the following::
275
275
 
276
276
Here, the ``style.linewidth.thin`` attribute overrides the preceding
277
277
``style.linewidth.Thick`` declaration. This is especially important in more
278
 
complex cases where PyXdefines default attributes for a certain operation. When
 
278
complex cases where PyX defines default attributes for a certain operation. When
279
279
calling the corresponding methods with an attribute list, this list is appended
280
280
to the list of defaults. This way, the user can easily override certain
281
281
defaults, while leaving the other default values intact. In addition, every
288
288
 
289
289
The clear attribute is also provided by the base classes of  the various styles.
290
290
For instance, :class:`style.strokestyle.clear` clears all strokestyle subclasses
291
 
and thus :class:`style.linewidth` and :class:`style.linestyle`. Since all
 
291
i.e. :class:`style.linewidth` and :class:`style.linestyle`. Since all
292
292
attributes derive from :class:`attr.attr`, you can remove all defaults using
293
 
``attr.clear``. An overview over the most important attribute typesprovided  by
 
293
``attr.clear``. An overview over the most important attribute types provided  by
294
294
PyX is given in the following table.
295
295
 
296
296
+----------------------------+---------------------------------+------------------------------------+
298
298
+============================+=================================+====================================+
299
299
| :class:`deco.deco`         | decorator specifying the way    | :class:`deco.stroked`,             |
300
300
|                            | the path is drawn               | :class:`deco.filled`,              |
301
 
|                            |                                 | :class:`deco.arrow`                |
 
301
|                            |                                 | :class:`deco.arrow`,               |
 
302
|                            |                                 | :class:`deco.text`                 |
302
303
+----------------------------+---------------------------------+------------------------------------+
303
304
| :class:`style.strokestyle` | style used for path stroking    | :class:`style.linecap`,            |
304
305
|                            |                                 | :class:`style.linejoin`,           |
311
312
| :class:`style.fillstyle`   | style used for path filling     | :class:`color.color`,              |
312
313
|                            |                                 | :class:`pattern.pattern`           |
313
314
+----------------------------+---------------------------------+------------------------------------+
314
 
| :class:`style.filltype`    | type of path filling            | ``style.filltype.nonzero_winding`` |
 
315
| :class:`style.filltype`    | type of path filling            | ``style.fillrule.nonzero_winding`` |
315
316
|                            |                                 | (default),                         |
316
 
|                            |                                 | ``style.filltype.even_odd``        |
 
317
|                            |                                 | ``style.fillrule.even_odd``        |
317
318
+----------------------------+---------------------------------+------------------------------------+
318
319
| :class:`deformer.deformer` | operations changing the shape   | :class:`deformer.cycloid`,         |
319
320
|                            | of the path                     | :class:`deformer.smoothed`         |
325
326
|                            |                                 | :class:`text.size`,                |
326
327
|                            |                                 | :class:`text.parbox`               |
327
328
+----------------------------+---------------------------------+------------------------------------+
328
 
| :class:`trafo.trafo`       | ransformations applied when     | :class:`trafo.mirror`,             |
 
329
| :class:`trafo.trafo`       | transformations applied when    | :class:`trafo.mirror`,             |
329
330
|                            | drawing object                  | :class:`trafo.rotate`,             |
330
331
|                            |                                 | :class:`trafo.scale`,              |
331
332
|                            |                                 | :class:`trafo.slant`,              |
332
333
|                            |                                 | :class:`trafo.translate`           |
333
334
+----------------------------+---------------------------------+------------------------------------+
334
335
 
335
 
XXX specify which classes in the table are in fact instances
 
336
.. todo::
 
337
 
 
338
   specify which classes in the table are in fact instances
336
339
 
337
340
Note that operations usually allow for certain attribute categories only. For
338
341
example when stroking a path, text attributes are not allowed, while stroke
362
365
 
363
366
   c.stroke(path, [deco.earrow(angle=30)])
364
367
 
365
 
XXX changeable attributes
 
368
.. todo::
 
369
 
 
370
   changeable attributes
366
371