diff options
Diffstat (limited to 'graphics/asymptote/doc/asymptote.texi')
-rw-r--r-- | graphics/asymptote/doc/asymptote.texi | 538 |
1 files changed, 345 insertions, 193 deletions
diff --git a/graphics/asymptote/doc/asymptote.texi b/graphics/asymptote/doc/asymptote.texi index ee0e3ae49e..f37789114f 100644 --- a/graphics/asymptote/doc/asymptote.texi +++ b/graphics/asymptote/doc/asymptote.texi @@ -81,6 +81,7 @@ Installation * Compiling from UNIX source:: Building @code{Asymptote} from scratch * Editing modes:: Convenient @code{emacs} and @code{vim} modes * Git:: Getting the latest development source +* Building the documentation:: Building the documentation * Uninstall:: Goodbye, @code{Asymptote}! Tutorial @@ -105,6 +106,7 @@ Programming * Pens:: Colors, line types, line widths, font sizes * Transforms:: Affine transforms * Frames and pictures:: Canvases for immediate and deferred drawing +* Deferred drawing:: Witholding drawing until all data is available * Files:: Reading and writing your data * Variable initializers:: Initialize your variables * Structures:: Organize your data @@ -141,6 +143,7 @@ Base modules * plain:: Default @code{Asymptote} base file * simplex:: Linear programming: simplex method +* simplex2:: Two-variable simplex method * math:: Extend @code{Asymptote}'s math capabilities * interpolate:: Interpolation routines * geometry:: Geometry routines @@ -308,6 +311,7 @@ A quick reference card for @code{Asymptote} is available at * Compiling from UNIX source:: Building @code{Asymptote} from scratch * Editing modes:: Convenient @code{emacs} and @code{vim} modes * Git:: Getting the latest development source +* Building the documentation:: Building the documentation * Uninstall:: Goodbye, @code{Asymptote}! @end menu @@ -404,7 +408,7 @@ The @code{ImageMagick} package from @noindent is required to support output formats other than @acronym{HTML}, -@acronym{PDF}, @acronym{SVG}, and @acronym{PNG} (@pxref{convert}). +@acronym{PDF}, @acronym{SVG}, and @acronym{PNG} (@pxref{magick}). The @code{Python 3} interpreter from @url{https://www.python.org} is only required if you wish to try out the graphical user interface (@pxref{GUI}). @@ -516,7 +520,7 @@ configuration variables @code{paperwidth} and @code{paperheight}. @cindex @code{texcommand} @cindex @code{dvips} @cindex @code{dvisvgm} -@cindex @code{convert} +@cindex @code{magick} @cindex @code{ImageMagick} @cindex @code{asygl} These additional configuration variables normally do not require adjustment: @@ -531,6 +535,7 @@ asygl @end verbatim @noindent +@cindex @code{warn} Warnings (such as "unbounded" and "offaxis") may be enabled or disabled with the functions @verbatim @@ -792,6 +797,21 @@ apt-get build-dep asymptote @end verbatim @noindent +@node Building the documentation +@section Building the documentation +Here are instructions for building the documentation: +@verbatim +cd doc +make # for both the PDF version doc/asymptote.pdf and the HTML version +cd png +make # for the HTML version only: doc/png/index.html +@end verbatim +Note that the @code{HTML} version cannot be built without +executing @code{make} from @code{doc} folder first. + +The @code{asy} executable is required for compiling the diagrams +in the documentation. + @node Uninstall, , Git, Installation @section Uninstall @cindex uninstall @@ -883,7 +903,7 @@ followed by @code{Enter}, to obtain the above image. @cindex arrow keys @cindex erase @cindex quit -@noindent + At this point you can type further @code{draw} commands, which will be added to the displayed figure, @code{erase} to clear the canvas, @verbatim @@ -1123,7 +1143,8 @@ use in constructing an optional legend entry. @cindex @code{Bar} @cindex @code{Bars} @cindex @code{barsize} -Bars are useful for indicating dimensions. The possible values of + +Bars @code{bar} are useful for indicating dimensions. The possible values of @code{bar} are @code{None}, @code{BeginBar}, @code{EndBar} (or equivalently @code{Bar}), and @code{Bars} (which draws a bar at both ends of the path). Each of these bar specifiers (except for @@ -1133,6 +1154,7 @@ bar length is @code{barsize(pen)}. @cindex arrows @anchor{arrows} +@cindex @code{arrowbar} @cindex @code{None} @cindex @code{Blank} @cindex @code{BeginArrow} @@ -1140,77 +1162,116 @@ bar length is @code{barsize(pen)}. @cindex @code{EndArrow} @cindex @code{Arrow} @cindex @code{Arrows} -@cindex @code{FillDraw} -@cindex @code{Fill} -@cindex @code{Draw} -@cindex @code{NoFill} -@cindex @code{UnFill} + +The possible values of @code{arrow} are @code{None}, @code{Blank} +(which draws no arrows or path), @code{BeginArrow}, @code{MidArrow}, +@code{EndArrow} (or equivalently @code{Arrow}), +and @code{Arrows} (which draws an arrow at both ends of the path). + @cindex @code{BeginArcArrow} @cindex @code{MidArcArrow} @cindex @code{EndArcArrow} @cindex @code{ArcArrow} @cindex @code{ArcArrows} +There are also arrow versions with +slightly modified default values of @code{size} and @code{angle} suitable for +curved arrows: @code{BeginArcArrow}, @code{EndArcArrow} (or equivalently +@code{ArcArrow}), @code{MidArcArrow}, and @code{ArcArrows}. + +For example: +@verbatim +draw((0,0)--(1,1),arrow=Arrows); +@end verbatim +All of the arrow specifiers except for @code{None} and @code{Blank} +may be given optional arguments, for example: +@verbatim +draw((0,0)--(1,1),arrow=Arrow( + arrowhead=HookHead,size=3mm,angle=20,filltype=Draw,position=0.9)); +@end verbatim + +The function @code{Arrow} has the signature +@verbatim +arrowbar Arrow(arrowhead arrowhead=DefaultHead, + real size=0, real angle=arrowangle, + filltype filltype=null, position position=EndPoint) +@end verbatim +@noindent +Calling @code{Arrow()} returns @code{Arrow}, which is an @code{arrowbar} object. +The parameters are: + +@itemize +@cindex @code{arrowhead} @cindex @code{DefaultHead} @cindex @code{SimpleHead} @cindex @code{HookHead} @cindex @code{TeXHead} -The possible values of @code{arrow} are @code{None}, @code{Blank} -(which draws no arrows or path), @code{BeginArrow}, @code{MidArrow}, -@code{EndArrow} (or equivalently @code{Arrow}), -and @code{Arrows} (which draws an arrow at both ends of the path). -All of the arrow specifiers except for @code{None} and @code{Blank} -may be given the optional arguments arrowhead @code{arrowhead} (one of +@item @code{arrowhead} +can be one of the predefined arrowhead styles @code{DefaultHead}, @code{SimpleHead}, -@code{HookHead}, @code{TeXHead}), -real @code{size} (arrowhead size in @code{PostScript} coordinates), -real @code{angle} (arrowhead angle -in degrees), filltype @code{filltype} (one of @code{FillDraw}, @code{Fill}, -@code{NoFill}, @code{UnFill}, @code{Draw}) and (except for -@code{MidArrow} and @code{Arrows}) a real @code{position} (in the +@code{HookHead}, @code{TeXHead}. +@item real @code{size} is the arrowhead size in @code{PostScript} coordinates. + +The default arrowhead size when drawn +with a pen @code{p} is @code{arrowsize(p)}. +@item real @code{angle} is the arrowhead angle +in degrees. + +@item filltype @code{filltype} (@pxref{filltype}), +@item (except for +@code{MidArrow} and @code{Arrows}) real @code{position} (in the sense of @code{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 @code{p} is @code{arrowsize(p)}. There are also arrow versions with -slightly modified default values of @code{size} and @code{angle} suitable for -curved arrows: @code{BeginArcArrow}, @code{EndArcArrow} (or equivalently -@code{ArcArrow}), @code{MidArcArrow}, and @code{ArcArrows}. +the arrow should be placed. +@end itemize +Margins @code{margin} can be used to shrink the visible portion of a path by +@code{labelmargin(p)} to avoid overlap with other drawn objects. + +Typical values of @code{margin} +are: +@table @code @cindex @code{NoMargin} +@item NoMargin @cindex @code{BeginMargin} +@item BeginMargin @cindex @code{EndMargin} @cindex @code{Margin} +@item EndMargin +(equivalently @code{Margin}) @cindex @code{Margins} +@item Margins +leaves a margin at both ends of the path. +@item Margin(real begin, real end=begin) +specify the size of the beginning and ending margin, respectively, +in multiples of the units @code{labelmargin(p)} used for aligning labels. @cindex @code{BeginPenMargin} +@item BeginPenMargin @cindex @code{EndPenMargin} @cindex @code{PenMargin} +@item EndPenMargin +(equivalently @code{PenMargin}) @cindex @code{PenMargins} +@item PenMargins +@item PenMargin(real begin, real end=begin) +specify a margin in units of +the pen line width, taking account of the pen line width when drawing +the path or arrow. +@cindex @code{DotMargin} +@item DotMargin +an abbreviation for @code{PenMargin(-0.5*dotfactor,0.5*dotfactor)}, +used to draw from the usual beginning point just up to the boundary of an +end dot of width @code{dotfactor*linewidth(p)}. @cindex @code{BeginDotMargin} +@item BeginDotMargin @cindex @code{EndDotMargin} -@cindex @code{DotMargin} @cindex @code{DotMargins} -@cindex @code{Margin} +@item DotMargins +work similarly. @cindex @code{TrueMargin} -Margins can be used to shrink the visible portion of a path by -@code{labelmargin(p)} to avoid overlap with other drawn objects. -Typical values of @code{margin} -are @code{NoMargin}, @code{BeginMargin}, @code{EndMargin} (or -equivalently @code{Margin}), and @code{Margins} (which leaves a margin -at both ends of the path). One may use -@code{Margin(real begin, real end=begin)} -to specify the size of the beginning and ending margin, respectively, -in multiples of the units @code{labelmargin(p)} used for aligning labels. -Alternatively, @code{BeginPenMargin}, @code{EndPenMargin} -(or equivalently @code{PenMargin}), @code{PenMargins}, -@code{PenMargin(real begin, real end=begin)} 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 @code{DotMargin}, an -abbreviation for @code{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 @code{dotfactor*linewidth(p)}. The qualifiers -@code{BeginDotMargin}, @code{EndDotMargin}, and @code{DotMargins} work -similarly. The qualifier @code{TrueMargin(real begin, real end=begin)} -allows one to specify a margin directly in @code{PostScript} units, +@item TrueMargin(real begin, real end=begin) +specify a margin directly in @code{PostScript} units, independent of the pen line width. +@end table The use of arrows, bars, and margins is illustrated by the examples @code{@uref{https://asymptote.sourceforge.io/gallery/Pythagoras.svg,,Pythagoras}@uref{https://asymptote.sourceforge.io/gallery/Pythagoras.asy,,.asy}} and @@ -1484,6 +1545,7 @@ For an illustration of picture clipping, see the first example in @ref{LaTeX usa @node label, , clip, Drawing commands @section label @cindex @code{label} +@cindex @code{labelmargin} @verbatim void label(picture pic=currentpicture, Label L, pair position, align align=NoAlign, pen p=currentpen, filltype filltype=NoFill) @@ -1494,6 +1556,16 @@ Draw Label @code{L} on picture @code{pic} using pen @code{p}. If coordinate @code{position}; otherwise it will be aligned in the direction of @code{align} and displaced from @code{position} by the @code{PostScript} offset @code{align*labelmargin(p)}. + +Here, @code{real labelmargin(pen p=currentpen)} is a quantity used to align labels. +In the code below, +@verbatim +label("abcdefg",(0,0),align=up,basealign); +@end verbatim +@noindent +the baseline of the label will be exactly +@code{labelmargin(currentpen)} @code{PostScript} units above the center. + @cindex @code{Align} The constant @code{Align} can be used to align the bottom-left corner of the label at @code{position}. @@ -1609,11 +1681,14 @@ label(graphic("file.eps","width=1cm"),(0,0),NE); layer(); @end verbatim +@anchor{baseline} @cindex @code{baseline} The @code{string baseline(string s, string template="\strut")} -function can be used to enlarge the bounding box of labels to match a +function can be used to enlarge the bounding box of a label to match a given template, so that their baselines will be typeset on a horizontal line. See @code{@uref{https://asymptote.sourceforge.io/gallery/Pythagoras.svg,,Pythagoras}@uref{https://asymptote.sourceforge.io/gallery/Pythagoras.asy,,.asy}} for an example. +Alternatively, the pen @code{basealign} may be used to force labels to +respect the TeX baseline (@pxref{basealign}). One can prevent labels from overwriting one another with the @code{overwrite} pen attribute (@pxref{overwrite}). @@ -1626,7 +1701,10 @@ A group of objects may be packed together into single frame with the routine frame pack(pair align=2S ... object inset[]); @end verbatim @noindent -To draw or fill a box (or ellipse or other path) around a Label and +@anchor{envelope} +@cindex @code{envelope} +@cindex @code{object} +To draw or fill a box (or ellipse or other path) around a @code{Label} and return the bounding object, use one of the routines @verbatim object draw(picture pic=currentpicture, Label L, envelope e, @@ -1638,8 +1716,7 @@ object draw(picture pic=currentpicture, Label L, envelope e, pair position, @end verbatim @noindent Here @code{envelope} is a boundary-drawing routine such as @code{box}, -@code{roundbox}, or @code{ellipse} defined in @code{plain_boxes.asy} -(@pxref{envelope}). +@code{roundbox}, or @code{ellipse} defined in @code{plain_boxes.asy}. @cindex @code{texpath} The function @code{path[] texpath(Label L)} returns the path array that @@ -1774,6 +1851,7 @@ should coincide with the first node of the second path). * Pens:: Colors, line types, line widths, font sizes * Transforms:: Affine transforms * Frames and pictures:: Canvases for immediate and deferred drawing +* Deferred drawing:: Witholding drawing until all data is available * Files:: Reading and writing your data * Variable initializers:: Initialize your variables * Structures:: Organize your data @@ -2222,13 +2300,13 @@ individual characters. The inverse operation is provided by @cindex @code{format} returns a string containing @code{n} formatted according to the C-style format string @code{s} using locale @code{locale} (or the current locale if an -empty string is specified), following the behaviour of the C function +empty string is specified), following the behavior of the C function @code{fprintf}), except that only one data field is allowed. @item string format(string s=defaultformat, bool forcemath=false, string s=defaultseparator, real x, string locale="") returns a string containing @code{x} formatted according to the C-style format string @code{s} using locale @code{locale} (or the current locale if an -empty string is specified), following the behaviour of the C function +empty string is specified), following the behavior of the C function @code{fprintf}), except that only one data field is allowed, trailing zeros are removed by default (unless @code{#} is specified), and if @code{s} specifies math mode or @code{forcemath=true}, @TeX{} is @@ -2665,7 +2743,7 @@ Note that @code{lastcut.before} plays the role of the @cindex @code{buildcycle} @item 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 +consecutively intersecting paths, following the behavior of the @code{MetaPost buildcycle} command. @cindex @code{min} @@ -2704,7 +2782,7 @@ otherwise. @cindex @code{inside} @item pair inside(path p, pen fillrule=currentpen); -returns an arbitrary point strictly inside a cyclic path @code{p} +returns an arbitrary point strictly inside a nondegenerate cyclic path @code{p} according to the fill rule @code{fillrule} (@pxref{fillrule}). @cindex @code{strokepath} @@ -3100,13 +3178,22 @@ pen basealign=basealign(1); @end verbatim @noindent -The default setting, @code{nobasealign},which may be changed with +The default setting, @code{nobasealign}, which may be changed with @code{defaultpen(pen)}, causes the label alignment routines to use the full label bounding box for alignment. In contrast, @code{basealign} requests that the @TeX{} baseline be respected. The base align setting of a pen is returned by @code{int basealign(pen p=currentpen)}. +For example, in the following image, the baselines of green @math{\pi} and +@math{\gamma} are aligned, while the bottom border of red @math{-\pi} +and @math{-\gamma} are aligned. +@verbatiminclude basealign.asy +@sp 1 +@center @image{./basealign} + +Another method for aligning baselines is provided by the @code{baseline} function (@pxref{baseline}). + @cindex @code{fontsize} @cindex @code{lineskip} @cindex @code{defaultpen} @@ -3173,7 +3260,6 @@ pen ZapfDingbats(string series="m", string shape="n"); @item Starting with the 2018/04/01 release, @LaTeX{} takes UTF-8 as the new default input encoding. However, you can still set different input encoding (so as the font, font encoding or even language context). -@noindent @cindex Cyrillic @cindex Russian Here is an example for @code{cp1251} and Russian language in Cyrillic script @@ -3225,7 +3311,7 @@ as described in Since @code{PostScript} does not support transparency, this feature is only effective with the @code{-f pdf} output format option; other formats can be produced from the resulting @acronym{PDF} file with the -@code{ImageMagick} @code{convert} program. +@code{ImageMagick} @code{magick} program. Labels are always drawn with an @code{opacity} of 1. A simple example of transparent filling is provided in the example file @code{@uref{https://asymptote.sourceforge.io/gallery/transparency.svg,,transparency}@uref{https://asymptote.sourceforge.io/gallery/transparency.asy,,.asy}}. @@ -3300,7 +3386,7 @@ the pen attribute @code{overwrite}, which takes a single argument: @cindex @code{Allow} @cindex @code{defaultpen} @item Allow -Allow labels to overwrite one another. This is the default behaviour (unless +Allow labels to overwrite one another. This is the default behavior (unless overridden with @code{defaultpen(pen)}. @cindex @code{Suppress} @@ -3404,7 +3490,7 @@ The function @code{bool isometry(transform t)} can be used to test if @code{t} is an isometry (preserves distance). -@node Frames and pictures, Files, Transforms, Programming +@node Frames and pictures @section Frames and pictures @table @code @@ -3440,24 +3526,6 @@ A frame obtained by aligning frame @code{f} in the direction frame align(frame f, pair align); @end verbatim -@cindex @code{box} -@cindex @code{ellipse} -@anchor{envelope} -@cindex @code{envelope} -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 @code{envelope} routines -@verbatim -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); -@end verbatim - @item picture @cindex @code{picture} Pictures are high-level structures (@pxref{Structures}) defined in @@ -3571,7 +3639,7 @@ To rotate the page by @math{-90} degrees, use the orientation @code{Seascape}. The orientation @code{UpsideDown} rotates the page by 180 degrees. @cindex subpictures -@cindex @code{fit} +@cindex @code{picture.fit} A picture @code{pic} can be explicitly fit to a frame by calling @verbatim frame pic.fit(real xsize=pic.xsize, real ysize=pic.ysize, @@ -3580,13 +3648,14 @@ frame pic.fit(real xsize=pic.xsize, real ysize=pic.ysize, The default size and aspect ratio settings are those given to the @code{size} command (which default to @code{0}, @code{0}, and @code{true}, respectively). -@cindex @code{calculateTransform} +@cindex @code{picture.calculateTransform} The transformation that would currently be used to fit a picture @code{pic} to a frame is returned by the member function @code{pic.calculateTransform()}. In certain cases (e.g.@ 2D graphs) where only an approximate size estimate for @code{pic} is available, the picture fitting routine +@cindex @code{picture.scale} @verbatim frame pic.scale(real xsize=this.xsize, real ysize=this.ysize, bool keepAspect=this.keepAspect); @@ -3603,6 +3672,7 @@ frame bbox(picture pic=currentpicture, real xmargin=0, real ymargin=xmargin, pen p=currentpen, filltype filltype=NoFill); @end verbatim +@cindex @code{filltype} @anchor{filltype} Here @code{filltype} specifies one of the following fill types: @table @code @@ -3730,10 +3800,9 @@ as a single entity (@pxref{GUI}), @code{filltype} requests optional background filling or clipping, and @code{above} specifies whether to add @code{src} above or below existing objects. -There are also routines to add a picture or frame @code{src} specified -in postscript coordinates to another picture @code{dest} (or -@code{currentpicture}) about the user coordinate -@code{position}: +There are also routines to add a fixed-size picture or frame +@code{src} to another picture @code{dest} (or @code{currentpicture}) +about the user coordinate @code{position}: @anchor{add about} @cindex @code{add} @cindex picture alignment @@ -3844,7 +3913,109 @@ that can be used for importing @code{LaTeX} packages. @end table -@node Files, Variable initializers, Frames and pictures, Programming +@node Deferred drawing +@section Deferred drawing +It is sometimes desirable to have elements of a fixed absolute size, +independent of the picture scaling from user to +@code{PostScript} coordinates. +For example, normally one would want the size of a dot created with +@code{dot}, the size of the arrowheads created with @code{arrow} +(@pxref{arrows}), and labels to be drawn independent of the scaling. + +However, because of @code{Asymptote}'s automatic scaling feature (@pxref{Figure size}), +the translation between user coordinate and @code{PostScript} coordinate +is not determined until shipout time: +@verbatim +size(1cm); +dot((0,0)); +dot((1,1)); +shipout("x"); // at this point, 1 unit coordinate = 1cm +dot((2,2)); +shipout("y"); // at this point, 1 unit coordinate = 0.5cm +@end verbatim +@noindent +It is therefore necessary to defer the drawing of these elements until shipout time. + +For example, a frame can be added at a specified user coordinate of a +picture with the deferred drawing routine +@code{add(picture dest=currentpicture, frame src, pair position)}: +@verbatim +frame f; +fill(f,circle((0,0),1.5pt)); +add(f,position=(1,1),align=(0,0)); +@end verbatim + +@cindex @code{picture.add} +@cindex @code{drawer} + +A deferred drawing routine is an object of type @code{drawer}, +which is a function with signature @code{void(frame f, transform t)}. +For example, if the drawing routine +@verbatim +void d(frame f, transform t){ + fill(f,shift(3cm,0)*circle(t*(1,1),2pt)); +} +@end verbatim +@noindent +is added to @code{currentpicture} with +@verbatim +currentpicture.add(d); +@end verbatim +@noindent +a filled circle of radius 2pt will be drawn on currentpicture centered +3cm to the right of user coordinate @code{(1,1)}. The parameter @code{t} is the +affine transformation from user coordinates to @code{PostScript} coordinates. + +Even though the actual drawing is deferred, you still need to specify to the +@code{Asymptote} scaling routines that ultimately a fixed-size circle +of radius 2pt will be drawn 3cm to the right of user-coordinate (1,1), +by adding a frame about (1,1) that extends beyond (1,1) from +@code{(3cm-2pt,-2pt)+min(currentpen)} to +@code{(3cm+2pt,2pt)+max(currentpen)}, where we have even +accounted for the pen linewidth. The following example will then +produce a @acronym{PDF} file 10 cm wide: + +@cindex @code{picture.addPoint} +@verbatim +settings.outformat="pdf"; +size(10cm); +dot((0,0)); +dot((1,1),red); +add(new void(frame f, transform t) { + fill(f,shift(3cm,0)*circle(t*(1,1),2pt)); +}); +pair trueMin=(3cm-2pt,-2pt)+min(currentpen); +pair trueMax=(3cm+2pt,2pt)+max(currentpen); +currentpicture.addPoint((1,1),trueMin); +currentpicture.addPoint((1,1),trueMax); +@end verbatim +@noindent +Here we specified the minimum and maximum user and truesize (fixed) +coordinates of the drawer with the @code{picture} routine +@verbatim +void addPoint(pair user, pair truesize); +@end verbatim +@noindent +Alternatively, one can use +@verbatim +void addBox(pair userMin, pair userMax, pair trueMin=0, pair trueMax=0) { +@end verbatim +@noindent +to specify a bounding box +with bottom-left corner @code{t*(1,1)+trueMin} +and top-right corner @code{t*(1,1)+trueMax}, +where @code{t} is the transformation that transforms +from user coordinates to @code{PostScript} coordinates. + +For more details about deferred drawing, see +``Asymptote: A vector graphics language,'' John C. Bowman and Andy +Hammerlindl, TUGBOAT: The Communications of the TeX Users Group, 29:2, +288-294 (2008), + +@noindent +@url{https://www.math.ualberta.ca/~bowman/publications/asyTUG.pdf}. + +@node Files @section Files @cindex @code{file} @@ -4102,6 +4273,7 @@ rename file @code{from} to file @code{to}. Unless the @code{-globalwrite} (or @code{-nosafe}) option is enabled, this operation is restricted to the current directory. @cindex @code{convert} +@cindex @code{magick} @cindex @code{animate} The functions @verbatim @@ -4109,11 +4281,11 @@ int convert(string args="", string file="", string format=""); int animate(string args="", string file="", string format=""); @end verbatim @noindent -call the @code{ImageMagick} commands @code{convert} and @code{animate}, +call the @code{ImageMagick} commands @code{magick} and @code{animate}, respectively, with the arguments @code{args} and the file name constructed from the strings @code{file} and @code{format}. -@node Variable initializers, Structures, Files, Programming +@node Variable initializers @section Variable initializers @cindex variable initializers @cindex @code{operator init} @@ -4262,7 +4434,7 @@ That is, after the definition of a structure @code{T}, a variable of type @code{T} is initialized to a new instance (@code{new T}) by default. During the definition of the structure, however, variables of type @code{T} are initialized to @code{null} by default. This -special behaviour is to avoid infinite recursion of creating new +special behavior is to avoid infinite recursion of creating new instances in code such as @verbatim struct tree { @@ -4328,59 +4500,8 @@ 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 -@code{Person(string,string)}: -@verbatim -struct Person { - string firstname; - string lastname; - - static Person Person(string firstname, string lastname) { - Person p=new Person; - p.firstname=firstname; - p.lastname=lastname; - return p; - } -} - -Person joe=Person.Person("Joe", "Jones"); -@end verbatim - -While it is now easier than before to create a new instance, we still -have to refer to the constructor by the qualified name -@code{Person.Person}. If we add the line -@verbatim -from Person unravel Person; -@end verbatim -@noindent -immediately after the structure definition, then the constructor can be used -without qualification: @code{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. - +We can reduce the work by defining @code{operator init}: @cindex @code{operator init} -If, in the body of a structure, Asymptote encounters the definition of -a function of the form @code{void operator init(@var{args})}, it implicitly -defines a constructor function of the arguments @code{@var{args}} that -uses the @code{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 @code{Foo}): - -@example -static Foo Foo(@var{args}) @{ - Foo instance=new Foo; - instance.operator init(@var{args}); - return instance; -@} -@end example - -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 @code{Person} example can thus be implemented as: @verbatim struct Person { string firstname; @@ -4401,26 +4522,6 @@ confused with its use to define default values for variables first case, the return type of the @code{operator init} must be @code{void} while in the second, it must be the (non-@code{void}) type of the variable. -@cindex @code{cputime} -The function @code{cputime()} -returns a structure @code{cputime} with cumulative @acronym{CPU} times -broken down into the fields @code{parent.user}, @code{parent.system}, -@code{child.user}, and @code{child.system}, along with the cumulative -wall clock time in @code{parent.clock}, all measured in seconds. -For convenience, the incremental fields @code{change.user}, -@code{change.system}, and @code{change.clock} indicate the change in -the corresponding fields since the last call to @code{cputime()}. The -function -@verbatim -void write(file file=stdout, string s="", cputime c, - string format=cputimeformat, suffix suffix=none); -@end verbatim -@noindent -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''. - @cindex inheritance @cindex virtual functions Much like in C++, casting (@pxref{Casts}) provides for an elegant @@ -5228,6 +5329,58 @@ If the iteration fails after the maximum allowed number of loops @item @code{real simpson(real f(real), real a, real b, real acc=realEpsilon, real dxmax=b-a)} returns the integral of @code{f} from @code{a} to @code{b} using adaptive Simpson integration. +Internally, @code{operator init} implicitly defines a constructor function +@code{Person(string,string)} as follows, where @var{args} is +@code{string firstname, string lastname} in this case: +@example +struct Person @{ + string firstname; + string lastname; + + static Person Person(@var{args}) @{ + Person p=new Person; + p.operator init(@var{args}); + return p; + @} +@} +@end example +@noindent +which then can be used as: +@verbatim +Person joe=Person.Person("Joe", "Jones"); +@end verbatim + +The following is also implicitly generated in the enclosing scope, +after the end of the structure definition. +@verbatim +from Person unravel Person; +@end verbatim +@noindent +It allows us to use the constructor without qualification, +otherwise we would have to refer to the constructor by the qualified name +@code{Person.Person}. + +@cindex @code{cputime} +@noindent +@item @code{cputime cputime()} +returns a structure @code{cputime} with cumulative @acronym{CPU} times +broken down into the fields @code{parent.user}, @code{parent.system}, +@code{child.user}, and @code{child.system}, along with the cumulative +wall clock time in @code{parent.clock}, all measured in seconds. +For convenience, the incremental fields @code{change.user}, +@code{change.system}, and @code{change.clock} indicate the change in +the corresponding fields since the last call to @code{cputime()}. The +function +@verbatim +void write(file file=stdout, string s="", cputime c, + string format=cputimeformat, suffix suffix=none); +@end verbatim +@noindent +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''. + @end table @node Arrays, Casts, Functions, Programming @@ -6073,7 +6226,6 @@ nonalphanumeric characters, enclose it with quotation marks: @cindex @acronym{libcurl} If @code{Asymptote} is compiled with support for @code{libcurl}, the file name can even be a @acronym{URL}: -@noindent @code{import "https://raw.githubusercontent.com/vectorgraphics/asymptote/HEAD/doc/axis3.asy" as axis3;} It is an error if modules import themselves (or each other in a cycle). @@ -6175,10 +6327,9 @@ access templatedModule(T=string, S=int[], Number=real) @end verbatim @noindent Note that this is actually an @emph{access} command rather than an -@emph{import} command, so the names of types, functions, etc. would have to be -stated as e.g. @code{templatedModule_string_int_real.Wrapper_Number} rather than -just @code{Wrapper_Number} (where @code{Wrapper_Number} is a type defined in -@code{templatedModule.asy}). +@emph{import} command, so a type, function, or variable @code{A} +defined in @code{templatedModule.asy} would need to be accessed +qualified as @code{templatedModule_string_int_real.A}. Alternatively, the module could be imported via a command like @verbatim @@ -6191,12 +6342,12 @@ This command would automatically rename @code{Wrapper_Number} to @code{Wrapper_real} and would also allow the use of any @code{operator ==} overloads defined in the module. -For more information, see the examples in -@url{https://github.com/vectorgraphics/asymptote/tree/647b6c5732ec94a48f0f0b2446f02c86888fe7e7/tests/template}. +Further examples can be found in the @code{tests/template} subdirectory +of the @code{Asymptote} source directory. -Issues: Certain standard features of almost any type (such as -@code{==}, @code{new}, and the ability to call static methods on the type) may -only be available for type arguments that are builtin or defined in the @code{plain} module. +Issues: Certain expected operators (such as +@code{operator ==}) may only be available for type arguments that are +builtin or defined in module @code{plain}. @node Static, , Import, Programming @section Static @@ -6372,7 +6523,6 @@ An even better method for processing a @code{LaTeX} file with embedded @noindent after putting the contents of @url{https://raw.githubusercontent.com/vectorgraphics/asymptote/HEAD/doc/latexmkrc} -@noindent in a file @code{latexmkrc} in the same directory. The command @verbatim latexmk -pdf latexusage @@ -6386,7 +6536,6 @@ To store the figures in a separate directory named @code{asy}, one can define \def\asydir{asy} @end verbatim in @code{latexusage.tex}. -@noindent External @code{Asymptote} code can be included with @cindex @code{asyinclude} @verbatim @@ -6442,6 +6591,7 @@ Here now is @code{latexusage.tex}: @menu * plain:: Default @code{Asymptote} base file * simplex:: Linear programming: simplex method +* simplex2:: Two-variable simplex method * math:: Extend @code{Asymptote}'s math capabilities * interpolate:: Interpolation routines * geometry:: Geometry routines @@ -6500,9 +6650,15 @@ option to disable this feature. @section @code{simplex} @cindex @code{simplex} @cindex @code{deferred drawing} -This module solves the two-variable linear programming problem using the -simplex method. It is used by the module @code{plain} for automatic -sizing of pictures. +This module solves the general linear programming problem using the +simplex method. + +@node simplex2, math, plain, Base modules +@section @code{simplex2} +@cindex @code{simplex2} +@cindex @code{deferred drawing} +This module solves a special case of the two-variable linear programming +problem used by the module @code{plain} for automatic sizing of pictures. @node math, interpolate, simplex, Base modules @section @code{math} @@ -6763,13 +6919,13 @@ sharp corners of paths, as illustrated in the example file @code{@uref{https://a @node animation, embed, roundedpath, Base modules @section @code{animation} @cindex @code{animation} -@cindex @code{convert} +@cindex @code{magick} @cindex animation @cindex @code{ImageMagick} This module allows one to generate animations, as illustrated by the files @code{@uref{https://asymptote.sourceforge.io/gallery/animations/wheel.gif,,wheel}@uref{https://asymptote.sourceforge.io/gallery/animations/wheel.asy,,.asy}}, @code{@uref{https://asymptote.sourceforge.io/gallery/animations/wavepacket.gif,,wavepacket}@uref{https://asymptote.sourceforge.io/gallery/animations/wavepacket.asy,,.asy}}, and @code{@uref{https://asymptote.sourceforge.io/gallery/animations/cube.gif,,cube}@uref{https://asymptote.sourceforge.io/gallery/animations/cube.asy,,.asy}} in the @code{animations} subdirectory of the examples directory. These -animations use the @code{ImageMagick} @code{convert} program to +animations use the @code{ImageMagick} @code{magick} program to merge multiple images into a @acronym{GIF} or @acronym{MPEG} movie. @@ -6780,7 +6936,6 @@ module, generates higher-quality portable clickable @acronym{PDF} movies, with optional controls. This requires installing the module @quotation @url{http://mirror.ctan.org/macros/latex/contrib/animate/animate.sty} -@noindent @end quotation @noindent (version 2007/11/30 or later) in a new directory @code{animate} in the @@ -8043,7 +8198,7 @@ light nolight; @cindex @code{transparent} The @code{currentlight.background} (or @code{background} member of the specified @code{light}) can be used -to set the background colour for 2D (or 3D) images. The default +to set the background color for 2D (or 3D) images. The default background is white for @code{HTML} images and transparent for all other formats. One can request a completely transparent background for 3D @code{WebGL} images with @@ -8949,7 +9104,6 @@ functions in @code{graph.asy}. @cindex @code{xaxis3} @cindex @code{yaxis3} @cindex @code{zaxis3} -@noindent To draw an @math{x} axis in three dimensions, use the routine @verbatim void xaxis3(picture pic=currentpicture, Label L="", axis axis=YZZero, @@ -9194,7 +9348,7 @@ depends of the relative time. The casting of @code{path} to @code{coloredpath} allows the use of a @code{path} instead of a @code{coloredpath}; in this case the -shading behaviour is the default shading behavior for a surface. +shading behavior is the default shading behavior for a surface. An example of @code{tube} is provided in the file @code{@uref{https://asymptote.sourceforge.io/gallery/3Dwebgl/trefoilknot.html,,trefoilknot}@uref{https://asymptote.sourceforge.io/gallery/3Dwebgl/trefoilknot.asy,,.asy}}. Further examples can be found at @@ -9602,7 +9756,7 @@ settings.autoplain=true; at the beginning of the configuration file, it can contain arbitrary @code{Asymptote} code. -@cindex @code{convert} +@cindex @code{magick} @cindex @code{output} @cindex @code{format} @cindex @code{ImageMagick} @@ -9619,7 +9773,7 @@ at the beginning of the configuration file, it can contain arbitrary @cindex @code{EPS} @cindex @code{PDF} @anchor{texengines} -@anchor{convert} +@anchor{magick} The default output format is @acronym{EPS} for the (default) @code{latex} and @code{tex} tex engine and @acronym{PDF} for the @code{pdflatex}, @code{xelatex}, @code{context}, @code{luatex}, and @@ -9638,20 +9792,18 @@ which can display @acronym{SVG} output (used by the with the default setting @code{settings.dvisvgmOptions="--optimize"}. @code{Asymptote} can also produce any output format supported -by the @code{ImageMagick} @code{convert} program (version 6.3.5 or -later recommended; an @code{Invalid Parameter} error message indicates -that the @code{MSDOS} utility @code{convert} is being used instead of -the one that comes with @code{ImageMagick}). +by the @code{ImageMagick} @code{magick} program (version 7 or +later. The optional setting @code{-render n} requests an output resolution of @code{n} pixels per @code{bp}. Antialiasing is controlled by the parameter @code{antialias}, which by default specifies a sampling width of 2 pixels. -To give other options to @code{convert}, use the -@code{convertOptions} setting or call convert manually. This example +To give other options to @code{magick}, use the +@code{convertOptions} setting or call @code{magick convert} manually. This example emulates how @code{Asymptote} produces antialiased @code{tiff} output at one pixel per @code{bp}: @verbatim -asy -o - venn | convert -alpha Off -density 144x144 -geometry 50%x eps:- venn.tiff +asy -o - venn | magick convert -alpha Off -density 144x144 -geometry 50%x eps:- venn.tiff @end verbatim @cindex @code{nosafe} @@ -10006,9 +10158,9 @@ available from @url{https://sourceforge.net/projects/pstoedit/}) includes an @code{Asymptote} backend. Unlike virtually all other @code{pstoedit} backends, this driver includes native clipping, even-odd fill rule, @code{PostScript} subpath, and full image support. Here is an example: + @noindent @code{asy -V @value{Datadir}/doc/asymptote/examples/venn.asy} -@noindent @verbatim pstoedit -f asy venn.eps test.asy asy -V test @@ -10219,7 +10371,7 @@ developed the @code{Asymptote Web Application} hosted at @c LocalWords: MetaPost MetaFont Hammerlindl Healy texinfo autoload setq setf @c LocalWords: printindex setfilename settitle dircategory direntry titlepage @c LocalWords: vskip filll insertcopying ifnottex detailmenu alist augroup PQ -@c LocalWords: bool behaviour facto zxf login Debian dev filetypedetect +@c LocalWords: bool behavior facto zxf login Debian dev filetypedetect @c LocalWords: FFTW bp readline gv eps args Boehm gc evenoddoverlap png joe @c LocalWords: boolean initializer expi dir xpart ypart STL substring rfind @c LocalWords: pos substr strftime typedef pxref unitcircle yscale Bezier iff |