summaryrefslogtreecommitdiff
path: root/Build/source/utils/asymptote/doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2014-04-21 22:28:30 +0000
committerKarl Berry <karl@freefriends.org>2014-04-21 22:28:30 +0000
commit447bcd45d972526c26cc8436a8096a7898160bbd (patch)
treee4b7129c70301517228885198ef4dfcd7f2e277d /Build/source/utils/asymptote/doc
parent99c5a17e1c6aea6aa01db94bd7bc0b4ad24af3bd (diff)
asy 2.25 sources again, this time from CTAN
git-svn-id: svn://tug.org/texlive/trunk@33603 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/utils/asymptote/doc')
-rw-r--r--Build/source/utils/asymptote/doc/.cvsignore18
-rw-r--r--Build/source/utils/asymptote/doc/CAD.pdfbin0 -> 68052 bytes
-rw-r--r--Build/source/utils/asymptote/doc/CAD1.asy86
-rw-r--r--Build/source/utils/asymptote/doc/FAQ/asy-faq.info1671
-rw-r--r--Build/source/utils/asymptote/doc/TeXShopAndAsymptote.pdfbin0 -> 31594 bytes
-rw-r--r--Build/source/utils/asymptote/doc/asy-latex.pdfbin0 -> 194499 bytes
-rw-r--r--Build/source/utils/asymptote/doc/asy.1297
-rw-r--r--Build/source/utils/asymptote/doc/asyRefCard.pdfbin0 -> 53907 bytes
-rw-r--r--Build/source/utils/asymptote/doc/asymptote.pdfbin0 -> 1272144 bytes
-rw-r--r--Build/source/utils/asymptote/doc/extra/intro_.bbl38
-rw-r--r--Build/source/utils/asymptote/doc/png/asymptote.info9988
11 files changed, 11999 insertions, 99 deletions
diff --git a/Build/source/utils/asymptote/doc/.cvsignore b/Build/source/utils/asymptote/doc/.cvsignore
deleted file mode 100644
index bd8d0a3caf6..00000000000
--- a/Build/source/utils/asymptote/doc/.cvsignore
+++ /dev/null
@@ -1,18 +0,0 @@
-*.png
-*.jpg
-*.eps
-*.aux
-*.log
-*.dvi
-*.cp
-*.cps
-*.fn
-*.info
-*.ky
-*.pg
-*.toc
-*.tp
-*.vr
-asymptote
-latexusage.asy
-version.texi
diff --git a/Build/source/utils/asymptote/doc/CAD.pdf b/Build/source/utils/asymptote/doc/CAD.pdf
new file mode 100644
index 00000000000..2eeebe293a4
--- /dev/null
+++ b/Build/source/utils/asymptote/doc/CAD.pdf
Binary files differ
diff --git a/Build/source/utils/asymptote/doc/CAD1.asy b/Build/source/utils/asymptote/doc/CAD1.asy
index 4602e73b709..26184aaad2c 100644
--- a/Build/source/utils/asymptote/doc/CAD1.asy
+++ b/Build/source/utils/asymptote/doc/CAD1.asy
@@ -1,43 +1,43 @@
-import CAD;
-
-sCAD cad=sCAD.Create();
-
-// Freehand line
-draw(g=cad.MakeFreehand(pFrom=(3,-1)*cm,(6,-1)*cm),
- p=cad.pFreehand);
-
-// Standard measurement lines
-draw(g=box((0,0)*cm,(1,1)*cm),p=cad.pVisibleEdge);
-cad.MeasureParallel(L="$\sqrt{2}$",
- pFrom=(0,1)*cm,
- pTo=(1,0)*cm,
- dblDistance=-15mm);
-
-// Label inside,shifted to the right; arrows outside
-draw(g=box((2,0)*cm,(3,1)*cm),p=cad.pVisibleEdge);
-cad.MeasureParallel(L="1",
- pFrom=(2,1)*cm,
- pTo=(3,1)*cm,
- dblDistance=5mm,
- dblLeft=5mm,
- dblRelPosition=0.75);
-
-// Label and arrows outside
-draw(g=box((5,0)*cm,(5.5,1)*cm),p=cad.pVisibleEdge);
-cad.MeasureParallel(L="0.5",
- pFrom=(5,1)*cm,
- pTo=(5.5,1)*cm,
- dblDistance=5mm,
- dblLeft=10mm,
- dblRelPosition=-1);
-
-// Small bounds,asymmetric measurement line
-draw(g=box((7,0)*cm,(7.5,1)*cm),p=cad.pVisibleEdge);
-cad.MeasureParallel(L="0.5",
- pFrom=(7,1)*cm,
- pTo=(7.5,1)*cm,
- dblDistance=5mm,
- dblLeft=2*cad.GetMeasurementBoundSize(bSmallBound=true),
- dblRight=10mm,
- dblRelPosition=2,
- bSmallBound=true);
+import CAD;
+
+sCAD cad=sCAD.Create();
+
+// Freehand line
+draw(g=cad.MakeFreehand(pFrom=(3,-1)*cm,(6,-1)*cm),
+ p=cad.pFreehand);
+
+// Standard measurement lines
+draw(g=box((0,0)*cm,(1,1)*cm),p=cad.pVisibleEdge);
+cad.MeasureParallel(L="$\sqrt{2}$",
+ pFrom=(0,1)*cm,
+ pTo=(1,0)*cm,
+ dblDistance=-15mm);
+
+// Label inside,shifted to the right; arrows outside
+draw(g=box((2,0)*cm,(3,1)*cm),p=cad.pVisibleEdge);
+cad.MeasureParallel(L="1",
+ pFrom=(2,1)*cm,
+ pTo=(3,1)*cm,
+ dblDistance=5mm,
+ dblLeft=5mm,
+ dblRelPosition=0.75);
+
+// Label and arrows outside
+draw(g=box((5,0)*cm,(5.5,1)*cm),p=cad.pVisibleEdge);
+cad.MeasureParallel(L="0.5",
+ pFrom=(5,1)*cm,
+ pTo=(5.5,1)*cm,
+ dblDistance=5mm,
+ dblLeft=10mm,
+ dblRelPosition=-1);
+
+// Small bounds,asymmetric measurement line
+draw(g=box((7,0)*cm,(7.5,1)*cm),p=cad.pVisibleEdge);
+cad.MeasureParallel(L="0.5",
+ pFrom=(7,1)*cm,
+ pTo=(7.5,1)*cm,
+ dblDistance=5mm,
+ dblLeft=2*cad.GetMeasurementBoundSize(bSmallBound=true),
+ dblRight=10mm,
+ dblRelPosition=2,
+ bSmallBound=true);
diff --git a/Build/source/utils/asymptote/doc/FAQ/asy-faq.info b/Build/source/utils/asymptote/doc/FAQ/asy-faq.info
new file mode 100644
index 00000000000..30134dc77d7
--- /dev/null
+++ b/Build/source/utils/asymptote/doc/FAQ/asy-faq.info
@@ -0,0 +1,1671 @@
+Info file: asy-faq.info, -*-Text-*-
+produced by bfnnconv.pl from the Bizarre Format With No Name.
+
+INFO-DIR-SECTION Languages
+START-INFO-DIR-ENTRY
+* asymptote FAQ: (asy-faq). Asymptote Frequently Asked Questions.
+END-INFO-DIR-ENTRY
+
+
+File: asy-faq.info, Node: Top, Next: Question 1.1, Up: (dir)
+
+ ASYMPTOTE FREQUENTLY ASKED QUESTIONS
+ 20 Apr 2014
+
+This is the list of Frequently Asked Questions about Asymptote (asy).
+
+Index
+
+* Menu:
+* Section 1:: About Asymptote
+* Section 2:: Questions about installation and setup
+* Section 3:: Questions about paths
+* Section 4:: Questions about labels
+* Section 5:: Questions about arrows
+* Section 6:: Questions about 2D graphs
+* Section 7:: Questions about programming
+* Section 8:: Questions about differences between Asymptote and
+ MetaPost
+* Section 9:: Questions about output
+
+Section 1, About Asymptote
+* Question 1.1:: What is Asymptote?
+* Question 1.2:: How do I obtain Asymptote?
+* Question 1.3:: Where can I ask questions about Asymptote?
+* Question 1.4:: Why was the name Asymptote chosen?
+* Question 1.5:: In the internal Asymptote source code, what does the
+ name camp refer to?
+
+Section 2, Questions about installation and setup
+* Question 2.1:: Is it possible to install Asymptote on Mac OS X?
+* Question 2.2:: Why do I get the error Bad CPU type in executable on
+ installing Asymptote from the MAC OS binary?
+* Question 2.3:: What do I do if I get the error: Error: pdfetex (file
+ pdftex.cfg): cannot open config file...texinfo.tex
+ appears to be broken?
+* Question 2.4:: What do I do if I get the error: ! Undefined control
+ sequence. l.6 @copying?
+* Question 2.5:: Is it possible to integrate Asymptote into LaTeX?
+* Question 2.6:: Is it possible to integrate Asymptote into latex or
+ pdflatex?
+* Question 2.7:: Do I need the tkinter package to install an Asymptote
+ rpm binary?
+* Question 2.8:: What does the path %USERPROFILE%\.asy\config.asy mean?
+* Question 2.9:: Why do I get the error "string not terminated" when I
+ try to set settings.dir="C:\asymptote\";?
+* Question 2.10:: How do I change environment variables in Microsoft
+ Windows, for example, in order to change the default
+ PostScript viewer?
+* Question 2.11:: Under Microsoft Windows XP, why do I get an error like
+ "Invalid Parameter - 432x432"?
+* Question 2.12:: Why does Asymptote freeze upon trying to draw a label
+ with my MikTex installation under Microsoft Windows?
+
+Section 3, Questions about paths
+* Question 3.1:: Why do I get a syntax error message when I specify an
+ integer value for the path tension?
+* Question 3.2:: Shouldn't dots always be the same size?
+
+Section 4, Questions about labels
+* Question 4.1:: How do I get Greek letters like omega to show up in my
+ labels?
+* Question 4.2:: Can Asymptote use matrices as labels?
+* Question 4.3:: How do I tell Asymptote to load a particular LaTeX
+ package, like mathptmx?
+* Question 4.4:: How can I use international fonts in Asymptote labels?
+* Question 4.5:: How can I use Fourier fonts?
+* Question 4.6:: Is there any way to change the default appearance of
+ the decimal separator, using a comma instead of a dot?
+* Question 4.7:: How can I get a rotated label with the filled box
+ rotated as well so that it fits the text?
+* Question 4.8:: How can I rotate labels in a 3D figure?
+* Question 4.9:: How can I draw some squares and circles of a fixed
+ size and put a label in the middle of them?
+* Question 4.10:: The binary operator * can be used to scale the color
+ of a pen by a real number. Does this scaling factor
+ have to be less than 1?
+* Question 4.11:: Why is the space after the comma decimal separator in
+ my locale so large?
+* Question 4.12:: How can I prevent
+ texpreamble("\usepackage[pdftex]{hyperref}") from
+ changing the page size?
+
+Section 5, Questions about arrows
+* Question 5.1:: How do I draw two arrows at arbitrary positions along
+ a path?
+* Question 5.2:: How do I reverse the direction of an arrowhead?
+* Question 5.3:: How do I change the size of all arrows?
+* Question 5.4:: Can I create other arrowhead styles?
+
+Section 6, Questions about 2D graphs
+* Question 6.1:: How can I draw x axis ticks on the right side, with
+ the tick labels on the left side (relative to the axis
+ path)?
+* Question 6.2:: How can I reposition the x axis label to
+ three-quarters along the axis length?
+* Question 6.3:: How can I move the x axis label down 10bp?
+* Question 6.4:: Can I use different pens for the axis, the axis label,
+ and the tick labels?
+* Question 6.5:: How can I change the font type of the axes label?
+* Question 6.6:: How can I change the font type of the tick labels on
+ an axis?
+* Question 6.7:: How can I prevent axes tick labels from rendering on
+ top of each other?
+* Question 6.8:: How do I make the plot region of a graph, ignoring
+ labels and legends, have a fixed size?
+* Question 6.9:: How can I plot a function f(x) within [0,1]x[0,2]
+ without explicitly calculating the x values for which
+ f(x) hits the boundary?
+* Question 6.10:: Is it possible to define customized palettes?
+* Question 6.11:: Is there an easy way to graph factorial functions
+ nicely?
+* Question 6.12:: How do I indicate that a certain length should be
+ exactly the size I prescribe with no rescaling, within
+ a picture which has its own size?
+* Question 6.13:: How can I make the y axis display base-2 logarithmic
+ values?
+* Question 6.14:: How can I align the x axes of two graphs on the same
+ figure?
+* Question 6.15:: How can I change the direction of the y-axis, such
+ that negatives values are on the upper y-axis?
+* Question 6.16:: How can I fill a path with a function that defines the
+ color of each location?
+* Question 6.17:: Is there a way to draw a function that is not
+ explicitly given, such as (y - 2)^2 = x - 1 ?
+* Question 6.18:: Is it possible to reverse or stretch an axis?
+* Question 6.19:: Why can't I use the UnFill option to draw graphs with
+ empty markers?
+* Question 6.20:: How can I force several images to use the same palette
+ range (e.g. the entire 0-255 grayscale range)?
+
+Section 7, Questions about programming
+* Question 7.1:: Is Asymptote an interpreter or a compiler?
+* Question 7.2:: What is the difference between a frame and a picture?
+* Question 7.3:: What is the difference between a path and a guide?
+* Question 7.4:: What is a convenient way to declare and initialize an
+ array of pictures?
+* Question 7.5:: Is there a way to define functions that act on arrays
+ in general (i.e. work for arrays of any type)?
+* Question 7.6:: Is there any way to declare structures ahead of their
+ definition, e.g. where struct A performs some
+ operation on struct B, but B contains an A member?
+* Question 7.7:: Where are static variables in for loops allocated?
+* Question 7.8:: Is there a debugger for asy?
+* Question 7.9:: Do you accept patches for Asymptote?
+
+Section 8, Questions about differences between Asymptote and
+ MetaPost
+* Question 8.1:: What is the equivalent of the MetaPost c[a,b]
+ interpolation operator?
+* Question 8.2:: How does picture scaling differ in Asymptote and
+ MetaPost?
+* Question 8.3:: How can I avoid automatic scaling of a picture?
+* Question 8.4:: What is the equivalent of MetaPost ... command?
+* Question 8.5:: What is the equivalent of the MetaPost pickup command?
+* Question 8.6:: What is the equivalent of the MetaPost whatever
+ command?
+* Question 8.7:: What is the equivalent for the MetaPost command for
+ lray - horiz*v - verti*u = whatever*(LightSource - R),
+ a system of three linear equations for three unknowns:
+ horiz, verti, whatever?
+* Question 8.8:: In MetaPost, it is possible to have a drawing remain
+ the same size in different pictures by defining a unit
+ u and explicitly multiply all the coordinates by u. Is
+ there a better way to do this in Asymptote?
+* Question 8.9:: In MetaPost, one could produce tiling pictures by
+ generating a picture, and then clipping the picture to
+ a rectangle of fixed dimensions around the center of
+ the picture. How is that done in Asymptote?
+
+Section 9, Questions about output
+* Question 9.1:: How can I disable automatic invocation of the PS
+ viewer after an asy file is done processing?
+* Question 9.2:: How do I output jpeg images?
+* Question 9.3:: Can I embed bitmaps (photos) into my drawings and
+ position and scale them?
+* Question 9.4:: Does Asymptote support direct PDF output?
+* Question 9.5:: How to I produce large pictures of high quality in
+ raster format (e.g. png, giff etc).
+* Question 9.6:: Is it possible to produce multi-page documents with
+ asymptote?
+
+
+
+File: asy-faq.info, Node: Section 1, Next: Section 2, Previous: Top, Up: Top
+
+About Asymptote
+
+* Menu:
+* Question 1.1:: What is Asymptote?
+* Question 1.2:: How do I obtain Asymptote?
+* Question 1.3:: Where can I ask questions about Asymptote?
+* Question 1.4:: Why was the name Asymptote chosen?
+* Question 1.5:: In the internal Asymptote source code, what does the
+ name camp refer to?
+
+
+
+File: asy-faq.info, Node: Question 1.1, Next: Question 1.2, Previous: Top, Up: Section 1
+
+Question 1.1. What is Asymptote?
+
+Asymptote is a vector graphics language designed for technical graphics,
+inspired by MetaPost but with IEEE floating-point numerics, native
+three-dimensional graphics, Grayscale/RGB/CMYK colourspaces, and a
+C++-like syntax. Unlike MetaPost, it natively supports multiple-segment
+paths (and hence regions other than simply connected ones), tiling
+patterns, Gouraud shading, tensor patch shading, and PostScript images.
+
+
+File: asy-faq.info, Node: Question 1.2, Next: Question 1.3, Previous: Question 1.1, Up: Section 1
+
+Question 1.2. How do I obtain Asymptote?
+
+Binary releases are available for Linux, MacOS X, and Microsoft Windows
+platforms, in addition to full source code, from the website
+http://asymptote.sourceforge.net/. Many Linux distributions (such as
+RedHat and Debian) now include an Asymptote package (check your
+distribution's documentation for further information about this).
+
+
+File: asy-faq.info, Node: Question 1.3, Next: Question 1.4, Previous: Question 1.2, Up: Section 1
+
+Question 1.3. Where can I ask questions about Asymptote?
+
+If you have a question, please try to find an answer in this FAQ, in the
+extensive Asymptote documentation at
+http://asymptote.sourceforge.net/doc/, or search the forum:
+http://sourceforge.net/forum/forum.php?forum_id=409349.
+
+
+File: asy-faq.info, Node: Question 1.4, Next: Question 1.5, Previous: Question 1.3, Up: Section 1
+
+Question 1.4. Why was the name Asymptote chosen?
+
+Well, it isn't the perfect graphics package, but we do think it is getting
+there asymptotically...
+
+
+File: asy-faq.info, Node: Question 1.5, Next: Question 2.1, Previous: Question 1.4, Up: Section 1
+
+Question 1.5. In the internal Asymptote source code, what does the name camp refer to?
+
+That was our original tentative name for this project, which stood for
+"C's Answer to MetaPost" (the language that inspired Asymptote). However,
+we eventually decided that the name Asymptote better emphasizes the
+mathematical and graphical nature of this language.
+
+
+File: asy-faq.info, Node: Section 2, Next: Section 3, Previous: Section 1, Up: Top
+
+Questions about installation and setup
+
+* Menu:
+* Question 2.1:: Is it possible to install Asymptote on Mac OS X?
+* Question 2.2:: Why do I get the error Bad CPU type in executable on
+ installing Asymptote from the MAC OS binary?
+* Question 2.3:: What do I do if I get the error: Error: pdfetex (file
+ pdftex.cfg): cannot open config file...texinfo.tex
+ appears to be broken?
+* Question 2.4:: What do I do if I get the error: ! Undefined control
+ sequence. l.6 @copying?
+* Question 2.5:: Is it possible to integrate Asymptote into LaTeX?
+* Question 2.6:: Is it possible to integrate Asymptote into latex or
+ pdflatex?
+* Question 2.7:: Do I need the tkinter package to install an Asymptote
+ rpm binary?
+* Question 2.8:: What does the path %USERPROFILE%\.asy\config.asy mean?
+* Question 2.9:: Why do I get the error "string not terminated" when I
+ try to set settings.dir="C:\asymptote\";?
+* Question 2.10:: How do I change environment variables in Microsoft
+ Windows, for example, in order to change the default
+ PostScript viewer?
+* Question 2.11:: Under Microsoft Windows XP, why do I get an error like
+ "Invalid Parameter - 432x432"?
+* Question 2.12:: Why does Asymptote freeze upon trying to draw a label
+ with my MikTex installation under Microsoft Windows?
+
+
+
+File: asy-faq.info, Node: Question 2.1, Next: Question 2.2, Previous: Question 1.5, Up: Section 2
+
+Question 2.1. Is it possible to install Asymptote on Mac OS X?
+
+It is easy to compile Asymptote directly from the source code at
+http://sourceforge.net/project/showfiles.php?group_id=120000 We recommend
+first upgrading to the latest GNU readline library, unless you don't care
+about interactive readline support (in which case configure will
+automatically detect and disable obsolete versions of the readline
+library). Marius Schamschula also maintains a binary package for various
+MacOS X platforms
+http://www.hmug.org/pub/MacOS_X/X/Applications/Publishing/asymptote.
+
+
+File: asy-faq.info, Node: Question 2.2, Next: Question 2.3, Previous: Question 2.1, Up: Section 2
+
+Question 2.2. Why do I get the error Bad CPU type in executable on installing Asymptote from the MAC OS binary?
+
+This means either that you have a binary distribution for another MAC
+architecture, or (according to Marius Schamschula) that you may have a
+missing library. The simplest solution is to compile Asymptote directly
+from the official source:
+http://sourceforge.net/project/showfiles.php?group_id=120000.
+
+
+File: asy-faq.info, Node: Question 2.3, Next: Question 2.4, Previous: Question 2.2, Up: Section 2
+
+Question 2.3. What do I do if I get the error: Error: pdfetex (file pdftex.cfg): cannot open config file...texinfo.tex appears to be broken?
+
+Simply put http://asymptote.sourceforge.net/asymptote.pdf in the directory
+doc and repeat the command make all. Or, if you don't want to build a
+local copy of the documentation, simply proceed with make install-asy.
+
+
+File: asy-faq.info, Node: Question 2.4, Next: Question 2.5, Previous: Question 2.3, Up: Section 2
+
+Question 2.4. What do I do if I get the error: ! Undefined control sequence. l.6 @copying?
+
+Either upgrade your texinfo package or follow one of the easy work arounds
+in *Note Question 2.3:: `What do I do if I get the error: Error: pdfetex
+(file pdftex.cfg): cannot open config file...texinfo.tex appears to be
+broken?'.
+
+
+File: asy-faq.info, Node: Question 2.5, Next: Question 2.6, Previous: Question 2.4, Up: Section 2
+
+Question 2.5. Is it possible to integrate Asymptote into LaTeX?
+
+Yes, see the example latexusage.tex. Dario Teixeira has also written a
+detailed guide on the topic. You can download it from
+http://dario.dse.nl/projects/asylatex/.
+
+Philippe Ivaldi has contributed an Asymptote mode for Emacs users
+http://asymptote.sourceforge.net/doc/Editing-modes.html, which includes a
+lasy-mode that allows one to compile and view the output of one
+\begin{asy}...\end{asy} section at a time.
+
+
+File: asy-faq.info, Node: Question 2.6, Next: Question 2.7, Previous: Question 2.5, Up: Section 2
+
+Question 2.6. Is it possible to integrate Asymptote into latex or pdflatex?
+
+Yes, as of version 1.14, Asymptote supports latex and pdflatex (both in
+EPS/PDF and inline mode), as illustrated by the example latexusage.tex:
+
+pdflatex latexusage
+asy latexusage
+pdflatex latexusage
+
+File: asy-faq.info, Node: Question 2.7, Next: Question 2.8, Previous: Question 2.6, Up: Section 2
+
+Question 2.7. Do I need the tkinter package to install an Asymptote rpm binary?
+
+No, you don't need tkinter unless you want to try out the GUI xasy. Try
+
+rpm -Uvh --nodeps asymptote-x.xx-1.i386.rpm
+where x.xx represents the version number.
+
+
+File: asy-faq.info, Node: Question 2.8, Next: Question 2.9, Previous: Question 2.7, Up: Section 2
+
+Question 2.8. What does the path %USERPROFILE%\.asy\config.asy mean?
+
+That is the way that Microsoft Windows refers to the user profile
+directory. There's nothing really to understand here, just put your
+configuration commands in the file config.asy in a new folder
+%USERPROFILE%\.asy.
+
+
+File: asy-faq.info, Node: Question 2.9, Next: Question 2.10, Previous: Question 2.8, Up: Section 2
+
+Question 2.9. Why do I get the error "string not terminated" when I try to set settings.dir="C:\asymptote\";?
+
+The backslash is an escape character here, so \" is interpreted as a
+verbatim quotation mark, leaving the string without a terminating
+quotation mark. Fortunately, this is the only escaped character in
+double-quoted strings. A final backslash isn't needed here anyway, but
+should you really want one somewhere, you can say:
+settings.dir="C:\asymptote"+'\\';.
+
+
+File: asy-faq.info, Node: Question 2.10, Next: Question 2.11, Previous: Question 2.9, Up: Section 2
+
+Question 2.10. How do I change environment variables in Microsoft Windows, for example, in order to change the default PostScript viewer?
+
+While it is easier to set the corresponding Asymptote configuration
+variable in your config.asy file, here is the procedure for changing
+Microsoft Windows environment variables:
+
+Click on the [Start] button
+
+* RIGHT-click on 'My Computer'
+
+* Choose 'Properties' from the popup menu
+
+* Click the 'Advanced' tab
+
+* Click the 'Environment Variables' button.
+
+
+File: asy-faq.info, Node: Question 2.11, Next: Question 2.12, Previous: Question 2.10, Up: Section 2
+
+Question 2.11. Under Microsoft Windows XP, why do I get an error like "Invalid Parameter - 432x432"?
+
+This means that ImageMagick wasn't properly installed and you are using
+the MSDOS convert program rather than the ImageMagick one. Or you may have
+installed ImageMagick but ran Asymptote from an existing MSDOS window. In
+that case, simply open a new window and try again. If that doesn't work,
+check that
+
+convert --version
+returns something like
+
+Version: ImageMagick 6.2.8 06/27/06 Q16 http://www.imagemagick.org
+
+File: asy-faq.info, Node: Question 2.12, Next: Question 3.1, Previous: Question 2.11, Up: Section 2
+
+Question 2.12. Why does Asymptote freeze upon trying to draw a label with my MikTex installation under Microsoft Windows?
+
+Likely, this means that latex and dvips are not in your default path. Try
+adding the appropriate paths in your config.asy file, for example:
+
+import settings;
+latex="C:\Program Files\MiKTeX 2.7\miktex\bin\latex.exe";
+dvips="C:\Program Files\MiKTeX 2.7\miktex\bin\dvips.exe";
+
+File: asy-faq.info, Node: Section 3, Next: Section 4, Previous: Section 2, Up: Top
+
+Questions about paths
+
+* Menu:
+* Question 3.1:: Why do I get a syntax error message when I specify an
+ integer value for the path tension?
+* Question 3.2:: Shouldn't dots always be the same size?
+
+
+
+File: asy-faq.info, Node: Question 3.1, Next: Question 3.2, Previous: Question 2.12, Up: Section 3
+
+Question 3.1. Why do I get a syntax error message when I specify an integer value for the path tension?
+
+What is happening here is that
+
+draw((0,0)..tension 2..(0,50)..(100,100));
+is read as
+
+draw((0,0)..tension 2. .(0,50)..(100,100));
+So the first . after the two is treated as a decimal point. Just put a
+space after the integer tension value:
+
+draw((0,0)..tension 2 ..(0,50)..(100,100));
+
+File: asy-faq.info, Node: Question 3.2, Next: Question 4.1, Previous: Question 3.1, Up: Section 3
+
+Question 3.2. Shouldn't dots always be the same size?
+
+From the documentation:
+
+"The dot command defined in the module plain draws a dot having a diameter
+equal to an explicit pen linewidth or the default linewidth magnified by
+dotfactor (6 by default)."
+
+Thus, when you use the default pen, the dot will have size 6*linewidth,
+but when you give a pen with an explicit width specified, you will have a
+dot of size linewidth. If you want the first case to behave like the
+second, you may set dotfactor=1.
+
+
+File: asy-faq.info, Node: Section 4, Next: Section 5, Previous: Section 3, Up: Top
+
+Questions about labels
+
+* Menu:
+* Question 4.1:: How do I get Greek letters like omega to show up in my
+ labels?
+* Question 4.2:: Can Asymptote use matrices as labels?
+* Question 4.3:: How do I tell Asymptote to load a particular LaTeX
+ package, like mathptmx?
+* Question 4.4:: How can I use international fonts in Asymptote labels?
+* Question 4.5:: How can I use Fourier fonts?
+* Question 4.6:: Is there any way to change the default appearance of
+ the decimal separator, using a comma instead of a dot?
+* Question 4.7:: How can I get a rotated label with the filled box
+ rotated as well so that it fits the text?
+* Question 4.8:: How can I rotate labels in a 3D figure?
+* Question 4.9:: How can I draw some squares and circles of a fixed
+ size and put a label in the middle of them?
+* Question 4.10:: The binary operator * can be used to scale the color
+ of a pen by a real number. Does this scaling factor
+ have to be less than 1?
+* Question 4.11:: Why is the space after the comma decimal separator in
+ my locale so large?
+* Question 4.12:: How can I prevent
+ texpreamble("\usepackage[pdftex]{hyperref}") from
+ changing the page size?
+
+
+
+File: asy-faq.info, Node: Question 4.1, Next: Question 4.2, Previous: Question 3.2, Up: Section 4
+
+Question 4.1. How do I get Greek letters like omega to show up in my labels?
+
+In (La)TeX, Greek letters can be obtained in math mode by prepending a
+backslash to the letter name. So for a omega symbol, use "$\omega$".
+Everything between the dollar signs is considered to be a math formula.
+Uppercase Greek letters can be used by capitalizing the first letter of
+the name:
+
+label("$\omega$",(0,0));
+label("$\Omega$",(20,0));
+
+File: asy-faq.info, Node: Question 4.2, Next: Question 4.3, Previous: Question 4.1, Up: Section 4
+
+Question 4.2. Can Asymptote use matrices as labels?
+
+Yes:
+usepackage("amsmath");
+label("$\begin{matrix} 1 & 2 \\\ 1 & 1 \end{matrix}$",(0,0));
+
+File: asy-faq.info, Node: Question 4.3, Next: Question 4.4, Previous: Question 4.2, Up: Section 4
+
+Question 4.3. How do I tell Asymptote to load a particular LaTeX package, like mathptmx?
+
+Put
+
+usepackage("mathptmx");
+at the beginning of your file. Note: to enable the Adobe Times Roman font
+for text, you will also need to say:
+defaultpen(TimesRoman());
+
+File: asy-faq.info, Node: Question 4.4, Next: Question 4.5, Previous: Question 4.3, Up: Section 4
+
+Question 4.4. How can I use international fonts in Asymptote labels?
+
+See http://asymptote.sourceforge.net/doc/unicode.html.
+
+
+File: asy-faq.info, Node: Question 4.5, Next: Question 4.6, Previous: Question 4.4, Up: Section 4
+
+Question 4.5. How can I use Fourier fonts?
+
+usepackage("fourier");
+defaultpen(font("T1","fut\textfamilyextension","m","n"));
+
+File: asy-faq.info, Node: Question 4.6, Next: Question 4.7, Previous: Question 4.5, Up: Section 4
+
+Question 4.6. Is there any way to change the default appearance of the decimal separator, using a comma instead of a dot?
+
+Just set your locale appropriately:
+
+locale("it_IT");
+usepackage("icomma");
+label(format(0.5));
+
+File: asy-faq.info, Node: Question 4.7, Next: Question 4.8, Previous: Question 4.6, Up: Section 4
+
+Question 4.7. How can I get a rotated label with the filled box rotated as well so that it fits the text?
+
+frame f;
+label(f,"This is some text",white,Fill(blue));
+add(rotate(65)*f);
+
+File: asy-faq.info, Node: Question 4.8, Next: Question 4.9, Previous: Question 4.7, Up: Section 4
+
+Question 4.8. How can I rotate labels in a 3D figure?
+
+You need to first project the triple to a pair like this:
+
+import three;
+size(100,100);
+
+draw(rotate(90,project(Z))*"A",O--X);
+
+File: asy-faq.info, Node: Question 4.9, Next: Question 4.10, Previous: Question 4.8, Up: Section 4
+
+Question 4.9. How can I draw some squares and circles of a fixed size and put a label in the middle of them?
+
+Fixed-size objects should be drawn on a separate picture and then added to
+currentpicture. Here is one way (see also
+http://asymptote.sourceforge.net/gallery/subpictures.asy and
+http://asymptote.sourceforge.net/gallery/mosquito.asy):
+
+real u=2cm;
+
+picture square;
+draw(square,scale(u)*shift(-0.5,-0.5)*unitsquare);
+
+picture circle;
+draw(circle,scale(0.5u)*unitcircle);
+
+void add(picture pic=currentpicture, Label L, picture object, pair z) {
+add(pic,object,z);
+label(pic,L,z);
+}
+
+add("square",square,(0,0));
+add("circle",circle,(5cm,0));
+
+File: asy-faq.info, Node: Question 4.10, Next: Question 4.11, Previous: Question 4.9, Up: Section 4
+
+Question 4.10. The binary operator * can be used to scale the color of a pen by a real number. Does this scaling factor have to be less than 1?
+
+The scaling factor can be greater than 1. But keep in mind that the rgb
+color components saturate at 1.
+
+Try
+write(cyan); write(0.8*cyan); write(1.5*cyan);
+and you will quickly see what is going on.
+
+To get a lighter cyan you can say white+cyan, which yields rgb(0.5,1,1).
+If you want something even lighter specify the rgb colors directly, for
+example, rgb(0.9,1,1).
+
+Alternatively, work in cmyk colour space, which is nicer in that it
+handles saturation separately from hue:
+
+0.1*Cyan is light and 0.9*Cyan is dark. You can also say 0.1*cmyk(red).
+
+
+File: asy-faq.info, Node: Question 4.11, Next: Question 4.12, Previous: Question 4.10, Up: Section 4
+
+Question 4.11. Why is the space after the comma decimal separator in my locale so large?
+
+LaTeX is treating the comma as punctuation and not as a decimal separator.
+The solution is to load the icomma package near the beginning of your
+file:
+usepackage("icomma");
+
+File: asy-faq.info, Node: Question 4.12, Next: Question 5.1, Previous: Question 4.11, Up: Section 4
+
+Question 4.12. How can I prevent texpreamble("\usepackage[pdftex]{hyperref}") from changing the page size?
+
+texpreamble("\usepackage[pdftex,setpagesize=false]{hyperref}");
+
+File: asy-faq.info, Node: Section 5, Next: Section 6, Previous: Section 4, Up: Top
+
+Questions about arrows
+
+* Menu:
+* Question 5.1:: How do I draw two arrows at arbitrary positions along
+ a path?
+* Question 5.2:: How do I reverse the direction of an arrowhead?
+* Question 5.3:: How do I change the size of all arrows?
+* Question 5.4:: Can I create other arrowhead styles?
+
+
+
+File: asy-faq.info, Node: Question 5.1, Next: Question 5.2, Previous: Question 4.12, Up: Section 5
+
+Question 5.1. How do I draw two arrows at arbitrary positions along a path?
+
+Assuming that at least one of the arrowheads is to be filled, you can do
+this:
+
+size(200);
+path g = (0,0)..(1,3)..(3,0);
+draw(g,Arrow(Relative(0.9)));
+add(arrow(g,invisible,FillDraw(black),Relative(0.5)));
+add(arrow(reverse(g),invisible,FillDraw(white,black),Relative(0.9)));
+If both of the arrowheads are to be drawn with filltype NoFill, one will
+need to create a specialized version of the arrow routine in
+plain_arrows.asy:
+
+void arrow(frame f, arrowhead arrowhead=DefaultHead,
+ path g, pen p=currentpen, real size=0,
+ real angle=arrowangle, filltype filltype=arrowhead.defaultfilltype,
+ position position=EndPoint, bool forwards=true,
+ margin margin=NoMargin, bool center=false);
+
+File: asy-faq.info, Node: Question 5.2, Next: Question 5.3, Previous: Question 5.1, Up: Section 5
+
+Question 5.2. How do I reverse the direction of an arrowhead?
+
+Simply reverse the direction of the path.
+
+path g=((0,0)--(5cm,0));
+draw(reverse(g),Arrow(Relative(0.55)));
+
+File: asy-faq.info, Node: Question 5.3, Next: Question 5.4, Previous: Question 5.2, Up: Section 5
+
+Question 5.3. How do I change the size of all arrows?
+
+To override the arrowsize you can give every Arrow drawing attribute a
+real size argument. If you want to do this globally, you can override the
+pen-dependent arrowsize function like this:
+
+DefaultHead.size=new real(pen p=currentpen) {return 2mm;};
+
+File: asy-faq.info, Node: Question 5.4, Next: Question 6.1, Previous: Question 5.3, Up: Section 5
+
+Question 5.4. Can I create other arrowhead styles?
+
+Yes, you can build custom arrowheads like this (see the predefined
+arrowhead styles in plain_arrows.asy for further examples):
+
+arrowhead DotHead;
+DotHead.head=new path(path g, position position=EndPoint, pen p=currentpen,
+ real size=0, real angle=arrowangle) {
+ if(size == 0) size=DotHead.size(p);
+ bool relative=position.relative;
+ real position=position.position.x;
+ if(relative) position=reltime(g,position);
+ path r=subpath(g,position,0);
+ pair x=point(r,0);
+ real t=arctime(r,size);
+ pair y=point(r,t);
+ return circle(0.5(x+y),0.5size);
+};
+
+size(100);
+draw((0,0)..(1,1)..(2,0),Arrow(DotHead));
+dot((2,0),red);
+If you submit your alternate arrowheads to the Forum or the Patch
+Tracking System, we'll consider including them in a future release.
+
+
+File: asy-faq.info, Node: Section 6, Next: Section 7, Previous: Section 5, Up: Top
+
+Questions about 2D graphs
+
+* Menu:
+* Question 6.1:: How can I draw x axis ticks on the right side, with
+ the tick labels on the left side (relative to the axis
+ path)?
+* Question 6.2:: How can I reposition the x axis label to
+ three-quarters along the axis length?
+* Question 6.3:: How can I move the x axis label down 10bp?
+* Question 6.4:: Can I use different pens for the axis, the axis label,
+ and the tick labels?
+* Question 6.5:: How can I change the font type of the axes label?
+* Question 6.6:: How can I change the font type of the tick labels on
+ an axis?
+* Question 6.7:: How can I prevent axes tick labels from rendering on
+ top of each other?
+* Question 6.8:: How do I make the plot region of a graph, ignoring
+ labels and legends, have a fixed size?
+* Question 6.9:: How can I plot a function f(x) within [0,1]x[0,2]
+ without explicitly calculating the x values for which
+ f(x) hits the boundary?
+* Question 6.10:: Is it possible to define customized palettes?
+* Question 6.11:: Is there an easy way to graph factorial functions
+ nicely?
+* Question 6.12:: How do I indicate that a certain length should be
+ exactly the size I prescribe with no rescaling, within
+ a picture which has its own size?
+* Question 6.13:: How can I make the y axis display base-2 logarithmic
+ values?
+* Question 6.14:: How can I align the x axes of two graphs on the same
+ figure?
+* Question 6.15:: How can I change the direction of the y-axis, such
+ that negatives values are on the upper y-axis?
+* Question 6.16:: How can I fill a path with a function that defines the
+ color of each location?
+* Question 6.17:: Is there a way to draw a function that is not
+ explicitly given, such as (y - 2)^2 = x - 1 ?
+* Question 6.18:: Is it possible to reverse or stretch an axis?
+* Question 6.19:: Why can't I use the UnFill option to draw graphs with
+ empty markers?
+* Question 6.20:: How can I force several images to use the same palette
+ range (e.g. the entire 0-255 grayscale range)?
+
+
+
+File: asy-faq.info, Node: Question 6.1, Next: Question 6.2, Previous: Question 5.4, Up: Section 6
+
+Question 6.1. How can I draw x axis ticks on the right side, with the tick labels on the left side (relative to the axis path)?
+
+import graph;
+
+size(250,200,IgnoreAspect);
+
+draw(graph(exp,-1,1),red);
+
+xaxis("$x$",RightTicks(Label(align=left)));
+yaxis("$y$",RightTicks);
+
+File: asy-faq.info, Node: Question 6.2, Next: Question 6.3, Previous: Question 6.1, Up: Section 6
+
+Question 6.2. How can I reposition the x axis label to three-quarters along the axis length?
+
+import graph;
+
+size(250,200,IgnoreAspect);
+
+draw(graph(exp,-1,1),red);
+
+xaxis(Label("$x$",0.75),LeftTicks);
+yaxis("$y$",RightTicks);
+
+File: asy-faq.info, Node: Question 6.3, Next: Question 6.4, Previous: Question 6.2, Up: Section 6
+
+Question 6.3. How can I move the x axis label down 10bp?
+
+import graph;
+size(250,200,IgnoreAspect);
+
+draw(graph(exp,-1,1),red);
+
+xaxis(shift(0,-10)*"$x$",LeftTicks);
+yaxis("$y$",RightTicks);
+
+File: asy-faq.info, Node: Question 6.4, Next: Question 6.5, Previous: Question 6.3, Up: Section 6
+
+Question 6.4. Can I use different pens for the axis, the axis label, and the tick labels?
+
+Yes:
+
+import graph;
+size(300,200,IgnoreAspect);
+
+xlimits(-50,50);
+ylimits(0,100);
+
+xaxis(Label("$x$",MidPoint,red),Bottom,blue,LeftTicks(green));
+yaxis("$y$",Left,RightTicks);
+
+File: asy-faq.info, Node: Question 6.5, Next: Question 6.6, Previous: Question 6.4, Up: Section 6
+
+Question 6.5. How can I change the font type of the axes label?
+
+import graph;
+size(300,200,IgnoreAspect);
+
+xlimits(-50,50);
+ylimits(0,100);
+
+xaxis("x",Bottom,Courier("m","n"),LeftTicks);
+yaxis("$y$",Left,RightTicks);
+
+File: asy-faq.info, Node: Question 6.6, Next: Question 6.7, Previous: Question 6.5, Up: Section 6
+
+Question 6.6. How can I change the font type of the tick labels on an axis?
+
+Tick labels are by default typeset in (TeX) math mode, so to use other
+fonts you need to override the default tick format:
+
+import graph;
+size(300,200,IgnoreAspect);
+
+xlimits(-50,50);
+ylimits(0,100);
+
+xaxis("$x$",Bottom,LeftTicks("%.4g",Courier("m","n")+fontsize(12)));
+yaxis("$y$",Left,RightTicks);
+
+File: asy-faq.info, Node: Question 6.7, Next: Question 6.8, Previous: Question 6.6, Up: Section 6
+
+Question 6.7. How can I prevent axes tick labels from rendering on top of each other?
+
+Either:
+
+(i) give LeftTicks/RightTicks/Ticks the arguments beginlabel=false and/or
+endlabel=false;
+
+(ii) explicitly remove specific ticks and their labels (drawing them
+manually; see
+http://asymptote.svn.sourceforge.net/viewvc/asymptote/trunk/asymptote/base/graph.asy
+for the definition of NoZero):
+
+import graph;
+
+size(10cm);
+
+real f(real x) {return x^2;}
+
+draw(graph(f,-2,2));
+
+xaxis(Ticks(NoZero));
+yaxis(Ticks(NoZero));
+
+label("$0$",(0,0),SW);
+(iii) explicitly remove specific tick labels and draw them manually (see
+http://asymptote.svn.sourceforge.net/viewvc/asymptote/trunk/asymptote/base/graph.asy
+for the definition of NoZeroFormat):
+
+import graph;
+
+size(10cm);
+
+real f(real x) {return x^2;}
+
+draw(graph(f,-2,2));
+
+xaxis(Ticks(NoZeroFormat));
+yaxis(Ticks(NoZeroFormat));
+
+label("$0$",(0,0),SW);
+(iv) use the xasy GUI to move overlapping labels;
+
+(v) change the Label argument of LeftTicks, RightTicks, or Ticks to:
+
+Label(currentpen+overwrite(Move))
+Solution (v) will move labels that might otherwise overwrite a previous
+label. Other possible overwrite arguments are Allow (allows overlapping
+labels; the default), Suppress (an overlapping label will not be written
+at all), SuppressQuiet, and MoveQuiet. The last two achieve the same
+result as the non-quiet types, but will not notify you which labels are
+overlapping. See: http://asymptote.sourceforge.net/doc/Pens.html.
+
+In the case of a user-specified tick array, you can change which labels
+get suppressed/moved by changing the order of array entries.
+
+
+File: asy-faq.info, Node: Question 6.8, Next: Question 6.9, Previous: Question 6.7, Up: Section 6
+
+Question 6.8. How do I make the plot region of a graph, ignoring labels and legends, have a fixed size?
+
+Either:
+
+i) Specify an explicit unitsize, which overrides any call to size:
+unitsize(x=1cm,y=2cm);
+ii) Explicitly tell Asymptote to map the plot region to a specific size:
+import graph;
+real[] x={0,1,2,3};
+real[] y=x^2;
+draw(graph(x,y),red);
+xaxis("$x$",BottomTop,LeftTicks);
+yaxis("$y$",LeftRight,RightTicks);
+
+size(5cm,5cm,point(SW),point(NE));
+
+label("$f_\mathrm{T}$",point(N),2N);
+iii) Specify the points in user coordinates that should correspond to a
+given picture size:
+
+import graph;
+
+size(250,200,IgnoreAspect);
+
+draw(graph(exp,-1,1),red);
+
+xaxis("$x$",BottomTop,LeftTicks);
+yaxis("$y$",LeftRight,RightTicks);
+
+fixedscaling((-1.5,-0.5),(1.5,3.5));
+In this example, the user coordinate (-1.5,-0.5) will end up being the
+lower left corner of the figure and (1.5,3.5) will be the upper right
+corner. You can use this option to ensure multiple figures have the same
+scaling and same resulting figure size (just ensure the two coordinates
+given to fixedscaling() leaves room for any labels).
+
+See also http://asymptote.sourceforge.net/doc/Frames-and-pictures.html.
+
+
+File: asy-faq.info, Node: Question 6.9, Next: Question 6.10, Previous: Question 6.8, Up: Section 6
+
+Question 6.9. How can I plot a function f(x) within [0,1]x[0,2] without explicitly calculating the x values for which f(x) hits the boundary?
+
+Call limits with the Crop option before drawing the graph:
+import graph;
+
+size(250,200,IgnoreAspect);
+
+draw(graph(exp,-1,1),red);
+
+limits((0,0),(1,2),Crop);
+
+xaxis("$x$",BottomTop,LeftTicks);
+yaxis("$y$",LeftRight,RightTicks);
+See also http://asymptote.sourceforge.net/doc/graph.html.
+
+
+File: asy-faq.info, Node: Question 6.10, Next: Question 6.11, Previous: Question 6.9, Up: Section 6
+
+Question 6.10. Is it possible to define customized palettes?
+
+Yes, you may generate your own pen[] array. For example:
+
+int NColors=32768;
+pen[] MyPalette=new pen[NColors];
+real step=1/(NColors-1.0);
+// Start at black: rgb(0,0,0)
+// End at yellow: rgb(1,1,0)
+for(int i=0; i < NColors; ++i) {
+ real rgval=i*step;
+ MyPalette[i]=rgb(rgval,rgval,0.0);
+}
+
+File: asy-faq.info, Node: Question 6.11, Next: Question 6.12, Previous: Question 6.10, Up: Section 6
+
+Question 6.11. Is there an easy way to graph factorial functions nicely?
+
+The example below shows a continuous function and two methods for placing
+markers at integer values of x:
+
+import graph;
+
+size(200,200,IgnoreAspect);
+
+real factorial(real t) {return gamma(t+1);}
+
+scale(Linear,Log);
+
+// Graph the factorial function.
+draw(graph(factorial,0,10));
+
+// Method 1: Draw nodes, but hide line
+pair F(int t) {return (t,factorial(t));}
+// Graph of factorial function from 0 to 10
+pair[] z=sequence(F,11);
+draw(graph(z),invisible,marker(scale(0.8mm)*unitcircle,blue,Fill));
+
+// Method 2: Nongraphing routines require explicit scaling:
+pair dotloc(int t) {return Scale(F(t));}
+pair[] dotlocs=sequence(dotloc,11);
+dot(dotlocs);
+
+xaxis("$x$",BottomTop,LeftTicks);
+yaxis("$y$",LeftRight,RightTicks);
+
+File: asy-faq.info, Node: Question 6.12, Next: Question 6.13, Previous: Question 6.11, Up: Section 6
+
+Question 6.12. How do I indicate that a certain length should be exactly the size I prescribe with no rescaling, within a picture which has its own size?
+
+Here's an easy way to do this.
+
+size(12cm,0);
+
+void distance(picture pic=currentpicture, pair A, pair B, Label L="", real n=0,
+ pen p=currentpen)
+{
+ real d=3mm;
+ path g=A--B;
+ transform T=shift(-n*d*unit(B-A)*I);
+ pic.add(new void(frame f, transform t) {
+ picture opic;
+ path G=T*t*g;
+ draw(opic,Label(L,Center,UnFill(1)),G,p,Arrows(NoFill),Bars,PenMargins);
+ add(f,opic.fit());
+ });
+ pic.addBox(min(g),max(g),T*min(p),T*max(p));
+}
+
+pair A=(0,0), B=(3,3);
+
+dot(A);
+dot(B);
+
+distance(A,B,"$\ell$",1);
+
+File: asy-faq.info, Node: Question 6.13, Next: Question 6.14, Previous: Question 6.12, Up: Section 6
+
+Question 6.13. How can I make the y axis display base-2 logarithmic values?
+
+See the example http://asymptote.sourceforge.net/gallery/2D
+graphs/log2graph.asy.
+
+
+File: asy-faq.info, Node: Question 6.14, Next: Question 6.15, Previous: Question 6.13, Up: Section 6
+
+Question 6.14. How can I align the x axes of two graphs on the same figure?
+
+An easy way to do this, if the axes to be aligned have the same scaling
+and size, is illustrated in the example
+http://asymptote.sourceforge.net/gallery/2D graphs/alignedaxis.asy.
+
+Here is a more general solution to the problem of aligning two arbitrary
+axes. One fits the second picture to a frame based on the horizontal
+scaling for the first picture:
+
+import graph;
+
+real width=15cm;
+real aspect=0.3;
+
+picture pic1,pic2;
+
+size(pic1,width,aspect*width,IgnoreAspect);
+size(pic2,width,aspect*width,IgnoreAspect);
+
+scale(pic1,false);
+scale(pic2,false);
+
+real xmin1=6;
+real xmax1=9;
+real xmin2=8;
+real xmax2=16;
+
+real a1=1;
+real a2=0.001;
+
+real f1(real x) {return a1*sin(x/2*pi);}
+real f2(real x) {return a2*sin(x/4*pi);}
+
+draw(pic1,graph(pic1,f1,xmin1,xmax1));
+draw(pic2,graph(pic2,f2,xmin2,xmax2));
+
+xaxis(pic1,Bottom,LeftTicks());
+yaxis(pic1,"$f_1(x)$",Left,RightTicks);
+
+xaxis(pic2,"$x$",Bottom,LeftTicks(Step=4));
+yaxis(pic2,"$f_2(x)$",Left,RightTicks);
+
+yequals(pic1,0,Dotted);
+yequals(pic2,0,Dotted);
+
+pair min1=point(pic1,SW);
+pair max1=point(pic1,NE);
+
+pair min2=point(pic2,SW);
+pair max2=point(pic2,NE);
+
+real scale=(max1.x-min1.x)/(max2.x-min2.x);
+real shift=min1.x/scale-min2.x;
+
+transform t1=pic1.calculateTransform();
+transform t2=pic2.calculateTransform();
+transform T=xscale(scale*t1.xx)*yscale(t2.yy);
+
+add(pic1.fit());
+real height=truepoint(N,user=false).y-truepoint(S,user=false).y;
+add(shift(0,-height)*(shift(shift)*pic2).fit(T));
+
+File: asy-faq.info, Node: Question 6.15, Next: Question 6.16, Previous: Question 6.14, Up: Section 6
+
+Question 6.15. How can I change the direction of the y-axis, such that negatives values are on the upper y-axis?
+
+Here is a simple example (see also the example
+http://asymptote.sourceforge.net/gallery/2D graphs/diatom.asy or the
+discussion of Linear(-1) in the documentation):
+
+import graph;
+size(250,200,IgnoreAspect);
+
+scale(Linear,Linear(-1));
+
+draw(graph(log,0.1,10),red);
+
+xaxis("$x$",LeftTicks);
+yaxis("$y$",RightTicks);
+
+File: asy-faq.info, Node: Question 6.16, Next: Question 6.17, Previous: Question 6.15, Up: Section 6
+
+Question 6.16. How can I fill a path with a function that defines the color of each location?
+
+Use functionshade with a PDF tex engine, as illustrated by the example
+{functionshading.asy}.
+
+If you want to produce PostScript output, an approximate solution for now
+would be to superimpose a fine grid and specify colors to latticeshade
+that depend on position as a single pen[][] lattice. Alternatively, it may
+be more efficient to use tensorshade}.
+
+
+File: asy-faq.info, Node: Question 6.17, Next: Question 6.18, Previous: Question 6.16, Up: Section 6
+
+Question 6.17. Is there a way to draw a function that is not explicitly given, such as (y - 2)^2 = x - 1 ?
+
+Yes, use the parametric form
+
+y=t
+x=(t-2)^2+1
+See the example http://asymptote.sourceforge.net/gallery/2D
+graphs/parametricgraph.asy.
+
+
+File: asy-faq.info, Node: Question 6.18, Next: Question 6.19, Previous: Question 6.17, Up: Section 6
+
+Question 6.18. Is it possible to reverse or stretch an axis?
+
+The real scaling argument to Linear is used to stretch (or reverse) the
+axis. To see the effect of axis stretching, be sure not to specify
+IgnoreAspect in the picture size command.
+
+A secondary axis has the same length as the primary axis, so stretching
+cannot have any effect. But one can still reverse the axis, with
+Linear(-1).
+
+
+File: asy-faq.info, Node: Question 6.19, Next: Question 6.20, Previous: Question 6.18, Up: Section 6
+
+Question 6.19. Why can't I use the UnFill option to draw graphs with empty markers?
+
+UnFill won't work here because it only affects the local frame the markers
+are initially drawn on, before being added to currentpicture. Here is a
+way of achieving the desired effect (assuming a white background):
+
+import graph;
+size(10cm,0);
+pair[] z={(0,0),(0.5,0.5),(1,1)};
+path g=graph(z);
+
+draw(shift(0,.5)*g,marker(scale(5)*unitcircle,FillDraw(white)));
+
+xaxis(BottomTop,LeftTicks);
+yaxis(LeftRight,RightTicks);
+
+File: asy-faq.info, Node: Question 6.20, Next: Question 7.1, Previous: Question 6.19, Up: Section 6
+
+Question 6.20. How can I force several images to use the same palette range (e.g. the entire 0-255 grayscale range)?
+
+The palette color space corresponds to a range of values specified by the
+argument range, which can be Full, Automatic or an explicit range
+Range(pair min, pair max). Here Full} specifies a range varying from the
+minimum to maximum values of the function over the sampling interval,
+while Automatic selects "nice" limits.
+
+
+File: asy-faq.info, Node: Section 7, Next: Section 8, Previous: Section 6, Up: Top
+
+Questions about programming
+
+* Menu:
+* Question 7.1:: Is Asymptote an interpreter or a compiler?
+* Question 7.2:: What is the difference between a frame and a picture?
+* Question 7.3:: What is the difference between a path and a guide?
+* Question 7.4:: What is a convenient way to declare and initialize an
+ array of pictures?
+* Question 7.5:: Is there a way to define functions that act on arrays
+ in general (i.e. work for arrays of any type)?
+* Question 7.6:: Is there any way to declare structures ahead of their
+ definition, e.g. where struct A performs some
+ operation on struct B, but B contains an A member?
+* Question 7.7:: Where are static variables in for loops allocated?
+* Question 7.8:: Is there a debugger for asy?
+* Question 7.9:: Do you accept patches for Asymptote?
+
+
+
+File: asy-faq.info, Node: Question 7.1, Next: Question 7.2, Previous: Question 6.20, Up: Section 7
+
+Question 7.1. Is Asymptote an interpreter or a compiler?
+
+Asymptote compiles Asymptote commands into its own virtual machine code.
+It then runs this pseudocode on a virtual machine to produce PostScript
+code.
+
+
+File: asy-faq.info, Node: Question 7.2, Next: Question 7.3, Previous: Question 7.1, Up: Section 7
+
+Question 7.2. What is the difference between a frame and a picture?
+
+Frames are canvases for drawing in PostScript coordinates. While working
+with frames directly is occasionally necessary for constructing deferred
+drawing routines, pictures are usually more convenient to work with. See
+*Note Question 8.8:: `In MetaPost, it is possible to have a drawing remain
+the same size in different pictures by defining a unit u and explicitly
+multiply all the coordinates by u. Is there a better way to do this in
+Asymptote?'.
+
+
+File: asy-faq.info, Node: Question 7.3, Next: Question 7.4, Previous: Question 7.2, Up: Section 7
+
+Question 7.3. What is the difference between a path and a guide?
+
+A path is a cubic spline with fixed endpoint conditions.
+
+A guide is an unresolved cubic spline (list of cubic-spline nodes and
+control points). A guide is like a path except that the computation of the
+cubic spline is deferred until drawing time (when it is resolved into a
+path); this allows two guides with free endpoint conditions to be joined
+together smoothly.
+
+
+File: asy-faq.info, Node: Question 7.4, Next: Question 7.5, Previous: Question 7.3, Up: Section 7
+
+Question 7.4. What is a convenient way to declare and initialize an array of pictures?
+
+You could write yourself a routine such as:
+picture[] picture(int n) {
+ picture[] pic;
+ for(int i=0; i < n; ++i) {
+ pic[i]=new picture;
+ size(pic[i],19cm,0);
+ }
+ return pic;
+}
+
+picture[] pic=picture(6);
+
+File: asy-faq.info, Node: Question 7.5, Next: Question 7.6, Previous: Question 7.4, Up: Section 7
+
+Question 7.5. Is there a way to define functions that act on arrays in general (i.e. work for arrays of any type)?
+
+Generic types aren't yet implemented.
+
+But for now you can at least say
+typedef string T;
+include F;
+
+typedef real T;
+include F;
+where F.asy contains some type-dependent code like
+T[] operator $(T A, T B) {return new T[] {A,B};}
+
+File: asy-faq.info, Node: Question 7.6, Next: Question 7.7, Previous: Question 7.5, Up: Section 7
+
+Question 7.6. Is there any way to declare structures ahead of their definition, e.g. where struct A performs some operation on struct B, but B contains an A member?
+
+Asymptote does not support forward declaration of types. You can, however,
+nest structures, so that both types are visible for parts of the bodies of
+both structure definitions. For example:
+
+struct B {
+ typedef void someroutine(B b);
+
+ static struct A {
+ someroutine routine;
+ void operator init(someroutine routine) {
+ this.routine=routine;
+ }
+ }
+
+ string test="Testing";
+}
+
+typedef B.A A;
+
+A a=B.A(new void(B b){write(b.test);});
+
+B b;
+a.routine(b);
+
+File: asy-faq.info, Node: Question 7.7, Next: Question 7.8, Previous: Question 7.6, Up: Section 7
+
+Question 7.7. Where are static variables in for loops allocated?
+
+In the example
+
+void f() {
+ for(int i=0; i < 3; ++i) {
+ static int n;
+ ++n;
+ write(n);
+ }
+}
+
+f(); // Writes 1, 2, 3
+the static qualifier means that n is allocated not just outside of the for
+loop, but also outside the function. This is clear if you call f multiple
+times; there is still only one instance of n.
+
+The "level" of a variable (where it is allocated) has nothing to do with
+the "scope" of a variable (how long it can be referred to by name). The
+curly braces enclosing a block affect only a variable's scope, not its
+level.
+
+Static modifiers are meaningless at the top level; they generate a warning
+and are simply ignored:
+
+for(int i=0; i < 3; ++i) {
+ static int n;
+ ++n;
+ write(n);
+}
+// Writes warning about top-level static modifier and then 1, 1, 1
+Since version 1.22, non-static variables allocated in a loop body are
+allocated anew every iteration. This is only noticable in obscure cases
+where a variable in a loop is accessed in the closure of a function
+defined in the loop:
+
+int f();
+
+for(int i=0; i < 10; ++i) {
+ int j=10*i;
+ if(i == 5)
+ f=new int() {return j;};
+}
+
+write(f()); // Writes 50
+Variables in the body of a loop last as long as that iteration of the
+loop, unless they are kept alive by a function closure as in the example
+above. In a function body, variables will last at least as long as the
+function call, though because of closures and garbage collection, they may
+last longer than that. If defined at the top level of a file or at the
+interactive prompt, they will last at least until the end of the file or
+prompt's run.
+
+
+File: asy-faq.info, Node: Question 7.8, Next: Question 7.9, Previous: Question 7.7, Up: Section 7
+
+Question 7.8. Is there a debugger for asy?
+
+Yes, Asymptote includes a line-based debugger:
+
+http://asymptote.sourceforge.net/doc/Debugger.html
+
+
+File: asy-faq.info, Node: Question 7.9, Next: Question 8.1, Previous: Question 7.8, Up: Section 7
+
+Question 7.9. Do you accept patches for Asymptote?
+
+Yes, in fact we would prefer that users submit patches for customized
+features (to http://sourceforge.net/tracker/?atid=685685&group_id=120000)
+instead of relying on us to do all of the coding. Development will proceed
+faster that way.
+
+
+File: asy-faq.info, Node: Section 8, Next: Section 9, Previous: Section 7, Up: Top
+
+Questions about differences between Asymptote and MetaPost
+
+* Menu:
+* Question 8.1:: What is the equivalent of the MetaPost c[a,b]
+ interpolation operator?
+* Question 8.2:: How does picture scaling differ in Asymptote and
+ MetaPost?
+* Question 8.3:: How can I avoid automatic scaling of a picture?
+* Question 8.4:: What is the equivalent of MetaPost ... command?
+* Question 8.5:: What is the equivalent of the MetaPost pickup command?
+* Question 8.6:: What is the equivalent of the MetaPost whatever
+ command?
+* Question 8.7:: What is the equivalent for the MetaPost command for
+ lray - horiz*v - verti*u = whatever*(LightSource - R),
+ a system of three linear equations for three unknowns:
+ horiz, verti, whatever?
+* Question 8.8:: In MetaPost, it is possible to have a drawing remain
+ the same size in different pictures by defining a unit
+ u and explicitly multiply all the coordinates by u. Is
+ there a better way to do this in Asymptote?
+* Question 8.9:: In MetaPost, one could produce tiling pictures by
+ generating a picture, and then clipping the picture to
+ a rectangle of fixed dimensions around the center of
+ the picture. How is that done in Asymptote?
+
+
+
+File: asy-faq.info, Node: Question 8.1, Next: Question 8.2, Previous: Question 7.9, Up: Section 8
+
+Question 8.1. What is the equivalent of the MetaPost c[a,b] interpolation operator?
+
+interp(a,b,c);
+
+File: asy-faq.info, Node: Question 8.2, Next: Question 8.3, Previous: Question 8.1, Up: Section 8
+
+Question 8.2. How does picture scaling differ in Asymptote and MetaPost?
+
+Asymptote includes an optional facility to do automatic scaling of
+pictures to achieve a given overall picture size, whereas Metapost only
+supports manual scaling. Asymptote defers drawing of objects drawn to
+pictures and distinguishes between true-size objects and objects that
+should scale with the picture size. The resulting linear programming
+problem is solved via the Simplex method.
+
+See the http://asymptote.sourceforge.net/gallery/dimension.asy example for
+an example of how deferred drawing is used to accomodate both user and
+true-size (PostScript) coordinates.
+
+
+File: asy-faq.info, Node: Question 8.3, Next: Question 8.4, Previous: Question 8.2, Up: Section 8
+
+Question 8.3. How can I avoid automatic scaling of a picture?
+
+If you really like Metapost-style manual (hard-wired) scaling either:
+
+(i) use the default size(0,0) for the entire picture and do all of the
+scaling by hand, just like in MetaPost;
+
+(ii) draw to a separate picture pic and add(pic.fit());
+
+(iii) use frames.
+
+
+File: asy-faq.info, Node: Question 8.4, Next: Question 8.5, Previous: Question 8.3, Up: Section 8
+
+Question 8.4. What is the equivalent of MetaPost ... command?
+
+The connector :: is a macro for tension atleast 1:
+
+size(100);
+pair z0=(0,0);
+pair z1=(1,0.25);
+pair z2=(2,0);
+draw(z0{up}::z1{right}::z2{down});
+
+File: asy-faq.info, Node: Question 8.5, Next: Question 8.6, Previous: Question 8.4, Up: Section 8
+
+Question 8.5. What is the equivalent of the MetaPost pickup command?
+
+Just say, for example:
+
+currentpen=red;
+
+File: asy-faq.info, Node: Question 8.6, Next: Question 8.7, Previous: Question 8.5, Up: Section 8
+
+Question 8.6. What is the equivalent of the MetaPost whatever command?
+
+Asymptote does not implicitly solve linear equations and therefore does
+not have the notion of a whatever unknown. Such a facility could certainly
+be added (perhaps using the notation ?= since = means assignment).
+However, the most common uses of whatever in MetaPost are covered by
+functions like extension in math.asy:
+pair extension(pair P, pair Q, pair p, pair q);
+this returns the intersection point of the extensions of the line segments
+PQ and pq. We find using routines like extension more explicit and less
+confusing to new users. But we could be persuaded to add something similar
+if someone can justify the need. In the meantime, one can always use the
+explicit built-in linear solver solve (see
+http://asymptote.sourceforge.net/doc/solve.html), which uses LU
+decomposition.
+
+
+File: asy-faq.info, Node: Question 8.7, Next: Question 8.8, Previous: Question 8.6, Up: Section 8
+
+Question 8.7. What is the equivalent for the MetaPost command for lray - horiz*v - verti*u = whatever*(LightSource - R), a system of three linear equations for three unknowns: horiz, verti, whatever?
+
+Since horiz*v+verti*u spans a plane, you could use
+real intersect(vector P, vector Q, vector n, vector Z);
+to find the intersection time for the line lray-whatever*(LightSource -
+R) and then extract the three desired values from there. (You'll still
+need to use the built-in explicit linear solver to solve a 2x2 system to
+get horiz and verti.)
+
+
+File: asy-faq.info, Node: Question 8.8, Next: Question 8.9, Previous: Question 8.7, Up: Section 8
+
+Question 8.8. In MetaPost, it is possible to have a drawing remain the same size in different pictures by defining a unit u and explicitly multiply all the coordinates by u. Is there a better way to do this in Asymptote?
+
+Yes, Asymptote has a better way: you definitely don't want to manually
+scale all of your coordinates. To make the user coordinates represent
+multiples of exactly 1cm:
+
+unitsize(1cm);
+draw(unitsquare);
+One can also specify different x and y unit sizes:
+
+unitsize(x=1cm,y=2cm);
+draw(unitsquare);
+Another way is to draw your fixed size object to a frame and add it to
+currentpicture like this:
+
+path p=(0,0)--(1,0);
+frame object;
+draw(object,scale(100)*p);
+
+add(object);
+add(object,(0,-10));
+To understand the difference between frames and pictures, try this:
+
+size(300,300);
+
+path p=(0,0)--(1,0);
+picture object;
+draw(object,scale(100)*p);
+
+add(object);
+add(object,(0,-10)); // Adds truesize object to currentpicture
+
+File: asy-faq.info, Node: Question 8.9, Next: Question 9.1, Previous: Question 8.8, Up: Section 8
+
+Question 8.9. In MetaPost, one could produce tiling pictures by generating a picture, and then clipping the picture to a rectangle of fixed dimensions around the center of the picture. How is that done in Asymptote?
+
+If you are using currentpicture the way one would in MetaPost (drawing in
+raw PostScript coordinates), you can simply do something like:
+
+fill((0,0)--(100,100)--(200,0)--cycle);
+
+pair center(picture pic=currentpicture) {return 0.5*(pic.min()+pic.max());}
+
+real height=100;
+real width=100;
+pair delta=0.5(width,height);
+pair c=center();
+clip(box(c-delta,c+delta));
+However, drawing in PostScript coordinates is often inconvenient. Here's
+the Asymptote way of doing the same thing, using deferred drawing:
+
+size(200,100);
+fill((0,0)--(1,1)--(2,0)--cycle);
+
+void clip(picture pic=currentpicture, real width, real height)
+{
+ pic.clip(new void (frame f, transform) {
+ pair center=0.5(min(f)+max(f));
+ pair delta=0.5(width,height);
+ clip(f,box(center-delta,center+delta));
+ });
+}
+
+clip(100,100);
+See also the discussion of tilings in the documentation:
+http://asymptote.sourceforge.net/doc/Pens.html.
+
+
+File: asy-faq.info, Node: Section 9, Previous: Section 8, Up: Top
+
+Questions about output
+
+* Menu:
+* Question 9.1:: How can I disable automatic invocation of the PS
+ viewer after an asy file is done processing?
+* Question 9.2:: How do I output jpeg images?
+* Question 9.3:: Can I embed bitmaps (photos) into my drawings and
+ position and scale them?
+* Question 9.4:: Does Asymptote support direct PDF output?
+* Question 9.5:: How to I produce large pictures of high quality in
+ raster format (e.g. png, giff etc).
+* Question 9.6:: Is it possible to produce multi-page documents with
+ asymptote?
+
+
+
+File: asy-faq.info, Node: Question 9.1, Next: Question 9.2, Previous: Question 8.9, Up: Section 9
+
+Question 9.1. How can I disable automatic invocation of the PS viewer after an asy file is done processing?
+
+It's actually not on by default, unless you happen to be using Microsoft
+Windows (because that is what most Microsoft Windows users expect).
+Microsoft Windows users can turn this feature off with the command-line
+option -noV or by putting
+
+import settings;
+interactiveView=false;
+batchView=false;
+in their config.asy file. See
+http://asymptote.sourceforge.net/doc/Options.html.
+
+
+File: asy-faq.info, Node: Question 9.2, Next: Question 9.3, Previous: Question 9.1, Up: Section 9
+
+Question 9.2. How do I output jpeg images?
+
+If you have the ImageMagick convert program installed, simply type
+
+asy -f jpg test.asy
+
+File: asy-faq.info, Node: Question 9.3, Next: Question 9.4, Previous: Question 9.2, Up: Section 9
+
+Question 9.3. Can I embed bitmaps (photos) into my drawings and position and scale them?
+
+Convert them to eps format and use the graphic(string) function just like
+a Label:
+
+label(graphic("file"),(0,0));
+See the example http://asymptote.sourceforge.net/gallery/orthocenter.asy
+and http://asymptote.sourceforge.net/doc/label.html.
+
+
+File: asy-faq.info, Node: Question 9.4, Next: Question 9.5, Previous: Question 9.3, Up: Section 9
+
+Question 9.4. Does Asymptote support direct PDF output?
+
+Yes, PDF output can be produced by the -f pdf option or -tex pdflatex
+option. This supports transparency, annotations, embedded movies, and
+U3D/PRC content.
+
+
+File: asy-faq.info, Node: Question 9.5, Next: Question 9.6, Previous: Question 9.4, Up: Section 9
+
+Question 9.5. How to I produce large pictures of high quality in raster format (e.g. png, giff etc).
+
+Try using some of the options to convert, mainly -geometry and -density.
+For example:
+convert -geometry 1000x3000 example.eps example.png
+You can also change the default resolution of the image with:
+convert -geometry 1000x3000 -density 300 -units PixelsPerInch example.eps example.png
+This does not change the number of pixels in the image, but just gives a
+hint as to how large each pixel should be displayed.
+
+If you include the -density option without the -geometry option, convert
+will keep the image size constant (so a 4cm x 3cm eps figure will
+generate a 4cm x 3cm png image).
+
+
+File: asy-faq.info, Node: Question 9.6, Previous: Question 9.5, Up: Section 9
+
+Question 9.6. Is it possible to produce multi-page documents with asymptote?
+
+Yes, simply call the newpage() function. This is used by the slide.asy
+package to produce high-quality slide presentations (easier to use than
+Prosper).
+
diff --git a/Build/source/utils/asymptote/doc/TeXShopAndAsymptote.pdf b/Build/source/utils/asymptote/doc/TeXShopAndAsymptote.pdf
new file mode 100644
index 00000000000..e956672af0d
--- /dev/null
+++ b/Build/source/utils/asymptote/doc/TeXShopAndAsymptote.pdf
Binary files differ
diff --git a/Build/source/utils/asymptote/doc/asy-latex.pdf b/Build/source/utils/asymptote/doc/asy-latex.pdf
new file mode 100644
index 00000000000..bb3e9426e26
--- /dev/null
+++ b/Build/source/utils/asymptote/doc/asy-latex.pdf
Binary files differ
diff --git a/Build/source/utils/asymptote/doc/asy.1 b/Build/source/utils/asymptote/doc/asy.1
new file mode 100644
index 00000000000..979fd50ee38
--- /dev/null
+++ b/Build/source/utils/asymptote/doc/asy.1
@@ -0,0 +1,297 @@
+.\" Hey, EMACS: -*- nroff -*-
+.TH ASY 1 "1 Dec 2004"
+.SH NAME
+asy \- Asymptote: a script-based vector graphics language
+.SH SYNOPSIS
+.B asy
+.RI [ options ]
+.RI [ file \ ...]
+.SH DESCRIPTION
+\fBAsymptote\fP is a powerful descriptive vector graphics language for
+technical drawings, inspired by MetaPost but with an improved C++-like syntax.
+Asymptote provides for figures the same high-quality level of typesetting that
+LaTeX does for scientific text.
+.SH OPTIONS
+If no arguments are given, Asymptote runs in interactive mode.
+.PP
+If "\-" is given as the file argument, Asymptote reads from standard input.
+.PP
+A summary of options is included below. The effect of most options
+can be negated by prepending
+.B no
+to the option name.
+Default values for most options may also be entered in the
+file
+.B .asy/config.asy
+in the user's home directory using the long form:
+.PP
+ import settings;
+ batchView=true;
+.PP
+For a complete
+description, see the Info files.
+.TP
+.B \-V,\-View
+View output; command-line only.
+.TP
+.B \-a,\-align C|B|T|Z
+Center, Bottom, Top, or Zero page alignment [C].
+.TP
+.B \-antialias n
+Antialiasing width for rasterized output [2].
+.TP
+.B \-arcballradius pixels
+Arcball radius [750].
+.TP
+.B \-auto3D
+Automatically activate 3D scene [true].
+.TP
+.B \-autobillboard
+3D labels always face viewer by default [true].
+.TP
+.B \-autoimport string
+Module to automatically import.
+.TP
+.B \-autoplain
+Enable automatic importing of plain [true].
+.TP
+.B \-autoplay
+Autoplay 3D animations [false].
+.TP
+.B \-autorotate
+Enable automatic PDF page rotation [false].
+.TP
+.B \-axes3
+Show 3D axes in PDF output [true].
+.TP
+.B \-batchMask
+Mask fpu exceptions in batch mode [false].
+.TP
+.B \-batchView
+View output in batch mode [false].
+.TP
+.B \-bw
+Convert all colors to black and white [false].
+.TP
+.B \-cd directory
+Set current directory; command-line only.
+.TP
+.B \-cmyk
+Convert rgb colors to cmyk [false].
+.TP
+.B \-c,\-command string
+Command to autoexecute.
+.TP
+.B \-compact
+Conserve memory at the expense of speed [false].
+.TP
+.B \-d,\-debug
+Enable debugging messages [false].
+.TP
+.B \-divisor n
+Garbage collect using purge(divisor=n) [2].
+.TP
+.B \-doubleclick ms
+Emulated double-click timeout [200].
+.TP
+.B \-embed
+Embed rendered preview image [true].
+.TP
+.B \-exitonEOF
+Exit interactive mode on EOF [true].
+.TP
+.B \-fitscreen
+Fit rendered image to screen [true].
+.TP
+.B \-framedelay ms
+Additional frame delay [0].
+.TP
+.B \-framerate frames/s
+Animation speed [30].
+.TP
+.B \-globalwrite
+Allow write to other directory [false].
+.TP
+.B \-gray
+Convert all colors to grayscale [false].
+.TP
+.B \-h,\-help
+Show summary of options; command-line only.
+.TP
+.B \-historylines n
+Retain n lines of history [1000].
+.TP
+.B \-iconify
+Iconify rendering window [false].
+.TP
+.B \-inlineimage
+Generate inline embedded image [false].
+.TP
+.B \-inlinetex
+Generate inline TeX code [false].
+.TP
+.B \-interactiveMask
+Mask fpu exceptions in interactive mode [true].
+.TP
+.B \-interactiveView
+View output in interactive mode [true].
+.TP
+.B \-interactiveWrite
+Write expressions entered at the prompt to stdout [true].
+.TP
+.B \-k,\-keep
+Keep intermediate files [false].
+.TP
+.B \-keepaux
+Keep intermediate LaTeX .aux files [false].
+.TP
+.B \-level n
+Postscript level [3].
+.TP
+.B \-l,\-listvariables
+List available global functions and variables [false].
+.TP
+.B \-localhistory
+Use a local interactive history file [false].
+.TP
+.B \-loop
+Loop 3D animations [false].
+.TP
+.B \-m,\-mask
+Mask fpu exceptions; command-line only.
+.TP
+.B \-maxtile pair
+Maximum rendering tile size [(1024,768)].
+.TP
+.B \-maxviewport pair
+Maximum viewport size [(2048,2048)].
+.TP
+.B \-multiline
+Input code over multiple lines at the prompt [false].
+.TP
+.B \-multipleView
+View output from multiple batch-mode files [false].
+.TP
+.B \-multisample n
+Multisampling width for screen images [4].
+.TP
+.B \-offscreen
+Use offscreen rendering [false].
+.TP
+.B \-O,\-offset pair
+PostScript offset [(0,0)].
+.TP
+.B \-f,\-outformat format
+Convert each output file to specified format.
+.TP
+.B \-o,\-outname name
+Alternative output directory/filename.
+.TP
+.B \-p,\-parseonly
+Parse file [false].
+.TP
+.B \-pdfreload
+Automatically reload document in pdfviewer [false].
+.TP
+.B \-pdfreloaddelay usec
+Delay before attempting initial pdf reload [750000].
+.TP
+.B \-position pair
+Initial 3D rendering screen position [(0,0)].
+.TP
+.B \-prc
+Embed 3D PRC graphics in PDF output [true].
+.TP
+.B \-prompt string
+Prompt [> ].
+.TP
+.B \-prompt2 string
+Continuation prompt for multiline input [..].
+.TP
+.B \-q,\-quiet
+Suppress welcome message [false].
+.TP
+.B \-render n
+Render 3D graphics using n pixels per bp (-1=auto) [-1].
+.TP
+.B \-resizestep step
+Resize step [1.2].
+.TP
+.B \-reverse
+reverse 3D animations [false].
+.TP
+.B \-rgb
+Convert cmyk colors to rgb [false].
+.TP
+.B \-safe
+Disable system call [true].
+.TP
+.B \-scroll n
+Scroll standard output n lines at a time [0].
+.TP
+.B \-spinstep deg/s
+Spin speed [60].
+.TP
+.B \-svgemulation
+Emulate unimplemented SVG shading [false].
+.TP
+.B \-tabcompletion
+Interactive prompt auto-completion [true].
+.TP
+.B \-tex engine
+latex|pdflatex|xelatex|tex|pdftex|context|none [latex].
+.TP
+.B \-thick
+Render thick 3D lines [true].
+.TP
+.B \-thin
+Render thin 3D lines [true].
+.TP
+.B \-threads
+Use POSIX threads for 3D rendering [true].
+.TP
+.B \-toolbar
+Show 3D toolbar in PDF output [true].
+.TP
+.B \-s,\-translate
+Show translated virtual machine code [false].
+.TP
+.B \-twice
+Run LaTeX twice (to resolve references) [false].
+.TP
+.B \-twosided
+Use two-sided 3D lighting model for rendering [true].
+.TP
+.B \-u,\-user string
+General purpose user string.
+.TP
+.B \-v,\-verbose
+Increase verbosity level (can specify multiple times) [0].
+.TP
+.B \-version
+Show version; command-line only.
+.TP
+.B \-wait
+Wait for child processes to finish before exiting [false].
+.TP
+.B \-warn string
+Enable warning; command-line only.
+.TP
+.B \-where
+Show where listed variables are declared [false].
+.TP
+.B \-zoomfactor factor
+Zoom step factor [1.05].
+.TP
+.B \-zoomstep step
+Mouse motion zoom step [0.1].
+
+.SH SEE ALSO
+Asymptote is documented fully in the asymptote Info page.
+The manual can also be accessed in interactive mode with the "help" command.
+
+.SH AUTHOR
+Asymptote was written by Andy Hammerlindl, John Bowman, and Tom Prince.
+.PP
+This manual page was written by Hubert Chan for the Debian project (but may
+be used by others).
diff --git a/Build/source/utils/asymptote/doc/asyRefCard.pdf b/Build/source/utils/asymptote/doc/asyRefCard.pdf
new file mode 100644
index 00000000000..c65e097e700
--- /dev/null
+++ b/Build/source/utils/asymptote/doc/asyRefCard.pdf
Binary files differ
diff --git a/Build/source/utils/asymptote/doc/asymptote.pdf b/Build/source/utils/asymptote/doc/asymptote.pdf
new file mode 100644
index 00000000000..8dd542c1c2f
--- /dev/null
+++ b/Build/source/utils/asymptote/doc/asymptote.pdf
Binary files differ
diff --git a/Build/source/utils/asymptote/doc/extra/intro_.bbl b/Build/source/utils/asymptote/doc/extra/intro_.bbl
deleted file mode 100644
index cf591457f05..00000000000
--- a/Build/source/utils/asymptote/doc/extra/intro_.bbl
+++ /dev/null
@@ -1,38 +0,0 @@
-\begin{thebibliography}{Bow07}
-
-\bibitem[BH08]{Bowman08}
-John~C. Bowman and Andy Hammerlindl.
-\newblock Asymptote: A vector graphics language.
-\newblock {\em TUGboat: The Communications of the \TeX\ Users Group},
- 29(2):288--294, 2008.
-
-\bibitem[Bow07]{Bowman07}
-John~C. Bowman.
-\newblock {The 3D {A}symptote generalization of MetaPost B\'ezier
- interpolation}.
-\newblock {\em Proceedings in Applied Mathematics and Mechanics},
- 7(1):2010021--2010022, 2007.
-
-\bibitem[BS09]{Bowman09}
-John~C. Bowman and Orest Shardt.
-\newblock Asymptote: Lifting {\TeX} to three dimensions.
-\newblock {\em TUGboat: The Communications of the \TeX\ Users Group},
- 30(1):58--63, 2009.
-
-\bibitem[Hob86]{Hobby86}
-John~D. Hobby.
-\newblock Smooth, easy to compute interpolating splines.
-\newblock {\em Discrete Comput. Geom.}, 1:123--140, 1986.
-
-\bibitem[Knu86]{Knuth86b}
-Donald~E. Knuth.
-\newblock {\em The \MF{}book}.
-\newblock Addison-Wesley, Reading, Massachusetts, 1986.
-
-\bibitem[SB10]{Shardt10}
-Orest Shardt and John~C. Bowman.
-\newblock Surface parametrization of nonsimply connected planar {B\'ezier}
- regions.
-\newblock {\em Submitted to Computer Aided Design}, 2010.
-
-\end{thebibliography}
diff --git a/Build/source/utils/asymptote/doc/png/asymptote.info b/Build/source/utils/asymptote/doc/png/asymptote.info
new file mode 100644
index 00000000000..d9bfe6891e3
--- /dev/null
+++ b/Build/source/utils/asymptote/doc/png/asymptote.info
@@ -0,0 +1,9988 @@
+This is asymptote.info, produced by makeinfo version 4.13 from
+../asymptote.texi.
+
+This file documents `Asymptote', version 2.25.
+
+ `http://asymptote.sourceforge.net'
+
+ Copyright (C) 2004-14 Andy Hammerlindl, John Bowman, and Tom Prince.
+
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Lesser General Public License
+ (see the file LICENSE in the top-level source directory).
+
+
+INFO-DIR-SECTION Languages
+START-INFO-DIR-ENTRY
+* asymptote: (asymptote/asymptote). Vector graphics language.
+END-INFO-DIR-ENTRY
+
+
+File: asymptote.info, Node: Top, Next: Description, Up: (dir)
+
+Asymptote
+*********
+
+This file documents `Asymptote', version 2.25.
+
+ `http://asymptote.sourceforge.net'
+
+ Copyright (C) 2004-14 Andy Hammerlindl, John Bowman, and Tom Prince.
+
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Lesser General Public License
+ (see the file LICENSE in the top-level source directory).
+
+
+* Menu:
+
+* Description:: What is `Asymptote'?
+* Installation:: Downloading and installing
+* Tutorial:: Getting started
+* Drawing commands:: Four primitive graphics commands
+* Bezier curves:: Path connectors and direction specifiers
+* Programming:: The `Asymptote' vector graphics language
+* LaTeX usage:: Embedding `Asymptote' commands within `LaTeX'
+* Base modules:: Base modules shipped with `Asymptote'
+* Options:: Command-line options
+* Interactive mode:: Typing `Asymptote' commands interactively
+* GUI:: Graphical user interface
+* PostScript to Asymptote:: `Asymptote' backend to `pstoedit'
+* Help:: Where to get help and submit bug reports
+* Debugger:: Squish those bugs!
+* Credits:: Contributions and acknowledgments
+* Index:: General index
+
+ --- The Detailed Node Listing ---
+
+Installation
+
+* UNIX binary distributions:: Prebuilt `UNIX' binaries
+* MacOS X binary distributions:: Prebuilt `MacOS X' binaries
+* Microsoft Windows:: Prebuilt `Microsoft Windows' binary
+* Configuring:: Configuring `Asymptote' for your system
+* Search paths:: Where `Asymptote' looks for your files
+* Compiling from UNIX source:: Building `Asymptote' from scratch
+* Editing modes:: Convenient `emacs' and `vim' modes
+* Subversion:: Getting the latest development source
+* Uninstall:: Goodbye, `Asymptote'!
+
+Drawing commands
+
+* draw:: Draw a path on a picture or frame
+* fill:: Fill a cyclic path on a picture or frame
+* clip:: Clip a picture or frame to a cyclic path
+* label:: Label a point on a picture
+
+Programming
+
+* Data types:: void, bool, int, real, pair, triple, string
+* Paths and guides:: Bezier curves
+* Pens:: Colors, line types, line widths, font sizes
+* Transforms:: Affine transforms
+* Frames and pictures:: Canvases for immediate and deferred drawing
+* Files:: Reading and writing your data
+* Variable initializers:: Initialize your variables
+* Structures:: Organize your data
+* Operators:: Arithmetic and logical operators
+* Implicit scaling:: Avoiding those ugly *s
+* Functions:: Traditional and high-order functions
+* Arrays:: Dynamic vectors
+* Casts:: Implicit and explicit casts
+* Import:: Importing external `Asymptote' modules
+* Static:: Where to allocate your variable?
+
+Operators
+
+* Arithmetic & logical:: Basic mathematical operators
+* Self & prefix operators:: Increment and decrement
+* User-defined operators:: Overloading operators
+
+Functions
+
+* Default arguments:: Default values can appear anywhere
+* Named arguments:: Assigning function arguments by keyword
+* Rest arguments:: Functions with a variable number of arguments
+* Mathematical functions:: Standard libm functions
+
+
+Arrays
+
+* Slices:: Python-style array slices
+
+Base modules
+
+* plain:: Default `Asymptote' base file
+* simplex:: Linear programming: simplex method
+* math:: Extend `Asymptote''s math capabilities
+* interpolate:: Interpolation routines
+* geometry:: Geometry routines
+* trembling:: Wavy lines
+* stats:: Statistics routines and histograms
+* patterns:: Custom fill and draw patterns
+* markers:: Custom path marker routines
+* tree:: Dynamic binary search tree
+* binarytree:: Binary tree drawing module
+* drawtree:: Tree drawing module
+* syzygy:: Syzygy and braid drawing module
+* feynman:: Feynman diagrams
+* roundedpath:: Round the sharp corners of paths
+* animation:: Embedded PDF and MPEG movies
+* embed:: Embedding movies, sounds, and 3D objects
+* slide:: Making presentations with `Asymptote'
+* MetaPost:: `MetaPost' compatibility routines
+* unicode:: Accept `unicode' (UTF-8) characters
+* latin1:: Accept `ISO 8859-1' characters
+* babel:: Interface to `LaTeX' `babel' package
+* labelpath:: Drawing curved labels
+* labelpath3:: Drawing curved labels in 3D
+* annotate:: Annotate your PDF files
+* CAD:: 2D CAD pen and measurement functions (DIN 15)
+* graph:: 2D linear & logarithmic graphs
+* palette:: Color density images and palettes
+* three:: 3D vector graphics
+* obj:: 3D obj files
+* graph3:: 3D linear & logarithmic graphs
+* grid3:: 3D grids
+* solids:: 3D solid geometry
+* tube:: 3D rotation minimizing tubes
+* flowchart:: Flowchart drawing routines
+* contour:: Contour lines
+* contour3:: Contour surfaces
+* slopefield:: Slope fields
+* ode:: Ordinary differential equations
+
+Graphical User Interface
+
+* GUI installation:: Installing `xasy'
+* GUI usage::
+
+
+File: asymptote.info, Node: Description, Next: Installation, Prev: Top, Up: Top
+
+1 Description
+*************
+
+`Asymptote' is a powerful descriptive vector graphics language that
+provides a mathematical coordinate-based framework for technical
+drawings. Labels and equations are typeset with `LaTeX', for overall
+document consistency, yielding the same high-quality level of
+typesetting that `LaTeX' provides for scientific text. By default it
+produces `PostScript' output, but it can also generate any format that
+the `ImageMagick' package can produce.
+
+ A major advantage of `Asymptote' over other graphics packages is
+that it is a high-level programming language, as opposed to just a
+graphics program: it can therefore exploit the best features of the
+script (command-driven) and graphical-user-interface (GUI) methods for
+producing figures. The rudimentary GUI `xasy' included with the package
+allows one to move script-generated objects around. To make `Asymptote'
+accessible to the average user, this GUI is currently being developed
+into a full-fledged interface that can generate objects directly.
+However, the script portion of the language is now ready for general
+use by users who are willing to learn a few simple `Asymptote' graphics
+commands (*note Drawing commands::).
+
+ `Asymptote' is mathematically oriented (e.g. one can use complex
+multiplication to rotate a vector) and uses `LaTeX' to do the
+typesetting of labels. This is an important feature for scientific
+applications. It was inspired by an earlier drawing program (with a
+weaker syntax and capabilities) called `MetaPost'.
+
+ The `Asymptote' vector graphics language provides:
+
+ * a standard for typesetting mathematical figures, just as
+ TeX/`LaTeX' is the de-facto standard for typesetting equations.
+
+ * `LaTeX' typesetting of labels, for overall document consistency;
+
+ * the ability to generate and embed 3D vector PRC graphics within
+ PDF files;
+
+ * a natural coordinate-based framework for technical drawings,
+ inspired by `MetaPost', with a much cleaner, powerful C++-like
+ programming syntax;
+
+ * compilation of figures into virtual machine code for speed, without
+ sacrificing portability;
+
+ * the power of a script-based language coupled to the convenience of
+ a GUI;
+
+ * customization using its own C++-like graphics programming language;
+
+ * sensible defaults for graphical features, with the ability to
+ override;
+
+ * a high-level mathematically oriented interface to the `PostScript'
+ language for vector graphics, including affine transforms and
+ complex variables;
+
+ * functions that can create new (anonymous) functions;
+
+ * deferred drawing that uses the simplex method to solve overall size
+ constraint issues between fixed-sized objects (labels and
+ arrowheads) and objects that should scale with figure size;
+
+
+ Many of the features of `Asymptote' are written in the `Asymptote'
+language itself. While the stock version of `Asymptote' is designed for
+mathematics typesetting needs, one can write `Asymptote' modules that
+tailor it to specific applications. A scientific graphing module has
+already been written (*note graph::). Examples of `Asymptote' code and
+output, including animations, are available at
+
+ `http://asymptote.sourceforge.net/gallery/'.
+ Links to many external resources, including an excellent user-written
+`Asymptote' tutorial can be found at
+
+ `http://asymptote.sourceforge.net/links.html'.
+ A quick reference card for `Asymptote' is available at
+
+ `http://asymptote.sourceforge.net/asyRefCard.pdf'.
+
+
+File: asymptote.info, Node: Installation, Next: Tutorial, Prev: Description, Up: Top
+
+2 Installation
+**************
+
+* Menu:
+
+* UNIX binary distributions:: Prebuilt `UNIX' binaries
+* MacOS X binary distributions:: Prebuilt `MacOS X' binaries
+* Microsoft Windows:: Prebuilt `Microsoft Windows' binary
+* Configuring:: Configuring `Asymptote' for your system
+* Search paths:: Where `Asymptote' looks for your files
+* Compiling from UNIX source:: Building `Asymptote' from scratch
+* Editing modes:: Convenient `emacs' and `vim' modes
+* Subversion:: Getting the latest development source
+* Uninstall:: Goodbye, `Asymptote'!
+
+ After following the instructions for your specific distribution,
+please see also *note Configuring::.
+
+We recommend subscribing to new release announcements at
+
+ `http://freshmeat.net/projects/asy'
+ Users may also wish to monitor the `Asymptote' forum:
+
+ `http://sourceforge.net/p/asymptote/discussion/409349'
+
+
+File: asymptote.info, Node: UNIX binary distributions, Next: MacOS X binary distributions, Up: Installation
+
+2.1 UNIX binary distributions
+=============================
+
+We release both `tgz' and RPM binary distributions of `Asymptote'. The
+root user can install the `Linux i386' `tgz' distribution of version
+`x.xx' of `Asymptote' with the commands:
+tar -C / -zxf asymptote-x.xx.i386.tgz
+texhash
+ The `texhash' command, which installs LaTeX style files, is optional.
+The executable file will be `/usr/local/bin/asy') and example code will
+be installed by default in `/usr/local/share/doc/asymptote/examples'.
+
+Fedora users can easily install the most recent version of `Asymptote'
+with the command
+yum --enablerepo=rawhide install asymptote
+
+To install the latest version of `Asymptote' on a Debian-based
+distribution (e.g. Ubuntu, Mepis, Linspire) follow the instructions for
+compiling from `UNIX' source (*note Compiling from UNIX source::).
+Alternatively, Debian users can install one of Hubert Chan's prebuilt
+`Asymptote' binaries from
+
+ `http://ftp.debian.org/debian/pool/main/a/asymptote'
+
+
+File: asymptote.info, Node: MacOS X binary distributions, Next: Microsoft Windows, Prev: UNIX binary distributions, Up: Installation
+
+2.2 MacOS X binary distributions
+================================
+
+`MacOS X' users can either compile the `UNIX' source code (*note
+Compiling from UNIX source::) or install the contributed `Asymptote'
+binary available at
+
+`http://www.hmug.org/pub/MacOS_X/X/Applications/Publishing/asymptote/'
+
+Because these preconfigured binary distributions have strict
+architecture and library dependencies that many installations do not
+satisfy, we recommend installing `Asymptote' directly from the official
+source:
+
+ `http://sourceforge.net/project/showfiles.php?group_id=120000'
+
+Note that many `MacOS X' (and FreeBSD) systems lack the GNU `readline'
+library. For full interactive functionality, GNU `readline' version 4.3
+or later must be installed.
+
+
+File: asymptote.info, Node: Microsoft Windows, Next: Configuring, Prev: MacOS X binary distributions, Up: Installation
+
+2.3 Microsoft Windows
+=====================
+
+Users of the `Microsoft Windows' operating system can install the
+self-extracting `Asymptote' executable `asymptote-x.xx-setup.exe',
+where `x.xx' denotes the latest version.
+
+ A working TeX implementation (such as the one available at
+`http://www.miktex.org') will be required to typeset labels. You will
+also need to install `GPL Ghostscript' from
+`http://sourceforge.net/projects/ghostscript/'.
+
+ To view the default `PostScript' output, you can install the program
+`gsview' available from `http://www.cs.wisc.edu/~ghost/gsview/'. A
+better (and free) `PostScript' viewer available at
+`http://psview.sourceforge.net/' (which in particular works properly in
+interactive mode) unfortunately currently requires some manual
+configuration. Specifically, if version `x.xx' of `psview' is extracted
+to the directory `c:\Program Files' one needs to put
+import settings;
+psviewer="c:\Program Files\psview-x.xx\psv.exe";
+ in the optional `Asymptote' configuration file; *note configuration
+file::).
+
+ The `ImageMagick' package from
+
+ `http://www.imagemagick.org/script/binary-releases.php'
+
+is required to support output formats other than EPS, PDF, SVG, and PNG
+(*note convert::). The `Python 2' interpreter from
+`http://www.python.org' is only required if you wish to try out the
+graphical user interface (*note GUI::).
+
+Example code will be installed by default in the `examples'
+subdirectory of the installation directory (by default, `C:\Program
+Files\Asymptote').
+
+
+File: asymptote.info, Node: Configuring, Next: Search paths, Prev: Microsoft Windows, Up: Installation
+
+2.4 Configuring
+===============
+
+In interactive mode, or when given the `-V' option (the default when
+running `Asymptote' on a single file under `MSDOS'), `Asymptote' will
+automatically invoke the `PostScript' viewer `gv' (under `UNIX') or
+`gsview' (under `MSDOS' to display graphical output. These defaults may
+be overridden with the configuration variable `psviewer'. The
+`PostScript' viewer should be capable of automatically redrawing
+whenever the output file is updated. The default `UNIX' `PostScript'
+viewer `gv' supports this (via a `SIGHUP' signal). Version `gv-3.6.3'
+or later (from `http://ftp.gnu.org/gnu/gv/') is required for
+interactive mode to work properly. Users of `ggv' will need to enable
+`Watch file' under `Edit/Postscript Viewer Preferences'. Users of
+`gsview' will need to enable `Options/Auto Redisplay' (however, under
+`MSDOS' it is still necessary to click on the `gsview' window; under
+`UNIX' one must manually redisplay by pressing the `r' key). A better
+(and free) multiplatform alternative to `gsview' is `psview' (*note
+psview::).
+
+ Configuration variables are most easily set as `Asymptote' variables
+in an optional configuration file `config.asy' *note configuration
+file::). Here are the default values of several important configuration
+variables under `UNIX':
+
+
+import settings;
+psviewer="gv";
+pdfviewer="acroread";
+gs="gs";
+
+Under `MSDOS', the (installation-dependent) default values of these
+configuration variables are determined automatically from the
+`Microsoft Windows' registry. Viewer settings (such as `psviewer' and
+`pdfviewer') can be set to the string `cmd' to request the application
+normally associated with the corresponding file type.
+
+ For PDF format output, the `gs' setting specifies the location of
+the `PostScript'-to-PDF processor `Ghostscript', available from
+`http://sourceforge.net/projects/ghostscript/'.
+
+ The setting `pdfviewer' specifies the location of the PDF viewer. On
+`UNIX' systems, to support automatic document reloading in `Adobe
+Reader', we recommend copying the file `reload.js' from the `Asymptote'
+system directory (by default, `/usr/local/share/asymptote' under `UNIX'
+to `~/.adobe/Acrobat/x.x/JavaScripts/', where `x.x' represents the
+appropriate `Adobe Reader' version number. The automatic document
+reload feature must then be explicitly enabled by putting
+import settings;
+pdfreload=true;
+pdfreloadOptions="-tempFile";
+ in the `Asymptote' configuration file. This reload feature is not
+useful under `MSDOS' since the document cannot be updated anyway on
+that operating system until it is first closed by `Adobe Reader'.
+
+ The configuration variable `dir' can be used to adjust the search
+path (*note Search paths::).
+
+ By default, `Asymptote' attempts to center the figure on the page,
+assuming that the paper type is `letter'. The default paper type may be
+changed to `a4' with the configuration variable `papertype'. Alignment
+to other paper sizes can be obtained by setting the configuration
+variables `paperwidth' and `paperheight'.
+
+ The following configuration variables normally do not require
+adjustment:
+texpath
+texcommand
+dvips
+dvisvgm
+libgs
+convert
+display
+animate
+ Warnings (such as "writeoverloaded") may be enabled or disabled with
+the functions
+warn(string s);
+nowarn(string s);
+ or by directly modifying the string array `settings.suppress', which
+lists all disabled warnings.
+
+ Configuration variables may also be set or overwritten with a
+command-line option:
+asy -psviewer=gsview -V venn
+
+ Alternatively, system environment versions of the above configuration
+variables may be set in the conventional way. The corresponding
+environment variable name is obtained by converting the configuration
+variable name to upper case and prepending `ASYMPTOTE_': for example,
+to set the environment variable
+ASYMPTOTE_PSVIEWER="C:\Program Files\Ghostgum\gsview\gsview32.exe";
+ under `Microsoft Windows XP':
+ 1. Click on the `Start' button;
+
+ 2. Right-click on `My Computer';
+
+ 3. Choose `View system information';
+
+ 4. Click the `Advanced' tab;
+
+ 5. Click the `Environment Variables' button.
+
+
+File: asymptote.info, Node: Search paths, Next: Compiling from UNIX source, Prev: Configuring, Up: Installation
+
+2.5 Search paths
+================
+
+In looking for `Asymptote' system files, `asy' will search the
+following paths, in the order listed:
+ 1. The current directory;
+
+ 2. A list of one or more directories specified by the configuration
+ variable `dir' or environment variable `ASYMPTOTE_DIR' (separated
+ by `:' under UNIX and `;' under `MSDOS');
+
+ 3. The directory specified by the environment variable
+ `ASYMPTOTE_HOME'; if this variable is not set, the directory
+ `.asy' in the user's home directory (`%USERPROFILE%\.asy' under
+ `MSDOS') is used;
+
+ 4. The `Asymptote' system directory (by default,
+ `/usr/local/share/asymptote' under `UNIX' and `C:\Program
+ Files\Asymptote' under `MSDOS').
+
+
+File: asymptote.info, Node: Compiling from UNIX source, Next: Editing modes, Prev: Search paths, Up: Installation
+
+2.6 Compiling from UNIX source
+==============================
+
+To compile and install a `UNIX' executable from a source release
+`x.xx', first execute the commands:
+gunzip asymptote-x.xx.src.tgz
+tar -xf asymptote-x.xx.src.tar
+cd asymptote-x.xx
+ By default the system version of the Boehm garbage collector will be
+used; if it is old we recommend first putting
+`http://hboehm.info/gc/gc_source/gc-7.4.0.tar.gz'
+`http://hboehm.info/gc/gc_source/libatomic_ops-7.4.0.tar.gz' in the
+`Asymptote' source directory.
+
+ On `UNIX' platforms (other than `MacOS X'), we recommend using
+version `2.8.1' of the `freeglut' library. To compile `freeglut',
+download
+
+ `http://prdownloads.sourceforge.net/freeglut/freeglut-2.8.1.tar.gz'
+ and type (as the root user):
+gunzip freeglut-2.8.1.tar.gz
+tar -xf freeglut-2.8.1.tar
+cd freeglut-2.8.1
+./configure --prefix=/usr
+make install
+cd ..
+ Then compile `Asymptote' with the commands
+./configure
+make all
+make install
+ Be sure to use GNU `make' (on non-GNU systems this command may be
+called `gmake'). To build the documentation, you may need to install
+the `texinfo-tex' package. If you get errors from a broken `texinfo' or
+`pdftex' installation, simply put
+
+ `http://asymptote.sourceforge.net/asymptote.pdf'
+ in the directory `doc' and repeat the command `make all'.
+
+For a (default) system-wide installation, the last command should be
+done as the root user. To install without root privileges, change the
+`./configure' command to
+./configure --prefix=$HOME/asymptote
+ One can disable use of the Boehm garbage collector by configuring with
+`./configure --disable-gc'. For a list of other configuration options,
+say `./configure --help'. For example, one can tell configure to look
+for header files and libraries in nonstandard locations:
+./configure CFLAGS=-I/opt/usr/include LDFLAGS=-L/opt/usr/lib
+
+ If you are compiling `Asymptote' with `gcc', you will need a
+relatively recent version (e.g. 3.4.4 or later). For full interactive
+functionality, you will need version 4.3 or later of the GNU `readline'
+library. The file `gcc3.3.2curses.patch' in the `patches' directory can
+be used to patch the broken curses.h header file (or a local copy
+thereof in the current directory) on some `AIX' and `IRIX' systems.
+
+ The `FFTW' library is only required if you want `Asymptote' to be
+able to take Fourier transforms of data (say, to compute an audio power
+spectrum). The `GSL' library is only required if you require the
+special functions that it supports.
+
+ If you don't want to install `Asymptote' system wide, just make sure
+the compiled binary `asy' and GUI script `xasy' are in your path and
+set the configuration variable `dir' to point to the directory `base'
+(in the top level directory of the `Asymptote' source code).
+
+
+File: asymptote.info, Node: Editing modes, Next: Subversion, Prev: Compiling from UNIX source, Up: Installation
+
+2.7 Editing modes
+=================
+
+Users of `emacs' can edit `Asymptote' code with the mode `asy-mode',
+after enabling it by putting the following lines in their `.emacs'
+initialization file, replacing `ASYDIR' with the location of the
+`Asymptote' system directory (by default, `/usr/local/share/asymptote'
+or `C:\Program Files\Asymptote' under `MSDOS'):
+(add-to-list 'load-path "ASYDIR")
+(autoload 'asy-mode "asy-mode.el" "Asymptote major mode." t)
+(autoload 'lasy-mode "asy-mode.el" "hybrid Asymptote/Latex major mode." t)
+(autoload 'asy-insinuate-latex "asy-mode.el" "Asymptote insinuate LaTeX." t)
+(add-to-list 'auto-mode-alist '("\\.asy$" . asy-mode))
+
+ Particularly useful key bindings in this mode are `C-c C-c', which
+compiles and displays the current buffer, and the key binding `C-c ?',
+which shows the available function prototypes for the command at the
+cursor. For full functionality you should also install the Apache
+Software Foundation package `two-mode-mode':
+
+ `http://www.dedasys.com/freesoftware/files/two-mode-mode.el'
+ Once installed, you can use the hybrid mode `lasy-mode' to edit a
+LaTeX file containing embedded `Asymptote' code (*note LaTeX usage::).
+This mode can be enabled within `latex-mode' with the key sequence `M-x
+lasy-mode <RET>'. On `UNIX' systems, additional keywords will be
+generated from all `asy' files in the space-separated list of
+directories specified by the environment variable `ASYMPTOTE_SITEDIR'.
+Further documentation of `asy-mode' is available within `emacs' by
+pressing the sequence keys `C-h f asy-mode <RET>'.
+
+ Fans of `vim' can customize `vim' for `Asymptote' with
+
+`cp /usr/local/share/asymptote/asy.vim ~/.vim/syntax/asy.vim'
+
+and add the following to their `~/.vimrc' file:
+augroup filetypedetect
+au BufNewFile,BufRead *.asy setf asy
+augroup END
+filetype plugin on
+
+ If any of these directories or files don't exist, just create them.
+To set `vim' up to run the current asymptote script using `:make' just
+add to `~/.vim/ftplugin/asy.vim':
+setlocal makeprg=asy\ %
+setlocal errorformat=%f:\ %l.%c:\ %m
+
+ Syntax highlighting support for the KDE editor `Kate' can be enabled
+by running `asy-kate.sh' in the `/usr/local/share/asymptote' directory
+and putting the generated `asymptote.xml' file in
+`~/.kde/share/apps/katepart/syntax/'.
+
+
+File: asymptote.info, Node: Subversion, Next: Uninstall, Prev: Editing modes, Up: Installation
+
+2.8 Subversion (SVN)
+====================
+
+The following commands are needed to install the latest development
+version of `Asymptote' using `Subversion':
+svn co http://svn.code.sf.net/p/asymptote/code/trunk/asymptote
+cd asymptote
+./autogen.sh
+./configure
+make all
+make install
+
+To compile without optimization, use the command `make CFLAGS=-g'.
+
+
+File: asymptote.info, Node: Uninstall, Prev: Subversion, Up: Installation
+
+2.9 Uninstall
+=============
+
+To uninstall an `Linux i386' binary distribution, use the commands
+tar -zxvf asymptote-x.xx.i386.tgz | xargs --replace=% rm /%
+texhash
+
+To uninstall all `Asymptote' files installed from a source
+distribution, use the command
+make uninstall
+
+
+File: asymptote.info, Node: Tutorial, Next: Drawing commands, Prev: Installation, Up: Top
+
+3 Tutorial
+**********
+
+3.1 Drawing in batch mode
+=========================
+
+To draw a line from coordinate (0,0) to coordinate (100,100), create a
+text file `test.asy' containing
+
+draw((0,0)--(100,100));
+ Then execute the command
+asy -V test
+ Alternatively, `MSDOS' users can drag and drop `test.asy' onto the
+Desktop `asy' icon (or make `Asymptote' the default application for the
+extension `asy').
+
+This method, known as _batch mode_, outputs a `PostScript' file
+`test.eps'. If you prefer PDF output, use the command line
+asy -V -f pdf test
+ In either case, the `-V' option opens up a viewer window so you can
+immediately view the result:
+
+
+Here, the `--' connector joins the two points `(0,0)' and `(100,100)'
+with a line segment.
+
+3.2 Drawing in interactive mode
+===============================
+
+Another method is _interactive mode_, where `Asymptote' reads
+individual commands as they are entered by the user. To try this out,
+enter `Asymptote''s interactive mode by clicking on the `Asymptote'
+icon or typing the command `asy'. Then type
+draw((0,0)--(100,100));
+ followed by `Enter', to obtain the above image. At this point you can
+type further `draw' commands, which will be added to the displayed
+figure, `erase' to clear the canvas,
+input test;
+ to execute all of the commands contained in the file `test.asy', or
+`quit' to exit interactive mode. You can use the arrow keys in
+interactive mode to edit previous lines. The tab key will
+automatically complete unambiguous words; otherwise, hitting tab again
+will show the possible choices. Further commands specific to
+interactive mode are described in *note Interactive mode::.
+
+3.3 Figure size
+===============
+
+In `Asymptote', coordinates like `(0,0)' and `(100,100)', called
+_pairs_, are expressed in `PostScript' "big points" (1 `bp' = 1/72
+`inch') and the default line width is `0.5bp'. However, it is often
+inconvenient to work directly in `PostScript' coordinates. The next
+example produces identical output to the previous example, by scaling
+the line `(0,0)--(1,1)' to fit a rectangle of width `100.5 bp' and
+height `100.5 bp' (the extra `0.5bp' accounts for the line width):
+size(100.5,100.5);
+draw((0,0)--(1,1));
+
+
+
+One can also specify the size in `pt' (1 `pt' = 1/72.27 `inch'), `cm',
+`mm', or `inches'. Two nonzero size arguments (or a single size
+argument) restrict the size in both directions, preserving the aspect
+ratio. If 0 is given as a size argument, no restriction is made in
+that direction; the overall scaling will be determined by the other
+direction (*note size::):
+
+size(0,100.5);
+draw((0,0)--(2,1),Arrow);
+
+
+
+To connect several points and create a cyclic path, use the `cycle'
+keyword:
+
+size(3cm);
+draw((0,0)--(1,0)--(1,1)--(0,1)--cycle);
+
+
+For convenience, the path `(0,0)--(1,0)--(1,1)--(0,1)--cycle' may be
+replaced with the predefined variable `unitsquare', or equivalently,
+`box((0,0),(1,1))'.
+
+ To make the user coordinates represent multiples of exactly `1cm':
+unitsize(1cm);
+draw(unitsquare);
+
+3.4 Labels
+==========
+
+Adding labels is easy in `Asymptote'; one specifies the label as a
+double-quoted `LaTeX' string, a coordinate, and an optional alignment
+direction:
+
+size(3cm);
+draw(unitsquare);
+label("$A$",(0,0),SW);
+label("$B$",(1,0),SE);
+label("$C$",(1,1),NE);
+label("$D$",(0,1),NW);
+
+
+
+`Asymptote' uses the standard compass directions `E=(1,0)', `N=(0,1)',
+`NE=unit(N+E)', and `ENE=unit(E+NE)', etc., which along with the
+directions `up', `down', `right', and `left' are defined as pairs in
+the `Asymptote' base module `plain' (a user who has a local variable
+named `E' may access the compass direction `E' by prefixing it with the
+name of the module where it is defined: `plain.E').
+
+3.5 Paths
+=========
+
+This example draws a path that approximates a quarter circle,
+terminated with an arrowhead:
+
+size(100,0);
+draw((1,0){up}..{left}(0,1),Arrow);
+
+
+Here the directions `up' and `left' in braces specify the incoming and
+outgoing directions at the points `(1,0)' and `(0,1)', respectively.
+
+ In general, a path is specified as a list of points (or other paths)
+interconnected with `--', which denotes a straight line segment, or
+`..', which denotes a cubic spline (*note Bezier curves::). Specifying
+a final `..cycle' creates a cyclic path that connects smoothly back to
+the initial node, as in this approximation (accurate to within 0.06%)
+of a unit circle:
+path unitcircle=E..N..W..S..cycle;
+
+An `Asymptote' path, being connected, is equivalent to a `Postscript
+subpath'. The `^^' binary operator, which requests that the pen be
+moved (without drawing or affecting endpoint curvatures) from the final
+point of the left-hand path to the initial point of the right-hand
+path, may be used to group several `Asymptote' paths into a `path[]'
+array (equivalent to a `PostScript' path):
+
+size(0,100);
+path unitcircle=E..N..W..S..cycle;
+path g=scale(2)*unitcircle;
+filldraw(unitcircle^^g,evenodd+yellow,black);
+
+
+
+The `PostScript' even-odd fill rule here specifies that only the region
+bounded between the two unit circles is filled (*note fillrule::). In
+this example, the same effect can be achieved by using the default zero
+winding number fill rule, if one is careful to alternate the
+orientation of the paths:
+filldraw(unitcircle^^reverse(g),yellow,black);
+
+ The `^^' operator is used by the `box(triple, triple)' function in
+the module `three.asy' to construct the edges of a cube `unitbox'
+without retracing steps (*note three::):
+
+import three;
+
+currentprojection=orthographic(5,4,2,center=true);
+
+size(5cm);
+size3(3cm,5cm,8cm);
+
+draw(unitbox);
+
+dot(unitbox,red);
+
+label("$O$",(0,0,0),NW);
+label("(1,0,0)",(1,0,0),S);
+label("(0,1,0)",(0,1,0),E);
+label("(0,0,1)",(0,0,1),Z);
+
+
+
+See section *note graph:: (or the online `Asymptote' gallery and
+external links posted at `http://asymptote.sourceforge.net') for
+further examples, including two-dimensional and interactive
+three-dimensional scientific graphs. Additional examples have been
+posted by Philippe Ivaldi at `http://www.piprime.fr/asymptote'.
+Excellent user-written `Asymptote' tutorials are also available:
+
+ `http://www.artofproblemsolving.com/Wiki/index.php/Asymptote:_Basics'
+
+`http://math.uchicago.edu/~cstaats/Charles_Staats_III/Notes_and_papers_files/asymptote_tutorial.pdf'
+
+
+File: asymptote.info, Node: Drawing commands, Next: Bezier curves, Prev: Tutorial, Up: Top
+
+4 Drawing commands
+******************
+
+All of `Asymptote''s graphical capabilities are based on four primitive
+commands. The three `PostScript' drawing commands `draw', `fill', and
+`clip' add objects to a picture in the order in which they are
+executed, with the most recently drawn object appearing on top. The
+labeling command `label' can be used to add text labels and external
+EPS images, which will appear on top of the `PostScript' objects (since
+this is normally what one wants), but again in the relative order in
+which they were executed. After drawing objects on a picture, the
+picture can be output with the `shipout' function (*note shipout::).
+
+ If you wish to draw `PostScript' objects on top of labels (or
+verbatim `tex' commands; *note tex::), the `layer' command may be used
+to start a new `PostScript/LaTeX' layer:
+void layer(picture pic=currentpicture);
+
+ The `layer' function gives one full control over the order in which
+objects are drawn. Layers are drawn sequentially, with the most recent
+layer appearing on top. Within each layer, labels, images, and verbatim
+`tex' commands are always drawn after the `PostScript' objects in that
+layer.
+
+ While some of these drawing commands take many options, they all
+have sensible default values (for example, the picture argument
+defaults to currentpicture).
+
+* Menu:
+
+* draw:: Draw a path on a picture or frame
+* fill:: Fill a cyclic path on a picture or frame
+* clip:: Clip a picture or frame to a cyclic path
+* label:: Label a point on a picture
+
+
+File: asymptote.info, Node: draw, Next: fill, Up: Drawing commands
+
+4.1 draw
+========
+
+void draw(picture pic=currentpicture, Label L="", path g,
+ align align=NoAlign, pen p=currentpen,
+ arrowbar arrow=None, arrowbar bar=None, margin margin=NoMargin,
+ Label legend="", marker marker=nomarker);
+
+Draw the path `g' on the picture `pic' using pen `p' for drawing, with
+optional drawing attributes (Label `L', explicit label alignment
+`align', arrows and bars `arrow' and `bar', margins `margin', legend,
+and markers `marker'). Only one parameter, the path, is required. For
+convenience, the arguments `arrow' and `bar' may be specified in either
+order. The argument `legend' is a Label to use in constructing an
+optional legend entry.
+
+ Bars are useful for indicating dimensions. The possible values of
+`bar' are `None', `BeginBar', `EndBar' (or equivalently `Bar'), and
+`Bars' (which draws a bar at both ends of the path). Each of these bar
+specifiers (except for `None') will accept an optional real argument
+that denotes the length of the bar in `PostScript' coordinates. The
+default bar length is `barsize(pen)'.
+
+ The possible values of `arrow' are `None', `Blank' (which draws no
+arrows or path), `BeginArrow', `MidArrow', `EndArrow' (or equivalently
+`Arrow'), and `Arrows' (which draws an arrow at both ends of the path).
+All of the arrow specifiers except for `None' and `Blank' may be given
+the optional arguments arrowhead `arrowhead' (one of the predefined
+arrowhead styles `DefaultHead', `SimpleHead', `HookHead', `TeXHead'),
+real `size' (arrowhead size in `PostScript' coordinates), real `angle'
+(arrowhead angle in degrees), filltype `filltype' (one of `FillDraw',
+`Fill', `NoFill', `UnFill', `Draw') and (except for `MidArrow' and
+`Arrows') a real `position' (in the sense of `point(path p, real t)')
+along the path where the tip of the arrow should be placed. The default
+arrowhead size when drawn with a pen `p' is `arrowsize(p)'. There are
+also arrow versions with slightly modified default values of `size' and
+`angle' suitable for curved arrows: `BeginArcArrow', `EndArcArrow' (or
+equivalently `ArcArrow'), `MidArcArrow', and `ArcArrows'.
+
+ Margins can be used to shrink the visible portion of a path by
+`labelmargin(p)' to avoid overlap with other drawn objects. Typical
+values of `margin' are `NoMargin', `BeginMargin', `EndMargin' (or
+equivalently `Margin'), and `Margins' (which leaves a margin at both
+ends of the path). One may use `Margin(real begin, real end)' to
+specify the size of the beginning and ending margin, respectively, in
+multiples of the units `labelmargin(p)' used for aligning labels.
+Alternatively, `BeginPenMargin', `EndPenMargin' (or equivalently
+`PenMargin'), `PenMargins', `PenMargin(real begin, real end)' specify a
+margin in units of the pen line width, taking account of the pen line
+width when drawing the path or arrow. For example, use `DotMargin', an
+abbreviation for `PenMargin(-0.5*dotfactor,0.5*dotfactor)', to draw
+from the usual beginning point just up to the boundary of an end dot of
+width `dotfactor*linewidth(p)'. The qualifiers `BeginDotMargin',
+`EndDotMargin', and `DotMargins' work similarly. The qualifier
+`TrueMargin(real begin, real end)' allows one to specify a margin
+directly in `PostScript' units, independent of the pen line width.
+
+ The use of arrows, bars, and margins is illustrated by the examples
+`Pythagoras.asy', `sqrtx01.asy', and `triads.asy'.
+
+ The legend for a picture `pic' can be fit and aligned to a frame
+with the routine:
+frame legend(picture pic=currentpicture, int perline=1,
+ real xmargin=legendmargin, real ymargin=xmargin,
+ real linelength=legendlinelength,
+ real hskip=legendhskip, real vskip=legendvskip,
+ real maxwidth=0, real maxheight=0,
+ bool hstretch=false, bool vstretch=false, pen p=currentpen);
+ Here `xmargin' and `ymargin' specify the surrounding x and y margins,
+`perline' specifies the number of entries per line (default 1; 0 means
+choose this number automatically), `linelength' specifies the length of
+the path lines, `hskip' and `vskip' specify the line skip (as a
+multiple of the legend entry size), `maxwidth' and `maxheight' specify
+optional upper limits on the width and height of the resulting legend
+(0 means unlimited), `hstretch' and `vstretch' allow the legend to
+stretch horizontally or vertically, and `p' specifies the pen used to
+draw the bounding box. The legend frame can then be added and aligned
+about a point on a picture `dest' using `add' or `attach' (*note add
+about::).
+
+ To draw a dot, simply draw a path containing a single point. The
+`dot' command defined in the module `plain' draws a dot having a
+diameter equal to an explicit pen line width or the default line width
+magnified by `dotfactor' (6 by default), using the specified filltype
+(*note filltype::):
+void dot(picture pic=currentpicture, pair z, pen p=currentpen,
+ filltype filltype=Fill);
+void dot(picture pic=currentpicture, Label L, pair z, align align=NoAlign,
+ string format=defaultformat, pen p=currentpen, filltype filltype=Fill);
+void dot(picture pic=currentpicture, Label[] L=new Label[], pair[] z,
+ align align=NoAlign, string format=defaultformat, pen p=currentpen,
+ filltype filltype=Fill)
+void dot(picture pic=currentpicture, Label L, pen p=currentpen,
+ filltype filltype=Fill);
+
+ If the variable `Label' is given as the `Label' argument to the
+second routine, the `format' argument will be used to format a string
+based on the dot location (here `defaultformat' is `"$%.4g$"'). The
+third routine draws a dot at every point of a pair array `z'. One can
+also draw a dot at every node of a path:
+void dot(picture pic=currentpicture, Label[] L=new Label[],
+ path g, align align=RightSide, string format=defaultformat,
+ pen p=currentpen, filltype filltype=Fill);
+ See *note pathmarkers:: and *note markers:: for more general methods
+for marking path nodes.
+
+ To draw a fixed-sized object (in `PostScript' coordinates) about the
+user coordinate `origin', use the routine
+void draw(pair origin, picture pic=currentpicture, Label L="", path g,
+ align align=NoAlign, pen p=currentpen, arrowbar arrow=None,
+ arrowbar bar=None, margin margin=NoMargin, Label legend="",
+ marker marker=nomarker);
+
+
+File: asymptote.info, Node: fill, Next: clip, Prev: draw, Up: Drawing commands
+
+4.2 fill
+========
+
+void fill(picture pic=currentpicture, path g, pen p=currentpen);
+
+Fill the interior region bounded by the cyclic path `g' on the picture
+`pic', using the pen `p'.
+
+ There is also a convenient `filldraw' command, which fills the path
+and then draws in the boundary. One can specify separate pens for each
+operation:
+void filldraw(picture pic=currentpicture, path g, pen fillpen=currentpen,
+ pen drawpen=currentpen);
+
+ This fixed-size version of `fill' allows one to fill an object
+described in `PostScript' coordinates about the user coordinate
+`origin':
+void fill(pair origin, picture pic=currentpicture, path g, pen p=currentpen);
+
+This is just a convenient abbreviation for the commands:
+picture opic;
+fill(opic,g,p);
+add(pic,opic,origin);
+
+ The routine
+void filloutside(picture pic=currentpicture, path g, pen p=currentpen);
+ fills the region exterior to the path `g', out to the current boundary
+of picture `pic'.
+
+ Lattice gradient shading varying smoothly over a two-dimensional
+array of pens `p', using fill rule `fillrule', can be produced with
+void latticeshade(picture pic=currentpicture, path g, bool stroke=false,
+ pen fillrule=currentpen, pen[][] p)
+ If `stroke=true', the region filled is the same as the region that
+would be drawn by `draw(pic,g,fillrule+zerowinding)'; in this case the
+path `g' need not be cyclic. The pens in `p' must belong to the same
+color space. One can use the functions `rgb(pen)' or `cmyk(pen)' to
+promote pens to a higher color space, as illustrated in the example file
+`latticeshading.asy'.
+
+ Axial gradient shading varying smoothly from `pena' to `penb' in the
+direction of the line segment `a--b' can be achieved with
+void axialshade(picture pic=currentpicture, path g, bool stroke=false,
+ pen pena, pair a, bool extenda=true,
+ pen penb, pair b, bool extendb=true);
+ The boolean parameters `extenda' and `extendb' indicate whether the
+shading should extend beyond the axis endpoints `a' and `b'.
+
+ Radial gradient shading varying smoothly from `pena' on the circle
+with center `a' and radius `ra' to `penb' on the circle with center `b'
+and radius `rb' is similar:
+void radialshade(picture pic=currentpicture, path g, bool stroke=false,
+ pen pena, pair a, real ra, bool extenda=true,
+ pen penb, pair b, real rb, bool extendb=true);
+ The boolean parameters `extenda' and `extendb' indicate whether the
+shading should extend beyond the radii `a' and `b'. Illustrations of
+radial shading are provided in the example files `shade.asy',
+`ring.asy', and `shadestroke.asy'.
+
+ Gouraud shading using fill rule `fillrule' and the vertex colors in
+the pen array `p' on a triangular lattice defined by the vertices `z'
+and edge flags `edges' is implemented with
+void gouraudshade(picture pic=currentpicture, path g, bool stroke=false,
+ pen fillrule=currentpen, pen[] p, pair[] z,
+ int[] edges);
+void gouraudshade(picture pic=currentpicture, path g, bool stroke=false,
+ pen fillrule=currentpen, pen[] p, int[] edges);
+ In the second form, the elements of `z' are taken to be successive
+nodes of path `g'. The pens in `p' must belong to the same color space.
+Illustrations of Gouraud shading are provided in the example file
+`Gouraud.asy' and in the solid geometry module `solids.asy'. The edge
+flags used in Gouraud shading are documented here:
+
+ `http://partners.adobe.com/public/developer/en/ps/sdk/TN5600.SmoothShading.pdf'.
+
+ Tensor product shading using fill rule `fillrule' on patches bounded
+by the n cyclic paths of length 4 in path array `b', using the vertex
+colors specified in the n \times 4 pen array `p' and internal control
+points in the n \times 4 array `z', is implemented with
+void tensorshade(picture pic=currentpicture, path[] g, bool stroke=false,
+ pen fillrule=currentpen, pen[][] p, path[] b=g,
+ pair[][] z=new pair[][]);
+ If the array `z' is empty, Coons shading, in which the color control
+points are calculated automatically, is used. The pens in `p' must
+belong to the same color space. A simpler interface for the case of a
+single patch (n=1) is also available:
+void tensorshade(picture pic=currentpicture, path g, bool stroke=false,
+ pen fillrule=currentpen, pen[] p, path b=g,
+ pair[] z=new pair[]);
+ One can also smoothly shade the regions between consecutive paths of a
+sequence using a given array of pens:
+void draw(picture pic=currentpicture, pen fillrule=currentpen, path[] g,
+ pen[] p);
+ Illustrations of tensor product and Coons shading are provided in the
+example files `tensor.asy', `Coons.asy', `BezierSurface.asy', and
+`rainbow.asy'.
+
+ More general shading possibilities are available with the `pdflatex',
+`context', and `pdftex' TeX engines: the routine
+void functionshade(picture pic=currentpicture, path[] g, bool stroke=false,
+ pen fillrule=currentpen, string shader);
+ shades on picture `pic' the interior of path `g' according to fill
+rule `fillrule' using the `PostScript' calculator routine specified by
+the string `shader'; this routine takes 2 arguments, each in [0,1], and
+returns `colors(fillrule).length' color components. Function shading
+is illustrated in the example `functionshading.asy'.
+
+ The following routine uses `evenodd' clipping together with the `^^'
+operator to unfill a region:
+
+void unfill(picture pic=currentpicture, path g);
+
+
+File: asymptote.info, Node: clip, Next: label, Prev: fill, Up: Drawing commands
+
+4.3 clip
+========
+
+void clip(picture pic=currentpicture, path g, stroke=false,
+ pen fillrule=currentpen);
+
+Clip the current contents of picture `pic' to the region bounded by the
+path `g', using fill rule `fillrule' (*note fillrule::). If
+`stroke=true', the clipped portion is the same as the region that would
+be drawn with `draw(pic,g,fillrule+zerowinding)'; in this case the path
+`g' need not be cyclic. For an illustration of picture clipping, see
+the first example in *note LaTeX usage::.
+
+
+File: asymptote.info, Node: label, Prev: clip, Up: Drawing commands
+
+4.4 label
+=========
+
+void label(picture pic=currentpicture, Label L, pair position,
+ align align=NoAlign, pen p=currentpen, filltype filltype=NoFill)
+
+Draw Label `L' on picture `pic' using pen `p'. If `align' is `NoAlign',
+the label will be centered at user coordinate `position'; otherwise it
+will be aligned in the direction of `align' and displaced from
+`position' by the `PostScript' offset `align*labelmargin(p)'. The
+constant `Align' can be used to align the bottom-left corner of the
+label at `position'. The Label `L' can either be a string or the
+structure obtained by calling one of the functions
+Label Label(string s="", pair position, align align=NoAlign,
+ pen p=nullpen, embed embed=Rotate, filltype filltype=NoFill);
+Label Label(string s="", align align=NoAlign,
+ pen p=nullpen, embed embed=Rotate, filltype filltype=NoFill);
+Label Label(Label L, pair position, align align=NoAlign,
+ pen p=nullpen, embed embed=L.embed, filltype filltype=NoFill);
+Label Label(Label L, align align=NoAlign,
+ pen p=nullpen, embed embed=L.embed, filltype filltype=NoFill);
+ The text of a Label can be scaled, slanted, rotated, or shifted by
+multiplying it on the left by an affine transform (*note Transforms::).
+For example, `rotate(45)*xscale(2)*L' first scales `L' in the x
+direction and then rotates it counterclockwise by 45 degrees. The final
+position of a Label can also be shifted by a `PostScript' coordinate
+translation: `shift(10,0)*L'. An explicit pen specified within the
+Label overrides other pen arguments. The `embed' argument determines
+how the Label should transform with the embedding picture:
+`Shift'
+ only shift with embedding picture;
+
+`Rotate'
+ only shift and rotate with embedding picture (default);
+
+`Rotate(pair z)'
+ rotate with (picture-transformed) vector `z'.
+
+`Slant'
+ only shift, rotate, slant, and reflect with embedding picture;
+
+`Scale'
+ shift, rotate, slant, reflect, and scale with embedding picture.
+
+
+ To add a label to a path, use
+void label(picture pic=currentpicture, Label L, path g, align align=NoAlign,
+ pen p=currentpen, filltype filltype=NoFill);
+ By default the label will be positioned at the midpoint of the path.
+An alternative label position (in the sense of `point(path p, real t)')
+may be specified as a real value for `position' in constructing the
+Label. The position `Relative(real)' specifies a location relative to
+the total arclength of the path. These convenient abbreviations are
+predefined:
+position BeginPoint=Relative(0);
+position MidPoint=Relative(0.5);
+position EndPoint=Relative(1);
+
+ Path labels are aligned in the direction `align', which may be
+specified as an absolute compass direction (pair) or a direction
+`Relative(pair)' measured relative to a north axis in the local
+direction of the path. For convenience `LeftSide', `Center', and
+`RightSide' are defined as `Relative(W)', `Relative((0,0))', and
+`Relative(E)', respectively. Multiplying `LeftSide', `Center',
+`RightSide' on the left by a real scaling factor will move the label
+further away from or closer to the path.
+
+ A label with a fixed-size arrow of length `arrowlength' pointing to
+`b' from direction `dir' can be produced with the routine
+void arrow(picture pic=currentpicture, Label L="", pair b, pair dir,
+ real length=arrowlength, align align=NoAlign,
+ pen p=currentpen, arrowbar arrow=Arrow, margin margin=EndMargin);
+ If no alignment is specified (either in the Label or as an explicit
+argument), the optional Label will be aligned in the direction `dir',
+using margin `margin'.
+
+ The function `string graphic(string name, string options="")'
+returns a string that can be used to include an encapsulated
+`PostScript' (EPS) file. Here, `name' is the name of the file to
+include and `options' is a string containing a comma-separated list of
+optional bounding box (`bb=llx lly urx ury'), width (`width=value'),
+height (`height=value'), rotation (`angle=value'), scaling
+(`scale=factor'), clipping (`clip=bool'), and draft mode (`draft=bool')
+parameters. The `layer()' function can be used to force future objects
+to be drawn on top of the included image:
+label(graphic("file.eps","width=1cm"),(0,0),NE);
+layer();
+
+ The `string baseline(string s, string template="\strut")' function
+can be used to enlarge the bounding box of labels to match a given
+template, so that their baselines will be typeset on a horizontal line.
+See `Pythagoras.asy' for an example.
+
+ One can prevent labels from overwriting one another with the
+`overwrite' pen attribute (*note overwrite::).
+
+ The structure `object' defined in `plain_Label.asy' allows Labels
+and frames to be treated in a uniform manner. A group of objects may
+be packed together into single frame with the routine
+frame pack(pair align=2S ... object inset[]);
+ To draw or fill a box (or ellipse or other path) around a Label and
+return the bounding object, use one of the routines
+object draw(picture pic=currentpicture, Label L, envelope e,
+ real xmargin=0, real ymargin=xmargin, pen p=currentpen,
+ filltype filltype=NoFill, bool above=true);
+object draw(picture pic=currentpicture, Label L, envelope e, pair position,
+ real xmargin=0, real ymargin=xmargin, pen p=currentpen,
+ filltype filltype=NoFill, bool above=true);
+ Here `envelope' is a boundary-drawing routine such as `box',
+`roundbox', or `ellipse' defined in `plain_boxes.asy' (*note
+envelope::).
+
+ The function `path[] texpath(Label L)' returns the path array that
+TeX would fill to draw the Label `L'.
+
+ The `string minipage(string s, width=100pt)' function can be used to
+format string `s' into a paragraph of width `width'. This example uses
+`minipage', `clip', and `graphic' to produce a CD label:
+
+
+size(11.7cm,11.7cm);
+asy(nativeformat(),"logo");
+fill(unitcircle^^(scale(2/11.7)*unitcircle),
+ evenodd+rgb(124/255,205/255,124/255));
+label(scale(1.1)*minipage(
+"\centering\scriptsize \textbf{\LARGE {\tt Asymptote}\\
+\smallskip
+\small The Vector Graphics Language}\\
+\smallskip
+\textsc{Andy Hammerlindl, John Bowman, and Tom Prince}
+http://asymptote.sourceforge.net\\
+",8cm),(0,0.6));
+label(graphic("logo."+nativeformat(),"height=7cm"),(0,-0.22));
+clip(unitcircle^^(scale(2/11.7)*unitcircle),evenodd);
+
+
+File: asymptote.info, Node: Bezier curves, Next: Programming, Prev: Drawing commands, Up: Top
+
+5 Bezier curves
+***************
+
+Each interior node of a cubic spline may be given a direction prefix or
+suffix `{dir}': the direction of the pair `dir' specifies the direction
+of the incoming or outgoing tangent, respectively, to the curve at that
+node. Exterior nodes may be given direction specifiers only on their
+interior side.
+
+ A cubic spline between the node z_0, with postcontrol point c_0, and
+the node z_1, with precontrol point c_1, is computed as the Bezier curve
+
+
+
+As illustrated in the diagram below, the third-order midpoint (m_5)
+constructed from two endpoints z_0 and z_1 and two control points c_0
+and c_1, is the point corresponding to t=1/2 on the Bezier curve formed
+by the quadruple (z_0, c_0, c_1, z_1). This allows one to recursively
+construct the desired curve, by using the newly extracted third-order
+midpoint as an endpoint and the respective second- and first-order
+midpoints as control points:
+
+
+
+Here m_0, m_1 and m_2 are the first-order midpoints, m_3 and m_4 are
+the second-order midpoints, and m_5 is the third-order midpoint. The
+curve is then constructed by recursively applying the algorithm to
+(z_0, m_0, m_3, m_5) and (m_5, m_4, m_2, z_1).
+
+ In fact, an analogous property holds for points located at any
+fraction t in [0,1] of each segment, not just for midpoints (t=1/2).
+
+ The Bezier curve constructed in this manner has the following
+properties:
+ * It is entirely contained in the convex hull of the given four
+ points.
+
+ * It starts heading from the first endpoint to the first control
+ point and finishes heading from the second control point to the
+ second endpoint.
+
+
+ The user can specify explicit control points between two nodes like
+this:
+draw((0,0)..controls (0,100) and (100,100)..(100,0));
+
+ However, it is usually more convenient to just use the `..'
+operator, which tells `Asymptote' to choose its own control points
+using the algorithms described in Donald Knuth's monograph, The
+MetaFontbook, Chapter 14. The user can still customize the guide (or
+path) by specifying direction, tension, and curl values.
+
+ The higher the tension, the straighter the curve is, and the more it
+approximates a straight line. One can change the spline tension from
+its default value of 1 to any real value greater than or equal to 0.75
+(cf. John D. Hobby, Discrete and Computational Geometry 1, 1986):
+draw((100,0)..tension 2 ..(100,100)..(0,100));
+draw((100,0)..tension 3 and 2 ..(100,100)..(0,100));
+draw((100,0)..tension atleast 2 ..(100,100)..(0,100));
+
+ In these examples there is a space between `2' and `..'. This is
+needed as `2.' is interpreted as a numerical constant.
+
+ The curl parameter specifies the curvature at the endpoints of a path
+(0 means straight; the default value of 1 means approximately circular):
+draw((100,0){curl 0}..(100,100)..{curl 0}(0,100));
+
+ The `MetaPost ...' path connector, which requests, when possible, an
+inflection-free curve confined to a triangle defined by the endpoints
+and directions, is implemented in `Asymptote' as the convenient
+abbreviation `::' for `..tension atleast 1 ..' (the ellipsis `...' is
+used in `Asymptote' to indicate a variable number of arguments; *note
+Rest arguments::). For example, compare
+
+draw((0,0){up}..(100,25){right}..(200,0){down});
+
+
+with
+
+draw((0,0){up}::(100,25){right}::(200,0){down});
+
+
+
+The `---' connector is an abbreviation for `..tension atleast
+infinity..' and the `&' connector concatenates two paths, after first
+stripping off the last node of the first path (which normally should
+coincide with the first node of the second path).
+
+
+File: asymptote.info, Node: Programming, Next: LaTeX usage, Prev: Bezier curves, Up: Top
+
+6 Programming
+*************
+
+Here is a short introductory example to the `Asymptote' programming
+language that highlights the similarity of its control structures with
+those of C, C++, and Java:
+// This is a comment.
+
+// Declaration: Declare x to be a real variable;
+real x;
+
+// Assignment: Assign the real variable x the value 1.
+x=1.0;
+
+// Conditional: Test if x equals 1 or not.
+if(x == 1.0) {
+ write("x equals 1.0");
+} else {
+ write("x is not equal to 1.0");
+}
+
+// Loop: iterate 10 times
+for(int i=0; i < 10; ++i) {
+ write(i);
+}
+
+ `Asymptote' supports `while', `do', `break', and `continue'
+statements just as in C/C++. It also supports the Java-style shorthand
+for iterating over all elements of an array:
+
+// Iterate over an array
+int[] array={1,1,2,3,5};
+for(int k : array) {
+ write(k);
+}
+ In addition, it supports many features beyond the ones found in those
+languages.
+
+* Menu:
+
+* Data types:: void, bool, int, real, pair, triple, string
+* Paths and guides:: Bezier curves
+* Pens:: Colors, line types, line widths, font sizes
+* Transforms:: Affine transforms
+* Frames and pictures:: Canvases for immediate and deferred drawing
+* Files:: Reading and writing your data
+* Variable initializers:: Initialize your variables
+* Structures:: Organize your data
+* Operators:: Arithmetic and logical operators
+* Implicit scaling:: Avoiding those ugly *s
+* Functions:: Traditional and high-order functions
+* Arrays:: Dynamic vectors
+* Casts:: Implicit and explicit casts
+* Import:: Importing external `Asymptote' modules
+* Static:: Where to allocate your variable?
+
+
+File: asymptote.info, Node: Data types, Next: Paths and guides, Up: Programming
+
+6.1 Data types
+==============
+
+`Asymptote' supports the following data types (in addition to
+user-defined types):
+
+`void'
+ The void type is used only by functions that take or return no
+ arguments.
+
+`bool'
+ a boolean type that can only take on the values `true' or `false'.
+ For example: bool b=true;
+
+ defines a boolean variable `b' and initializes it to the value
+ `true'. If no initializer is given: bool b;
+
+ the value `false' is assumed.
+
+`bool3'
+ an extended boolean type that can take on the values `true',
+ `default', or `false'. A bool3 type can be cast to or from a bool.
+ The default initializer for bool3 is `default'.
+
+`int'
+ an integer type; if no initializer is given, the implicit value `0'
+ is assumed. The minimum allowed value of an integer is `intMin'
+ and the maximum value is `intMax'.
+
+`real'
+ a real number; this should be set to the highest-precision native
+ floating-point type on the architecture. The implicit initializer
+ for reals is `0.0'. Real numbers have precision `realEpsilon',
+ with `realDigits' significant digits. The smallest positive real
+ number is `realMin' and the largest positive real number is
+ `realMax'. The variable `inf' and function `bool isnan(real x)'
+ are useful when floating-point exceptions are masked with the
+ `-mask' command-line option (the default in interactive mode).
+
+`pair'
+ complex number, that is, an ordered pair of real components
+ `(x,y)'. The real and imaginary parts of a pair `z' can read as
+ `z.x' and `z.y'. We say that `x' and `y' are virtual members of
+ the data element pair; they cannot be directly modified, however.
+ The implicit initializer for pairs is `(0.0,0.0)'.
+
+ There are a number of ways to take the complex conjugate of a pair:
+ pair z=(3,4);
+ z=(z.x,-z.y);
+ z=z.x-I*z.y;
+ z=conj(z);
+
+ Here `I' is the pair `(0,1)'. A number of built-in functions are
+ defined for pairs:
+
+ `pair conj(pair z)'
+ returns the conjugate of `z';
+
+ `real length(pair z)'
+ returns the complex modulus `|z|' of its argument `z'. For
+ example,
+ pair z=(3,4);
+ length(z);
+ returns the result 5. A synonym for `length(pair)' is
+ `abs(pair)';
+
+ `real angle(pair z, bool warn=true)'
+ returns the angle of `z' in radians in the interval
+ [-`pi',`pi'] or `0' if `warn' is `false' and `z=(0,0)'
+ (rather than producing an error);
+
+ `real degrees(pair z, bool warn=true)'
+ returns the angle of `z' in degrees in the interval [0,360)
+ or `0' if `warn' is `false' and `z=(0,0)' (rather than
+ producing an error);
+
+ `pair unit(pair z)'
+ returns a unit vector in the direction of the pair `z';
+
+ `pair expi(real angle)'
+ returns a unit vector in the direction `angle' measured in
+ radians;
+
+ `pair dir(real degrees)'
+ returns a unit vector in the direction `degrees' measured in
+ degrees;
+
+ `real xpart(pair z)'
+ returns `z.x';
+
+ `real ypart(pair z)'
+ returns `z.y';
+
+ `pair realmult(pair z, pair w)'
+ returns the element-by-element product `(z.x*w.x,z.y*w.y)';
+
+ `real dot(explicit pair z, explicit pair w)'
+ returns the dot product `z.x*w.x+z.y*w.y';
+
+ `pair minbound(pair z, pair w)'
+ returns `(min(z.x,w.x),min(z.y,w.y))';
+
+ `pair maxbound(pair z, pair w)'
+ returns `(max(z.x,w.x),max(z.y,w.y))'.
+
+
+`triple'
+ an ordered triple of real components `(x,y,z)' used for
+ three-dimensional drawings. The respective components of a triple
+ `v' can read as `v.x', `v.y', and `v.z'. The implicit initializer
+ for triples is `(0.0,0.0,0.0)'.
+
+ Here are the built-in functions for triples:
+ `real length(triple v)'
+ returns the length `|v|' of the vector `v'. A synonym for
+ `length(triple)' is `abs(triple)';
+
+ `real polar(triple v, bool warn=true)'
+ returns the colatitude of `v' measured from the z axis in
+ radians or `0' if `warn' is `false' and `v=O' (rather than
+ producing an error);
+
+ `real azimuth(triple v, bool warn=true)'
+ returns the longitude of `v' measured from the x axis in
+ radians or `0' if `warn' is `false' and `v.x=v.y=0' (rather
+ than producing an error);
+
+ `real colatitude(triple v, bool warn=true)'
+ returns the colatitude of `v' measured from the z axis in
+ degrees or `0' if `warn' is `false' and `v=O' (rather than
+ producing an error);
+
+ `real latitude(triple v, bool warn=true)'
+ returns the latitude of `v' measured from the xy plane in
+ degrees or `0' if `warn' is `false' and `v=O' (rather than
+ producing an error);
+
+ `real longitude(triple v, bool warn=true)'
+ returns the longitude of `v' measured from the x axis in
+ degrees or `0' if `warn' is `false' and `v.x=v.y=0' (rather
+ than producing an error);
+
+ `triple unit(triple v)'
+ returns a unit triple in the direction of the triple `v';
+
+ `triple expi(real polar, real azimuth)'
+ returns a unit triple in the direction `(polar,azimuth)'
+ measured in radians;
+
+ `triple dir(real colatitude, real longitude)'
+ returns a unit triple in the direction
+ `(colatitude,longitude)' measured in degrees;
+
+ `real xpart(triple v)'
+ returns `v.x';
+
+ `real ypart(triple v)'
+ returns `v.y';
+
+ `real zpart(triple v)'
+ returns `v.z';
+
+ `real dot(triple u, triple v)'
+ returns the dot product `u.x*v.x+u.y*v.y+u.z*v.z';
+
+ `triple cross(triple u, triple v)'
+ returns the cross product
+
+ `(u.y*v.z-u.z*v.y,u.z*v.x-u.x*v.z,u.x*v.y-v.x*u.y)';
+
+ `triple minbound(triple u, triple v)'
+ returns `(min(u.x,v.x),min(u.y,v.y),min(u.z,v.z))';
+
+ `triple maxbound(triple u, triple v)'
+ returns `(max(u.x,v.x),max(u.y,v.y),max(u.z,v.z)').
+
+
+`string'
+ a character string, implemented using the STL `string' class.
+
+ Strings delimited by double quotes (`"') are subject to the
+ following mappings to allow the use of double quotes in TeX (e.g.
+ for using the `babel' package, *note babel::):
+
+ * \" maps to "
+
+ * \\ maps to \\
+
+ Strings delimited by single quotes (`'') have the same mappings as
+ character strings in ANSI `C':
+
+ * \' maps to '
+
+ * \" maps to "
+
+ * \? maps to ?
+
+ * \\ maps to backslash
+
+ * \a maps to alert
+
+ * \b maps to backspace
+
+ * \f maps to form feed
+
+ * \n maps to newline
+
+ * \r maps to carriage return
+
+ * \t maps to tab
+
+ * \v maps to vertical tab
+
+ * \0-\377 map to corresponding octal byte
+
+ * \x0-\xFF map to corresponding hexadecimal byte
+
+ The implicit initializer for strings is the empty string `""'.
+ Strings may be concatenated with the `+' operator. In the following
+ string functions, position `0' denotes the start of the string:
+ `int length(string s)'
+ returns the length of the string `s';
+
+ `int find(string s, string t, int pos=0)'
+ returns the position of the first occurrence of string `t' in
+ string `s' at or after position `pos', or -1 if `t' is not a
+ substring of `s';
+
+ `int rfind(string s, string t, int pos=-1)'
+ returns the position of the last occurrence of string `t' in
+ string `s' at or before position `pos' (if `pos'=-1, at the
+ end of the string `s'), or -1 if `t' is not a substring of
+ `s';
+
+ `string insert(string s, int pos, string t)'
+ returns the string formed by inserting string `t' at position
+ `pos' in `s';
+
+ `string erase(string s, int pos, int n)'
+ returns the string formed by erasing the string of length `n'
+ (if `n'=-1, to the end of the string `s') at position `pos'
+ in `s';
+
+ `string substr(string s, int pos, int n=-1)'
+ returns the substring of `s' starting at position `pos' and
+ of length `n' (if `n'=-1, until the end of the string `s');
+
+ `string reverse(string s)'
+ returns the string formed by reversing string `s';
+
+ `string replace(string s, string before, string after)'
+ returns a string with all occurrences of the string `before'
+ in the string `s' changed to the string `after';
+
+ `string replace(string s, string[][] table)'
+ returns a string constructed by translating in string `s' all
+ occurrences of the string `before' in an array `table' of
+ string pairs {`before',`after'} to the corresponding string
+ `after';
+
+ `string[] split(string s, string delimiter="")'
+ returns an array of strings obtained by splitting `s' into
+ substrings delimited by `delimiter' (an empty delimiter
+ signifies a space, but with duplicate delimiters discarded);
+
+ `string format(string s, int n, string locale="")'
+ returns a string containing `n' formatted according to the
+ C-style format string `s' using locale `locale' (or the
+ current locale if an empty string is specified);
+
+ `string format(string s=defaultformat, string s=defaultseparator, real x, string locale="")'
+ returns a string containing `x' formatted according to the
+ C-style format string `s' using locale `locale' (or the
+ current locale if an empty string is specified), following
+ the behaviour of the C function `fprintf'), except that only
+ one data field is allowed, trailing zeros are removed by
+ default (unless `#' is specified), and (if the format string
+ specifies math mode) TeX is used to typeset scientific
+ notation using the `defaultseparator="\!\times\!";';
+
+ `int hex(string s);'
+ casts a hexidecimal string `s' to an integer;
+
+ `int ascii(string s);'
+ returns the ASCII code for the first character of string `s';
+
+ `string string(real x, int digits=realDigits)'
+ casts `x' to a string using precision `digits' and the C
+ locale;
+
+ `string locale(string s="")'
+ sets the locale to the given string, if nonempty, and returns
+ the current locale;
+
+ `string time(string format="%a %b %d %T %Z %Y")'
+ returns the current time formatted by the ANSI C routine
+ `strftime' according to the string `format' using the current
+ locale. Thus time();
+ time("%a %b %d %H:%M:%S %Z %Y");
+
+ are equivalent ways of returning the current time in the
+ default format used by the `UNIX' `date' command;
+
+ `int seconds(string t="", string format="")'
+ returns the time measured in seconds after the Epoch (Thu Jan
+ 01 00:00:00 UTC 1970) as determined by the ANSI C routine
+ `strptime' according to the string `format' using the current
+ locale, or the current time if `t' is the empty string. Note
+ that the `"%Z"' extension to the POSIX `strptime'
+ specification is ignored by the current GNU C Library. If an
+ error occurs, the value -1 is returned. Here are some
+ examples: seconds("Mar 02 11:12:36 AM PST 2007","%b %d %r PST %Y");
+ seconds(time("%b %d %r %z %Y"),"%b %d %r %z %Y");
+ seconds(time("%b %d %r %Z %Y"),"%b %d %r "+time("%Z")+" %Y");
+ 1+(seconds()-seconds("Jan 1","%b %d"))/(24*60*60);
+ The last example returns today's ordinal date, measured from
+ the beginning of the year.
+
+ `string time(int seconds, string format="%a %b %d %T %Z %Y")'
+ returns the time corresponding to `seconds' seconds after the
+ Epoch (Thu Jan 01 00:00:00 UTC 1970) formatted by the ANSI C
+ routine `strftime' according to the string `format' using the
+ current locale. For example, to return the date corresponding
+ to 24 hours ago: time(seconds()-24*60*60);
+
+ `int system(string s)'
+
+ `int system(string[] s)'
+ if the setting `safe' is false, call the arbitrary system
+ command `s';
+
+ `void asy(string format, bool overwrite=false ... string[] s)'
+ conditionally process each file name in array `s' in a new
+ environment, using format `format', overwriting the output
+ file only if `overwrite' is true;
+
+ `void abort(string s="")'
+ aborts execution (with a non-zero return code in batch mode);
+ if string `s' is nonempty, a diagnostic message constructed
+ from the source file, line number, and `s' is printed;
+
+ `void assert(bool b, string s="")'
+ aborts execution with an error message constructed from `s' if
+ `b=false';
+
+ `void exit()'
+ exits (with a zero error return code in batch mode);
+
+ `void sleep(int seconds)'
+ pauses for the given number of seconds;
+
+ `void usleep(int microseconds)'
+ pauses for the given number of microseconds;
+
+ `void beep()'
+ produces a beep on the console;
+
+
+
+ As in C/C++, complicated types may be abbreviated with `typedef'
+(see the example in *note Functions::).
+
+
+File: asymptote.info, Node: Paths and guides, Next: Pens, Prev: Data types, Up: Programming
+
+6.2 Paths and guides
+====================
+
+`path'
+ a cubic spline resolved into a fixed path. The implicit
+ initializer for paths is `nullpath'.
+
+ For example, the routine `circle(pair c, real r)', which returns a
+ Bezier curve approximating a circle of radius `r' centered on `c',
+ is based on `unitcircle' (*note unitcircle::): path circle(pair c, real r)
+ {
+ return shift(c)*scale(r)*unitcircle;
+ }
+ If high accuracy is needed, a true circle may be produced with the
+ routine `Circle' defined in the module `graph.asy': import graph;
+ path Circle(pair c, real r, int n=nCircle);
+
+ A circular arc consistent with `circle' centered on `c' with
+ radius `r' from `angle1' to `angle2' degrees, drawing
+ counterclockwise if `angle2 >= angle1', can be constructed with path arc(pair c, real r, real angle1, real angle2);
+ One may also specify the direction explicitly: path arc(pair c, real r, real angle1, real angle2, bool direction);
+ Here the direction can be specified as CCW (counter-clockwise) or
+ CW (clockwise). For convenience, an arc centered at `c' from pair
+ `z1' to `z2' (assuming `|z2-c|=|z1-c|') in the may also be
+ constructed with path arc(pair c, explicit pair z1, explicit pair z2,
+ bool direction=CCW)
+
+ If high accuracy is needed, true arcs may be produced with routines
+ in the module `graph.asy' that produce Bezier curves with `n'
+ control points: import graph;
+ path Arc(pair c, real r, real angle1, real angle2, bool direction,
+ int n=nCircle);
+ path Arc(pair c, real r, real angle1, real angle2, int n=nCircle);
+ path Arc(pair c, explicit pair z1, explicit pair z2,
+ bool direction=CCW, int n=nCircle);
+
+ An ellipse can be drawn with the routine path ellipse(pair c, real a, real b)
+ {
+ return shift(c)*scale(a,b)*unitcircle;
+ }
+
+ A brace can be constructed between pairs `a' and `b' with path brace(pair a, pair b, real amplitude=bracedefaultratio*length(b-a));
+
+ This example illustrates the use of all five guide connectors
+ discussed in *note Tutorial:: and *note Bezier curves::: size(300,0);
+ pair[] z=new pair[10];
+
+ z[0]=(0,100); z[1]=(50,0); z[2]=(180,0);
+
+ for(int n=3; n <= 9; ++n)
+ z[n]=z[n-3]+(200,0);
+
+ path p=z[0]..z[1]---z[2]::{up}z[3]
+ &z[3]..z[4]--z[5]::{up}z[6]
+ &z[6]::z[7]---z[8]..{up}z[9];
+
+ draw(p,grey+linewidth(4mm));
+
+ dot(z);
+
+
+
+ Here are some useful functions for paths:
+
+ `int length(path p);'
+ This is the number of (linear or cubic) segments in path `p'.
+ If `p' is cyclic, this is the same as the number of nodes in
+ `p'.
+
+ `int size(path p);'
+ This is the number of nodes in the path `p'. If `p' is
+ cyclic, this is the same as `length(p)'.
+
+ `bool cyclic(path p);'
+ returns `true' iff path `p' is cyclic.
+
+ `bool straight(path p, int i);'
+ returns `true' iff the segment of path `p' between node `i'
+ and node `i+1' is straight.
+
+ `bool piecewisestraight(path p)'
+ returns `true' iff the path `p' is piecewise straight.
+
+ `pair point(path p, int t);'
+ If `p' is cyclic, return the coordinates of node `t' mod
+ `length(p)'. Otherwise, return the coordinates of node `t',
+ unless `t' < 0 (in which case `point(0)' is returned) or `t'
+ > `length(p)' (in which case `point(length(p))' is returned).
+
+ `pair point(path p, real t);'
+ This returns the coordinates of the point between node
+ `floor(t)' and `floor(t)+1' corresponding to the cubic spline
+ parameter `t-floor(t)' (*note Bezier curves::). If `t' lies
+ outside the range [0,`length(p)'], it is first reduced modulo
+ `length(p)' in the case where `p' is cyclic or else converted
+ to the corresponding endpoint of `p'.
+
+ `pair dir(path p, int t, int sign=0, bool normalize=true);'
+ If `sign < 0', return the direction (as a pair) of the
+ incoming tangent to path `p' at node `t'; if `sign > 0',
+ return the direction of the outgoing tangent. If `sign=0',
+ the mean of these two directions is returned.
+
+ `pair dir(path p, real t, bool normalize=true);'
+ returns the direction of the tangent to path `p' at the point
+ between node `floor(t)' and `floor(t)+1' corresponding to the
+ cubic spline parameter `t-floor(t)' (*note Bezier curves::).
+
+ `pair dir(path p)'
+ returns dir(p,length(p)).
+
+ `pair dir(path p, path q)'
+ returns unit(dir(p)+dir(q)).
+
+ `pair accel(path p, int t, int sign=0);'
+ If `sign < 0', return the acceleration of the incoming path
+ `p' at node `t'; if `sign > 0', return the acceleration of
+ the outgoing path. If `sign=0', the mean of these two
+ accelerations is returned.
+
+ `pair accel(path p, real t);'
+ returns the acceleration of the path `p' at the point `t'.
+
+ `real radius(path p, real t);'
+ returns the radius of curvature of the path `p' at the point
+ `t'.
+
+ `pair precontrol(path p, int t);'
+ returns the precontrol point of `p' at node `t'.
+
+ `pair precontrol(path p, real t);'
+ returns the effective precontrol point of `p' at parameter
+ `t'.
+
+ `pair postcontrol(path p, int t);'
+ returns the postcontrol point of `p' at node `t'.
+
+ `pair postcontrol(path p, real t);'
+ returns the effective postcontrol point of `p' at parameter
+ `t'.
+
+ `real arclength(path p);'
+ returns the length (in user coordinates) of the piecewise
+ linear or cubic curve that path `p' represents.
+
+ `real arctime(path p, real L);'
+ returns the path "time", a real number between 0 and the
+ length of the path in the sense of `point(path p, real t)',
+ at which the cumulative arclength (measured from the
+ beginning of the path) equals `L'.
+
+ `real arcpoint(path p, real L);'
+ returns `point(p,arctime(p,L))'.
+
+ `real dirtime(path p, pair z);'
+ returns the first "time", a real number between 0 and the
+ length of the path in the sense of `point(path, real)', at
+ which the tangent to the path has the direction of pair `z',
+ or -1 if this never happens.
+
+ `real reltime(path p, real l);'
+ returns the time on path `p' at the relative fraction `l' of
+ its arclength.
+
+ `pair relpoint(path p, real l);'
+ returns the point on path `p' at the relative fraction `l' of
+ its arclength.
+
+ `pair midpoint(path p);'
+ returns the point on path `p' at half of its arclength.
+
+ `path reverse(path p);'
+ returns a path running backwards along `p'.
+
+ `path subpath(path p, int a, int b);'
+ returns the subpath of `p' running from node `a' to node `b'.
+ If `a' < `b', the direction of the subpath is reversed.
+
+ `path subpath(path p, real a, real b);'
+ returns the subpath of `p' running from path time `a' to path
+ time `b', in the sense of `point(path, real)'. If `a' < `b',
+ the direction of the subpath is reversed.
+
+ `real[] intersect(path p, path q, real fuzz=-1);'
+ If `p' and `q' have at least one intersection point, return a
+ real array of length 2 containing the times representing the
+ respective path times along `p' and `q', in the sense of
+ `point(path, real)', for one such intersection point (as
+ chosen by the algorithm described on page 137 of `The
+ MetaFontbook'). The computations are performed to the
+ absolute error specified by `fuzz', or if `fuzz < 0', to
+ machine precision. If the paths do not intersect, return a
+ real array of length 0.
+
+ `real[][] intersections(path p, path q, real fuzz=-1);'
+ Return all (unless there are infinitely many) intersection
+ times of paths `p' and `q' as a sorted array of real arrays
+ of length 2 (*note sort::). The computations are performed to
+ the absolute error specified by `fuzz', or if `fuzz < 0', to
+ machine precision.
+
+ `real[] intersections(path p, explicit pair a, explicit pair b, real fuzz=-1);'
+ Return all (unless there are infinitely many) intersection
+ times of path `p' with the (infinite) line through points `a'
+ and `b' as a sorted array. The intersections returned are
+ guaranteed to be correct to within the absolute error
+ specified by `fuzz', or if `fuzz < 0', to machine precision.
+
+ `real[] times(path p, real x)'
+ returns all intersection times of path `p' with the vertical
+ line through `(x,0)'.
+
+ `real[] times(path p, explicit pair z)'
+ returns all intersection times of path `p' with the
+ horizontal line through `(0,z.y)'.
+
+ `real[] mintimes(path p)'
+ returns an array of length 2 containing times at which path
+ `p' reaches its minimal horizontal and vertical extents,
+ respectively.
+
+ `real[] maxtimes(path p)'
+ returns an array of length 2 containing times at which path
+ `p' reaches its maximal horizontal and vertical extents,
+ respectively.
+
+ `pair intersectionpoint(path p, path q, real fuzz=-1);'
+ returns the intersection point
+ `point(p,intersect(p,q,fuzz)[0])'.
+
+ `pair[] intersectionpoints(path p, path q, real fuzz=-1);'
+ returns an array containing all intersection points of the
+ paths `p' and `q'.
+
+ `pair extension(pair P, pair Q, pair p, pair q);'
+ returns the intersection point of the extensions of the line
+ segments `P--Q' and `p--q', or if the lines are parallel,
+ `(infinity,infinity)'.
+
+ `slice cut(path p, path knife, int n);'
+ returns the portions of path `p' before and after the `n'th
+ intersection of `p' with path `knife' as a structure `slice'
+ (if no intersection exist is found, the entire path is
+ considered to be `before' the intersection): struct slice {
+ path before,after;
+ }
+ The argument `n' is treated as modulo the number of
+ intersections.
+
+ `slice firstcut(path p, path knife);'
+ equivalent to `cut(p,knife,0);' Note that `firstcut.after'
+ plays the role of the `MetaPost cutbefore' command.
+
+ `slice lastcut(path p, path knife);'
+ equivalent to `cut(p,knife,-1);' Note that `lastcut.before'
+ plays the role of the `MetaPost cutafter' command.
+
+ `path buildcycle(... path[] p);'
+ This returns the path surrounding a region bounded by a list
+ of two or more consecutively intersecting paths, following
+ the behaviour of the `MetaPost buildcycle' command.
+
+ `pair min(path p);'
+ returns the pair (left,bottom) for the path bounding box of
+ path `p'.
+
+ `pair max(path p);'
+ returns the pair (right,top) for the path bounding box of
+ path `p'.
+
+ `int windingnumber(path p, pair z);'
+ returns the winding number of the cyclic path `p' relative to
+ the point `z'. The winding number is positive if the path
+ encircles `z' in the counterclockwise direction. If `z' lies
+ on `p' the constant `undefined' (defined to be the largest
+ odd integer) is returned.
+
+ `bool interior(int windingnumber, pen fillrule)'
+ returns true if `windingnumber' corresponds to an interior
+ point according to `fillrule'.
+
+ `bool inside(path p, pair z, pen fillrule=currentpen);'
+ returns `true' iff the point `z' lies inside or on the edge of
+ the region bounded by the cyclic path `p' according to the
+ fill rule `fillrule' (*note fillrule::).
+
+ `int inside(path p, path q, pen fillrule=currentpen);'
+ returns `1' if the cyclic path `p' strictly contains `q'
+ according to the fill rule `fillrule' (*note fillrule::), `-1'
+ if the cyclic path `q' strictly contains `p', and `0'
+ otherwise.
+
+ `pair inside(path p, pen fillrule=currentpen);'
+ returns an arbitrary point strictly inside a cyclic path `p'
+ according to the fill rule `fillrule' (*note fillrule::).
+
+ `real side(pair a, pair b, pair c);'
+ determines the side of `a--b' that c lies on (negative=left,
+ zero=on `a--b', positive=right).
+
+ `real incircle(pair a, pair b, pair c, pair d);'
+ determines the side of the counterclockwise circle through
+ `a,b,c' that `d' lies on (negative=inside, 0=on circle,
+ positive=right).
+
+ `path[] strokepath(path g, pen p=currentpen);'
+ returns the path array that `PostScript' would fill in
+ drawing path `g' with pen `p'.
+
+
+`guide'
+ an unresolved cubic spline (list of cubic-spline nodes and control
+ points). The implicit initializer for a guide is `nullpath'; this
+ is useful for building up a guide within a loop.
+
+ A guide is similar to a path except that the computation of the
+ cubic spline is deferred until drawing time (when it is resolved
+ into a path); this allows two guides with free endpoint conditions
+ to be joined together smoothly. The solid curve in the following
+ example is built up incrementally as a guide, but only resolved at
+ drawing time; the dashed curve is incrementally resolved at each
+ iteration, before the entire set of nodes (shown in red) is known:
+
+ size(200);
+
+ real mexican(real x) {return (1-8x^2)*exp(-(4x^2));}
+
+ int n=30;
+ real a=1.5;
+ real width=2a/n;
+
+ guide hat;
+ path solved;
+
+ for(int i=0; i < n; ++i) {
+ real t=-a+i*width;
+ pair z=(t,mexican(t));
+ hat=hat..z;
+ solved=solved..z;
+ }
+
+ draw(hat);
+ dot(hat,red);
+ draw(solved,dashed);
+
+
+
+ We point out an efficiency distinction in the use of guides and
+ paths: guide g;
+ for(int i=0; i < 10; ++i)
+ g=g--(i,i);
+ path p=g;
+
+ runs in linear time, whereas path p;
+ for(int i=0; i < 10; ++i)
+ p=p--(i,i);
+
+ runs in quadratic time, as the entire path up to that point is
+ copied at each step of the iteration.
+
+ The following routines can be used to examine the individual
+ elements of a guide without actually resolving the guide to a
+ fixed path (except for internal cycles, which are resolved):
+
+ `int size(guide g);'
+ Analogous to `size(path p)'.
+
+ `int length(guide g);'
+ Analogous to `length(path p)'.
+
+ `bool cyclic(path p);'
+ Analogous to `cyclic(path p)'.
+
+ `pair point(guide g, int t);'
+ Analogous to `point(path p, int t)'.
+
+ `guide reverse(guide g);'
+ Analogous to `reverse(path p)'. If `g' is cyclic and also
+ contains a secondary cycle, it is first solved to a path,
+ then reversed. If `g' is not cyclic but contains an internal
+ cycle, only the internal cycle is solved before reversal. If
+ there are no internal cycles, the guide is reversed but not
+ solved to a path.
+
+ `pair[] dirSpecifier(guide g, int i);'
+ This returns a pair array of length 2 containing the outgoing
+ (in element 0) and incoming (in element 1) direction
+ specifiers (or `(0,0)' if none specified) for the segment of
+ guide `g' between nodes `i' and `i+1'.
+
+ `pair[] controlSpecifier(guide g, int i);'
+ If the segment of guide `g' between nodes `i' and `i+1' has
+ explicit outgoing and incoming control points, they are
+ returned as elements 0 and 1, respectively, of a two-element
+ array. Otherwise, an empty array is returned.
+
+ `tensionSpecifier tensionSpecifier(guide g, int i);'
+ This returns the tension specifier for the segment of guide
+ `g' between nodes `i' and `i+1'. The individual components of
+ the `tensionSpecifier' type can be accessed as the virtual
+ members `in', `out', and `atLeast'.
+
+ `real[] curlSpecifier(guide g);'
+ This returns an array containing the initial curl specifier
+ (in element 0) and final curl specifier (in element 1) for
+ guide `g'.
+
+
+ As a technical detail we note that a direction specifier given to
+ `nullpath' modifies the node on the other side: the guides a..{up}nullpath..b;
+ c..nullpath{up}..d;
+ e..{up}nullpath{down}..f;
+ are respectively equivalent to a..nullpath..{up}b;
+ c{up}..nullpath..d;
+ e{down}..nullpath..{up}f;
+
+
+
+File: asymptote.info, Node: Pens, Next: Transforms, Prev: Paths and guides, Up: Programming
+
+6.3 Pens
+========
+
+In `Asymptote', pens provide a context for the four basic drawing
+commands (*note Drawing commands::). They are used to specify the
+following drawing attributes: color, line type, line width, line cap,
+line join, fill rule, text alignment, font, font size, pattern,
+overwrite mode, and calligraphic transforms on the pen nib. The default
+pen used by the drawing routines is called `currentpen'. This provides
+the same functionality as the `MetaPost' command `pickup'. The
+implicit initializer for pens is `defaultpen'.
+
+ Pens may be added together with the nonassociative binary operator
+`+'. This will add the colors of the two pens. All other non-default
+attributes of the rightmost pen will override those of the leftmost
+pen. Thus, one can obtain a yellow dashed pen by saying
+`dashed+red+green' or `red+green+dashed' or `red+dashed+green'. The
+binary operator `*' can be used to scale the color of a pen by a real
+number, until it saturates with one or more color components equal to 1.
+
+ * Colors are specified using one of the following colorspaces:
+ `pen gray(real g);'
+ This produces a grayscale color, where the intensity `g' lies
+ in the interval [0,1], with 0.0 denoting black and 1.0
+ denoting white.
+
+ `pen rgb(real r, real g, real b);'
+ This produces an RGB color, where each of the red, green, and
+ blue intensities `r', `g', `b', lies in the interval [0,1].
+
+ `pen cmyk(real c, real m, real y, real k);'
+ This produces a CMYK color, where each of the cyan, magenta,
+ yellow, and black intensities `c', `m', `y', `k', lies in the
+ interval [0,1].
+
+ `pen invisible;'
+ This special pen writes in invisible ink, but adjusts the
+ bounding box as if something had been drawn (like the
+ `\phantom' command in TeX). The function `bool
+ invisible(pen)' can be used to test whether a pen is
+ invisible.
+
+
+ The default color is `black'; this may be changed with the routine
+ `defaultpen(pen)'. The function `colorspace(pen p)' returns the
+ colorspace of pen `p' as a string (`"gray"', `"rgb"', `"cmyk"', or
+ `""').
+
+ The function `real[] colors(pen)' returns the color components of
+ a pen. The functions `pen gray(pen)', `pen rgb(pen)', and `pen
+ cmyk(pen)' return new pens obtained by converting their arguments
+ to the respective color spaces. The function
+ `colorless(pen=currentpen)' returns a copy of its argument with
+ the color attributes stripped (to avoid color mixing).
+
+ A 6-character RGB hexidecimal string can be converted to a pen with
+ the routine pen rgb(string s);
+ A pen can be converted to a hexidecimal string with
+
+ * string hex(pen p);
+
+ Various shades and mixtures of the grayscale primary colors
+ `black' and `white', RGB primary colors `red', `green', and
+ `blue', and RGB secondary colors `cyan', `magenta', and `yellow'
+ are defined as named colors, along with the CMYK primary colors
+ `Cyan', `Magenta', `Yellow', and `Black', in the module `plain':
+
+
+
+ The standard 140 RGB `X11' colors can be imported with the command import x11colors;
+ and the standard 68 CMYK TeX colors can be imported with the
+ command import texcolors;
+ Note that there is some overlap between these two standards and
+ the definitions of some colors (e.g. `Green') actually disagree.
+
+ `Asymptote' also comes with a `asycolors.sty' `LaTeX' package that
+ defines to `LaTeX' CMYK versions of `Asymptote''s predefined
+ colors, so that they can be used directly within `LaTeX' strings.
+ Normally, such colors are passed to `LaTeX' via a pen argument;
+ however, to change the color of only a portion of a string, say
+ for a slide presentation, (*note slide::) it may be desirable to
+ specify the color directly to `LaTeX'. This file can be passed to
+ `LaTeX' with the `Asymptote' command usepackage("asycolors");
+
+ The structure `hsv' defined in `plain_pens.asy' may be used to
+ convert between HSV and RGB spaces, where the hue `h' is an angle
+ in [0,360) and the saturation `s' and value `v' lie in `[0,1]': pen p=hsv(180,0.5,0.75);
+ write(p); // ([default], red=0.375, green=0.75, blue=0.75)
+ hsv q=p;
+ write(q.h,q.s,q.v); // 180 0.5 0.75
+
+ * Line types are specified with the function `pen linetype(real[] a,
+ real offset=0, bool scale=true, bool adjust=true)', where `a' is
+ an array of real array numbers. The optional parameter `offset'
+ specifies where in the pattern to begin. The first number
+ specifies how far (if `scale' is `true', in units of the pen line
+ width; otherwise in `PostScript' units) to draw with the pen on,
+ the second number specifies how far to draw with the pen off, and
+ so on. If `adjust' is `true', these spacings are automatically
+ adjusted by `Asymptote' to fit the arclength of the path. Here are
+ the predefined line types: pen solid=linetype(new real[]);
+ pen dotted=linetype(new real[] {0,4});
+ pen dashed=linetype(new real[] {8,8});
+ pen longdashed=linetype(new real[] {24,8});
+ pen dashdotted=linetype(new real[] {8,8,0,8});
+ pen longdashdotted=linetype(new real[] {24,8,0,8});
+ pen Dotted(pen p=currentpen) {return linetype(new real[] {0,3})+2*linewidth(p);}
+ pen Dotted=Dotted();
+
+
+
+ The default line type is `solid'; this may be changed with
+ `defaultpen(pen)'. The line type of a pen can be determined with
+ the functions `real[] linetype(pen p=currentpen)', `real
+ offset(pen p)', `bool scale(pen p)', and `bool adjust(pen p)'.
+
+ * The pen line width is specified in `PostScript' units with `pen
+ linewidth(real)'. The default line width is 0.5 bp; this value may
+ be changed with `defaultpen(pen)'. The line width of a pen is
+ returned by `real linewidth(pen p=currentpen)'. For convenience,
+ in the module `plain_pens' we define void defaultpen(real w) {defaultpen(linewidth(w));}
+ pen operator +(pen p, real w) {return p+linewidth(w);}
+ pen operator +(real w, pen p) {return linewidth(w)+p;}
+ so that one may set the line width like this: defaultpen(2);
+ pen p=red+0.5;
+
+ * A pen with a specific `PostScript' line cap is returned on calling
+ `linecap' with an integer argument: pen squarecap=linecap(0);
+ pen roundcap=linecap(1);
+ pen extendcap=linecap(2);
+
+ The default line cap, `roundcap', may be changed with
+ `defaultpen(pen)'. The line cap of a pen is returned by `int
+ linecap(pen p=currentpen)'.
+
+ * A pen with a specific `PostScript' join style is returned on
+ calling `linejoin' with an integer argument: pen miterjoin=linejoin(0);
+ pen roundjoin=linejoin(1);
+ pen beveljoin=linejoin(2);
+
+ The default join style, `roundjoin', may be changed with
+ `defaultpen(pen)'.The join style of a pen is returned by `int
+ linejoin(pen p=currentpen)'.
+
+ * A pen with a specific `PostScript' miter limit is returned by
+ calling `miterlimit(real)'. The default miterlimit, `10.0', may
+ be changed with `defaultpen(pen)'. The miter limit of a pen is
+ returned by `real miterlimit(pen p=currentpen)'.
+
+ * A pen with a specific `PostScript' fill rule is returned on
+ calling `fillrule' with an integer argument: pen zerowinding=fillrule(0);
+ pen evenodd=fillrule(1);
+
+ The fill rule, which identifies the algorithm used to determine the
+ insideness of a path or array of paths, only affects the `clip',
+ `fill', and `inside' functions. For the `zerowinding' fill rule, a
+ point `z' is outside the region bounded by a path if the number of
+ upward intersections of the path with the horizontal line
+ `z--z+infinity' minus the number of downward intersections is
+ zero. For the `evenodd' fill rule, `z' is considered to be outside
+ the region if the total number of such intersections is even. The
+ default fill rule, `zerowinding', may be changed with
+ `defaultpen(pen)'. The fill rule of a pen is returned by `int
+ fillrule(pen p=currentpen)'.
+
+ * A pen with a specific text alignment setting is returned on
+ calling `basealign' with an integer argument: pen nobasealign=basealign(0);
+ pen basealign=basealign(1);
+
+ The default setting, `nobasealign',which may be changed with
+ `defaultpen(pen)', causes the label alignment routines to use the
+ full label bounding box for alignment. In contrast, `basealign'
+ requests that the TeX baseline be respected. The base align
+ setting of a pen is returned by `int basealigin(pen p=currentpen)'.
+
+ * The font size is specified in TeX points (1 pt = 1/72.27 inches)
+ with the function `pen fontsize(real size, real
+ lineskip=1.2*size)'. The default font size, 12pt, may be changed
+ with `defaultpen(pen)'. Nonstandard font sizes may require
+ inserting import fontsize;
+ at the beginning of the file (this requires the `type1cm' package
+ available from
+
+ `http://www.ctan.org/tex-archive/macros/latex/contrib/type1cm/'
+ and included in recent `LaTeX' distributions). The font size and
+ line skip of a pen can be examined with the routines `real
+ fontsize(pen p=currentpen)' and `real lineskip(pen p=currentpen)',
+ respectively.
+
+ * A pen using a specific `LaTeX' `NFSS' font is returned by calling
+ the function `pen font(string encoding, string family, string
+ series, string shape)'. The default setting,
+ `font("OT1","cmr","m","n")', corresponds to 12pt Computer Modern
+ Roman; this may be changed with `defaultpen(pen)'. The font
+ setting of a pen is returned by `string font(pen p=currentpen)'.
+ Support for standardized international characters is provided by
+ the `unicode' package (*note unicode::).
+
+ Alternatively, one may select a fixed-size TeX font (on which
+ `fontsize' has no effect) like `"cmr12"' (12pt Computer Modern
+ Roman) or `"pcrr"' (Courier) using the function `pen font(string
+ name)'. An optional size argument can also be given to scale the
+ font to the requested size: `pen font(string name, real size)'.
+
+ A nonstandard font command can be generated with `pen
+ fontcommand(string)'.
+
+ A convenient interface to the following standard `PostScript'
+ fonts is also provided: pen AvantGarde(string series="m", string shape="n");
+ pen Bookman(string series="m", string shape="n");
+ pen Courier(string series="m", string shape="n");
+ pen Helvetica(string series="m", string shape="n");
+ pen NewCenturySchoolBook(string series="m", string shape="n");
+ pen Palatino(string series="m", string shape="n");
+ pen TimesRoman(string series="m", string shape="n");
+ pen ZapfChancery(string series="m", string shape="n");
+ pen Symbol(string series="m", string shape="n");
+ pen ZapfDingbats(string series="m", string shape="n");
+
+ * The transparency of a pen can be changed with the command: pen opacity(real opacity=1, string blend="Compatible");
+ The opacity can be varied from `0' (fully transparent) to the
+ default value of `1' (opaque), and `blend' specifies one of the
+ following foreground-background blending operations: "Compatible","Normal","Multiply","Screen","Overlay","SoftLight",
+ "HardLight","ColorDodge","ColorBurn","Darken","Lighten","Difference",
+ "Exclusion","Hue","Saturation","Color","Luminosity",
+ as described in
+
+ `http://partners.adobe.com/public/developer/en/pdf/PDFReference16.pdf'.
+ Since `PostScript' does not support transparency, this feature is
+ only effective with the `-f pdf' output format option; other
+ formats can be produced from the resulting PDF file with the
+ `ImageMagick' `convert' program. Labels are always drawn with an
+ `opacity' of 1. A simple example of transparent filling is
+ provided in the example file `transparency.asy'.
+
+ * `PostScript' commands within a `picture' may be used to create a
+ tiling pattern, identified by the string `name', for `fill' and
+ `draw' operations by adding it to the global `PostScript' frame
+ `currentpatterns', with optional left-bottom margin `lb' and
+ right-top margin `rt'. import patterns;
+ void add(string name, picture pic, pair lb=0, pair rt=0);
+
+ To `fill' or `draw' using pattern `name', use the pen
+ `pattern("name")'. For example, rectangular tilings can be
+ constructed using the routines `picture tile(real Hx=5mm, real
+ Hy=0, pen p=currentpen, filltype filltype=NoFill)', `picture
+ checker(real Hx=5mm, real Hy=0, pen p=currentpen)', and `picture
+ brick(real Hx=5mm, real Hy=0, pen p=currentpen)' defined in
+ `patterns.asy': size(0,90);
+ import patterns;
+
+ add("tile",tile());
+ add("filledtilewithmargin",tile(6mm,4mm,red,Fill),(1mm,1mm),(1mm,1mm));
+ add("checker",checker());
+ add("brick",brick());
+
+ real s=2.5;
+ filldraw(unitcircle,pattern("tile"));
+ filldraw(shift(s,0)*unitcircle,pattern("filledtilewithmargin"));
+ filldraw(shift(2s,0)*unitcircle,pattern("checker"));
+ filldraw(shift(3s,0)*unitcircle,pattern("brick"));
+
+
+
+ Hatch patterns can be generated with the routines `picture
+ hatch(real H=5mm, pair dir=NE, pen p=currentpen)', `picture
+ crosshatch(real H=5mm, pen p=currentpen)': size(0,100);
+ import patterns;
+
+ add("hatch",hatch());
+ add("hatchback",hatch(NW));
+ add("crosshatch",crosshatch(3mm));
+
+ real s=1.25;
+ filldraw(unitsquare,pattern("hatch"));
+ filldraw(shift(s,0)*unitsquare,pattern("hatchback"));
+ filldraw(shift(2s,0)*unitsquare,pattern("crosshatch"));
+
+
+
+ You may need to turn off aliasing in your `PostScript' viewer for
+ patterns to appear correctly. Custom patterns can easily be
+ constructed, following the examples in `patterns.asy'. The tiled
+ pattern can even incorporate shading (*note gradient shading::),
+ as illustrated in this example (not included in the manual because
+ not all printers support `PostScript' 3): size(0,100);
+ import patterns;
+
+ real d=4mm;
+ picture tiling;
+ path square=scale(d)*unitsquare;
+ axialshade(tiling,square,white,(0,0),black,(d,d));
+ fill(tiling,shift(d,d)*square,blue);
+ add("shadedtiling",tiling);
+
+ filldraw(unitcircle,pattern("shadedtiling"));
+
+
+
+ * One can specify a custom pen nib as an arbitrary polygonal path
+ with `pen makepen(path)'; this path represents the mark to be
+ drawn for paths containing a single point. This pen nib path can be
+ recovered from a pen with `path nib(pen)'. Unlike in `MetaPost',
+ the path need not be convex:
+
+ size(200);
+ pen convex=makepen(scale(10)*polygon(8))+grey;
+ draw((1,0.4),convex);
+ draw((0,0)---(1,1)..(2,0)--cycle,convex);
+
+ pen nonconvex=scale(10)*
+ makepen((0,0)--(0.25,-1)--(0.5,0.25)--(1,0)--(0.5,1.25)--cycle)+red;
+ draw((0.5,-1.5),nonconvex);
+ draw((0,-1.5)..(1,-0.5)..(2,-1.5),nonconvex);
+
+
+
+ The value `nullpath' represents a circular pen nib (the default);
+ an elliptical pen can be achieved simply by multiplying the pen by
+ a transform: `yscale(2)*currentpen'.
+
+ * One can prevent labels from overwriting one another by using the
+ pen attribute `overwrite', which takes a single argument:
+
+ `Allow'
+ Allow labels to overwrite one another. This is the default
+ behaviour (unless overridden with `defaultpen(pen)'.
+
+ `Suppress'
+ Suppress, with a warning, each label that would overwrite
+ another label.
+
+ `SuppressQuiet'
+ Suppress, without warning, each label that would overwrite
+ another label.
+
+ `Move'
+ Move a label that would overwrite another out of the way and
+ issue a warning. As this adjustment is during the final
+ output phase (in `PostScript' coordinates) it could result in
+ a larger figure than requested.
+
+ `MoveQuiet'
+ Move a label that would overwrite another out of the way,
+ without warning. As this adjustment is during the final
+ output phase (in `PostScript' coordinates) it could result in
+ a larger figure than requested.
+
+
+
+ The routine `defaultpen()' returns the current default pen
+attributes. Calling the routine `resetdefaultpen()' resets all pen
+default attributes to their initial values.
+
+
+File: asymptote.info, Node: Transforms, Next: Frames and pictures, Prev: Pens, Up: Programming
+
+6.4 Transforms
+==============
+
+`Asymptote' makes extensive use of affine transforms. A pair `(x,y)' is
+transformed by the transform `t=(t.x,t.y,t.xx,t.xy,t.yx,t.yy)' to
+`(x',y')', where
+x' = t.x + t.xx * x + t.xy * y
+y' = t.y + t.yx * x + t.yy * y
+ This is equivalent to the `PostScript' transformation `[t.xx t.yx t.xy
+t.yy t.x t.y]'.
+
+ Transforms can be applied to pairs, guides, paths, pens, strings,
+transforms, frames, and pictures by multiplication (via the binary
+operator `*') on the left (*note circle:: for an example). Transforms
+can be composed with one another and inverted with the function
+`transform inverse(transform t)'; they can also be raised to any
+integer power with the `^' operator.
+
+ The built-in transforms are:
+
+`transform identity();'
+ the identity transform;
+
+`transform shift(pair z);'
+ translates by the pair `z';
+
+`transform shift(real x, real y);'
+ translates by the pair `(x,y)';
+
+`transform xscale(real x);'
+ scales by `x' in the x direction;
+
+`transform yscale(real y);'
+ scales by `y' in the y direction;
+
+`transform scale(real s);'
+ scale by `s' in both x and y directions;
+
+`transform scale(real x, real y);'
+ scale by `x' in the x direction and by `y' in the y direction;
+
+`transform slant(real s);'
+ maps `(x,y)' -> `(x+s*y,y)';
+
+`transform rotate(real angle, pair z=(0,0));'
+ rotates by `angle' in degrees about `z';
+
+`transform reflect(pair a, pair b);'
+ reflects about the line `a--b'.
+
+ The implicit initializer for transforms is `identity()'. The
+routines `shift(transform t)' and `shiftless(transform t)' return the
+transforms `(t.x,t.y,0,0,0,0)' and `(0,0,t.xx,t.xy,t.yx,t.yy)'
+respectively.
+
+
+File: asymptote.info, Node: Frames and pictures, Next: Files, Prev: Transforms, Up: Programming
+
+6.5 Frames and pictures
+=======================
+
+`frame'
+ Frames are canvases for drawing in `PostScript' coordinates. While
+ working with frames directly is occasionally necessary for
+ constructing deferred drawing routines, pictures are usually more
+ convenient to work with. The implicit initializer for frames is
+ `newframe'. The function `bool empty(frame f)' returns `true' only
+ if the frame `f' is empty. A frame may be erased with the
+ `erase(frame)' routine. The functions `pair min(frame)' and `pair
+ max(frame)' return the (left,bottom) and (right,top) coordinates
+ of the frame bounding box, respectively. The contents of frame
+ `src' may be appended to frame `dest' with the command void add(frame dest, frame src);
+ or prepended with void prepend(frame dest, frame src);
+ A frame obtained by aligning frame `f' in the direction `align',
+ in a manner analogous to the `align' argument of `label' (*note
+ label::), is returned by frame align(frame f, pair align);
+
+ To draw or fill a box or ellipse around a label or frame and
+ return the boundary as a path, use one of the predefined
+ `envelope' routines path box(frame f, Label L="", real xmargin=0,
+ real ymargin=xmargin, pen p=currentpen,
+ filltype filltype=NoFill, bool above=true);
+ path roundbox(frame f, Label L="", real xmargin=0,
+ real ymargin=xmargin, pen p=currentpen,
+ filltype filltype=NoFill, bool above=true);
+ path ellipse(frame f, Label L="", real xmargin=0,
+ real ymargin=xmargin, pen p=currentpen,
+ filltype filltype=NoFill, bool above=true);
+
+`picture'
+ Pictures are high-level structures (*note Structures::) defined in
+ the module `plain' that provide canvases for drawing in user
+ coordinates. The default picture is called `currentpicture'. A
+ new picture can be created like this: picture pic;
+ Anonymous pictures can be made by the expression `new picture'.
+
+ The `size' routine specifies the dimensions of the desired picture:
+
+ void size(picture pic=currentpicture, real x, real y=x,
+ bool keepAspect=Aspect);
+
+ If the `x' and `y' sizes are both 0, user coordinates will be
+ interpreted as `PostScript' coordinates. In this case, the
+ transform mapping `pic' to the final output frame is `identity()'.
+
+ If exactly one of `x' or `y' is 0, no size restriction is imposed
+ in that direction; it will be scaled the same as the other
+ direction.
+
+ If `keepAspect' is set to `Aspect' or `true', the picture will be
+ scaled with its aspect ratio preserved such that the final width
+ is no more than `x' and the final height is no more than `y'.
+
+ If `keepAspect' is set to `IgnoreAspect' or `false', the picture
+ will be scaled in both directions so that the final width is `x'
+ and the height is `y'.
+
+ To make the user coordinates of picture `pic' represent multiples
+ of `x' units in the x direction and `y' units in the y direction,
+ use void unitsize(picture pic=currentpicture, real x, real y=x);
+ When nonzero, these `x' and `y' values override the corresponding
+ size parameters of picture `pic'.
+
+ The routine void size(picture pic=currentpicture, real xsize, real ysize,
+ pair min, pair max);
+ forces the final picture scaling to map the user coordinates
+ `box(min,max)' to a region of width `xsize' and height `ysize'
+ (when these parameters are nonzero).
+
+ Alternatively, calling the routine transform fixedscaling(picture pic=currentpicture, pair min,
+ pair max, pen p=nullpen, bool warn=false);
+ will cause picture `pic' to use a fixed scaling to map user
+ coordinates in `box(min,max)' to the (already specified) picture
+ size, taking account of the width of pen `p'. A warning will be
+ issued if the final picture exceeds the specified size.
+
+ A picture `pic' can be fit to a frame and output to a file
+ `prefix'.`format' using image format `format' by calling the
+ `shipout' function: void shipout(string prefix=defaultfilename, picture pic=currentpicture,
+ orientation orientation=orientation,
+ string format="", bool wait=false, bool view=true,
+ string options="", string script="",
+ light light=currentlight, projection P=currentprojection)
+ The default output format, `PostScript', may be changed with the
+ `-f' or `-tex' command-line options. The `options', `script', and
+ `projection' parameters are only relevant for 3D pictures. If
+ `defaultfilename' is an empty string, the prefix `outprefix()'
+ will be used.
+
+ A `shipout()' command is added implicitly at file exit if no
+ previous `shipout' commands have been executed. The default page
+ orientation is `Portrait'; this may be modified by changing the
+ variable `orientation'. To output in landscape mode, simply set
+ the variable `orientation=Landscape' or issue the command shipout(Landscape);
+
+ To rotate the page by -90 degrees, use the orientation `Seascape'. The
+ orientation `UpsideDown' rotates the page by 180 degrees.
+
+ A picture `pic' can be explicitly fit to a frame by calling frame pic.fit(real xsize=pic.xsize, real ysize=pic.ysize,
+ bool keepAspect=pic.keepAspect);
+ The default size and aspect ratio settings are those given to the
+ `size' command (which default to `0', `0', and `true',
+ respectively). The transformation that would currently be used to
+ fit a picture `pic' to a frame is returned by the member function
+ `pic.calculateTransform()'.
+
+ In certain cases (e.g. 2D graphs) where only an approximate size
+ estimate for `pic' is available, the picture fitting routine frame pic.scale(real xsize=this.xsize, real ysize=this.ysize,
+ bool keepAspect=this.keepAspect);
+ (which scales the resulting frame, including labels and fixed-size
+ objects) will enforce perfect compliance with the requested size
+ specification, but should not normally be required.
+
+ To draw a bounding box with margins around a picture, fit the
+ picture to a frame using the function frame bbox(picture pic=currentpicture, real xmargin=0,
+ real ymargin=xmargin, pen p=currentpen,
+ filltype filltype=NoFill);
+ Here `filltype' specifies one of the following fill types:
+ `FillDraw'
+ Fill the interior and draw the boundary.
+
+ `FillDraw(real xmargin=0, real ymargin=xmargin, pen fillpen=nullpen,'
+ `pen drawpen=nullpen)' If `fillpen' is `nullpen', fill with
+ the drawing pen; otherwise fill with pen `fillpen'. If
+ `drawpen' is `nullpen', draw the boundary with `fillpen';
+ otherwise with `drawpen'. An optional margin of `xmargin' and
+ `ymargin' can be specified.
+
+ `Fill'
+ Fill the interior.
+
+ `Fill(real xmargin=0, real ymargin=xmargin, pen p=nullpen)'
+ If `p' is `nullpen', fill with the drawing pen; otherwise
+ fill with pen `p'. An optional margin of `xmargin' and
+ `ymargin' can be specified.
+
+ `NoFill'
+ Do not fill.
+
+ `Draw'
+ Draw only the boundary.
+
+ `Draw(real xmargin=0, real ymargin=xmargin, pen p=nullpen)'
+ If `p' is `nullpen', draw the boundary with the drawing pen;
+ otherwise draw with pen `p'. An optional margin of `xmargin'
+ and `ymargin' can be specified.
+
+ `UnFill'
+ Clip the region.
+
+ `UnFill(real xmargin=0, real ymargin=xmargin)'
+ Clip the region and surrounding margins `xmargin' and
+ `ymargin'.
+
+ `RadialShade(pen penc, pen penr)'
+ Fill varying radially from `penc' at the center of the
+ bounding box to `penr' at the edge.
+
+ `RadialShadeDraw(real xmargin=0, real ymargin=xmargin, pen penc,'
+ `pen penr, pen drawpen=nullpen)' Fill with RadialShade and
+ draw the boundary.
+
+
+ For example, to draw a bounding box around a picture with a 0.25 cm
+ margin and output the resulting frame, use the command: shipout(bbox(0.25cm));
+ A `picture' may be fit to a frame with the background color pen
+ `p', using the function `bbox(p,Fill)'.
+
+ The functions pair min(picture pic, user=false);
+ pair max(picture pic, user=false);
+ pair size(picture pic, user=false);
+ calculate the bounds that picture `pic' would have if it were
+ currently fit to a frame using its default size specification. If
+ `user' is `false' the returned value is in `PostScript'
+ coordinates, otherwise it is in user coordinates.
+
+ The function pair point(picture pic=currentpicture, pair dir, bool user=true);
+ is a convenient way of determining the point on the bounding box
+ of `pic' in the direction `dir' relative to its center, ignoring
+ the contributions from fixed-size objects (such as labels and
+ arrowheads). If `user' is `true' the returned value is in user
+ coordinates, otherwise it is in `PostScript' coordinates.
+
+ The function pair truepoint(picture pic=currentpicture, pair dir, bool user=true);
+ is identical to `point', except that it also accounts for
+ fixed-size objects, using the scaling transform that picture `pic'
+ would have if currently fit to a frame using its default size
+ specification. If `user' is `true' the returned value is in user
+ coordinates, otherwise it is in `PostScript' coordinates.
+
+ Sometimes it is useful to draw objects on separate pictures and
+ add one picture to another using the `add' function: void add(picture src, bool group=true,
+ filltype filltype=NoFill, bool above=true);
+ void add(picture dest, picture src, bool group=true,
+ filltype filltype=NoFill, bool above=true);
+ The first example adds `src' to `currentpicture'; the second one
+ adds `src' to `dest'. The `group' option specifies whether or not
+ the graphical user interface `xasy' should treat all of the
+ elements of `src' as a single entity (*note GUI::), `filltype'
+ requests optional background filling or clipping, and `above'
+ specifies whether to add `src' above or below existing objects.
+
+ There are also routines to add a picture or frame `src' specified
+ in postscript coordinates to another picture `dest' (or
+ `currentpicture') about the user coordinate `position': void add(picture src, pair position, bool group=true,
+ filltype filltype=NoFill, bool above=true);
+ void add(picture dest, picture src, pair position,
+ bool group=true, filltype filltype=NoFill, bool above=true);
+ void add(picture dest=currentpicture, frame src, pair position=0,
+ bool group=true, filltype filltype=NoFill, bool above=true);
+ void add(picture dest=currentpicture, frame src, pair position,
+ pair align, bool group=true, filltype filltype=NoFill,
+ bool above=true);
+
+ The optional `align' argument in the last form specifies a
+ direction to use for aligning the frame, in a manner analogous to
+ the `align' argument of `label' (*note label::). However, one key
+ difference is that when `align' is not specified, labels are
+ centered, whereas frames and pictures are aligned so that their
+ origin is at `position'. Illustrations of frame alignment can be
+ found in the examples *note errorbars:: and *note image::. If you
+ want to align three or more subpictures, group them two at a time:
+
+ picture pic1;
+ real size=50;
+ size(pic1,size);
+ fill(pic1,(0,0)--(50,100)--(100,0)--cycle,red);
+
+ picture pic2;
+ size(pic2,size);
+ fill(pic2,unitcircle,green);
+
+ picture pic3;
+ size(pic3,size);
+ fill(pic3,unitsquare,blue);
+
+ picture pic;
+ add(pic,pic1.fit(),(0,0),N);
+ add(pic,pic2.fit(),(0,0),10S);
+
+ add(pic.fit(),(0,0),N);
+ add(pic3.fit(),(0,0),10S);
+
+
+
+ Alternatively, one can use `attach' to automatically increase the
+ size of picture `dest' to accommodate adding a frame `src' about
+ the user coordinate `position': void attach(picture dest=currentpicture, frame src,
+ pair position=0, bool group=true,
+ filltype filltype=NoFill, bool above=true);
+ void attach(picture dest=currentpicture, frame src,
+ pair position, pair align, bool group=true,
+ filltype filltype=NoFill, bool above=true);
+
+ To erase the contents of a picture (but not the size
+ specification), use the function void erase(picture pic=currentpicture);
+
+ To save a snapshot of `currentpicture', `currentpen', and
+ `currentprojection', use the function `save()'.
+
+ To restore a snapshot of `currentpicture', `currentpen', and
+ `currentprojection', use the function `restore()'.
+
+ Many further examples of picture and frame operations are provided
+ in the base module `plain'.
+
+ It is possible to insert verbatim `PostScript' commands in a
+ picture with one of the routines void postscript(picture pic=currentpicture, string s);
+ void postscript(picture pic=currentpicture, string s, pair min,
+ pair max)
+ Here `min' and `max' can be used to specify explicit bounds
+ associated with the resulting `PostScript' code.
+
+ Verbatim TeX commands can be inserted in the intermediate `LaTeX'
+ output file with one of the functions void tex(picture pic=currentpicture, string s);
+ void tex(picture pic=currentpicture, string s, pair min, pair max)
+ Here `min' and `max' can be used to specify explicit bounds
+ associated with the resulting TeX code.
+
+ To issue a global TeX command (such as a TeX macro definition) in
+ the TeX preamble (valid for the remainder of the top-level module)
+ use: void texpreamble(string s);
+
+ The TeX environment can be reset to its initial state, clearing all
+ macro definitions, with the function void texreset();
+
+ The routine void usepackage(string s, string options="");
+ provides a convenient abbreviation for texpreamble("\usepackage["+options+"]{"+s+"}");
+ that can be used for importing `LaTeX' packages.
+
+
+
+File: asymptote.info, Node: Files, Next: Variable initializers, Prev: Frames and pictures, Up: Programming
+
+6.6 Files
+=========
+
+`Asymptote' can read and write text files (including comma-separated
+value) files and portable XDR (External Data Representation) binary
+files.
+
+ An input file must first be opened with
+input(string name="", bool check=true, string comment="#", string mode="");
+ reading is then done by assignment:
+file fin=input("test.txt");
+real a=fin;
+
+ If the optional boolean argument `check' is `false', no check will
+be made that the file exists. If the file does not exist or is not
+readable, the function `bool error(file)' will return `true'. The
+first character of the string `comment' specifies a comment character.
+If this character is encountered in a data file, the remainder of the
+line is ignored. When reading strings, a comment character followed
+immediately by another comment character is treated as a single literal
+comment character.
+
+ One can change the current working directory for read operations to
+the contents of the string `s' with the function `string cd(string s)',
+which returns the new working directory. If `string s' is empty, the
+path is reset to the value it had at program startup.
+
+ When reading pairs, the enclosing parenthesis are optional. Strings
+are also read by assignment, by reading characters up to but not
+including a newline. In addition, `Asymptote' provides the function
+`string getc(file)' to read the next character (treating the comment
+character as an ordinary character) and return it as a string.
+
+ A file named `name' can be open for output with
+file output(string name="", bool update=false, string comment="#", string mode="");
+ If `update=false', any existing data in the file will be erased and
+only write operations can be used on the file. If `update=true', any
+existing data will be preserved, the position will be set to the
+end-of-file, and both reading and writing operations will be enabled.
+For security reasons, writing to files in directories other than the
+current directory is allowed only if the `-globalwrite' (or `-nosafe')
+command-line option is specified. The function `string mktemp(string
+s)' may be used to create and return the name of a unique temporary
+file in the current directory based on the string `s'.
+
+ There are two special files: `stdin', which reads from the keyboard,
+and `stdout', which writes to the terminal. The implicit initializer
+for files is `null'.
+
+ Data of a built-in type `T' can be written to an output file by
+calling one of the functions
+write(string s="", T x, suffix suffix=endl ... T[]);
+write(file file, string s="", T x, suffix suffix=none ... T[]);
+write(file file=stdout, string s="", explicit T[] x ... T[][]);
+write(file file=stdout, T[][]);
+write(file file=stdout, T[][][]);
+write(suffix suffix=endl);
+write(file file, suffix suffix=none);
+ If `file' is not specified, `stdout' is used and terminated by default
+with a newline. If specified, the optional identifying string `s' is
+written before the data `x'. An arbitrary number of data values may be
+listed when writing scalars or one-dimensional arrays. The `suffix' may
+be one of the following: `none' (do nothing), `flush' (output buffered
+data), `endl' (terminate with a newline and flush), `newl' (terminate
+with a newline), `DOSendl' (terminate with a DOS newline and flush),
+`DOSnewl' (terminate with a DOS newline), `tab' (terminate with a tab),
+or `comma' (terminate with a comma). Here are some simple examples of
+data output:
+file fout=output("test.txt");
+write(fout,1); // Writes "1"
+write(fout); // Writes a new line
+write(fout,"List: ",1,2,3); // Writes "List: 1 2 3"
+ A file may be opened with `mode="xdr"', to read or write double
+precision (64-bit) reals and single precision (32-bit) integers in Sun
+Microsystem's XDR (External Data Representation) portable binary format
+(available on all `UNIX' platforms). Alternatively, a file may also be
+opened with `mode="binary"' to read or write double precision reals and
+single precision integers in the native (nonportable) machine binary
+format. The virtual member functions `file singlereal(bool b=true)'
+and `file singleint(bool b=true)' be used to change the precision of
+real and integer I/O operations, respectively, for an XDR or binary
+file `f'. Similarly, the function `file signedint(bool b=true)' can be
+used to modify the signedness of integer reads and writes for an XDR or
+binary file `f'.
+
+ The virtual members `name', `mode', `singlereal', `singleint', and
+`signedint' may be used to query the respective parameters for a given
+file.
+
+ One can test a file for end-of-file with the boolean function
+`eof(file)', end-of-line with `eol(file)', and for I/O errors with
+`error(file)'. One can flush the output buffers with `flush(file)',
+clear a previous I/O error with `clear(file)', and close the file with
+`close(file)'. The function `int precision(file file=stdout, int
+digits=0)' sets the number of digits of output precision for `file' to
+`digits', provided `digits' is nonzero, and returns the previous
+precision setting. The function `int tell(file)' returns the current
+position in a file relative to the beginning. The routine `seek(file
+file, int pos)' can be used to change this position, where a negative
+value for the position `pos' is interpreted as relative to the
+end-of-file. For example, one can rewind a file `file' with the command
+`seek(file,0)' and position to the final character in the file with
+`seek(file,-1)'. The command `seekeof(file)' sets the position to the
+end of the file.
+
+ Assigning `settings.scroll=n' for a positive integer `n' requests a
+pause after every `n' output lines to `stdout'. One may then press
+`Enter' to continue to the next `n' output lines, `s' followed by
+`Enter' to scroll without further interruption, or `q' followed by
+`Enter' to quit the current output operation. If `n' is negative, the
+output scrolls a page at a time (i.e. by one less than the current
+number of display lines). The default value, `settings.scroll=0',
+specifies continuous scrolling.
+
+ The routines
+string getstring(string name="", string default="", string prompt="",
+ bool store=true);
+int getint(string name="", int default=0, string prompt="",
+ bool store=true);
+real getreal(string name="", real default=0, string prompt="",
+ bool store=true);
+pair getpair(string name="", pair default=0, string prompt="",
+ bool store=true);
+triple gettriple(string name="", triple default=(0,0,0), string prompt="",
+ bool store=true);
+ defined in the module `plain' may be used to prompt for a value from
+`stdin' using the GNU `readline' library. If `store=true', the history
+of values for `name' is stored in the file `".asy_history_"+name'
+(*note history::). The most recent value in the history will be used to
+provide a default value for subsequent runs. The default value
+(initially `default') is displayed after `prompt'. These functions are
+based on the internal routines
+string readline(string prompt="", string name="", bool tabcompletion=false);
+void saveline(string name, string value, bool store=true);
+ Here, `readline' prompts the user with the default value formatted
+according to `prompt', while `saveline' is used to save the string
+`value' in a local history named `name', optionally storing the local
+history in a file `".asy_history_"+name'.
+
+ The routine `history(string name, int n=1)' can be used to look up
+the `n' most recent values (or all values up to `historylines' if
+`n=0') entered for string `name'. The routine `history(int n=0)'
+returns the interactive history. For example,
+write(output("transcript.asy"),history());
+ outputs the interactive history to the file `transcript.asy'.
+
+ The function `int delete(string s)' deletes the file named by the
+string `s'. Unless the `-globalwrite' (or `-nosafe') option is enabled,
+the file must reside in the current directory. The function `int
+rename(string from, string to)' may be used to rename file `from' to
+file `to'. Unless the `-globalwrite' (or `-nosafe') option is enabled,
+this operation is restricted to the current directory. The functions
+int convert(string args="", string file="", string format="");
+int animate(string args="", string file="", string format="");
+ call the `ImageMagick' commands `convert' and `animate', respectively,
+with the arguments `args' and the file name constructed from the
+strings `file' and `format'.
+
+
+File: asymptote.info, Node: Variable initializers, Next: Structures, Prev: Files, Up: Programming
+
+6.7 Variable initializers
+=========================
+
+A variable can be assigned a value when it is declared, as in `int
+x=3;' where the variable `x' is assigned the value `3'. As well as
+literal constants such as `3', arbitary expressions can be used as
+initializers, as in `real x=2*sin(pi/2);'.
+
+ A variable is not added to the namespace until after the initializer
+is evaluated, so for example, in
+int x=2;
+int x=5*x;
+ the `x' in the initializer on the second line refers to the variable
+`x' declared on the first line. The second line, then, declares a
+variable `x' shadowing the original `x' and initializes it to the value
+`10'.
+
+ Variables of most types can be declared without an explicit
+initializer and they will be initialized by the default initializer of
+that type:
+
+ * Variables of the numeric types `int', `real', and `pair' are all
+ initialized to zero; variables of type `triple' are initialized to
+ `O=(0,0,0)'.
+
+ * `boolean' variables are initialized to `false'.
+
+ * `string' variables are initialized to the empty string.
+
+ * `transform' variables are initialized to the identity
+ transformation.
+
+ * `path' and `guide' variables are initialized to `nullpath'.
+
+ * `pen' variables are initialized to the default pen.
+
+ * `frame' and `picture' variables are initialized to empty frames
+ and pictures, respectively.
+
+ * `file' variables are initialized to `null'.
+
+ The default initializers for user-defined array, structure, and
+function types are explained in their respective sections. Some types,
+such as `code', do not have default initializers. When a variable of
+such a type is introduced, the user must initialize it by explicitly
+giving it a value.
+
+ The default initializer for any type `T' can be redeclared by
+defining the function `T operator init()'. For instance, `int'
+variables are usually initialized to zero, but in
+int operator init() {
+ return 3;
+}
+int y;
+
+the variable `y' is initialized to `3'. This example was given for
+illustrative purposes; redeclaring the initializers of built-in types
+is not recommended. Typically, `operator init' is used to define
+sensible defaults for user-defined types.
+
+ The special type `var' may be used to infer the type of a variable
+from its initializer. If the initializer is an expression of a unique
+type, then the variable will be defined with that type. For instance,
+var x=5;
+var y=4.3;
+var reddash=red+dashed;
+ is equivalent to
+int x=5;
+real y=4.3;
+pen reddash=red+dashed;
+
+ `var' may also be used with the extended `for' loop syntax.
+
+int[] a = {1,2,3};
+for (var x : a)
+ write(x);
+
+
+File: asymptote.info, Node: Structures, Next: Operators, Prev: Variable initializers, Up: Programming
+
+6.8 Structures
+==============
+
+Users may also define their own data types as structures, along with
+user-defined operators, much as in C++. By default, structure members
+are `public' (may be read and modified anywhere in the code), but may be
+optionally declared `restricted' (readable anywhere but writeable only
+inside the structure where they are defined) or `private' (readable and
+writable only inside the structure). In a structure definition, the
+keyword `this' can be used as an expression to refer to the enclosing
+structure. Any code at the top-level scope within the structure is
+executed on initialization.
+
+ Variables hold references to structures. That is, in the example:
+struct T {
+ int x;
+}
+
+T foo;
+T bar=foo;
+bar.x=5;
+
+ The variable `foo' holds a reference to an instance of the structure
+`T'. When `bar' is assigned the value of `foo', it too now holds a
+reference to the same instance as `foo' does. The assignment `bar.x=5'
+changes the value of the field `x' in that instance, so that `foo.x'
+will also be equal to `5'.
+
+ The expression `new T' creates a new instance of the structure `T'
+and returns a reference to that instance. In creating the new
+instance, any code in the body of the record definition is executed.
+For example:
+int Tcount=0;
+struct T {
+ int x;
+ ++Tcount;
+}
+
+T foo;
+
+ Here, the expression `new T' will produce a new instance of the
+class, but will also cause `Tcount' to be incremented, so that it keeps
+track of the number of instances produced.
+
+ The expression `null' can be cast to any structure type to yield a
+null reference, a reference that does not actually refer to any
+instance of the structure. Trying to use a field of a null reference
+will cause an error.
+
+ The function `bool alias(T,T)' checks to see if two structure
+references refer to the same instance of the structure (or both to
+`null'). For example, in the example code at the start of the section,
+`alias(foo,bar)' would return true, but `alias(foo,new T)' would return
+false, as `new T' creates a new instance of the structure `T'. The
+boolean operators `==' and `!=' are by default equivalent to `alias' and
+`!alias' respectively, but may be overwritten for a particular type
+(for example, to do a deep comparison).
+
+ After the definition of a structure `T', a variable of type `T' is
+initialized to a new instance (`new T') by default. During the
+definition of the structure, however, variables of type `T' are
+initialized to `null' by default. This special behaviour is to avoid
+infinite recursion of creating new instances in code such as
+struct tree {
+ int value;
+ tree left;
+ tree right;
+}
+
+ Here is a simple example that illustrates the use of structures:
+struct S {
+ real a=1;
+ real f(real a) {return a+this.a;}
+}
+
+S s; // Initializes s with new S;
+
+write(s.f(2)); // Outputs 3
+
+S operator + (S s1, S s2)
+{
+ S result;
+ result.a=s1.a+s2.a;
+ return result;
+}
+
+write((s+s).f(0)); // Outputs 2
+
+ It is often convenient to have functions that construct new
+instances of a structure. Say we have a `Person' structure:
+struct Person {
+ string firstname;
+ string lastname;
+}
+
+Person joe;
+joe.firstname="Joe";
+joe.lastname="Jones";
+ Creating a new Person is a chore; it takes three lines to create a new
+instance and to initialize its fields (that's still considerably less
+effort than creating a new person in real life, though).
+
+ We can reduce the work by defining a constructor function
+`Person(string,string)':
+struct Person {
+ string firstname;
+ string lastname;
+
+ static Person Person(string firstname, string lastname) {
+ Person p;
+ p.firstname=firstname;
+ p.lastname=lastname;
+ return p;
+ }
+}
+
+Person joe=Person.Person("Joe", "Jones");
+
+ While it is now easier than before to create a new instance, we still
+have to refer to the constructor by the qualified name `Person.Person'.
+If we add the line
+from Person unravel Person;
+ immediately after the structure definition, then the constructor can
+be used without qualification: `Person joe=Person("Joe", "Jones");'.
+
+ The constructor is now easy to use, but it is quite a hassle to
+define. If you write a lot of constructors, you will find that you are
+repeating a lot of code in each of them. Fortunately, your friendly
+neighbourhood Asymptote developers have devised a way to automate much
+of the process.
+
+ If, in the body of a structure, Asymptote encounters the definition
+of a function of the form `void operator init(ARGS)', it implicitly
+defines a constructor function of the arguments `ARGS' that uses the
+`void operator init' function to initialize a new instance of the
+structure. That is, it essentially defines the following constructor
+(assuming the structure is called `Foo'):
+
+ static Foo Foo(ARGS) {
+ Foo instance;
+ instance.operator init(ARGS);
+ return instance;
+ }
+
+ This constructor is also implicitly copied to the enclosing scope
+after the end of the structure definition, so that it can used
+subsequently without qualifying it by the structure name. Our `Person'
+example can thus be implemented as:
+struct Person {
+ string firstname;
+ string lastname;
+
+ void operator init(string firstname, string lastname) {
+ this.firstname=firstname;
+ this.lastname=lastname;
+ }
+}
+
+Person joe=Person("Joe", "Jones");
+
+ The use of `operator init' to implicitly define constructors should
+not be confused with its use to define default values for variables
+(*note Variable initializers::). Indeed, in the first case, the return
+type of the `operator init' must be `void' while in the second, it must
+be the (non-`void') type of the variable.
+
+ The function `cputime()' returns a structure `cputime' with
+cumulative CPU times broken down into the fields `parent.user',
+`parent.system', `child.user', and `child.system'. For convenience, the
+incremental fields `change.user' and `change.system' indicate the
+change in the corresponding total parent and child CPU times since the
+last call to `cputime()'. The function
+void write(file file=stdout, string s="", cputime c,
+ string format=cputimeformat, suffix suffix=none);
+ displays the incremental user cputime followed by "u", the incremental
+system cputime followed by "s", the total user cputime followed by "U",
+and the total system cputime followed by "S".
+
+ Much like in C++, casting (*note Casts::) provides for an elegant
+implementation of structure inheritance, including virtual functions:
+struct parent {
+ real x;
+ void operator init(int x) {this.x=x;}
+ void virtual(int) {write(0);}
+ void f() {virtual(1);}
+}
+
+void write(parent p) {write(p.x);}
+
+struct child {
+ parent parent;
+ real y=3;
+ void operator init(int x) {parent.operator init(x);}
+ void virtual(int x) {write(x);}
+ parent.virtual=virtual;
+ void f()=parent.f;
+}
+
+parent operator cast(child child) {return child.parent;}
+
+parent p=parent(1);
+child c=child(2);
+
+write(c); // Outputs 2;
+
+p.f(); // Outputs 0;
+c.f(); // Outputs 1;
+
+write(c.parent.x); // Outputs 2;
+write(c.y); // Outputs 3;
+
+ For further examples of structures, see `Legend' and `picture' in
+the `Asymptote' base module `plain'.
+
+
+File: asymptote.info, Node: Operators, Next: Implicit scaling, Prev: Structures, Up: Programming
+
+6.9 Operators
+=============
+
+* Menu:
+
+* Arithmetic & logical:: Basic mathematical operators
+* Self & prefix operators:: Increment and decrement
+* User-defined operators:: Overloading operators
+
+
+File: asymptote.info, Node: Arithmetic & logical, Next: Self & prefix operators, Up: Operators
+
+6.9.1 Arithmetic & logical operators
+------------------------------------
+
+`Asymptote' uses the standard binary arithmetic operators. However,
+when one integer is divided by another, both arguments are converted to
+real values before dividing and a real quotient is returned (since this
+is usually what is intended). The function `int quotient(int x, int y)'
+returns the greatest integer less than or equal to `x/y'. In all other
+cases both operands are promoted to the same type, which will also be
+the type of the result:
+`+'
+ addition
+
+`-'
+ subtraction
+
+`*'
+ multiplication
+
+`/'
+ division
+
+`%'
+ modulo; the result always has the same sign as the divisor. In
+ particular, this makes `q*quotient(p,q)+p%q == p' for all integers
+ `p' and nonzero integers `q'.
+
+`^'
+ power; if the exponent (second argument) is an int, recursive
+ multiplication is used; otherwise, logarithms and exponentials are
+ used (`**' is a synonym for `^').
+
+
+ The usual boolean operators are also defined:
+`=='
+ equals
+
+`!='
+ not equals
+
+`<'
+ less than
+
+`<='
+ less than or equals
+
+`>='
+ greater than or equals
+
+`>'
+ greater than
+
+`&&'
+ and (with conditional evaluation of right-hand argument)
+
+`&'
+ and
+
+`||'
+ or (with conditional evaluation of right-hand argument)
+
+`|'
+ or
+
+`^'
+ xor
+
+`!'
+ not
+
+ `Asymptote' also supports the C-like conditional syntax:
+bool positive=(pi > 0) ? true : false;
+
+ The function `T interp(T a, T b, real t)' returns `(1-t)*a+t*b' for
+nonintegral built-in arithmetic types `T'. If `a' and `b' are pens,
+they are first promoted to the same color space.
+
+ `Asymptote' also defines bitwise functions `int AND(int,int)', `int
+OR(int,int)', `int XOR(int,int)', `int NOT(int)', `int CLZ(int)' (count
+leading zeros), and `int CTZ(int)' (count trailing zeros).
+
+
+File: asymptote.info, Node: Self & prefix operators, Next: User-defined operators, Prev: Arithmetic & logical, Up: Operators
+
+6.9.2 Self & prefix operators
+-----------------------------
+
+As in C, each of the arithmetic operators `+', `-', `*', `/', `%', and
+`^' can be used as a self operator. The prefix operators `++'
+(increment by one) and `--' (decrement by one) are also defined. For
+example,
+int i=1;
+i += 2;
+int j=++i;
+
+is equivalent to the code
+int i=1;
+i=i+2;
+int j=i=i+1;
+
+ However, postfix operators like `i++' and `i--' are not defined
+(because of the inherent ambiguities that would arise with the `--'
+path-joining operator). In the rare instances where `i++' and `i--' are
+really needed, one can substitute the expressions `(++i-1)' and
+`(--i+1)', respectively.
+
+
+File: asymptote.info, Node: User-defined operators, Prev: Self & prefix operators, Up: Operators
+
+6.9.3 User-defined operators
+----------------------------
+
+The following symbols may be used with `operator' to define or redefine
+operators on structures and built-in types:
+- + * / % ^ ! < > == != <= >= & | ^^ .. :: -- --- ++
+<< >> $ $$ @ @@
+ The operators on the second line have precedence one higher than the
+boolean operators `<', `>', `<=', and `>='.
+
+ Guide operators like `..' may be overloaded, say, to write a user
+function that produces a new guide from a given guide:
+guide dots(... guide[] g)=operator ..;
+
+guide operator ..(... guide[] g) {
+ guide G;
+ if(g.length > 0) {
+ write(g[0]);
+ G=g[0];
+ }
+ for(int i=1; i < g.length; ++i) {
+ write(g[i]);
+ write();
+ G=dots(G,g[i]);
+ }
+ return G;
+}
+
+guide g=(0,0){up}..{SW}(100,100){NE}..{curl 3}(50,50)..(10,10);
+write("g=",g);
+
+
+File: asymptote.info, Node: Implicit scaling, Next: Functions, Prev: Operators, Up: Programming
+
+6.10 Implicit scaling
+=====================
+
+If a numeric literal is in front of certain types of expressions, then
+the two are multiplied:
+int x=2;
+real y=2.0;
+real cm=72/2.540005;
+
+write(3x);
+write(2.5x);
+write(3y);
+write(-1.602e-19 y);
+write(0.5(x,y));
+write(2x^2);
+write(3x+2y);
+write(3(x+2y));
+write(3sin(x));
+write(3(sin(x))^2);
+write(10cm);
+
+ This produces the output
+6
+5
+6
+-3.204e-19
+(1,1)
+8
+10
+18
+2.72789228047704
+2.48046543129542
+283.464008929116
+
+
+File: asymptote.info, Node: Functions, Next: Arrays, Prev: Implicit scaling, Up: Programming
+
+6.11 Functions
+==============
+
+`Asymptote' functions are treated as variables with a signature
+(non-function variables have null signatures). Variables with the same
+name are allowed, so long as they have distinct signatures.
+
+ Functions arguments are passed by value. To pass an argument by
+reference, simply enclose it in a structure (*note Structures::).
+
+ Here are some significant features of `Asymptote' functions:
+
+ 1. Variables with signatures (functions) and without signatures
+ (nonfunction variables) are distinct: int x, x();
+ x=5;
+ x=new int() {return 17;};
+ x=x(); // calls x() and puts the result, 17, in the scalar x
+
+ 2. Traditional function definitions are allowed: int sqr(int x)
+ {
+ return x*x;
+ }
+ sqr=null; // but the function is still just a variable.
+
+ 3. Casting can be used to resolve ambiguities: int a, a(), b, b(); // Valid: creates four variables.
+ a=b; // Invalid: assignment is ambiguous.
+ a=(int) b; // Valid: resolves ambiguity.
+ (int) (a=b); // Valid: resolves ambiguity.
+ (int) a=b; // Invalid: cast expressions cannot be L-values.
+
+ int c();
+ c=a; // Valid: only one possible assignment.
+
+ 4. Anonymous (so-called "high-order") functions are also allowed: typedef int intop(int);
+ intop adder(int m)
+ {
+ return new int(int n) {return m+n;};
+ }
+ intop addby7=adder(7);
+ write(addby7(1)); // Writes 8.
+
+ 5. One may redefine a function `f', even for calls to `f' in
+ previously declared functions, by assigning another (anonymous or
+ named) function to it. However, if `f' is overloaded by a new
+ function definition, previous calls will still access the original
+ version of `f', as illustrated in this example: void f() {
+ write("hi");
+ }
+
+ void g() {
+ f();
+ }
+
+ g(); // writes "hi"
+
+ f=new void() {write("bye");};
+
+ g(); // writes "bye"
+
+ void f() {write("overloaded");};
+
+ f(); // writes "overloaded"
+ g(); // writes "bye"
+
+ 6. Anonymous functions can be used to redefine a function variable
+ that has been declared (and implicitly initialized to the null
+ function) but not yet explicitly defined: void f(bool b);
+
+ void g(bool b) {
+ if(b) f(b);
+ else write(b);
+ }
+
+ f=new void(bool b) {
+ write(b);
+ g(false);
+ };
+
+ g(true); // Writes true, then writes false.
+
+
+ `Asymptote' is the only language we know of that treats functions as
+variables, but allows overloading by distinguishing variables based on
+their signatures.
+
+ Functions are allowed to call themselves recursively. As in C++,
+infinite nested recursion will generate a stack overflow (reported as a
+segmentation fault, unless a fully working version of the GNU library
+`libsigsegv' (e.g. 2.4 or later) is installed at configuration time).
+
+* Menu:
+
+* Default arguments:: Default values can appear anywhere
+* Named arguments:: Assigning function arguments by keyword
+* Rest arguments:: Functions with a variable number of arguments
+* Mathematical functions:: Standard libm functions
+
+
+File: asymptote.info, Node: Default arguments, Next: Named arguments, Up: Functions
+
+6.11.1 Default arguments
+------------------------
+
+`Asymptote' supports a more flexible mechanism for default function
+arguments than C++: they may appear anywhere in the function prototype.
+Because certain data types are implicitly cast to more sophisticated
+types (*note Casts::) one can often avoid ambiguities by ordering
+function arguments from the simplest to the most complicated. For
+example, given
+real f(int a=1, real b=0) {return a+b;}
+ then `f(1)' returns 1.0, but `f(1.0)' returns 2.0.
+
+ The value of a default argument is determined by evaluating the
+given `Asymptote' expression in the scope where the called function is
+defined.
+
+
+File: asymptote.info, Node: Named arguments, Next: Rest arguments, Prev: Default arguments, Up: Functions
+
+6.11.2 Named arguments
+----------------------
+
+It is sometimes difficult to remember the order in which arguments
+appear in a function declaration. Named (keyword) arguments make calling
+functions with multiple arguments easier. Unlike in the C and C++
+languages, an assignment in a function argument is interpreted as an
+assignment to a parameter of the same name in the function signature,
+_not within the local scope_. The command-line option `-d' may be used
+to check `Asymptote' code for cases where a named argument may be
+mistaken for a local assignment.
+
+ When matching arguments to signatures, first all of the keywords are
+matched, then the arguments without names are matched against the
+unmatched formals as usual. For example,
+int f(int x, int y) {
+ return 10x+y;
+}
+write(f(4,x=3));
+ outputs 34, as `x' is already matched when we try to match the unnamed
+argument `4', so it gets matched to the next item, `y'.
+
+ For the rare occasions where it is desirable to assign a value to
+local variable within a function argument (generally _not_ a good
+programming practice), simply enclose the assignment in parentheses.
+For example, given the definition of `f' in the previous example,
+int x;
+write(f(4,(x=3)));
+ is equivalent to the statements
+int x;
+x=3;
+write(f(4,3));
+ and outputs 43.
+
+ Parameters can be specified as "keyword-only" by putting `keyword'
+immediately before the parameter name, as in `int f(int keyword x)' or
+`int f(int keyword x=77)'. This forces the caller of the function to
+use a named argument to give a value for this parameter. That is,
+`f(x=42)' is legal, but `f(25)' is not. Keyword-only parameters must
+be listed after normal parameters in a function definition.
+
+ As a technical detail, we point out that, since variables of the same
+name but different signatures are allowed in the same scope, the code
+int f(int x, int x()) {
+ return x+x();
+}
+int seven() {return 7;}
+ is legal in `Asymptote', with `f(2,seven)' returning 9. A named
+argument matches the first unmatched formal of the same name, so
+`f(x=2,x=seven)' is an equivalent call, but `f(x=seven,2)' is not, as
+the first argument is matched to the first formal, and `int ()' cannot
+be implicitly cast to `int'. Default arguments do not affect which
+formal a named argument is matched to, so if `f' were defined as
+int f(int x=3, int x()) {
+ return x+x();
+}
+ then `f(x=seven)' would be illegal, even though `f(seven)' obviously
+would be allowed.
+
+
+File: asymptote.info, Node: Rest arguments, Next: Mathematical functions, Prev: Named arguments, Up: Functions
+
+6.11.3 Rest arguments
+---------------------
+
+Rest arguments allow one to write functions that take a variable number
+of arguments:
+// This function sums its arguments.
+int sum(... int[] nums) {
+ int total=0;
+ for(int i=0; i < nums.length; ++i)
+ total += nums[i];
+ return total;
+}
+
+sum(1,2,3,4); // returns 10
+sum(); // returns 0
+
+// This function subtracts subsequent arguments from the first.
+int subtract(int start ... int[] subs) {
+ for(int i=0; i < subs.length; ++i)
+ start -= subs[i];
+ return start;
+}
+
+subtract(10,1,2); // returns 7
+subtract(10); // returns 10
+subtract(); // illegal
+
+ Putting an argument into a rest array is called _packing_. One can
+give an explicit list of arguments for the rest argument, so `subtract'
+could alternatively be implemented as
+int subtract(int start ... int[] subs) {
+ return start - sum(... subs);
+}
+
+ One can even combine normal arguments with rest arguments:
+sum(1,2,3 ... new int[] {4,5,6}); // returns 21
+ This builds a new six-element array that is passed to `sum' as `nums'.
+The opposite operation, _unpacking_, is not allowed:
+subtract(... new int[] {10, 1, 2});
+ is illegal, as the start formal is not matched.
+
+ If no arguments are packed, then a zero-length array (as opposed to
+`null') is bound to the rest parameter. Note that default arguments are
+ignored for rest formals and the rest argument is not bound to a
+keyword.
+
+ In some cases, keyword-only parameters are helpful to avoid
+arguments intended for the rest parameter to be assigned to other
+parameters. For example, here the use of `keyword' is to avoid
+`pnorm(1.0,2.0,0.3)' matching `1.0' to `p'.
+real pnorm(real keyword p=2.0 ... real[] v)
+{
+ return sum(v^p)^(1/p);
+}
+
+ The overloading resolution in `Asymptote' is similar to the function
+matching rules used in C++. Every argument match is given a score.
+Exact matches score better than matches with casting, and matches with
+formals (regardless of casting) score better than packing an argument
+into the rest array. A candidate is maximal if all of the arguments
+score as well in it as with any other candidate. If there is one
+unique maximal candidate, it is chosen; otherwise, there is an
+ambiguity error.
+
+int f(path g);
+int f(guide g);
+f((0,0)--(100,100)); // matches the second; the argument is a guide
+
+int g(int x, real y);
+int g(real x, int x);
+
+g(3,4); // ambiguous; the first candidate is better for the first argument,
+ // but the second candidate is better for the second argument
+
+int h(... int[] rest);
+int h(real x ... int[] rest);
+
+h(1,2); // the second definition matches, even though there is a cast,
+ // because casting is preferred over packing
+
+int i(int x ... int[] rest);
+int i(real x, real y ... int[] rest);
+
+i(3,4); // ambiguous; the first candidate is better for the first argument,
+ // but the second candidate is better for the second one
+
+
+File: asymptote.info, Node: Mathematical functions, Prev: Rest arguments, Up: Functions
+
+6.11.4 Mathematical functions
+-----------------------------
+
+`Asymptote' has built-in versions of the standard `libm' mathematical
+real(real) functions `sin', `cos', `tan', `asin', `acos', `atan',
+`exp', `log', `pow10', `log10', `sinh', `cosh', `tanh', `asinh',
+`acosh', `atanh', `sqrt', `cbrt', `fabs', `expm1', `log1p', as well as
+the identity function `identity'. `Asymptote' also defines the order
+`n' Bessel functions of the first kind `Jn(int n, real)' and second kind
+`Yn(int n, real)', as well as the gamma function `gamma', the error
+function `erf', and the complementary error function `erfc'. The
+standard real(real, real) functions `atan2', `hypot', `fmod',
+`remainder' are also included.
+
+ The functions `degrees(real radians)' and `radians(real degrees)'
+can be used to convert between radians and degrees. The function
+`Degrees(real radians)' returns the angle in degrees in the interval
+[0,360). For convenience, `Asymptote' defines variants `Sin', `Cos',
+`Tan', `aSin', `aCos', and `aTan' of the standard trigonometric
+functions that use degrees rather than radians. We also define complex
+versions of the `sqrt', `sin', `cos', `exp', `log', and `gamma'
+functions.
+
+ The functions `floor', `ceil', and `round' differ from their usual
+definitions in that they all return an int value rather than a real
+(since that is normally what one wants). The functions `Floor',
+`Ceil', and `Round' are respectively similar, except that if the result
+cannot be converted to a valid int, they return `intMax' for positive
+arguments and `intMin' for negative arguments, rather than generating
+an integer overflow. We also define a function `sgn', which returns
+the sign of its real argument as an integer (-1, 0, or 1).
+
+ There is an `abs(int)' function, as well as an `abs(real)' function
+(equivalent to `fabs(real)'), an `abs(pair)' function (equivalent to
+`length(pair)').
+
+ Random numbers can be seeded with `srand(int)' and generated with
+the `int rand()' function, which returns a random integer between 0 and
+the integer `randMax'. The `unitrand()' function returns a random
+number uniformly distributed in the interval [0,1]. A Gaussian random
+number generator `Gaussrand' and a collection of statistics routines,
+including `histogram', are provided in the base file `stats.asy'. The
+functions `factorial(int n)', which returns n!, and `choose(int n, int
+k)', which returns n!/(k!(n-k)!), are also defined.
+
+ When configured with the GNU Scientific Library (GSL), available from
+`http://www.gnu.org/software/gsl/', `Asymptote' contains an internal
+module `gsl' that defines the airy functions `Ai(real)', `Bi(real)',
+`Ai_deriv(real)', `Bi_deriv(real)', `zero_Ai(int)', `zero_Bi(int)',
+`zero_Ai_deriv(int)', `zero_Bi_deriv(int)', the Bessel functions
+`I(int, real)', `K(int, real)', `j(int, real)', `y(int, real)',
+`i_scaled(int, real)', `k_scaled(int, real)', `J(real, real)', `Y(real,
+real)', `I(real, real)', `K(real, real)', `zero_J(real, int)', the
+elliptic functions `F(real, real)', `E(real, real)', and `P(real,
+real)', the Jacobi elliptic functions `real[] sncndn(real,real)', the
+exponential/trigonometric integrals `Ei', `Si', and `Ci', the Legendre
+polynomials `Pl(int, real)', and the Riemann zeta function
+`zeta(real)'. For example, to compute the sine integral `Si' of 1.0:
+import gsl;
+write(Si(1.0));
+
+ `Asymptote' also provides a few general purpose numerical routines:
+
+``real newton(int iterations=100, real f(real), real fprime(real), real x, bool verbose=false);''
+ Use Newton-Raphson iteration to solve for a root of a real-valued
+ differentiable function `f', given its derivative `fprime' and an
+ initial guess `x'. Diagnostics for each iteration are printed if
+ `verbose=true'. If the iteration fails after the maximum allowed
+ number of loops (`iterations'), `realMax' is returned.
+
+``real newton(int iterations=100, real f(real), real fprime(real), real x1, real x2, bool verbose=false);''
+ Use bracketed Newton-Raphson bisection to solve for a root of a
+ real-valued differentiable function `f' within an interval
+ [`x1',`x2'] (on which the endpoint values of `f' have opposite
+ signs), given its derivative `fprime'. Diagnostics for each
+ iteration are printed if `verbose=true'. If the iteration fails
+ after the maximum allowed number of loops (`iterations'),
+ `realMax' is returned.
+
+``real simpson(real f(real), real a, real b, real acc=realEpsilon, real dxmax=b-a)''
+ returns the integral of `f' from `a' to `b' using adaptive Simpson
+ integration.
+
+
+
+File: asymptote.info, Node: Arrays, Next: Casts, Prev: Functions, Up: Programming
+
+6.12 Arrays
+===========
+
+* Menu:
+
+* Slices:: Python-style array slices
+
+ Appending `[]' to a built-in or user-defined type yields an array.
+The array element `i' of an array `A' can be accessed as `A[i]'. By
+default, attempts to access or assign to an array element using a
+negative index generates an error. Reading an array element with an
+index beyond the length of the array also generates an error; however,
+assignment to an element beyond the length of the array causes the
+array to be resized to accommodate the new element. One can also index
+an array `A' with an integer array `B': the array `A[B]' is formed by
+indexing array `A' with successive elements of array `B'. A convenient
+Java-style shorthand exists for iterating over all elements of an
+array; see *note array iteration::.
+
+ The declaration
+real[] A;
+
+initializes `A' to be an empty (zero-length) array. Empty arrays should
+be distinguished from null arrays. If we say
+real[] A=null;
+
+then `A' cannot be dereferenced at all (null arrays have no length and
+cannot be read from or assigned to).
+
+ Arrays can be explicitly initialized like this:
+real[] A={0,1,2};
+
+ Array assignment in `Asymptote' does a shallow copy: only the
+pointer is copied (if one copy if modified, the other will be too).
+The `copy' function listed below provides a deep copy of an array.
+
+ Every array `A' of type `T[]' has the virtual members
+ * `int length',
+
+ * `int cyclic',
+
+ * `int[] keys',
+
+ * `T push(T x)',
+
+ * `void append(T[] a)',
+
+ * `T pop()',
+
+ * `void insert(int i ... T[] x)',
+
+ * `void delete(int i, int j=i)',
+
+ * `void delete()', and
+
+ * `bool initialized(int n)'.
+
+ The member `A.length' evaluates to the length of the array. Setting
+`A.cyclic=true' signifies that array indices should be reduced modulo
+the current array length. Reading from or writing to a nonempty cyclic
+array never leads to out-of-bounds errors or array resizing.
+
+ The member `A.keys' evaluates to an array of integers containing the
+indices of initialized entries in the array in ascending order. Hence,
+for an array of length `n' with all entries initialized, `A.keys'
+evaluates to `{0,1,...,n-1}'. A new keys array is produced each time
+`A.keys' is evaluated.
+
+ The functions `A.push' and `A.append' append their arguments onto
+the end of the array, while `A.insert(int i ... T[] x)' inserts `x'
+into the array at index `i'. For convenience `A.push' returns the
+pushed item. The function `A.pop()' pops and returns the last element,
+while `A.delete(int i, int j=i)' deletes elements with indices in the
+range [`i',`j'], shifting the position of all higher-indexed elements
+down. If no arguments are given, `A.delete()' provides a convenient way
+of deleting all elements of `A'. The routine `A.initialized(int n)' can
+be used to examine whether the element at index `n' is initialized.
+Like all `Asymptote' functions, `push', `append', `pop', `insert',
+`delete', and `initialized' can be "pulled off" of the array and used
+on their own. For example,
+int[] A={1};
+A.push(2); // A now contains {1,2}.
+A.append(A); // A now contains {1,2,1,2}.
+int f(int)=A.push;
+f(3); // A now contains {1,2,1,2,3}.
+int g()=A.pop;
+write(g()); // Outputs 3.
+A.delete(0); // A now contains {2,1,2}.
+A.delete(0,1); // A now contains {2}.
+A.insert(1,3); // A now contains {2,3}.
+A.insert(1 ... A); // A now contains {2,2,3,3}
+A.insert(2,4,5); // A now contains {2,2,4,5,3,3}.
+
+ The `[]' suffix can also appear after the variable name; this is
+sometimes convenient for declaring a list of variables and arrays of
+the same type:
+real a,A[];
+ This declares `a' to be `real' and implicitly declares `A' to be of
+type `real[]'.
+
+ In the following list of built-in array functions, `T' represents a
+generic type. Note that the internal functions `alias', `array',
+`copy', `concat', `sequence', `map', and `transpose', which depend on
+type `T[]', are defined only after the first declaration of a variable
+of type `T[]'.
+
+`new T[]'
+ returns a new empty array of type `T[]';
+
+`new T[] {list}'
+ returns a new array of type `T[]' initialized with `list' (a comma
+ delimited list of elements).
+
+`new T[n]'
+ returns a new array of `n' elements of type `T[]'. These `n'
+ array elements are not initialized unless they are arrays
+ themselves (in which case they are each initialized to empty
+ arrays).
+
+`T[] array(int n, T value, int depth=intMax)'
+ returns an array consisting of `n' copies of `value'. If `value'
+ is itself an array, a deep copy of `value' is made for each entry.
+ If `depth' is specified, this deep copying only recurses to the
+ specified number of levels.
+
+`int[] sequence(int n)'
+ if `n >= 1' returns the array `{0,1,...,n-1}' (otherwise returns a
+ null array);
+
+`int[] sequence(int n, int m)'
+ if `m >= n' returns an array `{n,n+1,...,m}' (otherwise returns a
+ null array);
+
+`T[] sequence(T f(int), int n)'
+ if `n >= 1' returns the sequence `{f_i :i=0,1,...n-1}' given a
+ function `T f(int)' and integer `int n' (otherwise returns a null
+ array);
+
+`T[] map(T f(T), T[] a)'
+ returns the array obtained by applying the function `f' to each
+ element of the array `a'. This is equivalent to `sequence(new
+ T(int i) {return f(a[i]);},a.length)'.
+
+`int[] reverse(int n)'
+ if `n >= 1' returns the array `{n-1,n-2,...,0}' (otherwise returns
+ a null array);
+
+`int[] complement(int[] a, int n)'
+ returns the complement of the integer array `a' in
+ `{0,1,2,...,n-1}', so that `b[complement(a,b.length)]' yields the
+ complement of `b[a]'.
+
+`real[] uniform(real a, real b, int n)'
+ if `n >= 1' returns a uniform partition of `[a,b]' into `n'
+ subintervals (otherwise returns a null array);
+
+`int find(bool[], int n=1)'
+ returns the index of the `n'th `true' value or -1 if not found.
+ If `n' is negative, search backwards from the end of the array for
+ the `-n'th value;
+
+`int search(T[] a, T key)'
+ For built-in ordered types `T', searches a sorted array `a' of `n'
+ elements for k, returning the index `i' if `a[i] <= key < a[i+1]',
+ `-1' if `key' is less than all elements of `a', or `n-1' if `key'
+ is greater than or equal to the last element of `a'.
+
+`int search(T[] a, T key, bool less(T i, T j))'
+ searches an array `a' sorted in ascending order such that element
+ `i' precedes element `j' if `less(i,j)' is true;
+
+`T[] copy(T[] a)'
+ returns a deep copy of the array `a';
+
+`T[] concat(... T[][] a)'
+ returns a new array formed by concatenating the given
+ one-dimensional arrays given as arguments;
+
+`bool alias(T[] a, T[] b)'
+ returns `true' if the arrays `a' and `b' are identical;
+
+`T[] sort(T[] a)'
+ For built-in ordered types `T', returns a copy of `a' sorted in
+ ascending order;
+
+`T[][] sort(T[][] a)'
+ For built-in ordered types `T', returns a copy of `a' with the rows
+ sorted by the first column, breaking ties with successively higher
+ columns. For example: string[][] a={{"bob","9"},{"alice","5"},{"pete","7"},
+ {"alice","4"}};
+ // Row sort (by column 0, using column 1 to break ties):
+ write(sort(a));
+
+ produces alice 4
+ alice 5
+ bob 9
+ pete 7
+
+`T[] sort(T[] a, bool less(T i, T j))'
+ returns a copy of `a' stably sorted in ascending order such that
+ element `i' precedes element `j' if `less(i,j)' is true.
+
+`T[][] transpose(T[][] a)'
+ returns the transpose of `a'.
+
+`T[][][] transpose(T[][][] a, int[] perm)'
+ returns the 3D transpose of `a' obtained by applying the
+ permutation `perm' of `new int[]{0,1,2}' to the indices of each
+ entry.
+
+`T sum(T[] a)'
+ For arithmetic types `T', returns the sum of `a'. In the case
+ where `T' is `bool', the number of true elements in `a' is
+ returned.
+
+`T min(T[] a)'
+
+`T min(T[][] a)'
+
+`T min(T[][][] a)'
+ For built-in ordered types `T', returns the minimum element of `a'.
+
+`T max(T[] a)'
+
+`T max(T[][] a)'
+
+`T max(T[][][] a)'
+ For built-in ordered types `T', returns the maximum element of `a'.
+
+`T[] min(T[] a, T[] b)'
+ For built-in ordered types `T', and arrays `a' and `b' of the same
+ length, returns an array composed of the minimum of the
+ corresponding elements of `a' and `b'.
+
+`T[] max(T[] a, T[] b)'
+ For built-in ordered types `T', and arrays `a' and `b' of the same
+ length, returns an array composed of the maximum of the
+ corresponding elements of `a' and `b'.
+
+`pair[] pairs(real[] x, real[] y);'
+ For arrays `x' and `y' of the same length, returns the pair array
+ `sequence(new pair(int i) {return (x[i],y[i]);},x.length)'.
+
+`pair[] fft(pair[] a, int sign=1)'
+ returns the Fast Fourier Transform of `a' (if the optional `FFTW'
+ package is installed), using the given `sign'. Here is a simple
+ example: int n=4;
+ pair[] f=sequence(n);
+ write(f);
+ pair[] g=fft(f,-1);
+ write();
+ write(g);
+ f=fft(g,1);
+ write();
+ write(f/n);
+
+`real dot(real[] a, real[] b)'
+ returns the dot product of the vectors `a' and `b'.
+
+`pair dot(pair[] a, pair[] b)'
+ returns the complex dot product `sum(a*conj(b))' of the vectors
+ `a' and `b'.
+
+`real[] tridiagonal(real[] a, real[] b, real[] c, real[] f);'
+ Solve the periodic tridiagonal problem L`x'=`f' and return the
+ solution `x', where `f' is an n vector and L is the n \times n
+ matrix [ b[0] c[0] a[0] ]
+ [ a[1] b[1] c[1] ]
+ [ a[2] b[2] c[2] ]
+ [ ... ]
+ [ c[n-1] a[n-1] b[n-1] ]
+ For Dirichlet boundary conditions (denoted here by `u[-1]' and
+ `u[n]'), replace `f[0]' by `f[0]-a[0]u[-1]' and
+ `f[n-1]-c[n-1]u[n]'; then set `a[0]=c[n-1]=0'.
+
+`real[] solve(real[][] a, real[] b, bool warn=true)'
+ Solve the linear equation `a'x=`b' by LU decomposition and return
+ the solution x, where `a' is an n \times n matrix and `b' is an
+ array of length n. For example: import math;
+ real[][] a={{1,-2,3,0},{4,-5,6,2},{-7,-8,10,5},{1,50,1,-2}};
+ real[] b={7,19,33,3};
+ real[] x=solve(a,b);
+ write(a); write();
+ write(b); write();
+ write(x); write();
+ write(a*x);
+ If `a' is a singular matrix and `warn' is `false', return an
+ empty array. If the matrix `a' is tridiagonal, the routine
+ `tridiagonal' provides a more efficient algorithm (*note
+ tridiagonal::).
+
+`real[][] solve(real[][] a, real[][] b, bool warn=true)'
+ Solve the linear equation `a'x=`b' and return the solution x,
+ where `a' is an n \times n matrix and `b' is an n \times m matrix.
+ If `a' is a singular matrix and `warn' is `false', return an empty
+ matrix.
+
+`real[][] identity(int n);'
+ returns the n \times n identity matrix.
+
+`real[][] diagonal(... real[] a)'
+ returns the diagonal matrix with diagonal entries given by a.
+
+`real[][] inverse(real[][] a)'
+ returns the inverse of a square matrix `a'.
+
+``real[] quadraticroots(real a, real b, real c);''
+ This numerically robust solver returns the real roots of the
+ quadratic equation ax^2+bx+c=0, in ascending order. Multiple roots
+ are listed separately.
+
+``pair[] quadraticroots(explicit pair a, explicit pair b, explicit pair c);''
+ This numerically robust solver returns the complex roots of the
+ quadratic equation ax^2+bx+c=0.
+
+``real[] cubicroots(real a, real b, real c, real d);''
+ This numerically robust solver returns the real roots of the cubic
+ equation ax^3+bx^2+cx+d=0. Multiple roots are listed separately.
+
+
+ `Asymptote' includes a full set of vectorized array instructions for
+arithmetic (including self) and logical operations. These
+element-by-element instructions are implemented in C++ code for speed.
+Given
+real[] a={1,2};
+real[] b={3,2};
+ then `a == b' and `a >= 2' both evaluate to the vector `{false, true}'. To
+test whether all components of `a' and `b' agree, use the boolean
+function `all(a == b)'. One can also use conditionals like `(a >= 2) ?
+a : b', which returns the array `{3,2}', or `write((a >= 2) ? a :
+null', which returns the array `{2}'.
+
+ All of the standard built-in `libm' functions of signature
+`real(real)' also take a real array as an argument, effectively like an
+implicit call to `map'.
+
+ As with other built-in types, arrays of the basic data types can be
+read in by assignment. In this example, the code
+file fin=input("test.txt");
+real[] A=fin;
+
+reads real values into `A' until the end-of-file is reached (or an I/O
+error occurs).
+
+ The virtual members `dimension', `line', `csv', `word', and `read'
+of a file are useful for reading arrays. For example, if line mode is
+set with `file line(bool b=true)', then reading will stop once the end
+of the line is reached instead:
+file fin=input("test.txt");
+real[] A=fin.line();
+
+ Since string reads by default read up to the end of line anyway,
+line mode normally has no effect on string array reads. However, there
+is a white-space delimiter mode for reading strings, `file word(bool
+b=true)', which causes string reads to respect white-space delimiters,
+instead of the default end-of-line delimiter:
+file fin=input("test.txt").line().word();
+real[] A=fin;
+
+ Another useful mode is comma-separated-value mode, `file csv(bool
+b=true)', which causes reads to respect comma delimiters:
+file fin=csv(input("test.txt"));
+real[] A=fin;
+
+ To restrict the number of values read, use the `file dimension(int)'
+function:
+file fin=input("test.txt");
+real[] A=dimension(fin,10);
+
+ This reads 10 values into A, unless end-of-file (or end-of-line in
+line mode) occurs first. Attempting to read beyond the end of the file
+will produce a runtime error message. Specifying a value of 0 for the
+integer limit is equivalent to the previous example of reading until
+end-of-file (or end-of-line in line mode) is encountered.
+
+ Two- and three-dimensional arrays of the basic data types can be read
+in like this:
+file fin=input("test.txt");
+real[][] A=fin.dimension(2,3);
+real[][][] B=fin.dimension(2,3,4);
+ Again, an integer limit of zero means no restriction.
+
+ Sometimes the array dimensions are stored with the data as integer
+fields at the beginning of an array. Such 1, 2, or 3 dimensional arrays
+can be read in with the virtual member functions `read(1)', `read(2)',
+or `read(3)', respectively:
+file fin=input("test.txt");
+real[] A=fin.read(1);
+real[][] B=fin.read(2);
+real[][][] C=fin.read(3);
+
+ One, two, and three-dimensional arrays of the basic data types can be
+output with the functions `write(file,T[])', `write(file,T[][])',
+`write(file,T[][][])', respectively.
+
+
+File: asymptote.info, Node: Slices, Up: Arrays
+
+6.12.1 Slices
+-------------
+
+Asymptote allows a section of an array to be addressed as a slice using
+a Python-like syntax. If `A' is an array, the expression `A[m:n]'
+returns a new array consisting of the elements of `A' with indices from
+`m' up to but not including `n'. For example,
+int[] x={0,1,2,3,4,5,6,7,8,9};
+int[] y=x[2:6]; // y={2,3,4,5};
+int[] z=x[5:10]; // z={5,6,7,8,9};
+
+ If the left index is omitted, it is taken be `0'. If the right
+index is omitted it is taken to be the length of the array. If both
+are omitted, the slice then goes from the start of the array to the
+end, producing a non-cyclic deep copy of the array. For example:
+int[] x={0,1,2,3,4,5,6,7,8,9};
+int[] y=x[:4]; // y={0,1,2,3}
+int[] z=x[5:]; // z={5,6,7,8,9}
+int[] w=x[:]; // w={0,1,2,3,4,5,6,7,8,9}, distinct from array x.
+
+ If A is a non-cyclic array, it is illegal to use negative values for
+either of the indices. If the indices exceed the length of the array,
+however, they are politely truncated to that length.
+
+ For cyclic arrays, the slice `A[m:n]' still consists of the cells
+with indices in the set [`m',`n'), but now negative values and values
+beyond the length of the array are allowed. The indices simply wrap
+around. For example:
+
+int[] x={0,1,2,3,4,5,6,7,8,9};
+x.cyclic=true;
+int[] y=x[8:15]; // y={8,9,0,1,2,3,4}.
+int[] z=x[-5:5]; // z={5,6,7,8,9,0,1,2,3,4}
+int[] w=x[-3:17]; // w={7,8,9,0,1,2,3,4,5,6,7,8,9,0,1,2,3,4,5,6}
+
+ Notice that with cyclic arrays, it is possible to include the same
+element of the original array multiple times within a slice.
+Regardless of the original array, arrays produced by slices are always
+non-cyclic.
+
+ If the left and right indices of a slice are the same, the result is
+an empty array. If the array being sliced is empty, the result is an
+empty array. Any slice with a left index greater than its right index
+will yield an error.
+
+ Slices can also be assigned to, changing the value of the original
+array. If the array being assigned to the slice has a different length
+than the slice itself, elements will be inserted or removed from the
+array to accommodate it. For instance:
+string[] toppings={"mayo", "salt", "ham", "lettuce"};
+toppings[0:2]=new string[] {"mustard", "pepper"};
+ // Now toppings={"mustard", "pepper", "ham", "lettuce"}
+toppings[2:3]=new string[] {"turkey", "bacon" };
+ // Now toppings={"mustard", "pepper", "turkey", "bacon", "lettuce"}
+toppings[0:3]=new string[] {"tomato"};
+ // Now toppings={"tomato", "bacon", "lettuce"}
+
+ If an array is assigned to a slice of itself, a copy of the original
+array is assigned to the slice. That is, code such as `x[m:n]=x' is
+equivalent to `x[m:n]=copy(x)'. One can use the shorthand `x[m:m]=y'
+to insert the contents of the array `y' into the array `x' starting at
+the location just before `x[m]'.
+
+ For a cyclic array, a slice is bridging if it addresses cells up to
+the end of the array and then continues on to address cells at the
+start of the array. For instance, if `A' is a cyclic array of length
+10, `A[8:12]', `A[-3:1]', and `A[5:25]' are bridging slices whereas
+`A[3:7]', `A[7:10]', `A[-3:0]' and `A[103:107]' are not. Bridging
+slices can only be assigned to if the number of elements in the slice
+is exactly equal to the number of elements we are assigning to it.
+Otherwise, there is no clear way to decide which of the new entries
+should be `A[0]' and an error is reported. Non-bridging slices may be
+assigned an array of any length.
+
+ For a cyclic array `A' an expression of the form
+`A[A.length:A.length]' is equivalent to the expression `A[0:0]' and so
+assigning to this slice will insert values at the start of the array.
+`A.append()' can be used to insert values at the end of the array.
+
+ It is illegal to assign to a slice of a cyclic array that repeats
+any of the cells.
+
+
+File: asymptote.info, Node: Casts, Next: Import, Prev: Arrays, Up: Programming
+
+6.13 Casts
+==========
+
+`Asymptote' implicitly casts `int' to `real', `int' to `pair', `real'
+to `pair', `pair' to `path', `pair' to `guide', `path' to `guide',
+`guide' to `path', `real' to `pen', `pair[]' to `guide[]', `pair[]' to
+`path[]', `path' to `path[]', and `guide' to `path[]', along with
+various three-dimensional casts defined in `three.asy'. Implicit casts
+are automatically attempted on assignment and when trying to match
+function calls with possible function signatures. Implicit casting can
+be inhibited by declaring individual arguments `explicit' in the
+function signature, say to avoid an ambiguous function call in the
+following example, which outputs 0:
+int f(pair a) {return 0;}
+int f(explicit real x) {return 1;}
+
+write(f(0));
+
+ Other conversions, say `real' to `int' or `real' to `string',
+require an explicit cast:
+int i=(int) 2.5;
+string s=(string) 2.5;
+
+real[] a={2.5,-3.5};
+int[] b=(int []) a;
+write(stdout,b); // Outputs 2,-3
+
+ Casting to user-defined types is also possible using `operator cast':
+struct rpair {
+ real radius;
+ real angle;
+}
+
+pair operator cast(rpair x) {
+ return (x.radius*cos(x.angle),x.radius*sin(x.angle));
+}
+
+rpair x;
+x.radius=1;
+x.angle=pi/6;
+
+write(x); // Outputs (0.866025403784439,0.5)
+
+ One must use care when defining new cast operators. Suppose that in
+some code one wants all integers to represent multiples of 100. To
+convert them to reals, one would first want to multiply them by 100.
+However, the straightforward implementation
+real operator cast(int x) {return x*100;}
+ is equivalent to an infinite recursion, since the result `x*100' needs
+itself to be cast from an integer to a real. Instead, we want to use
+the standard conversion of int to real:
+real convert(int x) {return x*100;}
+real operator cast(int x)=convert;
+
+ Explicit casts are implemented similarly, with `operator ecast'.
+
+
+File: asymptote.info, Node: Import, Next: Static, Prev: Casts, Up: Programming
+
+6.14 Import
+===========
+
+While `Asymptote' provides many features by default, some applications
+require specialized features contained in external `Asymptote' modules.
+For instance, the lines
+access graph;
+graph.axes();
+ draw x and y axes on a two-dimensional graph. Here, the command looks
+up the module under the name `graph' in a global dictionary of modules
+and puts it in a new variable named `graph'. The module is a
+structure, and we can refer to its fields as we usually would with a
+structure.
+
+ Often, one wants to use module functions without having to specify
+the module name. The code
+from graph access axes;
+ adds the `axes' field of `graph' into the local name space, so that
+subsequently, one can just write `axes()'. If the given name is
+overloaded, all types and variables of that name are added. To add
+more than one name, just use a comma-separated list:
+from graph access axes, xaxis, yaxis;
+ Wild card notation can be used to add all non-private fields and types
+of a module to the local name space:
+
+from graph access *;
+
+ Similarly, one can add the non-private fields and types of a
+structure to the local environment with the `unravel' keyword:
+struct matrix {
+ real a,b,c,d;
+}
+
+real det(matrix m) {
+ unravel m;
+ return a*d-b*c;
+}
+ Alternatively, one can unravel selective fields:
+real det(matrix m) {
+ from m unravel a,b,c as C,d;
+ return a*d-b*C;
+}
+
+ The command
+import graph;
+ is a convenient abbreviation for the commands
+access graph;
+unravel graph;
+ That is, `import graph' first loads a module into a structure called
+`graph' and then adds its non-private fields and types to the local
+environment. This way, if a member variable (or function) is
+overwritten with a local variable (or function of the same signature),
+the original one can still be accessed by qualifying it with the module
+name.
+
+ Wild card importing will work fine in most cases, but one does not
+usually know all of the internal types and variables of a module, which
+can also change as the module writer adds or changes features of the
+module. As such, it is prudent to add `import' commands at the start
+of an `Asymptote' file, so that imported names won't shadow locally
+defined functions. Still, imported names may shadow other imported
+names, depending on the order in which they were imported, and imported
+functions may cause overloading resolution problems if they have the
+same name as local functions defined later.
+
+ To rename modules or fields when adding them to the local
+environment, use `as':
+access graph as graph2d;
+from graph access xaxis as xline, yaxis as yline;
+
+ The command
+import graph as graph2d;
+ is a convenient abbreviation for the commands
+access graph as graph2d;
+unravel graph2d;
+
+ Except for a few built-in modules, such as `settings', all modules
+are implemented as `Asymptote' files. When looking up a module that
+has not yet been loaded, `Asymptote' searches the standard search paths
+(*note Search paths::) for the matching file. The file corresponding
+to that name is read and the code within it is interpreted as the body
+of a structure defining the module.
+
+ If the file name contains nonalphanumeric characters, enclose it
+with quotation marks:
+
+`access "/usr/local/share/asymptote/graph.asy" as graph;'
+
+`from "/usr/local/share/asymptote/graph.asy" access axes;'
+
+`import "/usr/local/share/asymptote/graph.asy" as graph;'
+
+ It is an error if modules import themselves (or each other in a
+cycle). The module name to be imported must be known at compile time.
+
+ However, you can import an `Asymptote' module determined by the
+string `s' at runtime like this:
+eval("import "+s,true);
+
+ To conditionally execute an array of asy files, use
+void asy(string format, bool overwrite ... string[] s);
+ The file will only be processed, using output format `format', if
+overwrite is `true' or the output file is missing.
+
+ One can evaluate an `Asymptote' expression (without any return
+value, however) contained in the string `s' with:
+void eval(string s, bool embedded=false);
+ It is not necessary to terminate the string `s' with a semicolon. If
+`embedded' is `true', the string will be evaluated at the top level of
+the current environment. If `embedded' is `false' (the default), the
+string will be evaluated in an independent environment, sharing the same
+`settings' module (*note settings::).
+
+ One can evaluate arbitrary `Asymptote' code (which may contain
+unescaped quotation marks) with the command
+void eval(code s, bool embedded=false);
+ Here `code' is a special type used with `quote {}' to enclose
+`Asymptote code' like this:
+real a=1;
+code s=quote {
+ write(a);
+};
+eval(s,true); // Outputs 1
+
+ To include the contents of an existing file `graph' verbatim (as if
+the contents of the file were inserted at that point), use one of the
+forms:
+include graph;
+
+`include "/usr/local/share/asymptote/graph.asy";'
+
+ To list all global functions and variables defined in a module named
+by the contents of the string `s', use the function
+void list(string s, bool imports=false);
+ Imported global functions and variables are also listed if `imports'
+is `true'.
+
+
+File: asymptote.info, Node: Static, Prev: Import, Up: Programming
+
+6.15 Static
+===========
+
+Static qualifiers allocate the memory address of a variable in a higher
+enclosing level.
+
+ For a function body, the variable is allocated in the block where the
+function is defined; so in the code
+struct s {
+ int count() {
+ static int c=0;
+ ++c;
+ return c;
+ }
+}
+
+there is one instance of the variable `c' for each object `s' (as
+opposed to each call of `count').
+
+ Similarly, in
+int factorial(int n) {
+ int helper(int k) {
+ static int x=1;
+ x *= k;
+ return k == 1 ? x : helper(k-1);
+ }
+ return helper(n);
+}
+
+there is one instance of `x' for every call to `factorial' (and not for
+every call to `helper'), so this is a correct, but ugly, implementation
+of factorial.
+
+ Similarly, a static variable declared within a structure is
+allocated in the block where the structure is defined. Thus,
+struct A {
+ struct B {
+ static pair z;
+ }
+}
+
+creates one object `z' for each object of type `A' created.
+
+ In this example,
+int pow(int n, int k) {
+ struct A {
+ static int x=1;
+ void helper() {
+ x *= n;
+ }
+ }
+ for(int i=0; i < k; ++i) {
+ A a;
+ a.helper();
+ }
+ return A.x;
+}
+
+there is one instance of `x' for each call to `pow', so this is an ugly
+implementation of exponentiation.
+
+ Loop constructs allocate a new frame in every iteration. This is so
+that higher-order functions can refer to variables of a specific
+iteration of a loop:
+void f();
+for(int i=0; i < 10; ++i) {
+ int x=i;
+ if(x==5) {
+ f=new void () { write(x); }
+ }
+}
+f();
+
+ Here, every iteration of the loop has its own variable `x', so `f()'
+will write `5'. If a variable in a loop is declared static, it will be
+allocated where the enclosing function or structure was defined (just
+as if it were declared static outside of the loop). For instance, in:
+void f() {
+ static int x;
+ for(int i=0; i < 10; ++i) {
+ static int y;
+ }
+}
+ both `x' and `y' will be allocated in the same place, which is also
+where `f' is also allocated.
+
+ Statements may also be declared static, in which case they are run
+at the place where the enclosing function or structure is defined.
+Declarations or statements not enclosed in a function or structure
+definition are already at the top level, so static modifiers are
+meaningless. A warning is given in such a case.
+
+ Since structures can have static fields, it is not always clear for
+a qualified name whether the qualifier is a variable or a type. For
+instance, in:
+
+struct A {
+ static int x;
+}
+pair A;
+
+int y=A.x;
+ does the `A' in `A.x' refer to the structure or to the pair variable.
+It is the convention in Asymptote that, if there is a non-function
+variable with the same name as the qualifier, the qualifier refers to
+that variable, and not to the type. This is regardless of what fields
+the variable actually possesses.
+
+
+File: asymptote.info, Node: LaTeX usage, Next: Base modules, Prev: Programming, Up: Top
+
+7 `LaTeX' usage
+***************
+
+`Asymptote' comes with a convenient `LaTeX' style file `asymptote.sty'
+that makes `LaTeX' `Asymptote'-aware. Entering `Asymptote' code
+directly into the `LaTeX' source file, at the point where it is needed,
+keeps figures organized and avoids the need to invent new file names
+for each figure. Simply add the line `\usepackage{asymptote}' at the
+beginning of your file and enclose your `Asymptote' code within a
+`\begin{asy}...\end{asy}' environment. As with the `LaTeX' `comment'
+environment, the `\end{asy}' command must appear on a line by itself,
+with no trailing commands/comments. A blank line is not allowed after
+`\begin{asy}'.
+
+ The sample `LaTeX' file below, named `latexusage.tex', can be run as
+follows:
+latex latexusage
+asy latexusage-*.asy
+latex latexusage
+
+or
+pdflatex latexusage
+asy latexusage-*.asy
+pdflatex latexusage
+ To switch between using inline Asymptote code with `latex' and
+`pdflatex' you may first need to remove the files `latexusage-*.tex'.
+
+ An even better method for processing a `LaTeX' file with embedded
+`Asymptote' code is to use the `latexmk' utility from
+
+ `http://www.ctan.org/tex-archive/support/latexmk/'
+ after putting the contents of
+`http://asymptote.svn.sourceforge.net/viewvc/asymptote/trunk/asymptote/doc/latexmkrc'
+in a file `latexmkrc' in the same directory. The command
+latexmk -pdf latexusage
+ will then call `Asymptote' automatically, recompiling only the figures
+that have changed. Since each figure is compiled in a separate system
+process, this method also tends to use less memory. To store the
+figures in a separate directory named `asy', one can define
+\def\asydir{asy}
+ in `latexusage.tex' and put the contents of
+`http://asymptote.svn.sourceforge.net/viewvc/asymptote/trunk/asymptote/doc/latexmkrc_asydir'
+in a file `latexmkrc' in the same directory. External `Asymptote' code
+in `filename.asy' should be included with
+\asyinclude[<options>]{<filename.asy>}
+ so that `latexmk' will recognize when the code is changed. Note that
+`latemk' requires `perl', available from `http://www.perl.org/'.
+
+ One can specify `width', `height', `keepAspect', `viewportwidth',
+`viewportheight', `attach', and `inline'. `keyval'-style options to
+the `asy' and `asyinclude' environments. Three-dimensional PRC files
+may either be embedded within the page (the default) or attached as
+annotated (but printable) attachments, using the `attach' option and
+the `attachfile2' (or older `attachfile') `LaTeX' package. The
+`inline' option generates inline `LaTeX' code instead of EPS or PDF
+files. This makes 2D LaTeX symbols visible to the
+`\begin{asy}...\end{asy}' environment. In this mode, Asymptote
+correctly aligns 2D LaTeX symbols defined outside of
+`\begin{asy}...\end{asy}', but treats their size as zero; an optional
+second string can be given to `Label' to provide an estimate of the
+unknown label size.
+
+ Note that if the `latex' TeX engine is used with the `inline'
+option, labels might not show up in DVI viewers that cannot handle raw
+`PostScript' code. One can use `dvips'/`dvipdf' to produce
+`PostScript'/PDF output (we recommend using the modified version of
+`dvipdf' in the `Asymptote' patches directory, which accepts the `dvips
+-z' hyperdvi option).
+
+ Here now is `latexusage.tex':
+
+\documentclass[12pt]{article}
+
+% Use this form to include EPS (latex) or PDF (pdflatex) files:
+\usepackage{asymptote}
+
+% Use this form with latex or pdflatex to include inline LaTeX code by default:
+%\usepackage[inline]{asymptote}
+
+% Use this form with latex or pdflatex to create PDF attachments by default:
+%\usepackage[attach]{asymptote}
+
+% Enable this line to support the attach option:
+%\usepackage[dvips]{attachfile2}
+
+\begin{document}
+
+% Optional subdirectory for asy files (no spaces):
+\def\asydir{}
+
+\begin{asydef}
+// Global Asymptote definitions can be put here.
+import three;
+usepackage("bm");
+texpreamble("\def\V#1{\bm{#1}}");
+// One can globally override the default toolbar settings here:
+// settings.toolbar=true;
+\end{asydef}
+
+Here is a venn diagram produced with Asymptote, drawn to width 4cm:
+
+\def\A{A}
+\def\B{\V{B}}
+
+%\begin{figure}
+\begin{center}
+\begin{asy}
+size(4cm,0);
+pen colour1=red;
+pen colour2=green;
+
+pair z0=(0,0);
+pair z1=(-1,0);
+pair z2=(1,0);
+real r=1.5;
+path c1=circle(z1,r);
+path c2=circle(z2,r);
+fill(c1,colour1);
+fill(c2,colour2);
+
+picture intersection=new picture;
+fill(intersection,c1,colour1+colour2);
+clip(intersection,c2);
+
+add(intersection);
+
+draw(c1);
+draw(c2);
+
+//draw("$\A$",box,z1); // Requires [inline] package option.
+//draw(Label("$\B$","$B$"),box,z2); // Requires [inline] package option.
+draw("$A$",box,z1);
+draw("$\V{B}$",box,z2);
+
+pair z=(0,-2);
+real m=3;
+margin BigMargin=Margin(0,m*dot(unit(z1-z),unit(z0-z)));
+
+draw(Label("$A\cap B$",0),conj(z)--z0,Arrow,BigMargin);
+draw(Label("$A\cup B$",0),z--z0,Arrow,BigMargin);
+draw(z--z1,Arrow,Margin(0,m));
+draw(z--z2,Arrow,Margin(0,m));
+
+shipout(bbox(0.25cm));
+\end{asy}
+%\caption{Venn diagram}\label{venn}
+\end{center}
+%\end{figure}
+
+Each graph is drawn in its own environment. One can specify the width
+and height to \LaTeX\ explicitly. This 3D example can be viewed
+interactively either with Adobe Reader or Asymptote's fast OpenGL-based
+renderer. To support {\tt latexmk}, 3D figures should specify
+\verb+inline=true+. It is sometimes desirable to embed 3D files as annotated
+attachments; this requires the \verb+attach=true+ option as well as the
+\verb+attachfile2+ \LaTeX\ package.
+\begin{center}
+\begin{asy}[height=4cm,inline=true,attach=false,viewportwidth=\linewidth]
+currentprojection=orthographic(5,4,2);
+draw(unitcube,blue);
+label("$V-E+F=2$",(0,1,0.5),3Y,blue+fontsize(17pt));
+\end{asy}
+\end{center}
+
+One can also scale the figure to the full line width:
+\begin{center}
+\begin{asy}[width=\the\linewidth,inline=true]
+pair z0=(0,0);
+pair z1=(2,0);
+pair z2=(5,0);
+pair zf=z1+0.75*(z2-z1);
+
+draw(z1--z2);
+dot(z1,red+0.15cm);
+dot(z2,darkgreen+0.3cm);
+label("$m$",z1,1.2N,red);
+label("$M$",z2,1.5N,darkgreen);
+label("$\hat{\ }$",zf,0.2*S,fontsize(24pt)+blue);
+
+pair s=-0.2*I;
+draw("$x$",z0+s--z1+s,N,red,Arrows,Bars,PenMargins);
+s=-0.5*I;
+draw("$\bar{x}$",z0+s--zf+s,blue,Arrows,Bars,PenMargins);
+s=-0.95*I;
+draw("$X$",z0+s--z2+s,darkgreen,Arrows,Bars,PenMargins);
+\end{asy}
+\end{center}
+\end{document}
+
+
+File: asymptote.info, Node: Base modules, Next: Options, Prev: LaTeX usage, Up: Top
+
+8 Base modules
+**************
+
+`Asymptote' currently ships with the following base modules:
+
+* Menu:
+
+* plain:: Default `Asymptote' base file
+* simplex:: Linear programming: simplex method
+* math:: Extend `Asymptote''s math capabilities
+* interpolate:: Interpolation routines
+* geometry:: Geometry routines
+* trembling:: Wavy lines
+* stats:: Statistics routines and histograms
+* patterns:: Custom fill and draw patterns
+* markers:: Custom path marker routines
+* tree:: Dynamic binary search tree
+* binarytree:: Binary tree drawing module
+* drawtree:: Tree drawing module
+* syzygy:: Syzygy and braid drawing module
+* feynman:: Feynman diagrams
+* roundedpath:: Round the sharp corners of paths
+* animation:: Embedded PDF and MPEG movies
+* embed:: Embedding movies, sounds, and 3D objects
+* slide:: Making presentations with `Asymptote'
+* MetaPost:: `MetaPost' compatibility routines
+* unicode:: Accept `unicode' (UTF-8) characters
+* latin1:: Accept `ISO 8859-1' characters
+* babel:: Interface to `LaTeX' `babel' package
+* labelpath:: Drawing curved labels
+* labelpath3:: Drawing curved labels in 3D
+* annotate:: Annotate your PDF files
+* CAD:: 2D CAD pen and measurement functions (DIN 15)
+* graph:: 2D linear & logarithmic graphs
+* palette:: Color density images and palettes
+* three:: 3D vector graphics
+* obj:: 3D obj files
+* graph3:: 3D linear & logarithmic graphs
+* grid3:: 3D grids
+* solids:: 3D solid geometry
+* tube:: 3D rotation minimizing tubes
+* flowchart:: Flowchart drawing routines
+* contour:: Contour lines
+* contour3:: Contour surfaces
+* slopefield:: Slope fields
+* ode:: Ordinary differential equations
+
+
+File: asymptote.info, Node: plain, Next: simplex, Up: Base modules
+
+8.1 `plain'
+===========
+
+This is the default `Asymptote' base file, which defines key parts of
+the drawing language (such as the `picture' structure).
+
+ By default, an implicit `private import plain;' occurs before
+translating a file and before the first command given in interactive
+mode. This also applies when translating files for module definitions
+(except when translating `plain', of course). This means that the
+types and functions defined in `plain' are accessible in almost all
+`Asymptote' code. Use the `-noautoplain' command-line option to disable
+this feature.
+
+
+File: asymptote.info, Node: simplex, Next: math, Prev: plain, Up: Base modules
+
+8.2 `simplex'
+=============
+
+This package solves the two-variable linear programming problem using
+the simplex method. It is used by the module `plain' for automatic
+sizing of pictures.
+
+
+File: asymptote.info, Node: math, Next: interpolate, Prev: simplex, Up: Base modules
+
+8.3 `math'
+==========
+
+This package extends `Asymptote''s mathematical capabilities with
+useful functions such as
+
+`void drawline(picture pic=currentpicture, pair P, pair Q, pen p=currentpen);'
+ draw the visible portion of the (infinite) line going through `P'
+ and `Q', without altering the size of picture `pic', using pen `p'.
+
+`real intersect(triple P, triple Q, triple n, triple Z);'
+ returns the intersection time of the extension of the line segment
+ `PQ' with the plane perpendicular to `n' and passing through `Z'.
+
+`triple intersectionpoint(triple n0, triple P0, triple n1, triple P1);'
+ Return any point on the intersection of the two planes with normals
+ `n0' and `n1' passing through points `P0' and `P1', respectively.
+ If the planes are parallel, return `(infinity,infinity,infinity)'.
+
+`pair[] quarticroots(real a, real b, real c, real d, real e);'
+ returns the four complex roots of the quartic equation
+ ax^4+bx^3+cx^2+dx+e=0.
+
+`pair[][] fft(pair[][] a, int sign=1)'
+ returns the two-dimensional Fourier transform of a using the given
+ `sign'.
+
+`real time(path g, real x, int n=0)'
+ returns the `n'th intersection time of path `g' with the vertical
+ line through x.
+
+`real time(path g, explicit pair z, int n=0)'
+ returns the `n'th intersection time of path `g' with the horizontal
+ line through `(0,z.y)'.
+
+`real value(path g, real x, int n=0)'
+ returns the `n'th `y' value of `g' at `x'.
+
+`real value(path g, real x, int n=0)'
+ returns the `n'th `x' value of `g' at `y=z.y'.
+
+`real slope(path g, real x, int n=0)'
+ returns the `n'th slope of `g' at `x'.
+
+`real slope(path g, explicit pair z, int n=0)'
+ returns the `n'th slope of `g' at `y=z.y'.
+
+ int[][] segment(bool[] b) returns the indices of consecutive
+ true-element segments of bool[] `b'.
+
+`real[] partialsum(real[] a)'
+ returns the partial sums of a real array `a'.
+
+`real[] partialsum(real[] a, real[] dx)'
+ returns the partial `dx'-weighted sums of a real array `a'.
+
+`bool increasing(real[] a, bool strict=false)'
+ returns, if `strict=false', whether `i > j' implies `a[i] >=
+ a[j]', or if `strict=true', whether `i > j' implies implies `a[i]
+ > a[j]'.
+
+`int unique(real[] a, real x)'
+ if the sorted array `a' does not contain `x', insert it
+ sequentially, returning the index of `x' in the resulting array.
+
+`bool lexorder(pair a, pair b)'
+ returns the strict lexicographical partial order of `a' and `b'.
+
+`bool lexorder(triple a, triple b)'
+ returns the strict lexicographical partial order of `a' and `b'.
+
+
+File: asymptote.info, Node: interpolate, Next: geometry, Prev: math, Up: Base modules
+
+8.4 `interpolate'
+=================
+
+This module implements Lagrange, Hermite, and standard cubic spline
+interpolation in `Asymptote', as illustrated in the example
+`interpolate1.asy'.
+
+
+File: asymptote.info, Node: geometry, Next: trembling, Prev: interpolate, Up: Base modules
+
+8.5 `geometry'
+==============
+
+This module, written by Philippe Ivaldi, provides an extensive set of
+geometry routines, including `perpendicular' symbols and a `triangle'
+structure. Link to the documentation for the `geometry' module are
+posted here: `http://asymptote.sourceforge.net/links.html', including
+an extensive set of examples,
+`http://www.piprime.fr/files/asymptote/geometry/', and an index:
+
+ `http://www.piprime.fr/files/asymptote/geometry/modules/geometry.asy.index.type.html'
+
+
+File: asymptote.info, Node: trembling, Next: stats, Prev: geometry, Up: Base modules
+
+8.6 `trembling'
+===============
+
+This module, written by Philippe Ivaldi and illustrated in the example
+`floatingdisk.asy', allows one to draw wavy lines, as if drawn by hand.
+
+
+File: asymptote.info, Node: stats, Next: patterns, Prev: trembling, Up: Base modules
+
+8.7 `stats'
+===========
+
+This package implements a Gaussian random number generator and a
+collection of statistics routines, including `histogram' and
+`leastsquares'.
+
+
+File: asymptote.info, Node: patterns, Next: markers, Prev: stats, Up: Base modules
+
+8.8 `patterns'
+==============
+
+This package implements `Postscript' tiling patterns and includes
+several convenient pattern generation routines.
+
+
+File: asymptote.info, Node: markers, Next: tree, Prev: patterns, Up: Base modules
+
+8.9 `markers'
+=============
+
+This package implements specialized routines for marking paths and
+angles. The principal mark routine provided by this package is
+markroutine markinterval(int n=1, frame f, bool rotated=false);
+ which centers `n' copies of frame `f' within uniformly space intervals
+in arclength along the path, optionally rotated by the angle of the
+local tangent.
+
+ The `marker' (*note marker::) routine can be used to construct new
+markers from these predefined frames:
+
+frame stickframe(int n=1, real size=0, pair space=0, real angle=0,
+ pair offset=0, pen p=currentpen);
+
+frame circlebarframe(int n=1, real barsize=0,
+ real radius=0,real angle=0,
+ pair offset=0, pen p=currentpen,
+ filltype filltype=NoFill, bool above=false);
+
+frame crossframe(int n=3, real size=0, pair space=0,
+ real angle=0, pair offset=0, pen p=currentpen);
+
+frame tildeframe(int n=1, real size=0, pair space=0,
+ real angle=0, pair offset=0, pen p=currentpen);
+
+ For convenience, this module also constructs the markers
+`StickIntervalMarker', `CrossIntervalMarker',
+`CircleBarIntervalMarker', and `TildeIntervalMarker' from the above
+frames. The example `markers1.asy' illustrates the use of these markers:
+
+
+
+
+This package also provides a routine for marking an angle AOB:
+void markangle(picture pic=currentpicture, Label L="",
+ int n=1, real radius=0, real space=0,
+ pair A, pair O, pair B, arrowbar arrow=None,
+ pen p=currentpen, margin margin=NoMargin,
+ marker marker=nomarker);
+ as illustrated in the example `markers2.asy'.
+
+
+
+
+
+File: asymptote.info, Node: tree, Next: binarytree, Prev: markers, Up: Base modules
+
+8.10 `tree'
+===========
+
+This package implements an example of a dynamic binary search tree.
+
+
+File: asymptote.info, Node: binarytree, Next: drawtree, Prev: tree, Up: Base modules
+
+8.11 `binarytree'
+=================
+
+This module can be used to draw an arbitrary binary tree and includes an
+input routine for the special case of a binary search tree, as
+illustrated in the example `binarytreetest.asy':
+
+import binarytree;
+
+picture pic,pic2;
+
+binarytree bt=binarytree(1,2,4,nil,5,nil,nil,0,nil,nil,3,6,nil,nil,7);
+draw(pic,bt,condensed=false);
+
+binarytree st=searchtree(10,5,2,1,3,4,7,6,8,9,15,13,12,11,14,17,16,18,19);
+draw(pic2,st,blue,condensed=true);
+
+add(pic.fit(),(0,0),10N);
+add(pic2.fit(),(0,0),10S);
+
+
+
+
+File: asymptote.info, Node: drawtree, Next: syzygy, Prev: binarytree, Up: Base modules
+
+8.12 `drawtree'
+===============
+
+This is a simple tree drawing module used by the example `treetest.asy'.
+
+
+File: asymptote.info, Node: syzygy, Next: feynman, Prev: drawtree, Up: Base modules
+
+8.13 `syzygy'
+=============
+
+This module automates the drawing of braids, relations, and syzygies,
+along with the corresponding equations, as illustrated in the example
+`knots.asy'.
+
+
+File: asymptote.info, Node: feynman, Next: roundedpath, Prev: syzygy, Up: Base modules
+
+8.14 `feynman'
+==============
+
+This package, contributed by Martin Wiebusch, is useful for drawing
+Feynman diagrams, as illustrated by the examples `eetomumu.asy' and
+`fermi.asy'.
+
+
+File: asymptote.info, Node: roundedpath, Next: animation, Prev: feynman, Up: Base modules
+
+8.15 `roundedpath'
+==================
+
+This package, contributed by Stefan Knorr, is useful for rounding the
+sharp corners of paths, as illustrated in the example file
+`roundpath.asy'.
+
+
+File: asymptote.info, Node: animation, Next: embed, Prev: roundedpath, Up: Base modules
+
+8.16 `animation'
+================
+
+This module allows one to generate animations, as illustrated by the
+files `wheel.asy', `wavepacket.asy', and `cube.asy' in the `animations'
+subdirectory of the examples directory. These animations use the
+`ImageMagick' `convert' program to merge multiple images into a GIF or
+MPEG movie.
+
+ The related `animate' module, derived from the `animation' module,
+generates higher-quality portable clickable PDF movies, with optional
+controls. This requires installing the package
+
+ `http://www.ctan.org/tex-archive/macros/latex/contrib/animate/animate.sty'
+ (version 2007/11/30 or later) in a new directory `animate' in the
+local `LaTeX' directory (for example, in
+`/usr/local/share/texmf/tex/latex/animate'). On `UNIX' systems, one
+must then execute the command `texhash'.
+
+ The example `pdfmovie.asy' in the `animations' directory, along with
+the slide presentations `slidemovies.asy' and `intro.asy', illustrate
+the use of embedded PDF movies. The examples `inlinemovie.tex' and
+`inlinemovie3.tex' show how to generate and embed PDF movies directly
+within a `LaTeX' file (*note LaTeX usage::). The member function
+string pdf(fit fit=NoBox, real delay=animationdelay, string options="",
+ bool keep=settings.keep, bool multipage=true);
+ of the `animate' structure accepts any of the `animate.sty' options,
+as described here:
+
+ `http://www.ctan.org/tex-archive/macros/latex/contrib/animate/doc/animate.pdf'
+
+
+File: asymptote.info, Node: embed, Next: slide, Prev: animation, Up: Base modules
+
+8.17 `embed'
+============
+
+This module provides an interface to the `LaTeX' package (included with
+`MikTeX')
+
+ `http://www.ctan.org/tex-archive/macros/latex/contrib/media9'
+ for embedding movies, sounds, and 3D objects into a PDF document.
+
+ A more portable method for embedding movie files, which should work
+on any platform and does not require the `media9' package, is provided
+by using the `external' module instead of `embed'.
+
+ Examples of the above two interfaces is provided in the file
+`embeddedmovie.asy' and `externalmovie.asy' in the `animations'
+subdirectory of the examples directory. For a higher quality embedded
+movie generated directly by `Asymptote', use the `animate' module along
+with the `animate.sty' package to embed a portable PDF animation (*note
+animate::).
+
+ An example of embedding `U3D' code is provided in the file
+`embeddedu3d.asy'.
+
+
+File: asymptote.info, Node: slide, Next: MetaPost, Prev: embed, Up: Base modules
+
+8.18 `slide'
+============
+
+This package provides a simple yet high-quality facility for making
+presentation slides, including portable embedded PDF animations (see
+the file `slidemovies.asy'). A simple example is provided in the file
+`slidedemo.asy'.
+
+
+File: asymptote.info, Node: MetaPost, Next: unicode, Prev: slide, Up: Base modules
+
+8.19 `MetaPost'
+===============
+
+This package provides some useful routines to help `MetaPost' users
+migrate old `MetaPost' code to `Asymptote'. Further contributions here
+are welcome.
+
+ Unlike `MetaPost', `Asymptote' does not implicitly solve linear
+equations and therefore does not have the notion of a `whatever'
+unknown. The routine `extension' (*note extension::) provides a useful
+replacement for a common use of `whatever': finding the intersection
+point of the lines through `P', `Q' and `p', `q'. For less common
+occurrences of `whatever', one can use the built-in explicit linear
+equation solver `solve' instead.
+
+
+File: asymptote.info, Node: unicode, Next: latin1, Prev: MetaPost, Up: Base modules
+
+8.20 `unicode'
+==============
+
+Import this package at the beginning of the file to instruct `LaTeX' to
+accept `unicode' (UTF-8) standardized international characters. To use
+Cyrillic fonts, you will need to change the font encoding:
+import unicode;
+texpreamble("\usepackage{mathtext}\usepackage[russian]{babel}");
+defaultpen(font("T2A","cmr","m","n"));
+ Support for Chinese, Japanese, and Korean fonts is provided by the CJK
+package:
+
+ `http://www.ctan.org/tex-archive/languages/chinese/CJK/'
+ The following commands enable the CJK song family (within a label,
+you can also temporarily switch to another family, say kai, by
+prepending `"\CJKfamily{kai}"' to the label string):
+texpreamble("\usepackage{CJK}
+\AtBeginDocument{\begin{CJK*}{GBK}{song}}
+\AtEndDocument{\clearpage\end{CJK*}}");
+
+
+File: asymptote.info, Node: latin1, Next: babel, Prev: unicode, Up: Base modules
+
+8.21 `latin1'
+=============
+
+If you don't have `LaTeX' support for `unicode' installed, you can
+enable support for Western European languages (ISO 8859-1) by importing
+the module `latin1'. This module can be used as a template for
+providing support for other ISO 8859 alphabets.
+
+
+File: asymptote.info, Node: babel, Next: labelpath, Prev: latin1, Up: Base modules
+
+8.22 `babel'
+============
+
+This module implements the `LaTeX' `babel' package in `Asymptote'. For
+example:
+import babel;
+babel("german");
+
+
+File: asymptote.info, Node: labelpath, Next: labelpath3, Prev: babel, Up: Base modules
+
+8.23 `labelpath'
+================
+
+This module uses the `PSTricks' `pstextpath' macro to fit labels along
+a path (properly kerned, as illustrated in the example file
+`curvedlabel.asy'), using the command
+void labelpath(picture pic=currentpicture, Label L, path g,
+ string justify=Centered, pen p=currentpen);
+ Here `justify' is one of `LeftJustified', `Centered', or
+`RightJustified'. The x component of a shift transform applied to the
+Label is interpreted as a shift along the curve, whereas the y
+component is interpreted as a shift away from the curve. All other
+Label transforms are ignored. This package requires the `latex' tex
+engine and inherits the limitations of the `PSTricks' `\pstextpath'
+macro.
+
+
+File: asymptote.info, Node: labelpath3, Next: annotate, Prev: labelpath, Up: Base modules
+
+8.24 `labelpath3'
+=================
+
+This module, contributed by Jens Schwaiger, implements a 3D version of
+`labelpath' that does not require the `PSTricks' package. An example
+is provided in `curvedlabel3.asy'.
+
+
+File: asymptote.info, Node: annotate, Next: CAD, Prev: labelpath3, Up: Base modules
+
+8.25 `annotate'
+===============
+
+This module supports PDF annotations for viewing with `Adobe Reader',
+via the function
+void annotate(picture pic=currentpicture, string title, string text,
+ pair position);
+ Annotations are illustrated in the example file `annotation.asy'.
+Currently, annotations are only implemented for the `latex' (default)
+and `tex' TeX engines.
+
+
+File: asymptote.info, Node: CAD, Next: graph, Prev: annotate, Up: Base modules
+
+8.26 `CAD'
+==========
+
+This package, contributed by Mark Henning, provides basic pen
+definitions and measurement functions for simple 2D CAD drawings
+according to DIN 15. It is documented separately, in the file `CAD.pdf'.
+
+
+File: asymptote.info, Node: graph, Next: palette, Prev: CAD, Up: Base modules
+
+8.27 `graph'
+============
+
+This package implements two-dimensional linear and logarithmic graphs,
+including automatic scale and tick selection (with the ability to
+override manually). A graph is a `guide' (that can be drawn with the
+draw command, with an optional legend) constructed with one of the
+following routines:
+
+ * guide graph(picture pic=currentpicture, real f(real), real a, real b,
+ int n=ngraph, real T(real)=identity,
+ interpolate join=operator --);
+ guide[] graph(picture pic=currentpicture, real f(real), real a, real b,
+ int n=ngraph, real T(real)=identity, bool3 cond(real),
+ interpolate join=operator --);
+
+ Returns a graph using the scaling information for picture `pic'
+ (*note automatic scaling::) of the function `f' on the interval
+ [`T'(`a'),`T'(`b')], sampling at `n' points evenly spaced in
+ [`a',`b'], optionally restricted by the bool3 function `cond' on
+ [`a',`b']. If `cond' is:
+ * `true', the point is added to the existing guide;
+
+ * `default', the point is added to a new guide;
+
+ * `false', the point is omitted and a new guide is begun.
+ The points are connected using the interpolation specified by
+ `join':
+ * `operator --' (linear interpolation; the abbreviation
+ `Straight' is also accepted);
+
+ * `operator ..' (piecewise Bezier cubic spline interpolation;
+ the abbreviation `Spline' is also accepted);
+
+ * `Hermite' (standard cubic spline interpolation using boundary
+ condition `notaknot', `natural', `periodic', `clamped(real
+ slopea, real slopeb)'), or `monotonic'. The abbreviation
+ `Hermite' is equivalent to `Hermite(notaknot)' for
+ nonperiodic data and `Hermite(periodic)' for periodic data).
+
+
+ * guide graph(picture pic=currentpicture, real x(real), real y(real),
+ real a, real b, int n=ngraph, real T(real)=identity,
+ interpolate join=operator --);
+ guide[] graph(picture pic=currentpicture, real x(real), real y(real),
+ real a, real b, int n=ngraph, real T(real)=identity,
+ bool3 cond(real), interpolate join=operator --);
+
+ Returns a graph using the scaling information for picture `pic' of
+ the parametrized function (`x'(t),`y'(t)) for t in the interval
+ [`T'(`a'),`T'(`b')], sampling at `n' points evenly spaced in
+ [`a',`b'], optionally restricted by the bool3 function `cond' on
+ [`a',`b'], using the given interpolation type.
+
+ * guide graph(picture pic=currentpicture, pair z(real), real a, real b,
+ int n=ngraph, real T(real)=identity,
+ interpolate join=operator --);
+ guide[] graph(picture pic=currentpicture, pair z(real), real a, real b,
+ int n=ngraph, real T(real)=identity, bool3 cond(real),
+ interpolate join=operator --);
+
+ Returns a graph using the scaling information for picture `pic' of
+ the parametrized function `z'(t) for t in the interval
+ [`T'(`a'),`T'(`b')], sampling at `n' points evenly spaced in
+ [`a',`b'], optionally restricted by the bool3 function `cond' on
+ [`a',`b'], using the given interpolation type.
+
+ * guide graph(picture pic=currentpicture, pair[] z,
+ interpolate join=operator --);
+ guide[] graph(picture pic=currentpicture, pair[] z, bool3[] cond,
+ interpolate join=operator --);
+
+ Returns a graph using the scaling information for picture `pic' of
+ the elements of the array `z', optionally restricted to those
+ indices for which the elements of the boolean array `cond' are
+ `true', using the given interpolation type.
+
+ * guide graph(picture pic=currentpicture, real[] x, real[] y,
+ interpolate join=operator --);
+ guide[] graph(picture pic=currentpicture, real[] x, real[] y,
+ bool3[] cond, interpolate join=operator --);
+
+ Returns a graph using the scaling information for picture `pic' of
+ the elements of the arrays (`x',`y'), optionally restricted to
+ those indices for which the elements of the boolean array `cond'
+ are `true', using the given interpolation type.
+
+ * guide polargraph(picture pic=currentpicture, real f(real), real a,
+ real b, int n=ngraph, interpolate join=operator --);
+
+ Returns a polar-coordinate graph using the scaling information for
+ picture `pic' of the function `f' on the interval [`a',`b'],
+ sampling at `n' evenly spaced points, with the given interpolation
+ type.
+
+ * guide polargraph(picture pic=currentpicture, real[] r, real[] theta,
+ interpolate join=operator--);
+ Returns a polar-coordinate graph using the scaling information for
+ picture `pic' of the elements of the arrays (`r',`theta'), using
+ the given interpolation type.
+
+
+
+
+ An axis can be drawn on a picture with one of the following commands:
+
+ * void xaxis(picture pic=currentpicture, Label L="", axis axis=YZero,
+ real xmin=-infinity, real xmax=infinity, pen p=currentpen,
+ ticks ticks=NoTicks, arrowbar arrow=None, bool above=false);
+
+ Draw an x axis on picture `pic' from x=`xmin' to x=`xmax' using
+ pen `p', optionally labelling it with Label `L'. The relative
+ label location along the axis (a real number from [0,1]) defaults
+ to 1 (*note Label::), so that the label is drawn at the end of the
+ axis. An infinite value of `xmin' or `xmax' specifies that the
+ corresponding axis limit will be automatically determined from the
+ picture limits. The optional `arrow' argument takes the same
+ values as in the `draw' command (*note arrows::). The axis is
+ drawn before any existing objects in `pic' unless `above=true'.
+ The axis placement is determined by one of the following `axis'
+ types:
+
+ `YZero(bool extend=true)'
+ Request an x axis at y=0 (or y=1 on a logarithmic axis)
+ extending to the full dimensions of the picture, unless
+ `extend'=false.
+
+ `YEquals(real Y, bool extend=true)'
+ Request an x axis at y=`Y' extending to the full dimensions
+ of the picture, unless `extend'=false.
+
+ `Bottom(bool extend=false)'
+ Request a bottom axis.
+
+ `Top(bool extend=false)'
+ Request a top axis.
+
+ `BottomTop(bool extend=false)'
+ Request a bottom and top axis.
+
+
+ Custom axis types can be created by following the examples in
+ `graph.asy'. One can easily override the default values for the
+ standard axis types: import graph;
+
+ YZero=new axis(bool extend=true) {
+ return new void(picture pic, axisT axis) {
+ real y=pic.scale.x.scale.logarithmic ? 1 : 0;
+ axis.value=I*pic.scale.y.T(y);
+ axis.position=1;
+ axis.side=right;
+ axis.align=2.5E;
+ axis.value2=Infinity;
+ axis.extend=extend;
+ };
+ };
+ YZero=YZero();
+
+ The default tick option is `NoTicks'. The options `LeftTicks',
+ `RightTicks', or `Ticks' can be used to draw ticks on the left,
+ right, or both sides of the path, relative to the direction in
+ which the path is drawn. These tick routines accept a number of
+ optional arguments: ticks LeftTicks(Label format="", ticklabel ticklabel=null,
+ bool beginlabel=true, bool endlabel=true,
+ int N=0, int n=0, real Step=0, real step=0,
+ bool begin=true, bool end=true, tickmodifier modify=None,
+ real Size=0, real size=0, bool extend=false,
+ pen pTick=nullpen, pen ptick=nullpen);
+
+ If any of these parameters are omitted, reasonable defaults will
+ be chosen:
+ `Label format'
+ override the default tick label format (`defaultformat',
+ initially "$%.4g$"), rotation, pen, and alignment (for
+ example, `LeftSide', `Center', or `RightSide') relative to
+ the axis. To enable `LaTeX' math mode fonts, the format
+ string should begin and end with `$' *note format::. If the
+ format string is `trailingzero', trailing zeros will be added
+ to the tick labels; if the format string is `"%"', the tick
+ label will be suppressed;
+
+ `ticklabel'
+ is a function `string(real x)' returning the label (by
+ default, format(format.s,x)) for each major tick value `x';
+
+ `bool beginlabel'
+ include the first label;
+
+ `bool endlabel'
+ include the last label;
+
+ `int N'
+ when automatic scaling is enabled (the default; *note
+ automatic scaling::), divide a linear axis evenly into this
+ many intervals, separated by major ticks; for a logarithmic
+ axis, this is the number of decades between labelled ticks;
+
+ `int n'
+ divide each interval into this many subintervals, separated
+ by minor ticks;
+
+ `real Step'
+ the tick value spacing between major ticks (if `N'=`0');
+
+ `real step'
+ the tick value spacing between minor ticks (if `n'=`0');
+
+ `bool begin'
+ include the first major tick;
+
+ `bool end'
+ include the last major tick;
+
+ `tickmodifier modify;'
+ an optional function that takes and returns a `tickvalue'
+ structure having real[] members `major' and `minor'
+ consisting of the tick values (to allow modification of the
+ automatically generated tick values);
+
+ `real Size'
+ the size of the major ticks (in `PostScript' coordinates);
+
+ `real size'
+ the size of the minor ticks (in `PostScript' coordinates);
+
+ `bool extend;'
+ extend the ticks between two axes (useful for drawing a grid
+ on the graph);
+
+ `pen pTick'
+ an optional pen used to draw the major ticks;
+
+ `pen ptick'
+ an optional pen used to draw the minor ticks.
+
+
+ For convenience, the predefined tickmodifiers `OmitTick(... real[]
+ x)', `OmitTickInterval(real a, real b)', and
+ `OmitTickIntervals(real[] a, real[] b)' can be used to remove
+ specific auto-generated ticks and their labels. The
+ `OmitFormat(string s=defaultformat ... real[] x)' ticklabel can be
+ used to remove specific tick labels but not the corresponding
+ ticks. The tickmodifier `NoZero' is an abbreviation for
+ `OmitTick(0)' and the ticklabel `NoZeroFormat' is an abbrevation
+ for `OmitFormat(0)'.
+
+ It is also possible to specify custom tick locations with
+ `LeftTicks', `RightTicks', and `Ticks' by passing explicit real
+ arrays `Ticks' and (optionally) `ticks' containing the locations
+ of the major and minor ticks, respectively: ticks LeftTicks(Label format="", ticklabel ticklabel=null,
+ bool beginlabel=true, bool endlabel=true,
+ real[] Ticks, real[] ticks=new real[],
+ real Size=0, real size=0, bool extend=false,
+ pen pTick=nullpen, pen ptick=nullpen)
+
+ * void yaxis(picture pic=currentpicture, Label L="", axis axis=XZero,
+ real ymin=-infinity, real ymax=infinity, pen p=currentpen,
+ ticks ticks=NoTicks, arrowbar arrow=None, bool above=false,
+ bool autorotate=true);
+
+ Draw a y axis on picture `pic' from y=`ymin' to y=`ymax' using pen
+ `p', optionally labelling it with a Label `L' that is autorotated
+ unless `autorotate=false'. The relative location of the label (a
+ real number from [0,1]) defaults to 1 (*note Label::). An infinite
+ value of `ymin' or `ymax' specifies that the corresponding axis
+ limit will be automatically determined from the picture limits.
+ The optional `arrow' argument takes the same values as in the
+ `draw' command (*note arrows::). The axis is drawn before any
+ existing objects in `pic' unless `above=true'. The tick type is
+ specified by `ticks' and the axis placement is determined by one
+ of the following `axis' types:
+
+ `XZero(bool extend=true)'
+ Request a y axis at x=0 (or x=1 on a logarithmic axis)
+ extending to the full dimensions of the picture, unless
+ `extend'=false.
+
+ `XEquals(real X, bool extend=true)'
+ Request a y axis at x=`X' extending to the full dimensions of
+ the picture, unless `extend'=false.
+
+ `Left(bool extend=false)'
+ Request a left axis.
+
+ `Right(bool extend=false)'
+ Request a right axis.
+
+ `LeftRight(bool extend=false)'
+ Request a left and right axis.
+
+
+ * For convenience, the functions void xequals(picture pic=currentpicture, Label L="", real x,
+ bool extend=false, real ymin=-infinity, real ymax=infinity,
+ pen p=currentpen, ticks ticks=NoTicks, bool above=true,
+ arrowbar arrow=None);
+ and void yequals(picture pic=currentpicture, Label L="", real y,
+ bool extend=false, real xmin=-infinity, real xmax=infinity,
+ pen p=currentpen, ticks ticks=NoTicks, bool above=true,
+ arrowbar arrow=None);
+ can be respectively used to call `yaxis' and `xaxis' with the
+ appropriate axis types `XEquals(x,extend)' and
+ `YEquals(y,extend)'. This is the recommended way of drawing
+ vertical or horizontal lines and axes at arbitrary locations.
+
+ * void axes(picture pic=currentpicture, Label xlabel="", Label ylabel="",
+ bool extend=true,
+ pair min=(-infinity,-infinity), pair max=(infinity,infinity),
+ pen p=currentpen, arrowbar arrow=None, bool above=false);
+ This convenience routine draws both x and y axes on picture `pic'
+ from `min' to `max', with optional labels `xlabel' and `ylabel'
+ and any arrows specified by `arrow'. The axes are drawn on top of
+ existing objects in `pic' only if `above=true'.
+
+ * void axis(picture pic=currentpicture, Label L="", path g,
+ pen p=currentpen, ticks ticks, ticklocate locate,
+ arrowbar arrow=None, int[] divisor=new int[],
+ bool above=false, bool opposite=false);
+
+ This routine can be used to draw on picture `pic' a general axis
+ based on an arbitrary path `g', using pen `p'. One can optionally
+ label the axis with Label `L' and add an arrow `arrow'. The tick
+ type is given by `ticks'. The optional integer array `divisor'
+ specifies what tick divisors to try in the attempt to produce
+ uncrowded tick labels. A `true' value for the flag `opposite'
+ identifies an unlabelled secondary axis (typically drawn opposite
+ a primary axis). The axis is drawn before any existing objects in
+ `pic' unless `above=true'. The tick locator `ticklocate' is
+ constructed by the routine ticklocate ticklocate(real a, real b, autoscaleT S=defaultS,
+ real tickmin=-infinity, real tickmax=infinity,
+ real time(real)=null, pair dir(real)=zero);
+ where `a' and `b' specify the respective tick values at
+ `point(g,0)' and `point(g,length(g))', `S' specifies the
+ autoscaling transformation, the function `real time(real v)'
+ returns the time corresponding to the value `v', and `pair
+ dir(real t)' returns the absolute tick direction as a function of
+ `t' (zero means draw the tick perpendicular to the axis).
+
+ * These routines are useful for manually putting ticks and labels on
+ axes (if the variable `Label' is given as the `Label' argument,
+ the `format' argument will be used to format a string based on the
+ tick location): void xtick(picture pic=currentpicture, Label L="", explicit pair z,
+ pair dir=N, string format="",
+ real size=Ticksize, pen p=currentpen);
+ void xtick(picture pic=currentpicture, Label L="", real x,
+ pair dir=N, string format="",
+ real size=Ticksize, pen p=currentpen);
+ void ytick(picture pic=currentpicture, Label L="", explicit pair z,
+ pair dir=E, string format="",
+ real size=Ticksize, pen p=currentpen);
+ void ytick(picture pic=currentpicture, Label L="", real y,
+ pair dir=E, string format="",
+ real size=Ticksize, pen p=currentpen);
+ void tick(picture pic=currentpicture, pair z,
+ pair dir, real size=Ticksize, pen p=currentpen);
+ void labelx(picture pic=currentpicture, Label L="", explicit pair z,
+ align align=S, string format="", pen p=currentpen);
+ void labelx(picture pic=currentpicture, Label L="", real x,
+ align align=S, string format="", pen p=currentpen);
+ void labelx(picture pic=currentpicture, Label L,
+ string format="", explicit pen p=currentpen);
+ void labely(picture pic=currentpicture, Label L="", explicit pair z,
+ align align=W, string format="", pen p=currentpen);
+ void labely(picture pic=currentpicture, Label L="", real y,
+ align align=W, string format="", pen p=currentpen);
+ void labely(picture pic=currentpicture, Label L,
+ string format="", explicit pen p=currentpen);
+
+ Here are some simple examples of two-dimensional graphs:
+
+ 1. This example draws a textbook-style graph of y= exp(x), with the y
+ axis starting at y=0: import graph;
+ size(150,0);
+
+ real f(real x) {return exp(x);}
+ pair F(real x) {return (x,f(x));}
+
+ xaxis("$x$");
+ yaxis("$y$",0);
+
+ draw(graph(f,-4,2,operator ..),red);
+
+ labely(1,E);
+ label("$e^x$",F(1),SE);
+
+
+
+ 2. The next example draws a scientific-style graph with a legend.
+ The position of the legend can be adjusted either explicitly or by
+ using the graphical user interface `xasy' (*note GUI::). If an
+ `UnFill(real xmargin=0, real ymargin=xmargin)' or `Fill(pen)'
+ option is specified to `add', the legend will obscure any
+ underlying objects. Here we illustrate how to clip the portion of
+ the picture covered by a label:
+
+ import graph;
+
+ size(400,200,IgnoreAspect);
+
+ real Sin(real t) {return sin(2pi*t);}
+ real Cos(real t) {return cos(2pi*t);}
+
+ draw(graph(Sin,0,1),red,"$\sin(2\pi x)$");
+ draw(graph(Cos,0,1),blue,"$\cos(2\pi x)$");
+
+ xaxis("$x$",BottomTop,LeftTicks);
+ yaxis("$y$",LeftRight,RightTicks(trailingzero));
+
+ label("LABEL",point(0),UnFill(1mm));
+
+ add(legend(),point(E),20E,UnFill);
+
+
+
+ To specify a fixed size for the graph proper, use `attach': import graph;
+
+ size(250,200,IgnoreAspect);
+
+ real Sin(real t) {return sin(2pi*t);}
+ real Cos(real t) {return cos(2pi*t);}
+
+ draw(graph(Sin,0,1),red,"$\sin(2\pi x)$");
+ draw(graph(Cos,0,1),blue,"$\cos(2\pi x)$");
+
+ xaxis("$x$",BottomTop,LeftTicks);
+ yaxis("$y$",LeftRight,RightTicks(trailingzero));
+
+ label("LABEL",point(0),UnFill(1mm));
+
+ attach(legend(),truepoint(E),20E,UnFill);
+ A legend can have multiple entries per line: import graph;
+ size(8cm,6cm,IgnoreAspect);
+
+ typedef real realfcn(real);
+ realfcn F(real p) {
+ return new real(real x) {return sin(p*x);};
+ };
+
+ for(int i=1; i < 5; ++i)
+ draw(graph(F(i*pi),0,1),Pen(i),
+ "$\sin("+(i == 1 ? "" : (string) i)+"\pi x)$");
+ xaxis("$x$",BottomTop,LeftTicks);
+ yaxis("$y$",LeftRight,RightTicks(trailingzero));
+
+ attach(legend(2),(point(S).x,truepoint(S).y),10S,UnFill);
+
+
+
+ 3. This example draws a graph of one array versus another (both of
+ the same size) using custom tick locations and a smaller font size
+ for the tick labels on the y axis. import graph;
+
+ size(200,150,IgnoreAspect);
+
+ real[] x={0,1,2,3};
+ real[] y=x^2;
+
+ draw(graph(x,y),red);
+
+ xaxis("$x$",BottomTop,LeftTicks);
+ yaxis("$y$",LeftRight,
+ RightTicks(Label(fontsize(8pt)),new real[]{0,4,9}));
+
+
+
+ 4. This example shows how to graph columns of data read from a file. import graph;
+
+ size(200,150,IgnoreAspect);
+
+ file in=input("filegraph.dat").line();
+ real[][] a=in.dimension(0,0);
+ a=transpose(a);
+
+ real[] x=a[0];
+ real[] y=a[1];
+
+ draw(graph(x,y),red);
+
+ xaxis("$x$",BottomTop,LeftTicks);
+ yaxis("$y$",LeftRight,RightTicks);
+
+
+
+ 5. The next example draws two graphs of an array of coordinate pairs,
+ using frame alignment and data markers. In the left-hand graph, the
+ markers, constructed with marker marker(path g, markroutine markroutine=marknodes,
+ pen p=currentpen, filltype filltype=NoFill,
+ bool above=true);
+ using the path `unitcircle' (*note filltype::), are drawn below
+ each node. Any frame can be converted to a marker, using marker marker(frame f, markroutine markroutine=marknodes,
+ bool above=true);
+ In the right-hand graph, the unit n-sided regular polygon
+ `polygon(int n)' and the unit n-point cyclic cross `cross(int n,
+ bool round=true, real r=0)' (where `r' is an optional "inner"
+ radius) are used to build a custom marker frame. Here
+ `markuniform(bool centered=false, int n, bool rotated=false)' adds
+ this frame at `n' uniformly spaced points along the arclength of
+ the path, optionally rotated by the angle of the local tangent to
+ the path (if centered is true, the frames will be centered within
+ `n' evenly spaced arclength intervals). Alternatively, one can use
+ markroutine `marknodes' to request that the marks be placed at each
+ Bezier node of the path, or markroutine `markuniform(pair z(real
+ t), real a, real b, int n)' to place marks at points `z(t)' for n
+ evenly spaced values of `t' in `[a,b]'.
+
+ These markers are predefined: marker[] Mark={
+ marker(scale(circlescale)*unitcircle),
+ marker(polygon(3)),marker(polygon(4)),
+ marker(polygon(5)),marker(invert*polygon(3)),
+ marker(cross(4)),marker(cross(6))
+ };
+
+ marker[] MarkFill={
+ marker(scale(circlescale)*unitcircle,Fill),marker(polygon(3),Fill),
+ marker(polygon(4),Fill),marker(polygon(5),Fill),
+ marker(invert*polygon(3),Fill)
+ };
+
+ The example also illustrates the `errorbar' routines:
+
+ void errorbars(picture pic=currentpicture, pair[] z, pair[] dp,
+ pair[] dm={}, bool[] cond={}, pen p=currentpen,
+ real size=0);
+
+ void errorbars(picture pic=currentpicture, real[] x, real[] y,
+ real[] dpx, real[] dpy, real[] dmx={}, real[] dmy={},
+ bool[] cond={}, pen p=currentpen, real size=0);
+
+ Here, the positive and negative extents of the error are given by
+ the absolute values of the elements of the pair array `dp' and the
+ optional pair array `dm'. If `dm' is not specified, the positive
+ and negative extents of the error are assumed to be equal. import graph;
+
+ picture pic;
+ real xsize=200, ysize=140;
+ size(pic,xsize,ysize,IgnoreAspect);
+
+ pair[] f={(5,5),(50,20),(90,90)};
+ pair[] df={(0,0),(5,7),(0,5)};
+
+ errorbars(pic,f,df,red);
+ draw(pic,graph(pic,f),"legend",
+ marker(scale(0.8mm)*unitcircle,red,FillDraw(blue),above=false));
+
+ scale(pic,true);
+
+ xaxis(pic,"$x$",BottomTop,LeftTicks);
+ yaxis(pic,"$y$",LeftRight,RightTicks);
+ add(pic,legend(pic),point(pic,NW),20SE,UnFill);
+
+ picture pic2;
+ size(pic2,xsize,ysize,IgnoreAspect);
+
+ frame mark;
+ filldraw(mark,scale(0.8mm)*polygon(6),green,green);
+ draw(mark,scale(0.8mm)*cross(6),blue);
+
+ draw(pic2,graph(pic2,f),marker(mark,markuniform(5)));
+
+ scale(pic2,true);
+
+ xaxis(pic2,"$x$",BottomTop,LeftTicks);
+ yaxis(pic2,"$y$",LeftRight,RightTicks);
+
+ yequals(pic2,55.0,red+Dotted);
+ xequals(pic2,70.0,red+Dotted);
+
+ // Fit pic to W of origin:
+ add(pic.fit(),(0,0),W);
+
+ // Fit pic2 to E of (5mm,0):
+ add(pic2.fit(),(5mm,0),E);
+
+
+
+ 6. A custom mark routine can be also be specified: import graph;
+
+ size(200,100,IgnoreAspect);
+
+ markroutine marks() {
+ return new void(picture pic=currentpicture, frame f, path g) {
+ path p=scale(1mm)*unitcircle;
+ for(int i=0; i <= length(g); ++i) {
+ pair z=point(g,i);
+ frame f;
+ if(i % 4 == 0) {
+ fill(f,p);
+ add(pic,f,z);
+ } else {
+ if(z.y > 50) {
+ pic.add(new void(frame F, transform t) {
+ path q=shift(t*z)*p;
+ unfill(F,q);
+ draw(F,q);
+ });
+ } else {
+ draw(f,p);
+ add(pic,f,z);
+ }
+ }
+ }
+ };
+ }
+
+ pair[] f={(5,5),(40,20),(55,51),(90,30)};
+
+ draw(graph(f),marker(marks()));
+
+ scale(true);
+
+ xaxis("$x$",BottomTop,LeftTicks);
+ yaxis("$y$",LeftRight,RightTicks);
+
+
+
+ 7. This example shows how to label an axis with arbitrary strings. import graph;
+
+ size(400,150,IgnoreAspect);
+
+ real[] x=sequence(12);
+ real[] y=sin(2pi*x/12);
+
+ scale(false);
+
+ string[] month={"Jan","Feb","Mar","Apr","May","Jun",
+ "Jul","Aug","Sep","Oct","Nov","Dec"};
+
+ draw(graph(x,y),red,MarkFill[0]);
+
+ xaxis(BottomTop,LeftTicks(new string(real x) {
+ return month[round(x % 12)];}));
+ yaxis("$y$",LeftRight,RightTicks(4));
+
+
+
+ 8. The next example draws a graph of a parametrized curve. The calls
+ to xlimits(picture pic=currentpicture, real min=-infinity,
+ real max=infinity, bool crop=NoCrop);
+ and the analogous function `ylimits' can be uncommented to set
+ the respective axes limits for picture `pic' to the specified
+ `min' and `max' values. Alternatively, the function void limits(picture pic=currentpicture, pair min, pair max, bool crop=NoCrop);
+ can be used to limit the axes to the box having opposite vertices
+ at the given pairs). Existing objects in picture `pic' will be
+ cropped to lie within the given limits if `crop'=`Crop'. The
+ function `crop(picture pic)' can be used to crop a graph to the
+ current graph limits. import graph;
+
+ size(0,200);
+
+ real x(real t) {return cos(2pi*t);}
+ real y(real t) {return sin(2pi*t);}
+
+ draw(graph(x,y,0,1));
+
+ //limits((0,-1),(1,0),Crop);
+
+ xaxis("$x$",BottomTop,LeftTicks);
+ yaxis("$y$",LeftRight,RightTicks(trailingzero));
+
+
+
+ The next example illustrates how one can extract a common axis
+ scaling factor. import graph;
+
+ axiscoverage=0.9;
+ size(200,IgnoreAspect);
+
+ real[] x={-1e-11,1e-11};
+ real[] y={0,1e6};
+
+ real xscale=round(log10(max(x)));
+ real yscale=round(log10(max(y)))-1;
+
+ draw(graph(x*10^(-xscale),y*10^(-yscale)),red);
+
+ xaxis("$x/10^{"+(string) xscale+"}$",BottomTop,LeftTicks);
+ yaxis("$y/10^{"+(string) yscale+"}$",LeftRight,RightTicks(trailingzero));
+
+
+
+ Axis scaling can be requested and/or automatic selection of the
+ axis limits can be inhibited with one of these `scale' routines: void scale(picture pic=currentpicture, scaleT x, scaleT y);
+
+ void scale(picture pic=currentpicture, bool xautoscale=true,
+ bool yautoscale=xautoscale, bool zautoscale=yautoscale);
+
+ This sets the scalings for picture `pic'. The `graph' routines
+ accept an optional `picture' argument for determining the
+ appropriate scalings to use; if none is given, it uses those set
+ for `currentpicture'.
+
+ Two frequently used scaling routines `Linear' and `Log' are
+ predefined in `graph'.
+
+ All picture coordinates (including those in paths and those given
+ to the `label' and `limits' functions) are always treated as linear
+ (post-scaled) coordinates. Use pair Scale(picture pic=currentpicture, pair z);
+ to convert a graph coordinate into a scaled picture coordinate.
+
+ The x and y components can be individually scaled using the
+ analogous routines real ScaleX(picture pic=currentpicture, real x);
+ real ScaleY(picture pic=currentpicture, real y);
+
+ The predefined scaling routines can be given two optional boolean
+ arguments: `automin=false' and `automax=automin'. These default to
+ `false' but can be respectively set to `true' to enable automatic
+ selection of "nice" axis minimum and maximum values. The `Linear'
+ scaling can also take as optional final arguments a multiplicative
+ scaling factor and intercept (e.g. for a depth axis, `Linear(-1)'
+ requests axis reversal).
+
+ For example, to draw a log/log graph of a function, use
+ `scale(Log,Log)': import graph;
+
+ size(200,200,IgnoreAspect);
+
+ real f(real t) {return 1/t;}
+
+ scale(Log,Log);
+
+ draw(graph(f,0.1,10));
+
+ //limits((1,0.1),(10,0.5),Crop);
+
+ dot(Label("(3,5)",align=S),Scale((3,5)));
+
+ xaxis("$x$",BottomTop,LeftTicks);
+ yaxis("$y$",LeftRight,RightTicks);
+
+
+
+ By extending the ticks, one can easily produce a logarithmic grid: import graph;
+ size(200,200,IgnoreAspect);
+
+ real f(real t) {return 1/t;}
+
+ scale(Log,Log);
+ draw(graph(f,0.1,10),red);
+ pen thin=linewidth(0.5*linewidth());
+ xaxis("$x$",BottomTop,LeftTicks(begin=false,end=false,extend=true,
+ ptick=thin));
+ yaxis("$y$",LeftRight,RightTicks(begin=false,end=false,extend=true,
+ ptick=thin));
+
+
+
+ One can also specify custom tick locations and formats for
+ logarithmic axes: import graph;
+
+ size(300,175,IgnoreAspect);
+ scale(Log,Log);
+ draw(graph(identity,5,20));
+ xlimits(5,20);
+ ylimits(1,100);
+ xaxis("$M/M_\odot$",BottomTop,LeftTicks(DefaultFormat,
+ new real[] {6,10,12,14,16,18}));
+ yaxis("$\nu_{\rm upp}$ [Hz]",LeftRight,RightTicks(DefaultFormat));
+
+
+
+ It is easy to draw logarithmic graphs with respect to other bases: import graph;
+ size(200,IgnoreAspect);
+
+ // Base-2 logarithmic scale on y-axis:
+
+ real log2(real x) {static real log2=log(2); return log(x)/log2;}
+ real pow2(real x) {return 2^x;}
+
+ scaleT yscale=scaleT(log2,pow2,logarithmic=true);
+ scale(Linear,yscale);
+
+ real f(real x) {return 1+x^2;}
+
+ draw(graph(f,-4,4));
+
+ yaxis("$y$",ymin=1,ymax=f(5),RightTicks(Label(Fill(white))),EndArrow);
+ xaxis("$x$",xmin=-5,xmax=5,LeftTicks,EndArrow);
+
+
+
+ Here is an example of "broken" linear x and logarithmic y axes
+ that omit the segments [3,8] and [100,1000], respectively. In the
+ case of a logarithmic axis, the break endpoints are automatically
+ rounded to the nearest integral power of the base. import graph;
+
+ size(200,150,IgnoreAspect);
+
+ // Break the x axis at 3; restart at 8:
+ real a=3, b=8;
+
+ // Break the y axis at 100; restart at 1000:
+ real c=100, d=1000;
+
+ scale(Broken(a,b),BrokenLog(c,d));
+
+ real[] x={1,2,4,6,10};
+ real[] y=x^4;
+
+ draw(graph(x,y),red,MarkFill[0]);
+
+ xaxis("$x$",BottomTop,LeftTicks(Break(a,b)));
+ yaxis("$y$",LeftRight,RightTicks(Break(c,d)));
+
+ label(rotate(90)*Break,(a,point(S).y));
+ label(rotate(90)*Break,(a,point(N).y));
+ label(Break,(point(W).x,ScaleY(c)));
+ label(Break,(point(E).x,ScaleY(c)));
+
+
+
+ 9. `Asymptote' can draw secondary axes with the routines picture secondaryX(picture primary=currentpicture, void f(picture));
+ picture secondaryY(picture primary=currentpicture, void f(picture));
+
+ In this example, `secondaryY' is used to draw a secondary linear y
+ axis against a primary logarithmic y axis: import graph;
+ texpreamble("\def\Arg{\mathop {\rm Arg}\nolimits}");
+
+ size(10cm,5cm,IgnoreAspect);
+
+ real ampl(real x) {return 2.5/(1+x^2);}
+ real phas(real x) {return -atan(x)/pi;}
+
+ scale(Log,Log);
+ draw(graph(ampl,0.01,10));
+ ylimits(0.001,100);
+
+ xaxis("$\omega\tau_0$",BottomTop,LeftTicks);
+ yaxis("$|G(\omega\tau_0)|$",Left,RightTicks);
+
+ picture q=secondaryY(new void(picture pic) {
+ scale(pic,Log,Linear);
+ draw(pic,graph(pic,phas,0.01,10),red);
+ ylimits(pic,-1.0,1.5);
+ yaxis(pic,"$\Arg G/\pi$",Right,red,
+ LeftTicks("$% #.1f$",
+ begin=false,end=false));
+ yequals(pic,1,Dotted);
+ });
+ label(q,"(1,0)",Scale(q,(1,0)),red);
+ add(q);
+
+
+
+ A secondary logarithmic y axis can be drawn like this: import graph;
+
+ size(9cm,6cm,IgnoreAspect);
+ string data="secondaryaxis.csv";
+
+ file in=input(data).line().csv();
+
+ string[] titlelabel=in;
+ string[] columnlabel=in;
+
+ real[][] a=in.dimension(0,0);
+ a=transpose(a);
+ real[] t=a[0], susceptible=a[1], infectious=a[2], dead=a[3], larvae=a[4];
+ real[] susceptibleM=a[5], exposed=a[6],infectiousM=a[7];
+
+ scale(true);
+
+ draw(graph(t,susceptible,t >= 10 & t <= 15));
+ draw(graph(t,dead,t >= 10 & t <= 15),dashed);
+
+ xaxis("Time ($\tau$)",BottomTop,LeftTicks);
+ yaxis(Left,RightTicks);
+
+ picture secondary=secondaryY(new void(picture pic) {
+ scale(pic,Linear(true),Log(true));
+ draw(pic,graph(pic,t,infectious,t >= 10 & t <= 15),red);
+ yaxis(pic,Right,red,LeftTicks(begin=false,end=false));
+ });
+
+ add(secondary);
+ label(shift(5mm*N)*"Proportion of crows",point(NW),E);
+
+
+
+ 10. Here is a histogram example, which uses the `stats' module. import graph;
+ import stats;
+
+ size(400,200,IgnoreAspect);
+
+ int n=10000;
+ real[] a=new real[n];
+ for(int i=0; i < n; ++i) a[i]=Gaussrand();
+
+ draw(graph(Gaussian,min(a),max(a)),blue);
+
+ // Optionally calculate "optimal" number of bins a la Shimazaki and Shinomoto.
+ int N=bins(a);
+
+ histogram(a,min(a),max(a),N,normalize=true,low=0,lightred,black,bars=false);
+
+ xaxis("$x$",BottomTop,LeftTicks);
+ yaxis("$dP/dx$",LeftRight,RightTicks(trailingzero));
+
+
+
+ 11. Here is an example of reading column data in from a file and a
+ least-squares fit, using the `stats' module. size(400,200,IgnoreAspect);
+
+ import graph;
+ import stats;
+
+ file fin=input("leastsquares.dat").line();
+
+ real[][] a=fin.dimension(0,0);
+ a=transpose(a);
+
+ real[] t=a[0], rho=a[1];
+
+ // Read in parameters from the keyboard:
+ //real first=getreal("first");
+ //real step=getreal("step");
+ //real last=getreal("last");
+
+ real first=100;
+ real step=50;
+ real last=700;
+
+ // Remove negative or zero values of rho:
+ t=rho > 0 ? t : null;
+ rho=rho > 0 ? rho : null;
+
+ scale(Log(true),Linear(true));
+
+ int n=step > 0 ? ceil((last-first)/step) : 0;
+
+ real[] T,xi,dxi;
+
+ for(int i=0; i <= n; ++i) {
+ real first=first+i*step;
+ real[] logrho=(t >= first & t <= last) ? log(rho) : null;
+ real[] logt=(t >= first & t <= last) ? -log(t) : null;
+
+ if(logt.length < 2) break;
+
+ // Fit to the line logt=L.m*logrho+L.b:
+ linefit L=leastsquares(logt,logrho);
+
+ T.push(first);
+ xi.push(L.m);
+ dxi.push(L.dm);
+ }
+
+ draw(graph(T,xi),blue);
+ errorbars(T,xi,dxi,red);
+
+ crop();
+
+ ylimits(0);
+
+ xaxis("$T$",BottomTop,LeftTicks);
+ yaxis("$\xi$",LeftRight,RightTicks);
+
+
+
+ 12. Here is an example that illustrates the general `axis' routine. import graph;
+ size(0,100);
+
+ path g=ellipse((0,0),1,2);
+
+ scale(true);
+
+ axis(Label("C",align=10W),g,LeftTicks(endlabel=false,8,end=false),
+ ticklocate(0,360,new real(real v) {
+ path h=(0,0)--max(abs(max(g)),abs(min(g)))*dir(v);
+ return intersect(g,h)[0];}));
+
+
+
+ 13. To draw a vector field of `n' arrows evenly spaced along the
+ arclength of a path, use the routine picture vectorfield(path vector(real), path g, int n, bool truesize=false,
+ pen p=currentpen, arrowbar arrow=Arrow);
+ as illustrated in this simple example of a flow field: import graph;
+ defaultpen(1.0);
+
+ size(0,150,IgnoreAspect);
+
+ real arrowsize=4mm;
+ real arrowlength=2arrowsize;
+
+ typedef path vector(real);
+
+ // Return a vector interpolated linearly between a and b.
+ vector vector(pair a, pair b) {
+ return new path(real x) {
+ return (0,0)--arrowlength*interp(a,b,x);
+ };
+ }
+
+ real f(real x) {return 1/x;}
+
+ real epsilon=0.5;
+ path g=graph(f,epsilon,1/epsilon);
+
+ int n=3;
+ draw(g);
+ xaxis("$x$");
+ yaxis("$y$");
+
+ add(vectorfield(vector(W,W),g,n,true));
+ add(vectorfield(vector(NE,NW),(0,0)--(point(E).x,0),n,true));
+ add(vectorfield(vector(NE,NE),(0,0)--(0,point(N).y),n,true));
+
+
+
+ 14. To draw a vector field of `nx'\times`ny' arrows in `box(a,b)', use
+ the routine picture vectorfield(path vector(pair), pair a, pair b,
+ int nx=nmesh, int ny=nx, bool truesize=false,
+ real maxlength=truesize ? 0 : maxlength(a,b,nx,ny),
+ bool cond(pair z)=null, pen p=currentpen,
+ arrowbar arrow=Arrow, margin margin=PenMargin)
+ as illustrated in this example: import graph;
+ size(100);
+
+ pair a=(0,0);
+ pair b=(2pi,2pi);
+
+ path vector(pair z) {return (0,0)--(sin(z.x),cos(z.y));}
+
+ add(vectorfield(vector,a,b));
+
+
+
+ 15. The following scientific graphs, which illustrate many features of
+ `Asymptote''s graphics routines, were generated from the examples
+ `diatom.asy' and `westnile.asy', using the comma-separated data in
+ `diatom.csv' and `westnile.csv'.
+
+
+
+File: asymptote.info, Node: palette, Next: three, Prev: graph, Up: Base modules
+
+8.28 `palette'
+==============
+
+`Asymptote' can also generate color density images and palettes. The
+following palettes are predefined in `palette.asy':
+
+`pen[] Grayscale(int NColors=256)'
+ a grayscale palette;
+
+`pen[] Rainbow(int NColors=32766)'
+ a rainbow spectrum;
+
+`pen[] BWRainbow(int NColors=32761)'
+ a rainbow spectrum tapering off to black/white at the ends;
+
+`pen[] BWRainbow2(int NColors=32761)'
+ a double rainbow palette tapering off to black/white at the ends,
+ with a linearly scaled intensity.
+
+`pen[] Wheel(int NColors=32766)'
+ a full color wheel palette;
+
+`pen[] Gradient(int NColors=256 ... pen[] p)'
+ a palette varying linearly over the specified array of pens, using
+ NColors in each interpolation interval;
+
+
+ The function `cmyk(pen[] Palette)' may be used to convert any of
+these palettes to the CMYK colorspace.
+
+ A color density plot using palette `palette' can be generated from a
+function `f'(x,y) and added to a picture `pic':
+bounds image(picture pic=currentpicture, real f(real, real),
+ range range=Full, pair initial, pair final,
+ int nx=ngraph, int ny=nx, pen[] palette, bool antialias=false)
+ The function `f' will be sampled at `nx' and `ny' evenly spaced points
+over a rectangle defined by the points `initial' and `final',
+respecting the current graphical scaling of `pic'. The color space is
+scaled according to the z axis scaling (*note automatic scaling::). A
+bounds structure for the function values is returned:
+struct bounds {
+ real min;
+ real max;
+ // Possible tick intervals:
+ int[] divisor;
+}
+ This information can be used for generating an optional palette bar.
+The palette color space corresponds to a range of values specified by
+the argument `range', which can be `Full', `Automatic', or an explicit
+range `Range(real min, real max)'. Here `Full' specifies a range
+varying from the minimum to maximum values of the function over the
+sampling interval, while `Automatic' selects "nice" limits. The
+example `imagecontour.asy' illustrates how level sets (contour lines)
+can be drawn on a color density plot (*note contour::).
+
+ A color density plot can also be generated from an explicit real[][]
+array `data':
+bounds image(picture pic=currentpicture, real[][] f, range range=Full,
+ pair initial, pair final, pen[] palette,
+ bool transpose=(initial.x < final.x && initial.y < final.y),
+ bool copy=true, bool antialias=false);
+ If the initial point is to the left and below the final point, by
+default the array indices are interpreted according to the Cartesian
+convention (first index: x, second index: y) rather than the usual
+matrix convention (first index: -y, second index: x).
+
+ To construct an image from an array of irregularly spaced points and
+an array of values `f' at these points, use one of the routines
+bounds image(picture pic=currentpicture, pair[] z, real[] f,
+ range range=Full, pen[] palette)
+bounds image(picture pic=currentpicture, real[] x, real[] y, real[] f,
+ range range=Full, pen[] palette)
+
+ An optionally labelled palette bar may be generated with the routine
+void palette(picture pic=currentpicture, Label L="", bounds bounds,
+ pair initial, pair final, axis axis=Right, pen[] palette,
+ pen p=currentpen, paletteticks ticks=PaletteTicks,
+ bool copy=true, bool antialias=false);
+ The color space of `palette' is taken to be over bounds `bounds' with
+scaling given by the z scaling of `pic'. The palette orientation is
+specified by `axis', which may be one of `Right', `Left', `Top', or
+`Bottom'. The bar is drawn over the rectangle from `initial' to
+`final'. The argument `paletteticks' is a special tick type (*note
+ticks::) that takes the following arguments:
+paletteticks PaletteTicks(Label format="", ticklabel ticklabel=null,
+ bool beginlabel=true, bool endlabel=true,
+ int N=0, int n=0, real Step=0, real step=0,
+ pen pTick=nullpen, pen ptick=nullpen);
+
+ The image and palette bar can be fit to a frame and added and
+optionally aligned to a picture at the desired location:
+
+size(12cm,12cm);
+
+import graph;
+import palette;
+
+int n=256;
+real ninv=2pi/n;
+real[][] v=new real[n][n];
+
+for(int i=0; i < n; ++i)
+ for(int j=0; j < n; ++j)
+ v[i][j]=sin(i*ninv)*cos(j*ninv);
+
+pen[] Palette=BWRainbow();
+
+picture bar;
+
+bounds range=image(v,(0,0),(1,1),Palette);
+palette(bar,"$A$",range,(0,0),(0.5cm,8cm),Right,Palette,
+ PaletteTicks("$%+#.1f$"));
+add(bar.fit(),point(E),30E);
+
+
+
+Here is an example that uses logarithmic scaling of the function values:
+
+import graph;
+import palette;
+
+size(10cm,10cm,IgnoreAspect);
+
+real f(real x, real y) {
+ return 0.9*pow10(2*sin(x/5+2*y^0.25)) + 0.1*(1+cos(10*log(y)));
+}
+
+scale(Linear,Log,Log);
+
+pen[] Palette=BWRainbow();
+
+bounds range=image(f,Automatic,(0,1),(100,100),nx=200,Palette);
+
+xaxis("$x$",BottomTop,LeftTicks,above=true);
+yaxis("$y$",LeftRight,RightTicks,above=true);
+
+palette("$f(x,y)$",range,(0,200),(100,250),Top,Palette,
+ PaletteTicks(ptick=linewidth(0.5*linewidth())));
+
+
+
+One can also draw an image directly from a two-dimensional pen array or
+a function `pen f(int, int)':
+void image(picture pic=currentpicture, pen[][] data,
+ pair initial, pair final,
+ bool transpose=(initial.x < final.x && initial.y < final.y),
+ bool copy=true, bool antialias=false);
+void image(picture pic=currentpicture, pen f(int, int), int width, int height,
+ pair initial, pair final,
+ bool transpose=(initial.x < final.x && initial.y < final.y),
+ bool antialias=false);
+ as illustrated in the following examples:
+
+size(200);
+
+import palette;
+
+int n=256;
+real ninv=2pi/n;
+pen[][] v=new pen[n][n];
+
+for(int i=0; i < n; ++i)
+ for(int j=0; j < n; ++j)
+ v[i][j]=rgb(0.5*(1+sin(i*ninv)),0.5*(1+cos(j*ninv)),0);
+
+image(v,(0,0),(1,1));
+
+
+
+import palette;
+
+size(200);
+
+real fracpart(real x) {return (x-floor(x));}
+
+pair pws(pair z) {
+ pair w=(z+exp(pi*I/5)/0.9)/(1+z/0.9*exp(-pi*I/5));
+ return exp(w)*(w^3-0.5*I);
+}
+
+int N=512;
+
+pair a=(-1,-1);
+pair b=(0.5,0.5);
+real dx=(b-a).x/N;
+real dy=(b-a).y/N;
+
+pen f(int u, int v) {
+ pair z=a+(u*dx,v*dy);
+ pair w=pws(z);
+ real phase=degrees(w,warn=false);
+ real modulus=w == 0 ? 0: fracpart(log(abs(w)));
+ return hsv(phase,1,sqrt(modulus));
+}
+
+image(f,N,N,(0,0),(300,300),antialias=true);
+
+
+
+For convenience, the module `palette' also defines functions that may
+be used to construct a pen array from a given function and palette:
+pen[] palette(real[] f, pen[] palette);
+pen[][] palette(real[][] f, pen[] palette);
+
+
+File: asymptote.info, Node: three, Next: obj, Prev: palette, Up: Base modules
+
+8.29 `three'
+============
+
+This module fully extends the notion of guides and paths in `Asymptote'
+to three dimensions. It introduces the new types guide3, path3, and
+surface. Guides in three dimensions are specified with the same syntax
+as in two dimensions except that triples `(x,y,z)' are used in place of
+pairs `(x,y)' for the nodes and direction specifiers. This
+generalization of John Hobby's spline algorithm is shape-invariant under
+three-dimensional rotation, scaling, and shifting, and reduces in the
+planar case to the two-dimensional algorithm used in `Asymptote',
+`MetaPost', and `MetaFont' [cf. J. C. Bowman, Proceedings in Applied
+Mathematics and Mechanics, 7:1, 2010021-2010022 (2007)].
+
+ For example, a unit circle in the XY plane may be filled and drawn
+like this:
+
+import three;
+
+size(100);
+
+path3 g=(1,0,0)..(0,1,0)..(-1,0,0)..(0,-1,0)..cycle;
+draw(g);
+draw(O--Z,red+dashed,Arrow3);
+draw(((-1,-1,0)--(1,-1,0)--(1,1,0)--(-1,1,0)--cycle));
+dot(g,red);
+
+
+and then distorted into a saddle:
+
+import three;
+
+size(100,0);
+path3 g=(1,0,0)..(0,1,1)..(-1,0,0)..(0,-1,1)..cycle;
+draw(g);
+draw(((-1,-1,0)--(1,-1,0)--(1,1,0)--(-1,1,0)--cycle));
+dot(g,red);
+
+
+Module `three' provides constructors for converting two-dimensional
+paths to three-dimensional ones, and vice-versa:
+path3 path3(path p, triple plane(pair)=XYplane);
+path path(path3 p, pair P(triple)=xypart);
+
+ A Bezier surface, the natural two-dimensional generalization of
+Bezier curves, is defined in `three_surface.asy' as a structure
+containing an array of Bezier patches. Surfaces may drawn with one of
+the routines
+void draw(picture pic=currentpicture, surface s, int nu=1, int nv=1,
+ material surfacepen=currentpen, pen meshpen=nullpen,
+ light light=currentlight, light meshlight=light, string name="",
+ render render=defaultrender);
+void draw(picture pic=currentpicture, surface s, int nu=1, int nv=1,
+ material[] surfacepen, pen meshpen,
+ light light=currentlight, light meshlight=light, string name="",
+ render render=defaultrender);
+void draw(picture pic=currentpicture, surface s, int nu=1, int nv=1,
+ material[] surfacepen, pen[] meshpen=nullpens,
+ light light=currentlight, light meshlight=light, string name="",
+ render render=defaultrender);
+
+ The parameters `nu' and `nv' specify the number of subdivisions for
+drawing optional mesh lines for each Bezier patch. The optional `name'
+parameter is used as a prefix for naming the surface patches in the PRC
+model tree. Here material is a structure defined in `three_light.asy':
+struct material {
+ pen[] p; // diffusepen,ambientpen,emissivepen,specularpen
+ real opacity;
+ real shininess;
+...
+}
+ These material properties are used to implement `OpenGL'-style
+lighting, based on the Phong-Blinn specular model. Sample Bezier
+surfaces are contained in the example files `BezierSurface.asy',
+`teapot.asy', and `parametricsurface.asy'. The structure `render'
+contains specialized rendering options documented at the beginning of
+module `three.asy'.
+
+ The examples `elevation.asy' and `sphericalharmonic.asy' illustrate
+how to draw a surface with patch-dependent colors. The examples
+`vertexshading' and `smoothelevation' illustrate vertex-dependent
+colors, which is supported for both `Asymptote''s native `OpenGL'
+renderer and two-dimensional projections. Since the PRC output format
+does not currently support vertex shading of Bezier surfaces, PRC
+patches are shaded with the mean of the four vertex colors.
+
+ A surface can be constructed from a cyclic `path3' with the
+constructor
+surface surface(path3 external, triple[] internal=new triple[],
+ triple[] normals=new triple[], pen[] colors=new pen[],
+ bool3 planar=default);
+ and then filled:
+draw(surface(path3(polygon(5))),red,nolight);
+draw(surface(unitcircle3),red,nolight);
+draw(surface(unitcircle3,new pen[] {red,green,blue,black}),nolight);
+ The last example constructs a patch with vertex-specific colors. A
+three-dimensional planar surface in the plane `plane' can be
+constructed from a two-dimensional cyclic path `g' with the constructor
+surface surface(path p, triple plane(pair)=XYplane);
+ and then filled:
+draw(surface((0,0)--E+2N--2E--E+N..0.2E..cycle),red);
+ Planar Bezier surfaces patches are constructed using Orest Shardt's
+`bezulate' routine, which decomposes (possibly nonsimply connected)
+regions bounded (according to the `zerowinding' fill rule) by simple
+cyclic paths (intersecting only at the endpoints) into subregions
+bounded by cyclic paths of length `4' or less.
+
+ A more efficient routine also exists for drawing tessellations
+composed of many 3D triangles, with specified vertices, and optional
+normals or vertex colors:
+void draw(picture pic=currentpicture, triple[] v, int[][] vi,
+ triple[] n={}, int[][] ni={}, material m=currentpen, pen[] p={},
+ int[][] pi={}, light light=currentlight);
+ Here, the triple array `v' lists the distinct vertices, while the
+array `vi' lists integer arrays of length 3 containing the indices of
+`v' corresponding to the vertices of each triangle. Similarly, the
+arguments `n' and `ni' contain optional normal data and `p' and `pi'
+contain optional pen vertex data. An example of this tessellation
+facility is given in `triangles.asy'.
+
+ Arbitrary thick three-dimensional curves and line caps (which the
+`OpenGL' standard does not require implementations to provide) are
+constructed with
+tube tube(path3 p, real width, render render=defaultrender);
+ this returns a tube structure representing a tube of diameter `width'
+centered approximately on `g'. The tube structure consists of a surface
+`s' and the actual tube center, path3 `center'. Drawing thick lines as
+tubes can be slow to render, especially with the `Adobe Reader'
+renderer. The setting `thick=false' can be used to disable this feature
+and force all lines to be drawn with `linewidth(0)' (one pixel wide,
+regardless of the resolution). By default, mesh and contour lines in
+three-dimensions are always drawn thin, unless an explicit line width
+is given in the pen parameter or the setting `thin' is set to `false'.
+The pens `thin()' and `thick()' defined in plain_pens.asy can also be
+used to override these defaults for specific draw commands.
+
+There are four choices for viewing 3D `Asymptote' output:
+ 1. Use the native `Asymptote' adaptive `OpenGL'-based renderer (with
+ the command-line option `-V' and the default settings
+ `outformat=""' and `render=-1'). If you encounter warnings from
+ your graphics card driver, try specifying `-glOptions=-indirect'
+ on the command line. On `UNIX' systems with graphics support for
+ multisampling, the sample width can be controlled with the setting
+ `multisample'. An initial screen position can be specified with
+ the pair setting `position', where negative values are interpreted
+ as relative to the corresponding maximum screen dimension. The
+ default settings import settings;
+ leftbutton=new string[] {"rotate","zoom","shift","pan"};
+ middlebutton=new string[] {"menu"};
+ rightbutton=new string[] {"zoom/menu","rotateX","rotateY","rotateZ"};
+ wheelup=new string[] {"zoomin"};
+ wheeldown=new string[] {"zoomout"};
+ bind the mouse buttons as follows:
+ * Left: rotate
+
+ * Shift Left: zoom
+
+ * Ctrl Left: shift viewport
+
+ * Alt Left: pan
+
+ * Middle: menu (must be unmodified; ignores Shift, Ctrl, and
+ Alt)
+
+ * Wheel Up: zoom in
+
+ * Wheel Down: zoom out
+
+ * Right: zoom/menu (must be unmodified)
+
+ * Right double click: menu
+
+ * Shift Right: rotate about the X axis
+
+ * Ctrl Right: rotate about the Y axis
+
+ * Alt Right: rotate about the Z axis
+
+ The keyboard shortcuts are:
+ * h: home
+
+ * f: toggle fitscreen
+
+ * x: spin about the X axis
+
+ * y: spin about the Y axis
+
+ * z: spin about the Z axis
+
+ * s: stop spinning
+
+ * m: rendering mode (solid/mesh/patch)
+
+ * e: export
+
+ * c: show camera parameters
+
+ * p: play animation
+
+ * r: reverse animation
+
+ * : step animation
+
+ * +: expand
+
+ * =: expand
+
+ * >: expand
+
+ * -: shrink
+
+ * _: shrink
+
+ * <: shrink
+
+ * q: exit
+
+ * Ctrl-q: exit
+
+ 2. Render the scene to a specified rasterized format `outformat' at
+ the resolution of `n' pixels per `bp', as specified by the setting
+ `render=n'. A negative value of `n' is interpreted as `|2n|' for
+ EPS and PDF formats and `|n|' for other formats. The default value
+ of `render' is -1. By default, the scene is internally rendered
+ at twice the specified resolution; this can be disabled by setting
+ `antialias=1'. High resolution rendering is done by tiling the
+ image. If your graphics card allows it, the rendering can be made
+ more efficient by increasing the maximum tile size `maxtile' to
+ your screen dimensions (indicated by `maxtile=(0,0)'. If your
+ video card generates unwanted black stripes in the output, try
+ setting the horizontal and vertical components of `maxtiles' to
+ something less than your screen dimensions. The tile size is also
+ limited by the setting `maxviewport', which restricts the maximum
+ width and height of the viewport. On `UNIX' systems some graphics
+ drivers support batch mode (`-noV') rendering in an iconified
+ window; this can be enabled with the setting `iconify=true'. Some
+ (broken) `UNIX' graphics drivers may require the command line
+ setting `-glOptions=-indirect', which requests (slower) indirect
+ rendering.
+
+ 3. Embed the 3D PRC format in a PDF file and view the resulting PDF
+ file with version `9.0' or later of `Adobe Reader'. In addition
+ to the default `settings.prc=true', this requires
+ `settings.outformat="pdf"', which can be specified by the command
+ line option `-f pdf', put in the `Asymptote' configuration file
+ (*note configuration file::), or specified in the script before
+ `three.asy' (or `graph3.asy') is imported. The `media9' LaTeX
+ package is also required (*note embed::). The example `pdb.asy'
+ illustrates how one can generate a list of predefined views (see
+ `100d.views'). A stationary preview image with a resolution of
+ `n' pixels per `bp' can be embedded with the setting `render=n';
+ this allows the file to be viewed with other `PDF' viewers.
+ Alternatively, the file `externalprc.tex' illustrates how the
+ resulting PRC and rendered image files can be extracted and
+ processed in a separate `LaTeX' file. However, see *note LaTeX
+ usage:: for an easier way to embed three-dimensional `Asymptote'
+ pictures within `LaTeX'. For specialized applications where only
+ the raw PRC file is required, specify `settings.outformat="prc"'.
+ The open-source PRC specification is available from
+ `http://livedocs.adobe.com/acrobat_sdk/9/Acrobat9_HTMLHelp/API_References/PRCReference/PRC_Format_Specification/'.
+
+ 4. Project the scene to a two-dimensional vector (EPS or PDF) format
+ with `render=0'. Only limited hidden surface removal facilities
+ are currently available with this approach (*note PostScript3D::).
+
+
+ Automatic picture sizing in three dimensions is accomplished with
+double deferred drawing. The maximal desired dimensions of the scene in
+each of the three dimensions can optionally be specified with the
+routine
+void size3(picture pic=currentpicture, real x, real y=x, real z=y,
+ bool keepAspect=pic.keepAspect);
+ The resulting simplex linear programming problem is then solved to
+produce a 3D version of a frame (actually implemented as a 3D picture).
+The result is then fit with another application of deferred drawing to
+the viewport dimensions corresponding to the usual two-dimensional
+picture `size' parameters. The global pair `viewportmargin' may be used
+to add horizontal and vertical margins to the viewport dimensions.
+Alternatively, a minimum `viewportsize' may be specified. A 3D picture
+`pic' can be explicitly fit to a 3D frame by calling
+frame pic.fit3(projection P=currentprojection);
+ and then added to picture `dest' about `position' with
+void add(picture dest=currentpicture, frame src, triple position=(0,0,0));
+
+ For convenience, the `three' module defines `O=(0,0,0)',
+`X=(1,0,0)', `Y=(0,1,0)', and `Z=(0,0,1)', along with a unitcircle in
+the XY plane:
+path3 unitcircle3=X..Y..-X..-Y..cycle;
+
+ A general (approximate) circle can be drawn perpendicular to the
+direction `normal' with the routine
+path3 circle(triple c, real r, triple normal=Z);
+
+ A circular arc centered at `c' with radius `r' from
+`c+r*dir(theta1,phi1)' to `c+r*dir(theta2,phi2)', drawing
+counterclockwise relative to the normal vector
+`cross(dir(theta1,phi1),dir(theta2,phi2))' if `theta2 > theta1' or if
+`theta2 == theta1' and `phi2 >= phi1', can be constructed with
+path3 arc(triple c, real r, real theta1, real phi1, real theta2, real phi2,
+ triple normal=O);
+ The normal must be explicitly specified if `c' and the endpoints are
+colinear. If `r' < 0, the complementary arc of radius `|r|' is
+constructed. For convenience, an arc centered at `c' from triple `v1'
+to `v2' (assuming `|v2-c|=|v1-c|') in the direction CCW
+(counter-clockwise) or CW (clockwise) may also be constructed with
+path3 arc(triple c, triple v1, triple v2, triple normal=O,
+ bool direction=CCW);
+ When high accuracy is needed, the routines `Circle' and `Arc' defined
+in `graph3' may be used instead. See *note GaussianSurface:: for an
+example of a three-dimensional circular arc.
+
+ The representation `O--O+u--O+u+v--O+v--cycle' of the plane passing
+through point `O' with normal `cross(u,v)' is returned by
+path3 plane(triple u, triple v, triple O=O);
+ A three-dimensional box with opposite vertices at triples `v1' and
+`v2' may be drawn with the function
+path3[] box(triple v1, triple v2);
+ For example, a unit box is predefined as
+path3[] unitbox=box(O,(1,1,1));
+ `Asymptote' also provides optimized definitions for the
+three-dimensional paths `unitsquare3' and `unitcircle3', along with the
+surfaces `unitdisk', `unitplane', `unitcube', `unitcylinder',
+`unitcone', `unitsolidcone', `unitfrustum(real t1, real t2)',
+`unitsphere', and `unithemisphere'.
+
+These projections to two dimensions are predefined:
+`oblique'
+
+`oblique(real angle)'
+ The point `(x,y,z)' is projected to `(x-0.5z,y-0.5z)'. If an
+ optional real argument is given, the negative z axis is drawn at
+ this angle in degrees. The projection `obliqueZ' is a synonym for
+ `oblique'.
+
+`obliqueX'
+
+`obliqueX(real angle)'
+ The point `(x,y,z)' is projected to `(y-0.5x,z-0.5x)'. If an
+ optional real argument is given, the negative x axis is drawn at
+ this angle in degrees.
+
+`obliqueY'
+
+`obliqueY(real angle)'
+ The point `(x,y,z)' is projected to `(x+0.5y,z+0.5y)'. If an
+ optional real argument is given, the positive y axis is drawn at
+ this angle in degrees.
+
+`orthographic(triple camera, triple up=Z, triple target=O,
+ real zoom=1, pair viewportshift=0, bool showtarget=true,
+ bool center=false)'
+ This projects from three to two dimensions using the view as seen
+ at a point infinitely far away in the direction `unit(camera)',
+ orienting the camera so that, if possible, the vector `up' points
+ upwards. Parallel lines are projected to parallel lines. The
+ bounding volume is expanded to include `target' if
+ `showtarget=true'. If `center=true', the target will be adjusted
+ to the center of the bounding volume.
+
+`orthographic(real x, real y, real z, triple up=Z, triple target=O,
+ real zoom=1, pair viewportshift=0, bool showtarget=true,
+ bool center=false)'
+ This is equivalent to orthographic((x,y,z),up,target,zoom,viewportshift,showtarget,center)
+
+ The routine triple camera(real alpha, real beta);
+ can be used to compute the camera position with the x axis below
+ the horizontal at angle `alpha', the y axis below the horizontal
+ at angle `beta', and the z axis up.
+
+`perspective(triple camera, triple up=Z, triple target=O,
+ real zoom=1, real angle=0, pair viewportshift=0,
+ bool showtarget=true, bool autoadjust=true,
+ bool center=autoadjust)'
+ This projects from three to two dimensions, taking account of
+ perspective, as seen from the location `camera' looking at
+ `target', orienting the camera so that, if possible, the vector
+ `up' points upwards. If `render=0', projection of
+ three-dimensional cubic Bezier splines is implemented by
+ approximating a two-dimensional nonuniform rational B-spline
+ (NURBS) with a two-dimensional Bezier curve containing additional
+ nodes and control points. If `autoadjust=true', the camera will
+ automatically be adjusted to lie outside the bounding volume for
+ all possible interactive rotations about `target'. If
+ `center=true', the target will be adjusted to the center of the
+ bounding volume.
+
+`perspective(real x, real y, real z, triple up=Z, triple target=O,
+ real zoom=1, real angle=0, pair viewportshift=0,
+ bool showtarget=true, bool autoadjust=true,
+ bool center=autoadjust)'
+ This is equivalent to perspective((x,y,z),up,target,zoom,angle,viewportshift,showtarget,
+ autoadjust,center)
+
+The default projection, `currentprojection', is initially set to
+`perspective(5,4,2)'.
+
+ We also define standard orthographic views used in technical drawing:
+projection LeftView=orthographic(-X,showtarget=true);
+projection RightView=orthographic(X,showtarget=true);
+projection FrontView=orthographic(-Y,showtarget=true);
+projection BackView=orthographic(Y,showtarget=true);
+projection BottomView=orthographic(-Z,showtarget=true);
+projection TopView=orthographic(Z,showtarget=true);
+ The function
+void addViews(picture dest=currentpicture, picture src,
+ projection[][] views=SixViewsUS,
+ bool group=true, filltype filltype=NoFill);
+ adds to picture `dest' an array of views of picture `src' using the
+layout projection[][] `views'. The default layout `SixViewsUS' aligns
+the projection `FrontView' below `TopView' and above `BottomView', to
+the right of `LeftView' and left of `RightView' and `BackView'. The
+predefined layouts are:
+projection[][] ThreeViewsUS={{TopView},
+ {FrontView,RightView}};
+
+projection[][] SixViewsUS={{null,TopView},
+ {LeftView,FrontView,RightView,BackView},
+ {null,BottomView}};
+
+projection[][] ThreeViewsFR={{RightView,FrontView},
+ {null,TopView}};
+
+projection[][] SixViewsFR={{null,BottomView},
+ {RightView,FrontView,LeftView,BackView},
+ {null,TopView}};
+
+projection[][] ThreeViews={{FrontView,TopView,RightView}};
+
+projection[][] SixViews={{FrontView,TopView,RightView},
+ {BackView,BottomView,LeftView}};
+
+ A triple or path3 can be projected to a pair or path, with
+`project(triple, projection P=currentprojection)' or `project(path3,
+projection P=currentprojection)'.
+
+ It is occasionally useful to be able to invert a projection, sending
+a pair `z' onto the plane perpendicular to `normal' and passing through
+`point':
+triple invert(pair z, triple normal, triple point,
+ projection P=currentprojection);
+ A pair `z' on the projection plane can be inverted to a triple with
+the routine
+triple invert(pair z, projection P=currentprojection);
+ A pair direction `dir' on the projection plane can be inverted to a
+triple direction relative to a point `v' with the routine
+triple invert(pair dir, triple v, projection P=currentprojection).
+
+ Three-dimensional objects may be transformed with one of the
+following built-in transform3 types (the identity transformation is
+`identity4'):
+
+`shift(triple v)'
+ translates by the triple `v';
+
+`xscale3(real x)'
+ scales by `x' in the x direction;
+
+`yscale3(real y)'
+ scales by `y' in the y direction;
+
+`zscale3(real z)'
+ scales by `z' in the z direction;
+
+`scale3(real s)'
+ scales by `s' in the x, y, and z directions;
+
+`scale(real x, real y, real z)'
+ scales by `x' in the x direction, by `y' in the y direction, and
+ by `z' in the z direction;
+
+`rotate(real angle, triple v)'
+ rotates by `angle' in degrees about an axis `v' through the origin;
+
+`rotate(real angle, triple u, triple v)'
+ rotates by `angle' in degrees about the axis `u--v';
+
+`reflect(triple u, triple v, triple w)'
+ reflects about the plane through `u', `v', and `w'.
+
+ When not multiplied on the left by a transform3, three-dimensional
+TeX Labels are drawn as Bezier surfaces directly on the projection
+plane:
+void label(picture pic=currentpicture, Label L, triple position,
+ align align=NoAlign, pen p=currentpen,
+ light light=nolight, string name="",
+ render render=defaultrender, interaction interaction=
+ settings.autobillboard ? Billboard : Embedded)
+ The optional `name' parameter is used as a prefix for naming the label
+patches in the PRC model tree. The default interaction is `Billboard',
+which means that labels are rotated interactively so that they always
+face the camera. The interaction `Embedded' means that the label
+interacts as a normal `3D' surface, as illustrated in the example
+`billboard.asy'. Alternatively, a label can be transformed from the
+`XY' plane by an explicit transform3 or mapped to a specified
+two-dimensional plane with the predefined transform3 types `XY', `YZ',
+`ZX', `YX', `ZY', `ZX'. There are also modified versions of these
+transforms that take an optional argument `projection
+P=currentprojection' that rotate and/or flip the label so that it is
+more readable from the initial viewpoint.
+
+ A transform3 that projects in the direction `dir' onto the plane
+with normal `n' through point `O' is returned by
+transform3 planeproject(triple n, triple O=O, triple dir=n);
+ One can use
+triple normal(path3 p);
+ to find the unit normal vector to a planar three-dimensional path `p'.
+As illustrated in the example `planeproject.asy', a transform3 that
+projects in the direction `dir' onto the plane defined by a planar path
+`p' is returned by
+transform3 planeproject(path3 p, triple dir=normal(p));
+
+ The functions
+surface extrude(path p, triple axis=Z);
+surface extrude(Label L, triple axis=Z);
+ return the surface obtained by extruding path `p' or Label `L' along
+`axis'.
+
+ Three-dimensional versions of the path functions `length', `size',
+`point', `dir', `accel', `radius', `precontrol', `postcontrol',
+`arclength', `arctime', `reverse', `subpath', `intersect',
+`intersections', `intersectionpoint', `intersectionpoints', `min',
+`max', `cyclic', and `straight' are also defined.
+
+ The routine
+real[][] intersections(path3 p, surface s, real fuzz=-1);
+ returns the intersection times of a path `p' with a surface `s' as a
+sorted array of real arrays of length 3, and
+triple[] intersectionpoints(path3 p, surface s, real fuzz=-1);
+ returns the corresponding intersection points. Here, the computations
+are performed to the absolute error specified by `fuzz', or if `fuzz <
+0', to machine precision.
+
+ Here is an example showing all five guide3 connectors:
+
+import graph3;
+
+size(200);
+
+currentprojection=orthographic(500,-500,500);
+
+triple[] z=new triple[10];
+
+z[0]=(0,100,0); z[1]=(50,0,0); z[2]=(180,0,0);
+
+for(int n=3; n <= 9; ++n)
+ z[n]=z[n-3]+(200,0,0);
+
+path3 p=z[0]..z[1]---z[2]::{Y}z[3]
+&z[3]..z[4]--z[5]::{Y}z[6]
+&z[6]::z[7]---z[8]..{Y}z[9];
+
+draw(p,grey+linewidth(4mm),currentlight);
+
+xaxis3(Label(XY()*"$x$",align=-3Y),red,above=true);
+yaxis3(Label(XY()*"$y$",align=-3X),red,above=true);
+
+
+
+Three-dimensional versions of bars or arrows can be drawn with one of
+the specifiers `None', `Blank', `BeginBar3', `EndBar3' (or equivalently
+`Bar3'), `Bars3', `BeginArrow3', `MidArrow3', `EndArrow3' (or
+equivalently `Arrow3'), `Arrows3', `BeginArcArrow3', `EndArcArrow3' (or
+equivalently `ArcArrow3'), `MidArcArrow3', and `ArcArrows3'.
+Three-dimensional bars accept the optional arguments `(real size=0,
+triple dir=O)'. If `size=O', the default bar length is used; if
+`dir=O', the bar is drawn perpendicular to the path and the initial
+viewing direction. The predefined three-dimensional arrowhead styles
+are `DefaultHead3', `HookHead3', `TeXHead3'. Versions of the
+two-dimensional arrowheads lifted to three-dimensional space and
+aligned according to the initial viewpoint (or an optionally specified
+`normal' vector) are also defined: `DefaultHead2(triple normal=O)',
+`HookHead2(triple normal=O)', `TeXHead2(triple normal=O)'. These are
+illustrated in the example `arrows3.asy'.
+
+ Module `three' also defines the three-dimensional margins
+`NoMargin3', `BeginMargin3', `EndMargin3', `Margin3', `Margins3',
+`BeginPenMargin2', `EndPenMargin2', `PenMargin2', `PenMargins2',
+`BeginPenMargin3', `EndPenMargin3', `PenMargin3', `PenMargins3',
+`BeginDotMargin3', `EndDotMargin3', `DotMargin3', `DotMargins3',
+`Margin3', and `TrueMargin3'.
+
+ The routine
+void pixel(picture pic=currentpicture, triple v, pen p=currentpen,
+ real width=1);
+ can be used to draw on picture `pic' a pixel of width `width' at
+position `v' using pen `p'.
+
+ Further three-dimensional examples are provided in the files
+`near_earth.asy', `conicurv.asy', and (in the `animations'
+subdirectory) `cube.asy'.
+
+ Limited support for projected vector graphics (effectively
+three-dimensional nonrendered `PostScript') is available with the
+setting `render=0'. This currently only works for piecewise planar
+surfaces, such as those produced by the parametric `surface' routines
+in the `graph3' module. Surfaces produced by the `solids' package will
+also be properly rendered if the parameter `nslices' is sufficiently
+large.
+
+ In the module `bsp', hidden surface removal of planar pictures is
+implemented using a binary space partition and picture clipping. A
+planar path is first converted to a structure `face' derived from
+`picture'. A `face' may be given to a two-dimensional drawing routine
+in place of any `picture' argument. An array of such faces may then be
+drawn, removing hidden surfaces:
+void add(picture pic=currentpicture, face[] faces,
+ projection P=currentprojection);
+ Labels may be projected to two dimensions, using projection `P', onto
+the plane passing through point `O' with normal `cross(u,v)' by
+multiplying it on the left by the transform
+transform transform(triple u, triple v, triple O=O,
+ projection P=currentprojection);
+
+ Here is an example that shows how a binary space partition may be
+used to draw a two-dimensional vector graphics projection of three
+orthogonal intersecting planes:
+
+size(6cm,0);
+import bsp;
+
+real u=2.5;
+real v=1;
+
+currentprojection=oblique;
+
+path3 y=plane((2u,0,0),(0,2v,0),(-u,-v,0));
+path3 l=rotate(90,Z)*rotate(90,Y)*y;
+path3 g=rotate(90,X)*rotate(90,Y)*y;
+
+face[] faces;
+filldraw(faces.push(y),project(y),yellow);
+filldraw(faces.push(l),project(l),lightgrey);
+filldraw(faces.push(g),project(g),green);
+
+add(faces);
+
+
+
+
+File: asymptote.info, Node: obj, Next: graph3, Prev: three, Up: Base modules
+
+8.30 `obj'
+==========
+
+This module allows one to construct surfaces from simple obj files, as
+illustrated in the example files `galleon.asy' and `triceratops.asy'.
+
+
+File: asymptote.info, Node: graph3, Next: grid3, Prev: obj, Up: Base modules
+
+8.31 `graph3'
+=============
+
+This module implements three-dimensional versions of the functions in
+`graph.asy'. To draw an x axis in three dimensions, use the routine
+void xaxis3(picture pic=currentpicture, Label L="", axis axis=YZZero,
+ real xmin=-infinity, real xmax=infinity, pen p=currentpen,
+ ticks3 ticks=NoTicks3, arrowbar3 arrow=None, bool above=false);
+ Analogous routines `yaxis' and `zaxis' can be used to draw y and z
+axes in three dimensions. There is also a routine for drawing all
+three axis:
+void axes3(picture pic=currentpicture,
+ Label xlabel="", Label ylabel="", Label zlabel="",
+ bool extend=false,
+ triple min=(-infinity,-infinity,-infinity),
+ triple max=(infinity,infinity,infinity),
+ pen p=currentpen, arrowbar3 arrow=None);
+
+The predefined three-dimensional axis types are
+axis YZEquals(real y, real z, triple align=O, bool extend=false);
+axis XZEquals(real x, real z, triple align=O, bool extend=false);
+axis XYEquals(real x, real y, triple align=O, bool extend=false);
+axis YZZero(triple align=O, bool extend=false);
+axis XZZero(triple align=O, bool extend=false);
+axis XYZero(triple align=O, bool extend=false);
+axis Bounds(int type=Both, int type2=Both, triple align=O, bool extend=false);
+ The optional `align' parameter to these routines can be used to
+specify the default axis and tick label alignments. The `Bounds' axis
+accepts two type parameters, each of which must be one of `Min', `Max',
+or `Both'. These parameters specify which of the four possible
+three-dimensional bounding box edges should be drawn.
+
+ The three-dimensional tick options are `NoTicks3', `InTicks',
+`OutTicks', and `InOutTicks'. These specify the tick directions for the
+`Bounds' axis type; other axis types inherit the direction that would
+be used for the `Bounds(Min,Min)' axis.
+
+ Here is an example of a helix and bounding box axes with ticks and
+axis labels, using orthographic projection:
+
+import graph3;
+
+size(0,200);
+size3(200,IgnoreAspect);
+
+currentprojection=orthographic(4,6,3);
+
+real x(real t) {return cos(2pi*t);}
+real y(real t) {return sin(2pi*t);}
+real z(real t) {return t;}
+
+path3 p=graph(x,y,z,0,2.7,operator ..);
+
+draw(p,Arrow3);
+
+scale(true);
+
+xaxis3(XZ()*"$x$",Bounds,red,InTicks(Label,2,2));
+yaxis3(YZ()*"$y$",Bounds,red,InTicks(beginlabel=false,Label,2,2));
+zaxis3(XZ()*"$z$",Bounds,red,InTicks);
+
+
+
+The next example illustrates three-dimensional x, y, and z axes,
+without autoscaling of the axis limits:
+
+import graph3;
+
+size(0,200);
+size3(200,IgnoreAspect);
+
+currentprojection=perspective(5,2,2);
+
+scale(Linear,Linear,Log);
+
+xaxis3("$x$",0,1,red,OutTicks(2,2));
+yaxis3("$y$",0,1,red,OutTicks(2,2));
+zaxis3("$z$",1,30,red,OutTicks(beginlabel=false));
+
+
+
+One can also place ticks along a general three-dimensional axis:
+
+import graph3;
+
+size(0,100);
+
+path3 g=yscale3(2)*unitcircle3;
+currentprojection=perspective(10,10,10);
+
+axis(Label("C",position=0,align=15X),g,InTicks(endlabel=false,8,end=false),
+ ticklocate(0,360,new real(real v) {
+ path3 h=O--max(abs(max(g)),abs(min(g)))*dir(90,v);
+ return intersect(g,h)[0];},
+ new triple(real t) {return cross(dir(g,t),Z);}));
+
+
+
+Surface plots of matrices and functions over the region `box(a,b)' in
+the XY plane are also implemented:
+surface surface(real[][] f, pair a, pair b, bool[][] cond={});
+surface surface(real[][] f, pair a, pair b, splinetype xsplinetype,
+ splinetype ysplinetype=xsplinetype, bool[][] cond={});
+surface surface(real[][] f, real[] x, real[] y,
+ splinetype xsplinetype=null, splinetype ysplinetype=xsplinetype,
+ bool[][] cond={})
+surface surface(triple[][] f, bool[][] cond={});
+surface surface(real f(pair z), pair a, pair b, int nx=nmesh, int ny=nx,
+ bool cond(pair z)=null);
+surface surface(real f(pair z), pair a, pair b, int nx=nmesh, int ny=nx,
+ splinetype xsplinetype, splinetype ysplinetype=xsplinetype,
+ bool cond(pair z)=null);
+surface surface(triple f(pair z), real[] u, real[] v,
+ splinetype[] usplinetype, splinetype[] vsplinetype=Spline,
+ bool cond(pair z)=null);
+surface surface(triple f(pair z), pair a, pair b, int nu=nmesh, int nv=nu,
+ bool cond(pair z)=null);
+surface surface(triple f(pair z), pair a, pair b, int nu=nmesh, int nv=nu,
+ splinetype[] usplinetype, splinetype[] vsplinetype=Spline,
+ bool cond(pair z)=null);
+ The final two versions draw parametric surfaces for a function f(u,v)
+over the parameter space `box(a,b)', as illustrated in the example
+`parametricsurface.asy'. An optional splinetype `Spline' may be
+specified. The boolean array or function `cond' can be used to control
+which surface mesh cells are actually drawn (by default all mesh cells
+over `box(a,b)' are drawn). Surface lighting is illustrated in the
+example files `parametricsurface.asy' and `sinc.asy'. Lighting can be
+disabled by setting `light=nolight', as in this example of a Gaussian
+surface:
+
+import graph3;
+
+size(200,0);
+
+currentprojection=perspective(10,8,4);
+
+real f(pair z) {return 0.5+exp(-abs(z)^2);}
+
+draw((-1,-1,0)--(1,-1,0)--(1,1,0)--(-1,1,0)--cycle);
+
+draw(arc(0.12Z,0.2,90,60,90,25),ArcArrow3);
+
+surface s=surface(f,(-1,-1),(1,1),nx=5,Spline);
+
+xaxis3(Label("$x$"),red,Arrow3);
+yaxis3(Label("$y$"),red,Arrow3);
+zaxis3(XYZero(extend=true),red,Arrow3);
+
+draw(s,lightgray,meshpen=black+thick(),nolight,render(merge=true));
+
+label("$O$",O,-Z+Y,red);
+
+
+A mesh can be drawn without surface filling by specifying `nullpen' for
+the surfacepen.
+
+ A vector field of `nu'\times`nv' arrows on a parametric surface `f'
+over `box(a,b)' can be drawn with the routine
+picture vectorfield(path3 vector(pair v), triple f(pair z), pair a, pair b,
+ int nu=nmesh, int nv=nu, bool truesize=false,
+ real maxlength=truesize ? 0 : maxlength(f,a,b,nu,nv),
+ bool cond(pair z)=null, pen p=currentpen,
+ arrowbar3 arrow=Arrow3, margin3 margin=PenMargin3)
+ as illustrated in the examples `vectorfield3.asy' and
+`vectorfieldsphere.asy'.
+
+
+File: asymptote.info, Node: grid3, Next: solids, Prev: graph3, Up: Base modules
+
+8.32 `grid3'
+============
+
+This module, contributed by Philippe Ivaldi, can be used for drawing 3D
+grids. Here is an example (further examples can be found in `grid3.asy'
+and at `http://www.piprime.fr/files/asymptote/grid3/'):
+
+import grid3;
+
+size(8cm,0,IgnoreAspect);
+currentprojection=orthographic(0.5,1,0.5);
+
+scale(Linear, Linear, Log);
+
+limits((-2,-2,1),(0,2,100));
+
+grid3(XYZgrid);
+
+xaxis3(Label("$x$",position=EndPoint,align=S),Bounds(Min,Min),
+ OutTicks());
+yaxis3(Label("$y$",position=EndPoint,align=S),Bounds(Min,Min),OutTicks());
+zaxis3(Label("$z$",position=EndPoint,align=(-1,0.5)),Bounds(Min,Min),
+ OutTicks(beginlabel=false));
+
+
+
+
+File: asymptote.info, Node: solids, Next: tube, Prev: grid3, Up: Base modules
+
+8.33 `solids'
+=============
+
+This solid geometry package defines a structure `revolution' that can
+be used to fill and draw surfaces of revolution. The following example
+uses it to display the outline of a circular cylinder of radius 1 with
+axis `O--1.5unit(Y+Z)' with perspective projection:
+
+import solids;
+
+size(0,100);
+
+revolution r=cylinder(O,1,1.5,Y+Z);
+draw(r,heavygreen);
+
+
+
+Further illustrations are provided in the example files `cylinder.asy',
+`cones.asy', `hyperboloid.asy', and `torus.asy'.
+
+ The structure `skeleton' contains the three-dimensional wireframe
+used to visualize a volume of revolution:
+struct skeleton {
+ struct curve {
+ path3[] front;
+ path3[] back;
+ }
+ // transverse skeleton (perpendicular to axis of revolution)
+ curve transverse;
+ // longitudinal skeleton (parallel to axis of revolution)
+ curve longitudinal;
+}
+
+
+File: asymptote.info, Node: tube, Next: flowchart, Prev: solids, Up: Base modules
+
+8.34 `tube'
+===========
+
+This package extends the `tube' surfaces constructed in
+`three_arrows.asy' to arbitrary cross sections, colors, and spine
+transformations. The routine
+surface tube(path3 g, coloredpath section,
+ transform T(real)=new transform(real t) {return identity();},
+ real corner=1, real relstep=0);
+ draws a tube along `g' with cross section `section', after applying
+the transformation `T(t)' at `relpoint(g,t)'. The parameter `corner'
+controls the number of elementary tubes at the angular points of `g'. A
+nonzero value of `relstep' specifies a fixed relative time step (in the
+sense of `relpoint(g,t)') to use in constructing elementary tubes along
+`g'. The type `coloredpath' is a generalization of `path' to which a
+`path' can be cast:
+struct coloredpath
+{
+ path p;
+ pen[] pens(real);
+ int colortype=coloredSegments;
+}
+ Here `p' defines the cross section and the method `pens(real t)'
+returns an array of pens (interpreted as a cyclic array) used for
+shading the tube patches at `relpoint(g,t)'. If
+`colortype=coloredSegments', the tube patches are filled as if each
+segment of the section was colored with the pen returned by `pens(t)',
+whereas if `colortype=coloredNodes', the tube components are vertex
+shaded as if the nodes of the section were colored.
+
+ A `coloredpath' can be constructed with one of the routines:
+coloredpath coloredpath(path p, pen[] pens(real),
+ int colortype=coloredSegments);
+coloredpath coloredpath(path p, pen[] pens=new pen[] {currentpen},
+ int colortype=coloredSegments);
+coloredpath coloredpath(path p, pen pen(real));
+ In the second case, the pens are independent of the relative time. In
+the third case, the array of pens contains only one pen, which depends
+of the relative time.
+
+ The casting of `path' to `coloredpath' allows the use of a `path'
+instead of a `coloredpath'; in this case the shading behaviour is the
+default shading behavior for a surface.
+
+ An example of `tube' is provided in the file `trefoilknot.asy'.
+Further examples can be found at
+`http://www.piprime.fr/files/asymptote/tube/'.
+
+
+File: asymptote.info, Node: flowchart, Next: contour, Prev: tube, Up: Base modules
+
+8.35 `flowchart'
+================
+
+This package provides routines for drawing flowcharts. The primary
+structure is a `block', which represents a single block on the
+flowchart. The following eight functions return a position on the
+appropriate edge of the block, given picture transform `t':
+
+pair block.top(transform t=identity());
+pair block.left(transform t=identity());
+pair block.right(transform t=identity());
+pair block.bottom(transform t=identity());
+pair block.topleft(transform t=identity());
+pair block.topright(transform t=identity());
+pair block.bottomleft(transform t=identity());
+pair block.bottomright(transform t=identity());
+
+
+To obtain an arbitrary position along the boundary of the block in user
+coordinates, use:
+pair block.position(real x, transform t=identity());
+
+
+The center of the block in user coordinates is stored in `block.center'
+and the block size in `PostScript' coordinates is given by `block.size'.
+
+A frame containing the block is returned by
+frame block.draw(pen p=currentpen);
+
+
+ The following block generation routines accept a Label, string, or
+frame for their object argument:
+
+"rectangular block with an optional header (and padding `dx' around header and body):"
+ block rectangle(object header, object body, pair center=(0,0),
+ pen headerpen=mediumgray, pen bodypen=invisible,
+ pen drawpen=currentpen,
+ real dx=3, real minheaderwidth=minblockwidth,
+ real minheaderheight=minblockwidth,
+ real minbodywidth=minblockheight,
+ real minbodyheight=minblockheight);
+ block rectangle(object body, pair center=(0,0),
+ pen fillpen=invisible, pen drawpen=currentpen,
+ real dx=3, real minwidth=minblockwidth,
+ real minheight=minblockheight);
+
+"parallelogram block:"
+ block parallelogram(object body, pair center=(0,0),
+ pen fillpen=invisible, pen drawpen=currentpen,
+ real dx=3, real slope=2,
+ real minwidth=minblockwidth,
+ real minheight=minblockheight);
+
+"diamond-shaped block:"
+ block diamond(object body, pair center=(0,0),
+ pen fillpen=invisible, pen drawpen=currentpen,
+ real ds=5, real dw=1,
+ real height=20, real minwidth=minblockwidth,
+ real minheight=minblockheight);
+
+"circular block:"
+ block circle(object body, pair center=(0,0), pen fillpen=invisible,
+ pen drawpen=currentpen, real dr=3,
+ real mindiameter=mincirclediameter);
+
+"rectangular block with rounded corners:"
+ block roundrectangle(object body, pair center=(0,0),
+ pen fillpen=invisible, pen drawpen=currentpen,
+ real ds=5, real dw=0, real minwidth=minblockwidth,
+ real minheight=minblockheight);
+
+"rectangular block with beveled edges:"
+ block bevel(object body, pair center=(0,0), pen fillpen=invisible,
+ pen drawpen=currentpen, real dh=5, real dw=5,
+ real minwidth=minblockwidth, real minheight=minblockheight);
+
+
+ To draw paths joining the pairs in `point' with right-angled lines,
+use the routine:
+path path(pair point[] ... flowdir dir[]);
+ The entries in `dir' identify whether successive segments between the
+pairs specified by `point' should be drawn in the `Horizontal' or
+`Vertical' direction.
+
+ Here is a simple flowchart example (see also the example
+`controlsystem.asy'):
+
+size(0,300);
+
+import flowchart;
+
+block block1=rectangle(Label("Example",magenta),
+ pack(Label("Start:",heavygreen),"",Label("$A:=0$",blue),
+ "$B:=1$"),(-0.5,3),palegreen,paleblue,red);
+block block2=diamond(Label("Choice?",blue),(0,2),palegreen,red);
+block block3=roundrectangle("Do something",(-1,1));
+block block4=bevel("Don't do something",(1,1));
+block block5=circle("End",(0,0));
+
+draw(block1);
+draw(block2);
+draw(block3);
+draw(block4);
+draw(block5);
+
+add(new void(picture pic, transform t) {
+ blockconnector operator --=blockconnector(pic,t);
+ // draw(pic,block1.right(t)--block2.top(t));
+ block1--Right--Down--Arrow--block2;
+ block2--Label("Yes",0.5,NW)--Left--Down--Arrow--block3;
+ block2--Right--Label("No",0.5,NE)--Down--Arrow--block4;
+ block4--Down--Left--Arrow--block5;
+ block3--Down--Right--Arrow--block5;
+ });
+
+
+
+
+File: asymptote.info, Node: contour, Next: contour3, Prev: flowchart, Up: Base modules
+
+8.36 `contour'
+==============
+
+This package draws contour lines. To construct contours corresponding
+to the values in a real array `c' for a function `f' on `box(a,b)', use
+the routine
+guide[][] contour(real f(real, real), pair a, pair b,
+ real[] c, int nx=ngraph, int ny=nx,
+ interpolate join=operator --, int subsample=1);
+ The integers `nx' and `ny' define the resolution. The default
+resolution, `ngraph x ngraph' (here `ngraph' defaults to `100') can be
+increased for greater accuracy. The default interpolation operator is
+`operator --' (linear). Spline interpolation (`operator ..') may
+produce smoother contours but it can also lead to overshooting. The
+`subsample' parameter indicates the number of interior points that
+should be used to sample contours within each `1 x 1' box; the default
+value of `1' is usually sufficient.
+
+ To construct contours for an array of data values on a uniform
+two-dimensional lattice on `box(a,b)', use
+guide[][] contour(real[][] f, pair a, pair b, real[] c,
+ interpolate join=operator --, int subsample=1);
+
+ To construct contours for an array of data values on a nonoverlapping
+regular mesh specified by the two-dimensional array `z',
+guide[][] contour(pair[][] z, real[][] f, real[] c,
+ interpolate join=operator --, int subsample=1);
+
+ To construct contours for an array of values `f' specified at
+irregularly positioned points `z', use the routine
+guide[][] contour(pair[] z, real[] f, real[] c, interpolate join=operator --);
+ The contours themselves can be drawn with one of the routines
+void draw(picture pic=currentpicture, Label[] L=new Label[],
+ guide[][] g, pen p=currentpen);
+
+void draw(picture pic=currentpicture, Label[] L=new Label[],
+ guide[][] g, pen[] p);
+
+ The following simple example draws the contour at value `1' for the
+function z=x^2+y^2, which is a unit circle:
+
+import contour;
+size(75);
+
+real f(real a, real b) {return a^2+b^2;}
+draw(contour(f,(-1,-1),(1,1),new real[] {1}));
+
+
+
+The next example draws and labels multiple contours for the function
+z=x^2-y^2 with the resolution `100 x 100', using a dashed pen for
+negative contours and a solid pen for positive (and zero) contours:
+
+import contour;
+
+size(200);
+
+real f(real x, real y) {return x^2-y^2;}
+int n=10;
+real[] c=new real[n];
+for(int i=0; i < n; ++i) c[i]=(i-n/2)/n;
+
+pen[] p=sequence(new pen(int i) {
+ return (c[i] >= 0 ? solid : dashed)+fontsize(6pt);
+ },c.length);
+
+Label[] Labels=sequence(new Label(int i) {
+ return Label(c[i] != 0 ? (string) c[i] : "",Relative(unitrand()),(0,0),
+ UnFill(1bp));
+ },c.length);
+
+draw(Labels,contour(f,(-1,-1),(1,1),c),p);
+
+
+
+The next example illustrates how contour lines can be drawn on color
+density images:
+
+import graph;
+import palette;
+import contour;
+
+size(10cm,10cm,IgnoreAspect);
+
+pair a=(0,0);
+pair b=(2pi,2pi);
+
+real f(real x, real y) {return cos(x)*sin(y);}
+
+int N=200;
+int Divs=10;
+int divs=2;
+
+defaultpen(1bp);
+pen Tickpen=black;
+pen tickpen=gray+0.5*linewidth(currentpen);
+pen[] Palette=BWRainbow();
+
+bounds range=image(f,Automatic,a,b,N,Palette);
+
+// Major contours
+
+real[] Cvals=uniform(range.min,range.max,Divs);
+draw(contour(f,a,b,Cvals,N,operator --),Tickpen);
+
+// Minor contours
+real[] cvals;
+for(int i=0; i < Cvals.length-1; ++i)
+ cvals.append(uniform(Cvals[i],Cvals[i+1],divs)[1:divs]);
+draw(contour(f,a,b,cvals,N,operator --),tickpen);
+
+xaxis("$x$",BottomTop,LeftTicks,above=true);
+yaxis("$y$",LeftRight,RightTicks,above=true);
+
+palette("$f(x,y)$",range,point(NW)+(0,0.5),point(NE)+(0,1),Top,Palette,
+ PaletteTicks(N=Divs,n=divs,Tickpen,tickpen));
+
+
+
+Finally, here is an example that illustrates the construction of
+contours from irregularly spaced data:
+
+import contour;
+
+size(200);
+
+int n=100;
+
+real f(real a, real b) {return a^2+b^2;}
+
+srand(1);
+
+real r() {return 1.1*(rand()/randMax*2-1);}
+
+pair[] points=new pair[n];
+real[] values=new real[n];
+
+for(int i=0; i < n; ++i) {
+ points[i]=(r(),r());
+ values[i]=f(points[i].x,points[i].y);
+}
+
+draw(contour(points,values,new real[]{0.25,0.5,1},operator ..),blue);
+
+
+
+In the above example, the contours of irregularly spaced data are
+constructed by first creating a triangular mesh from an array `z' of
+pairs:
+
+int[][] triangulate(pair[] z);
+
+size(200);
+int np=100;
+pair[] points;
+
+real r() {return 1.2*(rand()/randMax*2-1);}
+
+for(int i=0; i < np; ++i)
+ points.push((r(),r()));
+
+int[][] trn=triangulate(points);
+
+for(int i=0; i < trn.length; ++i) {
+ draw(points[trn[i][0]]--points[trn[i][1]]);
+ draw(points[trn[i][1]]--points[trn[i][2]]);
+ draw(points[trn[i][2]]--points[trn[i][0]]);
+}
+
+for(int i=0; i < np; ++i)
+ dot(points[i],red);
+
+
+
+The example `Gouraudcontour' illustrates how to produce color density
+images over such irregular triangular meshes. `Asymptote' uses a
+robust version of Paul Bourke's Delaunay triangulation algorithm based
+on the public-domain exact arithmetic predicates written by Jonathan
+Shewchuk.
+
+
+File: asymptote.info, Node: contour3, Next: slopefield, Prev: contour, Up: Base modules
+
+8.37 `contour3'
+===============
+
+This package draws surfaces described as the null space of real-valued
+functions of (x,y,z) or real[][][] matrices. Its usage is illustrated
+in the example file `magnetic.asy'.
+
+
+File: asymptote.info, Node: slopefield, Next: ode, Prev: contour3, Up: Base modules
+
+8.38 `slopefield'
+=================
+
+To draw a slope field for the differential equation dy/dx=f(x,y) (or
+dy/dx=f(x)), use:
+picture slopefield(real f(real,real), pair a, pair b,
+ int nx=nmesh, int ny=nx,
+ real tickfactor=0.5, pen p=currentpen,
+ arrowbar arrow=None);
+ Here, the points `a' and `b' are the lower left and upper right
+corners of the rectangle in which the slope field is to be drawn, `nx'
+and `ny' are the respective number of ticks in the x and y directions,
+`tickfactor' is the fraction of the minimum cell dimension to use for
+drawing ticks, and `p' is the pen to use for drawing the slope fields.
+The return value is a picture that can be added to `currentpicture' via
+the `add(picture)' command.
+
+ The function
+path curve(pair c, real f(real,real), pair a, pair b);
+ takes a point (`c') and a slope field-defining function `f' and
+returns, as a path, the curve passing through that point. The points
+`a' and `b' represent the rectangular boundaries over which the curve
+is interpolated.
+
+ Both `slopefield' and `curve' alternatively accept a function `real
+f(real)' that depends on x only, as seen in this example:
+
+import slopefield;
+
+size(200);
+
+real func(real x) {return 2x;}
+add(slopefield(func,(-3,-3),(3,3),20,Arrow));
+draw(curve((0,0),func,(-3,-3),(3,3)),red);
+
+
+
+
+File: asymptote.info, Node: ode, Prev: slopefield, Up: Base modules
+
+8.39 `ode'
+==========
+
+The `ode' module, illustrated in the example `odetest.asy', implements
+a number of explicit numerical integration schemes for ordinary
+differential equations.
+
+
+File: asymptote.info, Node: Options, Next: Interactive mode, Prev: Base modules, Up: Top
+
+9 Command-line options
+**********************
+
+Type `asy -h' to see the full list of command-line options supported by
+`Asymptote':
+
+Usage: ../asy [options] [file ...]
+
+Options (negate by replacing - with -no):
+
+-V,-View View output; command-line only
+-a,-align C|B|T|Z Center, Bottom, Top, or Zero page alignment [C]
+-antialias n Antialiasing width for rasterized output [2]
+-arcballradius pixels Arcball radius [750]
+-auto3D Automatically activate 3D scene [true]
+-autobillboard 3D labels always face viewer by default [true]
+-autoimport string Module to automatically import
+-autoplain Enable automatic importing of plain [true]
+-autoplay Autoplay 3D animations [false]
+-autorotate Enable automatic PDF page rotation [false]
+-axes3 Show 3D axes in PDF output [true]
+-batchMask Mask fpu exceptions in batch mode [false]
+-batchView View output in batch mode [false]
+-bw Convert all colors to black and white [false]
+-cd directory Set current directory; command-line only
+-cmyk Convert rgb colors to cmyk [false]
+-c,-command string Command to autoexecute
+-compact Conserve memory at the expense of speed [false]
+-d,-debug Enable debugging messages [false]
+-divisor n Garbage collect using purge(divisor=n) [2]
+-doubleclick ms Emulated double-click timeout [200]
+-embed Embed rendered preview image [true]
+-exitonEOF Exit interactive mode on EOF [true]
+-fitscreen Fit rendered image to screen [true]
+-framedelay ms Additional frame delay [0]
+-framerate frames/s Animation speed [30]
+-globalwrite Allow write to other directory [false]
+-gray Convert all colors to grayscale [false]
+-h,-help Show summary of options; command-line only
+-historylines n Retain n lines of history [1000]
+-iconify Iconify rendering window [false]
+-inlineimage Generate inline embedded image [false]
+-inlinetex Generate inline TeX code [false]
+-interactiveMask Mask fpu exceptions in interactive mode [true]
+-interactiveView View output in interactive mode [true]
+-interactiveWrite Write expressions entered at the prompt to stdout [true]
+-k,-keep Keep intermediate files [false]
+-keepaux Keep intermediate LaTeX .aux files [false]
+-level n Postscript level [3]
+-l,-listvariables List available global functions and variables [false]
+-localhistory Use a local interactive history file [false]
+-loop Loop 3D animations [false]
+-m,-mask Mask fpu exceptions; command-line only
+-maxtile pair Maximum rendering tile size [(1024,768)]
+-maxviewport pair Maximum viewport size [(2048,2048)]
+-multiline Input code over multiple lines at the prompt [false]
+-multipleView View output from multiple batch-mode files [false]
+-multisample n Multisampling width for screen images [4]
+-offscreen Use offscreen rendering [false]
+-O,-offset pair PostScript offset [(0,0)]
+-f,-outformat format Convert each output file to specified format
+-o,-outname name Alternative output directory/filename
+-p,-parseonly Parse file [false]
+-pdfreload Automatically reload document in pdfviewer [false]
+-pdfreloaddelay usec Delay before attempting initial pdf reload [750000]
+-position pair Initial 3D rendering screen position [(0,0)]
+-prc Embed 3D PRC graphics in PDF output [true]
+-prompt string Prompt [> ]
+-prompt2 string Continuation prompt for multiline input [..]
+-q,-quiet Suppress welcome message [false]
+-render n Render 3D graphics using n pixels per bp (-1=auto) [-1]
+-resizestep step Resize step [1.2]
+-reverse reverse 3D animations [false]
+-rgb Convert cmyk colors to rgb [false]
+-safe Disable system call [true]
+-scroll n Scroll standard output n lines at a time [0]
+-spinstep deg/s Spin speed [60]
+-svgemulation Emulate unimplemented SVG shading [false]
+-tabcompletion Interactive prompt auto-completion [true]
+-tex engine latex|pdflatex|xelatex|tex|pdftex|context|none [latex]
+-thick Render thick 3D lines [true]
+-thin Render thin 3D lines [true]
+-threads Use POSIX threads for 3D rendering [true]
+-toolbar Show 3D toolbar in PDF output [true]
+-s,-translate Show translated virtual machine code [false]
+-twice Run LaTeX twice (to resolve references) [false]
+-twosided Use two-sided 3D lighting model for rendering [true]
+-u,-user string General purpose user string
+-v,-verbose Increase verbosity level (can specify multiple times) [0]
+-version Show version; command-line only
+-wait Wait for child processes to finish before exiting [false]
+-warn string Enable warning; command-line only
+-where Show where listed variables are declared [false]
+-zoomfactor factor Zoom step factor [1.05]
+-zoomstep step Mouse motion zoom step [0.1]
+
+ All boolean options can be negated by prepending `no' to the option
+name.
+
+ If no arguments are given, `Asymptote' runs in interactive mode
+(*note Interactive mode::). In this case, the default output file is
+`out.eps'.
+
+ If `-' is given as the file argument, `Asymptote' reads from
+standard input.
+
+ If multiple files are specified, they are treated as separate
+`Asymptote' runs.
+
+ If the string `autoimport' is nonempty, a module with this name is
+automatically imported for each run as the final step in loading module
+`plain'.
+
+ Default option values may be entered as `Asymptote' code in a
+configuration file named `config.asy' (or the file specified by the
+environment variable `ASYMPTOTE_CONFIG' or `-config' option).
+`Asymptote' will look for this file in its usual search path (*note
+Search paths::). Typically the configuration file is placed in the
+`.asy' directory in the user's home directory (`%USERPROFILE%\.asy'
+under `MSDOS'). Configuration variables are accessed using the long
+form of the option names:
+import settings;
+outformat="pdf";
+batchView=false;
+interactiveView=true;
+batchMask=false;
+interactiveMask=true;
+ Command-line options override these defaults. Most configuration
+variables may also be changed at runtime. The advanced configuration
+variables `dvipsOptions', `hyperrefOptions', `convertOptions',
+`gsOptions', `psviewerOptions', `pdfviewerOptions', `pdfreloadOptions',
+`glOptions', and `dvisvgmOptions' allow specialized options to be
+passed as a string to the respective applications or libraries. The
+default value of `hyperrefOptions' is
+`setpagesize=false,unicode,pdfborder=0 0 0'.
+
+ If you insert
+import plain;
+settings.autoplain=true;
+ at the beginning of the configuration file, it can contain arbitrary
+`Asymptote' code.
+
+ The default output format is EPS for the (default) `latex' and `tex'
+tex engine and PDF for the `pdflatex', `xelatex', and `context' tex
+engines. Alternative output formats may be produced using the `-f'
+option (or `outformat' setting).
+
+ To produce SVG output, you will need `dvisvgm' (version 0.8.7 or
+later) from `http://dvisvgm.sourceforge.net' and must use the `latex'
+or `tex' tex engine. You might need to adjust the configuration
+variable `libgs' to point to the location of your ghostscript library
+`libgs.so' (or to an empty string, depending on how `dvisvgm' was
+configured).
+
+ `Asymptote' can also produce any output format supported by the
+`ImageMagick' `convert' program (version 6.3.5 or later recommended; an
+`Invalid Parameter' error message indicates that the `MSDOS' utility
+`convert' is being used instead of the one that comes with
+`ImageMagick'). The optional setting `-render n' requests an output
+resolution of `n' pixels per `bp'. Antialiasing is controlled by the
+parameter `antialias', which by default specifies a sampling width of 2
+pixels. To give other options to `convert', use the `convertOptions'
+setting or call convert manually. This example emulates how `Asymptote'
+produces antialiased `tiff' output at one pixel per `bp':
+asy -o - venn | convert -alpha Off -density 144x144 -geometry 50%x eps:- venn.tiff
+
+ If the option `-nosafe' is given, `Asymptote' runs in unsafe mode.
+This enables the `int system(string s)' and `int system(string[] s)'
+calls, allowing one to execute arbitrary shell commands. The default
+mode, `-safe', disables this call.
+
+ A `PostScript' offset may be specified as a pair (in `bp' units)
+with the `-O' option:
+asy -O 0,0 file
+ The default offset is zero. The default value of the page alignment
+setting `align' is `Center'.
+
+ The `-c' (`command') option may be used to execute arbitrary
+`Asymptote' code on the command line as a string. It is not necessary
+to terminate the string with a semicolon. Multiple `-c' options are
+executed in the order they are given. For example
+asy -c 2+2 -c "sin(1)" -c "size(100); draw(unitsquare)"
+ produces the output
+4
+0.841470984807897
+ and draws a unitsquare of size `100'.
+
+ The `-u' (`user') option may be used to specify arbitrary
+`Asymptote' settings on the command line as a string. It is not
+necessary to terminate the string with a semicolon. Multiple `-u'
+options are executed in the order they are given. Command-line code like
+`-u x=sqrt(2)' can be executed within a module like this:
+real x;
+usersetting();
+write(x);
+
+ When the `-l' (`listvariables') option is used with file arguments,
+only global functions and variables defined in the specified file(s)
+are listed.
+
+ Additional debugging output is produced with each additional `-v'
+option:
+`-v'
+ Display top-level module and final output file names.
+
+`-vv'
+ Also display imported and included module names and final `LaTeX'
+ and `dvips' processing information.
+
+`-vvv'
+ Also output `LaTeX' bidirectional pipe diagnostics.
+
+`-vvvv'
+ Also output knot guide solver diagnostics.
+
+`-vvvvv'
+ Also output `Asymptote' traceback diagnostics.
+
+
+File: asymptote.info, Node: Interactive mode, Next: GUI, Prev: Options, Up: Top
+
+10 Interactive mode
+*******************
+
+Interactive mode is entered by executing the command `asy' with no file
+arguments. When the `-multiline' option is disabled (the default), each
+line must be a complete `Asymptote' statement (unless explicitly
+continued by a final backslash character `\'); it is not necessary to
+terminate input lines with a semicolon. If one assigns
+`settings.multiline=true', interactive code can be entered over
+multiple lines; in this mode, the automatic termination of interactive
+input lines by a semicolon is inhibited. Multiline mode is useful for
+cutting and pasting `Asymptote' code directly into the interactive
+input buffer.
+
+ Interactive mode can be conveniently used as a calculator:
+expressions entered at the interactive prompt (for which a
+corresponding `write' function exists) are automatically evaluated and
+written to `stdout'. If the expression is non-writable, its type
+signature will be printed out instead. In either case, the expression
+can be referred to using the symbol `%' in the next line input at the
+prompt. For example:
+> 2+3
+5
+> %*4
+20
+> 1/%
+0.05
+> sin(%)
+0.0499791692706783
+> currentpicture
+<picture currentpicture>
+> %.size(200,0)
+>
+
+ The `%' symbol, when used as a variable, is shorthand for the
+identifier `operator answer', which is set by the prompt after each
+written expression evaluation.
+
+ The following special commands are supported only in interactive mode
+and must be entered immediately after the prompt:
+
+`help'
+ view the manual;
+
+`erase'
+ erase `currentpicture';
+
+`reset'
+ reset the `Asymptote' environment to its initial state, except for
+ changes to the settings module (*note settings::), the current
+ directory (*note cd::), and breakpoints (*note Debugger::);
+
+`input FILE'
+ does an interactive reset, followed by the command `include FILE'.
+ If the file name `FILE' contains nonalphanumeric characters,
+ enclose it with quotation marks. A trailing semi-colon followed
+ by optional `Asymptote' commands may be entered on the same line.
+
+`quit'
+ exit interactive mode (`exit' is a synonym; the abbreviation `q'
+ is also accepted unless there exists a top-level variable named
+ `q'). A history of the most recent 1000 (this number can be
+ changed with the `historylines' configuration variable) previous
+ commands will be retained in the file `.asy/history' in the user's
+ home directory (unless the command-line option `-localhistory' was
+ specified, in which case the history will be stored in the file
+ `.asy_history' in the current directory).
+
+
+ Typing `ctrl-C' interrupts the execution of `Asymptote' code and
+returns control to the interactive prompt.
+
+ Interactive mode is implemented with the GNU `readline' library,
+with command history and auto-completion. To customize the key
+bindings, see:
+`http://cnswww.cns.cwru.edu/php/chet/readline/readline.html'
+
+ The file `asymptote.py' in the `Asymptote' system directory provides
+an alternative way of entering `Asymptote' commands interactively,
+coupled with the full power of `Python'. Copy this file to your `Python
+path' and then execute from within `Python' the commands
+from asymptote import *
+g=asy()
+g.size(200)
+g.draw("unitcircle")
+g.send("draw(unitsquare)")
+g.fill("unitsquare, blue")
+g.clip("unitcircle")
+g.label("\"$O$\", (0,0), SW")
+
+
+File: asymptote.info, Node: GUI, Next: PostScript to Asymptote, Prev: Interactive mode, Up: Top
+
+11 Graphical User Interface
+***************************
+
+In the event that adjustments to the final figure are required, the
+preliminary Graphical User Interface (GUI) `xasy' included with
+`Asymptote' allows you to move graphical objects and draw new ones.
+The modified figure can then be saved as a normal `Asymptote' file.
+
+* Menu:
+
+* GUI installation:: Installing `xasy'
+* GUI usage::
+
+
+File: asymptote.info, Node: GUI installation, Next: GUI usage, Up: GUI
+
+11.1 GUI installation
+=====================
+
+As `xasy' is written in the interactive scripting language `Python/TK',
+it requires `Python' (`http://www.python.org'), the `Python Imaging
+Library' (`http://www.pythonware.com/products/pil/'), and the `tkinter'
+package (included with `Python' under `Microsoft Windows') be
+installed. `Fedora Linux' users can either install `tkinter' with the
+commands
+yum install tkinter
+yum install tk-devel
+ or manually install the `tkinter', `tix', `tk', and `tk-devel'
+packages.
+
+ Pictures are deconstructed into the PNG image format, which supports
+full alpha channel transparency. Under `Microsoft Windows', this
+requires `Python 2.7.4' and the `Python Imaging Library':
+
+ `http://www.python.org/ftp/python/2.7.4/python-2.7.4.msi'
+
+ `http://effbot.org/downloads/PIL-1.1.7.win32-py2.7.exe'.
+ On `UNIX' systems, place
+`http://effbot.org/downloads/Imaging-1.1.7.tar.gz' in the `Asymptote'
+source directory, and type (as the root user):
+tar -zxf Imaging-1.1.7.tar.gz
+cd Imaging-1.1.7
+python setup.py install
+
+
+File: asymptote.info, Node: GUI usage, Prev: GUI installation, Up: GUI
+
+11.2 GUI usage
+==============
+
+A wheel mouse is convenient for raising and lowering objects within
+`xasy', to expose the object to be moved. If a wheel mouse is not
+available, mouse `Button-2' can be used to repeatedly lower an object
+instead. When run from the command line, `xasy' accepts a command line
+option `-x n', which sets the initial magnification to `n'.
+
+ Deconstruction of compound objects (such as arrows) can be prevented
+by enclosing them within the commands
+void begingroup(picture pic=currentpicture);
+void endgroup(picture pic=currentpicture);
+ By default, the elements of a picture or frame will be grouped
+together on adding them to a picture. However, the elements of a frame
+added to another frame are not grouped together by default: their
+elements will be individually deconstructed (*note add::).
+
+
+File: asymptote.info, Node: PostScript to Asymptote, Next: Help, Prev: GUI, Up: Top
+
+12 `PostScript' to `Asymptote'
+******************************
+
+The excellent `PostScript' editor `pstoedit' (version 3.50 or later;
+available from `http://sourceforge.net/projects/pstoedit/') includes an
+`Asymptote' backend. Unlike virtually all other `pstoedit' backends,
+this driver includes native clipping, even-odd fill rule, `PostScript'
+subpath, and full image support. Here is an example: `asy -V
+/usr/local/share/doc/asymptote/examples/venn.asy'
+pstoedit -f asy venn.eps test.asy
+asy -V test
+
+If the line widths aren't quite correct, try giving `pstoedit' the
+`-dis' option. If the fonts aren't typeset correctly, try giving
+`pstoedit' the `-dt' option.
+
+
+File: asymptote.info, Node: Help, Next: Debugger, Prev: PostScript to Asymptote, Up: Top
+
+13 Help
+*******
+
+A list of frequently asked questions (FAQ) is maintained at
+
+ `http://asymptote.sourceforge.net/FAQ'
+ Questions on installing and using `Asymptote' that are not addressed
+in the FAQ should be sent to the `Asymptote' forum:
+
+ `http://sourceforge.net/p/asymptote/discussion/409349'
+ Including an example that illustrates what you are trying to do will
+help you get useful feedback. `LaTeX' problems can often be diagnosed
+with the `-vv' or `-vvv' command-line options. Contributions in the
+form of patches or `Asymptote' modules can be posted here:
+
+ `http://sourceforge.net/tracker/?atid=685685&group_id=120000'
+ To receive announcements of upcoming releases, please subscribe to
+`Asymptote' at
+
+ `http://freshmeat.net/projects/asy'
+ If you find a bug in `Asymptote', please check (if possible) whether
+the bug is still present in the latest `Subversion' developmental code
+(*note Subversion::) before submitting a bug report. New bugs can be
+submitted using the Bug Tracking System at
+
+ `http://sourceforge.net/projects/asymptote'
+ To see if the bug has already been fixed, check bugs with Status
+`Closed' and recent lines in
+
+ `http://asymptote.sourceforge.net/ChangeLog'
+ `Asymptote' can be configured with the optional GNU library
+`libsigsegv', available from `http://libsigsegv.sourceforge.net', which
+allows one to distinguish user-generated `Asymptote' stack overflows
+(*note stack overflow::) from true segmentation faults (due to internal
+C++ programming errors; please submit the `Asymptote' code that
+generates such segmentation faults along with your bug report).
+
+
+File: asymptote.info, Node: Debugger, Next: Credits, Prev: Help, Up: Top
+
+14 Debugger
+***********
+
+Asymptote now includes a line-based (as opposed to code-based) debugger
+that can assist the user in following flow control. To set a break
+point in file `file' at line `line', use the command
+
+void stop(string file, int line, code s=quote{});
+ The optional argument `s' may be used to conditionally set the variable
+`ignore' in `plain_debugger.asy' to `true'. For example, the first 10
+instances of this breakpoint will be ignored (the variable `int
+count=0' is defined in `plain_debugger.asy'):
+stop("test",2,quote{ignore=(++count <= 10);});
+
+ To set a break point in file `file' at the first line containing the
+string `text', use
+
+void stop(string file, string text, code s=quote{});
+ To list all breakpoints, use:
+void breakpoints();
+ To clear a breakpoint, use:
+void clear(string file, int line);
+ To clear all breakpoints, use:
+void clear();
+
+ The following commands may be entered at the debugging prompt:
+
+``h''
+ help;
+
+``c''
+ continue execution;
+
+``i''
+ step to the next instruction;
+
+``s''
+ step to the next executable line;
+
+``n''
+ step to the next executable line in the current file;
+
+``f''
+ step to the next file;
+
+``r''
+ return to the file associated with the most recent breakpoint;
+
+``t''
+ toggle tracing (`-vvvvv') mode;
+
+``q''
+ quit debugging and end execution;
+
+``x''
+ exit the debugger and run to completion.
+
+ Arbitrary `Asymptote' code may also be entered at the debugging
+prompt; however, since the debugger is implemented with `eval',
+currently only top-level (global) variables can be displayed or
+modified.
+
+ The debugging prompt may be entered manually with the call
+void breakpoint(code s=quote{});
+
+
+File: asymptote.info, Node: Credits, Next: Index, Prev: Debugger, Up: Top
+
+15 Acknowledgments
+******************
+
+Financial support for the development of `Asymptote' was generously
+provided by the Natural Sciences and Engineering Research Council of
+Canada, the Pacific Institute for Mathematical Sciences, and the
+University of Alberta Faculty of Science.
+
+ We also would like to acknowledge the previous work of John D. Hobby,
+author of the program `MetaPost' that inspired the development of
+`Asymptote', and Donald E. Knuth, author of TeX and `MetaFont' (on
+which `MetaPost' is based).
+
+ The authors of `Asymptote' are Andy Hammerlindl, John Bowman, and
+Tom Prince. Sean Healy designed the `Asymptote' logo. Other
+contributors include Michail Vidiassov, Radoslav Marinov, Orest Shardt,
+Chris Savage, Philippe Ivaldi, Olivier Guibe', Jacques Pienaar, Mark
+Henning, Steve Melenchuk, Martin Wiebusch, and Stefan Knorr.
+
+
+File: asymptote.info, Node: Index, Prev: Credits, Up: Top
+
+Index
+*****
+
+
+* Menu:
+
+* !: Arithmetic & logical.
+ (line 68)
+* != <1>: Arithmetic & logical.
+ (line 38)
+* !=: Structures. (line 52)
+* % <1>: Interactive mode. (line 17)
+* %: Arithmetic & logical.
+ (line 23)
+* %=: Self & prefix operators.
+ (line 6)
+* & <1>: Arithmetic & logical.
+ (line 56)
+* &: Bezier curves. (line 86)
+* &&: Arithmetic & logical.
+ (line 53)
+* * <1>: Arithmetic & logical.
+ (line 17)
+* *: Pens. (line 15)
+* **: Arithmetic & logical.
+ (line 31)
+* *=: Self & prefix operators.
+ (line 6)
+* + <1>: Arithmetic & logical.
+ (line 13)
+* +: Pens. (line 15)
+* ++: Self & prefix operators.
+ (line 6)
+* +=: Self & prefix operators.
+ (line 6)
+* -: Arithmetic & logical.
+ (line 14)
+* -- <1>: Self & prefix operators.
+ (line 6)
+* --: Tutorial. (line 127)
+* ---: Bezier curves. (line 86)
+* -=: Self & prefix operators.
+ (line 6)
+* -c: Options. (line 180)
+* -l: Options. (line 199)
+* -u: Options. (line 190)
+* -V <1>: Tutorial. (line 19)
+* -V: Configuring. (line 6)
+* ..: Tutorial. (line 127)
+* .asy: Search paths. (line 14)
+* /: Arithmetic & logical.
+ (line 20)
+* /=: Self & prefix operators.
+ (line 6)
+* 2D graphs: graph. (line 6)
+* 3D graphs: graph3. (line 6)
+* 3D grids: grid3. (line 6)
+* 3D PostScript: three. (line 594)
+* :: Arithmetic & logical.
+ (line 73)
+* ::: Bezier curves. (line 70)
+* <: Arithmetic & logical.
+ (line 41)
+* <=: Arithmetic & logical.
+ (line 44)
+* == <1>: Arithmetic & logical.
+ (line 37)
+* ==: Structures. (line 52)
+* >: Arithmetic & logical.
+ (line 50)
+* >=: Arithmetic & logical.
+ (line 47)
+* ?: Arithmetic & logical.
+ (line 73)
+* ^: Arithmetic & logical.
+ (line 28)
+* ^=: Self & prefix operators.
+ (line 6)
+* ^^: Tutorial. (line 134)
+* a4: Configuring. (line 61)
+* abort: Data types. (line 339)
+* abs <1>: Mathematical functions.
+ (line 35)
+* abs: Data types. (line 62)
+* accel <1>: three. (line 520)
+* accel: Paths and guides. (line 117)
+* access: Import. (line 6)
+* acknowledgments: Credits. (line 6)
+* aCos: Mathematical functions.
+ (line 20)
+* acos: Mathematical functions.
+ (line 6)
+* acosh: Mathematical functions.
+ (line 6)
+* add <1>: three. (line 284)
+* add: Frames and pictures. (line 196)
+* addViews: three. (line 406)
+* adjust: Pens. (line 115)
+* Ai: Mathematical functions.
+ (line 48)
+* Ai_deriv: Mathematical functions.
+ (line 48)
+* Airy: Mathematical functions.
+ (line 48)
+* alias <1>: Arrays. (line 181)
+* alias: Structures. (line 52)
+* align: Options. (line 174)
+* Align: label. (line 12)
+* all: Arrays. (line 329)
+* Allow: Pens. (line 327)
+* AND: Arithmetic & logical.
+ (line 80)
+* and: Bezier curves. (line 56)
+* angle: Data types. (line 70)
+* animate <1>: animation. (line 12)
+* animate <2>: Files. (line 154)
+* animate: Configuring. (line 67)
+* animation: animation. (line 6)
+* annotate: annotate. (line 6)
+* antialias <1>: Options. (line 145)
+* antialias: three. (line 222)
+* append <1>: Arrays. (line 39)
+* append: Files. (line 36)
+* arc: three. (line 296)
+* Arc: Paths and guides. (line 32)
+* arc: Paths and guides. (line 22)
+* ArcArrow: draw. (line 26)
+* ArcArrow3: three. (line 561)
+* ArcArrows: draw. (line 26)
+* ArcArrows3: three. (line 561)
+* arclength <1>: three. (line 520)
+* arclength: Paths and guides. (line 144)
+* arcpoint: Paths and guides. (line 154)
+* arctime <1>: three. (line 520)
+* arctime: Paths and guides. (line 148)
+* arguments: Default arguments. (line 6)
+* arithmetic operators: Arithmetic & logical.
+ (line 6)
+* array: Arrays. (line 122)
+* array iteration: Programming. (line 33)
+* arrays: Arrays. (line 6)
+* arrow: label. (line 71)
+* Arrow: draw. (line 26)
+* arrow: Drawing commands. (line 31)
+* arrow keys: Tutorial. (line 37)
+* Arrow3: three. (line 561)
+* Arrows: draw. (line 26)
+* arrows: draw. (line 26)
+* Arrows3: three. (line 561)
+* as: Import. (line 68)
+* ascii: Data types. (line 286)
+* aSin: Mathematical functions.
+ (line 20)
+* asin: Mathematical functions.
+ (line 6)
+* asinh: Mathematical functions.
+ (line 6)
+* Aspect: Frames and pictures. (line 54)
+* assert: Data types. (line 344)
+* assignment: Programming. (line 8)
+* asy <1>: Import. (line 102)
+* asy: Data types. (line 334)
+* asy-mode: Editing modes. (line 6)
+* asy.vim: Editing modes. (line 33)
+* asyinclude: LaTeX usage. (line 46)
+* asymptote.sty: LaTeX usage. (line 6)
+* asymptote.xml: Editing modes. (line 49)
+* ASYMPTOTE_CONFIG: Options. (line 116)
+* aTan: Mathematical functions.
+ (line 20)
+* atan: Mathematical functions.
+ (line 6)
+* atan2: Mathematical functions.
+ (line 6)
+* atanh: Mathematical functions.
+ (line 6)
+* atleast: Bezier curves. (line 56)
+* attach <1>: graph. (line 416)
+* attach <2>: LaTeX usage. (line 51)
+* attach: Frames and pictures. (line 252)
+* autoadjust: three. (line 372)
+* autoimport: Options. (line 112)
+* automatic scaling: graph. (line 682)
+* axialshade: fill. (line 43)
+* axis <1>: graph3. (line 67)
+* axis: graph. (line 879)
+* azimuth: Data types. (line 126)
+* babel: babel. (line 6)
+* background color: Frames and pictures. (line 168)
+* BackView: three. (line 399)
+* Bar: draw. (line 19)
+* Bar3: three. (line 561)
+* Bars: draw. (line 19)
+* Bars3: three. (line 561)
+* barsize: draw. (line 19)
+* base modules: Base modules. (line 6)
+* basealign: Pens. (line 168)
+* baseline: label. (line 91)
+* batch mode: Tutorial. (line 6)
+* beep: Data types. (line 357)
+* BeginArcArrow: draw. (line 26)
+* BeginArcArrow3: three. (line 561)
+* BeginArrow: draw. (line 26)
+* BeginArrow3: three. (line 561)
+* BeginBar: draw. (line 19)
+* BeginBar3: three. (line 561)
+* BeginDotMargin: draw. (line 42)
+* BeginDotMargin3: three. (line 577)
+* BeginMargin: draw. (line 42)
+* BeginMargin3: three. (line 577)
+* BeginPenMargin: draw. (line 42)
+* BeginPenMargin2: three. (line 577)
+* BeginPenMargin3: three. (line 577)
+* BeginPoint: label. (line 56)
+* Bessel: Mathematical functions.
+ (line 48)
+* bevel: flowchart. (line 75)
+* beveljoin: Pens. (line 138)
+* Bezier curves: Bezier curves. (line 6)
+* bezulate: three. (line 104)
+* Bi: Mathematical functions.
+ (line 48)
+* Bi_deriv: Mathematical functions.
+ (line 48)
+* Billboard: three. (line 490)
+* binary: Files. (line 75)
+* binary format: Files. (line 75)
+* binary operators: Arithmetic & logical.
+ (line 6)
+* binarytree: binarytree. (line 6)
+* black stripes: three. (line 222)
+* Blank: draw. (line 26)
+* block.bottom: flowchart. (line 19)
+* block.bottomleft: flowchart. (line 19)
+* block.bottomright: flowchart. (line 19)
+* block.center: flowchart. (line 26)
+* block.draw: flowchart. (line 31)
+* block.left: flowchart. (line 19)
+* block.position: flowchart. (line 24)
+* block.right: flowchart. (line 19)
+* block.top: flowchart. (line 19)
+* block.topleft: flowchart. (line 19)
+* block.topright: flowchart. (line 19)
+* bool: Data types. (line 14)
+* bool3: Data types. (line 23)
+* boolean operators: Arithmetic & logical.
+ (line 6)
+* Bottom: graph. (line 134)
+* BottomTop: graph. (line 140)
+* BottomView: three. (line 399)
+* bounding box: Frames and pictures. (line 168)
+* Bounds: graph3. (line 21)
+* box <1>: three. (line 318)
+* box: Frames and pictures. (line 22)
+* bp: Tutorial. (line 26)
+* brace: Paths and guides. (line 44)
+* break: Programming. (line 29)
+* breakpoints: Debugger. (line 21)
+* brick: Pens. (line 251)
+* broken axis: graph. (line 782)
+* bug reports: Help. (line 23)
+* buildcycle: Paths and guides. (line 260)
+* Button-1: GUI. (line 6)
+* Button-2: GUI. (line 6)
+* BWRainbow: palette. (line 15)
+* BWRainbow2: palette. (line 18)
+* C string: Data types. (line 191)
+* CAD: CAD. (line 6)
+* calculateTransform: Frames and pictures. (line 107)
+* camera: three. (line 367)
+* casts: Casts. (line 6)
+* cbrt: Mathematical functions.
+ (line 6)
+* cd: Files. (line 25)
+* ceil: Mathematical functions.
+ (line 26)
+* center: three. (line 351)
+* Center: label. (line 61)
+* checker: Pens. (line 251)
+* Chinese: unicode. (line 12)
+* choose: Mathematical functions.
+ (line 39)
+* Ci: Mathematical functions.
+ (line 48)
+* circle <1>: flowchart. (line 64)
+* circle: three. (line 292)
+* Circle: Paths and guides. (line 17)
+* circle: Paths and guides. (line 10)
+* circlebarframe: markers. (line 18)
+* CJK: unicode. (line 12)
+* clamped: graph. (line 37)
+* clear <1>: Debugger. (line 23)
+* clear: Files. (line 92)
+* clip: fill. (line 115)
+* CLZ: Arithmetic & logical.
+ (line 80)
+* cm: Tutorial. (line 63)
+* cmd: Configuring. (line 34)
+* cmyk: Pens. (line 34)
+* colatitude: Data types. (line 131)
+* color: Pens. (line 23)
+* coloredNodes: tube. (line 25)
+* coloredpath: tube. (line 18)
+* coloredSegments: tube. (line 25)
+* colorless: Pens. (line 54)
+* colors: Pens. (line 51)
+* comma: Files. (line 61)
+* comma-separated-value mode: Arrays. (line 362)
+* command-line options <1>: Options. (line 6)
+* command-line options: Configuring. (line 84)
+* comment character: Files. (line 16)
+* compass directions: Tutorial. (line 106)
+* Compiling from UNIX source: Compiling from UNIX source.
+ (line 6)
+* complement: Arrays. (line 150)
+* concat: Arrays. (line 177)
+* conditional <1>: Arithmetic & logical.
+ (line 73)
+* conditional: Programming. (line 8)
+* config: Options. (line 116)
+* configuration file <1>: Options. (line 116)
+* configuration file: Configuring. (line 23)
+* configuring: Configuring. (line 6)
+* conj: Data types. (line 59)
+* constructors: Structures. (line 91)
+* context: Options. (line 145)
+* continue <1>: Debugger. (line 31)
+* continue: Programming. (line 29)
+* contour: contour. (line 9)
+* contour3: contour3. (line 6)
+* controls <1>: three. (line 6)
+* controls: Bezier curves. (line 45)
+* controlSpecifier: Paths and guides. (line 393)
+* convert <1>: Options. (line 145)
+* convert <2>: animation. (line 6)
+* convert <3>: Files. (line 154)
+* convert: Configuring. (line 67)
+* convertOptions: Options. (line 131)
+* Coons shading: fill. (line 78)
+* copy: Arrays. (line 174)
+* Cos: Mathematical functions.
+ (line 20)
+* cos: Mathematical functions.
+ (line 6)
+* cosh: Mathematical functions.
+ (line 6)
+* cputime: Structures. (line 169)
+* crop: graph. (line 637)
+* cropping graphs: graph. (line 637)
+* cross <1>: graph. (line 485)
+* cross: Data types. (line 169)
+* crossframe: markers. (line 23)
+* crosshatch: Pens. (line 267)
+* csv: Arrays. (line 362)
+* CTZ: Arithmetic & logical.
+ (line 80)
+* cubicroots: Arrays. (line 318)
+* curl <1>: three. (line 6)
+* curl: Bezier curves. (line 66)
+* curlSpecifier: Paths and guides. (line 405)
+* currentpen: Pens. (line 6)
+* currentprojection: three. (line 396)
+* curve: slopefield. (line 20)
+* custom axis types: graph. (line 144)
+* custom mark routine: graph. (line 577)
+* custom tick locations: graph. (line 249)
+* cut: Paths and guides. (line 242)
+* cycle <1>: three. (line 6)
+* cycle: Tutorial. (line 75)
+* cyclic <1>: three. (line 520)
+* cyclic <2>: Arrays. (line 39)
+* cyclic: Paths and guides. (line 76)
+* Cyrillic: unicode. (line 7)
+* dashdotted: Pens. (line 95)
+* dashed: Pens. (line 95)
+* data types: Data types. (line 6)
+* date: Data types. (line 298)
+* Debian: UNIX binary distributions.
+ (line 19)
+* debugger: Debugger. (line 6)
+* declaration: Programming. (line 8)
+* deconstruct: GUI usage. (line 6)
+* default arguments: Default arguments. (line 6)
+* defaultformat: graph. (line 175)
+* DefaultHead: draw. (line 26)
+* DefaultHead3: three. (line 561)
+* defaultpen: Pens. (line 46)
+* defaultrender: three. (line 47)
+* deferred drawing: simplex. (line 6)
+* Degrees: Mathematical functions.
+ (line 17)
+* degrees <1>: Mathematical functions.
+ (line 17)
+* degrees: Data types. (line 75)
+* delete <1>: Arrays. (line 39)
+* delete: Files. (line 149)
+* description: Description. (line 6)
+* diagonal: Arrays. (line 303)
+* diamond: flowchart. (line 57)
+* dimension: Arrays. (line 367)
+* dir <1>: three. (line 520)
+* dir <2>: Paths and guides. (line 100)
+* dir <3>: Data types. (line 87)
+* dir: Search paths. (line 10)
+* direction specifier: Bezier curves. (line 6)
+* directory: Files. (line 25)
+* dirSpecifier: Paths and guides. (line 387)
+* dirtime: Paths and guides. (line 157)
+* display: Configuring. (line 67)
+* do: Programming. (line 29)
+* DOSendl: Files. (line 61)
+* DOSnewl: Files. (line 61)
+* dot <1>: Arrays. (line 259)
+* dot <2>: Data types. (line 100)
+* dot: draw. (line 83)
+* DotMargin: draw. (line 42)
+* DotMargin3: three. (line 577)
+* DotMargins: draw. (line 42)
+* DotMargins3: three. (line 577)
+* dotted: Pens. (line 95)
+* double deferred drawing: three. (line 269)
+* double precision: Files. (line 75)
+* draw: three. (line 112)
+* Draw: Frames and pictures. (line 147)
+* draw: draw. (line 110)
+* Draw: draw. (line 26)
+* draw: Drawing commands. (line 31)
+* drawing commands: Drawing commands. (line 6)
+* drawline: math. (line 9)
+* drawtree: drawtree. (line 9)
+* dvips: Configuring. (line 67)
+* dvipsOptions: Options. (line 131)
+* dvisvgm <1>: Options. (line 150)
+* dvisvgm: Configuring. (line 67)
+* dvisvgmOptions: Options. (line 131)
+* E <1>: Mathematical functions.
+ (line 48)
+* E: Tutorial. (line 106)
+* Editing modes: Editing modes. (line 6)
+* Ei: Mathematical functions.
+ (line 48)
+* ellipse <1>: Frames and pictures. (line 22)
+* ellipse: Paths and guides. (line 39)
+* elliptic functions: Mathematical functions.
+ (line 48)
+* else: Programming. (line 8)
+* emacs: Editing modes. (line 6)
+* embed: embed. (line 6)
+* Embedded: three. (line 490)
+* empty: Frames and pictures. (line 7)
+* EndArcArrow: draw. (line 26)
+* EndArcArrow3: three. (line 561)
+* EndArrow: draw. (line 26)
+* EndArrow3: three. (line 561)
+* EndBar: draw. (line 19)
+* EndBar3: three. (line 561)
+* EndDotMargin: draw. (line 42)
+* EndDotMargin3: three. (line 577)
+* endl: Files. (line 61)
+* EndMargin: draw. (line 42)
+* EndMargin3: three. (line 577)
+* EndPenMargin: draw. (line 42)
+* EndPenMargin2: three. (line 577)
+* EndPenMargin3: three. (line 577)
+* EndPoint: label. (line 56)
+* envelope: Frames and pictures. (line 22)
+* environment variables: Configuring. (line 88)
+* eof <1>: Arrays. (line 344)
+* eof: Files. (line 92)
+* eol <1>: Arrays. (line 344)
+* eol: Files. (line 92)
+* EPS <1>: Options. (line 145)
+* EPS: label. (line 79)
+* erase <1>: Frames and pictures. (line 7)
+* erase <2>: Data types. (line 241)
+* erase: Tutorial. (line 37)
+* erf: Mathematical functions.
+ (line 6)
+* erfc: Mathematical functions.
+ (line 6)
+* error: Files. (line 16)
+* error bars: graph. (line 533)
+* errorbars: graph. (line 485)
+* eval: Import. (line 98)
+* evenodd <1>: Pens. (line 152)
+* evenodd: Tutorial. (line 148)
+* exit <1>: Debugger. (line 57)
+* exit <2>: Interactive mode. (line 59)
+* exit: Data types. (line 348)
+* exp: Mathematical functions.
+ (line 6)
+* expi: Data types. (line 83)
+* explicit: Casts. (line 6)
+* explicit casts: Casts. (line 21)
+* expm1: Mathematical functions.
+ (line 6)
+* exponential integral: Mathematical functions.
+ (line 48)
+* extendcap: Pens. (line 129)
+* extension <1>: MetaPost. (line 10)
+* extension: Paths and guides. (line 237)
+* external: embed. (line 12)
+* extrude: three. (line 514)
+* F: Mathematical functions.
+ (line 48)
+* fabs: Mathematical functions.
+ (line 6)
+* face: three. (line 602)
+* factorial: Mathematical functions.
+ (line 39)
+* Fedora: UNIX binary distributions.
+ (line 15)
+* feynman: feynman. (line 6)
+* fft <1>: math. (line 26)
+* fft: Arrays. (line 246)
+* FFTW: Compiling from UNIX source.
+ (line 58)
+* file <1>: Debugger. (line 45)
+* file: Files. (line 6)
+* Fill: Frames and pictures. (line 133)
+* fill <1>: fill. (line 17)
+* fill: draw. (line 116)
+* Fill: draw. (line 26)
+* FillDraw: Frames and pictures. (line 123)
+* filldraw: fill. (line 11)
+* FillDraw: draw. (line 26)
+* filloutside: fill. (line 27)
+* fillrule: Pens. (line 152)
+* find <1>: Arrays. (line 159)
+* find: Data types. (line 226)
+* firstcut: Paths and guides. (line 252)
+* fit: Frames and pictures. (line 103)
+* fit3: three. (line 282)
+* fixedscaling: Frames and pictures. (line 74)
+* floor: Mathematical functions.
+ (line 26)
+* flowchart: flowchart. (line 6)
+* flush: Files. (line 61)
+* fmod: Mathematical functions.
+ (line 6)
+* font: Pens. (line 192)
+* font command: Pens. (line 192)
+* fontcommand: Pens. (line 207)
+* fontsize: Pens. (line 178)
+* for: Programming. (line 8)
+* format <1>: Options. (line 145)
+* format: Data types. (line 269)
+* forum: Help. (line 6)
+* frame: Frames and pictures. (line 7)
+* from: Import. (line 17)
+* FrontView: three. (line 399)
+* function declarations: Functions. (line 67)
+* function shading: fill. (line 100)
+* Function shading: fill. (line 100)
+* functions <1>: Mathematical functions.
+ (line 6)
+* functions: Functions. (line 6)
+* functionshade: fill. (line 100)
+* gamma: Mathematical functions.
+ (line 6)
+* Gaussrand: Mathematical functions.
+ (line 39)
+* geometry: geometry. (line 6)
+* getc: Files. (line 30)
+* getpair: Files. (line 117)
+* getreal: Files. (line 117)
+* getstring: Files. (line 117)
+* gettriple: Files. (line 117)
+* glOptions <1>: Options. (line 131)
+* glOptions: three. (line 222)
+* GNU Scientific Library: Mathematical functions.
+ (line 48)
+* gouraudshade: fill. (line 62)
+* Gradient: palette. (line 25)
+* gradient shading: fill. (line 32)
+* graph: graph. (line 6)
+* graph3: graph3. (line 6)
+* graphic: label. (line 79)
+* graphical user interface: GUI. (line 6)
+* gray: Pens. (line 25)
+* Grayscale: palette. (line 9)
+* grayscale: Pens. (line 25)
+* grid <1>: graph. (line 733)
+* grid: Pens. (line 251)
+* grid3: grid3. (line 6)
+* gs: Configuring. (line 6)
+* gsl: Mathematical functions.
+ (line 48)
+* GSL: Compiling from UNIX source.
+ (line 58)
+* gsOptions: Options. (line 131)
+* GUI: GUI. (line 6)
+* GUI installation: GUI installation. (line 6)
+* GUI usage: GUI usage. (line 6)
+* guide: Paths and guides. (line 314)
+* guide3: three. (line 6)
+* hatch: Pens. (line 267)
+* height: LaTeX usage. (line 51)
+* help <1>: Debugger. (line 30)
+* help <2>: Help. (line 6)
+* help: Interactive mode. (line 44)
+* Hermite: graph. (line 37)
+* Hermite(splinetype splinetype: graph. (line 37)
+* hex <1>: Pens. (line 60)
+* hex: Data types. (line 283)
+* hexidecimal <1>: Pens. (line 59)
+* hexidecimal: Data types. (line 283)
+* hidden surface removal: three. (line 602)
+* histogram: Mathematical functions.
+ (line 39)
+* history <1>: Interactive mode. (line 59)
+* history: Files. (line 142)
+* historylines: Interactive mode. (line 64)
+* HookHead: draw. (line 26)
+* HookHead3: three. (line 561)
+* Horizontal: flowchart. (line 81)
+* hyperrefOptions: Options. (line 131)
+* hypot: Mathematical functions.
+ (line 6)
+* I: Mathematical functions.
+ (line 48)
+* i_scaled: Mathematical functions.
+ (line 48)
+* iconic: three. (line 222)
+* identity <1>: Arrays. (line 300)
+* identity <2>: Mathematical functions.
+ (line 6)
+* identity: Transforms. (line 24)
+* identity4: three. (line 450)
+* if: Programming. (line 8)
+* IgnoreAspect: Frames and pictures. (line 58)
+* image: palette. (line 34)
+* ImageMagick <1>: Options. (line 145)
+* ImageMagick <2>: animation. (line 6)
+* ImageMagick: Configuring. (line 67)
+* images: palette. (line 6)
+* implicit casts: Casts. (line 6)
+* implicit linear solver: MetaPost. (line 10)
+* implicit scaling: Implicit scaling. (line 6)
+* import: Import. (line 46)
+* inches: Tutorial. (line 63)
+* incircle: Paths and guides. (line 303)
+* include: Import. (line 127)
+* including images: label. (line 79)
+* increasing: math. (line 59)
+* inf: Data types. (line 33)
+* inheritance: Structures. (line 181)
+* initialized: Arrays. (line 39)
+* initializers: Variable initializers.
+ (line 6)
+* inline: LaTeX usage. (line 51)
+* InOutTicks: graph3. (line 35)
+* input <1>: Interactive mode. (line 48)
+* input: Files. (line 10)
+* insert <1>: Arrays. (line 39)
+* insert: Data types. (line 237)
+* inside: Paths and guides. (line 284)
+* inst: Debugger. (line 36)
+* installation: Installation. (line 6)
+* int: Data types. (line 28)
+* integer division: Arithmetic & logical.
+ (line 6)
+* interactive mode: Interactive mode. (line 6)
+* interior: Paths and guides. (line 280)
+* international characters: unicode. (line 6)
+* interp: Arithmetic & logical.
+ (line 76)
+* interpolate: interpolate. (line 6)
+* intersect <1>: three. (line 520)
+* intersect <2>: math. (line 13)
+* intersect: Paths and guides. (line 186)
+* intersectionpoint <1>: three. (line 520)
+* intersectionpoint <2>: math. (line 17)
+* intersectionpoint: Paths and guides. (line 229)
+* intersectionpoints <1>: three. (line 520)
+* intersectionpoints: Paths and guides. (line 233)
+* intersections <1>: three. (line 520)
+* intersections: Paths and guides. (line 197)
+* InTicks: graph3. (line 35)
+* intMax: Data types. (line 28)
+* intMin: Data types. (line 28)
+* inverse <1>: Arrays. (line 306)
+* inverse: Transforms. (line 16)
+* invert: three. (line 440)
+* invisible: Pens. (line 39)
+* isnan: Data types. (line 33)
+* J: Mathematical functions.
+ (line 6)
+* Japanese: unicode. (line 12)
+* K: Mathematical functions.
+ (line 48)
+* k_scaled: Mathematical functions.
+ (line 48)
+* Kate: Editing modes. (line 49)
+* KDE editor: Editing modes. (line 49)
+* keepAspect <1>: LaTeX usage. (line 51)
+* keepAspect: Frames and pictures. (line 54)
+* keyboard bindings:: three. (line 181)
+* keys: Arrays. (line 39)
+* keyword: Named arguments. (line 37)
+* keyword-only: Named arguments. (line 37)
+* keywords: Named arguments. (line 6)
+* Korean: unicode. (line 12)
+* label: three. (line 484)
+* Label <1>: graph. (line 343)
+* Label: label. (line 14)
+* label: clip. (line 16)
+* Label: draw. (line 98)
+* labelpath: labelpath. (line 6)
+* labelpath3: labelpath3. (line 6)
+* labelx: graph. (line 343)
+* labely: graph. (line 343)
+* Landscape: Frames and pictures. (line 95)
+* lastcut: Paths and guides. (line 256)
+* lasy-mode: Editing modes. (line 6)
+* latex: Options. (line 145)
+* LaTeX fonts: Pens. (line 192)
+* LaTeX usage: LaTeX usage. (line 6)
+* latexmk: LaTeX usage. (line 30)
+* latin1: latin1. (line 6)
+* latitude: Data types. (line 136)
+* latticeshade: fill. (line 32)
+* layer: Drawing commands. (line 16)
+* leastsquares <1>: graph. (line 901)
+* leastsquares: stats. (line 6)
+* Left: graph. (line 284)
+* LeftRight: graph. (line 290)
+* LeftSide: label. (line 61)
+* LeftTicks: graph. (line 161)
+* LeftView: three. (line 399)
+* legend <1>: graph. (line 432)
+* legend <2>: draw. (line 64)
+* legend: Drawing commands. (line 31)
+* Legendre: Mathematical functions.
+ (line 48)
+* length <1>: three. (line 520)
+* length <2>: Arrays. (line 39)
+* length <3>: Paths and guides. (line 67)
+* length: Data types. (line 62)
+* letter: Configuring. (line 61)
+* lexorder: math. (line 68)
+* libgs <1>: Options. (line 150)
+* libgs: Configuring. (line 67)
+* libm routines: Mathematical functions.
+ (line 6)
+* libsigsegv <1>: Help. (line 33)
+* libsigsegv: Functions. (line 88)
+* limits: graph. (line 637)
+* line: Arrays. (line 344)
+* line mode: Arrays. (line 344)
+* Linear: graph. (line 682)
+* linecap: Pens. (line 129)
+* linejoin: Pens. (line 138)
+* lineskip: Pens. (line 178)
+* linetype: Pens. (line 115)
+* linewidth: Pens. (line 119)
+* locale: Data types. (line 293)
+* Log: graph. (line 682)
+* log: Mathematical functions.
+ (line 6)
+* log-log graph: graph. (line 713)
+* log10: Mathematical functions.
+ (line 6)
+* log1p: Mathematical functions.
+ (line 6)
+* log2 graph: graph. (line 762)
+* logarithmic graph: graph. (line 713)
+* logical operators: Arithmetic & logical.
+ (line 6)
+* longdashdotted: Pens. (line 95)
+* longdashed: Pens. (line 95)
+* longitude: Data types. (line 141)
+* loop: Programming. (line 8)
+* MacOS X binary distributions: MacOS X binary distributions.
+ (line 6)
+* makepen: Pens. (line 300)
+* map: Arrays. (line 141)
+* Margin: draw. (line 42)
+* Margin3: three. (line 577)
+* margins: three. (line 275)
+* Margins: draw. (line 42)
+* Margins3: three. (line 577)
+* mark: graph. (line 485)
+* markangle: markers. (line 38)
+* marker: graph. (line 485)
+* markers: markers. (line 6)
+* marknodes: graph. (line 485)
+* markuniform: graph. (line 485)
+* mask: Data types. (line 33)
+* math: math. (line 6)
+* mathematical functions: Mathematical functions.
+ (line 6)
+* max <1>: three. (line 520)
+* max <2>: Arrays. (line 225)
+* max <3>: Frames and pictures. (line 7)
+* max: Paths and guides. (line 269)
+* maxbound: Data types. (line 106)
+* maxtile: three. (line 222)
+* maxtimes: Paths and guides. (line 224)
+* maxviewport: three. (line 222)
+* MetaPost: MetaPost. (line 6)
+* MetaPost ... : Bezier curves. (line 70)
+* MetaPost cutafter: Paths and guides. (line 257)
+* MetaPost cutbefore: Paths and guides. (line 253)
+* MetaPost pickup: Pens. (line 6)
+* MetaPost whatever: MetaPost. (line 10)
+* Microsoft Windows: Microsoft Windows. (line 6)
+* MidArcArrow: draw. (line 26)
+* MidArcArrow3: three. (line 561)
+* MidArrow: draw. (line 26)
+* MidArrow3: three. (line 561)
+* midpoint: Paths and guides. (line 171)
+* MidPoint: label. (line 56)
+* min <1>: three. (line 520)
+* min <2>: Arrays. (line 218)
+* min <3>: Frames and pictures. (line 7)
+* min: Paths and guides. (line 265)
+* minbound: Data types. (line 103)
+* minipage: label. (line 118)
+* mintimes: Paths and guides. (line 219)
+* miterjoin: Pens. (line 138)
+* miterlimit: Pens. (line 147)
+* mktemp: Files. (line 44)
+* mm: Tutorial. (line 63)
+* mode: Files. (line 75)
+* monotonic: graph. (line 37)
+* mouse: GUI. (line 6)
+* mouse bindings: three. (line 149)
+* Move: Pens. (line 339)
+* MoveQuiet: Pens. (line 345)
+* multisample: three. (line 140)
+* N: Tutorial. (line 106)
+* name: Files. (line 88)
+* named arguments: Named arguments. (line 6)
+* natural: graph. (line 37)
+* new <1>: Arrays. (line 109)
+* new: Structures. (line 6)
+* newframe: Frames and pictures. (line 7)
+* newl: Files. (line 61)
+* newton: Mathematical functions.
+ (line 66)
+* next: Debugger. (line 42)
+* NFSS: Pens. (line 192)
+* nobasealign: Pens. (line 168)
+* NoFill <1>: Frames and pictures. (line 141)
+* NoFill: draw. (line 26)
+* NoMargin: draw. (line 42)
+* NoMargin3: three. (line 577)
+* none: Files. (line 61)
+* None: draw. (line 19)
+* normal: three. (line 506)
+* nosafe: Options. (line 169)
+* NOT: Arithmetic & logical.
+ (line 80)
+* notaknot: graph. (line 37)
+* NoTicks: graph. (line 161)
+* NoTicks3: graph3. (line 35)
+* null: Structures. (line 6)
+* nullpen <1>: Frames and pictures. (line 127)
+* nullpen: label. (line 14)
+* NURBS: three. (line 376)
+* O: three. (line 287)
+* obj: obj. (line 9)
+* oblique: three. (line 332)
+* obliqueX: three. (line 340)
+* obliqueY: three. (line 347)
+* obliqueZ: three. (line 332)
+* ode: ode. (line 9)
+* offset <1>: Options. (line 174)
+* offset: Pens. (line 115)
+* OmitTick: graph. (line 239)
+* OmitTickInterval: graph. (line 239)
+* OmitTickIntervals: graph. (line 239)
+* opacity: Pens. (line 222)
+* open: Files. (line 12)
+* OpenGL: three. (line 140)
+* operator: User-defined operators.
+ (line 6)
+* operator --: graph. (line 31)
+* operator ..: graph. (line 34)
+* operator answer: Interactive mode. (line 37)
+* operator cast: Casts. (line 30)
+* operator ecast: Casts. (line 57)
+* operator init <1>: Structures. (line 134)
+* operator init: Variable initializers.
+ (line 6)
+* operators: Operators. (line 6)
+* options: Options. (line 6)
+* OR: Arithmetic & logical.
+ (line 80)
+* orientation: Frames and pictures. (line 95)
+* orthographic: three. (line 351)
+* outformat: three. (line 140)
+* outprefix: Frames and pictures. (line 83)
+* output <1>: Options. (line 145)
+* output: Files. (line 36)
+* OutTicks: graph3. (line 35)
+* overloading functions: Functions. (line 44)
+* overwrite: Pens. (line 324)
+* P: Mathematical functions.
+ (line 48)
+* pack: label. (line 101)
+* packing: Rest arguments. (line 30)
+* pair <1>: Data types. (line 43)
+* pair: Tutorial. (line 51)
+* pairs: Arrays. (line 242)
+* paperheight: Configuring. (line 61)
+* papertype: Configuring. (line 61)
+* paperwidth: Configuring. (line 61)
+* parallelogram: flowchart. (line 50)
+* parametric surface: graph3. (line 101)
+* parametrized curve: graph. (line 637)
+* partialsum: math. (line 53)
+* patch-dependent colors: three. (line 81)
+* path <1>: flowchart. (line 81)
+* path <2>: three. (line 43)
+* path: Paths and guides. (line 7)
+* path markers: graph. (line 485)
+* path3: three. (line 6)
+* path[]: Tutorial. (line 134)
+* patterns <1>: patterns. (line 6)
+* patterns: Pens. (line 238)
+* PDF: Options. (line 145)
+* pdflatex: Options. (line 145)
+* pdfreloadOptions: Options. (line 131)
+* pdfviewer: Configuring. (line 6)
+* pdfviewerOptions: Options. (line 131)
+* pen: Pens. (line 6)
+* PenMargin: draw. (line 42)
+* PenMargin2: three. (line 577)
+* PenMargin3: three. (line 577)
+* PenMargins: draw. (line 42)
+* PenMargins2: three. (line 577)
+* PenMargins3: three. (line 577)
+* periodic: graph. (line 37)
+* perl: LaTeX usage. (line 30)
+* perpendicular: geometry. (line 6)
+* perspective: three. (line 376)
+* picture: Frames and pictures. (line 35)
+* picture alignment: Frames and pictures. (line 209)
+* piecewisestraight: Paths and guides. (line 83)
+* pixel: three. (line 584)
+* Pl: Mathematical functions.
+ (line 48)
+* plain: plain. (line 6)
+* planar: three. (line 89)
+* plane: three. (line 314)
+* planeproject: three. (line 503)
+* point <1>: three. (line 520)
+* point: Paths and guides. (line 86)
+* polar: Data types. (line 121)
+* polargraph: graph. (line 90)
+* polygon: graph. (line 485)
+* pop: Arrays. (line 39)
+* Portrait: Frames and pictures. (line 95)
+* postcontrol <1>: three. (line 520)
+* postcontrol: Paths and guides. (line 137)
+* postfix operators: Self & prefix operators.
+ (line 19)
+* postscript: Frames and pictures. (line 271)
+* PostScript fonts: Pens. (line 210)
+* PostScript subpath: Tutorial. (line 134)
+* pow10: Mathematical functions.
+ (line 6)
+* prc: three. (line 243)
+* precision: Files. (line 92)
+* precontrol <1>: three. (line 520)
+* precontrol: Paths and guides. (line 130)
+* prefix operators: Self & prefix operators.
+ (line 6)
+* private: Structures. (line 6)
+* programming: Programming. (line 6)
+* pstoedit: PostScript to Asymptote.
+ (line 6)
+* psview: Microsoft Windows. (line 16)
+* psviewer: Configuring. (line 6)
+* psviewerOptions: Options. (line 131)
+* pt: Tutorial. (line 63)
+* public: Structures. (line 6)
+* push: Arrays. (line 39)
+* Python usage: Interactive mode. (line 80)
+* quadraticroots: Arrays. (line 309)
+* quarticroots: math. (line 22)
+* quick reference: Description. (line 80)
+* quit <1>: Debugger. (line 54)
+* quit <2>: Interactive mode. (line 59)
+* quit: Tutorial. (line 37)
+* quote: Import. (line 116)
+* quotient: Arithmetic & logical.
+ (line 6)
+* RadialShade: Frames and pictures. (line 159)
+* radialshade: fill. (line 51)
+* RadialShadeDraw: Frames and pictures. (line 163)
+* radians: Mathematical functions.
+ (line 17)
+* radius <1>: three. (line 520)
+* radius: Paths and guides. (line 126)
+* Rainbow: palette. (line 12)
+* rand: Mathematical functions.
+ (line 39)
+* randMax: Mathematical functions.
+ (line 39)
+* read: Arrays. (line 385)
+* reading: Files. (line 12)
+* reading string arrays: Arrays. (line 354)
+* readline: Files. (line 134)
+* real: Data types. (line 33)
+* realDigits: Data types. (line 33)
+* realEpsilon: Data types. (line 33)
+* realMax: Data types. (line 33)
+* realMin: Data types. (line 33)
+* realmult: Data types. (line 97)
+* rectangle: flowchart. (line 37)
+* recursion: Functions. (line 88)
+* reference: Description. (line 80)
+* reflect: Transforms. (line 51)
+* Relative: label. (line 51)
+* relpoint: Paths and guides. (line 167)
+* reltime: Paths and guides. (line 163)
+* remainder: Mathematical functions.
+ (line 6)
+* rename: Files. (line 151)
+* render <1>: Options. (line 145)
+* render: three. (line 47)
+* replace: Data types. (line 254)
+* resetdefaultpen: Pens. (line 353)
+* rest arguments: Rest arguments. (line 6)
+* restore: Frames and pictures. (line 265)
+* restricted: Structures. (line 6)
+* return: Debugger. (line 48)
+* reverse <1>: three. (line 520)
+* reverse <2>: Arrays. (line 146)
+* reverse <3>: Paths and guides. (line 174)
+* reverse: Data types. (line 250)
+* rewind: Files. (line 92)
+* rfind: Data types. (line 231)
+* rgb: Pens. (line 30)
+* Riemann zeta function: Mathematical functions.
+ (line 48)
+* Right: graph. (line 287)
+* RightSide: label. (line 61)
+* RightTicks: graph. (line 161)
+* RightView: three. (line 399)
+* rotate: three. (line 471)
+* Rotate: label. (line 36)
+* Rotate(pair z): label. (line 39)
+* round: Mathematical functions.
+ (line 26)
+* roundcap: Pens. (line 129)
+* roundedpath: roundedpath. (line 6)
+* roundjoin: Pens. (line 138)
+* roundrectangle: flowchart. (line 69)
+* RPM: UNIX binary distributions.
+ (line 6)
+* runtime imports: Import. (line 98)
+* Russian: unicode. (line 7)
+* S: Tutorial. (line 106)
+* safe: Options. (line 169)
+* save: Frames and pictures. (line 262)
+* saveline: Files. (line 134)
+* scale: three. (line 470)
+* Scale: graph. (line 698)
+* scale <1>: graph. (line 682)
+* scale <2>: Transforms. (line 39)
+* scale: Pens. (line 115)
+* Scale: label. (line 45)
+* scale3: three. (line 467)
+* scaled graph: graph. (line 663)
+* scientific graph: graph. (line 397)
+* scroll: Files. (line 108)
+* search: Arrays. (line 164)
+* search paths: Search paths. (line 6)
+* Seascape: Frames and pictures. (line 100)
+* secondary axis: graph. (line 812)
+* secondaryX: graph. (line 812)
+* secondaryY: graph. (line 812)
+* seconds: Data types. (line 306)
+* seek: Files. (line 92)
+* seekeof: Files. (line 92)
+* segment: math. (line 50)
+* segmentation fault: Help. (line 33)
+* self operators: Self & prefix operators.
+ (line 6)
+* sequence: Arrays. (line 128)
+* settings <1>: Options. (line 116)
+* settings: Configuring. (line 23)
+* sgn: Mathematical functions.
+ (line 26)
+* shading: fill. (line 32)
+* shift <1>: three. (line 455)
+* shift: Transforms. (line 27)
+* Shift: label. (line 33)
+* shiftless: Transforms. (line 53)
+* shipout: Frames and pictures. (line 83)
+* showtarget: three. (line 351)
+* Si: Mathematical functions.
+ (line 48)
+* side: Paths and guides. (line 299)
+* signedint: Files. (line 75)
+* SimpleHead: draw. (line 26)
+* simplex: simplex. (line 6)
+* simpson: Mathematical functions.
+ (line 82)
+* Sin: Mathematical functions.
+ (line 20)
+* sin: Mathematical functions.
+ (line 6)
+* single precision: Files. (line 75)
+* singleint: Files. (line 75)
+* singlereal: Files. (line 75)
+* sinh: Mathematical functions.
+ (line 6)
+* SixViews: three. (line 414)
+* SixViewsFR: three. (line 414)
+* SixViewsUS: three. (line 414)
+* size <1>: Options. (line 145)
+* size <2>: three. (line 520)
+* size <3>: Frames and pictures. (line 43)
+* size: Paths and guides. (line 72)
+* size3: three. (line 272)
+* slant: Transforms. (line 45)
+* Slant: label. (line 42)
+* sleep: Data types. (line 351)
+* slice: Paths and guides. (line 242)
+* slices: Slices. (line 6)
+* slide: slide. (line 6)
+* slope: math. (line 44)
+* slopefield: slopefield. (line 6)
+* sncndn: Mathematical functions.
+ (line 48)
+* solid: Pens. (line 95)
+* solids: solids. (line 9)
+* solve: Arrays. (line 278)
+* sort: Arrays. (line 184)
+* Spline <1>: graph3. (line 101)
+* Spline: graph. (line 34)
+* split: Data types. (line 263)
+* sqrt: Mathematical functions.
+ (line 6)
+* squarecap: Pens. (line 129)
+* srand: Mathematical functions.
+ (line 39)
+* stack overflow <1>: Help. (line 33)
+* stack overflow: Functions. (line 88)
+* static: Static. (line 6)
+* stats: stats. (line 6)
+* stdin: Files. (line 48)
+* stdout: Files. (line 48)
+* step: Debugger. (line 39)
+* stickframe: markers. (line 16)
+* stop: Debugger. (line 10)
+* straight: three. (line 520)
+* Straight: graph. (line 31)
+* straight: Paths and guides. (line 79)
+* strftime: Data types. (line 298)
+* string: Data types. (line 181)
+* stroke: fill. (line 36)
+* strokepath: Paths and guides. (line 308)
+* strptime: Data types. (line 306)
+* struct: Structures. (line 6)
+* structures: Structures. (line 6)
+* subpath <1>: three. (line 520)
+* subpath: Paths and guides. (line 177)
+* subpictures: Frames and pictures. (line 103)
+* substr: Data types. (line 246)
+* Subversion: Subversion. (line 6)
+* sum: Arrays. (line 213)
+* superpath: Tutorial. (line 134)
+* Suppress: Pens. (line 331)
+* SuppressQuiet: Pens. (line 335)
+* surface <1>: graph3. (line 101)
+* surface: three. (line 47)
+* SVG: Options. (line 150)
+* SVN: Subversion. (line 6)
+* system <1>: Options. (line 169)
+* system: Data types. (line 328)
+* syzygy: syzygy. (line 6)
+* tab: Files. (line 61)
+* tab completion: Tutorial. (line 37)
+* Tan: Mathematical functions.
+ (line 20)
+* tan: Mathematical functions.
+ (line 6)
+* tanh: Mathematical functions.
+ (line 6)
+* target: three. (line 351)
+* tell: Files. (line 92)
+* tension <1>: three. (line 6)
+* tension: Bezier curves. (line 56)
+* tensionSpecifier: Paths and guides. (line 399)
+* tensor product shading: fill. (line 78)
+* tensorshade: fill. (line 78)
+* tessellation: three. (line 112)
+* tex <1>: Options. (line 145)
+* tex: Frames and pictures. (line 278)
+* TeX fonts: Pens. (line 201)
+* TeX string: Data types. (line 181)
+* texcommand: Configuring. (line 67)
+* TeXHead: draw. (line 26)
+* TeXHead3: three. (line 561)
+* texpath <1>: label. (line 115)
+* texpath: Configuring. (line 67)
+* texpreamble: Frames and pictures. (line 286)
+* texreset: Frames and pictures. (line 289)
+* textbook graph: graph. (line 372)
+* tgz: UNIX binary distributions.
+ (line 6)
+* thick: three. (line 123)
+* thin: three. (line 123)
+* this: Structures. (line 6)
+* three: three. (line 6)
+* ThreeViews: three. (line 414)
+* ThreeViewsFR: three. (line 414)
+* ThreeViewsUS: three. (line 414)
+* tick: graph. (line 343)
+* Ticks: graph. (line 161)
+* ticks: graph. (line 161)
+* tildeframe: markers. (line 26)
+* tile: Pens. (line 251)
+* tilings: Pens. (line 238)
+* time <1>: math. (line 30)
+* time: Data types. (line 298)
+* times: Paths and guides. (line 211)
+* Top: graph. (line 137)
+* TopView: three. (line 399)
+* trace: Debugger. (line 51)
+* trailingzero: graph. (line 175)
+* transform <1>: three. (line 495)
+* transform: Transforms. (line 6)
+* transform3: three. (line 450)
+* transparency: Pens. (line 222)
+* transpose: Arrays. (line 205)
+* tree: tree. (line 9)
+* trembling: trembling. (line 6)
+* triangle: geometry. (line 6)
+* triangles: three. (line 112)
+* triangulate: contour. (line 156)
+* tridiagonal: Arrays. (line 266)
+* trigonometric integrals: Mathematical functions.
+ (line 48)
+* triple: Data types. (line 110)
+* TrueMargin: draw. (line 42)
+* TrueMargin3: three. (line 577)
+* tube <1>: tube. (line 6)
+* tube: three. (line 123)
+* tutorial: Tutorial. (line 6)
+* type1cm: Pens. (line 178)
+* typedef <1>: Functions. (line 36)
+* typedef: Data types. (line 361)
+* U3D: embed. (line 23)
+* undefined: Paths and guides. (line 273)
+* UnFill: Frames and pictures. (line 152)
+* unfill: fill. (line 110)
+* UnFill: draw. (line 26)
+* unicode: unicode. (line 6)
+* uniform: Arrays. (line 155)
+* Uninstall: Uninstall. (line 6)
+* unique: math. (line 64)
+* unit: Data types. (line 80)
+* unitbox <1>: three. (line 320)
+* unitbox: Tutorial. (line 155)
+* unitcircle <1>: three. (line 287)
+* unitcircle: Tutorial. (line 128)
+* unitrand: Mathematical functions.
+ (line 39)
+* unitsize <1>: Frames and pictures. (line 64)
+* unitsize: Tutorial. (line 86)
+* UNIX binary distributions: UNIX binary distributions.
+ (line 6)
+* unpacking: Rest arguments. (line 39)
+* unravel: Import. (line 30)
+* up: three. (line 351)
+* update: Files. (line 36)
+* UpsideDown: Frames and pictures. (line 95)
+* usepackage: Frames and pictures. (line 291)
+* user coordinates: Tutorial. (line 86)
+* user-defined operators: User-defined operators.
+ (line 6)
+* usleep: Data types. (line 354)
+* value: math. (line 38)
+* var: Variable initializers.
+ (line 63)
+* variable initializers: Variable initializers.
+ (line 6)
+* vectorfield: graph. (line 974)
+* vectorfield3: graph3. (line 160)
+* vectorization: Arrays. (line 323)
+* verbatim: Frames and pictures. (line 271)
+* vertex-dependent colors: three. (line 81)
+* Vertical: flowchart. (line 81)
+* viewportheight: LaTeX usage. (line 51)
+* viewportmargin: three. (line 275)
+* viewportsize: three. (line 275)
+* viewportwidth: LaTeX usage. (line 51)
+* views: three. (line 243)
+* vim: Editing modes. (line 33)
+* virtual functions: Structures. (line 181)
+* void: Data types. (line 10)
+* W: Tutorial. (line 106)
+* whatever: Paths and guides. (line 237)
+* Wheel: palette. (line 22)
+* wheel mouse: GUI. (line 6)
+* while: Programming. (line 29)
+* white-space string delimiter mode: Arrays. (line 354)
+* width: LaTeX usage. (line 51)
+* windingnumber: Paths and guides. (line 273)
+* word: Arrays. (line 354)
+* write <1>: Arrays. (line 394)
+* write: Files. (line 53)
+* X: three. (line 287)
+* xasy: GUI. (line 6)
+* xaxis3: graph3. (line 7)
+* xdr: Files. (line 75)
+* xelatex: Options. (line 145)
+* xequals: graph. (line 294)
+* XEquals: graph. (line 280)
+* xlimits: graph. (line 637)
+* XOR: Arithmetic & logical.
+ (line 80)
+* xpart: Data types. (line 91)
+* xscale: Transforms. (line 33)
+* xscale3: three. (line 458)
+* xtick: graph. (line 343)
+* XY: three. (line 480)
+* XYEquals: graph3. (line 21)
+* XYZero: graph3. (line 21)
+* XZEquals: graph3. (line 21)
+* XZero: graph. (line 275)
+* XZZero: graph3. (line 21)
+* Y <1>: three. (line 287)
+* Y: Mathematical functions.
+ (line 6)
+* yaxis3: graph3. (line 7)
+* yequals: graph. (line 294)
+* YEquals: graph. (line 130)
+* ylimits: graph. (line 637)
+* ypart: Data types. (line 94)
+* yscale: Transforms. (line 36)
+* yscale3: three. (line 461)
+* ytick: graph. (line 343)
+* YX: three. (line 495)
+* YZ: three. (line 495)
+* YZEquals: graph3. (line 21)
+* YZero: graph. (line 125)
+* YZZero: graph3. (line 21)
+* Z: three. (line 287)
+* zaxis3: graph3. (line 7)
+* zero_Ai: Mathematical functions.
+ (line 48)
+* zero_Ai_deriv: Mathematical functions.
+ (line 48)
+* zero_Bi: Mathematical functions.
+ (line 48)
+* zero_Bi_deriv: Mathematical functions.
+ (line 48)
+* zero_J: Mathematical functions.
+ (line 48)
+* zerowinding: Pens. (line 152)
+* zeta: Mathematical functions.
+ (line 48)
+* zpart: Data types. (line 163)
+* zscale3: three. (line 464)
+* ZX: three. (line 495)
+* ZY: three. (line 495)
+* |: Arithmetic & logical.
+ (line 62)
+* ||: Arithmetic & logical.
+ (line 59)
+
+
+
+Tag Table:
+Node: Top575
+Node: Description6859
+Node: Installation10475
+Node: UNIX binary distributions11519
+Node: MacOS X binary distributions12625
+Node: Microsoft Windows13509
+Ref: psview14219
+Node: Configuring15153
+Node: Search paths19373
+Node: Compiling from UNIX source20215
+Node: Editing modes23112
+Node: Subversion25544
+Node: Uninstall25992
+Node: Tutorial26342
+Ref: unitcircle30640
+Node: Drawing commands32696
+Node: draw34407
+Ref: arrows35555
+Node: fill40798
+Ref: gradient shading41842
+Node: clip46399
+Node: label46991
+Ref: Label47589
+Node: Bezier curves53392
+Node: Programming57094
+Ref: array iteration57908
+Node: Data types59014
+Ref: format68211
+Node: Paths and guides72464
+Ref: circle72718
+Ref: extension82276
+Node: Pens89331
+Ref: fillrule96699
+Ref: basealign97596
+Ref: transparency100422
+Ref: makepen103865
+Ref: overwrite104703
+Node: Transforms105913
+Node: Frames and pictures107704
+Ref: envelope108845
+Ref: size109928
+Ref: unitsize110915
+Ref: shipout111975
+Ref: filltype114308
+Ref: add117445
+Ref: add about118391
+Ref: tex121329
+Node: Files122203
+Ref: cd123186
+Ref: scroll127860
+Node: Variable initializers130775
+Node: Structures133500
+Node: Operators140902
+Node: Arithmetic & logical141216
+Node: Self & prefix operators143189
+Node: User-defined operators143977
+Node: Implicit scaling144888
+Node: Functions145451
+Ref: stack overflow148204
+Node: Default arguments148768
+Node: Named arguments149507
+Node: Rest arguments152078
+Node: Mathematical functions155199
+Node: Arrays159864
+Ref: sort166853
+Ref: tridiagonal169257
+Ref: solve170485
+Node: Slices174679
+Node: Casts178569
+Node: Import180534
+Node: Static185771
+Node: LaTeX usage188665
+Node: Base modules195077
+Node: plain197577
+Node: simplex198229
+Node: math198502
+Node: interpolate201207
+Node: geometry201486
+Node: trembling202080
+Node: stats202349
+Node: patterns202609
+Node: markers202845
+Node: tree204628
+Node: binarytree204816
+Node: drawtree205436
+Node: syzygy205640
+Node: feynman205914
+Node: roundedpath206189
+Node: animation206472
+Ref: animate206892
+Node: embed208031
+Node: slide208998
+Node: MetaPost209338
+Node: unicode210054
+Node: latin1210942
+Node: babel211310
+Node: labelpath211539
+Node: labelpath3212359
+Node: annotate212670
+Node: CAD213141
+Node: graph213451
+Ref: ticks220580
+Ref: pathmarkers233907
+Ref: marker234372
+Ref: markuniform234723
+Ref: errorbars236514
+Ref: automatic scaling240551
+Node: palette251180
+Ref: images251298
+Ref: image255470
+Ref: logimage255948
+Ref: penimage257009
+Ref: penfunctionimage257230
+Node: three257954
+Ref: PostScript3D283633
+Node: obj285325
+Node: graph3285577
+Ref: GaussianSurface290732
+Node: grid3291836
+Node: solids292576
+Node: tube293524
+Node: flowchart295759
+Node: contour300328
+Node: contour3305418
+Node: slopefield305725
+Node: ode307162
+Node: Options307422
+Ref: configuration file313467
+Ref: settings313467
+Ref: convert314706
+Node: Interactive mode317853
+Ref: history320006
+Node: GUI321311
+Node: GUI installation321814
+Node: GUI usage322944
+Node: PostScript to Asymptote323847
+Node: Help324603
+Node: Debugger326330
+Node: Credits328115
+Node: Index329047
+
+End Tag Table