Work at SourceForge, help us to make it a better place! We have an immediate need for a Support Technician in our San Francisco or Denver office.

[PyX-checkins] SF.net SVN: pyx:[3146] trunk/pyx/manual

 [PyX-checkins] SF.net SVN: pyx:[3146] trunk/pyx/manual From: - 2011-05-20 08:36:41 Revision: 3146 http://pyx.svn.sourceforge.net/pyx/?rev=3146&view=rev Author: wobsta Date: 2011-05-20 08:36:34 +0000 (Fri, 20 May 2011) Log Message: ----------- new build infrastructure Modified Paths: -------------- trunk/pyx/manual/Makefile Added Paths: ----------- trunk/pyx/manual/_static/ trunk/pyx/manual/_templates/ trunk/pyx/manual/conf.py Modified: trunk/pyx/manual/Makefile =================================================================== --- trunk/pyx/manual/Makefile 2011-05-20 08:32:20 UTC (rev 3145) +++ trunk/pyx/manual/Makefile 2011-05-20 08:36:34 UTC (rev 3146) @@ -1,54 +1,39 @@ -# You need mkhowto from the python distribution for creating this manual. -# Get a copy of a current python source archive and make a symbolic link -# from /Python-x.x.x/Doc/tools/mkhowto into this directory. -# Furthermore you need tex, latex2html and a few other things to build -# the manual (see the python documentation about creating documentations -# for details). +# Makefile for Sphinx documentation +# PYTHON ?= python -default: dvi +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build -clean: - -rm -fr manual.dvi *.eps *.pdf *.aux *.out *.toc *.log manual +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees$(PAPEROPT_$(PAPER))$(SPHINXOPTS) . -all: - make clean - make html - make pdf - make dvi +.PHONY: help clean all html latexpdf figs -src=$(wildcard *.tex) pyxversion.tex pyxdate.tex +all: html latexpdf + @echo "Done." -dvi: manual.dvi -pdf: manual.pdf -html: manual/manual.html +clean: + -rm -rf$(BUILDDIR)/* *.eps *.pdf *.png -manual.pdf: $(src) pdf_figs - #for index-with-own-hyperrefs debugging, anybody interested? - #./mkhowto --a4 --pdf --keep manual.tex - ./mkhowto --a4 --pdf manual.tex +html: figs +$(SPHINXBUILD) -b html $(ALLSPHINXOPTS)$(BUILDDIR)/html + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." -manual.dvi:$(src) eps_figs - ./mkhowto --a4 --dvi manual.tex +latexpdf: figs + $(SPHINXBUILD) -b latex$(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + make -C$(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." -manual/manual.html:$(src) eps_figs - ./mkhowto --image-type png --favicon "/pyx.ico" \ - --up-link "/" --up-title "PyX homepage" \ - --html manual.tex +figs: $(patsubst %.py, %.png,$(filter-out conf.py,$(wildcard *.py))) -pyxversion.tex: ../pyx/version.py -$(PYTHON) -c "import sys;sys.path[:0]=[\"..\"];import pyx.version;print pyx.version.version+'%'" > pyxversion.tex - -pyxdate.tex: ../pyx/version.py - $(PYTHON) -c "import sys;sys.path[:0]=[\"..\"];import pyx.version;print pyx.version.date+'%'" > pyxdate.tex - -eps_figs:$(patsubst %.py, %.eps, $(wildcard *.py)) - -pdf_figs:$(patsubst %.py, %.pdf, $(wildcard *.py)) - -%.eps: %.py +%.png: %.py export PYTHONPATH=$(CURDIR)/.. ; $(PYTHON)$^ - -%.pdf: %.py - export PYTHONPATH=$(CURDIR)/.. ;$(PYTHON) $^ +$(PYTHON) ../contrib/epstopng.py -o $@$*.eps Added: trunk/pyx/manual/conf.py =================================================================== --- trunk/pyx/manual/conf.py (rev 0) +++ trunk/pyx/manual/conf.py 2011-05-20 08:36:34 UTC (rev 3146) @@ -0,0 +1,222 @@ +# -*- coding: utf-8 -*- +# +# PyX documentation build configuration file, created by +# sphinx-quickstart on Thu May 19 17:32:57 2011. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os +sys.path.insert(0, '..') +import pyx.version + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['mathjax'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'manual' + +# General information about the project. +project = u'PyX' +copyright = u'2011, Jörg Lehmann, Michael Schindler, André Wobst' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '.'.join(pyx.version.version.split('.')[:1]) +# The full version, including alpha/beta/rc tags. +release = pyx.version.version + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +today = pyx.version.date +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: text) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'PyXdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('manual', 'PyX.tex', u'PyX Documentation', + u'Jörg Lehmann, Michael Schindler, André Wobst', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('manual', 'pyx', u'PyX Documentation', + [u'Jörg Lehmann, Michael Schindler, André Wobst'], 1) +] + +# -- Other options ------------------------------------------------------------ + +mathjax_path = 'http://mathjax.connectmv.com/MathJax.js'; Property changes on: trunk/pyx/manual/conf.py ___________________________________________________________________ Added: svn:keywords + LastChangedRevision LastChangedBy HeadURL This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. 

 [PyX-checkins] SF.net SVN: pyx:[3139] trunk/pyx/manual From: - 2011-05-20 07:58:37 Revision: 3139 http://pyx.svn.sourceforge.net/pyx/?rev=3139&view=rev Author: wobsta Date: 2011-05-20 07:58:29 +0000 (Fri, 20 May 2011) Log Message: ----------- prepare manual for rest conversion Modified Paths: -------------- trunk/pyx/manual/arrows.tex trunk/pyx/manual/axis.tex trunk/pyx/manual/bbox.tex trunk/pyx/manual/bitmap.tex trunk/pyx/manual/box.tex trunk/pyx/manual/colorname.tex trunk/pyx/manual/connector.tex trunk/pyx/manual/deformer.tex trunk/pyx/manual/document.tex trunk/pyx/manual/epsfile.tex trunk/pyx/manual/gradientname.tex trunk/pyx/manual/graph.tex trunk/pyx/manual/graphics.tex trunk/pyx/manual/manual.tex trunk/pyx/manual/pathstyles.tex trunk/pyx/manual/pattern.tex trunk/pyx/manual/text.tex trunk/pyx/manual/trafo.tex trunk/pyx/manual/unit.tex Modified: trunk/pyx/manual/arrows.tex =================================================================== --- trunk/pyx/manual/arrows.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/arrows.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -1,3 +1,3 @@ \chapter{Arrows in deco module} \label{arrows} -\centerline{\includegraphics{arrows}} +\includegraphics{arrows} Modified: trunk/pyx/manual/axis.tex =================================================================== --- trunk/pyx/manual/axis.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/axis.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -225,7 +225,11 @@ for the average \PyX{} user, we'll not go into all the details of their parameters and except for some handy axis position methods: -\begin{methoddesc}[anchoredaxis]{basepath}{x1=None, x2=None} +\begin{classdesc}{anchoredaxis}{} + DUMMY +\end{classdesc} + +\begin{methoddesc}{basepath}{x1=None, x2=None} Returns a path instance for the base path. \var{x1} and \var{x2} define the axis range, the base path should cover. For \code{None} the beginning and end of the path is taken, which might cover a @@ -235,37 +239,37 @@ the subaxis is the first or last of the subaxes. \end{methoddesc} -\begin{methoddesc}[anchoredaxis]{vbasepath}{v1=None, v2=None} +\begin{methoddesc}{vbasepath}{v1=None, v2=None} Like \method{basepath} but in graph coordinates. \end{methoddesc} -\begin{methoddesc}[anchoredaxis]{gridpath}{x} +\begin{methoddesc}{gridpath}{x} Returns a path instance for the grid path at position \var{x}. Might return \code{None} when no grid path is available. \end{methoddesc} -\begin{methoddesc}[anchoredaxis]{vgridpath}{v} +\begin{methoddesc}{vgridpath}{v} Like \method{gridpath} but in graph coordinates. \end{methoddesc} -\begin{methoddesc}[anchoredaxis]{tickpoint}{x} +\begin{methoddesc}{tickpoint}{x} Returns the position of \var{x} as a tuple \samp{(x, y)}. \end{methoddesc} -\begin{methoddesc}[anchoredaxis]{vtickpoint}{v} +\begin{methoddesc}{vtickpoint}{v} Like \method{tickpoint} but in graph coordinates. \end{methoddesc} -\begin{methoddesc}[anchoredaxis]{tickdirection}{x} +\begin{methoddesc}{tickdirection}{x} Returns the direction of a tick at \var{x} as a tuple \samp{(dx, dy)}. The tick direction points inside of the graph. \end{methoddesc} -\begin{methoddesc}[anchoredaxis]{vtickdirection}{v} +\begin{methoddesc}{vtickdirection}{v} Like \method{tickdirection} but in graph coordinates. \end{methoddesc} -\begin{methoddesc}[anchoredaxis]{vtickdirection}{v} +\begin{methoddesc}{vtickdirection}{v} Like \method{tickdirection} but in graph coordinates. \end{methoddesc} @@ -949,6 +953,10 @@ The position of an axis is defined by an instance of a class providing the following methods: +\begin{classdesc}{positioner}{} + DUMMY +\end{classdesc} + \begin{methoddesc}{vbasepath}{v1=None, v2=None} Returns a path instance for the base path. \var{v1} and \var{v2} define the axis range in graph coordinates the base path should Modified: trunk/pyx/manual/bbox.tex =================================================================== --- trunk/pyx/manual/bbox.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/bbox.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -12,58 +12,28 @@ The \texttt{bbox} constructor accepts the following keyword arguments -\medskip -\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X} -keyword & description\\ -\hline -\texttt{llx}&\texttt{None} (default) for $-\infty$ or $x$-position of -the lower left corner of the bbox (in user units)\\ -\texttt{lly}&\texttt{None} (default) for $-\infty$ or $y$-position of -the lower left corner of the bbox (in user units)\\ -\texttt{urx}&\texttt{None} (default) for $\infty$ or $x$-position of -the upper right corner of the bbox (in user units)\\ -\texttt{ury}&\texttt{None} (default) for $\infty$ or $y$-position of -the upper right corner of the bbox (in user units) -\end{tabularx} +\begin{tableii}{l|l}{textrm}{keyword}{description} +\lineii{\texttt{llx}}{\texttt{None} (default) for $-\infty$ or $x$-position of the lower left corner of the bbox (in user units)} +\lineii{\texttt{lly}}{\texttt{None} (default) for $-\infty$ or $y$-position of the lower left corner of the bbox (in user units)} +\lineii{\texttt{urx}}{\texttt{None} (default) for $\infty$ or $x$-position of the upper right corner of the bbox (in user units)} +\lineii{\texttt{ury}}{\texttt{None} (default) for $\infty$ or $y$-position of the upper right corner of the bbox (in user units)} +\end{tableii} \section{bbox methods} -%Instances of the \texttt{bbox} class offer the following methods: -%\medskip +\begin{tableii}{l|l}{textrm}{\texttt{bbox} method}{function} +\lineii{\texttt{intersects(other)}}{returns \texttt{1} if the \texttt{bbox} instance and \texttt{other} intersect with each other.} +\lineii{\texttt{transformed(self, trafo)}}{returns \texttt{self} transformed by transformation \texttt{trafo}.} +\lineii{\texttt{enlarged(all=0, bottom=None, left=None, top=None, right=None)}}{return the bounding box enlarged by the given amount (in visual units). \texttt{all} is the default for all other directions, which is used whenever \texttt{None} is given for the corresponding direction.} +\lineii{\texttt{path()} or \texttt{rect()}}{return the \texttt{path} corresponding to the bounding box rectangle.} +\lineii{\texttt{height()}}{returns the height of the bounding box (in \PyX{} lengths).} +\lineii{\texttt{width()}}{returns the width of the bounding box (in \PyX{} lengths).} +\lineii{\texttt{top()}}{returns the $y$-position of the top of the bounding box (in \PyX{} lengths).} +\lineii{\texttt{bottom()}}{returns the $y$-position of the bottom of the bounding box (in \PyX{} lengths).} +\lineii{\texttt{left()}}{returns the $x$-position of the left side of the bounding box (in \PyX{} lengths).} +\lineii{\texttt{right()}}{returns the $x$-position of the right side of the bounding box (in \PyX{} lengths).} +\end{tableii} -\begin{tabularx} - {\linewidth} - {>{\hsize=.85\hsize}X>{\raggedright\arraybackslash\hsize=1.15\hsize}X} - \texttt{bbox} method & function \\ - \hline - \texttt{intersects(other)} & returns \texttt{1} if the \texttt{bbox} instance - and \texttt{other} intersect with each other.\\ - \texttt{transformed(self, trafo)}& returns \texttt{self} transformed - by transformation \texttt{trafo}.\\ - \texttt{enlarged(all=0, bottom=None, - \newline\phantom{enlarged(}left=None, top=None, - \newline\phantom{enlarged(}right=None)} & - return the bounding box enlarged by the given amount (in visual - units). \texttt{all} is the default for all other directions, which - is used whenever \texttt{None} is given for the corresponding - direction.\\ - \texttt{path()} or \texttt{rect()} & return the \texttt{path} corresponding to the - bounding box rectangle.\\ - \texttt{height()} & returns the height of the bounding box (in \PyX{} - lengths).\\ - \texttt{width()} & returns the width of the bounding box (in \PyX{} - lengths).\\ - \texttt{top()} & returns the $y$-position of the top of the bounding - box (in \PyX{} lengths).\\ - \texttt{bottom()} & returns the $y$-position of the bottom of the - bounding box (in \PyX{} lengths).\\ - \texttt{left()} & returns the $x$-position of the left side of the - bounding box (in \PyX{} lengths).\\ - \texttt{right()} & returns the $x$-position of the right side of the - bounding box (in \PyX{} lengths).\\ - \end{tabularx} -\medskip - Furthermore, two bounding boxes can be added (giving the bounding box enclosing both) and multiplied (giving the intersection of both bounding boxes). Modified: trunk/pyx/manual/bitmap.tex =================================================================== --- trunk/pyx/manual/bitmap.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/bitmap.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -42,11 +42,8 @@ c.writeEPSfile("bitmap") \end{verbatim} Figure~\ref{fig:bitmap} shows the resulting output. -\begin{figure}[ht] -\centerline{\includegraphics{bitmap}} -\caption{An introductory bitmap example.} -\label{fig:bitmap} -\end{figure} +\includegraphics{bitmap} +\centerline{An introductory bitmap example.} \section{Bitmap module} \declaremodule{}{bitmap} Modified: trunk/pyx/manual/box.tex =================================================================== --- trunk/pyx/manual/box.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/box.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -26,7 +26,6 @@ some methods of this \verb|polygon| class are explained: \begin{description} -\raggedright \item[\texttt{path(centerradius=None, bezierradius=None, beziersoftness=1)}:] returns a path of the box; the center might be marked by a small circle of radius \verb|centerradius|; the corners @@ -40,12 +39,9 @@ \item[\texttt{reltransform(*trafos)}:] performs a list of transformations to the box relative to the box center -\begin{figure} -\centerline{\includegraphics{boxalign}} -\caption{circle and line alignment examples (equal direction and +\includegraphics{boxalign} +\centerline{circle and line alignment examples (equal direction and distance)} -\label{fig:boxalign} -\end{figure} \item[\texttt{circlealignvector(a, dx, dy)}:] returns a vector (a tuple (x, y)) to align the box at a circle with radius \verb|a| in @@ -70,7 +66,6 @@ \section{Functions working on a box list} \begin{description} -\raggedright \item[\texttt{circlealignequal(boxes, a, dx, dy)}:] Performs a circle alignment of the boxes \verb|boxes| using the parameters \verb|a|, \verb|dx|, and \verb|dy| as in the \verb|circlealign| method. For the Modified: trunk/pyx/manual/colorname.tex =================================================================== --- trunk/pyx/manual/colorname.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/colorname.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -1,3 +1,3 @@ \chapter{Named colors} \label{colorname} -\centerline{\includegraphics{colorname}} +\includegraphics{colorname} Modified: trunk/pyx/manual/connector.tex =================================================================== --- trunk/pyx/manual/connector.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/connector.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -53,14 +53,9 @@ values produce output similar to the defaults of \class{arc}.)\medskip -\begin{figure}[hbt] -\centerline{ \includegraphics{connector} -} -\caption{The angle-parameters of the connector.arc (left panel) and the +\centerline{The angle-parameters of the connector.arc (left panel) and the connector.curve (right panel) classes.} -\label{fig:connector} -\end{figure} \section{Class \class{twolines}} Modified: trunk/pyx/manual/deformer.tex =================================================================== --- trunk/pyx/manual/deformer.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/deformer.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -12,6 +12,10 @@ All classes of the \module{deformer} module provide the following methods: +\begin{classdesc}{deformer}{} + DUMMY +\end{classdesc} + \begin{methoddesc}{__call__}{(specific parameters for the class)} Returns a deformer with modified parameters \end{methoddesc} Modified: trunk/pyx/manual/document.tex =================================================================== --- trunk/pyx/manual/document.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/document.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -88,25 +88,17 @@ Predefined paperformats are listed in the following table \medskip -\begin{center} -\begin{tabular}{l|l|l|l} -instance & name & width & height \\ -\hline -\constant{document.paperformat.A0} & A0 & \unit[840]{mm} & -\unit[1188]{mm}\\ -\constant{document.paperformat.A0b} & &\unit[910]{mm} & -\unit[1370]{mm}\\ -\constant{document.paperformat.A1} & A1& \unit[594]{mm} & -\unit[840]{mm}\\ -\constant{document.paperformat.A2} & A2& \unit[420]{mm} & -\unit[594]{mm}\\ -\constant{document.paperformat.A3} & A3 & \unit[297]{mm} & \unit[420]{mm}\\ -\constant{document.paperformat.A4} & A4& \unit[210]{mm} & \unit[297]{mm}\\ -\constant{document.paperformat.Letter} & Letter & \unit[8.5]{inch} & -\unit[11]{inch}\\ -\constant{document.paperformat.Legal} & Legal & \unit[8.5]{inch} & \unit[14]{inch} -\end{tabular} -\end{center} +\begin{tableiv}{l|l|l|l}{textrm}{instance}{name}{width}{height} +\lineiv{\constant{document.paperformat.A0}}{A0}{840 mm}{1188 mm} +\lineiv{\constant{document.paperformat.A0b}}{}{910 mm}{1370 mm} +\lineiv{\constant{document.paperformat.A1}}{A1}{594 mm}{840 mm} +\lineiv{\constant{document.paperformat.A2}}{A2}{420 mm}{594 mm} +\lineiv{\constant{document.paperformat.A3}}{A3}{297 mm}{420 mm} +\lineiv{\constant{document.paperformat.A4}}{A4}{210 mm}{297 mm} +\lineiv{\constant{document.paperformat.A5}}{A5}{148.5 mm}{210 mm} +\lineiv{\constant{document.paperformat.Letter}}{Letter}{8.5 inch}{11 inch} +\lineiv{\constant{document.paperformat.Legal}}{Legal}{8.5 inch}{14 inch} +\end{tableiv} \medskip Modified: trunk/pyx/manual/epsfile.tex =================================================================== --- trunk/pyx/manual/epsfile.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/epsfile.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -16,31 +16,19 @@ constructor. They are summarized in the following table: \medskip -\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X} -argument name&description\\ -\hline -\texttt{x} & $x$-coordinate of position.\\ -\texttt{y} & $y$-coordinate of position.\\ -\texttt{filename} & Name of the EPS file (including a possible -extension).\\ -\texttt{width=None} & Desired width of EPS graphics or \texttt{None} -for original width. Cannot be combined with scale specification.\\ -\texttt{height=None} & Desired height of EPS graphics or \texttt{None} -for original height. Cannot be combined with scale specification.\\ -\texttt{scale=None} & Scaling factor for EPS graphics or \texttt{None} -for no scaling. Cannot be combined with width or height specification.\\ -\texttt{align="bl"} & Alignment of EPS graphics. The first character -specifies the vertical alignment: \texttt{b} for bottom, \texttt{c} -for center, and \texttt{t} for top. The second character fixes the -horizontal alignment: \texttt{l} for left, \texttt{c} for center -\texttt{r} for right.\\ -\texttt{clip=1} & Clip to bounding box of EPS file?\\ -\texttt{translatebbox=1} & Use lower left corner of bounding box of EPS -file? Set to $0$ with care.\\ -\texttt{bbox=None} & If given, use \texttt{bbox} instance instead of -bounding box of EPS file.\\ -\texttt{kpsearch=0} & Search for file using the kpathsea library. -\end{tabularx} +\begin{tableii}{l|l}{textrm}{argument name}{description} +\lineii{\texttt{x}}{$x$-coordinate of position.} +\lineii{\texttt{y}}{$y$-coordinate of position.} +\lineii{\texttt{filename}}{Name of the EPS file (including a possible extension).} +\lineii{\texttt{width=None}}{Desired width of EPS graphics or \texttt{None} for original width. Cannot be combined with scale specification.} +\lineii{\texttt{height=None}}{Desired height of EPS graphics or \texttt{None} for original height. Cannot be combined with scale specification.} +\lineii{\texttt{scale=None}}{Scaling factor for EPS graphics or \texttt{None} for no scaling. Cannot be combined with width or height specification.} +\lineii{\texttt{align="bl"}}{Alignment of EPS graphics. The first character specifies the vertical alignment: \texttt{b} for bottom, \texttt{c} for center, and \texttt{t} for top. The second character fixes the horizontal alignment: \texttt{l} for left, \texttt{c} for center \texttt{r} for right.} +\lineii{\texttt{clip=1}}{Clip to bounding box of EPS file?} +\lineii{\texttt{translatebbox=1}}{Use lower left corner of bounding box of EPS file? Set to $0$ with care.} +\lineii{\texttt{bbox=None}}{If given, use \texttt{bbox} instance instead of bounding box of EPS file.} +\lineii{\texttt{kpsearch=0}}{Search for file using the kpathsea library.} +\end{tableii} Modified: trunk/pyx/manual/gradientname.tex =================================================================== --- trunk/pyx/manual/gradientname.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/gradientname.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -1,3 +1,3 @@ \chapter{Named gradients} \label{gradientname} -\centerline{\includegraphics{gradientname}} +\includegraphics{gradientname} Modified: trunk/pyx/manual/graph.tex =================================================================== --- trunk/pyx/manual/graph.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/graph.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -40,11 +40,8 @@ \end{verbatim} The result \file{graph.eps} is shown in figure~\ref{fig:graph}. -\begin{figure}[ht] -\centerline{\includegraphics{graph}} -\caption[A minimalistic plot for the data from a file.]{A minimalistic plot for the data from file \file{graph.dat}.} -\label{fig:graph} -\end{figure} +\includegraphics{graph} +\centerline{A minimalistic plot for the data from file \file{graph.dat}.} Instead of plotting data from a file, other data source are available as well. For example function data is created and placed into @@ -63,11 +60,8 @@ in figure~\ref{fig:graph2}, a function is plotted as a line by default. -\begin{figure}[ht] -\centerline{\includegraphics{graph2}} -\caption{Plotting data from a file together with a function.} -\label{fig:graph2} -\end{figure} +\includegraphics{graph2} +\centerline{Plotting data from a file together with a function.} While the axes ranges got adjusted automatically in the previous example, they might be fixed by keyword options in axes constructors. @@ -79,12 +73,8 @@ The result is shown in figure~\ref{fig:graph3}. -\begin{figure}[ht] -\centerline{\includegraphics{graph3}} -\caption{Plotting a function for a given axis range and use a -logarithmic y-axis.} -\label{fig:graph3} -\end{figure} % }}} +\includegraphics{graph3} +\centerline{Plotting a function for a given axis range and use a logarithmic y-axis.} \section{Component architecture} % {{{ \label{graph:components} @@ -657,28 +647,28 @@ The builtins in math expressions are listed in the following table: \begin{tableii}{l|l}{textrm}{name}{value} -\code{neg}&\code{lambda x: -x}\\ -\code{abs}&\code{lambda x: x < 0 and -x or x}\\ -\code{sgn}&\code{lambda x: x < 0 and -1 or 1}\\ -\code{sqrt}&\code{math.sqrt}\\ -\code{exp}&\code{math.exp}\\ -\code{log}&\code{math.log}\\ -\code{sin}&\code{math.sin}\\ -\code{cos}&\code{math.cos}\\ -\code{tan}&\code{math.tan}\\ -\code{asin}&\code{math.asin}\\ -\code{acos}&\code{math.acos}\\ -\code{atan}&\code{math.atan}\\ -\code{sind}&\code{lambda x: math.sin(math.pi/180*x)}\\ -\code{cosd}&\code{lambda x: math.cos(math.pi/180*x)}\\ -\code{tand}&\code{lambda x: math.tan(math.pi/180*x)}\\ -\code{asind}&\code{lambda x: 180/math.pi*math.asin(x)}\\ -\code{acosd}&\code{lambda x: 180/math.pi*math.acos(x)}\\ -\code{atand}&\code{lambda x: 180/math.pi*math.atan(x)}\\ -\code{norm}&\code{lambda x, y: math.hypot(x, y)}\\ -\code{splitatvalue}&see the \code{splitatvalue} description below\\ -\code{pi}&\code{math.pi}\\ -\code{e}&\code{math.e} +\lineii{\code{neg}}{\code{lambda x: -x}} +\lineii{\code{abs}}{\code{lambda x: x < 0 and -x or x}} +\lineii{\code{sgn}}{\code{lambda x: x < 0 and -1 or 1}} +\lineii{\code{sqrt}}{\code{math.sqrt}} +\lineii{\code{exp}}{\code{math.exp}} +\lineii{\code{log}}{\code{math.log}} +\lineii{\code{sin}}{\code{math.sin}} +\lineii{\code{cos}}{\code{math.cos}} +\lineii{\code{tan}}{\code{math.tan}} +\lineii{\code{asin}}{\code{math.asin}} +\lineii{\code{acos}}{\code{math.acos}} +\lineii{\code{atan}}{\code{math.atan}} +\lineii{\code{sind}}{\code{lambda x: math.sin(math.pi/180*x)}} +\lineii{\code{cosd}}{\code{lambda x: math.cos(math.pi/180*x)}} +\lineii{\code{tand}}{\code{lambda x: math.tan(math.pi/180*x)}} +\lineii{\code{asind}}{\code{lambda x: 180/math.pi*math.asin(x)}} +\lineii{\code{acosd}}{\code{lambda x: 180/math.pi*math.acos(x)}} +\lineii{\code{atand}}{\code{lambda x: 180/math.pi*math.atan(x)}} +\lineii{\code{norm}}{\code{lambda x, y: math.hypot(x, y)}} +\lineii{\code{splitatvalue}}{see the \code{splitatvalue} description below} +\lineii{\code{pi}}{\code{math.pi}} +\lineii{\code{e}}{\code{math.e}} \end{tableii} \code{math} refers to Pythons \module{math} module. The \code{splitatvalue} function is defined as: @@ -929,13 +919,6 @@ the data provided by the \class{range} style. The additional data column named \code{color} specifies the color of the rectangle defined by \var{gradient}. The valid color range is [0:1]. - - \begin{note} - Although this style can be used for plotting colored surfaces, it - will lead to a huge memory footprint of \PyX{} together with a - long running time and large outputs. Improved support for colored - surfaces is planned for the future. - \end{note} \end{classdesc} % }}} \begin{classdesc}{histogram}{lineattrs=[], steps=0, fromvalue=0, % {{{ Modified: trunk/pyx/manual/graphics.tex =================================================================== --- trunk/pyx/manual/graphics.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/graphics.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -80,13 +80,10 @@ Fig.~\ref{fig:rects}b), the pen is not lifted between the first and the last point: % -\begin{figure} -\centerline{\includegraphics{rects}} -\caption{Rectangle consisting of (a) four separate lines, (b) one open +\includegraphics{rects} +\centerline{Rectangle consisting of (a) four separate lines, (b) one open path, and (c) one closed path. (d) Filling a path always closes it automatically.} -\label{fig:rects} -\end{figure} % \begin{verbatim} rect2 = path.path(path.moveto(0, 0), path.lineto(0, 1), @@ -146,11 +143,8 @@ circle with a straight line. This task can be done using the following code which results in Fig.~\ref{fig:radii} \verbatiminput{radii.py} -\begin{figure} -\centerline{\includegraphics{radii}} -\caption{Example: Intersection of circle with line yielding two radii.} -\label{fig:radii} -\end{figure} +\includegraphics{radii} +\centerline{Example: Intersection of circle with line yielding two radii.} Here, the basic elements, a circle around the point $(0, 0)$ with radius $2$ and a straight line, are defined. Then, passing the \var{line}, to the \method{intersect()} method of \var{circle}, we obtain a tuple of @@ -181,12 +175,9 @@ segment = line2 << arc \end{verbatim} -\begin{figure} -\centerline{\includegraphics{radii2}} -\caption{Example: Intersection of circle with line yielding radii and +\includegraphics{radii2} +\centerline{Example: Intersection of circle with line yielding radii and circle segment.} -\label{fig:radii2} -\end{figure} Here, we first split the circle using the \method{split()} method passing the list of parameters obtained above. Since the circle is closed, this yields two arc segments. We then use the \method{arclen()}, which @@ -304,54 +295,15 @@ \code{attr.clear}. An overview over the most important attribute typesprovided by PyX is given in the following table. \medskip -\begin{center} -\begin{tabular}{l|l|p{0.3\linewidth}} -Attribute category & description & examples\\ -\hline -\class{deco.deco} & decorator specifying the way the path is drawn & -\class{deco.stroked}\newline -\class{deco.filled}\newline -\class{deco.arrow} -\\ -\class{style.strokestyle} & style used for path stroking & -\class{style.linecap}\newline -\class{style.linejoin}\newline -\class{style.miterlimit}\newline -\class{style.dash}\newline -\class{style.linestyle}\newline -\class{style.linewidth}\newline -\class{color.color} -\\ -\class{style.fillstyle} & style used for path filling & -\class{color.color}\newline\class{pattern.pattern} -\\ -\class{style.filltype} & type of path filling & -\code{style.filltype.nonzero_winding} (default)\newline\code{style.filltype.even_odd} -\\ -\class{deformer.deformer} & -operations changing the shape of the path -& -\class{deformer.cycloid}\newline -\class{deformer.smoothed} -\\ -\class{text.textattr} & attributes used for typesetting & -\class{text.halign}\newline -\class{text.valign}\newline -\class{text.mathmode}\newline -\class{text.phantom}\newline -\class{text.size}\newline -\class{text.parbox} -\\ -\class{trafo.trafo} -& transformations applied when drawing object -& -\class{trafo.mirror}\newline -\class{trafo.rotate}\newline -\class{trafo.scale}\newline -\class{trafo.slant}\newline -\class{trafo.translate} -\end{tabular} -\end{center} +\begin{tableiii}{l|l|l}{textrm}{Attribute category}{description}{examples} +\lineiii{\class{deco.deco}}{decorator specifying the way the path is drawn}{\class{deco.stroked}, \class{deco.filled}, \class{deco.arrow}} +\lineiii{\class{style.strokestyle}}{style used for path stroking}{\class{style.linecap}, \class{style.linejoin}, \class{style.miterlimit}, \class{style.dash}, \class{style.linestyle}, \class{style.linewidth}, \class{color.color}} +\lineiii{\class{style.fillstyle}}{style used for path filling}{\class{color.color}, \class{pattern.pattern}} +\lineiii{\class{style.filltype}}{type of path filling}{\code{style.filltype.nonzero_winding} (default), \code{style.filltype.even_odd}} +\lineiii{\class{deformer.deformer}}{operations changing the shape of the path}{\class{deformer.cycloid}, \class{deformer.smoothed}} +\lineiii{\class{text.textattr}}{attributes used for typesetting}{\class{text.halign}, \class{text.valign}, \class{text.mathmode}, \class{text.phantom}, \class{text.size}, \class{text.parbox}} +\lineiii{\class{trafo.trafo}}{ransformations applied when drawing object}{\class{trafo.mirror}, \class{trafo.rotate}, \class{trafo.scale}, \class{trafo.slant}, \class{trafo.translate}} +\end{tableiii} \medskip XXX specify which classes in the table are in fact instances Modified: trunk/pyx/manual/manual.tex =================================================================== --- trunk/pyx/manual/manual.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/manual.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -1,23 +1,13 @@ \documentclass{manual} - -% to shorten edit-compile-view cycles use -% \includeonly{graph} - \usepackage{pyx} -\ifhtml -\def\PyX{PyX} % redefine the PyX macro for html (the other makes trouble) -\def\textquotedbl{"} % make double quotes available in html -\fi \usepackage{graphicx} \usepackage[T1]{fontenc} -\usepackage{tabularx} % TODO: get rid of that -\usepackage{units} % TODO: get rid of that \title{\PyX{} Reference Manual} \author{J\"org Lehmann, Andr\'e Wobst} \authoraddress{http://pyx.sourceforge.net/} -\date{\input{pyxdate.tex}} -\release{\input{pyxversion.tex}} +\date{DUMMY} +\release{DUMMY} \makeindex @@ -26,9 +16,6 @@ \maketitle \cleardoublepage -\ifhtml % make abstract better available (as in the Python docs) -\chapter*{Front Matter\label{front}} -\fi \begin{abstract} \noindent \PyX{} is a Python package for the creation of PostScript and PDF files. It @@ -39,31 +26,28 @@ \tableofcontents -\include{intro} -\include{graphics} -\include{path} -%\include{deco} -\include{deformer} -\include{canvas} -\include{document} -\include{text} -\include{graph} -\include{axis} -\include{box} -\include{connector} -\include{epsfile} -\include{bitmap} -\include{bbox} -\include{color} -\include{pattern} -\include{unit} -\include{trafo} -\appendix -\include{colorname} -\include{palettename} -\include{pathstyles} -\include{arrows} +% \include{intro} +% \include{graphics} +% \include{path} +% \include{deformer} +% \include{canvas} +% \include{document} +% \include{text} +% \include{graph} +% \include{axis} +% \include{box} +% \include{connector} +% \include{epsfile} +% \include{bitmap} +% \include{bbox} +% \include{color} +% \include{pattern} +% \include{unit} +% \include{trafo} +% \appendix +% \include{colorname} +% \include{palettename} +% \include{pathstyles} +% \include{arrows} -\input{manual.ind} - \end{document} Modified: trunk/pyx/manual/pathstyles.tex =================================================================== --- trunk/pyx/manual/pathstyles.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/pathstyles.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -1,3 +1,3 @@ \chapter{Module \module{style}} \label{pathstyles} -\centerline{\includegraphics{pathstyles}} +\includegraphics{pathstyles} Modified: trunk/pyx/manual/pattern.tex =================================================================== --- trunk/pyx/manual/pattern.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/pattern.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -19,33 +19,15 @@ keyword arguments: \medskip -\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X} -keyword&description\\ -\hline -\texttt{painttype}&\texttt{1} (default) for coloured patterns or -\texttt{2} for uncoloured patterns\\ -\texttt{tilingtype}&\texttt{1} (default) for constant spacing tilings -(patterns are spaced constantly by a multiple of a device pixel), -\texttt{2} for undistorted pattern cell, whereby the spacing may vary -by as much as one device pixel, or \texttt{3} for constant spacing and -faster tiling which behaves as tiling type \texttt{1} but with -additional distortion allowed to permit a more efficient -implementation.\\ -\texttt{xstep}&desired horizontal spacing between pattern cells, use -\texttt{None} (default) for automatic calculation from pattern -bounding box.\\ -\texttt{ystep}&desired vertical spacing between pattern cells, use -\texttt{None} (default) for automatic calculation from pattern -bounding box.\\ -\texttt{bbox}&bounding box of pattern. Use \texttt{None} for an -automatic determination of the bounding box (including an -enlargement by \texttt{bboxenlarge} pts on each side.)\\ -\texttt{trafo}&additional transformation applied to pattern or -\texttt{None} (default). This may be used to rotate the pattern or to -shift its phase (by a translation).\\ -\texttt{bboxenlarge}&enlargement when using the automatic bounding box -determination; default is 5 pts. -\end{tabularx} +\begin{tableii}{l|l}{textrm}{keyword}{description} +\lineii{\texttt{painttype}}{\texttt{1} (default) for coloured patterns or \texttt{2} for uncoloured patterns} +\lineii{\texttt{tilingtype}}{\texttt{1} (default) for constant spacing tilings (patterns are spaced constantly by a multiple of a device pixel), \texttt{2} for undistorted pattern cell, whereby the spacing may vary by as much as one device pixel, or \texttt{3} for constant spacing and faster tiling which behaves as tiling type \texttt{1} but with additional distortion allowed to permit a more efficient implementation.} +\lineii{\texttt{xstep}}{desired horizontal spacing between pattern cells, use \texttt{None} (default) for automatic calculation from pattern bounding box.} +\lineii{\texttt{ystep}}{desired vertical spacing between pattern cells, use \texttt{None} (default) for automatic calculation from pattern bounding box.} +\lineii{\texttt{bbox}}{bounding box of pattern. Use \texttt{None} for an automatic determination of the bounding box (including an enlargement by \texttt{bboxenlarge} pts on each side.)} +\lineii{\texttt{trafo}}{additional transformation applied to pattern or \texttt{None} (default). This may be used to rotate the pattern or to shift its phase (by a translation).} +\lineii{\texttt{bboxenlarge}}{enlargement when using the automatic bounding box determination; default is 5 pts.} +\end{tableii} \medskip After you have created a pattern instance, you define the pattern Modified: trunk/pyx/manual/text.tex =================================================================== --- trunk/pyx/manual/text.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/text.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -1,4 +1,4 @@ -\chapter[Module \module{text}: TeX/LaTeX interface]{Module \module{text}: \TeX/\LaTeX{} interface} +\chapter{Module \module{text}: \TeX/\LaTeX{} interface} \label{module:text} \section{Basic functionality} @@ -32,8 +32,7 @@ the \var{fontmap} keyword argument to a texrunners \method{text} method to use different mappings within a single outout file. -\section[TeX/LaTeX instances: the \class{texrunner} class]% -{\TeX/\LaTeX{} instances: the \class{texrunner} class} +\section{\TeX/\LaTeX{} instances: the \class{texrunner} class} \declaremodule{}{text} \modulesynopsis{\TeX/\LaTeX interface} @@ -193,8 +192,7 @@ \end{methoddesc} -\section[TeX/LaTeX attributes] -{\TeX/\LaTeX{} attributes} +\section{\TeX/\LaTeX{} attributes} \declaremodule{}{text} \modulesynopsis{\TeX/\LaTeX interface} @@ -276,11 +274,8 @@ \code{halign(1, 1)}. \end{memberdesc} -\begin{figure} -\centerline{\includegraphics{textvalign}} -\caption{valign example} -\label{fig:textvalign} -\end{figure} +\includegraphics{textvalign} +\centerline{valign example} \begin{classdesc}{valign}{valign} Instances of this class set the vertical alignment of a text box to @@ -441,8 +436,7 @@ Skip the text in the box, but keep its size. \end{datadesc} -\section[Using the graphics-bundle with LaTeX]% -{Using the graphics-bundle with \LaTeX} +\section{Using the graphics-bundle with \LaTeX} The packages in the \LaTeX{} graphics bundle (\texttt{color.sty}, \texttt{graphics.sty}, \texttt{graphicx.sty}, \ldots) make extensive use of @@ -506,8 +500,7 @@ ends rotation. \end{description} -\section[TeX message parsers]% -{\TeX{} message parsers} +\section{\TeX{} message parsers} \declaremodule{}{text} \modulesynopsis{\TeX/\LaTeX interface} Modified: trunk/pyx/manual/trafo.tex =================================================================== --- trunk/pyx/manual/trafo.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/trafo.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -12,9 +12,9 @@ The \verb|trafo| class represents a general linear transformation, which is defined for a vector $\vec{x}$ as -$+\begin{displaymath} \vec{x}' = \mathsf{A}\, \vec{x} + \vec{b}\ , -$ +\end{displaymath} where $\mathsf{A}$ is the transformation matrix and $\vec{b}$ the translation vector. The transformation matrix must not be singular, \textit{i.e.} we require $\det \mathsf{A} \ne 0$. @@ -37,33 +37,16 @@ table. \medskip -\begin{tabularx}{\linewidth}{>{\hsize=.8\hsize}X>{\raggedright\arraybackslash\hsize=1.2\hsize}X} -\texttt{trafo} method & function \\ -\hline -\texttt{\_\_init\_\_(matrix=((1,0),(0,1)),\newline -\phantom{\_\_init\_\_(}vector=(0,0)):} & create new \texttt{trafo} -instance with transformation \texttt{matrix} and \texttt{vector}. -\\ -\texttt{apply(x, y)} & apply \texttt{trafo} to point vector -$(\mathtt{x}, \mathtt{y})$.\\ -\texttt{inverse()} & returns inverse transformation of -\texttt{trafo}.\\ -\texttt{mirrored(angle)} & returns \texttt{trafo} followed by mirroring -at line through $(0,0)$ with direction \texttt{angle} in degrees.\\ -\texttt{rotated(angle, \newline\phantom{rotate(}x=None, y=None)} & -returns \texttt{trafo} followed by rotation by \texttt{angle} degrees -around point $(\mathtt{x}, -\mathtt{y})$, or $(0,0)$, if not given.\\ -\texttt{scaled(sx, sy=None,\newline\phantom{scale(}x=None, y=None)} & -returns \texttt{trafo} followed by -scaling with scaling factor \texttt{sx} in $x$-direction, \texttt{sy} in -$y$-direction ($\mathtt{sy}=\mathtt{sx}$, if not given) with scaling -center $(\mathtt{x}, \mathtt{y})$, or $(0,0)$, if not given.\\ -\texttt{translated(x, y)} & returns \texttt{trafo} followed by -translation by vector $(\mathtt{x}, \mathtt{y})$.\\ -\texttt{slanted(a, angle=0, x=None, y=None)} & returns \texttt{trafo} -followed by XXX\\ -\end{tabularx} +\begin{tableii}{l|l}{textrm}{\texttt{trafo} method}{function} +\lineii{\texttt{\_\_init\_\_(matrix=((1,0),(0,1)), vector=(0,0)):}}{create new \texttt{trafo} instance with transformation \texttt{matrix} and \texttt{vector}.} +\lineii{\texttt{apply(x, y)}}{apply \texttt{trafo} to point vector $(\mathtt{x}, \mathtt{y})$.} +\lineii{\texttt{inverse()}}{returns inverse transformation of \texttt{trafo}.} +\lineii{\texttt{mirrored(angle)}}{returns \texttt{trafo} followed by mirroring at line through $(0,0)$ with direction \texttt{angle} in degrees.} +\lineii{\texttt{rotated(angle, x=None, y=None)}}{returns \texttt{trafo} followed by rotation by \texttt{angle} degrees around point $(\mathtt{x}, \mathtt{y})$, or $(0,0)$, if not given.} +\lineii{\texttt{scaled(sx, sy=None, x=None, y=None)}}{returns \texttt{trafo} followed by scaling with scaling factor \texttt{sx} in $x$-direction, \texttt{sy} in $y$-direction ($\mathtt{sy}=\mathtt{sx}$, if not given) with scaling center $(\mathtt{x}, \mathtt{y})$, or $(0,0)$, if not given.} +\lineii{\texttt{translated(x, y)}}{returns \texttt{trafo} followed by translation by vector $(\mathtt{x}, \mathtt{y})$.} +\lineii{\texttt{slanted(a, angle=0, x=None, y=None)}}{returns \texttt{trafo} followed by XXX} +\end{tableii} \medskip @@ -75,23 +58,13 @@ method. They are listed in the following table: \medskip -\begin{tabularx}{\linewidth}{>{\hsize=.7\hsize}X>{\raggedright\arraybackslash\hsize=1.3\hsize}X} - \texttt{trafo} subclass & function \\ - \hline - \texttt{mirror(angle)} & mirroring at line through $(0,0)$ - with direction \texttt{angle} in degrees.\\ - \texttt{rotate(angle, \newline\phantom{rotation(}x=None, y=None)} & - rotation by \texttt{angle} degrees around point $(\mathtt{x}, - \mathtt{y})$, or $(0,0)$, if not given.\\ - \texttt{scale(sx, sy=None,\newline\phantom{scaling(}x=None, y=None)} & - scaling with scaling factor \texttt{sx} in $x$-direction, - \texttt{sy} in $y$-direction ($\mathtt{sy}=\mathtt{sx}$, if not - given) with scaling - center $(\mathtt{x}, \mathtt{y})$, or $(0,0)$, if not given.\\ - \texttt{translate(x, y)} & - translation by vector $(\mathtt{x}, \mathtt{y})$.\\ - \texttt{slant(a, angle=0, x=None, y=None)} & XXX \\ -\end{tabularx} +\begin{tableii}{l|l}{textrm}{\texttt{trafo} subclass}{function} +\lineii{\texttt{mirror(angle)}}{mirroring at line through $(0,0)$ with direction \texttt{angle} in degrees.} +\lineii{\texttt{rotate(angle, x=None, y=None)}}{rotation by \texttt{angle} degrees around point $(\mathtt{x}, \mathtt{y})$, or $(0,0)$, if not given.} +\lineii{\texttt{scale(sx, sy=None, x=None, y=None)}}{scaling with scaling factor \texttt{sx} in $x$-direction, \texttt{sy} in $y$-direction ($\mathtt{sy}=\mathtt{sx}$, if not given) with scaling center $(\mathtt{x}, \mathtt{y})$, or $(0,0)$, if not given.} +\lineii{\texttt{translate(x, y)}}{translation by vector $(\mathtt{x}, \mathtt{y})$.} +\lineii{\texttt{slant(a, angle=0, x=None, y=None)}}{XXX} +\end{tableii} \medskip Modified: trunk/pyx/manual/unit.tex =================================================================== --- trunk/pyx/manual/unit.tex 2011-05-19 12:17:50 UTC (rev 3138) +++ trunk/pyx/manual/unit.tex 2011-05-20 07:58:29 UTC (rev 3139) @@ -8,15 +8,14 @@ With the \verb|unit| module \PyX{} makes available classes and functions for the specification and manipulation of lengths. As usual, lengths consist of a number together with a measurement unit, e.g., -\unit[1]{cm}, \unit[50]{points}, \unit[0.42]{inch}. In addition, +1 cm, 50 points, 0.42 inch. In addition, lengths in \PyX{} are composed of the five types true'', user'', -visual'', width'', and \TeX'', e.g., \unit[1]{user cm}, -\unit[50]{true points}, $(0.42\ \mathrm{visual} + 0.2\ -\mathrm{width})$ inch. As their names indicate, they serve different -purposes. True lengths are not scalable and are mainly used for return -values of \PyX{} functions. The other length types can be rescaled by -the user and differ with respect to the type of object they are -applied to: +visual'', width'', and \TeX'', e.g., 1 user cm, +50 true points, 0.42 visual + 0.2 width inch. As their names +indicate, they serve different purposes. True lengths are not scalable +and are mainly used for return values of \PyX{} functions. The other +length types can be rescaled by the user and differ with respect to +the type of object they are applied to: \begin{description} \item[user length:] used for lengths of graphical objects like @@ -28,7 +27,7 @@ \end{description} When not specified otherwise, all types of lengths are interpreted -in terms of a default unit, which, by default, is \unit[1]{cm}. +in terms of a default unit, which, by default, is 1 cm. You may change this default unit by using the module level function \begin{funcdesc}{set}{uscale=None, vscale=None, wscale=None, xscale=None, defaultunit=None} @@ -81,28 +80,38 @@ summarized in the following table \medskip -\begin{center} -\begin{tabular}{lll|lll} -name & type & unit & name & type & unit\\ -\hline -\constant{m} & user & m & \constant{v\_m} & visual & m\\ -\constant{cm} & user & cm & \constant{v\_cm} & visual & cm\\ -\constant{mm} & user & mm & \constant{v\_mm} & visual & mm\\ -\constant{inch} & user & inch & \constant{v\_inch} & visual & inch\\ -\constant{pt} & user & points & \constant{v\_pt} & visual & points\\ -\constant{t\_m} & true & m & \constant{w\_m} & width & m\\ -\constant{t\_cm} & true & cm & \constant{w\_cm} & width & cm\\ -\constant{t\_mm} & true & mm & \constant{w\_mm} & width & mm\\ -\constant{t\_inch} & true & inch & \constant{w\_inch} & width & inch\\ -\constant{t\_pt} & true & points & \constant{w\_pt} & width & points\\ -\constant{u\_m} & user & m & \constant{x\_m} & \TeX & m \\ -\constant{u\_cm} & user & cm & \constant{x\_cm} & \TeX & cm \\ -\constant{u\_mm} & user & mm & \constant{x\_mm} & \TeX & mm \\ -\constant{u\_inch} & user & inch & \constant{x\_inch} & \TeX & inch \\ -\constant{u\_pt} & user & points & \constant{x\_pt} & \TeX & points\\ - -\end{tabular} -\end{center} +\begin{tableiii}{lll}{textrm}{name}{type}{unit} +\lineiii{\constant{m}}{user}{m} +\lineiii{\constant{cm}}{user}{cm} +\lineiii{\constant{mm}}{user}{mm} +\lineiii{\constant{inch}}{user}{inch} +\lineiii{\constant{pt}}{user}{points} +\lineiii{\constant{t\_m}}{true}{m} +\lineiii{\constant{t\_cm}}{true}{cm} +\lineiii{\constant{t\_mm}}{true}{mm} +\lineiii{\constant{t\_inch}}{true}{inch} +\lineiii{\constant{t\_pt}}{true}{points} +\lineiii{\constant{u\_m}}{user}{m} +\lineiii{\constant{u\_cm}}{user}{cm} +\lineiii{\constant{u\_mm}}{user}{mm} +\lineiii{\constant{u\_inch}}{user}{inch} +\lineiii{\constant{u\_pt}}{user}{points} +\lineiii{\constant{v\_m}}{visual}{m} +\lineiii{\constant{v\_cm}}{visual}{cm} +\lineiii{\constant{v\_mm}}{visual}{mm} +\lineiii{\constant{v\_inch}}{visual}{inch} +\lineiii{\constant{v\_pt}}{visual}{points} +\lineiii{\constant{w\_m}}{width}{m} +\lineiii{\constant{w\_cm}}{width}{cm} +\lineiii{\constant{w\_mm}}{width}{mm} +\lineiii{\constant{w\_inch}}{width}{inch} +\lineiii{\constant{w\_pt}}{width}{points} +\lineiii{\constant{x\_m}}{\TeX}{m } +\lineiii{\constant{x\_cm}}{\TeX}{cm } +\lineiii{\constant{x\_mm}}{\TeX}{mm } +\lineiii{\constant{x\_inch}}{\TeX}{inch } +\lineiii{\constant{x\_pt}}{\TeX}{points} +\end{tableiii} \medskip Thus, in order to specify, e.g., a length of 5 width points, just use @@ -112,17 +121,13 @@ If you want to know the value of a \PyX{} length in certain units, you may use the predefined conversion functions which are given in the following table -\begin{center} -\begin{tabular}{ll} -function & result \\ -\hline -\texttt{tom(l)} & \texttt{l} in units of m\\ -\texttt{tocm(l)} & \texttt{l} in units of cm\\ -\texttt{tomm(l)} & \texttt{l} in units of mm\\ -\texttt{toinch(l)} & \texttt{l} in units of inch\\ -\texttt{topt(l)} & \texttt{l} in units of points\\ -\end{tabular} -\end{center} +\begin{tableii}{l|l}{textrm}{function}{result} +\lineii{\texttt{tom(l)}}{\texttt{l} in units of m} +\lineii{\texttt{tocm(l)}}{\texttt{l} in units of cm} +\lineii{\texttt{tomm(l)}}{\texttt{l} in units of mm} +\lineii{\texttt{toinch(l)}}{\texttt{l} in units of inch} +\lineii{\texttt{topt(l)}}{\texttt{l} in units of points} +\end{tableii} If \verb|l| is not yet a \verb|length| instance but a number, it first is interpreted as a user length in the default units. This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. 
 [PyX-checkins] SF.net SVN: pyx:[3142] trunk/pyx/manual From: - 2011-05-20 08:02:25 Revision: 3142 http://pyx.svn.sourceforge.net/pyx/?rev=3142&view=rev Author: wobsta Date: 2011-05-20 08:02:19 +0000 (Fri, 20 May 2011) Log Message: ----------- remove pyxdate and pyxversion, which are not be handled by separate files Removed Paths: ------------- trunk/pyx/manual/pyxdate.rst trunk/pyx/manual/pyxversion.rst Deleted: trunk/pyx/manual/pyxdate.rst =================================================================== --- trunk/pyx/manual/pyxdate.rst 2011-05-20 08:00:48 UTC (rev 3141) +++ trunk/pyx/manual/pyxdate.rst 2011-05-20 08:02:19 UTC (rev 3142) @@ -1,4 +0,0 @@ -2011/05/15 - -.. % - Deleted: trunk/pyx/manual/pyxversion.rst =================================================================== --- trunk/pyx/manual/pyxversion.rst 2011-05-20 08:00:48 UTC (rev 3141) +++ trunk/pyx/manual/pyxversion.rst 2011-05-20 08:02:19 UTC (rev 3142) @@ -1,4 +0,0 @@ -0.11 - -.. % - This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. 
 [PyX-checkins] SF.net SVN: pyx:[3141] trunk/pyx/manual From: - 2011-05-20 08:00:57 Revision: 3141 http://pyx.svn.sourceforge.net/pyx/?rev=3141&view=rev Author: wobsta Date: 2011-05-20 08:00:48 +0000 (Fri, 20 May 2011) Log Message: ----------- conversion result (non-edited) Added Paths: ----------- trunk/pyx/manual/arrows.rst trunk/pyx/manual/axis.rst trunk/pyx/manual/bbox.rst trunk/pyx/manual/bitmap.rst trunk/pyx/manual/box.rst trunk/pyx/manual/canvas.rst trunk/pyx/manual/color.rst trunk/pyx/manual/colorname.rst trunk/pyx/manual/connector.rst trunk/pyx/manual/deformer.rst trunk/pyx/manual/document.rst trunk/pyx/manual/epsfile.rst trunk/pyx/manual/gradientname.rst trunk/pyx/manual/graph.rst trunk/pyx/manual/graphics.rst trunk/pyx/manual/intro.rst trunk/pyx/manual/manual.rst trunk/pyx/manual/path.rst trunk/pyx/manual/pathstyles.rst trunk/pyx/manual/pattern.rst trunk/pyx/manual/pyxdate.rst trunk/pyx/manual/pyxversion.rst trunk/pyx/manual/text.rst trunk/pyx/manual/trafo.rst trunk/pyx/manual/unit.rst Added: trunk/pyx/manual/arrows.rst =================================================================== --- trunk/pyx/manual/arrows.rst (rev 0) +++ trunk/pyx/manual/arrows.rst 2011-05-20 08:00:48 UTC (rev 3141) @@ -0,0 +1,12 @@ + +.. _arrows: + +********************* +Arrows in deco module +********************* + +.. % DUMMY +.. _fig_label: +.. figure:: arrows.* + :align: center + Added: trunk/pyx/manual/axis.rst =================================================================== --- trunk/pyx/manual/axis.rst (rev 0) +++ trunk/pyx/manual/axis.rst 2011-05-20 08:00:48 UTC (rev 3141) @@ -0,0 +1,905 @@ + +.. _axis: + +**** +Axes +**** + + +Component architecture +====================== + +Axes are a fundamental component of graphs although there might be applications +outside of the graph system. Internally axes are constructed out of components, +which handle different tasks axes need to fulfill: + +.. % {{{ + +axis + Implements the conversion of a data value to a graph coordinate of range [0:1]. + It does also handle the proper usage of the components in complicated tasks + (*i.e.* combine the partitioner, texter, painter and rater to find the best + partitioning). + + An anchoredaxis is a container to combine an axis with an positioner and provide + a storage area for all kind of axis data. That way axis instances are reusable + (they do not store any data locally). The anchoredaxis and the positioner are + created by a graph corresponding to its geometry. + +tick + Ticks are plotted along the axis. They might be labeled with text as well. + +partitioner, we use "parter" as a short form + Creates one or several choices of tick lists suitable to a certain axis range. + +texter + Creates labels for ticks when they are not set manually. + +painter + Responsible for painting the axis. + +rater + Calculate ratings, which can be used to select the best suitable partitioning. + +positioner + Defines the position of an axis. + +The names above map directly to modules which are provided in the directory +:file:graph/axis except for the anchoredaxis, which is part of the axis module +as well. Sometimes it might be convenient to import the axis directory directly +rather than to access iit through the graph. This would look like:: + + from pyx import * + graph.axis.painter() # and the like + + from pyx.graph import axis + axis.painter() # this is shorter ... + +In most cases different implementations are available through different classes, +which can be combined in various ways. There are various axis examples +distributed with PyX, where you can see some of the features of the axis with a +few lines of code each. Hence we can here directly come to the reference of the +available components. + +.. % }}} + + +Module :mod:graph.axis.axis: Axes +=================================== + +.. module:: graph.axis.axis + :synopsis: Axes + + +.. % {{{ + +The following classes are part of the module :mod:graph.axis.axis. However, +there is a shortcut to access those classes via graph.axis directly. + +Instances of the following classes can be passed to the *\*\*axes* keyword +arguments of a graph. Those instances should only be used once. + + +.. class:: linear(min=None, max=None, reverse=0, divisor=None, title=None, parter=parter.autolinear(), manualticks=[], density=1, maxworse=2, rater=rater.linear(), texter=texter.mixed(), painter=painter.regular(), linkpainter=painter.linked(), fallbackrange=None) + + This class provides a linear axis. *min* and *max* define the axis range. When + not set, they are adjusted automatically by the data to be plotted in the graph. + Note, that some data might want to access the range of an axis (*e.g.* the + :class:function class when no range was provided there) or you need to specify + a range when using the axis without plugging it into a graph (*e.g.* when + drawing an axis along a path). In cases where the data provides a range of zero + (e.g. a when plotting a constant function), then a *fallbackrange* can be set to + guarantee a minimal range of the axis. + + *reverse* can be set to indicate a reversed axis starting with bigger values + first. Alternatively you can fix the axis range by *min* and *max* accordingly. + When divisor is set, it is taken to divide all data range and position + informations while creating ticks. You can create ticks not taking into account + a factor by that. *title* is the title of the axis. + + *parter* is a partitioner instance, which creates suitable ticks for the axis + range. Those ticks are merged with ticks manually given by *manualticks* before + proceeding with rating, painting *etc.* Manually placed ticks win against those + created by the partitioner. For automatic partitioners, which are able to + calculate several possible tick lists for a given axis range, the *density* is a + (linear) factor to favour more or less ticks. It should not be stressed to much + (its likely, that the result would be unappropriate or not at all valid in terms + of rating label distances). But within a range of say 0.5 to 2 (even bigger for + large graphs) it can help to get less or more ticks than the default would lead + to. *maxworse* is the number of trials with more and less ticks when a better + rating was already found. *rater* is a rater instance, which rates the ticks and + the label distances for being best suitable. It also takes into account + *density*. The rater is only needed, when the partitioner creates several tick + lists. + + *texter* is a texter instance. It creates labels for those ticks, which claim to + have a label, but do not have a label string set already. Ticks created by + partitioners typically receive their label strings by texters. The *painter* is + finally used to construct the output. Note, that usually several output + constructions are needed, since the rater is also used to rate the distances + between the labels for an optimum. The *linkedpainter* is used as the axis + painter, when automatic link axes are created by the :meth:createlinked + method. + + +.. class:: lin(...) + + This class is an abbreviation of :class:linear described above. + + +.. class:: logarithmic(min=None, max=None, reverse=0, divisor=None, title=None, parter=parter.autologarithmic(), manualticks=[], density=1, maxworse=2, rater=rater.logarithmic(), texter=texter.mixed(), painter=painter.regular(), linkpainter=painter.linked(), fallbackrange=None) + + This class provides a logarithmic axis. All parameters work like + :class:linear. Only two parameters have a different default: *parter* and + *rater*. Furthermore and most importantly, the mapping between data and graph + coordinates is logarithmic. + + +.. class:: log(...) + + This class is an abbreviation of :class:logarithmic described above. + + +.. class:: bar(subaxes=None, defaultsubaxis=linear(painter=None, linkpainter=None, parter=None, texter=None), dist=0.5, firstdist=None, lastdist=None, title=None, reverse=0, painter=painter.bar(), linkpainter=painter.linkedbar()) + + This class provides an axis suitable for a bar style. It handles a discrete set + of values and maps them to distinct ranges in graph coordinates. For that, the + axis gets a tuple of two values. + + The first item is taken to be one of the discrete values valid on this axis. The + discrete values can be any hashable type and the order of the subaxes is defined + by the order the data is received or the inverse of that when *reverse* is set. + + The second item is passed to the corresponding subaxis. The result of the + conversion done by the subaxis is mapped to the graph coordinate range reserved + for this subaxis. This range is defined by a size attribute of the subaxis, + which can be added to any axis. (see the sized linear axes described below for + some axes already having a size argument). When no size information is available + for a subaxis, a size value of 1 is used. The baraxis itself calculates its size + by suming up the sizes of its subaxes plus *firstdist*, *lastdist* and *dist* + times the number of subaxes minus 1. + + *subaxes* should be a list or a dictionary mapping a discrete value of the bar + axis to the corresponding subaxis. When no subaxes are set or data is received + for an unknown discrete axis value, instances of defaultsubaxis are used as the + subaxis for this discrete value. + + *dist* is used as the spacing between the ranges for each distinct value. It is + measured in the same units as the subaxis results, thus the default value of + 0.5 means half the width between the distinct values as the width for each + distinct value. *firstdist* and *lastdist* are used before the first and after + the last value. When set to None, half of *dist* is used. + + *title* is the title of the split axes and *painter* is a specialized painter + for an bar axis and *linkpainter* is used as the painter, when automatic link + axes are created by the :meth:createlinked method. + + +.. class:: nestedbar(subaxes=None, defaultsubaxis=bar(dist=0, painter=None, linkpainter=None), dist=0.5, firstdist=None, lastdist=None, title=None, reverse=0, painter=painter.bar(), linkpainter=painter.linkedbar()) + + This class is identical to the bar axis except for the different default value + for defaultsubaxis. + + +.. class:: split(subaxes=None, defaultsubaxis=linear(), dist=0.5, firstdist=0, lastdist=0, title=None, reverse=0, painter=painter.split(), linkpainter=painter.linkedsplit()) + + This class is identical to the bar axis except for the different default value + for defaultsubaxis, firstdist, lastdist, painter, and linkedpainter. + +Sometimes you want to alter the default size of 1 of the subaxes. For that you +have to add a size attribute to the axis data. The two classes +:class:sizedlinear and :class:autosizedlinear do that for linear axes. Their +short names are :class:sizedlin and :class:autosizedlin. +:class:sizedlinear extends the usual linear axis by an first argument *size*. +:class:autosizedlinear creates the size out of its data range automatically +but sets an :class:autolinear parter with *extendtick* being None in order +to disable automatic range modifications while painting the axis. + +The :mod:axis module also contains classes implementing so called anchored +axes, which combine an axis with an positioner and a storage place for axis +related data. Since these features are not interesting for the average PyX user, +we'll not go into all the details of their parameters and except for some handy +axis position methods: + + +.. class:: anchoredaxis() + + DUMMY + + +.. method:: anchoredaxis.basepath(x1=None, x2=None) + + Returns a path instance for the base path. *x1* and *x2* define the axis range, + the base path should cover. For None the beginning and end of the path is + taken, which might cover a longer range, when the axis is embedded as a subaxis. + For that case, a None value extends the range to the point of the middle + between two subaxes or the beginning or end of the whole axis, when the subaxis + is the first or last of the subaxes. + + +.. method:: anchoredaxis.vbasepath(v1=None, v2=None) + + Like :meth:basepath but in graph coordinates. + + +.. method:: anchoredaxis.gridpath(x) + + Returns a path instance for the grid path at position *x*. Might return None + when no grid path is available. + + +.. method:: anchoredaxis.vgridpath(v) + + Like :meth:gridpath but in graph coordinates. + + +.. method:: anchoredaxis.tickpoint(x) + + Returns the position of *x* as a tuple (x, y). + + +.. method:: anchoredaxis.vtickpoint(v) + + Like :meth:tickpoint but in graph coordinates. + + +.. method:: anchoredaxis.tickdirection(x) + + Returns the direction of a tick at *x* as a tuple (dx, dy). The tick + direction points inside of the graph. + + +.. method:: anchoredaxis.vtickdirection(v) + + Like :meth:tickdirection but in graph coordinates. + + +.. method:: anchoredaxis.vtickdirection(v) + + Like :meth:tickdirection but in graph coordinates. + +However, there are two anchored axes implementations :class:linkedaxis and +:class:anchoredpathaxis which are available to the user to create special +forms of anchored axes. + + +.. class:: linkedaxis(linkedaxis=None, errorname="manual-linked", painter=_marker) + + This class implements an anchored axis to be passed to a graph constructor to + manually link the axis to another anchored axis instance *linkedaxis*. Note that + you can skip setting the value of *linkedaxis* in the constructor, but set it + later on by the :meth:setlinkedaxis method described below. *errorname* is + printed within error messages when the data is used and some problem occurs. + *painter* is used for painting the linked axis instead of the *linkedpainter* + provided by the *linkedaxis*. + + +.. method:: linkedaxis.setlinkedaxis(linkedaxis) + + This method can be used to set the *linkedaxis* after constructing the axis. By + that you can create several graph instances with cycled linked axes. + + +.. class:: anchoredpathaxis(path, axis, direction=1) + + This class implements an anchored axis the path *path*. *direction* defines the + direction of the ticks. Allowed values are 1 (left) and -1 (right). + +The :class:anchoredpathaxis contains as any anchored axis after calling its +:meth:create method the painted axis in the :attr:canvas member attribute. +The function :func:pathaxis has the same signature like the +:class:anchoredpathaxis class, but immediately creates the axis and returns +the painted axis. + +.. % }}} + + +Module :mod:graph.axis.tick: Ticks +==================================== + +.. module:: graph.axis.tick + :synopsis: Axes ticks + + +.. % {{{ + +The following classes are part of the module :mod:graph.axis.tick. + + +.. class:: rational(x, power=1, floatprecision=10) + + This class implements a rational number with infinite precision. For that it + stores two integers, the numerator num and a denominator denom. Note + that the implementation of rational number arithmetics is not at all complete + and designed for its special use case of axis partitioning in PyX preventing any + roundoff errors. + + *x* is the value of the rational created by a conversion from one of the + following input values: + +* A float. It is converted to a rational with finite precision determined by + *floatprecision*. + +* A string, which is parsed to a rational number with full precision. It is also + allowed to provide a fraction like "1/3". + +* A sequence of two integers. Those integers are taken as numerator and + denominator of the rational. + +* An instance defining instance variables num and denom like + :class:rational itself. + + *power* is an integer to calculate x**power. This is useful at certain + places in partitioners. + + +.. class:: tick(x, ticklevel=0, labellevel=0, label=None, labelattrs=[], power=1, floatprecision=10) + + This class implements ticks based on rational numbers. Instances of this class + can be passed to the manualticks parameter of a regular axis. + + The parameters *x*, *power*, and *floatprecision* share its meaning with + :class:rational. + + A tick has a tick level (*i.e.* markers at the axis path) and a label lavel + (*e.i.* place text at the axis path), *ticklevel* and *labellevel*. These are + non-negative integers or *None*. A value of 0 means a regular tick or label, + 1 stands for a subtick or sublabel, 2 for subsubtick or subsublabel and + so on. None means omitting the tick or label. *label* is the text of the + label. When not set, it can be created automatically by a texter. *labelattrs* + are the attributes for the labels. + +.. % }}} + + +Module :mod:graph.axis.parter: Partitioners +============================================= + +.. module:: graph.axis.parter + :synopsis: Axes partitioners + + +.. % {{{ + +The following classes are part of the module :mod:graph.axis.parter. Instances +of the classes can be passed to the parter keyword argument of regular axes. + + +.. class:: linear(tickdists=None, labeldists=None, extendtick=0, extendlabel=None, epsilon=1e-10) + + Instances of this class creates equally spaced tick lists. The distances between + the ticks, subticks, subsubticks *etc.* starting from a tick at zero are given + as first, second, third *etc.* item of the list *tickdists*. For a tick + position, the lowest level wins, *i.e.* for [2, 1] even numbers will have + ticks whereas subticks are placed at odd integer. The items of *tickdists* might + be strings, floats or tuples as described for the *pos* parameter of class + :class:tick. + + *labeldists* works equally for placing labels. When *labeldists* is kept + None, labels will be placed at each tick position, but sublabels *etc.* will + not be used. This copy behaviour is also available *vice versa* and can be + disabled by an empty list. + + *extendtick* can be set to a tick level for including the next tick of that + level when the data exceeds the range covered by the ticks by more than + *epsilon*. *epsilon* is taken relative to the axis range. *extendtick* is + disabled when set to None or for fixed range axes. *extendlabel* works + similar to *extendtick* but for labels. + + +.. class:: lin(...) + + This class is an abbreviation of :class:linear described above. + + +.. class:: autolinear(variants=defaultvariants, extendtick=0, epsilon=1e-10) + + Instances of this class creates equally spaced tick lists, where the distance + between the ticks is adjusted to the range of the axis automatically. Variants + are a list of possible choices for *tickdists* of :class:linear. Further + variants are build out of these by multiplying or dividing all the values by + multiples of 10. *variants* should be ordered that way, that the number of + ticks for a given range will decrease, hence the distances between the ticks + should increase within the *variants* list. *extendtick* and *epsilon* have the + same meaning as in :class:linear. + + +.. attribute:: autolinear.defaultvariants + + [[tick.rational((1, 1)), tick.rational((1, 2))], [tick.rational((2, 1)), + tick.rational((1, 1))], [tick.rational((5, 2)), tick.rational((5, 4))], + [tick.rational((5, 1)), tick.rational((5, 2))]] + + +.. class:: autolin(...) + + This class is an abbreviation of :class:autolinear described above. + + +.. class:: preexp(pres, exp) + + This is a storage class defining positions of ticks on a logarithmic scale. It + contains a list *pres* of positions :math:p_i and *exp*, a multiplicator + :math:m. Valid tick positions are defined by :math:p_im^n for any integer + :math:n. + + +.. class:: logarithmic(tickpreexps=None, labelpreexps=None, extendtick=0, extendlabel=None, epsilon=1e-10) + + Instances of this class creates tick lists suitable to logarithmic axes. The + positions of the ticks, subticks, subsubticks *etc.* are defined by the first, + second, third *etc.* item of the list *tickpreexps*, which are all + :class:preexp instances. + + *labelpreexps* works equally for placing labels. When *labelpreexps* is kept + None, labels will be placed at each tick position, but sublabels *etc.* will + not be used. This copy behaviour is also available *vice versa* and can be + disabled by an empty list. + + *extendtick*, *extendlabel* and *epsilon* have the same meaning as in + :class:linear. + +Some :class:preexp instances for the use in :class:logarithmic are available +as instance variables (should be used read-only): + + +.. attribute:: logarithmic.pre1exp5 + + preexp([tick.rational((1, 1))], 100000) + + +.. attribute:: logarithmic.pre1exp4 + + preexp([tick.rational((1, 1))], 10000) + + +.. attribute:: logarithmic.pre1exp3 + + preexp([tick.rational((1, 1))], 1000) + + +.. attribute:: logarithmic.pre1exp2 + + preexp([tick.rational((1, 1))], 100) + + +.. attribute:: logarithmic.pre1exp + + preexp([tick.rational((1, 1))], 10) + + +.. attribute:: logarithmic.pre125exp + + preexp([tick.rational((1, 1)), tick.rational((2, 1)), tick.rational((5, 1))], + 10) + + +.. attribute:: logarithmic.pre1to9exp + + preexp([tick.rational((1, 1)) for x in range(1, 10)], 10) + + +.. class:: log(...) + + This class is an abbreviation of :class:logarithmic described above. + + +.. class:: autologarithmic(variants=defaultvariants, extendtick=0, extendlabel=None, epsilon=1e-10) + + Instances of this class creates tick lists suitable to logarithmic axes, where + the distance between the ticks is adjusted to the range of the axis + automatically. Variants are a list of tuples with possible choices for + *tickpreexps* and *labelpreexps* of :class:logarithmic. *variants* should be + ordered that way, that the number of ticks for a given range will decrease + within the *variants* list. + + *extendtick*, *extendlabel* and *epsilon* have the same meaning as in + :class:linear. + + +.. attribute:: autologarithmic.defaultvariants + + [([log.pre1exp, log.pre1to9exp], [log.pre1exp, log.pre125exp]), ([log.pre1exp, + log.pre1to9exp], None), ([log.pre1exp2, log.pre1exp], None), ([log.pre1exp3, + log.pre1exp], None), ([log.pre1exp4, log.pre1exp], None), ([log.pre1exp5, + log.pre1exp], None)] + + +.. class:: autolog(...) + + This class is an abbreviation of :class:autologarithmic described above. + +.. % }}} + + +Module :mod:graph.axis.texter: Texter +======================================= + +.. module:: graph.axis.texter + :synopsis: Axes texters + + +.. % {{{ + +The following classes are part of the module :mod:graph.axis.texter. Instances +of the classes can be passed to the texter keyword argument of regular axes. +Texters are used to define the label text for ticks, which request to have a +label, but for which no label text has been specified so far. A typical case are +ticks created by partitioners described above. + + +.. class:: decimal(prefix="", infix="", suffix="", equalprecision=0, decimalsep=".", thousandsep="", thousandthpartsep="", plus="", minus="-", period=r"\\overline{%s}", labelattrs=[text.mathmode]) + + Instances of this class create decimal formatted labels. + + The strings *prefix*, *infix*, and *suffix* are added to the label at the + beginning, immediately after the plus or minus, and at the end, respectively. + *decimalsep*, *thousandsep*, and *thousandthpartsep* are strings used to + separate integer from fractional part and three-digit groups in the integer and + fractional part. The strings *plus* and *minus* are inserted in front of the + unsigned value for non-negative and negative numbers, respectively. + + The format string *period* should generate a period. It must contain one string + insert operators %s for the period. + + *labelattrs* is a list of attributes to be added to the label attributes given + in the painter. It should be used to setup TeX features like text.mathmode. + Text format options like text.size should instead be set at the painter. + + +.. class:: exponential(plus="", minus="-", mantissaexp=r"{{%s}\\cdot10^{%s}}", skipexp0=r"{%s}", skipexp1=None, nomantissaexp=r"{10^{%s}}", minusnomantissaexp=r"{-10^{%s}}", mantissamin=tick.rational((1, 1)), mantissamax=tick.rational((10L, 1)), skipmantissa1=0, skipallmantissa1=1, mantissatexter=decimal()) + + Instances of this class create decimal formatted labels with an exponential. + + The strings *plus* and *minus* are inserted in front of the unsigned value of + the exponent. + + The format string *mantissaexp* should generate the exponent. It must contain + two string insert operators %s, the first for the mantissa and the second + for the exponent. An alternative to the default is r"{{%s}{\rm e}{%s}}". + + The format string *skipexp0* is used to skip exponent 0 and must contain one + string insert operator %s for the mantissa. None turns off the special + handling of exponent 0. The format string *skipexp1* is similar to + *skipexp0*, but for exponent 1. + + The format string *nomantissaexp* is used to skip the mantissa 1 and must + contain one string insert operator %s for the exponent. None turns off + the special handling of mantissa 1. The format string *minusnomantissaexp* + is similar to *nomantissaexp*, but for mantissa -1. + + The :class:tick.rational instances *mantissamin*< *mantissamax* are minimum + (including) and maximum (excluding) of the mantissa. + + The boolean *skipmantissa1* enables the skipping of any mantissa equals 1 + and -1, when *minusnomantissaexp* is set. When the boolean + *skipallmantissa1* is set, a mantissa equals 1 is skipped only, when all + mantissa values are 1. Skipping of a mantissa is stronger than the skipping + of an exponent. + + *mantissatexter* is a texter instance for the mantissa. + + +.. class:: mixed(smallestdecimal=tick.rational((1, 1000)), biggestdecimal=tick.rational((9999, 1)), equaldecision=1, decimal=decimal(), exponential=exponential()) + + Instances of this class create decimal formatted labels with an exponential, + when the unsigned values are small or large compared to *1*. + + The rational instances *smallestdecimal* and *biggestdecimal* are the smallest + and biggest decimal values, where the decimal texter should be used. The sign of + the value is ignored here. For a tick at zero the decimal texter is considered + best as well. *equaldecision* is a boolean to indicate whether the decision for + the decimal or exponential texter should be done globally for all ticks. + + *decimal* and *exponential* are a decimal and an exponential texter instance, + respectively. + + +.. class:: rational(prefix="", infix="", suffix="", numprefix="", numinfix="", numsuffix="", denomprefix="", denominfix="", denomsuffix="", plus="", minus="-", minuspos=0, over=r"%s\\over%s", equaldenom=0, skip1=1, skipnum0=1, skipnum1=1, skipdenom1=1, labelattrs=[text.mathmode]) + + Instances of this class create labels formated as fractions. + + The strings *prefix*, *infix*, and *suffix* are added to the label at the + beginning, immediately after the plus or minus, and at the end, respectively. + The strings *numprefix*, *numinfix*, and *numsuffix* are added to the labels + numerator accordingly whereas *denomprefix*, *denominfix*, and *denomsuffix* do + the same for the denominator. + + The strings *plus* and *minus* are inserted in front of the unsigned value. The + position of the sign is defined by *minuspos* with values 1 (at the + numerator), 0 (in front of the fraction), and -1 (at the denominator). + + The format string *over* should generate the fraction. It must contain two + string insert operators %s, the first for the numerator and the second for + the denominator. An alternative to the default is "{{%s}/{%s}}". + + Usually, the numerator and denominator are canceled, while, when *equaldenom* is + set, the least common multiple of all denominators is used. + + The boolean *skip1* indicates, that only the prefix, plus or minus, the infix + and the suffix should be printed, when the value is 1 or -1 and at least + one of *prefix*, *infix* and *suffix* is present. + + The boolean *skipnum0* indicates, that only a 0 is printed when the + numerator is zero. + + *skipnum1* is like *skip1* but for the numerator. + + *skipdenom1* skips the denominator, when it is 1 taking into account + *denomprefix*, *denominfix*, *denomsuffix* *minuspos* and the sign of the + number. + + *labelattrs* has the same meaning as for *decimal*. + +.. % }}} + + +Module :mod:graph.axis.painter: Painter +========================================= + +.. module:: graph.axis.painter + :synopsis: Axes painters + + +.. % {{{ + +The following classes are part of the module :mod:graph.axis.painter. +Instances of the painter classes can be passed to the painter keyword argument +of regular axes. + + +.. class:: rotatetext(direction, epsilon=1e-10) + + This helper class is used in direction arguments of the painters below to + prevent axis labels and titles being written upside down. In those cases the + text will be rotated by 180 degrees. *direction* is an angle to be used relative + to the tick direction. *epsilon* is the value by which 90 degrees can be + exceeded before an 180 degree rotation is performed. + +The following two class variables are initialized for the most common +applications: + + +.. attribute:: rotatetext.parallel + + rotatetext(90) + + +.. attribute:: rotatetext.orthogonal + + rotatetext(180) + + +.. class:: ticklength(initial, factor) + + This helper class provides changeable PyX lengths starting from an initial value + *initial* multiplied by *factor* again and again. The resulting lengths are thus + a geometric series. + +There are some class variables initialized with suitable values for tick +stroking. They are named ticklength.SHORT, ticklength.SHORt, …, +ticklength.short, ticklength.normal, ticklength.long, …, +ticklength.LONG. ticklength.normal is initialized with a length of +0.12 and the reciprocal of the golden mean as factor whereas the others +have a modified initial value obtained by multiplication with or division by +appropriate multiples of :math:\sqrt{2}. + + +.. class:: regular(innerticklength=ticklength.normal, outerticklength=None, tickattrs=[], gridattrs=None, basepathattrs=[], labeldist="0.3 cm", labelattrs=[], labeldirection=None, labelhequalize=0, labelvequalize=1, titledist="0.3 cm", titleattrs=[], titledirection=rotatetext.parallel, titlepos=0.5, texrunner=None) + + Instances of this class are painters for regular axes like linear and + logarithmic axes. + + *innerticklength* and *outerticklength* are visual PyX lengths of the ticks, + subticks, subsubticks *etc.* plotted along the axis inside and outside of the + graph. Provide changeable attributes to modify the lengths of ticks compared to + subticks *etc.* None turns off the ticks inside and outside the graph, + respectively. + + *tickattrs* and *gridattrs* are changeable stroke attributes for the ticks and + the grid, where None turns off the feature. *basepathattrs* are stroke + attributes for the axis or None to turn it off. *basepathattrs* is merged + with [style.linecap.square]. + + *labeldist* is the distance of the labels from the axis base path as a visual + PyX length. *labelattrs* is a list of text attributes for the labels. It is + merged with [text.halign.center, text.vshift.mathaxis]. *labeldirection* is + an instance of *rotatetext* to rotate the labels relative to the axis tick + direction or None. + + The boolean values *labelhequalize* and *labelvequalize* force an equal + alignment of all labels for straight vertical and horizontal axes, respectively. + + *titledist* is the distance of the title from the rest of the axis as a visual + PyX length. *titleattrs* is a list of text attributes for the title. It is + merged with [text.halign.center, text.vshift.mathaxis]. *titledirection* is + an instance of *rotatetext* to rotate the title relative to the axis tick + direction or None. *titlepos* is the position of the title in graph + coordinates. + + *texrunner* is the texrunner instance to create axis text like the axis title or + labels. When not set the texrunner of the graph instance is taken to create the + text. + + +.. class:: linked(innerticklength=ticklength.short, outerticklength=None, tickattrs=[], gridattrs=None, basepathattrs=[], labeldist="0.3 cm", labelattrs=None, labeldirection=None, labelhequalize=0, labelvequalize=1, titledist="0.3 cm", titleattrs=None, titledirection=rotatetext.parallel, titlepos=0.5, texrunner=None) + + This class is identical to :class:regular up to the default values of + *labelattrs* and *titleattrs*. By turning off those features, this painter is + suitable for linked axes. + + +.. class:: bar(innerticklength=None, outerticklength=None, tickattrs=[], basepathattrs=[], namedist="0.3 cm", nameattrs=[], namedirection=None, namepos=0.5, namehequalize=0, namevequalize=1, titledist="0.3 cm", titleattrs=[], titledirection=rotatetext.parallel, titlepos=0.5, texrunner=None) + + Instances of this class are suitable painters for bar axes. + + *innerticklength* and *outerticklength* are visual PyX lengths to mark the + different bar regions along the axis inside and outside of the graph. None + turns off the ticks inside and outside the graph, respectively. *tickattrs* are + stroke attributes for the ticks or None to turn all ticks off. + + The parameters with prefix *name* are identical to their *label* counterparts in + :class:regular. All other parameters have the same meaning as in + :class:regular. + + +.. class:: linkedbar(innerticklength=None, outerticklength=None, tickattrs=[], basepathattrs=[], namedist="0.3 cm", nameattrs=None, namedirection=None, namepos=0.5, namehequalize=0, namevequalize=1, titledist="0.3 cm", titleattrs=None, titledirection=rotatetext.parallel, titlepos=0.5, texrunner=None) + + This class is identical to :class:bar up to the default values of *nameattrs* + and *titleattrs*. By turning off those features, this painter is suitable for + linked bar axes. + + +.. class:: split(breaklinesdist="0.05 cm", breaklineslength="0.5 cm", breaklinesangle=-60, titledist="0.3 cm", titleattrs=[], titledirection=rotatetext.parallel, titlepos=0.5, texrunner=None) + + Instances of this class are suitable painters for split axes. + + *breaklinesdist* and *breaklineslength* are the distance between axes break + markers in visual PyX lengths. *breaklinesangle* is the angle of the axis break + marker with respect to the base path of the axis. All other parameters have the + same meaning as in :class:regular. + + +.. class:: linkedsplit(breaklinesdist="0.05 cm", breaklineslength="0.5 cm", breaklinesangle=-60, titledist="0.3 cm", titleattrs=None, titledirection=rotatetext.parallel, titlepos=0.5, texrunner=None) + + This class is identical to :class:split up to the default value of + *titleattrs*. By turning off this feature, this painter is suitable for linked + split axes. + +.. % }}} + + +Module :mod:graph.axis.rater: Rater +===================================== + +.. module:: graph.axis.rater + :synopsis: Axes raters + + +.. % {{{ + +The rating of axes is implemented in :mod:graph.axis.rater. When an axis +partitioning scheme returns several partitioning possibilities, the partitions +need to be rated by a positive number. The axis partitioning rated lowest is +considered best. + +The rating consists of two steps. The first takes into account only the number +of ticks, subticks, labels and so on in comparison to optimal numbers. +Additionally, the extension of the axis range by ticks and labels is taken into +account. This rating leads to a preselection of possible partitions. In the +second step, after the layout of preferred partitionings has been calculated, +the distance of the labels in a partition is taken into account as well at a +smaller weight factor by default. Thereby partitions with overlapping labels +will be rejected completely. Exceptionally sparse or dense labels will receive a +bad rating as well. + + +.. class:: cube(opt, left=None, right=None, weight=1) + + Instances of this class provide a number rater. *opt* is the optimal value. When + not provided, *left* is set to 0 and *right* is set to 3*opt. Weight is + a multiplicator to the result. + + The rater calculates width*((x-opt)/(other-opt))**3 to rate the value x, + where other is *left* (x<*opt*) or *right* (x>*opt*). + + +.. class:: distance(opt, weight=0.1) + + Instances of this class provide a rater for a list of numbers. The purpose is to + rate the distance between label boxes. *opt* is the optimal value. + + The rater calculates the sum of weight*(opt/x-1) (x<*opt*) or + weight*(x/opt-1) (x>*opt*) for all elements x of the list. It + returns this value divided by the number of elements in the list. + + +.. class:: rater(ticks, labels, range, distance) + + Instances of this class are raters for axes partitionings. + + *ticks* and *labels* are both lists of number rater instances, where the first + items are used for the number of ticks and labels, the second items are used for + the number of subticks (including the ticks) and sublabels (including the + labels) and so on until the end of the list is reached or no corresponding ticks + are available. + + *range* is a number rater instance which rates the range of the ticks relative + to the range of the data. + + *distance* is an distance rater instance. + + +.. class:: linear(ticks=[cube(4), cube(10, weight=0.5)], labels=[cube(4)], range=cube(1, weight=2), distance=distance("1 cm")) + + This class is suitable to rate partitionings of linear axes. It is equal to + :class:rater but defines predefined values for the arguments. + + +.. class:: lin(...) + + This class is an abbreviation of :class:linear described above. + + +.. class:: logarithmic(ticks=[cube(5, right=20), cube(20, right=100, weight=0.5)], labels=[cube(5, right=20), cube(5, right=20, weight=0.5)], range=cube(1, weight=2), distance=distance("1 cm")) + + This class is suitable to rate partitionings of logarithmic axes. It is equal to + :class:rater but defines predefined values for the arguments. + + +.. class:: log(...) + + This class is an abbreviation of :class:logarithmic described above. + +.. % }}} + + +Module :mod:graph.axis.positioner: Positioners +================================================ + +.. module:: graph.axis.positioners + :synopsis: Axes positioners + + +.. % {{{ + +The position of an axis is defined by an instance of a class providing the +following methods: + + +.. class:: positioner() + + DUMMY + + +.. method:: positioner.vbasepath(v1=None, v2=None) + + Returns a path instance for the base path. *v1* and *v2* define the axis range + in graph coordinates the base path should cover. + + +.. method:: positioner.vgridpath(v) + + Returns a path instance for the grid path at position *v* in graph coordinates. + The method might return None when no grid path is available (for an axis + along a path for example). + + +.. method:: positioner.vtickpoint_pt(v) + + Returns the position of *v* in graph coordinates as a tuple (x, y) in + points. + + +.. method:: positioner.vtickdirection(v) + + Returns the direction of a tick at *v* in graph coordinates as a tuple (dx, + dy). The tick direction points inside of the graph. + +The module contains several implementations of those positioners, but since the +positioner instances are created by graphs etc. as needed, the details are not +interesting for the average PyX user. + +.. % }}} % }}} +.. % vim:fdm=marker + Added: trunk/pyx/manual/bbox.rst =================================================================== --- trunk/pyx/manual/bbox.rst (rev 0) +++ trunk/pyx/manual/bbox.rst 2011-05-20 08:00:48 UTC (rev 3141) @@ -0,0 +1,87 @@ + +*********** +Module bbox +*********** + +.. _bbox: + +The bbox module contains the definition of the bbox class representing +bounding boxes of graphical elements like paths, canvases, etc. used in PyX. +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 +================ + +The bbox constructor accepts the following keyword arguments + ++---------+-----------------------------------------------+ +| keyword | description | ++=========+===============================================+ +| llx | None (default) for :math:-\infty or | +| | :math:x\ -position of the lower left corner | +| | of the bbox (in user units) | ++---------+-----------------------------------------------+ +| lly | None (default) for :math:-\infty or | +| | :math:y\ -position of the lower left corner | +| | of the bbox (in user units) | ++---------+-----------------------------------------------+ +| urx | None (default) for :math:\infty or | +| | :math:x\ -position of the upper right | +| | corner of the bbox (in user units) | ++---------+-----------------------------------------------+ +| ury | None (default) for :math:\infty or | +| | :math:y\ -position of the upper right | +| | corner of the bbox (in user units) | ++---------+-----------------------------------------------+ + + +bbox methods +============ + ++-------------------------------------------+-----------------------------------------------+ +| bbox method | function | ++===========================================+===============================================+ +| intersects(other) | returns 1 if the bbox instance and | +| | other intersect with each other. | ++-------------------------------------------+-----------------------------------------------+ +| transformed(self, trafo) | returns self transformed by | +| | transformation trafo. | ++-------------------------------------------+-----------------------------------------------+ +| enlarged(all=0, bottom=None, left=None, | return the bounding box enlarged by the given | +| top=None, right=None) | amount (in visual units). all is the | +| | default for all other directions, which is | +| | used whenever None is given for the | +| | corresponding direction. | ++-------------------------------------------+-----------------------------------------------+ +| path() or rect() | return the path corresponding to the | +| | bounding box rectangle. | ++-------------------------------------------+-----------------------------------------------+ +| height() | returns the height of the bounding box (in | +| | PyX lengths). | ++-------------------------------------------+-----------------------------------------------+ +| width() | returns the width of the bounding box (in PyX | +| | lengths). | ++-------------------------------------------+-----------------------------------------------+ +| top() | returns the :math:y\ -position of the top | +| | of the bounding box (in PyX lengths). | ++-------------------------------------------+-----------------------------------------------+ +| bottom() | returns the :math:y\ -position of the | +| | bottom of the bounding box (in PyX lengths). | ++-------------------------------------------+-----------------------------------------------+ +| left() | returns the :math:x\ -position of the left | +| | side of the bounding box (in PyX lengths). | ++-------------------------------------------+-----------------------------------------------+ +| right() | returns the :math:x\ -position of the right | +| | side of the bounding box (in PyX lengths). | ++-------------------------------------------+-----------------------------------------------+ + +Furthermore, two bounding boxes can be added (giving the bounding box enclosing +both) and multiplied (giving the intersection of both bounding boxes). + +.. % %% Local Variables: +.. % %% mode: latex +.. % %% TeX-master: "manual.tex" +.. % %% End: + Added: trunk/pyx/manual/bitmap.rst =================================================================== --- trunk/pyx/manual/bitmap.rst (rev 0) +++ trunk/pyx/manual/bitmap.rst 2011-05-20 08:00:48 UTC (rev 3141) @@ -0,0 +1,137 @@ + +******* +Bitmaps +******* + + +Introduction +============ + +PyX focuses on the creation of scaleable vector graphics. However, PyX also +allows for the output of bitmap images. Still, the support for creation and +handling of bitmap images is quite limited. On the other hand the interfaces are +built that way, that its trivial to combine PyX with the "Python Image Library", +also known as "PIL". + +The creation of a bitmap can be performed out of some unpacked binary data by +first creating image instances:: + + from pyx import * + image_bw = bitmap.image(2, 2, "L", "\0\377\377\0") + image_rgb = bitmap.image(3, 2, "RGB", "\77\77\77\177\177\177\277\277\277" + "\377\0\0\0\377\0\0\0\377") + +Now image_bw is a :math:2\times2 grayscale image. The bitmap data is +provided by a string, which contains two black ("\0" == chr(0)) and two +white ("\377" == chr(255)) pixels. Currently the values per (colour) channel +is fixed to 8 bits. The coloured image image_rgb has :math:3\times2 pixels +containing a row of 3 different gray values and a row of the three colours red, +green, and blue. + +The images can then be wrapped into bitmap instances by:: + + bitmap_bw = bitmap.bitmap(0, 1, image_bw, height=0.8) + bitmap_rgb = bitmap.bitmap(0, 0, image_rgb, height=0.8) + +When constructing a bitmap instance you have to specify a certain position +by the first two arguments fixing the bitmaps lower left corner. Some optional +arguments control further properties. Since in this example there is no +information about the dpi-value of the images, we have to specify at least a +width or a height of the bitmap. + +The bitmaps are now to be inserted into a canvas:: + + c = canvas.canvas() + c.insert(bitmap_bw) + c.insert(bitmap_rgb) + c.writeEPSfile("bitmap") + +Figure :ref:fig:bitmap shows the resulting output. + +.. % DUMMY +.. _fig_label: +.. figure:: bitmap.* + :align: center + + +.. centered:: An introductory bitmap example. + + +Bitmap module +============= + +.. module:: bitmap + :synopsis: Bitmap support + + + +.. class:: image(width, height, mode, data, compressed=None) + + This class is a container for image data. *width* and *height* are the size of + the image in pixel. *mode* is one of "L", " RGB" or "CMYK" for + grayscale, rgb, or cmyk colours, respectively. *data* is the bitmap data as a + string, where each single character represents a colour value with ordinal range + 0 to 255. Each pixel is described by the appropriate number of colour + components according to *mode*. The pixels are listed row by row one after the + other starting at the upper left corner of the image. + + *compressed* might be set to " Flate" or "DCT" to provide already + compressed data. Note that those data will be passed to PostScript without + further checks, *i.e.* this option is for experts only. + + +.. class:: jpegimage(file) + + This class is specialized to read data from a JPEG/JFIF-file. *file* is either + an open file handle (it only has to provide a :meth:read method; the file + should be opened in binary mode) or a string. In the latter case + :class:jpegimage will try to open a file named like *file* for reading. + + The contents of the file is checked for some JPEG/JFIF format markers in order + to identify the size and dpi resolution of the image for further usage. These + checks will typically fail for invalid data. The data are not uncompressed, but + directly inserted into the output stream (for invalid data the result will be + invalid PostScript). Thus there is no quality loss by recompressing the data as + it would occur when recompressing the uncompressed stream with the lossy jpeg + compression method. + + +.. class:: bitmap(xpos, ypos, image, width=None, height=None, ratio=None, storedata=0, maxstrlen=4093, compressmode="Flate", flatecompresslevel=6, dctquality=75, dctoptimize=1, dctprogression=0) + + *xpos* and *ypos* are the position of the lower left corner of the image. This + position might be modified by some additional transformations when inserting the + bitmap into a canvas. *image* is an instance of :class:image or + :class:jpegimage but it can also be an image instance from the "Python Image + Library". + + *width*, *height*, and *ratio* adjust the size of the image. At least *width* or + *height* needs to be given, when no dpi information is available from *image*. + + *storedata* is a flag indicating, that the (still compressed) image data should + be put into the printers memory instead of writing it as a stream into the + PostScript file. While this feature consumes memory of the PostScript + interpreter, it allows for multiple usage of the image without including the + image data several times in the PostScript file. + + *maxstrlen* defines a maximal string length when *storedata* is enabled. Since + the data must be kept in the PostScript interpreters memory, it is stored in + strings. While most interpreters do not allow for an arbitrary string length (a + common limit is 65535 characters), a limit for the string length is set. When + more data need to be stored, a list of strings will be used. Note that lists are + also subject to some implementation limits. Since a typical value is 65535 + entries, in combination a huge amount of memory can be used. + + Valid values for *compressmode* currently are "Flate" (zlib compression), + "DCT" (jpeg compression), or None (disabling the compression). The zlib + compression makes use of the zlib module as it is part of the standard Python + distribution. The jpeg compression is available for those *image* instances + only, which support the creation of a jpeg-compressed stream, *e.g.* images from + the "Python Image Library" with jpeg support installed. The compression must be + disabled when the image data is already compressed. + + *flatecompresslevel* is a parameter of the zlib compression. *dctquality*, + *dctoptimize*, and *dctprogression* are parameters of the jpeg compression. + Note, that the progression feature of the jpeg compression should be turned off + in order to produce valid PostScript. Also the optimization feature is known to + produce errors on certain printers. + Added: trunk/pyx/manual/box.rst =================================================================== --- trunk/pyx/manual/box.rst (rev 0) +++ trunk/pyx/manual/box.rst 2011-05-20 08:00:48 UTC (rev 3141) @@ -0,0 +1,112 @@ + +.. _module:box: + +******************************* +Module box: convex box handling +******************************* + +This module has a quite internal character, but might still be useful from the +users point of view. It might also get further enhanced to cover a broader range +of standard arranging problems. + +In the context of this module a box is a convex polygon having optionally a +center coordinate, which plays an important role for the box alignment. The +center might not at all be central, but it should be within the box. The +convexity is necessary in order to keep the problems to be solved by this module +quite a bit easier and unambiguous. + +Directions (for the alignment etc.) are usually provided as pairs (dx, dy) +within this module. It is required, that at least one of these two numbers is +unequal to zero. No further assumptions are taken. + + +Polygon +======= + +A polygon is the most general case of a box. It is an instance of the class +polygon. The constructor takes a list of points (which are (x, y) tuples) in +the keyword argument corners and optionally another (x, y) tuple as the +keyword argument center. The corners have to be ordered counterclockwise. In +the following list some methods of this polygon class are explained: + +path(centerradius=None, bezierradius=None, beziersoftness=1): + returns a path of the box; the center might be marked by a small circle of + radius centerradius; the corners might be rounded using the parameters + bezierradius and beziersoftness. For each corner of the box there may be + one value for beziersoftness and two bezierradii. For convenience, it is not + necessary to specify the whole list (for beziersoftness) and the whole list of + lists (bezierradius) here. You may give a single value and/or a 2-tuple instead. + +transform(*trafos): + performs a list of transformations to the box + +reltransform(*trafos): + performs a list of transformations to the box relative to the box center + + .. % DUMMY +.. _fig_label: +.. figure:: boxalign.* + :align: center + + + .. centered:: circle and line alignment examples (equal direction and distance) + +circlealignvector(a, dx, dy): + returns a vector (a tuple (x, y)) to align the box at a circle with radius a + in the direction (dx, dy); see figure :ref:fig:boxalign + +linealignvector(a, dx, dy): + as above, but align at a line with distance a + +circlealign(a, dx, dy): + as circlealignvector, but perform the alignment instead of returning the vector + +linealign(a, dx, dy): + as linealignvector, but perform the alignment instead of returning the vector + +extent(dx, dy): + extent of the box in the direction (dx, dy) + +pointdistance(x, y): + distance of the point (x, y) to the box; the point must be outside of + the box + +boxdistance(other): + distance of the box to the box other; when the boxes are overlapping, + BoxCrossError is raised + +bbox(): + returns a bounding box instance appropriate to the box + + +Functions working on a box list +=============================== + +circlealignequal(boxes, a, dx, dy): + Performs a circle alignment of the boxes boxes using the parameters a, + dx, and dy as in the circlealign method. For the length of the + alignment vector its largest value is taken for all cases. + +linealignequal(boxes, a, dx, dy): + as above, but performing a line alignment + +tile(boxes, a, dx, dy): + tiles the boxes boxes with a distance a between the boxes (in addition + the maximal box extent in the given direction (dx, dy) is taken into + account) + + +Rectangular boxes +================= + +For easier creation of rectangular boxes, the module provides the specialized +class rect. Its constructor first takes four parameters, namely the x, y +position and the box width and height. Additionally, for the definition of the +position of the center, two keyword arguments are available. The parameter +relcenter takes a tuple containing a relative x, y position of the center +(they are relative to the box extent, thus values between 0 and 1 should +be used). The parameter abscenter takes a tuple containing the x and y +position of the center. This values are measured with respect to the lower left +corner of the box. By default, the center of the rectangular box is set to this +lower left corner. + Added: trunk/pyx/manual/canvas.rst =================================================================== --- trunk/pyx/manual/canvas.rst (rev 0) +++ trunk/pyx/manual/canvas.rst 2011-05-20 08:00:48 UTC (rev 3141) @@ -0,0 +1,156 @@ + +.. _canvas: + +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. + +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.. + +.. module:: canvas + + + +Class :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. + + +.. class:: canvas(attrs=[], texrunner=None) + + Construct a new canvas, applying the given *attrs*, which can be instances of + :class:trafo.trafo, :class:canvas.clip, :class:style.strokestyle or + :class:style.fillstyle. The *texrunner* argument can be used to specify the + texrunner instance used for the :meth:text method of the canvas. If not + specified, it defaults to *text.defaulttexrunner*. + +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*. + + +.. method:: canvas.fill(path, attrs=[]) + + Fills the given *path* on the canvas applying the given *attrs*. + + +.. method:: canvas.stroke(path, attrs=[]) + + Strokes the given *path* on the canvas applying the given *attrs*. + +Arbitrary allowed elements like other :class:canvas instances can be inserted +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. + +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))). + +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. + +A canvas also allows one 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. + + +.. method:: canvas.writeEPSfile(file, *args, **kwargs) + + Writes the canvas to *file* using the EPS format. *file* either has to provide a + 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 + of this :class:document.document instance passing the *file*. + + +.. method:: canvas.writePSfile(file, *args, **kwargs) + + Similar to :meth:writeEPSfile but using the PS format. + + +.. method:: canvas.writePDFfile(file, *args, **kwargs) + + Similar to :meth:writeEPSfile but using the PDF format. + + +.. method:: canvas.writetofile(filename, *args, **kwargs) + + Determine the file type (EPS, PS, or PDF) from the file extension of *filename* + and call the corresponding write method with the given arguments *arg* and + *kwargs*. + + +.. 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 + 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 + is written to stdout. *device* specifies a ghostscript output device by a + string. Depending on your 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. + + *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). + + *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 + gain access to the :class:document.page constructor arguments. + +For more information about the possible arguments of the :class:document.page +constructor, we refer to Sect. :ref:document. + +.. % %% Local Variables: +.. % %% mode: latex +.. % %% TeX-master: "manual.tex" +.. % %% End: + Added: trunk/pyx/manual/color.rst =================================================================== --- trunk/pyx/manual/color.rst (rev 0) +++ trunk/pyx/manual/color.rst 2011-05-20 08:00:48 UTC (rev 3141) @@ -0,0 +1,116 @@ + +.. _color: + +************ +Module color +************ + + +Color models +============ + +PostScript provides different color models. They are available to PyX by +different color classes, which just pass the colors down to the PostScript +level. This implies, that there are no conversion routines between different +color models available. However, some color model conversion routines are +included in Python's standard library in the module colorsym. Furthermore +also the comparison of colors within a color model is not supported, but might +be added in future versions at least for checking color identity and for +ordering gray colors. + +There is a class for each of the supported color models, namely gray, +rgb, cmyk, and hsb. The constructors take variables appropriate for +the color model. Additionally, a list of named colors is given in appendix +:ref:colorname. + + +Example +======= + + :: + + from pyx import * + + c = canvas.canvas() + + c.fill(path.rect(0, 0, 7, 3), [color.gray(0.8)]) + c.fill(path.rect(1, 1, 1, 1), [color.rgb.red]) + c.fill(path.rect(3, 1, 1, 1), [color.rgb.green]) + c.fill(path.rect(5, 1, 1, 1), [color.rgb.blue]) + + c.writeEPSfile("color") + + +The file color.eps is created and looks like: + + .. % DUMMY +.. _fig_label: +.. figure:: color.* + :align: center + + + +Color gradients +=============== + +The color module provides a class gradient for continous transitions between +colors. A list of named gradients is available in appendix :ref:gradientname. + + +.. class:: gradient(min=0, max=1) + + This class provides the methods for the gradient. Different initializations + can be found in lineargradient and functiongradient. + + *min* and *max* provide the valid range of the arguments for getcolor. + + + .. function:: getcolor(parameter) + + Returns the color that corresponds to *parameter* (must be between *min* and + *max*). + + + .. function:: select(index, n_indices) + + When a total number of *n_indices* different colors is needed from the gradient, + this method returns the *index*-th color. + + +.. class:: lineargradient(startcolor, endcolor, min=0, max=1) + + This class provides a linear transition between two given colors. The linear + interpolation is performed on the color components of the specific color model. + + *startcolor* and *endcolor* must be colors of the same color model. + + +.. class:: functiongradient(functions, type, min=0, max=1) + + This class provides an arbitray transition between colors of the same color + model. + + *type* is a string indicating the color model (one of "cmyk", "rgb", + "hsb", "grey") + + *functions* is a dictionary that maps the color components onto given functions. + E.g. for type="rgb" this dictionary must have the keys "r", "g", and + "b". + + +Transparency +============ + + +.. class:: transparency(value) + + Instances of this class will make drawing operations (stroking, filling) to + become partially transparent. *value* defines the transparency factor in the + range 0 (opaque) to 1 (transparent). + + Transparency is available in PDF output only since it is not supported by + PostScript. However, for certain ghostscript devices (for example the pdf + backend as used by ps2pdf) proprietary PostScript extension allows for + transparency in PostScript code too. PyX creates such PostScript proprietary + code, but issues a warning when doing so. + Added: trunk/pyx/manual/colorname.rst =================================================================== --- trunk/pyx/manual/colorname.rst (rev 0) +++ trunk/pyx/manual/colorname.rst 2011-05-20 08:00:48 UTC (rev 3141) @@ -0,0 +1,12 @@ + +.. _colorname: + +************ +Named colors +************ + +.. % DUMMY +.. _fig_label: +.. figure:: colorname.* + :align: center + Added: trunk/pyx/manual/connector.rst =================================================================== --- trunk/pyx/manual/connector.rst (rev 0) +++ trunk/pyx/manual/connector.rst 2011-05-20 08:00:48 UTC (rev 3141) @@ -0,0 +1,88 @@ + +.. _connector: + +*********************** +Module :mod:connector +*********************** + +This module provides classes for connecting two :class:box\ -instances with +lines, arcs or curves. All constructors of the following connector-classes take +two :class:box\ -instances as the two first arguments. They return a +connecting path from the first to the second box. The overall geometry of the +path is such that is starts/ends at the boxes' centers. It is then cut by the +boxes' outlines. The resulting :class:connector will additionally be shortened +by lengths given in the :keyword:boxdists\ -keyword (a list of two lengths, +default [0,0]). + +Angle keywords can be either absolute or relative. The absolute angles refer to +the angle between x-axis and the running tangent of the connector, while the +relative angles are between the direct connecting line of the box-centers and +the running tangent (see figure. :ref:fig:connector). + +The bulge-keywords parameterize the deviation of the connector from the +connecting line. It has different meanings for different connectors (see figure. +:ref:fig:connector). + + +Class :class:line +=================== + +The constructor of the :class:line class accepts only boxes and the +:keyword:boxdists\ -keyword. + + +Class :class:arc +================== + +The constructor takes either the :keyword:relangle\ -keyword or a combination +of :keyword:relbulge and :keyword:absbulge. The "bulge" is meant to be a +hint for the greatest distance between the connecting arc and the straight +connection between the box-centers. (Default: relangle=45, +relbulge=None, absbulge=None) + +Note that the bulge-keywords override the angle-keyword. + +If both :keyword:relbulge and :keyword:absbulge are given, they will be +added. + + +Class :class:curve +==================== + +The constructor takes both angle- and bulge-keywords. Here, the bulges are used +as distances between the control points of the cubic Beziér-curve. For the signs +of the angle- and bulge-keywords refer to figure :ref:fig:connector. + +:keyword:absangle1 or :keyword:relangle1 --- :keyword:absangle2 or +:keyword:relangle2, where the absolute angle overrides the relative if both +are given. (Default: relangle1=45, relangle2=45, absangle1=None, +absangle2=None) + +:keyword:absbulge and :keyword:relbulge, where they will be added if both +are given. --- (Default: absbulge=None, relbulge=0.39; these default +values produce output similar to the defaults of :class:arc.) + +.. % DUMMY +.. _fig_label: +.. figure:: connector.* + :align: center + + +.. centered:: The angle-parameters of the connector.arc (left panel) and the connector.curve (right panel) classes. + + +Class :class:twolines +======================= + +This class returns two connected straight lines. There is a vast variety of +combinations for angle- and length-keywords. The user has to make sure to +provide a non-ambiguous set of keywords: + +:keyword:absangle1 or :keyword:relangle1 for the first angle, --- +:keyword:relangleM for the middle angle and --- :keyword:absangle2 or +:keyword:relangle2 for the ending angle. Again, the absolute angle overrides +the relative if both are given. (Default: all five angles are None) + +:keyword:length1 and :keyword:length2 for the lengths of the connecting +lines. (Default: None) + Added: trunk/pyx/manual/deformer.rst =================================================================== --- trunk/pyx/manual/deformer.rst (rev 0) +++ trunk/pyx/manual/deformer.rst 2011-05-20 08:00:48 UTC (rev 3141) @@ -0,0 +1,140 @@ + +.. _deformer: + +Module :mod:deformer +====================== + +.. module:: deformer + :synopsis: 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. + +All classes of the :mod:deformer module provide the following methods: + + +.. class:: deformer() + + DUMMY + + +.. method:: deformer.__call__((specific parameters for the class)) + + Returns a deformer with modified parameters + + +.. method:: deformer.deform(path) + + Returns the deformed normpath on the basis of the *path*. This method allows + using the deformers outside of a drawing call. + +The deformer classes are the following: + + +.. class:: cycloid(radius, halfloops=10, skipfirst=1*unit.t_cm, skiplast=1*unit.t_cm, curvesperhloop=3, sign=1, turnangle=45) + + This deformer creates a cycloid around a path. The outcome looks similar to a 3D + spring stretched along the original path. + + *radius*: the radius of the cycloid (this is the radius of the 3D spring) + + *halfloops*: the number of half-loops of the cycloid + + *skipfirst* and *skiplast*: the lengths on the original path not to be bent to a + cycloid + + *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. + + *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. + + +.. 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! + 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* + 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 + in a *geometrically smooth* way. Path elements that are shorter than + *radius*:math:\times*relskipthres* are ignored. + + The new curve smoothing the corner consists either of one or of two Bezier + curves, depending on the surrounding path elements. If there are straight lines + before and after the new curve, then two Bezier curves are used. This optimises + the bending of curves in rectangular boxes or polygons. Here, the curves have an + additional degree of freedom that can be set with *softness* :math:\in(0,1]. + If one of the concerned path elements is curved, only one Bezier curve is used + that is (not always uniquely) determined by its geometrical constraints. There + are, nevertheless, some *caveats*: + + A curve that strictly obeys the sign and magnitude of the curvature might not + look very smooth in some cases. Especially when connecting a curved with a + straight piece, the smoothed path contains unwanted overshootings. To prevent + this, the parameter default *obeycurv=0* releases the curvature constraints a + little: The curvature may then change its sign (still looks smooth for human + eyes) or, in more extreme cases, even its magnitude (does not look so smooth). + If you really need a geometrically smooth path on the basis of Bezier curves, + then set *obeycurv=1*. + + +.. class:: parallel(distance, relerr=0.05, sharpoutercorners=0, dointersection=1, checkdistanceparams=[0.5], lookforcurvatures=11) + + This deformer creates a parallel curve to a given path. The result is similar to + what is usually referred to as the *set with constant distance* to the set of + points on the path. It differs in one important respect, because the *distance* + parameter in the deformer is a signed distance. The resulting parallel normpath + is constructed on the level of the original pathitems. For each of them a + parallel pathitem is constructed. Then, they are connected by circular arcs (or + by sharp edges) around the corners of the original path. Later, everything that + is nearer to the original path than distance is cut away. + + .. % + + There are some caveats: + +* When the original path is too curved then the parallel path would contain + 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. + + 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. + + *sharpoutercorners* connects the parallel pathitems by wegde build 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 + + *lookforcurvatures* is the number of points per normpathitem where its curvature + is checked for critical values + +.. % %% Local Variables: +.. % %% mode: latex +.. % %% TeX-master: "manual.tex" +.. % %% ispell-dictionary: "british" +.. % %% End: + Added: trunk/pyx/manual/document.rst =================================================================== --- trunk/pyx/manual/document.rst (rev 0) +++ trunk/pyx/manual/document.rst 2011-05-20 08:00:48 UTC (rev 3141) @@ -0,0 +1,119 @@ + +.. _document: + +Module :mod:document +====================== + +.. sectionauthor:: Jörg Lehmann + + +.. module:: document + + +The document module contains two classes: :class:document and :class:page. A +:class:document consists of one or several :class:page\ s. + + +Class :class:page +------------------- + +A :class:page is a thin wrapper around a :class:canvas, which defines some +additional properties of the page. + + +.. class:: page(canvas, pagename=None, paperformat=None, rotated=0, centered=1, fittosize=0, margin=1 * unit.t_cm, bboxenlarge=1 * unit.t_pt, bbox=None) + + Construct a new :class:page from the given :class:canvas instance. A string + *pagename* and the *paperformat* can be defined. See below, for a list of known + paper formats. If *rotated* is set, the output is rotated by 90 degrees on the + page. If *centered* is set, the output is centered on the given paperformat. If + *fittosize* is set, the output is scaled to fill the full page except for a + given *margin*. Normally, the bounding box of the canvas is calculated + automatically from the bounding box of its elements. Alternatively, you may + specify the *bbox* manually. In any case, the bounding box is enlarged on all + sides by *bboxenlarge*. + + +Class :class:document +----------------------- + + +.. class:: document(pages=[]) + + Construct a :class:document consisting of a given list of *pages*. + +A :class:document can be written to a file using one of the following methods: + + +.. method:: document.writeEPSfile(file, title=None, strip_fonts=True, text_as_path=False, mesh_as_bitmap=False, mesh_as_bitmap_resolution=300) + + Write a single page :class:document to an EPS file. *title* is used as the + document title, *strip_fonts* enabled font stripping (removal of unused glyphs), + *text_as_path* converts all text to paths instead of using fonts in the output, + *mesh_as_bitmap* converts meshs (like 3d surface plots) to bitmaps (to reduce + complexity in the output) and *mesh_as_bitmap_resolution* is the resolution of + this conversion in dots per inch. + + +.. method:: document.writePSfile(file, writebbox=False, title=None, strip_fonts=True, text_as_path=False, mesh_as_bitmap=False, mesh_as_bitmap_resolution=300) + + Write :class:document to a PS file. *writebbox* add the page bounding boxes to + the output. All other parameters are identical to the :meth:writeEPSfile + method. + + +.. method:: document.writePDFfile(file, title=None, author=None, subject=None, keywords=None, fullscreen=False, writebbox=False, compress=True, compresslevel=6, strip_fonts=True, text_as_path=False, mesh_as_bitmap=False, mesh_as_bitmap_resolution=300) + + Write :class:document to a PDF file. *author*, *subject*, and *keywords* are + used for the document author, subject, and keyword information, respectively. + *fullscreen* enabled fullscreen mode when the document is opened, *writebbox* + enables writing of the crop box to each page, *compress* enables output stream + compression and *compresslevel* sets the compress level to be used (from 1 to + 9). All other parameters are identical to the :meth:writeEPSfile. + + +.. method:: document.writetofile(filename, *args, **kwargs) + + Determine the file type (EPS, PS, or PDF) from the file extension of *filename* + and call the corresponding write method with the given arguments *arg* and + *kwargs*. + + +Class :class:paperformat +-------------------------- + + +.. class:: paperformat(width, height, name=None) + + Define a :class:paperformat with the given *width* and *height* and the + optional *name*. + +Predefined paperformats are listed in the following table + ++--------------------------------------+--------+----------+---------+ +| instance | name | width | height | ++======================================+========+==========+=========+ +| :const:document.paperformat.A0 | A0 | 840 mm | 1188 mm | ++--------------------------------------+--------+----------+---------+ +| :const:document.paperformat.A0b | | 910 mm | 1370 mm | ++--------------------------------------+--------+----------+---------+ +| :const:document.paperformat.A1 | A1 | 594 mm | 840 mm | ++--------------------------------------+--------+----------+---------+ +| :const:document.paperformat.A2 | A2 | 420 mm | 594 mm | ++--------------------------------------+--------+----------+---------+ +| :const:document.paperformat.A3 | A3 | 297 mm | 420 mm | ++--------------------------------------+--------+----------+---------+ +| :const:document.paperformat.A4 | A4 | 210 mm | 297 mm | ++--------------------------------------+--------+----------+---------+ +| :const:document.paperformat.A5 | A5 | 148.5 mm | 210 mm | ++--------------------------------------+--------+----------+---------+ +| :const:document.paperformat.Letter | Letter | 8.5 inch | 11 inch | ++--------------------------------------+--------+----------+---------+ +| :const:document.paperformat.Legal | Legal | 8.5 inch | 14 inch | ++--------------------------------------+--------+----------+---------+ + +.. % %% Local Variables: +.. % %% mode: latex +.. % %% TeX-master: "manual.tex" +.. % %% End: + Added: trunk/pyx/manual/epsfile.rst =================================================================== --- trunk/pyx/manual/epsfile.rst (rev 0) +++ trunk/pyx/manual/epsfile.rst 2011-05-20 08:00:48 UTC (rev 3141) @@ -0,0 +1,67 @@ + +********************************** +Module epsfile: EPS file inclusion +********************************** + +With the help of the epsfile.epsfile class, you can easily embed another EPS +file in your canvas, thereby scaling, aligning the content at discretion. The +most simple example looks like + + :: + + from pyx import * + c = canvas.canvas() + c.insert(epsfile.epsfile(0, 0, "file.eps")) + c.writeEPSfile("output") + + +All relevant parameters are passed to the epsfile.epsfile constructor. They +are summarized in the following table: + ++---------------------+-----------------------------------------------+ +| argument name | description | ++=====================+===============================================+ +| x | :math:x\ -coordinate of position. | ++---------------------+-----------------------------------------------+ +| y | :math:y\ -coordinate of position. | ++---------------------+-----------------------------------------------+ +| filename | Name of the EPS file (including a possible | +| | extension). | ++---------------------+-----------------------------------------------+ +| width=None | Desired width of EPS graphics or None for | +| | original width. Cannot be combined with scale | +| | specification. | ++---------------------+-----------------------------------------------+ +| height=None | Desired height of EPS graphics or None | +| | for original height. Cannot be combined with | +| | scale specification. | ++---------------------+-----------------------------------------------+ +| scale=None | Scaling factor for EPS graphics or None | +| | for no scaling. Cannot be combined with width | +| | or height specification. | ++---------------------+-----------------------------------------------+ +| align="bl" | Alignment of EPS graphics. The first | +| | character specifies the vertical alignment: | +| | b for bottom, c for center, and t | +| | for top. The second character fixes the | +| | horizontal alignment: l for left, c | +| | for center r for right. | ++---------------------+-----------------------------------------------+ +| clip=1 | Clip to bounding box of EPS file? | ++---------------------+-----------------------------------------------+ +| translatebbox=1 | Use lower left corner of bounding box of EPS | +| | file? Set to :math:0 with care. | ++---------------------+-----------------------------------------------+ +| bbox=None | If given, use bbox instance instead of | +| | bounding box of EPS file. | ++---------------------+-----------------------------------------------+ +| kpsearch=0 | Search for file using the kpathsea library. | ++---------------------+-----------------------------------------------+ + +.. _epsfile: + +.. % %% Local Variables: +.. % %% mode: latex +.. % %% TeX-master: "manual.tex" +.. % %% End: + Added: trunk/pyx/manual/gradientname.rst =================================================================== --- trunk/pyx/manual/gradientname.rst (rev 0) +++ trunk/pyx/manual/gradientname.rst 2011-05-20 08:00:48 UTC (rev 3141) @@ -0,0 +1,12 @@ + +.. _gradientname: + +*************** +Named gradients +*************** + +.. % DUMMY +.. _fig_label: +.. figure:: gradientname.* + :align: center + Added: trunk/pyx/manual/graph.rst =================================================================== --- trunk/pyx/manual/graph.rst (rev 0) +++ trunk/pyx/manual/graph.rst 2011-05-20 08:00:48 UTC (rev 3141) @@ -0,0 +1,1223 @@ + +.. _graph: + +****** +Graphs +****** + + +Introduction +============ + +PyX can be used for data and function plotting. At present x-y-graphs and +x-y-z-graphs are supported only. However, the component architecture of the +graph system described in section :ref:graph:components allows for additional +graph geometries while reusing most of the existing components. + +.. % {{{ + +Creating a graph splits into two basic steps. First you have to create a graph +instance. The most simple form would look like:: + + from pyx import * + g = graph.graphxy(width=8) + +The graph instance g created in this example can then be used to actually +plot something into the graph. Suppose you have some data in a file +:file:graph.dat you want to plot. The content of the file could look like: + + +.. include:: ../includes/graph.dat + :literal: + +To plot these data into the graph g you must perform:: + + g.plot(graph.data.file("graph.dat", x=1, y=2)) + +The method :meth:plot takes the data to be plotted and optionally a list of +graph styles to be used to plot the data. When no styles are provided, a default +style defined by the data instance is used. For data read from a file by an +instance of :class:graph.data.file, the default are symbols. When +instantiating :class:graph.data.file, you not only specify the file name, but +also a mapping from columns to axis names and other information the styles might +make use of (*e.g.* data for error bars to be used by the errorbar style). + +While the graph is already created by that, we still need to perform a write of +the result into a file. Since the graph instance is a canvas, we can just call +its :meth:writeEPSfile method. :: + + g.writeEPSfile("graph") + +The result :file:graph.eps is shown in figure :ref:fig:graph. + +.. % DUMMY +.. _fig_label: +.. figure:: graph.* + :align: center + + +.. centered:: A minimalistic plot for the data from file :file:graph.dat. + +Instead of plotting data from a file, other data source are available as well. +For example function data is created and placed into :meth:plot by the +following line:: + + g.plot(graph.data.function("y(x)=x**2")) + +You can plot different data in a single graph by calling :meth:plot several +times before :meth:writeEPSfile or :meth:writePDFfile. Note that a calling +:meth:plot will fail once a graph was forced to "finish" itself. This happens +automatically, when the graph is written to a file. Thus it is not an option to +call :meth:plot after :meth:writeEPSfile or :meth:writePDFfile. The topic +of the finalization of a graph is addressed in more detail in section +:ref:graph:graph. As you can see in figure :ref:fig:graph2, a function is +plotted as a line by default. + +.. % DUMMY +.. _fig_label: +.. figure:: graph2.* + :align: center + + +.. centered:: Plotting data from a file together with a function. + +While the axes ranges got adjusted automatically in the previous example, they +might be fixed by keyword options in axes constructors. Plotting only a function +will need such a setting at least in the variable coordinate. The following code +also shows how to set a logathmic axis in y-direction: + + +.. include:: ../includes/graph3.py + :literal: + +The result is shown in figure :ref:fig:graph3. + +.. % DUMMY +.. _fig_label: +.. figure:: graph3.* + :align: center + + +.. centered:: Plotting a function for a given axis range and use a logarithmic y-axis. + + +Component architecture +====================== + +.. % {{{ + +.. _graph:components: + +Creating a graph involves a variety of tasks, which thus can be separated into +components without significant additional costs. This structure manifests itself +also in the PyX source, where there are different modules for the different +tasks. They interact by some well-defined interfaces. They certainly have to be +completed and stabilized in their details, but the basic structure came up in +the continuous development quite clearly. The basic parts of a graph are: + +graph + Defines the geometry of the graph by means of graph coordinates with range + [0:1]. Keeps lists of plotted data, axes *etc.* + +data + Produces or prepares data to be plotted in graphs. + +style + Performs the plotting of the data into the graph. It gets data, converts them + via the axes into graph coordinates and uses the graph to finally plot the data + with respect to the graph geometry methods. + +key + Responsible for the graph keys. + +axis + Creates axes for the graph, which take care of the mapping from data values to + graph coordinates. Because axes are also responsible for creating ticks and + labels, showing up in the graph themselves and other things, this task is + splitted into several independent subtasks. Axes are discussed separately in + chapter :ref:axis. + +.. % }}} + + +Module :mod:graph.graph: Graphs +================================= + +.. % {{{ + +.. _graph:graph: + +.. module:: graph.graph + :synopsis: Graph geometry + + +The classes :class:graphxy and :class:graphxyz are part of the module +:mod:graph.graph. However, there are shortcuts to access the classes via +graph.graphxy and graph.graphxyz, respectively. + + +.. class:: graphxy(xpos=0, ypos=0, width=None, height=None, ratio=goldenmean, key=None, backgroundattrs=None, axesdist=0.8*unit.v_cm, xaxisat=None, yaxisat=None, **axes) + + This class provides an x-y-graph. A graph instance is also a fully functional + canvas. + + The position of the graph on its own canvas is specified by *xpos* and *ypos*. + The size of the graph is specified by *width*, *height*, and *ratio*. These + parameters define the size of the graph area not taking into account the + additional space needed for the axes. Note that you have to specify at least + *width* or *height*. *ratio* will be used as the ratio between *width* and + *height* when only one of these is provided. + + *key* can be set to a :class:graph.key.key instance to create an automatic + graph key. None omits the graph key. + + *backgroundattrs* is a list of attributes for drawing the background of the + graph. Allowed are decorators, strokestyles, and fillstyles. None disables + background drawing. + + *axisdist* is the distance between axes drawn at the same side of a graph. + + *xaxisat* and *yaxisat* specify a value at the y and x axis, where the + corresponding axis should be moved to. It's a shortcut for corresonding calls of + :meth:axisatv described below. Moving an axis by *xaxisat* or *yaxisat* + disables the automatic creation of a linked axis at the opposite side of the + graph. + + *\*\*axes* receives axes instances. Allowed keywords (axes names) are x, + x2, x3, *etc.* and y, y2, y3, *etc.* When not providing an + x or y axis, linear axes instances will be used automatically. When not + providing a x2 or y2 axis, linked axes to the x and y axes are + created automatically and *vice versa*. As an exception, a linked axis is not + created automatically when the axis is placed at a specific position by + *xaxisat* or *yaxisat*. You can disable the automatic creation of axes by + setting the linked axes to None. The even numbered axes are plotted at the + top (x axes) and right (y axes) while the others are plotted at the + bottom (x axes) and left (y axes) in ascending order each. + +Some instance attributes might be useful for outside read-access. Those are: + + +.. attribute:: graphxy.axes + + A dictionary mapping axes names to the :class:anchoredaxis instances. + +To actually plot something into the graph, the following instance method +:meth:plot is provided: + + +.. method:: graphxy.plot(data, styles=None) + + Adds *data* to the list of data to be plotted. Sets *styles* to be used for + plotting the data. When *styles* is None, the default styles for the data as + provided by *data* is used. + + *data* should be an instance of any of the data described in section + :ref:graph:data. + + When the same combination of styles (*i.e.* the same references) are used + several times within the same graph instance, the styles are kindly asked by the + graph to iterate their appearance. Its up to the styles how this is performed. + + Instead of calling the plot method several times with different *data* but the + same style, you can use a list (or something iterateable) for *data*. + +While a graph instance only collects data initially, at a certain point it must +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: + + +.. method:: graphxy.dolayout() + + Fixes the layout of the graph. As part of this work, the ranges of the axes are + fitted to the data when the axes ranges are allowed to adjust themselves to the + data ranges. The other :meth:do\ -methods ensure, that this method is always + called first. + + +.. method:: graphxy.dobackground() + + Draws the background. + + +.. method:: graphxy.doaxes() + + Inserts the axes. + + +.. method:: graphxy.doplotitem(plotitem) + + Plots the plotitem as returned by the graphs plot method. + + +.. method:: graphxy.doplot() + + Plots all (remaining) plotitems. + + +.. method:: graphxy.dokeyitem() + + Inserts a plotitem in the graph key as returned by the graphs plot method. + + +.. method:: graphxy.dokey() + + Inserts the graph key. + + +.. method:: graphxy.finish() + + Finishes the graph by calling all pending :meth:do\ -methods. This is done + automatically, when the output is created. + +The graph provides some methods to access its geometry: + + +.. method:: graphxy.pos(x, y, xaxis=None, yaxis=None) + + Returns the given point at *x* and *y* as a tuple (xpos, ypos) at the graph + canvas. *x* and *y* are anchoredaxis instances for the two axes *xaxis* and + *yaxis*. When *xaxis* or *yaxis* are None, the axes with names x and + y are used. This method fails if called before :meth:dolayout. + + +.. method:: graphxy.vpos(vx, vy) + + Returns the given point at *vx* and *vy* as a tuple (xpos, ypos) at the + graph canvas. *vx* and *vy* are graph coordinates with range [0:1]. + + +.. method:: graphxy.vgeodesic(vx1, vy1, vx2, vy2) + + Returns the geodesic between points *vx1*, *vy1* and *vx2*, *vy2* as a path. All + parameters are in graph coordinates with range [0:1]. For :class:graphxy this + is a straight line. + + +.. method:: graphxy.vgeodesic_el(vx1, vy1, vx2, vy2) + + Like :meth:vgeodesic but this method returns the path element to connect the + two points. + +.. index:: + single: xbasepath()@xbasepath() (graphxy method) + single: xvbasepath()@xvbasepath() (graphxy method) + single: xgridpath()@xgridpath() (graphxy method) + single: xvgridpath()@xvgridpath() (graphxy method) + single: xtickpoint()@xtickpoint() (graphxy method) + single: xvtickpoint()@xvtickpoint() (graphxy method) + single: xtickdirection()@xtickdirection() (graphxy method) + single: xvtickdirection()@xvtickdirection() (graphxy method) + single: ybasepath()@ybasepath() (graphxy method) + single: yvbasepath()@yvbasepath() (graphxy method) + single: ygridpath()@ygridpath() (graphxy method) + single: yvgridpath()@yvgridpath() (graphxy method) + single: ytickpoint()@ytickpoint() (graphxy method) + single: yvtickpoint()@yvtickpoint() (graphxy method) + single: ytickdirection()@ytickdirection() (graphxy method) + single: yvtickdirection()@yvtickdirection() (graphxy method) + +.. % dirty hack to add a whole list of methods to the index: + +Further geometry information is available by the :attr:axes instance variable, +with is a dictionary mapping axis names to :class:anchoredaxis instances. +Shortcuts to the anchoredaxis positioner methods for the x\ - and y\ +-axis become available after :meth:dolayout as :class:graphxy methods +Xbasepath, Xvbasepath, Xgridpath, Xvgridpath, Xtickpoint, +Xvtickpoint, Xtickdirection, and Xvtickdirection where the prefix +X stands for x and y. + + +.. method:: graphxy.axistrafo(axis, t) + + This method can be used to apply a transformation *t* to an + :class:anchoredaxis instance *axis* to modify the axis position and the like. + This method fails when called on a not yet finished axis, i.e. it should be used + after :meth:dolayout. + + +.. method:: graphxy.axisatv(axis, v) + + This method calls :meth:axistrafo with a transformation to move the axis + *axis* to a graph position *v* (in graph coordinates). + +The class :class:graphxyz is very similar to the :class:graphxy class, +except for its additional dimension. In the following documentation only the +differences to the :class:graphxy class are described. + + +.. class:: graphxyz(xpos=0, ypos=0, size=None, xscale=1, yscale=1, zscale=1/goldenmean, projector=central(10, -30, 30), key=None, **axes) + + This class provides an x-y-z-graph. + + The position of the graph on its own canvas is specified by *xpos* and *ypos*. + The size of the graph is specified by *size* and the length factors *xscale*, + *yscale*, and *zscale*. The final size of the graph depends on the projector + *projector*, which is called with x, y, and z values up to *xscale*, + *yscale*, and *zscale* respectively and scaling the result by *size*. For a + parallel projector changing *size* is thus identical to changing *xscale*, + *yscale*, and *zscale* by the same factor. For the central projector the + projectors internal distance would also need to be changed by this factor. Thus + *size* changes the size of the whole graph without changing the projection. + + *projector* defines the conversion of 3d coordinates to 2d coordinates. It can + be an instance of :class:central or :class:parallel described below. + + *\*\*axes* receives axes instances as for :class:graphxyz. The graphxyz allows + for 4 axes per graph dimension x, x2, x3, x4, y, y2, + y3, y4, z, z2, z3, and z4. The x-y-plane is the @@ Diff output truncated at 100000 characters. @@ This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. 
 [PyX-checkins] SF.net SVN: pyx:[3143] trunk/pyx/manual From: - 2011-05-20 08:08:33 Revision: 3143 http://pyx.svn.sourceforge.net/pyx/?rev=3143&view=rev Author: wobsta Date: 2011-05-20 08:08:24 +0000 (Fri, 20 May 2011) Log Message: ----------- remove old tex sources Removed Paths: ------------- trunk/pyx/manual/arrows.tex trunk/pyx/manual/axis.tex trunk/pyx/manual/bbox.tex trunk/pyx/manual/bitmap.tex trunk/pyx/manual/box.tex trunk/pyx/manual/canvas.tex trunk/pyx/manual/color.tex trunk/pyx/manual/colorname.tex trunk/pyx/manual/connector.tex trunk/pyx/manual/deformer.tex trunk/pyx/manual/document.tex trunk/pyx/manual/epsfile.tex trunk/pyx/manual/gradientname.tex trunk/pyx/manual/graph.tex trunk/pyx/manual/graphics.tex trunk/pyx/manual/intro.tex trunk/pyx/manual/manual.tex trunk/pyx/manual/path.tex trunk/pyx/manual/pathstyles.tex trunk/pyx/manual/pattern.tex trunk/pyx/manual/text.tex trunk/pyx/manual/trafo.tex trunk/pyx/manual/unit.tex Deleted: trunk/pyx/manual/arrows.tex =================================================================== --- trunk/pyx/manual/arrows.tex 2011-05-20 08:02:19 UTC (rev 3142) +++ trunk/pyx/manual/arrows.tex 2011-05-20 08:08:24 UTC (rev 3143) @@ -1,3 +0,0 @@ -\chapter{Arrows in deco module} -\label{arrows} -\includegraphics{arrows} Deleted: trunk/pyx/manual/axis.tex =================================================================== --- trunk/pyx/manual/axis.tex 2011-05-20 08:02:19 UTC (rev 3142) +++ trunk/pyx/manual/axis.tex 2011-05-20 08:08:24 UTC (rev 3143) @@ -1,989 +0,0 @@ -\chapter{Axes} -\label{axis} -\section{Component architecture} % {{{ - -Axes are a fundamental component of graphs although there might be -applications outside of the graph system. Internally axes are -constructed out of components, which handle different tasks axes need -to fulfill: - -\begin{definitions} -\term{axis} - Implements the conversion of a data value to a graph coordinate of - range [0:1]. It does also handle the proper usage of the components - in complicated tasks (\emph{i.e.} combine the partitioner, texter, - painter and rater to find the best partitioning). - - An anchoredaxis is a container to combine an axis with an positioner - and provide a storage area for all kind of axis data. That way axis - instances are reusable (they do not store any data locally). The - anchoredaxis and the positioner are created by a graph corresponding - to its geometry. -\term{tick} - Ticks are plotted along the axis. They might be labeled with text as - well. -\term{partitioner, we use parter'' as a short form} - Creates one or several choices of tick lists suitable to a certain - axis range. -\term{texter} - Creates labels for ticks when they are not set manually. -\term{painter} - Responsible for painting the axis. -\term{rater} - Calculate ratings, which can be used to select the best suitable - partitioning. -\term{positioner} - Defines the position of an axis. -\end{definitions} - -The names above map directly to modules which are provided in the -directory \file{graph/axis} except for the anchoredaxis, which is part -of the axis module as well. Sometimes it might be convenient to import -the axis directory directly rather than to access iit through the -graph. This would look like: -\begin{verbatim} - from pyx import * - graph.axis.painter() # and the like - - from pyx.graph import axis - axis.painter() # this is shorter ... -\end{verbatim} - -In most cases different implementations are available through -different classes, which can be combined in various ways. There are -various axis examples distributed with \PyX{}, where you can see some -of the features of the axis with a few lines of code each. Hence we -can here directly come to the reference of the available -components. % }}} - -\section{Module \module{graph.axis.axis}: Axes} % {{{ - -\declaremodule{}{graph.axis.axis} -\modulesynopsis{Axes} - -The following classes are part of the module \module{graph.axis.axis}. -However, there is a shortcut to access those classes via -\code{graph.axis} directly. - -Instances of the following classes can be passed to the \var{**axes} -keyword arguments of a graph. Those instances should only be used once. - -\begin{classdesc}{linear}{min=None, max=None, reverse=0, divisor=None, title=None, - parter=parter.autolinear(), manualticks=[], - density=1, maxworse=2, rater=rater.linear(), - texter=texter.mixed(), painter=painter.regular(), - linkpainter=painter.linked(), fallbackrange=None} - This class provides a linear axis. \var{min} and \var{max} define the - axis range. When not set, they are adjusted automatically by the - data to be plotted in the graph. Note, that some data might want to - access the range of an axis (\emph{e.g.} the \class{function} class - when no range was provided there) or you need to specify a range - when using the axis without plugging it into a graph (\emph{e.g.} - when drawing an axis along a path). In cases where the data provides - a range of zero (e.g.~a when plotting a constant function), then a - \var{fallbackrange} can be set to guarantee a minimal range of the - axis. - - \var{reverse} can be set to indicate a reversed axis starting with - bigger values first. Alternatively you can fix the axis range by - \var{min} and \var{max} accordingly. When divisor is set, it is - taken to divide all data range and position informations while - creating ticks. You can create ticks not taking into account a - factor by that. \var{title} is the title of the axis. - - \var{parter} is a partitioner instance, which creates suitable ticks - for the axis range. Those ticks are merged with ticks manually given - by \var{manualticks} before proceeding with rating, painting - \emph{etc.} Manually placed ticks win against those created by the - partitioner. For automatic partitioners, which are able to calculate - several possible tick lists for a given axis range, the - \var{density} is a (linear) factor to favour more or less ticks. It - should not be stressed to much (its likely, that the result would be - unappropriate or not at all valid in terms of rating label - distances). But within a range of say 0.5 to 2 (even bigger for - large graphs) it can help to get less or more ticks than the default - would lead to. \var{maxworse} is the number of trials with more - and less ticks when a better rating was already found. \var{rater} - is a rater instance, which rates the ticks and the label distances - for being best suitable. It also takes into account \var{density}. - The rater is only needed, when the partitioner creates several tick - lists. - - \var{texter} is a texter instance. It creates labels for those - ticks, which claim to have a label, but do not have a label string - set already. Ticks created by partitioners typically receive their - label strings by texters. The \var{painter} is finally used to - construct the output. Note, that usually several output - constructions are needed, since the rater is also used to rate the - distances between the labels for an optimum. The \var{linkedpainter} - is used as the axis painter, when automatic link axes are created by - the \method{createlinked()} method. -\end{classdesc} - -\begin{classdesc}{lin}{...} - This class is an abbreviation of \class{linear} described above. -\end{classdesc} - -\begin{classdesc}{logarithmic}{min=None, max=None, reverse=0, divisor=None, title=None, - parter=parter.autologarithmic(), manualticks=[], - density=1, maxworse=2, rater=rater.logarithmic(), - texter=texter.mixed(), painter=painter.regular(), - linkpainter=painter.linked(), fallbackrange=None} - This class provides a logarithmic axis. All parameters work like - \class{linear}. Only two parameters have a different default: - \var{parter} and \var{rater}. Furthermore and most importantly, the - mapping between data and graph coordinates is logarithmic. -\end{classdesc} - -\begin{classdesc}{log}{...} -This class is an abbreviation of \class{logarithmic} described above. -\end{classdesc} - -\begin{classdesc}{bar}{subaxes=None, - defaultsubaxis=linear(painter=None, - linkpainter=None, - parter=None, - texter=None), - dist=0.5, firstdist=None, lastdist=None, - title=None, reverse=0, - painter=painter.bar(), - linkpainter=painter.linkedbar()} - This class provides an axis suitable for a bar style. It handles a - discrete set of values and maps them to distinct ranges in graph - coordinates. For that, the axis gets a tuple of two values. - - The first item is taken to be one of the discrete values valid on - this axis. The discrete values can be any hashable type and the - order of the subaxes is defined by the order the data is received or - the inverse of that when \var{reverse} is set. - - The second item is passed to the corresponding subaxis. The result - of the conversion done by the subaxis is mapped to the graph - coordinate range reserved for this subaxis. This range is defined by - a size attribute of the subaxis, which can be added to any axis. - (see the sized linear axes described below for some axes already - having a size argument). When no size information is available for a - subaxis, a size value of 1 is used. The baraxis itself calculates - its size by suming up the sizes of its subaxes plus \var{firstdist}, - \var{lastdist} and \var{dist} times the number of subaxes minus 1. - - \var{subaxes} should be a list or a dictionary mapping a discrete - value of the bar axis to the corresponding subaxis. When no subaxes - are set or data is received for an unknown discrete axis value, - instances of defaultsubaxis are used as the subaxis for this - discrete value. - - \var{dist} is used as the spacing between the ranges for each - distinct value. It is measured in the same units as the subaxis - results, thus the default value of \code{0.5} means half the width - between the distinct values as the width for each distinct value. - \var{firstdist} and \var{lastdist} are used before the first and - after the last value. When set to \code{None}, half of \var{dist} - is used. - - \var{title} is the title of the split axes and \var{painter} is a - specialized painter for an bar axis and \var{linkpainter} is used as - the painter, when automatic link axes are created by the - \method{createlinked()} method. -\end{classdesc} - -\begin{classdesc}{nestedbar}{subaxes=None, - defaultsubaxis=bar(dist=0, painter=None, linkpainter=None), - dist=0.5, firstdist=None, lastdist=None, - title=None, reverse=0, - painter=painter.bar(), - linkpainter=painter.linkedbar()} - This class is identical to the bar axis except for the different - default value for defaultsubaxis. -\end{classdesc} - -\begin{classdesc}{split}{subaxes=None, - defaultsubaxis=linear(), - dist=0.5, firstdist=0, lastdist=0, - title=None, reverse=0, - painter=painter.split(), - linkpainter=painter.linkedsplit()} - This class is identical to the bar axis except for the different - default value for defaultsubaxis, firstdist, lastdist, painter, and - linkedpainter. -\end{classdesc} - -Sometimes you want to alter the default size of 1 of the subaxes. For -that you have to add a size attribute to the axis data. The two -classes \class{sizedlinear} and \class{autosizedlinear} do that for -linear axes. Their short names are \class{sizedlin} and -\class{autosizedlin}. \class{sizedlinear} extends the usual linear -axis by an first argument \var{size}. \class{autosizedlinear} creates -the size out of its data range automatically but sets an -\class{autolinear} parter with \var{extendtick} being \code{None} in -order to disable automatic range modifications while painting the -axis. - -The \module{axis} module also contains classes implementing so called -anchored axes, which combine an axis with an positioner and a storage -place for axis related data. Since these features are not interesting -for the average \PyX{} user, we'll not go into all the details of -their parameters and except for some handy axis position methods: - -\begin{classdesc}{anchoredaxis}{} - DUMMY -\end{classdesc} - -\begin{methoddesc}{basepath}{x1=None, x2=None} - Returns a path instance for the base path. \var{x1} and \var{x2} - define the axis range, the base path should cover. For \code{None} - the beginning and end of the path is taken, which might cover a - longer range, when the axis is embedded as a subaxis. For that case, - a \code{None} value extends the range to the point of the middle - between two subaxes or the beginning or end of the whole axis, when - the subaxis is the first or last of the subaxes. -\end{methoddesc} - -\begin{methoddesc}{vbasepath}{v1=None, v2=None} - Like \method{basepath} but in graph coordinates. -\end{methoddesc} - -\begin{methoddesc}{gridpath}{x} - Returns a path instance for the grid path at position \var{x}. - Might return \code{None} when no grid path is available. -\end{methoddesc} - -\begin{methoddesc}{vgridpath}{v} - Like \method{gridpath} but in graph coordinates. -\end{methoddesc} - -\begin{methoddesc}{tickpoint}{x} - Returns the position of \var{x} as a tuple \samp{(x, y)}. -\end{methoddesc} - -\begin{methoddesc}{vtickpoint}{v} - Like \method{tickpoint} but in graph coordinates. -\end{methoddesc} - -\begin{methoddesc}{tickdirection}{x} - Returns the direction of a tick at \var{x} as a tuple \samp{(dx, dy)}. - The tick direction points inside of the graph. -\end{methoddesc} - -\begin{methoddesc}{vtickdirection}{v} - Like \method{tickdirection} but in graph coordinates. -\end{methoddesc} - -\begin{methoddesc}{vtickdirection}{v} - Like \method{tickdirection} but in graph coordinates. -\end{methoddesc} - -However, there are two anchored axes implementations -\class{linkedaxis} and \class{anchoredpathaxis} which are available to -the user to create special forms of anchored axes. - -\begin{classdesc}{linkedaxis}{linkedaxis=None, errorname="manual-linked", painter=_marker} - This class implements an anchored axis to be passed to a graph - constructor to manually link the axis to another anchored axis - instance \var{linkedaxis}. Note that you can skip setting the value - of \var{linkedaxis} in the constructor, but set it later on by the - \method{setlinkedaxis} method described below. \var{errorname} is - printed within error messages when the data is used and some problem - occurs. \var{painter} is used for painting the linked axis instead - of the \var{linkedpainter} provided by the \var{linkedaxis}. -\end{classdesc} - -\begin{methoddesc}{setlinkedaxis}{linkedaxis} - This method can be used to set the \var{linkedaxis} after - constructing the axis. By that you can create several graph - instances with cycled linked axes. -\end{methoddesc} - -\begin{classdesc}{anchoredpathaxis}{path, axis, direction=1} - This class implements an anchored axis the path \var{path}. - \var{direction} defines the direction of the ticks. Allowed values - are \code{1} (left) and \code{-1} (right). -\end{classdesc} - -The \class{anchoredpathaxis} contains as any anchored axis after -calling its \method{create} method the painted axis in the -\member{canvas} member attribute. The function \function{pathaxis} has -the same signature like the \class{anchoredpathaxis} class, but -immediately creates the axis and returns the painted axis. % }}} - -\section{Module \module{graph.axis.tick}: Ticks} % {{{ - -\declaremodule{}{graph.axis.tick} -\modulesynopsis{Axes ticks} - -The following classes are part of the module \module{graph.axis.tick}. - -\begin{classdesc}{rational}{x, power=1, floatprecision=10} - This class implements a rational number with infinite precision. For - that it stores two integers, the numerator \code{num} and a - denominator \code{denom}. Note that the implementation of rational - number arithmetics is not at all complete and designed for its - special use case of axis partitioning in \PyX{} preventing any - roundoff errors. - - \var{x} is the value of the rational created by a conversion from - one of the following input values: - \begin{itemize} - \item A float. It is converted to a rational with finite precision - determined by \var{floatprecision}. - \item A string, which is parsed to a rational number with full - precision. It is also allowed to provide a fraction like - \code{\textquotedbl{}1/3\textquotedbl}. - \item A sequence of two integers. Those integers are taken as - numerator and denominator of the rational. - \item An instance defining instance variables \code{num} and - \code{denom} like \class{rational} itself. - \end{itemize} - - \var{power} is an integer to calculate \code{\var{x}**\var{power}}. - This is useful at certain places in partitioners. -\end{classdesc} - -\begin{classdesc}{tick}{x, ticklevel=0, labellevel=0, label=None, - labelattrs=[], power=1, floatprecision=10} - This class implements ticks based on rational numbers. Instances of - this class can be passed to the \code{manualticks} parameter of a - regular axis. - - The parameters \var{x}, \var{power}, and \var{floatprecision} share - its meaning with \class{rational}. - - A tick has a tick level (\emph{i.e.} markers at the axis path) and a - label lavel (\emph{e.i.} place text at the axis path), - \var{ticklevel} and \var{labellevel}. These are non-negative - integers or \var{None}. A value of \code{0} means a regular tick or - label, \code{1} stands for a subtick or sublabel, \code{2} for - subsubtick or subsublabel and so on. \code{None} means omitting the - tick or label. \var{label} is the text of the label. When not set, - it can be created automatically by a texter. \var{labelattrs} are - the attributes for the labels. -\end{classdesc} % }}} - -\section{Module \module{graph.axis.parter}: Partitioners} % {{{ - -\declaremodule{}{graph.axis.parter} -\modulesynopsis{Axes partitioners} - -The following classes are part of the module \module{graph.axis.parter}. -Instances of the classes can be passed to the parter keyword argument -of regular axes. - -\begin{classdesc}{linear}{tickdists=None, labeldists=None, - extendtick=0, extendlabel=None, - epsilon=1e-10} - Instances of this class creates equally spaced tick lists. The - distances between the ticks, subticks, subsubticks \emph{etc.} - starting from a tick at zero are given as first, second, third - \emph{etc.} item of the list \var{tickdists}. For a tick position, - the lowest level wins, \emph{i.e.} for \code{[2, 1]} even numbers - will have ticks whereas subticks are placed at odd integer. The - items of \var{tickdists} might be strings, floats or tuples as - described for the \var{pos} parameter of class \class{tick}. - - \var{labeldists} works equally for placing labels. When - \var{labeldists} is kept \code{None}, labels will be placed at each - tick position, but sublabels \emph{etc.} will not be used. This copy - behaviour is also available \emph{vice versa} and can be disabled by - an empty list. - - \var{extendtick} can be set to a tick level for including the next - tick of that level when the data exceeds the range covered by the - ticks by more than \var{epsilon}. \var{epsilon} is taken relative - to the axis range. \var{extendtick} is disabled when set to - \code{None} or for fixed range axes. \var{extendlabel} works similar - to \var{extendtick} but for labels. -\end{classdesc} - -\begin{classdesc}{lin}{...} -This class is an abbreviation of \class{linear} described above. -\end{classdesc} - -\begin{classdesc}{autolinear}{variants=defaultvariants, - extendtick=0, - epsilon=1e-10} - Instances of this class creates equally spaced tick lists, where the - distance between the ticks is adjusted to the range of the axis - automatically. Variants are a list of possible choices for - \var{tickdists} of \class{linear}. Further variants are build out of - these by multiplying or dividing all the values by multiples of - \code{10}. \var{variants} should be ordered that way, that the - number of ticks for a given range will decrease, hence the distances - between the ticks should increase within the \var{variants} list. - \var{extendtick} and \var{epsilon} have the same meaning as in - \class{linear}. -\end{classdesc} - -\begin{memberdesc}{defaultvariants} - \code{[[tick.rational((1, 1)), - tick.rational((1, 2))], [tick.rational((2, 1)), tick.rational((1, - 1))], [tick.rational((5, 2)), tick.rational((5, 4))], - [tick.rational((5, 1)), tick.rational((5, 2))]]} -\end{memberdesc} - -\begin{classdesc}{autolin}{...} -This class is an abbreviation of \class{autolinear} described above. -\end{classdesc} - -\begin{classdesc}{preexp}{pres, exp} - This is a storage class defining positions of ticks on a - logarithmic scale. It contains a list \var{pres} of positions $p_i$ - and \var{exp}, a multiplicator $m$. Valid tick positions are defined - by $p_im^n$ for any integer $n$. -\end{classdesc} - -\begin{classdesc}{logarithmic}{tickpreexps=None, labelpreexps=None, - extendtick=0, extendlabel=None, - epsilon=1e-10} - Instances of this class creates tick lists suitable to logarithmic - axes. The positions of the ticks, subticks, subsubticks \emph{etc.} - are defined by the first, second, third \emph{etc.} item of the list - \var{tickpreexps}, which are all \class{preexp} instances. - - \var{labelpreexps} works equally for placing labels. When \var{labelpreexps} - is kept \code{None}, labels will be placed at each tick position, - but sublabels \emph{etc.} will not be used. This copy behaviour is - also available \emph{vice versa} and can be disabled by an empty - list. - - \var{extendtick}, \var{extendlabel} and \var{epsilon} have the same - meaning as in \class{linear}. -\end{classdesc} - -Some \class{preexp} instances for the use in \class{logarithmic} are -available as instance variables (should be used read-only): - -\begin{memberdesc}{pre1exp5} - \code{preexp([tick.rational((1, 1))], 100000)} -\end{memberdesc} - -\begin{memberdesc}{pre1exp4} - \code{preexp([tick.rational((1, 1))], 10000)} -\end{memberdesc} - -\begin{memberdesc}{pre1exp3} - \code{preexp([tick.rational((1, 1))], 1000)} -\end{memberdesc} - -\begin{memberdesc}{pre1exp2} - \code{preexp([tick.rational((1, 1))], 100)} -\end{memberdesc} - -\begin{memberdesc}{pre1exp} - \code{preexp([tick.rational((1, 1))], 10)} -\end{memberdesc} - -\begin{memberdesc}{pre125exp} - \code{preexp([tick.rational((1, 1)), tick.rational((2, 1)), tick.rational((5, 1))], 10)} -\end{memberdesc} - -\begin{memberdesc}{pre1to9exp} - \code{preexp([tick.rational((1, 1)) for x in range(1, 10)], 10)} -\end{memberdesc} - -\begin{classdesc}{log}{...} -This class is an abbreviation of \class{logarithmic} described above. -\end{classdesc} - -\begin{classdesc}{autologarithmic}{variants=defaultvariants, - extendtick=0, extendlabel=None, - epsilon=1e-10} - Instances of this class creates tick lists suitable to logarithmic - axes, where the distance between the ticks is adjusted to the range - of the axis automatically. Variants are a list of tuples with - possible choices for \var{tickpreexps} and \var{labelpreexps} of - \class{logarithmic}. \var{variants} should be ordered that way, that - the number of ticks for a given range will decrease within the - \var{variants} list. - - \var{extendtick}, \var{extendlabel} and \var{epsilon} have the same - meaning as in \class{linear}. -\end{classdesc} - -\begin{memberdesc}{defaultvariants} - \code{[([log.pre1exp, log.pre1to9exp], [log.pre1exp, - log.pre125exp]), ([log.pre1exp, log.pre1to9exp], None), - ([log.pre1exp2, log.pre1exp], None), ([log.pre1exp3, - log.pre1exp], None), ([log.pre1exp4, log.pre1exp], None), - ([log.pre1exp5, log.pre1exp], None)]} -\end{memberdesc} - -\begin{classdesc}{autolog}{...} -This class is an abbreviation of \class{autologarithmic} described above. -\end{classdesc} % }}} - -\section{Module \module{graph.axis.texter}: Texter} % {{{ - -\declaremodule{}{graph.axis.texter} -\modulesynopsis{Axes texters} - -The following classes are part of the module \module{graph.axis.texter}. -Instances of the classes can be passed to the texter keyword argument -of regular axes. Texters are used to define the label text for ticks, -which request to have a label, but for which no label text has been specified -so far. A typical case are ticks created by partitioners described -above. - -\begin{classdesc}{decimal}{prefix="", infix="", suffix="", equalprecision=0, - decimalsep=".", thousandsep="", thousandthpartsep="", - plus="", minus="-", period=r"\textbackslash overline\{\%s\}", - labelattrs=[text.mathmode]} - Instances of this class create decimal formatted labels. - - The strings \var{prefix}, \var{infix}, and \var{suffix} are added to - the label at the beginning, immediately after the plus or minus, and at - the end, respectively. \var{decimalsep}, \var{thousandsep}, and - \var{thousandthpartsep} are strings used to separate integer from - fractional part and three-digit groups in the integer and fractional - part. The strings \var{plus} and \var{minus} are inserted in front - of the unsigned value for non-negative and negative numbers, - respectively. - - The format string \var{period} should generate a period. It must - contain one string insert operators \code{\%s} for the period. - - \var{labelattrs} is a list of attributes to be added to the label - attributes given in the painter. It should be used to setup \TeX{} - features like \code{text.mathmode}. Text format options like - \code{text.size} should instead be set at the painter. -\end{classdesc} - -\begin{classdesc}{exponential}{plus="", minus="-", - mantissaexp=r"\{\{\%s\}\textbackslash cdot10\textasciicircum\{\%s\}\}", - skipexp0=r"\{\%s\}", - skipexp1=None, - nomantissaexp=r"\{10\textasciicircum\{\%s\}\}", - minusnomantissaexp=r"\{-10\textasciicircum\{\%s\}\}", - mantissamin=tick.rational((1, 1)), mantissamax=tick.rational((10L, 1)), - skipmantissa1=0, skipallmantissa1=1, - mantissatexter=decimal()} - Instances of this class create decimal formatted labels with an - exponential. - - The strings \var{plus} and \var{minus} are inserted in front of the - unsigned value of the exponent. - - The format string \var{mantissaexp} should generate the exponent. It - must contain two string insert operators \code{\%s}, the first for - the mantissa and the second for the exponent. An alternative to the - default is \code{r\textquotedbl\{\{\%s\}\{\e rm e\}\{\%s\}\}\textquotedbl}. - - The format string \var{skipexp0} is used to skip exponent \code{0} and must - contain one string insert operator \code{\%s} for the mantissa. - \code{None} turns off the special handling of exponent \code{0}. - The format string \var{skipexp1} is similar to \var{skipexp0}, but - for exponent \code{1}. - - The format string \var{nomantissaexp} is used to skip the mantissa - \code{1} and must contain one string insert operator \code{\%s} for - the exponent. \code{None} turns off the special handling of mantissa - \code{1}. The format string \var{minusnomantissaexp} is similar - to \var{nomantissaexp}, but for mantissa \code{-1}. - - The \class{tick.rational} instances \var{mantissamin}\textless - \var{mantissamax} are minimum (including) and maximum (excluding) of - the mantissa. - - The boolean \var{skipmantissa1} enables the skipping of any mantissa - equals \code{1} and \code{-1}, when \var{minusnomantissaexp} is set. - When the boolean \var{skipallmantissa1} is set, a mantissa equals - \code{1} is skipped only, when all mantissa values are \code{1}. - Skipping of a mantissa is stronger than the skipping of an exponent. - - \var{mantissatexter} is a texter instance for the mantissa. -\end{classdesc} - -\begin{classdesc}{mixed}{smallestdecimal=tick.rational((1, 1000)), - biggestdecimal=tick.rational((9999, 1)), - equaldecision=1, - decimal=decimal(), - exponential=exponential()} - Instances of this class create decimal formatted labels with an - exponential, when the unsigned values are small or large compared to - \var{1}. - - The rational instances \var{smallestdecimal} and - \var{biggestdecimal} are the smallest and biggest decimal values, - where the decimal texter should be used. The sign of the value is - ignored here. For a tick at zero the decimal texter is considered - best as well. \var{equaldecision} is a boolean to indicate whether - the decision for the decimal or exponential texter should be done - globally for all ticks. - - \var{decimal} and \var{exponential} are a decimal and an exponential - texter instance, respectively. -\end{classdesc} - -\begin{classdesc}{rational}{prefix="", infix="", suffix="", - numprefix="", numinfix="", numsuffix="", - denomprefix="", denominfix="", denomsuffix="", - plus="", minus="-", minuspos=0, over=r"{{\%s}\textbackslash over{\%s}}", - equaldenom=0, skip1=1, skipnum0=1, skipnum1=1, skipdenom1=1, - labelattrs=[text.mathmode]} - Instances of this class create labels formated as fractions. - - The strings \var{prefix}, \var{infix}, and \var{suffix} are added to - the label at the beginning, immediately after the plus or minus, and at - the end, respectively. The strings \var{numprefix}, - \var{numinfix}, and \var{numsuffix} are added to the labels - numerator accordingly whereas \var{denomprefix}, \var{denominfix}, - and \var{denomsuffix} do the same for the denominator. - - The strings \var{plus} and \var{minus} are inserted in front of the - unsigned value. The position of the sign is defined by - \var{minuspos} with values \code{1} (at the numerator), \code{0} - (in front of the fraction), and \code{-1} (at the denominator). - - The format string \var{over} should generate the fraction. It - must contain two string insert operators \code{\%s}, the first for - the numerator and the second for the denominator. An alternative to - the default is \code{\textquotedbl\{\{\%s\}/\{\%s\}\}\textquotedbl}. - - Usually, the numerator and denominator are canceled, while, when - \var{equaldenom} is set, the least common multiple of all - denominators is used. - - The boolean \var{skip1} indicates, that only the prefix, plus or minus, - the infix and the suffix should be printed, when the value is - \code{1} or \code{-1} and at least one of \var{prefix}, \var{infix} - and \var{suffix} is present. - - The boolean \var{skipnum0} indicates, that only a \code{0} is - printed when the numerator is zero. - - \var{skipnum1} is like \var{skip1} but for the numerator. - - \var{skipdenom1} skips the denominator, when it is \code{1} taking - into account \var{denomprefix}, \var{denominfix}, \var{denomsuffix} - \var{minuspos} and the sign of the number. - - \var{labelattrs} has the same meaning as for \var{decimal}. -\end{classdesc} % }}} - -\section{Module \module{graph.axis.painter}: Painter} % {{{ - -\declaremodule{}{graph.axis.painter} -\modulesynopsis{Axes painters} - -The following classes are part of the module -\module{graph.axis.painter}. Instances of the painter classes can be -passed to the painter keyword argument of regular axes. - -\begin{classdesc}{rotatetext}{direction, epsilon=1e-10} - This helper class is used in direction arguments of the painters - below to prevent axis labels and titles being written upside down. - In those cases the text will be rotated by 180 degrees. - \var{direction} is an angle to be used relative to the tick - direction. \var{epsilon} is the value by which 90 degrees can be - exceeded before an 180 degree rotation is performed. -\end{classdesc} - -The following two class variables are initialized for the most common -applications: - -\begin{memberdesc}{parallel} - \code{rotatetext(90)} -\end{memberdesc} - -\begin{memberdesc}{orthogonal} - \code{rotatetext(180)} -\end{memberdesc} - -\begin{classdesc}{ticklength}{initial, factor} - This helper class provides changeable \PyX{} lengths starting from - an initial value \var{initial} multiplied by \var{factor} again and - again. The resulting lengths are thus a geometric series. -\end{classdesc} - -There are some class variables initialized with suitable values for -tick stroking. They are named \code{ticklength.SHORT}, -\code{ticklength.SHORt}, \dots, \code{ticklength.short}, -\code{ticklength.normal}, \code{ticklength.long}, \dots, -\code{ticklength.LONG}. \code{ticklength.normal} is initialized with -a length of \code{0.12} and the reciprocal of the golden mean as -\code{factor} whereas the others have a modified initial value -obtained by multiplication with or division by appropriate multiples of -$\sqrt{2}$. - -\begin{classdesc}{regular}{innerticklength=ticklength.normal, - outerticklength=None, - tickattrs=[], - gridattrs=None, - basepathattrs=[], - labeldist="0.3 cm", - labelattrs=[], - labeldirection=None, - labelhequalize=0, - labelvequalize=1, - titledist="0.3 cm", - titleattrs=[], - titledirection=rotatetext.parallel, - titlepos=0.5, - texrunner=None} - Instances of this class are painters for regular axes like linear - and logarithmic axes. - - \var{innerticklength} and \var{outerticklength} are visual \PyX{} - lengths of the ticks, subticks, subsubticks \emph{etc.} plotted - along the axis inside and outside of the graph. Provide changeable - attributes to modify the lengths of ticks compared to subticks - \emph{etc.} \code{None} turns off the ticks inside and outside the - graph, respectively. - - \var{tickattrs} and \var{gridattrs} are changeable stroke attributes - for the ticks and the grid, where \code{None} turns off the feature. - \var{basepathattrs} are stroke attributes for the axis or - \code{None} to turn it off. \var{basepathattrs} is merged with - \code{[style.linecap.square]}. - - \var{labeldist} is the distance of the labels from the axis base path - as a visual \PyX{} length. \var{labelattrs} is a list of text - attributes for the labels. It is merged with - \code{[text.halign.center, text.vshift.mathaxis]}. - \var{labeldirection} is an instance of \var{rotatetext} to rotate - the labels relative to the axis tick direction or \code{None}. - - The boolean values \var{labelhequalize} and \var{labelvequalize} - force an equal alignment of all labels for straight vertical and - horizontal axes, respectively. - - \var{titledist} is the distance of the title from the rest of the - axis as a visual \PyX{} length. \var{titleattrs} is a list of text - attributes for the title. It is merged with - \code{[text.halign.center, text.vshift.mathaxis]}. - \var{titledirection} is an instance of \var{rotatetext} to rotate - the title relative to the axis tick direction or \code{None}. - \var{titlepos} is the position of the title in graph coordinates. - - \var{texrunner} is the texrunner instance to create axis text like - the axis title or labels. When not set the texrunner of the graph - instance is taken to create the text. -\end{classdesc} - -\begin{classdesc}{linked}{innerticklength=ticklength.short, - outerticklength=None, - tickattrs=[], - gridattrs=None, - basepathattrs=[], - labeldist="0.3 cm", - labelattrs=None, - labeldirection=None, - labelhequalize=0, - labelvequalize=1, - titledist="0.3 cm", - titleattrs=None, - titledirection=rotatetext.parallel, - titlepos=0.5, - texrunner=None} - This class is identical to \class{regular} up to the default values of - \var{labelattrs} and \var{titleattrs}. By turning off those - features, this painter is suitable for linked axes. -\end{classdesc} - -\begin{classdesc}{bar}{innerticklength=None, - outerticklength=None, - tickattrs=[], - basepathattrs=[], - namedist="0.3 cm", - nameattrs=[], - namedirection=None, - namepos=0.5, - namehequalize=0, - namevequalize=1, - titledist="0.3 cm", - titleattrs=[], - titledirection=rotatetext.parallel, - titlepos=0.5, - texrunner=None} - Instances of this class are suitable painters for bar axes. - - \var{innerticklength} and \var{outerticklength} are visual \PyX{} - lengths to mark the different bar regions along the axis inside and - outside of the graph. \code{None} turns off the ticks inside and - outside the graph, respectively. \var{tickattrs} are stroke - attributes for the ticks or \code{None} to turn all ticks off. - - The parameters with prefix \var{name} are identical to their - \var{label} counterparts in \class{regular}. All other parameters have - the same meaning as in \class{regular}. -\end{classdesc} - -\begin{classdesc}{linkedbar}{innerticklength=None, - outerticklength=None, - tickattrs=[], - basepathattrs=[], - namedist="0.3 cm", - nameattrs=None, - namedirection=None, - namepos=0.5, - namehequalize=0, - namevequalize=1, - titledist="0.3 cm", - titleattrs=None, - titledirection=rotatetext.parallel, - titlepos=0.5, - texrunner=None} - This class is identical to \class{bar} up to the default values of - \var{nameattrs} and \var{titleattrs}. By turning off those features, - this painter is suitable for linked bar axes. -\end{classdesc} - -\begin{classdesc}{split}{breaklinesdist="0.05 cm", - breaklineslength="0.5 cm", - breaklinesangle=-60, - titledist="0.3 cm", - titleattrs=[], - titledirection=rotatetext.parallel, - titlepos=0.5, - texrunner=None} - Instances of this class are suitable painters for split axes. - - \var{breaklinesdist} and \var{breaklineslength} are the distance - between axes break markers in visual \PyX{} lengths. - \var{breaklinesangle} is the angle of the axis break marker with - respect to the base path of the axis. All other parameters have the - same meaning as in \class{regular}. -\end{classdesc} - -\begin{classdesc}{linkedsplit}{breaklinesdist="0.05 cm", - breaklineslength="0.5 cm", - breaklinesangle=-60, - titledist="0.3 cm", - titleattrs=None, - titledirection=rotatetext.parallel, - titlepos=0.5, - texrunner=None} - This class is identical to \class{split} up to the default value of - \var{titleattrs}. By turning off this feature, this painter is - suitable for linked split axes. -\end{classdesc} % }}} - -\section{Module \module{graph.axis.rater}: Rater} % {{{ - -\declaremodule{}{graph.axis.rater} -\modulesynopsis{Axes raters} - -The rating of axes is implemented in \module{graph.axis.rater}. When -an axis partitioning scheme returns several partitioning -possibilities, the partitions need to be rated by a positive number. -The axis partitioning rated lowest is considered best. - -The rating consists of two steps. The first takes into account only -the number of ticks, subticks, labels and so on in comparison to -optimal numbers. Additionally, the extension of the axis range by -ticks and labels is taken into account. This rating leads to a -preselection of possible partitions. In the second step, after the -layout of preferred partitionings has been calculated, the distance of -the labels in a partition is taken into account as well at a smaller -weight factor by default. Thereby partitions with overlapping labels -will be rejected completely. Exceptionally sparse or dense labels will -receive a bad rating as well. - -\begin{classdesc}{cube}{opt, left=None, right=None, weight=1} - Instances of this class provide a number rater. \var{opt} is the - optimal value. When not provided, \var{left} is set to \code{0} and - \var{right} is set to \code{3*\var{opt}}. Weight is a multiplicator - to the result. - - The rater calculates - \code{\var{width}*((x-\var{opt})/(other-\var{opt}))**3} to rate the - value \code{x}, where \code{other} is \var{left} - (\code{x}\textless\var{opt}) or \var{right} - (\code{x}\textgreater\var{opt}). -\end{classdesc} - -\begin{classdesc}{distance}{opt, weight=0.1} - Instances of this class provide a rater for a list of numbers. - The purpose is to rate the distance between label boxes. \var{opt} - is the optimal value. - - The rater calculates the sum of \code{\var{weight}*(\var{opt}/x-1)} - (\code{x}\textless\var{opt}) or \code{\var{weight}*(x/\var{opt}-1)} - (\code{x}\textgreater\var{opt}) for all elements \code{x} of the - list. It returns this value divided by the number of elements in the - list. -\end{classdesc} - -\begin{classdesc}{rater}{ticks, labels, range, distance} - Instances of this class are raters for axes partitionings. - - \var{ticks} and \var{labels} are both lists of number rater - instances, where the first items are used for the number of ticks - and labels, the second items are used for the number of subticks - (including the ticks) and sublabels (including the labels) and so on - until the end of the list is reached or no corresponding ticks are - available. - - \var{range} is a number rater instance which rates the range of the - ticks relative to the range of the data. - - \var{distance} is an distance rater instance. -\end{classdesc} - -\begin{classdesc}{linear}{ticks=[cube(4), cube(10, weight=0.5)], - labels=[cube(4)], - range=cube(1, weight=2), - distance=distance("1 cm")} - This class is suitable to rate partitionings of linear axes. It is - equal to \class{rater} but defines predefined values for the - arguments. -\end{classdesc} - -\begin{classdesc}{lin}{...} - This class is an abbreviation of \class{linear} described above. -\end{classdesc} - -\begin{classdesc}{logarithmic}{ticks=[cube(5, right=20), cube(20, right=100, weight=0.5)], - labels=[cube(5, right=20), cube(5, right=20, weight=0.5)], - range=cube(1, weight=2), - distance=distance("1 cm")} - This class is suitable to rate partitionings of logarithmic axes. It - is equal to \class{rater} but defines predefined values for the - arguments. -\end{classdesc} - -\begin{classdesc}{log}{...} - This class is an abbreviation of \class{logarithmic} described above. -\end{classdesc} % }}} - -\section{Module \module{graph.axis.positioner}: Positioners} % {{{ - -\declaremodule{}{graph.axis.positioners} -\modulesynopsis{Axes positioners} - -The position of an axis is defined by an instance of a class providing -the following methods: - -\begin{classdesc}{positioner}{} - DUMMY -\end{classdesc} - -\begin{methoddesc}{vbasepath}{v1=None, v2=None} - Returns a path instance for the base path. \var{v1} and \var{v2} - define the axis range in graph coordinates the base path should - cover. -\end{methoddesc} - -\begin{methoddesc}{vgridpath}{v} - Returns a path instance for the grid path at position \var{v} in - graph coordinates. The method might return \code{None} when no grid - path is available (for an axis along a path for example). -\end{methoddesc} - -\begin{methoddesc}{vtickpoint_pt}{v} - Returns the position of \var{v} in graph coordinates as a tuple - \code{(x, y)} in points. -\end{methoddesc} - -\begin{methoddesc}{vtickdirection}{v} - Returns the direction of a tick at \var{v} in graph coordinates as a - tuple \code{(dx, dy)}. The tick direction points inside of the - graph. -\end{methoddesc} - -The module contains several implementations of those positioners, but -since the positioner instances are created by graphs etc. as needed, -the details are not interesting for the average \PyX{} user. - -% }}} % }}} - -% vim:fdm=marker Deleted: trunk/pyx/manual/bbox.tex =================================================================== --- trunk/pyx/manual/bbox.tex 2011-05-20 08:02:19 UTC (rev 3142) +++ trunk/pyx/manual/bbox.tex 2011-05-20 08:08:24 UTC (rev 3143) @@ -1,44 +0,0 @@ -\chapter{Module bbox} - -\label{bbox} - -The \texttt{bbox} module contains the definition of the \texttt{bbox} -class representing bounding boxes of graphical elements like paths, -canvases, etc.\ used in \PyX. Usually, you obtain \texttt{bbox} -instances as return values of the corresponding \texttt{bbox())} -method, but you may also construct a bounding box by yourself. - -\section{bbox constructor} - -The \texttt{bbox} constructor accepts the following keyword arguments - -\begin{tableii}{l|l}{textrm}{keyword}{description} -\lineii{\texttt{llx}}{\texttt{None} (default) for $-\infty$ or $x$-position of the lower left corner of the bbox (in user units)} -\lineii{\texttt{lly}}{\texttt{None} (default) for $-\infty$ or $y$-position of the lower left corner of the bbox (in user units)} -\lineii{\texttt{urx}}{\texttt{None} (default) for $\infty$ or $x$-position of the upper right corner of the bbox (in user units)} -\lineii{\texttt{ury}}{\texttt{None} (default) for $\infty$ or $y$-position of the upper right corner of the bbox (in user units)} -\end{tableii} - -\section{bbox methods} - -\begin{tableii}{l|l}{textrm}{\texttt{bbox} method}{function} -\lineii{\texttt{intersects(other)}}{returns \texttt{1} if the \texttt{bbox} instance and \texttt{other} intersect with each other.} -\lineii{\texttt{transformed(self, trafo)}}{returns \texttt{self} transformed by transformation \texttt{trafo}.} -\lineii{\texttt{enlarged(all=0, bottom=None, left=None, top=None, right=None)}}{return the bounding box enlarged by the given amount (in visual units). \texttt{all} is the default for all other directions, which is used whenever \texttt{None} is given for the corresponding direction.} -\lineii{\texttt{path()} or \texttt{rect()}}{return the \texttt{path} corresponding to the bounding box rectangle.} -\lineii{\texttt{height()}}{returns the height of the bounding box (in \PyX{} lengths).} -\lineii{\texttt{width()}}{returns the width of the bounding box (in \PyX{} lengths).} -\lineii{\texttt{top()}}{returns the $y$-position of the top of the bounding box (in \PyX{} lengths).} -\lineii{\texttt{bottom()}}{returns the $y$-position of the bottom of the bounding box (in \PyX{} lengths).} -\lineii{\texttt{left()}}{returns the $x$-position of the left side of the bounding box (in \PyX{} lengths).} -\lineii{\texttt{right()}}{returns the $x$-position of the right side of the bounding box (in \PyX{} lengths).} -\end{tableii} - -Furthermore, two bounding boxes can be added (giving the bounding box -enclosing both) and multiplied (giving the intersection of both -bounding boxes). - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "manual.tex" -%%% End: Deleted: trunk/pyx/manual/bitmap.tex =================================================================== --- trunk/pyx/manual/bitmap.tex 2011-05-20 08:02:19 UTC (rev 3142) +++ trunk/pyx/manual/bitmap.tex 2011-05-20 08:08:24 UTC (rev 3143) @@ -1,137 +0,0 @@ -\chapter{Bitmaps} -\section{Introduction} -\PyX{} focuses on the creation of scaleable vector graphics. However, -\PyX{} also allows for the output of bitmap images. Still, the support -for creation and handling of bitmap images is quite limited. On the -other hand the interfaces are built that way, that its trivial to -combine \PyX{} with the Python Image Library'', also known as -PIL''. - -The creation of a bitmap can be performed out of some unpacked binary -data by first creating image instances: -\begin{verbatim} -from pyx import * -image_bw = bitmap.image(2, 2, "L", "\0\377\377\0") -image_rgb = bitmap.image(3, 2, "RGB", "\77\77\77\177\177\177\277\277\277" - "\377\0\0\0\377\0\0\0\377") -\end{verbatim} -Now \code{image_bw} is a $2\times2$ grayscale image. The bitmap data -is provided by a string, which contains two black (\code{"\e 0" == -chr(0)}) and two white (\code{"\e 377" == chr(255)}) pixels. Currently -the values per (colour) channel is fixed to 8 bits. The coloured image -\code{image_rgb} has $3\times2$ pixels containing a row of 3 different -gray values and a row of the three colours red, green, and blue. - -The images can then be wrapped into \code{bitmap} instances by: -\begin{verbatim} -bitmap_bw = bitmap.bitmap(0, 1, image_bw, height=0.8) -bitmap_rgb = bitmap.bitmap(0, 0, image_rgb, height=0.8) -\end{verbatim} -When constructing a \code{bitmap} instance you have to specify a -certain position by the first two arguments fixing the bitmaps lower -left corner. Some optional arguments control further properties. Since -in this example there is no information about the dpi-value of the -images, we have to specify at least a \code{width} or a \code{height} -of the bitmap. - -The bitmaps are now to be inserted into a canvas: -\begin{verbatim} -c = canvas.canvas() -c.insert(bitmap_bw) -c.insert(bitmap_rgb) -c.writeEPSfile("bitmap") -\end{verbatim} -Figure~\ref{fig:bitmap} shows the resulting output. -\includegraphics{bitmap} -\centerline{An introductory bitmap example.} - -\section{Bitmap module} -\declaremodule{}{bitmap} -\modulesynopsis{Bitmap support} - -\begin{classdesc}{image}{width, height, mode, data, compressed=None} - This class is a container for image data. \var{width} and - \var{height} are the size of the image in pixel. \var{mode} is one - of \code{\textquotedbl L\textquotedbl}, \code{\textquotedbl - RGB\textquotedbl} or \code{\textquotedbl CMYK\textquotedbl} for - grayscale, rgb, or cmyk colours, respectively. \var{data} is the - bitmap data as a string, where each single character represents a - colour value with ordinal range \code{0} to \code{255}. Each pixel - is described by the appropriate number of colour components - according to \var{mode}. The pixels are listed row by row one after - the other starting at the upper left corner of the image. - - \var{compressed} might be set to \code{\textquotedbl - Flate\textquotedbl} or \code{\textquotedbl DCT\textquotedbl} to - provide already compressed data. Note that those data will be passed - to PostScript without further checks, \emph{i.e.} this option is for - experts only. -\end{classdesc} - -\begin{classdesc}{jpegimage}{file} - This class is specialized to read data from a JPEG/JFIF-file. - \var{file} is either an open file handle (it only has to provide a - \method{read()} method; the file should be opened in binary mode) or - a string. In the latter case \class{jpegimage} will try to open a - file named like \var{file} for reading. - - The contents of the file is checked for some JPEG/JFIF format - markers in order to identify the size and dpi resolution of the - image for further usage. These checks will typically fail for - invalid data. The data are not uncompressed, but directly inserted - into the output stream (for invalid data the result will be invalid - PostScript). Thus there is no quality loss by recompressing the data - as it would occur when recompressing the uncompressed stream with - the lossy jpeg compression method. -\end{classdesc} - -\begin{classdesc}{bitmap}{xpos, ypos, image, width=None, height=None, - ratio=None, storedata=0, maxstrlen=4093, compressmode="Flate", - flatecompresslevel=6, dctquality=75, dctoptimize=1, - dctprogression=0} - \var{xpos} and \var{ypos} are the position of the lower left corner - of the image. This position might be modified by some additional - transformations when inserting the bitmap into a canvas. \var{image} - is an instance of \class{image} or \class{jpegimage} but it can also - be an image instance from the Python Image Library''. - - \var{width}, \var{height}, and \var{ratio} adjust the size of the - image. At least \var{width} or \var{height} needs to be given, when - no dpi information is available from \var{image}. - - \var{storedata} is a flag indicating, that the (still compressed) - image data should be put into the printers memory instead of writing - it as a stream into the PostScript file. While this feature consumes - memory of the PostScript interpreter, it allows for multiple usage - of the image without including the image data several times in the - PostScript file. - - \var{maxstrlen} defines a maximal string length when \var{storedata} - is enabled. Since the data must be kept in the PostScript - interpreters memory, it is stored in strings. While most - interpreters do not allow for an arbitrary string length (a common - limit is 65535 characters), a limit for the string length is set. - When more data need to be stored, a list of strings will be used. - Note that lists are also subject to some implementation limits. Since - a typical value is 65535 entries, in combination a huge amount of - memory can be used. - - Valid values for \var{compressmode} currently are - \code{\textquotedbl Flate\textquotedbl} (zlib compression), - \code{\textquotedbl DCT\textquotedbl} (jpeg compression), or - \code{None} (disabling the compression). The zlib compression makes - use of the zlib module as it is part of the standard Python - distribution. The jpeg compression is available for those - \var{image} instances only, which support the creation of a - jpeg-compressed stream, \emph{e.g.} images from the Python Image - Library'' with jpeg support installed. The compression must be - disabled when the image data is already compressed. - - \var{flatecompresslevel} is a parameter of the zlib compression. - \var{dctquality}, \var{dctoptimize}, and \var{dctprogression} are - parameters of the jpeg compression. Note, that the progression - feature of the jpeg compression should be turned off in order to - produce valid PostScript. Also the optimization feature is known to - produce errors on certain printers. -\end{classdesc} - Deleted: trunk/pyx/manual/box.tex =================================================================== --- trunk/pyx/manual/box.tex 2011-05-20 08:02:19 UTC (rev 3142) +++ trunk/pyx/manual/box.tex 2011-05-20 08:08:24 UTC (rev 3143) @@ -1,96 +0,0 @@ -\chapter{Module box: convex box handling} -\label{module:box} - -This module has a quite internal character, but might still be useful -from the users point of view. It might also get further enhanced to -cover a broader range of standard arranging problems. - -In the context of this module a box is a convex polygon having -optionally a center coordinate, which plays an important role for the -box alignment. The center might not at all be central, but it should -be within the box. The convexity is necessary in order to keep the -problems to be solved by this module quite a bit easier and -unambiguous. - -Directions (for the alignment etc.) are usually provided as pairs -(dx, dy) within this module. It is required, that at least one of -these two numbers is unequal to zero. No further assumptions are taken. - -\section{Polygon} - -A polygon is the most general case of a box. It is an instance of the -class \verb|polygon|. The constructor takes a list of points (which -are (x, y) tuples) in the keyword argument \verb|corners| and -optionally another (x, y) tuple as the keyword argument \verb|center|. -The corners have to be ordered counterclockwise. In the following list -some methods of this \verb|polygon| class are explained: - -\begin{description} -\item[\texttt{path(centerradius=None, bezierradius=None, -beziersoftness=1)}:] returns a path of the box; the center might be -marked by a small circle of radius \verb|centerradius|; the corners -might be rounded using the parameters \verb|bezierradius| and -\verb|beziersoftness|. For each corner of the box there may be one value -for beziersoftness and two bezierradii. For convenience, it is not necessary -to specify the whole list (for beziersoftness) and the whole list of -lists (bezierradius) here. You may give a single value and/or a 2-tuple instead. -\item[\texttt{transform(*trafos)}:] performs a list of transformations -to the box -\item[\texttt{reltransform(*trafos)}:] performs a list of -transformations to the box relative to the box center - -\includegraphics{boxalign} -\centerline{circle and line alignment examples (equal direction and -distance)} - -\item[\texttt{circlealignvector(a, dx, dy)}:] returns a vector (a -tuple (x, y)) to align the box at a circle with radius \verb|a| in -the direction (\verb|dx|, \verb|dy|); see figure~\ref{fig:boxalign} -\item[\texttt{linealignvector(a, dx, dy)}:] as above, but align at a -line with distance \verb|a| -\item[\texttt{circlealign(a, dx, dy)}:] as circlealignvector, but -perform the alignment instead of returning the vector -\item[\texttt{linealign(a, dx, dy)}:] as linealignvector, but -perform the alignment instead of returning the vector -\item[\texttt{extent(dx, dy)}:] extent of the box in the direction -(\verb|dx|, \verb|dy|) -\item[\texttt{pointdistance(x, y)}:] distance of the point (\verb|x|, -\verb|y|) to the box; the point must be outside of the box -\item[\texttt{boxdistance(other)}:] distance of the box to the box -\verb|other|; when the boxes are overlapping, \verb|BoxCrossError| is -raised -\item[\texttt{bbox()}:] returns a bounding box instance appropriate to -the box -\end{description} - -\section{Functions working on a box list} - -\begin{description} -\item[\texttt{circlealignequal(boxes, a, dx, dy)}:] Performs a circle -alignment of the boxes \verb|boxes| using the parameters \verb|a|, -\verb|dx|, and \verb|dy| as in the \verb|circlealign| method. For the -length of the alignment vector its largest value is taken for all -cases. -\item[\texttt{linealignequal(boxes, a, dx, dy)}:] as above, but -performing a line alignment -\item[\texttt{tile(boxes, a, dx, dy)}:] tiles the boxes \verb|boxes| -with a distance \verb|a| between the boxes (in addition the maximal box -extent in the given direction (\verb|dx|, \verb|dy|) is taken into -account) -\end{description} - -\section{Rectangular boxes} - -For easier creation of rectangular boxes, the module provides the -specialized class \verb|rect|. Its constructor first takes four -parameters, namely the x, y position and the box width and height. -Additionally, for the definition of the position of the center, two -keyword arguments are available. The parameter \verb|relcenter| takes -a tuple containing a relative x, y position of the center (they are -relative to the box extent, thus values between \verb|0| and -\verb|1| should be used). The parameter \verb|abscenter| takes a tuple -containing the x and y position of the center. This values are -measured with respect to the lower left corner of the box. By -default, the center of the rectangular box is set to this lower left -corner. - Deleted: trunk/pyx/manual/canvas.tex =================================================================== --- trunk/pyx/manual/canvas.tex 2011-05-20 08:02:19 UTC (rev 3142) +++ trunk/pyx/manual/canvas.tex 2011-05-20 08:08:24 UTC (rev 3143) @@ -1,156 +0,0 @@ -\section{Module \module{canvas}} -\label{canvas} - -\sectionauthor{J\"org Lehmann}{joergl@...} - -One of the central modules for the PostScript access in \PyX{} is -named \verb|canvas|. Besides providing the class \verb|canvas|, which -presents a collection of visual elements like paths, other canvases, -\TeX{} or \LaTeX{} elements, it contains the class -\texttt{canvas.clip} which allows clipping of the output. - -A canvas may also be embedded in another one using its \texttt{insert} -method. This may be useful when you want to apply a transformation on -a whole set of operations.. - -\declaremodule{}{canvas} - -\subsection{Class \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. - -\begin{classdesc}{canvas}{attrs=[], texrunner=None} - Construct a new canvas, applying the given \var{attrs}, which can be - instances of \class{trafo.trafo}, \class{canvas.clip}, - \class{style.strokestyle} or \class{style.fillstyle}. The - \var{texrunner} argument can be used to specify the texrunner - instance used for the \method{text()} method of the canvas. If not - specified, it defaults to \var{text.defaulttexrunner}. -\end{classdesc} - - -Paths can be drawn on the canvas using one of the following methods: - -\begin{methoddesc}{draw}{path, attrs} - Draws \var{path} on the canvas applying the given \var{attrs}. -\end{methoddesc} - -\begin{methoddesc}{fill}{path, attrs=[]} - Fills the given \var{path} on the canvas applying the given - \var{attrs}. -\end{methoddesc} - -\begin{methoddesc}{stroke}{path, attrs=[]} - Strokes the given \var{path} on the canvas applying the given - \var{attrs}. -\end{methoddesc} - -Arbitrary allowed elements like other \class{canvas} instances can -be inserted in the canvas using - -\begin{methoddesc}{insert}{item, attrs=[]} - Inserts an instance of \class{base.canvasitem} into the canvas. If - \var{attrs} are present, \var{item} is inserted into a new - \class{canvas}instance with \var{attrs} as arguments passed to its - constructor is created. Then this \class{canvas} instance is - inserted itself into the canvas. -\end{methoddesc} - -Text output on the canvas is possible using - -\begin{methoddesc}{text}{x, y, text, attrs=[]} - Inserts \var{text} at position (\var{x}, \var{y}) into the - canvas applying \var{attrs}. This is a shortcut for - \texttt{insert(texrunner.text(x, y, text, attrs))}). -\end{methoddesc} - -The \class{canvas} class provides access to the total geometrical size -of its element: - -\begin{methoddesc}{bbox}{} - Returns the bounding box enclosing all elements of the canvas. -\end{methoddesc} - -A canvas also allows one to set its TeX runner: - -\begin{methoddesc}{settexrunner}{texrunner} - Sets a new \var{texrunner} for the canvas. -\end{methoddesc} - -The contents of the canvas can be written using the following two -convenience methods, which wrap the canvas into a single page -document. - -\begin{methoddesc}{writeEPSfile}{file, *args, **kwargs} - Writes the canvas to \var{file} using the EPS format. \var{file} - either has to provide a write method or it is used as a string - containing the filename (the extension \texttt{.eps} is appended - automatically, if it is not present). This method constructs a - single page document, passing \var{args} and \var{kwargs} to the - \class{document.page} constructor and the calls the - \method{writeEPSfile} method of this \class{document.document} - instance passing the \var{file}. -\end{methoddesc} - -\begin{methoddesc}{writePSfile}{file, *args, **kwargs} - Similar to \method{writeEPSfile} but using the PS format. -\end{methoddesc} - -\begin{methoddesc}{writePDFfile}{file, *args, **kwargs} - Similar to \method{writeEPSfile} but using the PDF format. -\end{methoddesc} - -\begin{methoddesc}{writetofile}{filename, *args, **kwargs} - Determine the file type (EPS, PS, or PDF) from the file extension - of \var{filename} and call the corresponding write method with - the given arguments \var{arg} and \var{kwargs}. -\end{methoddesc} - -\begin{methoddesc}{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 - \var{filename} or \var{device} must be set. \var{filename} specifies - the name of the output file. No file extension will be added to that - name in any case. When no \var{filename} is specified, the output is - written to stdout. \var{device} specifies a ghostscript output - device by a string. Depending on your ghostscript configuration - \code{"png16"}, \code{"png16m"}, \code{"png256"}, \code{"png48"}, - \code{"pngalpha"}, \code{"pnggray"}, \code{"pngmono"}, - \code{"jpeg"}, and \code{"jpeggray"} might be available among - others. See the output of \texttt{gs --help} and the ghostscript - documentation for more information. When \var{filename} is specified - but the device is not set, \code{"png16m"} is used when the filename - ends in \texttt{.png} and \code{"jpeg"} is used when the filename - ends in \texttt{.jpg}. - - \var{resolution} specifies the resolution in dpi (dots per inch). - \var{gscmd} is the command to be used to invoke ghostscript. - \var{gsoptions} are an option string passed to the ghostscript - interpreter. \var{textalphabits} are \var{graphicsalphabits} are - conventient parameters to set the \texttt{TextAlphaBits} and - \texttt{GraphicsAlphaBits} options of ghostscript. You can skip - the addition of those option by set their value to \code{None}. - \var{ciecolor} adds the \texttt{-dUseCIEColor} flag to improve - the CMYK to RGB color conversion. \var{input} can be either - \code{"eps"} or \code{"pdf"} to select the input type to be passed - to ghostscript (note slightly different features available in the - different input types). - - \var{kwargs} are passed to the \method{writeEPSfile} method (not - counting the \var{file} parameter), which is used to generate the - input for ghostscript. By that you gain access to the - \class{document.page} constructor arguments. -\end{methoddesc} - -For more information about the possible arguments of the -\class{document.page} constructor, we refer to Sect.~\ref{document}. - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "manual.tex" -%%% End: Deleted: trunk/pyx/manual/color.tex =================================================================== --- trunk/pyx/manual/color.tex 2011-05-20 08:02:19 UTC (rev 3142) +++ trunk/pyx/manual/color.tex 2011-05-20 08:08:24 UTC (rev 3143) @@ -1,102 +0,0 @@ -\chapter{Module color} -\label{color} -\section{Color models} -PostScript provides different color models. They are available to -\PyX{} by different color classes, which just pass the colors down to -the PostScript level. This implies, that there are no conversion -routines between different color models available. However, some color -model conversion routines are included in Python's standard library in -the module \texttt{colorsym}. Furthermore also the comparison of -colors within a color model is not supported, but might be added in -future versions at least for checking color identity and for ordering -gray colors. - -There is a class for each of the supported color models, namely -\verb|gray|, \verb|rgb|, \verb|cmyk|, and \verb|hsb|. The constructors -take variables appropriate for the color model. Additionally, a list of -named colors is given in appendix~\ref{colorname}. - -\section{Example} -\begin{quote} -\begin{verbatim} -from pyx import * - -c = canvas.canvas() - -c.fill(path.rect(0, 0, 7, 3), [color.gray(0.8)]) -c.fill(path.rect(1, 1, 1, 1), [color.rgb.red]) -c.fill(path.rect(3, 1, 1, 1), [color.rgb.green]) -c.fill(path.rect(5, 1, 1, 1), [color.rgb.blue]) - -c.writeEPSfile("color") -\end{verbatim} -\end{quote} - -The file \verb|color.eps| is created and looks like: -\begin{quote} -\includegraphics{color} -\end{quote} - -\section{Color gradients} - -The color module provides a class \verb|gradient| for continous transitions between -colors. A list of named gradients is available in appendix~\ref{gradientname}. - -\begin{classdesc}{gradient}{min=0, max=1} - This class provides the methods for the \verb|gradient|. Different - initializations can be found in \verb|lineargradient| and - \verb|functiongradient|. - - \var{min} and \var{max} provide the valid range of the arguments for - \verb|getcolor|. - - \begin{funcdesc}{getcolor}{parameter} - Returns the color that corresponds to \var{parameter} (must be between - \var{min} and \var{max}). - \end{funcdesc} - - \begin{funcdesc}{select}{index, n\_indices} - When a total number of \var{n\_indices} different colors is needed from the - gradient, this method returns the \var{index}-th color. - \end{funcdesc} - -\end{classdesc} - - -\begin{classdesc}{lineargradient}{startcolor, endcolor, min=0, max=1} - This class provides a linear transition between two given colors. The linear - interpolation is performed on the color components of the specific color - model. - - \var{startcolor} and \var{endcolor} must be colors of the same color model. -\end{classdesc} - -\begin{classdesc}{functiongradient}{functions, type, min=0, max=1} - This class provides an arbitray transition between colors of the same - color model. - - \var{type} is a string indicating the color model (one of \code{"cmyk"}, - \code{"rgb"}, \code{"hsb"}, \code{"grey"}) - - \var{functions} is a dictionary that maps the color components onto given - functions. E.g. for \code{type="rgb"} this dictionary must have the keys - \code{"r"}, \code{"g"}, and \code{"b"}. - -\end{classdesc} - -\section{Transparency} - -\begin{classdesc}{transparency}{value} - Instances of this class will make drawing operations (stroking, - filling) to become partially transparent. \var{value} defines the - transparency factor in the range \code{0} (opaque) to \code{1} - (transparent). - - Transparency is available in PDF output only since it is not - supported by PostScript. However, for certain ghostscript devices - (for example the pdf backend as used by ps2pdf) proprietary - PostScript extension allows for transparency in PostScript code too. - \PyX{} creates such PostScript proprietary code, but issues a - warning when doing so. -\end{classdesc} - Deleted: trunk/pyx/manual/colorname.tex =================================================================== --- trunk/pyx/manual/colorname.tex 2011-05-20 08:02:19 UTC (rev 3142) +++ trunk/pyx/manual/colorname.tex 2011-05-20 08:08:24 UTC (rev 3143) @@ -1,3 +0,0 @@ -\chapter{Named colors} -\label{colorname} -\includegraphics{colorname} Deleted: trunk/pyx/manual/connector.tex =================================================================== --- trunk/pyx/manual/connector.tex 2011-05-20 08:02:19 UTC (rev 3142) +++ trunk/pyx/manual/connector.tex 2011-05-20 08:08:24 UTC (rev 3143) @@ -1,75 +0,0 @@ -\chapter{Module \module{connector}} -\label{connector} - -This module provides classes for connecting two \class{box}-instances with -lines, arcs or curves. All constructors of the following connector-classes take -two \class{box}-instances as the two first arguments. They return a connecting -path from the first to the second box. The overall geometry of the path is such -that is starts/ends at the boxes' centers. It is then cut by the boxes' -outlines. The resulting \class{connector} will additionally be shortened by -lengths given in the \keyword{boxdists}-keyword (a list of two lengths, default -\code{[0,0]}). - -Angle keywords can be either absolute or relative. The absolute angles refer to -the angle between x-axis and the running tangent of the connector, while the -relative angles are between the direct connecting line of the box-centers and -the running tangent (see figure.~\ref{fig:connector}). - -The bulge-keywords parameterize the deviation of the connector from the -connecting line. It has different meanings for different connectors (see -figure.~\ref{fig:connector}). - -\section{Class \class{line}} - -The constructor of the \class{line} class accepts only boxes and the -\keyword{boxdists}-keyword. - -\section{Class \class{arc}} - -The constructor takes either the \keyword{relangle}-keyword or a -combination of \keyword{relbulge} and \keyword{absbulge}. The bulge'' is -meant to be a hint for the greatest distance between the connecting arc and the -straight connection between the box-centers. (Default: \code{relangle=45}, -\code{relbulge=None}, \code{absbulge=None})\smallskip - -Note that the bulge-keywords override the angle-keyword. - -If both \keyword{relbulge} and \keyword{absbulge} are given, they will be -added. - -\section{Class \class{curve}} - -The constructor takes both angle- and bulge-keywords. Here, the bulges are -used as distances between the control points of the cubic Bezi\'er-curve. -For the signs of the angle- and bulge-keywords refer to figure~\ref{fig:connector}. - -\keyword{absangle1} or \keyword{relangle1}\\ -\keyword{absangle2} or \keyword{relangle2}, where the absolute angle overrides the -relative if both are given. (Default: \code{relangle1=45}, -\code{relangle2=45}, \code{absangle1=None}, \code{absangle2=None})\medskip - -\keyword{absbulge} and \keyword{relbulge}, where they will be added if both are -given.\\ (Default: \code{absbulge=None}, \code{relbulge=0.39}; these default -values produce output similar to the defaults of \class{arc}.)\medskip - - -\includegraphics{connector} -\centerline{The angle-parameters of the connector.arc (left panel) and the -connector.curve (right panel) classes.} - -\section{Class \class{twolines}} - -This class returns two connected straight lines. There is a vast variety of -combinations for angle- and length-keywords. The user has to make sure to -provide a non-ambiguous set of keywords:\medskip - -\keyword{absangle1} or \keyword{relangle1} for the first angle,\\ -\keyword{relangleM} for the middle angle and\\ -\keyword{absangle2} or \keyword{relangle2} for the ending angle. -Again, the absolute angle overrides the relative if both are given. (Default: -all five angles are \code{None})\medskip - -\keyword{length1} and \keyword{length2} for the lengths of the connecting lines. -(Default: \code{None}) - - Deleted: trunk/pyx/manual/deformer.tex =================================================================== --- trunk/pyx/manual/deformer.tex 2011-05-20 08:02:19 UTC (rev 3142) +++ trunk/pyx/manual/deformer.tex 2011-05-20 08:08:24 UTC (rev 3143) @@ -1,130 +0,0 @@ -\section{Module \module{deformer}} -\label{deformer} - -\declaremodule{}{deformer} -\modulesynopsis{Path deformers} - -The \module{deformer} module provides techniques to generate modulated paths. -All classes in the \module{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 \module{deco} -module is that here, a totally new path is constructed. - -All classes of the \module{deformer} module provide the following methods: - -\begin{classdesc}{deformer}{} - DUMMY -\end{classdesc} - -\begin{methoddesc}{__call__}{(specific parameters for the class)} -Returns a deformer with modified parameters -\end{methoddesc} - -\begin{methoddesc}{deform}{path} Returns the deformed normpath on the basis of -the \var{path}. This method allows using the deformers outside of a -drawing call. -\end{methoddesc} - -The deformer classes are the following: - -\begin{classdesc}{cycloid}{radius, halfloops=10, skipfirst=1*unit.t_cm, -skiplast=1*unit.t_cm, curvesperhloop=3, sign=1, turnangle=45} -This deformer creates a cycloid around a path. The outcome looks similar to -a 3D spring stretched along the original path. - -\var{radius}: the radius of the cycloid (this is the radius of the 3D spring) - -\var{halfloops}: the number of half-loops of the cycloid - -\var{skipfirst} and \var{skiplast}: the lengths on the original path not to be bent to a cycloid - -\var{curvesperhloop}: the number of Bezier curves to approximate a half-loop - -\var{sign}: with \code{sign>=0} starts the cycloid to the left of the path, \code{sign<0} to the right. - -\var{turnangle}: the angle of perspective on the 3D spring. At -\code{turnangle=0} one sees a sinusoidal curve, at \code{turnangle=90} one -essentially sees a circle. -\end{classdesc} - -\begin{classdesc}{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! -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 $2\times$\var{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 in a \textit{geometrically smooth} way. Path elements that are shorter than -\var{radius}$\times$\var{relskipthres} are ignored. - -The new curve smoothing the corner consists either of one or of two Bezier -curves, depending on the surrounding path elements. If there are straight lines -before and after the new curve, then two Bezier curves are used. This optimises -the bending of curves in rectangular boxes or polygons. Here, the curves have -an additional degree of freedom that can be set with \var{softness} $\in(0,1]$. -If one of the concerned path elements is curved, only one Bezier curve is used -that is (not always uniquely) determined by its geometrical constraints. There -are, nevertheless, some \textit{caveats}: - -A curve that strictly obeys the sign and magnitude of the curvature might not -look very smooth in some cases. Especially when connecting a curved with a -straight piece, the smoothed path contains unwanted overshootings. To prevent -this, the parameter default \var{obeycurv=0} releases the curvature constraints a -little: The curvature may then change its sign (still looks smooth for human -eyes) or, in more extreme cases, even its magnitude (does not look so smooth). -If you really need a geometrically smooth path on the basis of Bezier curves, -then set \var{obeycurv=1}. -\end{classdesc} - -\begin{classdesc}{parallel}{distance, relerr=0.05, sharpoutercorners=0, dointersection=1, - checkdistanceparams=[0.5], lookforcurvatures=11}% -This deformer creates a parallel curve to a given path. The result is similar to -what is usually referred to as the \emph{set with constant distance} to the set of -points on the path. It differs in one important respect, because the -\var{distance} parameter in the deformer is a signed distance. The resulting -parallel normpath is constructed on the level of the original pathitems. For -each of them a parallel pathitem is constructed. Then, they are connected by -circular arcs (or by sharp edges) around the corners of the original path. -Later, everything that is nearer to the original path than distance is cut away. - -There are some caveats: -\begin{itemize} - \item When the original path is too curved then the parallel path would - contain points with infinte curvature. The resulting path stops at such points - and leaves the too strongly curved piece out. - \item 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. -\end{itemize} - -The parameters are the following: - -\var{distance} is the minimal (signed) distance between the original and the -parallel paths. - -\var{relerr} is the allowed error in the distance is given by -\code{distance*relerr}. - -\var{sharpoutercorners} connects the parallel pathitems by wegde build of -straight lines, instead of taking circular arcs. This preserves the angle of the -original corners. - -\var{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. - -\var{checkdistanceparams} is a list of parameter values in the interval (0,1) -where the distance is checked on each parallel pathitem - -\var{lookforcurvatures} is the number of points per normpathitem where its -curvature is checked for critical values - -\end{classdesc} - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "manual.tex" -%%% ispell-dictionary: "british" -%%% End: Deleted: trunk/pyx/manual/document.tex =================================================================== --- trunk/pyx/manual/document.tex 2011-05-20 08:02:19 UTC (rev 3142) +++ trunk/pyx/manual/document.tex 2011-05-20 08:08:24 UTC (rev 3143) @@ -1,109 +0,0 @@ -\section{Module \module{document}} -\label{document} - -\sectionauthor{J\"org Lehmann}{joergl@...} - -\declaremodule{}{document} - - - -The document module contains two classes: \class{document} and -\class{page}. A \class{document} consists of one or several -\class{page}s. - - -\subsection{Class \class{page}} - -A \class{page} is a thin wrapper around a \class{canvas}, which -defines some additional properties of the page. - -\begin{classdesc}{page}{canvas, pagename=None, - paperformat=None, rotated=0, centered=1, fittosize=0, - margin=1 * unit.t_cm, bboxenlarge=1 * unit.t_pt, bbox=None} - Construct a new \class{page} from the given \class{canvas} instance. - A string \var{pagename} and the \var{paperformat} can be - defined. See below, for a list of known paper formats. - If \var{rotated} is set, the output is rotated by 90 degrees on the - page. If \var{centered} is set, the output is centered on the given - paperformat. If \var{fittosize} is set, the output is scaled to fill - the full page except for a given \var{margin}. - Normally, the bounding box of the canvas is calculated automatically - from the bounding box of its elements. Alternatively, you may - specify the \var{bbox} manually. In any case, the bounding box is - enlarged on all sides by \var{bboxenlarge}. -\end{classdesc} - -\subsection{Class \class{document}} - -\begin{classdesc}{document}{pages=[]} - Construct a \class{document} consisting of a given list of \var{pages}. -\end{classdesc} - -A \class{document} can be written to a file using one of the following methods: - -\begin{methoddesc}{writeEPSfile}{file, title=None, strip_fonts=True, - text_as_path=False, mesh_as_bitmap=False, mesh_as_bitmap_resolution=300} - Write a single page \class{document} to an EPS file. \var{title} - is used as the document title, \var{strip_fonts} enabled font - stripping (removal of unused glyphs), \var{text_as_path} converts - all text to paths instead of using fonts in the output, - \var{mesh_as_bitmap} converts meshs (like 3d surface plots) to - bitmaps (to reduce complexity in the output) and - \var{mesh_as_bitmap_resolution} is the resolution of this conversion - in dots per inch. -\end{methoddesc} - -\begin{methoddesc}{writePSfile}{file, writebbox=False, title=None, strip_fonts=True, - text_as_path=False, mesh_as_bitmap=False, mesh_as_bitmap_resolution=300} - Write \class{document} to a PS file. \var{writebbox} add the page - bounding boxes to the output. All other parameters are identical to - the \method{writeEPSfile} method. -\end{methoddesc} - -\begin{methoddesc}{writePDFfile}{file, title=None, author=None, subject=None, -keywords=None, fullscreen=False, writebbox=False, compress=True, compresslevel=6, -strip_fonts=True, text_as_path=False, mesh_as_bitmap=False, mesh_as_bitmap_resolution=300} - Write \class{document} to a PDF file. \var{author}, \var{subject}, - and \var{keywords} are used for the document author, subject, and - keyword information, respectively. \var{fullscreen} enabled - fullscreen mode when the document is opened, \var{writebbox} enables - writing of the crop box to each page, \var{compress} enables output - stream compression and \var{compresslevel} sets the compress level - to be used (from 1 to 9). All other parameters are identical to the - \method{writeEPSfile}. -\end{methoddesc} - -\begin{methoddesc}{writetofile}{filename, *args, **kwargs} - Determine the file type (EPS, PS, or PDF) from the file extension - of \var{filename} and call the corresponding write method with - the given arguments \var{arg} and \var{kwargs}. -\end{methoddesc} - -\subsection{Class \class{paperformat}} - -\begin{classdesc}{paperformat}{width, height, name=None} -Define a \class{paperformat} with the given \var{width} and -\var{height} and the optional \var{name}. -\end{classdesc} - -Predefined paperformats are listed in the following table -\medskip -\begin{tableiv}{l|l|l|l}{textrm}{instance}{name}{width}{height} -\lineiv{\constant{document.paperformat.A0}}{A0}{840 mm}{1188 mm} -\lineiv{\constant{document.paperformat.A0b}}{}{910 mm}{1370 mm} -\lineiv{\constant{document.paperformat.A1}}{A1}{594 mm}{840 mm} -\lineiv{\constant{document.paperformat.A2}}{A2}{420 mm}{594 mm} -\lineiv{\constant{document.paperformat.A3}}{A3}{297 mm}{420 mm} -\lineiv{\constant{document.paperformat.A4}}{A4}{210 mm}{297 mm} -\lineiv{\constant{document.paperformat.A5}}{A5}{148.5 mm}{210 mm} -\lineiv{\constant{document.paperformat.Letter}}{Letter}{8.5 inch}{11 inch} -\lineiv{\constant{document.paperformat.Legal}}{Legal}{8.5 inch}{14 inch} -\end{tableiv} -\medskip - - - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "manual.tex" -%%% End: Deleted: trunk/pyx/manual/epsfile.tex =================================================================== --- trunk/pyx/manual/epsfile.tex 2011-05-20 08:02:19 UTC (rev 3142) +++ trunk/pyx/manual/epsfile.tex 2011-05-20 08:08:24 UTC (rev 3143) @@ -1,41 +0,0 @@ -\chapter{Module epsfile: EPS file inclusion} - -With the help of the \verb|epsfile.epsfile| class, you can easily embed -another EPS file in your canvas, thereby scaling, aligning the content -at discretion. The most simple example looks like -\begin{quote} -\begin{verbatim} -from pyx import * -c = canvas.canvas() -c.insert(epsfile.epsfile(0, 0, "file.eps")) -c.writeEPSfile("output") -\end{verbatim} -\end{quote} - -All relevant parameters are passed to the \verb|epsfile.epsfile| -constructor. They are summarized in the following table: - -\medskip -\begin{tableii}{l|l}{textrm}{argument name}{description} -\lineii{\texttt{x}}{$x$-coordinate of position.} -\lineii{\texttt{y}}{$y$-coordinate of position.} -\lineii{\texttt{filename}}{Name of the EPS file (including a possible extension).} -\lineii{\texttt{width=None}}{Desired width of EPS graphics or \texttt{None} for original width. Cannot be combined with scale specification.} -\lineii{\texttt{height=None}}{Desired height of EPS graphics or \texttt{None} for original height. Cannot be combined with scale specification.} -\lineii{\texttt{scale=None}}{Scaling factor for EPS graphics or \texttt{None} for no scaling. Cannot be combined with width or height specification.} -\lineii{\texttt{align="bl"}}{Alignment of EPS graphics. The first character specifies the vertical alignment: \texttt{b} for bottom, \texttt{c} for center, and \texttt{t} for top. The second character fixes the horizontal alignment: \texttt{l} for left, \texttt{c} for center \texttt{r} for right.} -\lineii{\texttt{clip=1}}{Clip to bounding box of EPS file?} -\lineii{\texttt{translatebbox=1}}{Use lower left corner of bounding box of EPS file? Set to $0$ with care.} -\lineii{\texttt{bbox=None}}{If given, use \texttt{bbox} instance instead of bounding box of EPS file.} -\lineii{\texttt{kpsearch=0}}{Search for file using the kpathsea library.} -\end{tableii} - - - -\label{epsfile} - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "manual.tex" -%%% End: - Deleted: trunk/pyx/manual/gradientname.tex =================================================================== --- trunk/pyx/manual/gradientname.tex 2011-05-20 08:02:19 UTC (rev 3142) +++ trunk/pyx/manual/gradientname.tex 2011-05-20 08:08:24 UTC (rev 3143) @@ -1,3 +0,0 @@ -\chapter{Named gradients} -\label{gradientname} -\includegraphics{gradientname} Deleted: trunk/pyx/manual/graph.tex =================================================================== --- trunk/pyx/manual/graph.tex 2011-05-20 08:02:19 UTC (rev 3142) +++ trunk/pyx/manual/graph.tex 2011-05-20 08:08:24 UTC (rev 3143) @@ -1,1130 +0,0 @@ -\chapter{Graphs} -\label{graph} - -\section{Introduction} % {{{ -\PyX{} can be used for data and function plotting. At present -x-y-graphs and x-y-z-graphs are supported only. However, the component -architecture of the graph system described in section -\ref{graph:components} allows for additional graph geometries while -reusing most of the existing components. - -Creating a graph splits into two basic steps. First you have to create -a graph instance. The most simple form would look like: -\begin{verbatim} -from pyx import * -g = graph.graphxy(width=8) -\end{verbatim} -The graph instance \code{g} created in this example can then be used -to actually plot something into the graph. Suppose you have some data -in a file \file{graph.dat} you want to plot. The content of the file -could look like: -\verbatiminput{graph.dat} -To plot these data into the graph \code{g} you must perform: -\begin{verbatim} -g.plot(graph.data.file("graph.dat", x=1, y=2)) -\end{verbatim} -The method \method{plot()} takes the data to be plotted and optionally -a list of graph styles to be used to plot the data. When no styles are -provided, a default style defined by the data instance is used. For -data read from a file by an instance of \class{graph.data.file}, the -default are symbols. When instantiating \class{graph.data.file}, you -not only specify the file name, but also a mapping from columns to -axis names and other information the styles might make use of -(\emph{e.g.} data for error bars to be used by the errorbar style). - -While the graph is already created by that, we still need to perform a -write of the result into a file. Since the graph instance is a canvas, -we can just call its \method{writeEPSfile()} method. -\begin{verbatim} -g.writeEPSfile("graph") -\end{verbatim} -The result \file{graph.eps} is shown in figure~\ref{fig:graph}. - -\includegraphics{graph} -\centerline{A minimalistic plot for the data from file \file{graph.dat}.} - -Instead of plotting data from a file, other data source are available -as well. For example function data is created and placed into -\method{plot()} by the following line: -\begin{verbatim} -g.plot(graph.data.function("y(x)=x**2")) -\end{verbatim} -You can plot different data in a single graph by calling -\method{plot()} several times before \method{writeEPSfile()} or -\method{writePDFfile()}. Note that a calling \method{plot()} will fail -once a graph was forced to finish'' itself. This happens -automatically, when the graph is written to a file. Thus it is not an -option to call \method{plot()} after \method{writeEPSfile()} or -\method{writePDFfile()}. The topic of the finalization of a graph is -addressed in more detail in section~\ref{graph:graph}. As you can see -in figure~\ref{fig:graph2}, a function is plotted as a line by -default. - -\includegraphics{graph2} -\centerline{Plotting data from a file together with a function.} - -While the axes ranges got adjusted automatically in the previous -example, they might be fixed by keyword options in axes constructors. -Plotting only a function will need such a setting at least in the -variable coordinate. The following code also shows how to set a -logathmic axis in y-direction: - -\verbatiminput{graph3.py} - -The result is shown in figure~\ref{fig:graph3}. - -\includegraphics{graph3} -\centerline{Plotting a function for a given axis range and use a logarithmic y-axis.} - -\section{Component architecture} % {{{ -\label{graph:components} - -Creating a graph involves a variety of tasks, which thus can be -separated into components without significant additional costs. -This structure manifests itself also in the \PyX{} source, where there -are different modules for the different tasks. They interact by some -well-defined interfaces. They certainly have to be completed and -stabilized in their details, but the basic structure came up in the -continuous development quite clearly. The basic parts of a graph are: - -\begin{definitions} -\term{graph} - Defines the geometry of the graph by means of graph coordinates with - range [0:1]. Keeps lists of plotted data, axes \emph{etc.} -\term{data} - Produces or prepares data to be plotted in graphs. -\term{style} - Performs the plotting of the data into the graph. It gets data, - converts them via the axes into graph coordinates and uses the graph - to finally plot the data with respect to the graph geometry methods. -\term{key} - Responsible for the graph keys. -\term{axis} - Creates axes for the graph, which take care of the mapping from data - values to graph coordinates. Because axes are also responsible for - creating ticks and labels, showing up in the graph themselves and - other things, this task is splitted into several independent - subtasks. Axes are discussed separately in chapter~\ref{axis}. -\end{definitions} % }}} - -\section{Module \module{graph.graph}: Graphs} % {{{ -\label{graph:graph} - -\declaremodule{}{graph.graph} -\modulesynopsis{Graph geometry} - -The classes \class{graphxy} and \class{graphxyz} are part of the -module \module{graph.graph}. However, there are shortcuts to access -the classes via \code{graph.graphxy} and \code{graph.graphxyz}, -respectively. - -\begin{classdesc}{graphxy}{xpos=0, ypos=0, width=None, height=None, -ratio=goldenmean, key=None, backgroundattrs=None, -axesdist=0.8*unit.v\_cm, xaxisat=None, yaxisat=None, **axes} - This class provides an x-y-graph. A graph instance is also a fully - functional canvas. - - The position of the graph on its own canvas is specified by - \var{xpos} and \var{ypos}. The size of the graph is specified by - \var{width}, \var{height}, and \var{ratio}. These parameters define - the size of the graph area not taking into account the additional - space needed for the axes. Note that you have to specify at least - \var{width} or \var{height}. \var{ratio} will be used as the ratio - between \var{width} and \var{height} when only one of these is - provided. - - \var{key} can be set to a \class{graph.key.key} instance to create - an automatic graph key. \code{None} omits the graph key. - - \var{backgroundattrs} is a list of attributes for drawing the - background of the graph. Allowed are decorators, strokestyles, and - fillstyles. \code{None} disables background drawing. - - \var{axisdist} is the distance between axes drawn at the same side - of a graph. - - \var{xaxisat} and \var{yaxisat} specify a value at the y and x axis, - where the corresponding axis should be moved to. It's a shortcut for - corresonding calls of \method{axisatv()} described below. Moving an - axis by \var{xaxisat} or \var{yaxisat} disables the automatic - creation of a linked axis at the opposite side of the graph. - - \var{**axes} receives axes instances. Allowed keywords (axes names) - are \code{x}, \code{x2}, \code{x3}, \emph{etc.} and \code{y}, - \code{y2}, \code{y3}, \emph{etc.} When not providing an \code{x} or - \code{y} axis, linear axes instances will be used automatically. - When not providing a \code{x2} or \code{y2} axis, linked axes to the - \code{x} and \code{y} axes are created automatically and \emph{vice - versa}. As an exception, a linked axis is not created automatically - when the axis is placed at a specific position by \var{xaxisat} or - \var{yaxisat}. You can disable the automatic creation of axes by - setting the linked axes to \code{None}. The even numbered axes are - plotted at the top (\code{x} axes) and right (\code{y} axes) while - the others are plotted at the bottom (\code{x} axes) and left - (\code{y} axes) in ascending order each. -\end{classdesc} - -Some instance attributes might be useful for outside read-access. -Those are: - -\begin{memberdesc}{axes} - A dictionary mapping axes names to the \class{anchoredaxis} instances. -\end{memberdesc} - -To actually plot something into the graph, the following instance -method \method{plot()} is provided: - -\begin{methoddesc}{plot}{data, styles=None} - Adds \var{data} to the list of data to be plotted. Sets \var{styles} - to be used for plotting the data. When \var{styles} is \code{None}, - the default styles for the data as provided by \var{data} is used. - - \var{data} should be an instance of any of the data described in - section~\ref{graph:data}. - - When the same combination of styles (\emph{i.e.} the same - references) are used several times within the same graph instance, - the styles are kindly asked by the graph to iterate their - appearance. Its up to the styles how this is performed. - - Instead of calling the plot method several times with different - \var{data} but the same style, you can use a list (or something - iterateable) for \var{data}. -\end{methoddesc} - -While a graph instance only collects data initially, at a certain -point it must create the whole plot. Once this is done, further calls -of \method{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 -\method{do}-methods yourself you can also alter the order in which the -graph components are plotted. Multiple calls to any of the -\method{do}-methods have no effect (only the first call counts). The -orginal order in which the \method{do}-methods are called is: - -\begin{methoddesc}{dolayout}{} - Fixes the layout of the graph. As part of this work, the ranges of - the axes are fitted to the data when the axes ranges are allowed to - adjust themselves to the data ranges. The other \method{do}-methods - ensure, that this method is always called first. -\end{methoddesc} - -\begin{methoddesc}{dobackground}{} - Draws the background. -\end{methoddesc} - -\begin{methoddesc}{doaxes}{} - Inserts the axes. -\end{methoddesc} - -\begin{methoddesc}{doplotitem}{plotitem} - Plots the plotitem as returned by the graphs plot method. -\end{methoddesc} - -\begin{methoddesc}{doplot}{} - Plots all (remaining) plotitems. -\end{methoddesc} - -\begin{methoddesc}{dokeyitem}{} - Inserts a plotitem in the graph key as returned by the graphs plot method. -\end{methoddesc} - -\begin{methoddesc}{dokey}{} - Inserts the graph key. -\end{methoddesc} - -\begin{methoddesc}{finish}{} - Finishes the graph by calling all pending \method{do}-methods. This - is done automatically, when the output is created. -\end{methoddesc} - -The graph provides some methods to access its geometry: - -\begin{methoddesc}{pos}{x, y, xaxis=None, yaxis=None} - Returns the given point at \var{x} and \var{y} as a tuple - \code{(xpos, ypos)} at the graph canvas. \var{x} and \var{y} are - anchoredaxis instances for the two axes \var{xaxis} and \var{yaxis}. - When \var{xaxis} or \var{yaxis} are \code{None}, the axes with names - \code{x} and \code{y} are used. This method fails if called before - \method{dolayout()}. -\end{methoddesc} - -\begin{methoddesc}{vpos}{vx, vy} - Returns the given point at \var{vx} and \var{vy} as a tuple - \code{(xpos, ypos)} at the graph canvas. \var{vx} and \var{vy} are - graph coordinates with range [0:1]. -\end{methoddesc} - -\begin{methoddesc}{vgeodesic}{vx1, vy1, vx2, vy2} - Returns the geodesic between points \var{vx1}, \var{vy1} and - \var{vx2}, \var{vy2} as a path. All parameters are in graph - coordinates with range [0:1]. For \class{graphxy} this is a straight - line. -\end{methoddesc} - -\begin{methoddesc}{vgeodesic\_el}{vx1, vy1, vx2, vy2} - Like \method{vgeodesic()} but this method returns the path element to - connect the two points. -\end{methoddesc} - -% dirty hack to add a whole list of methods to the index: -\index{xbasepath()@\texttt{xbasepath()} (graphxy method)} -\index{xvbasepath()@\texttt{xvbasepath()} (graphxy method)} -\index{xgridpath()@\texttt{xgridpath()} (graphxy method)} -\index{xvgridpath()@\texttt{xvgridpath()} (graphxy method)} -\index{xtickpoint()@\texttt{xtickpoint()} (graphxy method)} -\index{xvtickpoint()@\texttt{xvtickpoint()} (graphxy method)} -\index{xtickdirection()@\texttt{xtickdirection()} (graphxy method)} -\index{xvtickdirection()@\texttt{xvtickdirection()} (graphxy method)} -\index{ybasepath()@\texttt{ybasepath()} (graphxy method)} -\index{yvbasepath()@\texttt{yvbasepath()} (graphxy method)} -\index{ygridpath()@\texttt{ygridpath()} (graphxy method)} -\index{yvgridpath()@\texttt{yvgridpath()} (graphxy method)} @@ Diff output truncated at 100000 characters. @@ This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. 
 [PyX-checkins] SF.net SVN: pyx:[3146] trunk/pyx/manual From: - 2011-05-20 08:36:41 Revision: 3146 http://pyx.svn.sourceforge.net/pyx/?rev=3146&view=rev Author: wobsta Date: 2011-05-20 08:36:34 +0000 (Fri, 20 May 2011) Log Message: ----------- new build infrastructure Modified Paths: -------------- trunk/pyx/manual/Makefile Added Paths: ----------- trunk/pyx/manual/_static/ trunk/pyx/manual/_templates/ trunk/pyx/manual/conf.py Modified: trunk/pyx/manual/Makefile =================================================================== --- trunk/pyx/manual/Makefile 2011-05-20 08:32:20 UTC (rev 3145) +++ trunk/pyx/manual/Makefile 2011-05-20 08:36:34 UTC (rev 3146) @@ -1,54 +1,39 @@ -# You need mkhowto from the python distribution for creating this manual. -# Get a copy of a current python source archive and make a symbolic link -# from /Python-x.x.x/Doc/tools/mkhowto into this directory. -# Furthermore you need tex, latex2html and a few other things to build -# the manual (see the python documentation about creating documentations -# for details). +# Makefile for Sphinx documentation +# PYTHON ?= python -default: dvi +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build -clean: - -rm -fr manual.dvi *.eps *.pdf *.aux *.out *.toc *.log manual +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees$(PAPEROPT_$(PAPER))$(SPHINXOPTS) . -all: - make clean - make html - make pdf - make dvi +.PHONY: help clean all html latexpdf figs -src=$(wildcard *.tex) pyxversion.tex pyxdate.tex +all: html latexpdf + @echo "Done." -dvi: manual.dvi -pdf: manual.pdf -html: manual/manual.html +clean: + -rm -rf$(BUILDDIR)/* *.eps *.pdf *.png -manual.pdf: $(src) pdf_figs - #for index-with-own-hyperrefs debugging, anybody interested? - #./mkhowto --a4 --pdf --keep manual.tex - ./mkhowto --a4 --pdf manual.tex +html: figs +$(SPHINXBUILD) -b html $(ALLSPHINXOPTS)$(BUILDDIR)/html + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." -manual.dvi:$(src) eps_figs - ./mkhowto --a4 --dvi manual.tex +latexpdf: figs + $(SPHINXBUILD) -b latex$(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + make -C$(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." -manual/manual.html:$(src) eps_figs - ./mkhowto --image-type png --favicon "/pyx.ico" \ - --up-link "/" --up-title "PyX homepage" \ - --html manual.tex +figs: $(patsubst %.py, %.png,$(filter-out conf.py,$(wildcard *.py))) -pyxversion.tex: ../pyx/version.py -$(PYTHON) -c "import sys;sys.path[:0]=[\"..\"];import pyx.version;print pyx.version.version+'%'" > pyxversion.tex - -pyxdate.tex: ../pyx/version.py - $(PYTHON) -c "import sys;sys.path[:0]=[\"..\"];import pyx.version;print pyx.version.date+'%'" > pyxdate.tex - -eps_figs:$(patsubst %.py, %.eps, $(wildcard *.py)) - -pdf_figs:$(patsubst %.py, %.pdf, $(wildcard *.py)) - -%.eps: %.py +%.png: %.py export PYTHONPATH=$(CURDIR)/.. ; $(PYTHON)$^ - -%.pdf: %.py - export PYTHONPATH=$(CURDIR)/.. ;$(PYTHON) $^ +$(PYTHON) ../contrib/epstopng.py -o $@$*.eps Added: trunk/pyx/manual/conf.py =================================================================== --- trunk/pyx/manual/conf.py (rev 0) +++ trunk/pyx/manual/conf.py 2011-05-20 08:36:34 UTC (rev 3146) @@ -0,0 +1,222 @@ +# -*- coding: utf-8 -*- +# +# PyX documentation build configuration file, created by +# sphinx-quickstart on Thu May 19 17:32:57 2011. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os +sys.path.insert(0, '..') +import pyx.version + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['mathjax'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'manual' + +# General information about the project. +project = u'PyX' +copyright = u'2011, Jörg Lehmann, Michael Schindler, André Wobst' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '.'.join(pyx.version.version.split('.')[:1]) +# The full version, including alpha/beta/rc tags. +release = pyx.version.version + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +today = pyx.version.date +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: text) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'PyXdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('manual', 'PyX.tex', u'PyX Documentation', + u'Jörg Lehmann, Michael Schindler, André Wobst', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('manual', 'pyx', u'PyX Documentation', + [u'Jörg Lehmann, Michael Schindler, André Wobst'], 1) +] + +# -- Other options ------------------------------------------------------------ + +mathjax_path = 'http://mathjax.connectmv.com/MathJax.js'; Property changes on: trunk/pyx/manual/conf.py ___________________________________________________________________ Added: svn:keywords + LastChangedRevision LastChangedBy HeadURL This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. 
 [PyX-checkins] SF.net SVN: pyx:[3149] trunk/pyx/manual From: - 2011-05-20 10:31:25 Revision: 3149 http://pyx.svn.sourceforge.net/pyx/?rev=3149&view=rev Author: wobsta Date: 2011-05-20 10:31:17 +0000 (Fri, 20 May 2011) Log Message: ----------- various documentation fixes Modified Paths: -------------- trunk/pyx/manual/arrows.rst trunk/pyx/manual/axis.rst trunk/pyx/manual/bbox.rst trunk/pyx/manual/bitmap.rst trunk/pyx/manual/box.rst trunk/pyx/manual/canvas.rst trunk/pyx/manual/color.rst trunk/pyx/manual/colorname.rst trunk/pyx/manual/connector.rst trunk/pyx/manual/deformer.rst trunk/pyx/manual/document.rst trunk/pyx/manual/epsfile.rst trunk/pyx/manual/gradientname.rst trunk/pyx/manual/graph.rst trunk/pyx/manual/graphics.rst trunk/pyx/manual/manual.rst trunk/pyx/manual/path.rst trunk/pyx/manual/pathstyles.rst trunk/pyx/manual/pattern.rst trunk/pyx/manual/text.rst trunk/pyx/manual/trafo.rst trunk/pyx/manual/unit.rst Modified: trunk/pyx/manual/arrows.rst =================================================================== --- trunk/pyx/manual/arrows.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/arrows.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,12 +1,13 @@ .. _arrows: -********************* -Arrows in deco module -********************* +******************************* +Appendix: Arrows in deco module +******************************* -.. % DUMMY -.. _fig_label: +.. _fig_arrows: .. figure:: arrows.* :align: center + Arrows in deco module + Modified: trunk/pyx/manual/axis.rst =================================================================== --- trunk/pyx/manual/axis.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/axis.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,5 +1,5 @@ -.. _axis: +.. module:: axis **** Axes @@ -64,13 +64,11 @@ .. % }}} +.. module:: graph.axis.axis + Module :mod:graph.axis.axis: Axes =================================== -.. module:: graph.axis.axis - :synopsis: Axes - - .. % {{{ The following classes are part of the module :mod:graph.axis.axis. However, @@ -204,9 +202,6 @@ .. class:: anchoredaxis() - DUMMY - - .. method:: anchoredaxis.basepath(x1=None, x2=None) Returns a path instance for the base path. *x1* and *x2* define the axis range, @@ -294,12 +289,10 @@ .. % }}} -Module :mod:graph.axis.tick: Ticks -==================================== - .. module:: graph.axis.tick - :synopsis: Axes ticks +Module :mod:graph.axis.tick: Axes ticks +========================================= .. % {{{ @@ -352,12 +345,10 @@ .. % }}} -Module :mod:graph.axis.parter: Partitioners -============================================= - .. module:: graph.axis.parter - :synopsis: Axes partitioners +Module :mod:graph.axis.parter: Axes partitioners +================================================== .. % {{{ @@ -512,12 +503,10 @@ .. % }}} -Module :mod:graph.axis.texter: Texter -======================================= - .. module:: graph.axis.texter - :synopsis: Axes texters +Module :mod:graph.axis.texter: Axes texter +============================================ .. % {{{ @@ -634,12 +623,10 @@ .. % }}} -Module :mod:graph.axis.painter: Painter -========================================= - .. module:: graph.axis.painter - :synopsis: Axes painters +Module :mod:graph.axis.painter: Axes painter +============================================== .. % {{{ @@ -769,12 +756,10 @@ .. % }}} -Module :mod:graph.axis.rater: Rater -===================================== - .. module:: graph.axis.rater - :synopsis: Axes raters +Module :mod:graph.axis.rater: Axes rater +========================================== .. % {{{ @@ -854,12 +839,10 @@ .. % }}} -Module :mod:graph.axis.positioner: Positioners -================================================ - .. module:: graph.axis.positioners - :synopsis: Axes positioners +Module :mod:graph.axis.positioner: Axes positioners +===================================================== .. % {{{ @@ -869,9 +852,6 @@ .. class:: positioner() - DUMMY - - .. method:: positioner.vbasepath(v1=None, v2=None) Returns a path instance for the base path. *v1* and *v2* define the axis range Modified: trunk/pyx/manual/bbox.rst =================================================================== --- trunk/pyx/manual/bbox.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/bbox.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,11 +1,10 @@ +.. module:: bbox -*********** -Module bbox -*********** +****************** +Module :mod:bbox +****************** -.. _bbox: - -The bbox module contains the definition of the bbox class representing +The :mod:bbox module contains the definition of the :class:bbox class representing bounding boxes of graphical elements like paths, canvases, etc. used in PyX. Usually, you obtain bbox instances as return values of the corresponding bbox()) method, but you may also construct a bounding box by yourself. Modified: trunk/pyx/manual/bitmap.rst =================================================================== --- trunk/pyx/manual/bitmap.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/bitmap.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -46,23 +46,19 @@ c.insert(bitmap_rgb) c.writeEPSfile("bitmap") -Figure :ref:fig:bitmap shows the resulting output. +Figure :ref:fig_bitmap shows the resulting output. -.. % DUMMY -.. _fig_label: +.. _fig_bitmap: .. figure:: bitmap.* :align: center + An introductory bitmap example. -.. centered:: An introductory bitmap example. - -Bitmap module -============= - .. module:: bitmap - :synopsis: Bitmap support +Bitmap :mod:module: Bitmap support +==================================== .. class:: image(width, height, mode, data, compressed=None) Modified: trunk/pyx/manual/box.rst =================================================================== --- trunk/pyx/manual/box.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/box.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,9 +1,9 @@ -.. _module:box: +.. module:: box -******************************* -Module box: convex box handling -******************************* +************************************** +Module :mod:box: Convex box handling +************************************** This module has a quite internal character, but might still be useful from the users point of view. It might also get further enhanced to cover a broader range @@ -43,17 +43,15 @@ reltransform(*trafos): performs a list of transformations to the box relative to the box center - .. % DUMMY -.. _fig_label: +.. _fig_boxalign: .. figure:: boxalign.* :align: center + circle and line alignment examples (equal direction and distance) - .. centered:: circle and line alignment examples (equal direction and distance) - circlealignvector(a, dx, dy): returns a vector (a tuple (x, y)) to align the box at a circle with radius a - in the direction (dx, dy); see figure :ref:fig:boxalign + in the direction (dx, dy); see figure :ref:fig_boxalign linealignvector(a, dx, dy): as above, but align at a line with distance a Modified: trunk/pyx/manual/canvas.rst =================================================================== --- trunk/pyx/manual/canvas.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/canvas.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,6 +1,7 @@ -.. _canvas: +.. module:: canvas +==================== Module :mod:canvas ==================== @@ -16,13 +17,10 @@ may be useful when you want to apply a transformation on a whole set of operations.. -.. module:: canvas +Class canvas +------------ - -Class :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. @@ -147,7 +145,7 @@ gain access to the :class:document.page constructor arguments. For more information about the possible arguments of the :class:document.page -constructor, we refer to Sect. :ref:document. +constructor, we refer to Sect. :mod:document. .. % %% Local Variables: .. % %% mode: latex Modified: trunk/pyx/manual/color.rst =================================================================== --- trunk/pyx/manual/color.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/color.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,9 +1,9 @@ -.. _color: +.. module:: color -************ -Module color -************ +******************* +Module :mod:color +******************* Color models @@ -43,11 +43,11 @@ The file color.eps is created and looks like: - .. % DUMMY -.. _fig_label: +.. _fig_color: .. figure:: color.* :align: center + Color example Color gradients Modified: trunk/pyx/manual/colorname.rst =================================================================== --- trunk/pyx/manual/colorname.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/colorname.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,12 +1,13 @@ .. _colorname: -************ -Named colors -************ +********************** +Appendix: Named colors +********************** -.. % DUMMY -.. _fig_label: +.. _fig_colorname: .. figure:: colorname.* :align: center + Names colors + Modified: trunk/pyx/manual/connector.rst =================================================================== --- trunk/pyx/manual/connector.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/connector.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,5 +1,5 @@ -.. _connector: +.. module:: connector *********************** Module :mod:connector @@ -11,38 +11,38 @@ connecting path from the first to the second box. The overall geometry of the path is such that is starts/ends at the boxes' centers. It is then cut by the boxes' outlines. The resulting :class:connector will additionally be shortened -by lengths given in the :keyword:boxdists\ -keyword (a list of two lengths, +by lengths given in the *boxdists* (a list of two lengths, default [0,0]). Angle keywords can be either absolute or relative. The absolute angles refer to the angle between x-axis and the running tangent of the connector, while the relative angles are between the direct connecting line of the box-centers and -the running tangent (see figure. :ref:fig:connector). +the running tangent (see figure. :ref:fig_connector). The bulge-keywords parameterize the deviation of the connector from the connecting line. It has different meanings for different connectors (see figure. -:ref:fig:connector). +:ref:fig_connector). Class :class:line =================== The constructor of the :class:line class accepts only boxes and the -:keyword:boxdists\ -keyword. +*boxdists*. Class :class:arc ================== -The constructor takes either the :keyword:relangle\ -keyword or a combination -of :keyword:relbulge and :keyword:absbulge. The "bulge" is meant to be a +The constructor takes either the *relangle* or a combination +of *relbulge* and *absbulge*. The "bulge" is meant to be a hint for the greatest distance between the connecting arc and the straight connection between the box-centers. (Default: relangle=45, relbulge=None, absbulge=None) Note that the bulge-keywords override the angle-keyword. -If both :keyword:relbulge and :keyword:absbulge are given, they will be +If both *relbulge* and *absbulge* are given, they will be added. @@ -51,26 +51,24 @@ The constructor takes both angle- and bulge-keywords. Here, the bulges are used as distances between the control points of the cubic Beziér-curve. For the signs -of the angle- and bulge-keywords refer to figure :ref:fig:connector. +of the angle- and bulge-keywords refer to figure :ref:fig_connector. -:keyword:absangle1 or :keyword:relangle1 --- :keyword:absangle2 or -:keyword:relangle2, where the absolute angle overrides the relative if both +*absangle1* or *relangle1* --- *absangle2* or +*relangle2*, where the absolute angle overrides the relative if both are given. (Default: relangle1=45, relangle2=45, absangle1=None, absangle2=None) -:keyword:absbulge and :keyword:relbulge, where they will be added if both +*absbulge* and *relbulge*, where they will be added if both are given. --- (Default: absbulge=None, relbulge=0.39; these default values produce output similar to the defaults of :class:arc.) -.. % DUMMY -.. _fig_label: +.. _fig_connector: .. figure:: connector.* :align: center + The angle-parameters of the connector.arc (left panel) and the connector.curve (right panel) classes. -.. centered:: The angle-parameters of the connector.arc (left panel) and the connector.curve (right panel) classes. - Class :class:twolines ======================= @@ -78,11 +76,11 @@ combinations for angle- and length-keywords. The user has to make sure to provide a non-ambiguous set of keywords: -:keyword:absangle1 or :keyword:relangle1 for the first angle, --- -:keyword:relangleM for the middle angle and --- :keyword:absangle2 or -:keyword:relangle2 for the ending angle. Again, the absolute angle overrides +*absangle1* or *relangle1* for the first angle, --- +*relangleM* for the middle angle and --- *absangle2* or +*relangle2* for the ending angle. Again, the absolute angle overrides the relative if both are given. (Default: all five angles are None) -:keyword:length1 and :keyword:length2 for the lengths of the connecting +*length1* and *length2* for the lengths of the connecting lines. (Default: None) Modified: trunk/pyx/manual/deformer.rst =================================================================== --- trunk/pyx/manual/deformer.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/deformer.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,12 +1,9 @@ -.. _deformer: - -Module :mod:deformer -====================== - .. module:: deformer - :synopsis: Path deformers +====================================== +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 @@ -19,9 +16,6 @@ .. class:: deformer() - DUMMY - - .. method:: deformer.__call__((specific parameters for the class)) Returns a deformer with modified parameters @@ -61,12 +55,12 @@ 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! 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 length :math:2\times *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 in a *geometrically smooth* way. Path elements that are shorter than - *radius*:math:\times*relskipthres* are ignored. + *radius* :math:\times *relskipthres* are ignored. The new curve smoothing the corner consists either of one or of two Bezier curves, depending on the surrounding path elements. If there are straight lines @@ -131,10 +125,3 @@ *lookforcurvatures* is the number of points per normpathitem where its curvature is checked for critical values - -.. % %% Local Variables: -.. % %% mode: latex -.. % %% TeX-master: "manual.tex" -.. % %% ispell-dictionary: "british" -.. % %% End: - Modified: trunk/pyx/manual/document.rst =================================================================== --- trunk/pyx/manual/document.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/document.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,15 +1,12 @@ -.. _document: +.. module:: document +====================== Module :mod:document ====================== .. sectionauthor:: Jörg Lehmann - -.. module:: document - - The document module contains two classes: :class:document and :class:page. A :class:document consists of one or several :class:page\ s. Modified: trunk/pyx/manual/epsfile.rst =================================================================== --- trunk/pyx/manual/epsfile.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/epsfile.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,7 +1,8 @@ +.. module:: epsfile -********************************** -Module epsfile: EPS file inclusion -********************************** +***************************************** +Module :mod:epsfile: EPS file inclusion +***************************************** With the help of the epsfile.epsfile class, you can easily embed another EPS file in your canvas, thereby scaling, aligning the content at discretion. The Modified: trunk/pyx/manual/gradientname.rst =================================================================== --- trunk/pyx/manual/gradientname.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/gradientname.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,12 +1,11 @@ - .. _gradientname: -*************** -Named gradients -*************** +************************* +Appendix: Named gradients +************************* -.. % DUMMY -.. _fig_label: +.. _fig_gradientname: .. figure:: gradientname.* :align: center + Names gradients Modified: trunk/pyx/manual/graph.rst =================================================================== --- trunk/pyx/manual/graph.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/graph.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,5 +1,5 @@ -.. _graph: +.. module:: graph ****** Graphs @@ -11,7 +11,7 @@ PyX can be used for data and function plotting. At present x-y-graphs and x-y-z-graphs are supported only. However, the component architecture of the -graph system described in section :ref:graph:components allows for additional +graph system described in section :ref:graph_components allows for additional graph geometries while reusing most of the existing components. .. % {{{ @@ -27,7 +27,7 @@ :file:graph.dat you want to plot. The content of the file could look like: -.. include:: ../includes/graph.dat +.. include:: graph.dat :literal: To plot these data into the graph g you must perform:: @@ -48,16 +48,14 @@ g.writeEPSfile("graph") -The result :file:graph.eps is shown in figure :ref:fig:graph. +The result :file:graph.eps is shown in figure :ref:fig_graph. -.. % DUMMY -.. _fig_label: +.. _fig_graph: .. figure:: graph.* :align: center + A minimalistic plot for the data from file :file:graph.dat. -.. centered:: A minimalistic plot for the data from file :file:graph.dat. - Instead of plotting data from a file, other data source are available as well. For example function data is created and placed into :meth:plot by the following line:: @@ -70,44 +68,40 @@ automatically, when the graph is written to a file. Thus it is not an option to call :meth:plot after :meth:writeEPSfile or :meth:writePDFfile. The topic of the finalization of a graph is addressed in more detail in section -:ref:graph:graph. As you can see in figure :ref:fig:graph2, a function is +:mod:graph.graph. As you can see in figure :ref:fig_graph2, a function is plotted as a line by default. -.. % DUMMY -.. _fig_label: +.. _fig_graph2: .. figure:: graph2.* :align: center + Plotting data from a file together with a function. -.. centered:: Plotting data from a file together with a function. - While the axes ranges got adjusted automatically in the previous example, they might be fixed by keyword options in axes constructors. Plotting only a function will need such a setting at least in the variable coordinate. The following code also shows how to set a logathmic axis in y-direction: -.. include:: ../includes/graph3.py +.. include:: graph3.py :literal: -The result is shown in figure :ref:fig:graph3. +The result is shown in figure :ref:fig_graph3. -.. % DUMMY -.. _fig_label: +.. _fig_graph3: .. figure:: graph3.* :align: center + Plotting a function for a given axis range and use a logarithmic y-axis. -.. centered:: Plotting a function for a given axis range and use a logarithmic y-axis. +.. _graph_components: Component architecture ====================== .. % {{{ -.. _graph:components: - Creating a graph involves a variety of tasks, which thus can be separated into components without significant additional costs. This structure manifests itself also in the PyX source, where there are different modules for the different @@ -135,22 +129,16 @@ graph coordinates. Because axes are also responsible for creating ticks and labels, showing up in the graph themselves and other things, this task is splitted into several independent subtasks. Axes are discussed separately in - chapter :ref:axis. + chapter :mod:axis. .. % }}} - -Module :mod:graph.graph: Graphs -================================= - -.. % {{{ - -.. _graph:graph: - .. module:: graph.graph - :synopsis: Graph geometry +Module :mod:graph.graph: Graph geometry +========================================= + The classes :class:graphxy and :class:graphxyz are part of the module :mod:graph.graph. However, there are shortcuts to access the classes via graph.graphxy and graph.graphxyz, respectively. @@ -212,7 +200,7 @@ provided by *data* is used. *data* should be an instance of any of the data described in section - :ref:graph:data. + :mod:graph.data. When the same combination of styles (*i.e.* the same references) are used several times within the same graph instance, the styles are kindly asked by the @@ -450,17 +438,12 @@ .. % }}} -Module :mod:graph.data: Data -============================== - -.. % {{{ - -.. _graph:data: - .. module:: graph.data - :synopsis: Graph data +Module :mod:graph.data: Graph data +==================================== + The following classes provide data for the :meth:plot method of a graph. The classes are implemented in :mod:graph.data. @@ -732,16 +715,10 @@ .. % }}} -Module :mod:graph.style: Styles -================================= - -.. % {{{ - -.. _graph:style: - .. module:: graph.style - :synopsis: Graph style +Module :mod:graph.style: Graph styles +======================================= Please note that we are talking about graph styles here. Those are responsible for plotting symbols, lines, bars and whatever else into a graph. Do not mix it @@ -813,7 +790,7 @@ *size* using *symbolattrs*. *symbolattrs* is merged with defaultsymbolattrs which is a list containing the decorator :class:deco.stroked. An instance of :class:symbol is the default style for all graph data classes described in - section :ref:graph:data except for :class:function and + section :mod:graph.data except for :class:function and :class:paramfunction. The class :class:symbol provides some symbol functions as member variables, @@ -929,7 +906,7 @@ defaultlineattrs which is a list containing the member variable changelinestyle as described below. An instance of :class:line is the default style of the graph data classes :class:function and - :class:paramfunction described in section :ref:graph:data. + :class:paramfunction described in section :mod:graph.data. .. % {{{ @@ -1177,16 +1154,10 @@ .. % }}} -Module :mod:graph.key: Keys -============================= - -.. % {{{ - -.. _graph:key: - .. module:: graph.key - :synopsis: Graph keys +Module :mod:graph.key: Graph keys +=================================== The following class provides a key, whose instances can be passed to the constructor keyword argument key of a graph. The class is implemented in Modified: trunk/pyx/manual/graphics.rst =================================================================== --- trunk/pyx/manual/graphics.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/graphics.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,3 +1,4 @@ +.. _graphics: ************** Basic graphics @@ -6,9 +7,6 @@ .. sectionauthor:: Jörg Lehmann -.. _graphics: - - Introduction ============ @@ -75,27 +73,24 @@ 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: -.. % -.. % DUMMY -.. _fig_label: +.. _fig_rects: .. figure:: rects.* :align: center + Rectangle example -.. centered:: Rectangle consisting of (a) four separate lines, (b) one open path, and (c) one closed path. (d) Filling a path always closes it automatically. + Rectangle consisting of (a) four separate lines, (b) one open path, and (c) one closed path. (d) Filling a path always closes it automatically. -.. % - :: rect2 = path.path(path.moveto(0, 0), path.lineto(0, 1), 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 @@ -108,9 +103,9 @@ 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)])]) @@ -119,9 +114,9 @@ decorator :class:deco.filled. As it 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 +elements of the list can be found in Sect. :ref:graphics_attributes. More details on the available path elements can be found in Sect. -:ref:path:pathitem. +:ref:path_pathitem. To conclude this section, we should not forget to mention that rectangles are, of course, predefined in PyX, so above we could have as well written :: @@ -130,7 +125,7 @@ Here, the first two arguments specify the origin of the rectangle while the second two arguments define its width and height, respectively. For more details -on the predefined paths, we refer the reader to Sect. :ref:path:predefined. +on the predefined paths, we refer the reader to Sect. :ref:path_predefined. Path operations @@ -144,20 +139,18 @@ Suppose you want to draw the radii to the intersection points of a circle with a straight line. This task can be done using the following code which results in -Fig. :ref:fig:radii +Fig. :ref:fig_radii -.. include:: ../includes/radii.py +.. include:: radii.py :literal: -.. % DUMMY -.. _fig_label: +.. _fig_radii: .. figure:: radii.* :align: center + Example: Intersection of circle with line yielding two radii. -.. centered:: 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 :meth:intersect method of *circle*, we obtain a tuple of parameter values of @@ -171,7 +164,7 @@ Another powerful feature of PyX is its ability to split paths at a given set of parameters. For instance, in order to fill in the previous example the segment -of the circle delimited by the straight line (cf. Fig. :ref:fig:radii2), one +of the circle delimited by the straight line (cf. Fig. :ref:fig_radii2), one first has to construct a path corresponding to the outline of this segment. The following code snippet yields this *segment* :: @@ -186,14 +179,12 @@ segment = line2 << arc -.. % DUMMY -.. _fig_label: +.. _fig_radii2: .. figure:: radii2.* :align: center + Example: Intersection of circle with line yielding radii and circle segment. -.. centered:: 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 segments. We then use the :meth:arclen, which returns the arc length of the @@ -220,7 +211,7 @@ reason for this behaviour lies in the internal path handling of PyX: Before performing any non-trivial geometrical operation with a path, it will automatically be converted into an instance of the :class:normpath class (see -also Sect. :ref:path:normpath). These so generated paths are already separated +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. @@ -247,14 +238,14 @@ for this boundary case. More information on the available path methods can be found in Sect. -:ref:path:path. +:class:path.path. +.. _graphics_attributes: + Attributes: Styles and Decorations ================================== -.. _graphics:attributes: - 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 other, while for one type of attribute, several choices are possible. An example @@ -273,7 +264,7 @@ 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. :ref:unit for more information about PyX's unit system). +(see Sect. :mod: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:: Modified: trunk/pyx/manual/manual.rst =================================================================== --- trunk/pyx/manual/manual.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/manual.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -2,13 +2,6 @@ PyX Reference Manual ************************ -:Author: Jörg Lehmann, André Wobst - -:Date: DUMMY - -.. |release| replace:: DUMMY - - .. topic:: Abstract PyX is a Python package for the creation of PostScript and PDF files. It Modified: trunk/pyx/manual/path.rst =================================================================== --- trunk/pyx/manual/path.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/path.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,12 +1,12 @@ +.. module:: path +================== Module :mod:path ================== .. sectionauthor:: Jörg Lehmann -.. _path: - The :mod:path module defines several important classes which are documented in the present section. @@ -14,18 +14,12 @@ Class :class:path --- PostScript-like paths --------------------------------------------- -.. _path:path: - -.. module:: path - - - .. class:: path(*pathitems) This class represents a PostScript like path consisting of the path elements *pathitems*. - All possible path items are described in Sect. :ref:path:pathitem. Note that + All possible path items are described in Sect. :ref:path_pathitem. Note that there are restrictions on the first path element and likewise on each path element after a :class:closepath directive. In both cases, no current point is defined and the path element has to be an instance of one of the following @@ -193,11 +187,11 @@ length along the path. +.. _path_pathitem: + Path elements ------------- -.. _path:pathitem: - The class :class:pathitem is the superclass of all PostScript path construction primitives. It is never used directly, but only by instantiating its subclasses, which correspond one by one to the PostScript primitives. @@ -279,7 +273,7 @@ control point and the other control points defined relative to the current point by the coordinates (*dx1*, *dy1*), (*dx2*, *dy2*), and (*dx3*, *dy3*). -Note that when calculating the bounding box (see Sect. :ref:bbox) of Bézier +Note that when calculating the bounding box (see Sect. :mod:bbox) of Bézier curves, PyX uses for performance reasons the so-called control box, i.e., the smallest rectangle enclosing the four control points of the Bézier curve. In general, this is not the smallest rectangle enclosing the Bézier curve. @@ -309,11 +303,11 @@ argument. Thus, *points_pt* must be a sequence of 6-tuples. +.. _path_normpath: + Class :class:normpath ----------------------- -.. _path: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 @@ -410,10 +404,11 @@ segment from the first to the last point, if it is not already present. +.. _path_predefined: + Predefined paths ---------------- -.. _path:predefined: For convenience, some oft-used paths are already predefined. All of them are subclasses of the :class:path class. Modified: trunk/pyx/manual/pathstyles.rst =================================================================== --- trunk/pyx/manual/pathstyles.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/pathstyles.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,12 +1,13 @@ .. _pathstyles: -******************* -Module :mod:style -******************* +********************* +Appendix: path styles +********************* -.. % DUMMY -.. _fig_label: +.. _fig_pathstyles: .. figure:: pathstyles.* :align: center + path styles + Modified: trunk/pyx/manual/pattern.rst =================================================================== --- trunk/pyx/manual/pattern.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/pattern.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,6 +1,5 @@ +.. module:: pattern -.. _pattern: - ********************* Module :mod:pattern ********************* @@ -13,10 +12,7 @@ Manual) which may then be used to fill paths. In addition, a number of predefined hatch patterns are included. -.. module:: pattern - - Class :class:pattern ====================== Modified: trunk/pyx/manual/text.rst =================================================================== --- trunk/pyx/manual/text.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/text.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,5 +1,5 @@ -.. _module:text: +.. module:: text *************************************** Module :mod:text: TeX/LaTeX interface @@ -42,10 +42,7 @@ TeX/LaTeX instances: the :class:texrunner class ================================================= -.. module:: text - :synopsis: TeX/LaTeXinterface - Instances of the class :class:texrunner are responsible for executing and controling a TeX/LaTeX instance. @@ -169,10 +166,7 @@ TeX/LaTeX attributes ==================== -.. module:: text - :synopsis: TeX/LaTeXinterface - TeX/LaTeX attributes are instances to be passed to a :class:texrunner\ s :meth:text method. They stand for TeX/LaTeX expression fragments and handle dependencies by proper ordering. @@ -256,21 +250,19 @@ Combines :attr:boxright and :attr:flushright, *i.e.* halign(1, 1). -.. % DUMMY -.. _fig_label: +.. _fig_textvalign: .. figure:: textvalign.* :align: center + valign example -.. centered:: valign example - .. class:: valign(valign) Instances of this class set the vertical alignment of a text box to be top, center and bottom for *valign* being 0, 0.5, and 1. Other values are allowed as well, although such an alignment seems quite unusual. See the left - side of figure :ref:fig:textvalign for an example. + side of figure :ref:fig_textvalign for an example. Some handy instances available as class members: @@ -307,7 +299,7 @@ baseline to be used by the optional *baseline* argument. You can set it to the symbolic names :attr:top, :attr:parbox.middle, and :attr:parbox.bottom only, which are members of :class:valign. See the right side of figure - :ref:fig:textvalign for an example. + :ref:fig_textvalign for an example. Since you need to specify a box width no predefined instances are available as class members. @@ -495,10 +487,7 @@ TeX message parsers =================== -.. module:: text - :synopsis: TeX/LaTeXinterface - Message parsers are used to scan the output of TeX/LaTeX. The output is analysed by a sequence of TeX message parsers. Each message parser analyses the output and removes those parts of the output, it feels responsible for. If there is @@ -582,11 +571,7 @@ The :attr:defaulttexrunner instance ===================================== -.. module:: text - :synopsis: TeX/LaTeXinterface - - .. data:: defaulttexrunner The defaulttexrunner is an instance of :class:texrunner. It is created Modified: trunk/pyx/manual/trafo.rst =================================================================== --- trunk/pyx/manual/trafo.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/trafo.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,9 +1,9 @@ +.. module:: trafo -************************************ -Module trafo: linear transformations -************************************ +******************************************* +Module :mod:trafo: Linear transformations +******************************************* -.. _trafo: 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 Modified: trunk/pyx/manual/unit.rst =================================================================== --- trunk/pyx/manual/unit.rst 2011-05-20 08:51:56 UTC (rev 3148) +++ trunk/pyx/manual/unit.rst 2011-05-20 10:31:17 UTC (rev 3149) @@ -1,14 +1,13 @@ -.. _unit: +.. module:: unit -*********** -Module unit -*********** +****************** +Module :mod:unit +****************** .. sectionauthor:: Jörg Lehmann -.. module:: unit With the unit module PyX makes available classes and functions for the @@ -40,9 +39,9 @@ .. function:: set(uscale=None, vscale=None, wscale=None, xscale=None, defaultunit=None) - When *uscale*, *vscale*, *wscale*, or *xscale* is not :keyword:None, the + When *uscale*, *vscale*, *wscale*, or *xscale* is not None, the corresponding scaling factor(s) is redefined to the given number. When - *defaultunit* is not :keyword:None, the default unit is set to the given + *defaultunit* is not None, the default unit is set to the given value, which has to be one of "cm", "mm", "inch", or "pt". For instance, if you only want thicker lines for a publication version of your This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. 
 [PyX-checkins] SF.net SVN: pyx:[3150] trunk/pyx/manual From: - 2011-05-20 10:48:55 Revision: 3150 http://pyx.svn.sourceforge.net/pyx/?rev=3150&view=rev Author: wobsta Date: 2011-05-20 10:48:48 +0000 (Fri, 20 May 2011) Log Message: ----------- remove comments, improve a few links Modified Paths: -------------- trunk/pyx/manual/axis.rst trunk/pyx/manual/bbox.rst trunk/pyx/manual/canvas.rst trunk/pyx/manual/deformer.rst trunk/pyx/manual/document.rst trunk/pyx/manual/epsfile.rst trunk/pyx/manual/graph.rst trunk/pyx/manual/intro.rst trunk/pyx/manual/path.rst trunk/pyx/manual/pathstyles.rst trunk/pyx/manual/pattern.rst trunk/pyx/manual/trafo.rst trunk/pyx/manual/unit.rst Modified: trunk/pyx/manual/axis.rst =================================================================== --- trunk/pyx/manual/axis.rst 2011-05-20 10:31:17 UTC (rev 3149) +++ trunk/pyx/manual/axis.rst 2011-05-20 10:48:48 UTC (rev 3150) @@ -1,5 +1,5 @@ -.. module:: axis +.. module:: graph.axis **** Axes @@ -13,8 +13,6 @@ outside of the graph system. Internally axes are constructed out of components, which handle different tasks axes need to fulfill: -.. % {{{ - axis Implements the conversion of a data value to a graph coordinate of range [0:1]. It does also handle the proper usage of the components in complicated tasks @@ -61,16 +59,12 @@ few lines of code each. Hence we can here directly come to the reference of the available components. -.. % }}} - .. module:: graph.axis.axis Module :mod:graph.axis.axis: Axes =================================== -.. % {{{ - The following classes are part of the module :mod:graph.axis.axis. However, there is a shortcut to access those classes via graph.axis directly. @@ -286,16 +280,12 @@ :class:anchoredpathaxis class, but immediately creates the axis and returns the painted axis. -.. % }}} - .. module:: graph.axis.tick Module :mod:graph.axis.tick: Axes ticks ========================================= -.. % {{{ - The following classes are part of the module :mod:graph.axis.tick. @@ -342,16 +332,12 @@ label. When not set, it can be created automatically by a texter. *labelattrs* are the attributes for the labels. -.. % }}} - .. module:: graph.axis.parter Module :mod:graph.axis.parter: Axes partitioners ================================================== -.. % {{{ - The following classes are part of the module :mod:graph.axis.parter. Instances of the classes can be passed to the parter keyword argument of regular axes. @@ -500,16 +486,12 @@ This class is an abbreviation of :class:autologarithmic described above. -.. % }}} - .. module:: graph.axis.texter Module :mod:graph.axis.texter: Axes texter ============================================ -.. % {{{ - The following classes are part of the module :mod:graph.axis.texter. Instances of the classes can be passed to the texter keyword argument of regular axes. Texters are used to define the label text for ticks, which request to have a @@ -620,16 +602,12 @@ *labelattrs* has the same meaning as for *decimal*. -.. % }}} - .. module:: graph.axis.painter Module :mod:graph.axis.painter: Axes painter ============================================== -.. % {{{ - The following classes are part of the module :mod:graph.axis.painter. Instances of the painter classes can be passed to the painter keyword argument of regular axes. @@ -753,16 +731,12 @@ *titleattrs*. By turning off this feature, this painter is suitable for linked split axes. -.. % }}} - .. module:: graph.axis.rater Module :mod:graph.axis.rater: Axes rater ========================================== -.. % {{{ - The rating of axes is implemented in :mod:graph.axis.rater. When an axis partitioning scheme returns several partitioning possibilities, the partitions need to be rated by a positive number. The axis partitioning rated lowest is @@ -836,16 +810,12 @@ This class is an abbreviation of :class:logarithmic described above. -.. % }}} - .. module:: graph.axis.positioners Module :mod:graph.axis.positioner: Axes positioners ===================================================== -.. % {{{ - The position of an axis is defined by an instance of a class providing the following methods: @@ -880,6 +850,3 @@ positioner instances are created by graphs etc. as needed, the details are not interesting for the average PyX user. -.. % }}} % }}} -.. % vim:fdm=marker - Modified: trunk/pyx/manual/bbox.rst =================================================================== --- trunk/pyx/manual/bbox.rst 2011-05-20 10:31:17 UTC (rev 3149) +++ trunk/pyx/manual/bbox.rst 2011-05-20 10:48:48 UTC (rev 3150) @@ -79,8 +79,3 @@ Furthermore, two bounding boxes can be added (giving the bounding box enclosing both) and multiplied (giving the intersection of both bounding boxes). -.. % %% Local Variables: -.. % %% mode: latex -.. % %% TeX-master: "manual.tex" -.. % %% End: - Modified: trunk/pyx/manual/canvas.rst =================================================================== --- trunk/pyx/manual/canvas.rst 2011-05-20 10:31:17 UTC (rev 3149) +++ trunk/pyx/manual/canvas.rst 2011-05-20 10:48:48 UTC (rev 3150) @@ -147,8 +147,3 @@ For more information about the possible arguments of the :class:document.page constructor, we refer to Sect. :mod:document. -.. % %% Local Variables: -.. % %% mode: latex -.. % %% TeX-master: "manual.tex" -.. % %% End: - Modified: trunk/pyx/manual/deformer.rst =================================================================== --- trunk/pyx/manual/deformer.rst 2011-05-20 10:31:17 UTC (rev 3149) +++ trunk/pyx/manual/deformer.rst 2011-05-20 10:48:48 UTC (rev 3150) @@ -92,15 +92,13 @@ by sharp edges) around the corners of the original path. Later, everything that is nearer to the original path than distance is cut away. - .. % - There are some caveats: -* When the original path is too curved then the parallel path would contain + * When the original path is too curved then the parallel path would contain 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 + * 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. Modified: trunk/pyx/manual/document.rst =================================================================== --- trunk/pyx/manual/document.rst 2011-05-20 10:31:17 UTC (rev 3149) +++ trunk/pyx/manual/document.rst 2011-05-20 10:48:48 UTC (rev 3150) @@ -109,8 +109,3 @@ | :const:document.paperformat.Legal | Legal | 8.5 inch | 14 inch | +--------------------------------------+--------+----------+---------+ -.. % %% Local Variables: -.. % %% mode: latex -.. % %% TeX-master: "manual.tex" -.. % %% End: - Modified: trunk/pyx/manual/epsfile.rst =================================================================== --- trunk/pyx/manual/epsfile.rst 2011-05-20 10:31:17 UTC (rev 3149) +++ trunk/pyx/manual/epsfile.rst 2011-05-20 10:48:48 UTC (rev 3150) @@ -61,8 +61,3 @@ .. _epsfile: -.. % %% Local Variables: -.. % %% mode: latex -.. % %% TeX-master: "manual.tex" -.. % %% End: - Modified: trunk/pyx/manual/graph.rst =================================================================== --- trunk/pyx/manual/graph.rst 2011-05-20 10:31:17 UTC (rev 3149) +++ trunk/pyx/manual/graph.rst 2011-05-20 10:48:48 UTC (rev 3150) @@ -14,8 +14,6 @@ graph system described in section :ref:graph_components allows for additional graph geometries while reusing most of the existing components. -.. % {{{ - Creating a graph splits into two basic steps. First you have to create a graph instance. The most simple form would look like:: @@ -100,8 +98,6 @@ Component architecture ====================== -.. % {{{ - Creating a graph involves a variety of tasks, which thus can be separated into components without significant additional costs. This structure manifests itself also in the PyX source, where there are different modules for the different @@ -131,8 +127,6 @@ splitted into several independent subtasks. Axes are discussed separately in chapter :mod:axis. -.. % }}} - .. module:: graph.graph Module :mod:graph.graph: Graph geometry @@ -311,8 +305,6 @@ single: ytickdirection()@ytickdirection() (graphxy method) single: yvtickdirection()@yvtickdirection() (graphxy method) -.. % dirty hack to add a whole list of methods to the index: - Further geometry information is available by the :attr:axes instance variable, with is a dictionary mapping axis names to :class:anchoredaxis instances. Shortcuts to the anchoredaxis positioner methods for the x\ - and y\ @@ -435,9 +427,7 @@ central projection). All other parameters are identical to the :class:central class. -.. % }}} - .. module:: graph.data Module :mod:graph.data: Graph data @@ -544,9 +534,7 @@ re.compile(r"(.*?)(\s+|)") -.. % }}} - .. class:: function(expression, title=notitle, min=None, max=None, points=100, context={}) This class creates graph data from a function. *expression* is the mathematical @@ -566,9 +554,7 @@ the identifiers in *context*, the variable name and the functions shown in the table "builtins in math expressions" at the end of the section are available. -.. % }}} - .. class:: paramfunction(varname, min, max, expression, title=notitle, points=100, context={}) This class creates graph data from a parametric function. *varname* is the @@ -587,9 +573,7 @@ the identifiers in *context*, *varname* and the functions shown in the table "builtins in math expressions" at the end of the section are available. -.. % }}} - .. class:: values(title="user provided values", **columns) This class creates graph data from externally provided data. Each column is a @@ -597,9 +581,7 @@ *title* is the title of the data to be used in the graph key. -.. % }}} - .. class:: points(data, title="user provided points", addlinenumbers=1, **columns) This class creates graph data from externally provided data. *data* is a list of @@ -612,9 +594,7 @@ column is added to contain a line number in that case), while the column numbers starts from zero, when *addlinenumbers* is switched off. -.. % }}} - .. class:: data(data, title=notitle, context=, copy=1, replacedollar=1, columncallback="__column__", **columns) This class provides graph data out of other graph data. *data* is the source of @@ -623,9 +603,7 @@ reading the file and caching its contents in a :class:graph.data.list instance. -.. % }}} - .. class:: conffile(filename, title=notitle, context=, copy=1, replacedollar=1, columncallback="__column__", **columns) This class reads data from a config file with the file name *filename*. The @@ -637,9 +615,7 @@ other parameters work as in *graph.data.file* and *graph.data.data* since they all use the same code. -.. % }}} - .. class:: cbdfile(filename, minrank=None, maxrank=None, title=notitle, context=, copy=1, replacedollar=1, columncallback="__column__", **columns) This is an experimental class to read map data from cbd-files. See @@ -647,8 +623,6 @@ The builtins in math expressions are listed in the following table: -.. % }}} - +------------------+--------------------------------------------+ | name | value | +==================+============================================+ @@ -712,9 +686,7 @@ equal the third item. It continues to alter between None and 2, 3, etc. -.. % }}} - .. module:: graph.style Module :mod:graph.style: Graph styles @@ -744,19 +716,13 @@ an axis name. Data points are considered to be out of graph when their position in graph coordinates exceeds the range [0:1] by more than *epsilon*. - .. % {{{ -.. % }}} - - .. class:: range(usenames=, epsilon=1e-10) This class is a hidden style providing an errorbar range. It needs data column names constructed out of a axis name X for each dimension errorbar data should be provided as follows: - .. % {{{ - +-----------+---------------------------+ | data name | description | +===========+===========================+ @@ -777,9 +743,7 @@ *epsilon* is a comparison precision when checking for invalid errorbar ranges. -.. % }}} - .. class:: symbol(symbol=changecross, size=0.2*unit.v_cm, symbolattrs=[]) This class is a style for plotting symbols in a graph. *symbol* refers to a @@ -897,9 +861,7 @@ attr.changelist([deco.filled, deco.stroked]) -.. % }}} - .. class:: line(lineattrs=[]) This class is a style to stroke lines in a graph. *lineattrs* is merged with @@ -908,8 +870,6 @@ default style of the graph data classes :class:function and :class:paramfunction described in section :mod:graph.data. - .. % {{{ - The class :class:line provides a changeable line style. Its definition is: @@ -918,9 +878,7 @@ attr.changelist([style.linestyle.solid, style.linestyle.dashed, style.linestyle.dotted, style.linestyle.dashdotted]) -.. % }}} - .. class:: impulses(lineattrs=[], fromvalue=0, frompathattrs=[], valueaxisindex=1) This class is a style to plot impulses. *lineattrs* is merged with @@ -930,9 +888,7 @@ baseline. When fromvalue is set, *frompathattrs* are the stroke attributes used to show the impulses baseline path. -.. % }}} - .. class:: errorbar(size=0.1*unit.v_cm, errorbarattrs=[], epsilon=1e-10) This class is a style to stroke errorbars in a graph. *size* is the size of the @@ -941,9 +897,7 @@ graph coordinates exceeds the range [0:1] by more that *epsilon*. Out of graph caps are omitted and the errorbars are cut to the valid graph range. -.. % }}} - .. class:: text(textname="text", dxname=None, dyname=None, dxunit=0.3*unit.v_cm, dyunit=0.3*unit.v_cm, textdx=0*unit.v_cm, textdy=0.3*unit.v_cm, textattrs=[]) This class is a style to stroke text in a graph. The text to be written has to @@ -955,9 +909,7 @@ for the output of the text. Those attributes are merged with the default attributes textmodule.halign.center and textmodule.vshift.mathaxis. -.. % }}} - .. class:: arrow(linelength=0.25*unit.v_cm, arrowsize=0.15*unit.v_cm, lineattrs=[], arrowattrs=[], arrowpos=0.5, epsilon=1e-10, decorator=deco.earrow) This class is a style to plot short lines with arrows into a two-dimensional @@ -975,9 +927,7 @@ order to prevent numerical instabilities. *decorator* defines the decorator to be added to the line. -.. % }}} - .. class:: rect(gradient=color.gradient.Grey) This class is a style to plot colored rectangles into a two-dimensional graph. @@ -985,11 +935,7 @@ style. The additional data column named color specifies the color of the rectangle defined by *gradient*. The valid color range is [0:1]. - .. % {{{ -.. % }}} - - .. class:: histogram(lineattrs=[], steps=0, fromvalue=0, frompathattrs=[], fillable=0, rectkey=0, autohistogramaxisindex=0, autohistogrampointpos=0.5, epsilon=1e-10) This class is a style to plot histograms. *lineattrs* is merged with @@ -1022,9 +968,7 @@ Positions of the histograms are considered to be out of graph when they exceed the graph coordinate range [0:1] by more than *epsilon*. -.. % }}} - .. class:: barpos(fromvalue=None, frompathattrs=[], epsilon=1e-10) This class is a hidden style providing position information in a bar graph. @@ -1034,17 +978,13 @@ plot several bars in a single graph side by side, you need to have a nested bar axis and provide a tuple as data for nested bar axis. - .. % {{{ - The bars start at *fromvalue* when provided. The *fromvalue* is marked by a gridline stroked using *frompathattrs*. Thus this hidden style might actually create some output. The value of a bar axis is considered to be out of graph when its position in graph coordinates exceeds the range [0:1] by more than *epsilon*. -.. % }}} - .. class:: stackedbarpos(stackname, addontop=0, epsilon=1e-10) This class is a hidden style providing position information in a bar graph by @@ -1052,19 +992,13 @@ the data column named *stackname*. When *addontop* is set, the values is taken relative to the previous top of the bar. - .. % {{{ -.. % }}} - - .. class:: bar(barattrs=[], epsilon=1e-10, gradient=color.gradient.RedBlack) This class draws bars in a bar graph. The bars are filled using *barattrs*. *barattrs* is merged with defaultbarattrs which is a list containing [color.gradient.Rainbow, deco.stroked([color.grey.black])]. - .. % {{{ - The bar style has limited support for 3d graphs: Occlusion does not work properly on stacked bars or multiple dataset. *epsilon* is used in 3d to prevent numerical instabilities on bars without hight. When *gradient* is not None @@ -1072,9 +1006,7 @@ between the view ray and the bar and the distance between viewer and bar. The precise conversion is defined in the :meth:lighting method. -.. % }}} - .. class:: changebar(barattrs=[]) This style works like the :class:bar style, but instead of the *barattrs* to @@ -1083,11 +1015,7 @@ several data instances and does not support 3d. The style raises an error instead. - .. % {{{ -.. % }}} - - .. class:: gridpos(index1=0, index2=1, gridlines1=1, gridlines2=1, gridattrs=[], epsilon=1e-10) This class is a hidden style providing rectangular grid information out of graph @@ -1096,9 +1024,7 @@ [0:1] by more than *epsilon*. Data points are merged to a single graph coordinate value when their difference in graph coordinates is below *epsilon*. -.. % }}} - .. class:: grid(gridlines1=1, gridlines2=1, gridattrs=[]) Strokes a rectangular grid in the first grid direction, when *gridlines1* is set @@ -1106,11 +1032,7 @@ merged with defaultgridattrs which is a list containing the member variable 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) Draws a surface of a rectangular grid. Each rectangle is divided into 4 @@ -1150,8 +1072,6 @@ * Color changes are continuous (in the selected color space) for each triangle. -.. % }}} -.. % }}} .. module:: graph.key @@ -1189,6 +1109,4 @@ When *keyattrs* is set to contain some draw attributes, the graph key is enlarged by *border* and the key area is drawn using *keyattrs*. -.. % }}} % }}} -.. % vim:fdm=marker Modified: trunk/pyx/manual/intro.rst =================================================================== --- trunk/pyx/manual/intro.rst 2011-05-20 10:31:17 UTC (rev 3149) +++ trunk/pyx/manual/intro.rst 2011-05-20 10:48:48 UTC (rev 3150) @@ -50,9 +50,3 @@ pollution, you may also simply use import pyx. Throughout this manual, we shall always assume the presence of the above given import line.a -.. % %% Local Variables: -.. % %% mode: latex -.. % %% TeX-master: "manual.tex" -.. % %% ispell-dictionary: "british" -.. % %% End: - Modified: trunk/pyx/manual/path.rst =================================================================== --- trunk/pyx/manual/path.rst 2011-05-20 10:31:17 UTC (rev 3149) +++ trunk/pyx/manual/path.rst 2011-05-20 10:48:48 UTC (rev 3150) @@ -433,9 +433,3 @@ A closed circle with center (*x*, *y*) and radius *r*. -.. % %% Local Variables: -.. % %% mode: latex -.. % %% TeX-master: "manual.tex" -.. % %% ispell-dictionary: "british" -.. % %% End: - Modified: trunk/pyx/manual/pathstyles.rst =================================================================== --- trunk/pyx/manual/pathstyles.rst 2011-05-20 10:31:17 UTC (rev 3149) +++ trunk/pyx/manual/pathstyles.rst 2011-05-20 10:48:48 UTC (rev 3150) @@ -1,4 +1,5 @@ +.. module:: style .. _pathstyles: ********************* Modified: trunk/pyx/manual/pattern.rst =================================================================== --- trunk/pyx/manual/pattern.rst 2011-05-20 10:31:17 UTC (rev 3149) +++ trunk/pyx/manual/pattern.rst 2011-05-20 10:48:48 UTC (rev 3150) @@ -63,8 +63,3 @@ the pattern instance to a :meth:stroke, :meth:fill, :meth:draw or :meth:set method of the canvas, just like you would do with a colour, etc. -.. % %% Local Variables: -.. % %% mode: latex -.. % %% TeX-master: "manual.tex" -.. % %% End: - Modified: trunk/pyx/manual/trafo.rst =================================================================== --- trunk/pyx/manual/trafo.rst 2011-05-20 10:31:17 UTC (rev 3149) +++ trunk/pyx/manual/trafo.rst 2011-05-20 10:48:48 UTC (rev 3150) @@ -102,10 +102,3 @@ | slant(a, angle=0, x=None, y=None) | XXX | +----------------------------------------+----------------------------------------------+ -.. % \section{Examples} - -.. % %% Local Variables: -.. % %% mode: latex -.. % %% TeX-master: "manual.tex" -.. % %% End: - Modified: trunk/pyx/manual/unit.rst =================================================================== --- trunk/pyx/manual/unit.rst 2011-05-20 10:31:17 UTC (rev 3149) +++ trunk/pyx/manual/unit.rst 2011-05-20 10:48:48 UTC (rev 3150) @@ -180,8 +180,3 @@ If l is not yet a length instance but a number, it first is interpreted as a user length in the default units. -.. % %% Local Variables: -.. % %% mode: latex -.. % %% TeX-master: "manual.tex" -.. % %% End: - This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.   [PyX-checkins] SF.net SVN: pyx:[3191] trunk/pyx/manual From: - 2011-07-10 10:03:59 Revision: 3191 http://pyx.svn.sourceforge.net/pyx/?rev=3191&view=rev Author: wobsta Date: 2011-07-10 10:03:53 +0000 (Sun, 10 Jul 2011) Log Message: ----------- use pdf for png creation Modified Paths: -------------- trunk/pyx/manual/Makefile trunk/pyx/manual/arrows.py trunk/pyx/manual/bitmap.py trunk/pyx/manual/boxalign.py trunk/pyx/manual/color.py trunk/pyx/manual/colorname.py trunk/pyx/manual/connector.py trunk/pyx/manual/gradientname.py trunk/pyx/manual/graph.py trunk/pyx/manual/graph2.py trunk/pyx/manual/graph3.py trunk/pyx/manual/pathstyles.py trunk/pyx/manual/radii.py trunk/pyx/manual/radii2.py trunk/pyx/manual/rects.py trunk/pyx/manual/textvalign.py Modified: trunk/pyx/manual/Makefile =================================================================== --- trunk/pyx/manual/Makefile 2011-07-10 09:06:26 UTC (rev 3190) +++ trunk/pyx/manual/Makefile 2011-07-10 10:03:53 UTC (rev 3191) @@ -20,7 +20,7 @@ @echo "Done." clean: - -rm -rf(BUILDDIR)/* *.eps *.pdf *.png + -rm -rf $(BUILDDIR)/* *.pdf *.png html: figs$(SPHINXBUILD) -b html $(ALLSPHINXOPTS)$(BUILDDIR)/html @@ -36,4 +36,4 @@ %.png: %.py export PYTHONPATH=$(CURDIR)/.. ;$(PYTHON) $^ -$(PYTHON) ../contrib/epstopng.py -o $@$*.eps + $(PYTHON) ../contrib/epstopng.py -o$@ \$*.pdf Modified: trunk/pyx/manual/arrows.py =================================================================== --- trunk/pyx/manual/arrows.py 2011-07-10 09:06:26 UTC (rev 3190) +++ trunk/pyx/manual/arrows.py 2011-07-10 10:03:53 UTC (rev 3191) @@ -47,5 +47,4 @@ drawdeco("earrow.Large([style.linejoin.round])") drawdeco("earrow.Large([deco.stroked.clear])") -c.writeEPSfile("arrows") -c.writePDFfile("arrows") +c.writePDFfile() Modified: trunk/pyx/manual/bitmap.py =================================================================== --- trunk/pyx/manual/bitmap.py 2011-07-10 09:06:26 UTC (rev 3190) +++ trunk/pyx/manual/bitmap.py 2011-07-10 10:03:53 UTC (rev 3191) @@ -10,6 +10,5 @@ c = canvas.canvas() c.insert(bitmap_bw) c.insert(bitmap_rgb) -c.writeEPSfile("bitmap") -c.writePDFfile("bitmap") +c.writePDFfile() Modified: trunk/pyx/manual/boxalign.py =================================================================== --- trunk/pyx/manual/boxalign.py 2011-07-10 09:06:26 UTC (rev 3190) +++ trunk/pyx/manual/boxalign.py 2011-07-10 10:03:53 UTC (rev 3191) @@ -16,6 +16,5 @@ c.stroke(t2.path(centerradius=0.05), [style.linewidth.THin]) c.stroke(path.line(5, 0, 5 + x, y), [deco.earrow.normal]) c.insert(t2) -c.writeEPSfile("boxalign") -c.writePDFfile("boxalign") +c.writePDFfile() Modified: trunk/pyx/manual/color.py =================================================================== --- trunk/pyx/manual/color.py 2011-07-10 09:06:26 UTC (rev 3190) +++ trunk/pyx/manual/color.py 2011-07-10 10:03:53 UTC (rev 3191) @@ -8,6 +8,5 @@ c.fill(path.rect(1, 1, 1, 1), [color.rgb.red]) c.fill(path.rect(3, 1, 1, 1), [color.rgb.green]) c.fill(path.rect(5, 1, 1, 1), [color.rgb.blue]) -c.writeEPSfile("color") -c.writePDFfile("color") +c.writePDFfile() Modified: trunk/pyx/manual/colorname.py =================================================================== --- trunk/pyx/manual/colorname.py 2011-07-10 09:06:26 UTC (rev 3190) +++ trunk/pyx/manual/colorname.py 2011-07-10 10:03:53 UTC (rev 3191) @@ -42,5 +42,4 @@ y = 0 x += dx -c.writeEPSfile("colorname") -c.writePDFfile("colorname") +c.writePDFfile() Modified: trunk/pyx/manual/connector.py =================================================================== --- trunk/pyx/manual/connector.py 2011-07-10 09:06:26 UTC (rev 3190) +++ trunk/pyx/manual/connector.py 2011-07-10 10:03:53 UTC (rev 3191) @@ -119,7 +119,6 @@ # write everything c1.insert(c2, [trafo.translate(6.5, 0)]) -c1.writeEPSfile("connector", paperformat=document.paperformat.A4) -c1.writePDFfile("connector") +c1.writePDFfile() # vim:foldmethod=marker:foldmarker=<<<,>>> Modified: trunk/pyx/manual/gradientname.py =================================================================== --- trunk/pyx/manual/gradientname.py 2011-07-10 09:06:26 UTC (rev 3190) +++ trunk/pyx/manual/gradientname.py 2011-07-10 10:03:53 UTC (rev 3191) @@ -45,5 +45,4 @@ y += dy -c.writeEPSfile("gradientname") -c.writePDFfile("gradientname") +c.writePDFfile() Modified: trunk/pyx/manual/graph.py =================================================================== --- trunk/pyx/manual/graph.py 2011-07-10 09:06:26 UTC (rev 3190) +++ trunk/pyx/manual/graph.py 2011-07-10 10:03:53 UTC (rev 3191) @@ -1,5 +1,4 @@ from pyx import * g = graph.graphxy(width=8) g.plot(graph.data.file("graph.dat", x=1, y=2)) -g.writeEPSfile("graph") -g.writePDFfile("graph") +g.writePDFfile() Modified: trunk/pyx/manual/graph2.py =================================================================== --- trunk/pyx/manual/graph2.py 2011-07-10 09:06:26 UTC (rev 3190) +++ trunk/pyx/manual/graph2.py 2011-07-10 10:03:53 UTC (rev 3191) @@ -2,5 +2,4 @@ g = graph.graphxy(width=8) g.plot(graph.data.file("graph.dat", x=1, y=2)) g.plot(graph.data.function("y(x)=x**2")) -g.writeEPSfile("graph2") -g.writePDFfile("graph2") +g.writePDFfile() Modified: trunk/pyx/manual/graph3.py =================================================================== --- trunk/pyx/manual/graph3.py 2011-07-10 09:06:26 UTC (rev 3190) +++ trunk/pyx/manual/graph3.py 2011-07-10 10:03:53 UTC (rev 3191) @@ -2,5 +2,4 @@ g = graph.graphxy(width=8, x=graph.axis.linear(min=-5, max=5), y=graph.axis.logarithmic()) g.plot(graph.data.function("y(x)=exp(x)")) -g.writeEPSfile("graph3") -g.writePDFfile("graph3") +g.writePDFfile() Modified: trunk/pyx/manual/pathstyles.py =================================================================== --- trunk/pyx/manual/pathstyles.py 2011-07-10 09:06:26 UTC (rev 3190) +++ trunk/pyx/manual/pathstyles.py 2011-07-10 10:03:53 UTC (rev 3191) @@ -79,5 +79,4 @@ drawstyle("dash((1, 2, 3), rellengths=1)") -c.writeEPSfile("pathstyles") -c.writePDFfile("pathstyles") +c.writePDFfile() Modified: trunk/pyx/manual/radii.py =================================================================== --- trunk/pyx/manual/radii.py 2011-07-10 09:06:26 UTC (rev 3190) +++ trunk/pyx/manual/radii.py 2011-07-10 10:03:53 UTC (rev 3191) @@ -12,5 +12,4 @@ isectx, isecty = circle.at(isect) c.stroke(path.line(0, 0, isectx, isecty)) -c.writeEPSfile("radii") -c.writePDFfile("radii") +c.writePDFfile() Modified: trunk/pyx/manual/radii2.py =================================================================== --- trunk/pyx/manual/radii2.py 2011-07-10 09:06:26 UTC (rev 3190) +++ trunk/pyx/manual/radii2.py 2011-07-10 10:03:53 UTC (rev 3191) @@ -23,5 +23,4 @@ for isect in isects_circle: c.stroke(path.line(0, 0, *circle.at(isect))) -c.writeEPSfile("radii2") -c.writePDFfile("radii2") +c.writePDFfile() Modified: trunk/pyx/manual/rects.py =================================================================== --- trunk/pyx/manual/rects.py 2011-07-10 09:06:26 UTC (rev 3190) +++ trunk/pyx/manual/rects.py 2011-07-10 10:03:53 UTC (rev 3191) @@ -24,8 +24,7 @@ c.stroke(rect3, [trafo.scale(2).translated(8, 0), style.linewidth.THICK]) c.text(9, -0.7, "(c)", [text.halign.center]) -c.stroke(rect3, [trafo.scale(2).translated(12, 0), style.linewidth.THICK, deco.filled([color.grey(0.95)])]) +c.stroke(rect3, [trafo.scale(2).translated(12, 0), style.linewidth.THICK, deco.filled([color.grey(0.5)])]) c.text(13, -0.7, "(d)", [text.halign.center]) -c.writeEPSfile("rects") -c.writePDFfile("rects") +c.writePDFfile() Modified: trunk/pyx/manual/textvalign.py =================================================================== --- trunk/pyx/manual/textvalign.py 2011-07-10 09:06:26 UTC (rev 3190) +++ trunk/pyx/manual/textvalign.py 2011-07-10 10:03:53 UTC (rev 3191) @@ -21,5 +21,4 @@ c.stroke(path.line(0, b.bottom()-b2.bottom(), 7.2, b.bottom()-b2.bottom())) c.stroke(path.line(7.3, b.bottom()-b2.bottom(), 7.5, b.bottom()-b2.bottom()), [deco.barrow.Small]) c.text(7.7, b.bottom()-b2.bottom(), "parbox.bottom", [text.vshift.mathaxis]) -c.writeEPSfile("textvalign") -c.writePDFfile("textvalign") +c.writePDFfile() This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. 
 [PyX-checkins] SF.net SVN: pyx:[3193] trunk/pyx/manual From: - 2011-07-10 16:04:10 Revision: 3193 http://pyx.svn.sourceforge.net/pyx/?rev=3193&view=rev Author: wobsta Date: 2011-07-10 16:04:02 +0000 (Sun, 10 Jul 2011) Log Message: ----------- improvements to the documentation by GLI Modified Paths: -------------- trunk/pyx/manual/bbox.rst trunk/pyx/manual/canvas.rst trunk/pyx/manual/color.rst trunk/pyx/manual/deformer.rst trunk/pyx/manual/epsfile.rst trunk/pyx/manual/gradientname.rst trunk/pyx/manual/graphics.rst trunk/pyx/manual/manual.rst trunk/pyx/manual/path.rst trunk/pyx/manual/pattern.rst trunk/pyx/manual/radii2.py trunk/pyx/manual/text.rst trunk/pyx/manual/trafo.rst trunk/pyx/manual/unit.rst Modified: trunk/pyx/manual/bbox.rst =================================================================== --- trunk/pyx/manual/bbox.rst 2011-07-10 10:04:24 UTC (rev 3192) +++ trunk/pyx/manual/bbox.rst 2011-07-10 16:04:02 UTC (rev 3193) @@ -1,3 +1,6 @@ + +.. _bbox_module: + .. module:: bbox ****************** @@ -10,8 +13,8 @@ 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 @@ +---------+-----------------------------------------------+ -bbox methods -============ +:class:bbox methods +===================== +-------------------------------------------+-----------------------------------------------+ | bbox method | function | Modified: trunk/pyx/manual/canvas.rst =================================================================== --- trunk/pyx/manual/canvas.rst 2011-07-10 10:04:24 UTC (rev 3192) +++ trunk/pyx/manual/canvas.rst 2011-07-10 16:04:02 UTC (rev 3193) @@ -8,23 +8,18 @@ .. 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. 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. -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. - - .. class:: canvas(attrs=[], texrunner=None) Construct a new canvas, applying the given *attrs*, which can be instances of @@ -38,7 +33,10 @@ .. 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 @@ .. 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 @@ .. 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 @@ .. 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 @@ 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 @@ .. 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 @@ .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 @@ 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. Modified: trunk/pyx/manual/color.rst =================================================================== --- trunk/pyx/manual/color.rst 2011-07-10 10:04:24 UTC (rev 3192) +++ trunk/pyx/manual/color.rst 2011-07-10 16:04:02 UTC (rev 3193) @@ -53,7 +53,7 @@ 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. Modified: trunk/pyx/manual/deformer.rst =================================================================== --- trunk/pyx/manual/deformer.rst 2011-07-10 10:04:24 UTC (rev 3192) +++ trunk/pyx/manual/deformer.rst 2011-07-10 16:04:02 UTC (rev 3193) @@ -7,9 +7,8 @@ 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 @@ *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 @@ 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. Modified: trunk/pyx/manual/epsfile.rst =================================================================== --- trunk/pyx/manual/epsfile.rst 2011-07-10 10:04:24 UTC (rev 3192) +++ trunk/pyx/manual/epsfile.rst 2011-07-10 16:04:02 UTC (rev 3193) @@ -1,3 +1,4 @@ + .. module:: epsfile ***************************************** Modified: trunk/pyx/manual/gradientname.rst =================================================================== --- trunk/pyx/manual/gradientname.rst 2011-07-10 10:04:24 UTC (rev 3192) +++ trunk/pyx/manual/gradientname.rst 2011-07-10 16:04:02 UTC (rev 3193) @@ -1,3 +1,4 @@ + .. _gradientname: ************************* Modified: trunk/pyx/manual/graphics.rst =================================================================== --- trunk/pyx/manual/graphics.rst 2011-07-10 10:04:24 UTC (rev 3192) +++ trunk/pyx/manual/graphics.rst 2011-07-10 16:04:02 UTC (rev 3193) @@ -1,3 +1,4 @@ + .. _graphics: ************** @@ -16,8 +17,10 @@ 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 the :class:path class. The following code snippet, for instance, defines a @@ -73,7 +76,7 @@ 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 @@ 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 @@ 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 @@ .. 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 @@ .. 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 @@ 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 @@ 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 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 @@ 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 @@ 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 @@ 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 @@ | :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,15 +325,17 @@ | | | :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 attributes and decorators are. Some attributes might belong to several attribute @@ -362,5 +364,7 @@ c.stroke(path, [deco.earrow(angle=30)]) -XXX changeable attributes +.. todo:: + changeable attributes + Modified: trunk/pyx/manual/manual.rst =================================================================== --- trunk/pyx/manual/manual.rst 2011-07-10 10:04:24 UTC (rev 3192) +++ trunk/pyx/manual/manual.rst 2011-07-10 16:04:02 UTC (rev 3193) @@ -1,3 +1,4 @@ + ************************ PyX Reference Manual ************************ Modified: trunk/pyx/manual/path.rst =================================================================== --- trunk/pyx/manual/path.rst 2011-07-10 10:04:24 UTC (rev 3192) +++ trunk/pyx/manual/path.rst 2011-07-10 16:04:02 UTC (rev 3193) @@ -1,3 +1,4 @@ + .. module:: path ================== @@ -11,6 +12,8 @@ the present section. +.. _postscript_like_paths: + Class :class:path --- PostScript-like paths --------------------------------------------- @@ -36,39 +39,34 @@ .. 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 @@ 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 @@ .. 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,61 +132,61 @@ .. 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 + Here, trafo must be an instance of the :class:trafo.trafo class. + [#normpathconvert]_ -Some notes on the above: -* 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. +.. [#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. -* Instead of using the :meth:joined method, you can also join two paths - together with help of the << operator, for instance p = p1 << p2. +.. [#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. -* :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. - .. _path_pathitem: Path elements @@ -225,7 +225,7 @@ .. 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,29 +237,27 @@ 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*). --- + 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: \ +Bézier curves can be constructed using: - .. class:: curveto(x1, y1, x2, y2, x3, y3) Path element which appends a Bézier curve with the current point as first @@ -292,15 +290,15 @@ .. 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 @@ ----------------------- 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 @@ 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 @@ .. 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 @@ ---------------- -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. Modified: trunk/pyx/manual/pattern.rst =================================================================== --- trunk/pyx/manual/pattern.rst 2011-07-10 10:04:24 UTC (rev 3192) +++ trunk/pyx/manual/pattern.rst 2011-07-10 16:04:02 UTC (rev 3193) @@ -1,3 +1,4 @@ + .. module:: pattern ********************* Modified: trunk/pyx/manual/radii2.py =================================================================== --- trunk/pyx/manual/radii2.py 2011-07-10 10:04:24 UTC (rev 3192) +++ trunk/pyx/manual/radii2.py 2011-07-10 16:04:02 UTC (rev 3193) @@ -15,7 +15,7 @@ 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]) Modified: trunk/pyx/manual/text.rst =================================================================== --- trunk/pyx/manual/text.rst 2011-07-10 10:04:24 UTC (rev 3192) +++ trunk/pyx/manual/text.rst 2011-07-10 16:04:02 UTC (rev 3193) @@ -599,8 +599,8 @@ 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 Modified: trunk/pyx/manual/trafo.rst =================================================================== --- trunk/pyx/manual/trafo.rst 2011-07-10 10:04:24 UTC (rev 3192) +++ trunk/pyx/manual/trafo.rst 2011-07-10 16:04:02 UTC (rev 3193) @@ -1,3 +1,4 @@ + .. module:: trafo ******************************************* @@ -12,15 +13,16 @@ and mirroring. -Class trafo -=========== +Class :class:trafo +=================== The trafo class represents a general linear transformation, which is defined -for a vector :math:\vec{x} as :: +for a vector :math:\vec{x} as - XXX: translate this math - \vec{x}' = \mathsf{A}\, \vec{x} + \vec{b}\ , +.. 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. @@ -35,70 +37,71 @@ :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. +.. class:: trafo(matrix=((1,0),(0,1)), vector=(0,0)) -+-----------------------------------------+----------------------------------------------+ -| 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 | -+-----------------------------------------+----------------------------------------------+ + create new trafo instance with transformation matrix and vector +.. method:: apply(x, y) -Subclasses of trafo -=================== + 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. They are listed in the -following table: +each of which corresponds to one trafo method. -+----------------------------------------+----------------------------------------------+ -| 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 | -+----------------------------------------+----------------------------------------------+ +.. 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}). + Modified: trunk/pyx/manual/unit.rst =================================================================== --- trunk/pyx/manual/unit.rst 2011-07-10 10:04:24 UTC (rev 3192) +++ trunk/pyx/manual/unit.rst 2011-07-10 16:04:02 UTC (rev 3193) @@ -1,6 +1,8 @@ .. module:: unit +.. _module_unit: + ****************** Module :mod:unit ****************** @@ -57,8 +59,8 @@ at the beginning of your program. -Class length -============ +Class :class:length +===================== .. class:: length(f, type="u", unit=None) This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. `