From bdbdf16c8b1d4ed91e261ede3cdbaae90b6391d9 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Andr=C3=A9=20Wobst?= Date: Wed, 17 Oct 2012 14:51:09 +0000 Subject: [PATCH] add some documentation git-svn-id: http://svn.code.sf.net/p/pyx/code/trunk/pyx@3321 a4f5e268-e194-4f32-bce1-d30804cbbcc5 --- manual/canvas.rst | 51 +++++++++++++++++++++++++++++++++++++------------- manual/graph.rst | 54 ++++++++++++++++++++++++++++++++--------------------- manual/graphics.rst | 3 ++- manual/trafo.rst | 2 +- 4 files changed, 74 insertions(+), 36 deletions(-) diff --git a/manual/canvas.rst b/manual/canvas.rst index 4e79e19c..e738a9e4 100644 --- a/manual/canvas.rst +++ b/manual/canvas.rst @@ -67,13 +67,28 @@ Text output on the canvas is possible using Inserts *text* at position (*x*, *y*) into the canvas applying *attrs*. This is a shortcut for ``insert(texrunner.text(x, y, text, attrs))``. +To group drawing operations, layers can be used: + + +.. method:: canvas.layer( name, above=None, below=None) + + This method creates or gets a layer with name *name*. + + A layer is a canvas itself and can be used to combine drawing operations for + ordering purposes, i.e., what is above and below each other. The layer name + *name* is a dotted string, where dots are used to form a hierarchy of layer + groups. When inserting a layer, it is put on top of its layer group except + when another layer of this group is specified by means of the parameters + *above* or *below*. + + The :class:`canvas` class provides access to the total geometrical size of its element: .. method:: canvas.bbox() - Returns the bounding box enclosing all elements of the canvas (see Sect. :ref:`bbox_module`). + Returns the bounding box enclosing all elements of the canvas (see Sect. :mod:`bbox`). A canvas also allows to set its TeX runner: @@ -113,20 +128,17 @@ convenience methods, which wrap the canvas into a single page document. *kwargs*. -.. method:: canvas.pipeGS(filename="-", device=None, resolution=100, gscommand="gs", gsoptions="", textalphabits=4, graphicsalphabits=4, ciecolor=False, input="eps", **kwargs) +.. method:: canvas.pipeGS(device, seekable=False, 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 - 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. When no *filename* is specified, the output - is written to stdout. *device* specifies a ghostscript output device by a - 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 - *filename* is specified but the device is not set, ``"png16m"`` is used when the - filename ends in ``.png`` and ``"jpeg"`` is used when the filename ends in - ``.jpg``. + to generate other output formats. The output is returned by means of a + python file object. As this file object is generated from a pipe, it is + not seekable by default. To make it seekable, enable the *seekable* flag. + *device* specifies a ghostscript output device by a 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. *resolution* specifies the resolution in dpi (dots per inch). *gscmd* is the command to be used to invoke ghostscript. *gsoptions* is an option string @@ -143,6 +155,19 @@ convenience methods, which wrap the canvas into a single page document. parameter), which is used to generate the input for ghostscript. By that you gain access to the :class:`document.page` constructor arguments. +.. method:: canvas.writeGSfile(filename=None, device=None, **kwargs) + + This method is similar to pipeGS, but the content is written into the file + *filename*. If filename is None it is auto-guessed from the script name. If + filename is "-", the output is written to stdout. In both cases, a device + needs to be specified to define the format (and the file suffix in case the + filename is created from the script name). + + If device is None, but a filename with suffix is given, PNG files will + be written using the png16m device and JPG files using the jpeg device. + + All other arguments are identical to those of the :meth:`canvas.pipeGS`. + For more information about the possible arguments of the :class:`document.page` constructor, we refer to Sect. :mod:`document`. diff --git a/manual/graph.rst b/manual/graph.rst index d48bbd75..7f9bbe60 100644 --- a/manual/graph.rst +++ b/manual/graph.rst @@ -208,11 +208,11 @@ create the whole plot. Once this is done, further calls of :meth:`plot` will fail. Usually you do not need to take care about the finalization of the graph, because it happens automatically once you write the plot into a file. However, sometimes position methods (described below) are nice to be accessible. For -that, at least the layout of the graph must have been finished. By calling the -:meth:`do`\ -methods yourself you can also alter the order in which the graph -components are plotted. Multiple calls to any of the :meth:`do`\ -methods have -no effect (only the first call counts). The orginal order in which the -:meth:`do`\ -methods are called is: +that, at least the layout of the graph must have been finished. However, the +drawing order is based on canvas layers and thus the order in which the +:meth:`do`\ -methods are called will not alter the output. Multiple calls to +any of the :meth:`do`\ -methods have no effect (only the first call counts). +The orginal order in which the :meth:`do`\ -methods are called is: .. method:: graphxy.dolayout() @@ -929,12 +929,17 @@ The class :class:`line` provides a changeable line style. Its definition is: be added to the line. -.. class:: rect(gradient=color.gradient.Grey) +.. class:: rect(colorname="color", gradient=color.gradient.Grey, coloraxis=None, keygraph=_autokeygraph) This class is a style to plot colored rectangles into a two-dimensional graph. The size of the rectangles is taken from the data provided by the :class:`range` - style. The additional data column named ``color`` specifies the color of the - rectangle defined by *gradient*. The valid color range is [0:1]. + style. The additional data column named *colorname* specifies the color of the + rectangle defined by *gradient*. The translation of the data values to the + gradient is done by the *coloraxis*, which is set to be a linear axis if not + provided by *coloraxis*. A key graph, a graphx instance, is generated + automatically to indicate the color scale if not provided by *keygraph*. + If a *keygraph* is given, its ``x`` axis defines the color conversion and + *coloraxis* is ignored. .. class:: histogram(lineattrs=[], steps=0, fromvalue=0, frompathattrs=[], fillable=0, rectkey=0, autohistogramaxisindex=0, autohistogrampointpos=0.5, epsilon=1e-10) @@ -1034,21 +1039,11 @@ The class :class:`line` provides a changeable line style. Its definition is: ``changelinestyle`` of the :class:`line` class. -.. class:: surface(colorname="color", gradient=color.gradient.Grey, mincolor=None, maxcolor=None, gridlines1=0.05, gridlines2=0.05, gridcolor=None, backcolor=color.gray.black) +.. class:: surface(gridlines1=0.05, gridlines2=0.05, gridcolor=None, backcolor=color.gray.black, **kwargs) Draws a surface of a rectangular grid. Each rectangle is divided into 4 triangles. - The grid can be colored using values provided by the data column named - *colorname*. The values are rescaled to the range [0:1] using mincolor and - maxcolor (which are taken from the minimal and maximal values, but larger bounds - could be set). - - If no *colorname* column exists, the surface style falls back to a lighting - coloring taking into account the angle between the view ray and the triangle and - the distance between viewer and triangle. The precise conversion is defined in - the :meth:`lighting` method. - If a *gridcolor* is set, the rectangular grid is marked by small stripes of the relative (compared to each rectangle) size of *gridlines1* and *gridlines2* for the first and second grid direction, respectively. @@ -1062,8 +1057,9 @@ The class :class:`line` provides a changeable line style. Its definition is: * All colors must use the same color space. * HSB colors are not allowed, whereas Gray, RGB, and CMYK are allowed. You can - convert HSB colors into a different color space before passing them to the - surface. + convert HSB colors into a different color space by means of + :class:`rgbgradient` and class:`cmykgradient` before passing it to the + surface style. * The grid itself is also constructed out of triangles. The grid is transformed along with the triangles thus looking quite different from a stroked grid (as @@ -1073,6 +1069,22 @@ The class :class:`line` provides a changeable line style. Its definition is: * Color changes are continuous (in the selected color space) for each triangle. + Further arguments are identical to the :class:`graph.style.rect` style. However, + if no *colorname* column exists, the surface style falls back to a lighting + coloring taking into account the angle between the view ray and the triangle and + the distance between viewer and triangle. The precise conversion is defined in + the :meth:`lighting` method. + + +.. class:: density(epsilon=1e-10, **kwargs): + + Density plots can be created by the density style. It is similar to a surface + plot in 2d, but it does not use a mesh, but a bitmap representation instead. + Due to that difference, the file size is smaller and not color interpolation + takes place. Furthermore the style can be used with equidistantly spaced data + only (after conversion by the axis, so logarithmic raw data and such are + possible using proper axes). Further arguments are identical to the + :class:`graph.style.rect` style. .. module:: graph.key diff --git a/manual/graphics.rst b/manual/graphics.rst index b0799cd7..8f7d5c10 100644 --- a/manual/graphics.rst +++ b/manual/graphics.rst @@ -298,7 +298,8 @@ PyX is given in the following table. +============================+=================================+====================================+ | :class:`deco.deco` | decorator specifying the way | :class:`deco.stroked`, | | | the path is drawn | :class:`deco.filled`, | -| | | :class:`deco.arrow` | +| | | :class:`deco.arrow`, | +| | | :class:`deco.text` | +----------------------------+---------------------------------+------------------------------------+ | :class:`style.strokestyle` | style used for path stroking | :class:`style.linecap`, | | | | :class:`style.linejoin`, | diff --git a/manual/trafo.rst b/manual/trafo.rst index e50e314a..8e60fb5e 100644 --- a/manual/trafo.rst +++ b/manual/trafo.rst @@ -14,7 +14,7 @@ and mirroring. Class :class:`trafo` -=================== +==================== The ``trafo`` class represents a general linear transformation, which is defined for a vector :math:`\vec{x}` as -- 2.11.4.GIT