From 13bbb86a9f31d9c578af046e7f8cbe0a0a9ed4b9 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Andr=C3=A9=20Wobst?= Date: Sun, 10 Jul 2011 16:04:02 +0000 Subject: [PATCH] improvements to the documentation by GLI git-svn-id: https://pyx.svn.sourceforge.net/svnroot/pyx/trunk/pyx@3193 069f4177-920e-0410-937b-c2a4a81bcd90 --- manual/bbox.rst | 11 ++- manual/canvas.rst | 74 +++++++++-------- manual/color.rst | 2 +- manual/deformer.rst | 41 +++++----- manual/epsfile.rst | 1 + manual/gradientname.rst | 1 + manual/graphics.rst | 56 +++++++------ manual/manual.rst | 1 + manual/path.rst | 171 +++++++++++++++++++-------------------- manual/pattern.rst | 1 + manual/radii2.py | 2 +- manual/text.rst | 4 +- manual/trafo.rst | 211 ++++++++++++++++++++++++------------------------ manual/unit.rst | 6 +- 14 files changed, 302 insertions(+), 280 deletions(-) rewrite manual/trafo.rst (77%) diff --git a/manual/bbox.rst b/manual/bbox.rst index 05f48d3a..4a05a238 100644 --- a/manual/bbox.rst +++ b/manual/bbox.rst @@ -1,3 +1,6 @@ + +.. _bbox_module: + .. module:: bbox ****************** @@ -10,8 +13,8 @@ Usually, you obtain ``bbox`` instances as return values of the corresponding ``bbox())`` method, but you may also construct a bounding box by yourself. -bbox constructor -================ +:class:`bbox` constructor +========================= The ``bbox`` constructor accepts the following keyword arguments @@ -36,8 +39,8 @@ The ``bbox`` constructor accepts the following keyword arguments +---------+-----------------------------------------------+ -bbox methods -============ +:class:`bbox` methods +===================== +-------------------------------------------+-----------------------------------------------+ | ``bbox`` method | function | diff --git a/manual/canvas.rst b/manual/canvas.rst index 30fb2b7b..4e79e19c 100644 --- a/manual/canvas.rst +++ b/manual/canvas.rst @@ -8,22 +8,17 @@ Module :mod:`canvas` .. sectionauthor:: Jörg Lehmann -One of the central modules for the PostScript access in PyX is named ``canvas``. -Besides providing the class ``canvas``, which presents a collection of visual -elements like paths, other canvases, TeX or LaTeX elements, it contains the -class ``canvas.clip`` which allows clipping of the output. +In addition it +contains the class ``canvas.clip`` which allows clipping of the output. -A canvas may also be embedded in another one using its ``insert`` method. This -may be useful when you want to apply a transformation on a whole set of -operations.. +Class :class:`canvas` +--------------------- -Class canvas ------------- - -This is the basic class of the canvas module, which serves to collect various -graphical and text elements you want to write eventually to an (E)PS file. - +This is the basic class of the canvas module. Instances of this class collect +visual elements like paths, other canvases, TeX or LaTeX elements. A canvas may +also be embedded in another one using its ``insert`` method. This may be useful +when you want to apply a transformation on a whole set of operations. .. class:: canvas(attrs=[], texrunner=None) @@ -38,7 +33,10 @@ Paths can be drawn on the canvas using one of the following methods: .. method:: canvas.draw(path, attrs) - Draws *path* on the canvas applying the given *attrs*. + Draws *path* on the canvas applying the given *attrs*. Depending on the + *attrs* the path will be filled, stroked, ornamented, or a combination + thereof. For the common first two cases the following two convenience + functions are provided. .. method:: canvas.fill(path, attrs=[]) @@ -57,9 +55,9 @@ in the canvas using .. method:: canvas.insert(item, attrs=[]) Inserts an instance of :class:`base.canvasitem` into the canvas. If *attrs* are - present, *item* is inserted into a new :class:`canvas`\ instance with *attrs* as - arguments passed to its constructor is created. Then this :class:`canvas` - instance is inserted itself into the canvas. + present, *item* is inserted into a new :class:`canvas` instance with *attrs* + as arguments passed to its constructor. Then this :class:`canvas` instance + is inserted itself into the canvas. Text output on the canvas is possible using @@ -67,7 +65,7 @@ Text output on the canvas is possible using .. method:: canvas.text(x, y, text, attrs=[]) Inserts *text* at position (*x*, *y*) into the canvas applying *attrs*. This is - a shortcut for ``insert(texrunner.text(x, y, text, attrs))``). + a shortcut for ``insert(texrunner.text(x, y, text, attrs))``. The :class:`canvas` class provides access to the total geometrical size of its element: @@ -75,17 +73,17 @@ element: .. method:: canvas.bbox() - Returns the bounding box enclosing all elements of the canvas. + Returns the bounding box enclosing all elements of the canvas (see Sect. :ref:`bbox_module`). -A canvas also allows one to set its TeX runner: +A canvas also allows to set its TeX runner: .. method:: canvas.settexrunner(texrunner) Sets a new *texrunner* for the canvas. -The contents of the canvas can be written using the following two convenience -methods, which wrap the canvas into a single page document. +The contents of the canvas can be written to a file using the following +convenience methods, which wrap the canvas into a single page document. .. method:: canvas.writeEPSfile(file, *args, **kwargs) @@ -94,7 +92,7 @@ methods, which wrap the canvas into a single page document. write method or it is used as a string containing the filename (the extension ``.eps`` is appended automatically, if it is not present). This method constructs a single page document, passing *args* and *kwargs* to the - :class:`document.page` constructor and the calls the :meth:`writeEPSfile` method + :class:`document.page` constructor and calls the :meth:`writeEPSfile` method of this :class:`document.document` instance passing the *file*. @@ -118,11 +116,11 @@ methods, which wrap the canvas into a single page document. .. method:: canvas.pipeGS(filename="-", device=None, resolution=100, gscommand="gs", gsoptions="", textalphabits=4, graphicsalphabits=4, ciecolor=False, input="eps", **kwargs) This method pipes the content of a canvas to the ghostscript interpreter - directly to generate other output formats. At least *filename* or *device* must + to generate other output formats. At least *filename* or *device* must be set. *filename* specifies the name of the output file. No file extension will - be added to that name in any case. When no *filename* is specified, the output + be added to that name. When no *filename* is specified, the output is written to stdout. *device* specifies a ghostscript output device by a - string. Depending on your ghostscript configuration ``"png16"``, ``"png16m"``, + string. Depending on the ghostscript configuration ``"png16"``, ``"png16m"``, ``"png256"``, ``"png48"``, ``"pngalpha"``, ``"pnggray"``, ``"pngmono"``, ``"jpeg"``, and ``"jpeggray"`` might be available among others. See the output of ``gs --help`` and the ghostscript documentation for more information. When @@ -131,14 +129,15 @@ methods, which wrap the canvas into a single page document. ``.jpg``. *resolution* specifies the resolution in dpi (dots per inch). *gscmd* is the - command to be used to invoke ghostscript. *gsoptions* are an option string - passed to the ghostscript interpreter. *textalphabits* are *graphicsalphabits* - are conventient parameters to set the ``TextAlphaBits`` and - ``GraphicsAlphaBits`` options of ghostscript. You can skip the addition of those - option by set their value to ``None``. *ciecolor* adds the ``-dUseCIEColor`` - flag to improve the CMYK to RGB color conversion. *input* can be either - ``"eps"`` or ``"pdf"`` to select the input type to be passed to ghostscript - (note slightly different features available in the different input types). + command to be used to invoke ghostscript. *gsoptions* is an option string + passed to the ghostscript interpreter. *textalphabits* and *graphicsalphabits* + are convenient parameters to set the ``TextAlphaBits`` and + ``GraphicsAlphaBits`` options of ghostscript. The addition of these options + can be skipped by setting their values to ``None``. *ciecolor* adds the + ``-dUseCIEColor`` flag to improve the CMYK to RGB color conversion. *input* + can be either ``"eps"`` or ``"pdf"`` to select the input type to be passed + to ghostscript (note slightly different features available in the different + input types regarding e.g. :mod:`epsfile` inclusion and transparency). *kwargs* are passed to the :meth:`writeEPSfile` method (not counting the *file* parameter), which is used to generate the input for ghostscript. By that you @@ -147,3 +146,10 @@ methods, which wrap the canvas into a single page document. For more information about the possible arguments of the :class:`document.page` constructor, we refer to Sect. :mod:`document`. + +Class :class:`clip` +--------------------- + +In addition the canvas module contains the class ``canvas.clip`` which allows for +clipping of the output by passing a clipping instance to the attrs parameter of +the canvas constructor. diff --git a/manual/color.rst b/manual/color.rst index 724b85d4..f905bd69 100644 --- a/manual/color.rst +++ b/manual/color.rst @@ -53,7 +53,7 @@ The file ``color.eps`` is created and looks like: Color gradients =============== -The color module provides a class ``gradient`` for continous transitions between +The color module provides a class :class:`gradient` for continous transitions between colors. A list of named gradients is available in appendix :ref:`gradientname`. diff --git a/manual/deformer.rst b/manual/deformer.rst index e6baaa45..15fdad56 100644 --- a/manual/deformer.rst +++ b/manual/deformer.rst @@ -7,9 +7,8 @@ Module :mod:`deformer`: Path deformers The :mod:`deformer` module provides techniques to generate modulated paths. All classes in the :mod:`deformer` module can be used as attributes when -drawing/stroking paths onto a canvas, but also independently for manipulating -previously created paths. The difference to the classes in the :mod:`deco` -module is that here, a totally new path is constructed. +drawing/stroking paths onto a canvas. Alternatively new paths can be created by +deforming an existing path by means of the :meth:`deform` method. All classes of the :mod:`deformer` module provide the following methods: @@ -43,22 +42,23 @@ The deformer classes are the following: *curvesperhloop*: the number of Bezier curves to approximate a half-loop - *sign*: with ``sign>=0`` starts the cycloid to the left of the path, ``sign<0`` - to the right. + *sign*: for ``sign>=0`` the cycloid starts to the left of the path, whereas + for ``sign<0`` it starts to the right. - *turnangle*: the angle of perspective on the 3D spring. At ``turnangle=0`` one - sees a sinusoidal curve, at ``turnangle=90`` one essentially sees a circle. + *turnangle*: the angle of perspective on the 3D spring. At ``turnangle=0`` + results in a sinusoidal curve, whereas for ``turnangle=90`` one essentially + obtains a circle. .. class:: smoothed(radius, softness=1, obeycurv=0, relskipthres=0.01) This deformer creates a smoothed variant of the original path. The smoothing is - done on the basis of the corners of the original path, not on a global skope! + done on the basis of the corners of the original path, not on a global scope! Therefore, the result might not be what one would draw by hand. At each corner - (or wherever two path elements meet) a piece of length :math:`2\times` *radius* + (or wherever two path elements meet) a piece of twice the *radius* is taken out of the original path and replaced by a curve. This curve is determined by the tangent directions and the curvatures at its endpoints. Both - are given from the original path, and therefore, the new curve fits into the gap + are taken from the original path, and therefore, the new curve fits into the gap in a *geometrically smooth* way. Path elements that are shorter than *radius* :math:`\times` *relskipthres* are ignored. @@ -98,28 +98,29 @@ The deformer classes are the following: points with infinte curvature. The resulting path stops at such points and leaves the too strongly curved piece out. - * When the original path contains self-intersection, then the resulting parallel - path is not continuous in the parameterisation of the original path. It may - first take a piece that corresponds to "later" parameter values and then - continue with an "earlier" one. Please don't get confused. + * When the original path contains on or more self-intersections, then the + resulting parallel path is not continuous in the parameterisation of the + original path. This may result in the surprising behaviour that a piece + that corresponding to a "later" parameter value is followed by an + "earlier" one. The parameters are the following: *distance* is the minimal (signed) distance between the original and the parallel paths. - *relerr* is the allowed error in the distance is given by ``distance*relerr``. + *relerr* is the allowed relative error in the distance. - *sharpoutercorners* connects the parallel pathitems by wegde build of straight - lines, instead of taking circular arcs. This preserves the angle of the original - corners. + *sharpoutercorners* connects the parallel pathitems by a wegde made of + straight lines, instead of taking circular arcs. This preserves the angle of + the original corners. *dointersection* is a boolean for performing the last step, the intersection step, in the path construction. Setting this to 0 gives the full parallel path, which can be favourable for self-intersecting paths. *checkdistanceparams* is a list of parameter values in the interval (0,1) where - the distance is checked on each parallel pathitem + the distance is checked on each parallel pathitem. *lookforcurvatures* is the number of points per normpathitem where its curvature - is checked for critical values + is checked for critical values. diff --git a/manual/epsfile.rst b/manual/epsfile.rst index a37b4ee3..7becc791 100644 --- a/manual/epsfile.rst +++ b/manual/epsfile.rst @@ -1,3 +1,4 @@ + .. module:: epsfile ***************************************** diff --git a/manual/gradientname.rst b/manual/gradientname.rst index 15c15b3d..7686c7af 100644 --- a/manual/gradientname.rst +++ b/manual/gradientname.rst @@ -1,3 +1,4 @@ + .. _gradientname: ************************* diff --git a/manual/graphics.rst b/manual/graphics.rst index 5fce8b41..b0799cd7 100644 --- a/manual/graphics.rst +++ b/manual/graphics.rst @@ -1,3 +1,4 @@ + .. _graphics: ************** @@ -16,7 +17,9 @@ an arbitrary shape consisting of straight lines, arc segments and cubic Bézier curves. Such a path does not have to be connected but may also comprise several disconnected segments, which will be called *subpaths* in the following. -XXX example for paths and subpaths (figure) +.. todo:: + + example for paths and subpaths (figure) Usually, a path is constructed by passing a list of the path primitives :class:`moveto`, :class:`lineto`, :class:`curveto`, etc., to the constructor of @@ -73,7 +76,7 @@ means that if one wants to draw a rectangle, one should not use :: path.moveto(1, 0), path.lineto(0, 0)) which would construct a rectangle out of four disconnected subpaths (see Fig. -:ref:`fig_rects`\ a). In a better solution (see Fig. :ref:`fig_rects`\ b), the +:ref:`fig_rects` a). In a better solution (see Fig. :ref:`fig_rects` b), the pen is not lifted between the first and the last point: .. _fig_rects: @@ -90,7 +93,7 @@ pen is not lifted between the first and the last point: path.lineto(1, 1), path.lineto(1, 0), path.lineto(0, 0)) -However, as one can see in the lower left corner of Fig. :ref:`fig_rects`\ b, +However, as one can see in the lower left corner of Fig. :ref:`fig_rects` b, the rectangle is still incomplete. It needs to be closed, which can be done explicitly by using for the last straight line of the rectangle (from the point :math:`(0, 1)` back to the origin at :math:`(0, 0)`) the :class:`closepath` @@ -103,15 +106,15 @@ directive:: The :class:`closepath` directive adds a straight line from the current point to the first point of the current subpath and furthermore *closes* the sub path, i.e., it joins the beginning and the end of the line segment. This results in -the intended rectangle shown in Fig. :ref:`fig_rects`\ c. Note that filling the +the intended rectangle shown in Fig. :ref:`fig_rects` c. Note that filling the path implicitly closes every open subpath, as is shown for a single subpath in -Fig. :ref:`fig_rects`\ d), which results from :: +Fig. :ref:`fig_rects` d), which results from :: - c.stroke(rect2, [deco.filled([color.grey(0.95)])]) + c.stroke(rect2, [deco.filled([color.grey(0.5)])]) Here, we supply as second argument of the :meth:`stroke` method a list which in the present case only consists of a single element, namely the so called -decorator :class:`deco.filled`. As it name says, this decorator specifies that +decorator :class:`deco.filled`. As its name says, this decorator specifies that the path is not only being stroked but also filled with the given color. More information about decorators, styles and other attributes which can be passed as elements of the list can be found in Sect. :ref:`graphics_attributes`. More @@ -149,7 +152,7 @@ Fig. :ref:`fig_radii` .. figure:: radii.* :align: center - Example: Intersection of circle with line yielding two radii. + Example: Intersection of circle with line yielding two radii Here, the basic elements, a circle around the point :math:`(0, 0)` with radius :math:`2` and a straight line, are defined. Then, passing the *line*, to the @@ -183,7 +186,7 @@ following code snippet yields this *segment* :: .. figure:: radii2.* :align: center - Example: Intersection of circle with line yielding radii and circle segment. + Example: Intersection of circle with line yielding radii and circle segment Here, we first split the circle using the :meth:`split` method passing the list of parameters obtained above. Since the circle is closed, this yields two arc @@ -209,12 +212,10 @@ parameter value ranges from :math:`0` to :math:`1`, because the predefined circle consists just of one :class:`arc` together with a :class:`closepath` element. However, this is not the case: the actual range is much larger. The reason for this behaviour lies in the internal path handling of PyX: Before -performing any non-trivial geometrical operation with a path, it will +performing any non-trivial geometrical operation on a path, it will automatically be converted into an instance of the :class:`normpath` class (see also Sect. :class:`path.normpath`). These so generated paths are already separated in their subpaths and only contain straight lines and Bézier curve segments. -Thus, as is easily imaginable, they are much simpler to deal with. - XXX explain normpathparams and things like p.begin(), p.end()-1, A more geometrical way of accessing a point on the path is to use the arc length @@ -233,12 +234,11 @@ an arc length. For instance, :: will draw a straight line from a point at angle :math:`180` degrees (in radians :math:`\pi`) to another point at angle :math:`270` degrees (in radians :math:`3\pi/2`) on a circle with radius :math:`r=2`. Note however, that the -mapping arc length :math:`\to` point is in general discontinuous at the begin +mapping from an arc length to a point is in general discontinuous at the beginning and the end of a subpath, and thus PyX does not guarantee any particular result for this boundary case. -More information on the available path methods can be found in Sect. -:class:`path.path`. +More information on the available path methods can be found in Sect. :ref:`postscript_like_paths`. .. _graphics_attributes: @@ -247,10 +247,10 @@ Attributes: Styles and Decorations ================================== Attributes define properties of a given object when it is being used. Typically, -there are different kind of attributes which are usually orthogonal to each +there are different kinds of attributes which are usually orthogonal to each other, while for one type of attribute, several choices are possible. An example is the stroking of a path. There, linewidth and linestyle are different kind of -attributes. The linewidth might be normal, thin, thick, etc, and the linestyle +attributes. The linewidth might be thin, normal, thick, etc., and the linestyle might be solid, dashed etc. Attributes always occur in lists passed as an optional keyword argument to a @@ -264,7 +264,7 @@ Here, we also encounter another feature of PyX's attribute system. For many attributes useful default values are stored as member variables of the actual attribute. For instance, ``style.linewidth.Thick`` is equivalent to ``style.linewidth(0.04, type="w", unit="cm")``, that is :math:`0.04` width cm -(see Sect. :mod:`unit` for more information about PyX's unit system). +(see Sect. :ref:`module_unit` for more information about PyX's unit system). Another important feature of PyX attributes is what is call attributed merging. A trivial example is the following:: @@ -275,7 +275,7 @@ A trivial example is the following:: Here, the ``style.linewidth.thin`` attribute overrides the preceding ``style.linewidth.Thick`` declaration. This is especially important in more -complex cases where PyXdefines default attributes for a certain operation. When +complex cases where PyX defines default attributes for a certain operation. When calling the corresponding methods with an attribute list, this list is appended to the list of defaults. This way, the user can easily override certain defaults, while leaving the other default values intact. In addition, every @@ -288,9 +288,9 @@ delete a default value. For path stroking this looks like :: The clear attribute is also provided by the base classes of the various styles. For instance, :class:`style.strokestyle.clear` clears all strokestyle subclasses -and thus :class:`style.linewidth` and :class:`style.linestyle`. Since all +i.e. :class:`style.linewidth` and :class:`style.linestyle`. Since all attributes derive from :class:`attr.attr`, you can remove all defaults using -``attr.clear``. An overview over the most important attribute typesprovided by +``attr.clear``. An overview over the most important attribute types provided by PyX is given in the following table. +----------------------------+---------------------------------+------------------------------------+ @@ -311,9 +311,9 @@ PyX is given in the following table. | :class:`style.fillstyle` | style used for path filling | :class:`color.color`, | | | | :class:`pattern.pattern` | +----------------------------+---------------------------------+------------------------------------+ -| :class:`style.filltype` | type of path filling | ``style.filltype.nonzero_winding`` | +| :class:`style.filltype` | type of path filling | ``style.fillrule.nonzero_winding`` | | | | (default), | -| | | ``style.filltype.even_odd`` | +| | | ``style.fillrule.even_odd`` | +----------------------------+---------------------------------+------------------------------------+ | :class:`deformer.deformer` | operations changing the shape | :class:`deformer.cycloid`, | | | of the path | :class:`deformer.smoothed` | @@ -325,14 +325,16 @@ PyX is given in the following table. | | | :class:`text.size`, | | | | :class:`text.parbox` | +----------------------------+---------------------------------+------------------------------------+ -| :class:`trafo.trafo` | ransformations applied when | :class:`trafo.mirror`, | +| :class:`trafo.trafo` | transformations applied when | :class:`trafo.mirror`, | | | drawing object | :class:`trafo.rotate`, | | | | :class:`trafo.scale`, | | | | :class:`trafo.slant`, | | | | :class:`trafo.translate` | +----------------------------+---------------------------------+------------------------------------+ -XXX specify which classes in the table are in fact instances +.. todo:: + + specify which classes in the table are in fact instances Note that operations usually allow for certain attribute categories only. For example when stroking a path, text attributes are not allowed, while stroke @@ -362,5 +364,7 @@ acute angle (compared to the default value of :math:`45` degrees):: c.stroke(path, [deco.earrow(angle=30)]) -XXX changeable attributes +.. todo:: + + changeable attributes diff --git a/manual/manual.rst b/manual/manual.rst index 4a9228e6..5fab2d37 100644 --- a/manual/manual.rst +++ b/manual/manual.rst @@ -1,3 +1,4 @@ + ************************ PyX Reference Manual ************************ diff --git a/manual/path.rst b/manual/path.rst index f5727d15..ca4c36f0 100644 --- a/manual/path.rst +++ b/manual/path.rst @@ -1,3 +1,4 @@ + .. module:: path ================== @@ -11,6 +12,8 @@ The :mod:`path` module defines several important classes which are documented in the present section. +.. _postscript_like_paths: + Class :class:`path` --- PostScript-like paths --------------------------------------------- @@ -36,39 +39,34 @@ alphabetic order): .. method:: path.arclen() - Returns the total arc length of the path.\ :math:`^\dagger` + Returns the total arc length of the path. [#normpathconvert]_ .. method:: path.arclentoparam(lengths) - Returns the parameter value(s) corresponding to the arc length(s) *lengths*.\ - :math:`^\dagger` + Returns the parameter value(s) corresponding to the arc length(s) *lengths*. + [#normpathconvert]_ .. method:: path.at(params) Returns the coordinates (as 2-tuple) of the path point(s) corresponding to the - parameter value(s) *params*.\ :math:`^\ddagger` :math:`^\dagger` + parameter value(s) *params*. [#normpathconvert]_ [#value_or_list]_ .. method:: path.atbegin() - Returns the coordinates (as 2-tuple) of the first point of the path.\ - :math:`^\dagger` + Returns the coordinates (as 2-tuple) of the first point of the path. [#normpathconvert]_ .. method:: path.atend() - Returns the coordinates (as 2-tuple) of the end point of the path.\ - :math:`^\dagger` + Returns the coordinates (as 2-tuple) of the end point of the path. [#normpathconvert]_ .. method:: path.bbox() - Returns the bounding box of the path. Note that this returned bounding box may - be too large, if the path contains any :class:`curveto` elements, since for - these the control box, i.e., the bounding box enclosing the control points of - the Bézier curve is returned. + Returns the bounding box of the path. .. method:: path.begin() @@ -77,12 +75,12 @@ alphabetic order): point in the path. -.. method:: path.curveradius(param=None, arclen=None) +.. method:: path.curveradius(params) Returns the curvature radius/radii (or None if infinite) at parameter value(s) - params.\ :math:`^\ddagger` This is the inverse of the curvature at this + *params*. [#value_or_list]_ This is the inverse of the curvature at this parameter. Note that this radius can be negative or positive, depending on the - sign of the curvature.\ :math:`^\dagger` + sign of the curvature. [#normpathconvert]_ .. method:: path.end() @@ -99,30 +97,32 @@ alphabetic order): .. method:: path.intersect(opath) Returns a tuple consisting of two lists of parameter values corresponding to the - intersection points of the path with the other path *opath*, respectively.\ - :math:`^\dagger` For intersection points which are not farther apart then - *epsilon* points, only one is returned. + intersection points of the path with the other path *opath*, respectively. + [#normpathconvert]_ For intersection points which are not farther apart then + *epsilon* (defaulting to :math:`10^{-5}` PostScript points), only one is returned. .. method:: path.joined(opath) Appends *opath* to the end of the path, thereby merging the last subpath (which must not be closed) of the path with the first sub path of *opath* and returns - the resulting new path.\ :math:`^\dagger` + the resulting new path. [#normpathconvert]_ Instead of using the + :meth:`joined` method, you can also join two paths together with help of the + ``<<`` operator, for instance ``p = p1 << p2``. .. method:: path.normpath(epsilon=None) Returns the equivalent :class:`normpath`. For the conversion and for later - calculations with this :class:`normpath` and accuracy of *epsilon* points is - used. If *epsilon* is *None*, the global *epsilon* of the :mod:`path` module is + calculations with this :class:`normpath` an accuracy of *epsilon* is used. + If *epsilon* is *None*, the global *epsilon* of the :mod:`path` module is used. .. method:: path.paramtoarclen(params) - Returns the arc length(s) corresponding to the parameter value(s) *params*.\ - :math:`^\ddagger` :math:`^\dagger` + Returns the arc length(s) corresponding to the parameter value(s) *params*. + [#value_or_list]_ [#normpathconvert]_ .. method:: path.range() @@ -132,59 +132,59 @@ alphabetic order): .. method:: path.reversed() - Returns the reversed path.\ :math:`^\dagger` + Returns the reversed path. [#normpathconvert]_ .. method:: path.rotation(params) - Returns (a) rotations(s) which (each), which rotate the x-direction to the - tangent and the y-direction to the normal at that param.\ :math:`^\dagger` + Returns a transformation or a list of transformations, which rotate the + x-direction to the tangent vector and the y-direction to the normal vector + at the parameter value(s) *params*. [#value_or_list]_ [#normpathconvert]_ .. method:: path.split(params) Splits the path at the parameter values *params*, which have to be sorted in ascending order, and returns a corresponding list of :class:`normpath` - instances.\ :math:`^\dagger` + instances. [#normpathconvert]_ .. method:: path.tangent(params, length=1) - Return (a) :class:`line` instance(s) corresponding to the tangent vector(s) to - the path at the parameter value(s) *params*.\ :math:`^\ddagger` The tangent - vector will be scaled to the length *length*.\ :math:`^\dagger` + Return a :class:`line` instance or a list of :class:`line` instances, + corresponding to the tangent vectors at the parameter value(s) *params*. + [#value_or_list]_ The tangent vector will be scaled to the length *length*. + [#normpathconvert]_ .. method:: path.trafo(params) - Returns (a) trafo(s) which (each) translate to a point on the path corresponding - to the param, rotate the x-direction to the tangent and the y-direction to the - normal in that point.\ :math:`^\dagger` + Returns a transformation or a list of tranformations, which translate the + origin to a point on the path corresponding to parameter value(s) *params* + and rotate the x-direction to the tangent vector and the y-direction to the + normal vector. [#normpathconvert]_ .. method:: path.transformed(trafo) Returns the path transformed according to the linear transformation *trafo*. - Here, ``trafo`` must be an instance of the :class:`trafo.trafo` class.\ - :math:`^\dagger` - -Some notes on the above: + Here, ``trafo`` must be an instance of the :class:`trafo.trafo` class. + [#normpathconvert]_ -* The :math:`\dagger` denotes methods which require a prior conversion of the - path into a :class:`normpath` instance. This is done automatically (using the - precision *epsilon* set globally using :meth:`path.set`). If you need a - different *epsilon* for a normpath, you also can perform the conversion - manually. -* Instead of using the :meth:`joined` method, you can also join two paths - together with help of the ``<<`` operator, for instance ``p = p1 << p2``. +.. [#normpathconvert] + This method requires a prior conversion of the path into a :class:`normpath` + instance. This is done automatically (using the precision *epsilon* set + globally using :meth:`path.set`). If you need a different *epsilon* for a + normpath, you also can perform the conversion manually. -* :math:`^\ddagger` In these methods, *params* may either be a single value or a - list. In the latter case, the result of the method will be a list consisting of - the results for every parameter. The parameter itself may either be a length - (or a number which is then interpreted as a user length) or an instance of the - class :class:`normpathparam`. In the former case, the length refers to the arc - length along the path. +.. [#value_or_list] + In these methods, *params* may either be a single value or a + list. In the latter case, the result of the method will be a list consisting of + the results for each parameter. The parameter itself may either be a length + (or a number which is then interpreted as a user length) or an instance of the + class :class:`normpathparam`. In the former case, the length refers to the arc + length along the path. .. _path_pathitem: @@ -225,7 +225,7 @@ Drawing a straight line can be accomplished using: .. class:: rlineto(dx, dy) - Path element which appends a straight line from the current point to the a point + Path element which appends a straight line from the current point to the point with relative coordinates (*dx*, *dy*), which becomes the new current point. For the construction of arc segments, the following three operations are @@ -237,28 +237,26 @@ available: Path element which appends an arc segment in counterclockwise direction with absolute coordinates (*x*, *y*) of the center and radius *r* from *angle1* to *angle2* (in degrees). If before the operation, the current point is defined, a - straight line is from the current point to the beginning of the arc segment is + straight line from the current point to the beginning of the arc segment is prepended. Otherwise, a subpath, which thus is the first one in the path, is opened. After the operation, the current point is at the end of the arc segment. .. class:: arcn(x, y, r, angle1, angle2) - Path element which appends an arc segment in clockwise direction with absolute - coordinates (*x*, *y*) of the center and radius *r* from *angle1* to *angle2* - (in degrees). If before the operation, the current point is defined, a straight - line is from the current point to the beginning of the arc segment is prepended. - Otherwise, a subpath, which thus is the first one in the path, is opened. After - the operation, the current point is at the end of the arc segment. + Same as :class:`arc` but in clockwise direction. .. class:: arct(x1, y1, x2, y2, r) - Path element which appends an arc segment of radius *r* connecting between - (*x1*, *y1*) and (*x2*, *y2*). --- - -Bézier curves can be constructed using: \ + Path element consisting of a line followed by an arc of radius *r*. The arc + is part of the circle inscribed to the angle at *x1*, *y1* given by lines in + the directions to the current point and to *x2*, *y2*. The initial line + connects the current point to the point where the circle touches the line + through the current point and *x1*, *y1*. The arc then continues to the + point where the circle touches the line through *x1*, *y1* and *x2*, *y2*. +Bézier curves can be constructed using: .. class:: curveto(x1, y1, x2, y2, x3, y3) @@ -292,15 +290,15 @@ perform multiple identical operations: .. class:: multilineto_pt(points_pt) Path element which appends straight line segments starting from the current - point and going through the list of points given in the *points_pt* argument. - All coordinates have to be given in PostScript points. + point and going through the list of points given in the *points_pt* + argument. All coordinates have to be given in PostScript points. .. class:: multicurveto_pt(points_pt) - Path element which appends Bézier curve segments starting from the current point - and going through the list of each three control points given in the *points_pt* - argument. Thus, *points_pt* must be a sequence of 6-tuples. + Path element which appends Bézier curve segments starting from the current + point. *points_pt* is a sequence of 6-tuples containing the coordinates of + the two control points and the end point of a multicurveto segment. .. _path_normpath: @@ -309,37 +307,36 @@ Class :class:`normpath` ----------------------- The :class:`normpath` class is used internally for all non-trivial path -operations, i.e. the ones marked by a :math:`\dagger` in the description of the -:class:`path` above. It represents a path as a list of subpaths, which are +operations, cf. footnote [#normpathconvert]_ in Sect. :ref:`postscript_like_paths`. +It represents a path as a list of subpaths, which are instances of the class :class:`normsubpath`. These :class:`normsubpath`\ s themselves consist of a list of :class:`normsubpathitems` which are either straight lines (:class:`normline`) or Bézier curves (:class:`normcurve`). -A given path can easily be converted to the corresponding :class:`normpath` -using the method with this name:: +A given path ``p`` can easily be converted to the corresponding +:class:`normpath` ``np`` by:: np = p.normpath() -Additionally, you can specify the accuracy (in points) which is used in all -:class:`normpath` calculations by means of the argument *epsilon*, which -defaults to to :math:`10^{-5}` points. This default value can be changed using -the module function :func:`path.set`. +Additionally, the accuracy is used in all :class:`normpath` calculations can be +specified by means of the argument *epsilon*, which defaults to to +:math:`10^{-5}` where units of PostScript points are understood. This default +value can be changed using the module function :func:`path.set`. To construct a :class:`normpath` from a list of :class:`normsubpath` instances, -you pass them to the :class:`normpath` constructor: - +they are passed to the :class:`normpath` constructor: .. class:: normpath(normsubpaths=[]) Construct a :class:`normpath` consisting of *subnormpaths*, which is a list of :class:`subnormpath` instances. -Instances of :class:`normpath` offers all methods of regular :class:`path`\ s, +Instances of :class:`normpath` offer all methods of regular :class:`path` instances, which also have the same semantics. An exception are the methods :meth:`append` and :meth:`extend`. While they allow for adding of instances of :class:`subnormpath` to the :class:`normpath` instance, they also keep the functionality of a regular path and allow for regular path elements to be -appended. The later are converted to the proper normpath representation during +appended. The latter are converted to the proper normpath representation during addition. In addition to the :class:`path` methods, a :class:`normpath` instance also @@ -377,7 +374,8 @@ Class :class:`normsubpath` list of :class:`normsubpathitem` instances. If *closed* is set, the :class:`normsubpath` will be closed, thereby appending a straight line segment from the first to the last point, if it is not already present. All calculations - with the :class:`normsubpath` are performed with an accuracy of *epsilon*. + with the :class:`normsubpath` are performed with an accuracy of *epsilon* + (in units of PostScript points). Most :class:`normsubpath` methods behave like the ones of a :class:`path`. @@ -386,22 +384,23 @@ Exceptions are: .. method:: normsubpath.append(anormsubpathitem) - Append the *anormsubpathitem* to the end of the :class:`normsubpath` instance. + Append the *normsubpathitem* to the end of the :class:`normsubpath` instance. This is only possible if the :class:`normsubpath` is not closed, otherwise an - exception is raised. + :exc:`NormpathException` is raised. .. method:: normsubpath.extend(normsubpathitems) Extend the :class:`normsubpath` instances by *normsubpathitems*, which has to be a list of :class:`normsubpathitem` instances. This is only possible if the - :class:`normsubpath` is not closed, otherwise an exception is raised. + :class:`normsubpath` is not closed, otherwise an :exc:`NormpathException` is + raised. .. method:: normsubpath.close() - Close the :class:`normsubpath` instance, thereby appending a straight line - segment from the first to the last point, if it is not already present. + Close the :class:`normsubpath` instance by appending a straight line + segment from the first to the last point, if not already present. .. _path_predefined: @@ -410,7 +409,7 @@ Predefined paths ---------------- -For convenience, some oft-used paths are already predefined. All of them are +For convenience, some often used paths are already predefined. All of them are subclasses of the :class:`path` class. diff --git a/manual/pattern.rst b/manual/pattern.rst index 67c9451e..3309dfe8 100644 --- a/manual/pattern.rst +++ b/manual/pattern.rst @@ -1,3 +1,4 @@ + .. module:: pattern ********************* diff --git a/manual/radii2.py b/manual/radii2.py index 8fba092f..157de1a1 100644 --- a/manual/radii2.py +++ b/manual/radii2.py @@ -15,7 +15,7 @@ line1, line2, line3 = line.split(isects_line) segment = line2 << arc -c.fill(segment, [color.grey(0.9)]) +c.fill(segment, [color.grey(0.5)]) c.stroke(circle, [style.linewidth.Thick]) c.stroke(line, [style.linewidth.Thick]) diff --git a/manual/text.rst b/manual/text.rst index 71127aba..ef7e903c 100644 --- a/manual/text.rst +++ b/manual/text.rst @@ -599,8 +599,8 @@ The :attr:`defaulttexrunner` instance ``defaulttexrunner.reset`` -Some internals on temporary files etc. -====================================== +Some internals on temporary files +================================= It is not totally obvious how TeX processes are supervised by PyX and why it's done that way. However there are good reasons for it and the following diff --git a/manual/trafo.rst b/manual/trafo.rst dissimilarity index 77% index 432aeee5..e50e314a 100644 --- a/manual/trafo.rst +++ b/manual/trafo.rst @@ -1,104 +1,107 @@ -.. module:: trafo - -******************************************* -Module :mod:`trafo`: Linear transformations -******************************************* - - -With the ``trafo`` module PyX supports linear transformations, which can then -be applied to canvases, Bézier paths and other objects. It consists of the main -class ``trafo`` representing a general linear transformation and subclasses -thereof, which provide special operations like translation, rotation, scaling, -and mirroring. - - -Class trafo -=========== - -The ``trafo`` class represents a general linear transformation, which is defined -for a vector :math:`\vec{x}` as :: - - XXX: translate this math - \vec{x}' = \mathsf{A}\, \vec{x} + \vec{b}\ , - -where :math:`\mathsf{A}` is the transformation matrix and :math:`\vec{b}` the -translation vector. The transformation matrix must not be singular, *i.e.* we -require :math:`\det \mathsf{A} \ne 0`. - -Multiple ``trafo`` instances can be multiplied, corresponding to a consecutive -application of the respective transformation. Note that ``trafo1*trafo2`` means -that ``trafo1`` is applied after ``trafo2``, *i.e.* the new transformation is -given by :math:`\mathsf{A} = \mathsf{A}_1 \mathsf{A}_2` and :math:`\vec{b} = -\mathsf{A}_1 \vec{b}_2 + \vec{b}_1`. Use the ``trafo`` methods described below, -if you prefer thinking the other way round. The inverse of a transformation can -be obtained via the ``trafo`` method ``inverse()``, defined by the inverse -:math:`\mathsf{A}^{-1}` of the transformation matrix and the translation vector -:math:`-\mathsf{A}^{-1}\vec{b}`. - -The methods of the ``trafo`` class are summarized in the following table. - -+-----------------------------------------+----------------------------------------------+ -| ``trafo`` method | function | -+=========================================+==============================================+ -| ``__init__(matrix=((1,0),(0,1)), | create new ``trafo`` instance with | -| vector=(0,0)):`` | transformation ``matrix`` and ``vector``. | -+-----------------------------------------+----------------------------------------------+ -| ``apply(x, y)`` | apply ``trafo`` to point vector | -| | :math:`(\mathtt{x}, \mathtt{y})`. | -+-----------------------------------------+----------------------------------------------+ -| ``inverse()`` | returns inverse transformation of ``trafo``. | -+-----------------------------------------+----------------------------------------------+ -| ``mirrored(angle)`` | returns ``trafo`` followed by mirroring at | -| | line through :math:`(0,0)` with direction | -| | ``angle`` in degrees. | -+-----------------------------------------+----------------------------------------------+ -| ``rotated(angle, x=None, y=None)`` | returns ``trafo`` followed by rotation by | -| | ``angle`` degrees around point | -| | :math:`(\mathtt{x}, \mathtt{y})`, or | -| | :math:`(0,0)`, if not given. | -+-----------------------------------------+----------------------------------------------+ -| ``scaled(sx, sy=None, x=None, y=None)`` | returns ``trafo`` followed by scaling with | -| | scaling factor ``sx`` in :math:`x`\ | -| | -direction, ``sy`` in :math:`y`\ -direction | -| | (:math:`\mathtt{sy}=\mathtt{sx}`, if not | -| | given) with scaling center | -| | :math:`(\mathtt{x}, \mathtt{y})`, or | -| | :math:`(0,0)`, if not given. | -+-----------------------------------------+----------------------------------------------+ -| ``translated(x, y)`` | returns ``trafo`` followed by translation by | -| | vector :math:`(\mathtt{x}, \mathtt{y})`. | -+-----------------------------------------+----------------------------------------------+ -| ``slanted(a, angle=0, x=None, y=None)`` | returns ``trafo`` followed by XXX | -+-----------------------------------------+----------------------------------------------+ - - -Subclasses of trafo -=================== - -The ``trafo`` module provides a number of subclasses of the ``trafo`` class, -each of which corresponds to one ``trafo`` method. They are listed in the -following table: - -+----------------------------------------+----------------------------------------------+ -| ``trafo`` subclass | function | -+========================================+==============================================+ -| ``mirror(angle)`` | mirroring at line through :math:`(0,0)` with | -| | direction ``angle`` in degrees. | -+----------------------------------------+----------------------------------------------+ -| ``rotate(angle, x=None, y=None)`` | rotation by ``angle`` degrees around point | -| | :math:`(\mathtt{x}, \mathtt{y})`, or | -| | :math:`(0,0)`, if not given. | -+----------------------------------------+----------------------------------------------+ -| ``scale(sx, sy=None, x=None, y=None)`` | scaling with scaling factor ``sx`` in | -| | :math:`x`\ -direction, ``sy`` in :math:`y`\ | -| | -direction (:math:`\mathtt{sy}=\mathtt{sx}`, | -| | if not given) with scaling center | -| | :math:`(\mathtt{x}, \mathtt{y})`, or | -| | :math:`(0,0)`, if not given. | -+----------------------------------------+----------------------------------------------+ -| ``translate(x, y)`` | translation by vector :math:`(\mathtt{x}, | -| | \mathtt{y})`. | -+----------------------------------------+----------------------------------------------+ -| ``slant(a, angle=0, x=None, y=None)`` | XXX | -+----------------------------------------+----------------------------------------------+ - + +.. module:: trafo + +******************************************* +Module :mod:`trafo`: Linear transformations +******************************************* + + +With the ``trafo`` module PyX supports linear transformations, which can then +be applied to canvases, Bézier paths and other objects. It consists of the main +class ``trafo`` representing a general linear transformation and subclasses +thereof, which provide special operations like translation, rotation, scaling, +and mirroring. + + +Class :class:`trafo` +=================== + +The ``trafo`` class represents a general linear transformation, which is defined +for a vector :math:`\vec{x}` as + +.. math:: + + \vec{x}' = \mathsf{A}\, \vec{x} + \vec{b}\ , + +where :math:`\mathsf{A}` is the transformation matrix and :math:`\vec{b}` the +translation vector. The transformation matrix must not be singular, *i.e.* we +require :math:`\det \mathsf{A} \ne 0`. + +Multiple ``trafo`` instances can be multiplied, corresponding to a consecutive +application of the respective transformation. Note that ``trafo1*trafo2`` means +that ``trafo1`` is applied after ``trafo2``, *i.e.* the new transformation is +given by :math:`\mathsf{A} = \mathsf{A}_1 \mathsf{A}_2` and :math:`\vec{b} = +\mathsf{A}_1 \vec{b}_2 + \vec{b}_1`. Use the ``trafo`` methods described below, +if you prefer thinking the other way round. The inverse of a transformation can +be obtained via the ``trafo`` method ``inverse()``, defined by the inverse +:math:`\mathsf{A}^{-1}` of the transformation matrix and the translation vector +:math:`-\mathsf{A}^{-1}\vec{b}`. + +.. class:: trafo(matrix=((1,0),(0,1)), vector=(0,0)) + + create new ``trafo`` instance with transformation ``matrix`` and ``vector`` + +.. method:: apply(x, y) + + apply ``trafo`` to point vector :math:`(\mathtt{x}, \mathtt{y})`. + +.. method:: inverse() + + returns inverse transformation of ``trafo``. + +.. method:: mirrored(angle) + + returns ``trafo`` followed by mirroring at line through :math:`(0,0)` with + direction ``angle`` in degrees. + +.. method:: rotated(angle, x=None, y=None) + + returns ``trafo`` followed by rotation by ``angle`` degrees around point + :math:`(\mathtt{x}, \mathtt{y})`, or :math:`(0,0)`, if not given. + +.. method:: scaled(sx, sy=None, x=None, y=None) + + returns ``trafo`` followed by scaling with scaling factor ``sx`` in + :math:`x`\ -direction, ``sy`` in :math:`y`\ -direction + (:math:`\mathtt{sy}=\mathtt{sx}`, if not given) with scaling center + :math:`(\mathtt{x}, \mathtt{y})`, or :math:`(0,0)`, if not given. + +.. method:: slanted(a, angle=0, x=None, y=None) + + returns ``trafo`` followed by slant by ``angle`` around point + :math:`(\mathtt{x}, \mathtt{y})`, or :math:`(0,0)`, if not given. + +.. method:: translated(x, y) + + returns ``trafo`` followed by translation by vector :math:`(\mathtt{x}, \mathtt{y})`. + + +Subclasses of :class:`trafo` +============================ + +The ``trafo`` module provides a number of subclasses of the ``trafo`` class, +each of which corresponds to one ``trafo`` method. + +.. class:: mirror(angle) + + mirroring at line through :math:`(0,0)` with direction ``angle`` in degrees. + +.. class:: rotate(angle, x=None, y=None) + + rotation by ``angle`` degrees around point :math:`(\mathtt{x}, \mathtt{y})`, or :math:`(0,0)`, if not given. + +.. class:: scale(sx, sy=None, x=None, y=None) + + scaling with scaling factor ``sx`` in :math:`x`\ -direction, ``sy`` in + :math:`y`\ -direction (:math:`\mathtt{sy}=\mathtt{sx}`, if not given) with + scaling center :math:`(\mathtt{x}, \mathtt{y})`, or :math:`(0,0)`, if not + given. + +.. class:: slant(a, angle=0, x=None, y=None) + + slant by ``angle`` around point :math:`(\mathtt{x}, \mathtt{y})`, or :math:`(0,0)`, if not given. + +.. class:: translate(x, y) + + translation by vector :math:`(\mathtt{x}, \mathtt{y})`. + diff --git a/manual/unit.rst b/manual/unit.rst index 029b85c6..880ed805 100644 --- a/manual/unit.rst +++ b/manual/unit.rst @@ -1,6 +1,8 @@ .. module:: unit +.. _module_unit: + ****************** Module :mod:`unit` ****************** @@ -57,8 +59,8 @@ admittedly rather unfortunate case, just use :: at the beginning of your program. -Class length -============ +Class :class:`length` +===================== .. class:: length(f, type="u", unit=None) -- 2.11.4.GIT