diff options
Diffstat (limited to 'Build/source/utils/asymptote/doc/asymptote.texi')
-rw-r--r-- | Build/source/utils/asymptote/doc/asymptote.texi | 235 |
1 files changed, 173 insertions, 62 deletions
diff --git a/Build/source/utils/asymptote/doc/asymptote.texi b/Build/source/utils/asymptote/doc/asymptote.texi index b803c7cfc33..aca2cd69b35 100644 --- a/Build/source/utils/asymptote/doc/asymptote.texi +++ b/Build/source/utils/asymptote/doc/asymptote.texi @@ -84,7 +84,7 @@ Installation Tutorial * Drawing in batch mode:: Run @code{Asymptote} on a text file -* Drawing in interactive mode:: Running @code{Asymptote} interactively +* Drawing in interactive mode:: Running @code{Asymptote} interactively * Figure size:: Specifying the figure size * Labels:: Adding @code{LaTeX} labels * Paths:: Drawing lines and curves @@ -221,6 +221,9 @@ as @TeX{}/@code{LaTeX} is the de-facto standard for typesetting equations. @item @code{LaTeX} typesetting of labels, for overall document consistency; +@item the ability to generate and embed 3D vector @acronym{WebGL} +graphics within @acronym{HTML} files; + @item the ability to generate and embed 3D vector @acronym{PRC} graphics within @acronym{PDF} files; @@ -254,7 +257,7 @@ Many of the features of @code{Asymptote} are written in the @code{Asymptote} language itself. While the stock version of @code{Asymptote} is designed for mathematics typesetting needs, one can write @code{Asymptote} modules that tailor it to specific -applications. A scientific graphing module has already been written +applications; for example, a scientific graphing module is available (@pxref{graph}). Examples of @code{Asymptote} code and output, including animations, are available at @quotation @@ -382,7 +385,7 @@ The @code{ImageMagick} package from @url{http://www.imagemagick.org/script/binary-releases.php} @noindent -is required to support output formats other than @acronym{EPS}, +is required to support output formats other than @acronym{HTML}, @acronym{PDF}, @acronym{SVG}, and @acronym{PNG} (@pxref{convert}). The @code{Python 3} interpreter from @url{http://www.python.org} is only required if you wish to try out the graphical user interface (@pxref{GUI}). @@ -396,15 +399,11 @@ subdirectory of the installation directory (by default, @section Configuring @cindex configuring @cindex @code{-V} -@cindex @code{psviewer} -@cindex @code{pdfviewer} -@cindex @code{gs} In interactive mode, or when given the @code{-V} option (the default when running @code{Asymptote} on a single file under @code{MSDOS}), @code{Asymptote} will automatically invoke the @code{PostScript} viewer @code{gv} (under @code{UNIX}) or @code{gsview} (under -@code{MSDOS} to display graphical output. These defaults may be -overridden with the configuration variable @code{psviewer}. +@code{MSDOS} to display graphical output. The @code{PostScript} viewer should be capable of automatically redrawing whenever the output file is updated. The default @code{UNIX} @code{PostScript} viewer @code{gv} supports this (via a @code{SIGHUP} @@ -418,40 +417,58 @@ Users of @code{gsview} will need to enable @code{Options/Auto Redisplay} @code{gsview} window; under @code{UNIX} one must manually redisplay by pressing the @code{r} key). +@cindex @code{psviewer} +@cindex @code{pdfviewer} +@cindex @code{htmlviewer} +@cindex @code{gs} +@cindex @code{display} +@cindex @code{animate} @cindex @code{settings} @cindex configuration file Configuration variables are most easily set as @code{Asymptote} variables in an optional configuration file @code{config.asy} @pxref{configuration file}). -Here are the default values of several important configuration -variables under @code{UNIX}: +For example, the setting @code{pdfviewer} specifies the location of +the @acronym{PDF} viewer. Here are the default values of several +important configuration variables under @code{UNIX}: @noindent @verbatim import settings; -psviewer="gv"; pdfviewer="acroread"; +htmlviewer="google-chrome"; +psviewer="gv"; +display="display"; +animate="animate"; gs="gs"; +libgs=""; @end verbatim @noindent @cindex @code{cmd} -Under @code{MSDOS}, the (installation-dependent) default values of -these configuration variables are determined automatically from the -@code{Microsoft Windows} registry. Viewer settings (such as -@code{psviewer} and @code{pdfviewer}) can be set to the string -@code{cmd} to request the application normally associated with the -corresponding file type. - -For @acronym{PDF} format output, the @code{gs} setting specifies the -location of the @code{PostScript}-to-@acronym{PDF} processor @code{Ghostscript}, -available from @url{http://downloads.ghostscript.com/public}. - -The setting @code{pdfviewer} specifies the location of the @acronym{PDF} -viewer. On @code{UNIX} systems, to support automatic document -reloading in @code{Adobe Reader}, we recommend copying the file -@code{reload.js} from the @code{Asymptote} system directory (by default, -@code{@value{Datadir}/asymptote} under @code{UNIX} to +Under @code{MSDOS}, the viewer settings +@code{htmlviewer}, @code{pdfviewer}, @code{psviewer}, +@code{display}, and @code{animate} default to the string @code{cmd}, +requesting the application normally associated with each file type. +The (installation-dependent) default values of @code{gs} +and @code{libgs} are determined automatically from the @code{Microsoft +Windows} registry. The @code{gs} setting specifies the location of the +@code{PostScript} processor @code{Ghostscript}, available from +@url{https://www.ghostscript.com/}. + +@noindent +@cindex @code{htmlviewer} +The configuration variable @code{htmlviewer} specifies the +browser to use to display 3D @code{WebGL} output. +The default setting is @code{google-chrome} under @code{UNIX} and +@code{cmd} under @code{Microsoft Windows}. Note that @code{Internet Explorer} +does not support @code{WebGL}; @code{Microsoft Windows} users should set their +default html browser to @code{chrome} or @code{microsoft-edge}. + +On @code{UNIX} systems, to support automatic document +reloading of @code{PDF} files in @code{Adobe Reader}, we recommend +copying the file @code{reload.js} from the @code{Asymptote} system +directory (by default, @code{@value{Datadir}/asymptote} under @code{UNIX} to @code{~/.adobe/Acrobat/x.x/JavaScripts/}, where @code{x.x} represents the appropriate @code{Adobe Reader} version number. The automatic document reload feature must then be @@ -485,22 +502,17 @@ configuration variables @code{paperwidth} and @code{paperheight}. @cindex @code{texcommand} @cindex @code{dvips} @cindex @code{dvisvgm} -@cindex @code{libgs} @cindex @code{convert} -@cindex @code{display} -@cindex @code{animate} @cindex @code{ImageMagick} -The following configuration variables normally do not require adjustment: +@cindex @code{asygl} +These additional configuration variables normally do not require adjustment: @verbatim config texpath texcommand dvips dvisvgm -libgs convert -display -animate @end verbatim @noindent @@ -777,7 +789,7 @@ make uninstall @menu * Drawing in batch mode:: Run @code{Asymptote} on a text file -* Drawing in interactive mode:: Running @code{Asymptote} interactively +* Drawing in interactive mode:: Running @code{Asymptote} interactively * Figure size:: Specifying the figure size * Labels:: Adding @code{LaTeX} labels * Paths:: Drawing lines and curves @@ -4384,7 +4396,7 @@ type of the result: addition @cindex @code{-} @item - -subtractiona +subtraction @cindex @code{*} @item * multiplication @@ -5585,7 +5597,7 @@ real[] A=fin; Another useful mode is comma-separated-value mode, @code{file csv(bool b=true)}, which causes reads to respect comma delimiters: @verbatim -file fin=csv(input("test.txt")); +file fin=input("test.txt").csv(); real[] A=fin; @end verbatim @@ -5594,7 +5606,7 @@ To restrict the number of values read, use the @code{file dimension(int)} function: @verbatim file fin=input("test.txt"); -real[] A=dimension(fin,10); +real[] A=fin.dimension(10); @end verbatim This reads 10 values into A, unless end-of-file (or end-of-line in line mode) @@ -7786,17 +7798,70 @@ for drawing optional mesh lines for each Bezier patch. The optional @code{name} parameter is used as a prefix for naming the surface patches in the @acronym{PRC} model tree. Here material is a structure defined in @code{three_light.asy}: +@cindex @code{material} +@cindex @code{diffusepen} +@cindex @code{emissivepen} +@cindex @code{specularpen} +@cindex @code{opacity} +@cindex @code{shininess} +@cindex @code{metallic} +@cindex @code{freshnel0} @verbatim struct material { pen[] p; // diffusepen,emissivepen,specularpen real opacity; real shininess; -... + real metallic; + real fresnel0; } @end verbatim @noindent -These material properties are used to implement @code{OpenGL}-style lighting, -based on the Phong-Blinn specular model. Sample Bezier surfaces are +@cindex @code{PBR} +@cindex @code{physically based rendering} +These material properties are used to implement physically based +rendering (PBR) using light properties defined in @code{plain_prethree.asy} +and @code{three_light.asy}: +@cindex @code{light} +@cindex @code{diffuse} +@cindex @code{specular} +@cindex @code{background} +@cindex @code{specularfactor} +@cindex @code{position} +@cindex @code{currentlight} +@cindex @code{Viewport} +@cindex @code{White} +@cindex @code{Headlamp} +@cindex @code{nolight} +@verbatim +struct light { + real[][] diffuse; + real[][] specular; + pen background=nullpen; // Background color of the 3D canvas. + real specularfactor; + triple[] position; // Only directional lights are currently implemented. +} + +light Viewport=light(specularfactor=3,(0.25,-0.25,1)); + +light White=light(new pen[] {rgb(0.38,0.38,0.45),rgb(0.6,0.6,0.67), + rgb(0.5,0.5,0.57)},specularfactor=3, + new triple[] {(-2,-1.5,-0.5),(2,1.1,-2.5),(-0.5,0,2)}); + +light Headlamp=light(gray(0.8),specular=gray(0.7), + specularfactor=3,dir(42,48)); + +currentlight=Headlamp; + +light nolight; +@end verbatim +@cindex @code{background} +@cindex @code{transparent} +The @code{background} pen can be use to set the 3D @code{OpenGL} +background colour (the default is white). In the case of +3D @code{WebGL} images one can request a completely transparent background with +@code{currentlight.background=black+opacity(0.0);} + +Sample Bezier surfaces are contained in the example files @code{@uref{http://asymptote.sourceforge.net/gallery/BezierSurface.pdf,,BezierSurface}@uref{http://asymptote.sourceforge.net/gallery/BezierSurface.asy,,.asy}}, @code{@uref{http://asymptote.sourceforge.net/gallery/teapot.pdf,,teapot}@uref{http://asymptote.sourceforge.net/gallery/teapot.asy,,.asy}}, and @code{@uref{http://asymptote.sourceforge.net/gallery/parametricsurface.pdf,,parametricsurface}@uref{http://asymptote.sourceforge.net/gallery/parametricsurface.asy,,.asy}}. The structure @code{render} contains specialized rendering options documented at the beginning of module @@ -7863,14 +7928,16 @@ normals or vertex colors: @cindex @code{tessellation} @verbatim void draw(picture pic=currentpicture, triple[] v, int[][] vi, - triple[] n={}, int[][] ni={}, material m=currentpen, pen[] p={}, - int[][] pi={}, light light=currentlight); + triple[] n={}, int[][] ni=vi, material m=currentpen, pen[] p={}, + int[][] pi=vi, light light=currentlight); @end verbatim -Here, the triple array @code{v} lists the distinct vertices, while -the array @code{vi} lists integer arrays of length 3 containing -the indices of @code{v} corresponding to the vertices of each +Here, the triple array @code{v} lists the (typically distinct) vertices, while +the array @code{vi} contains integer arrays of length 3 containing +the indices of the elements in @code{v} that form the vertices of each triangle. Similarly, the arguments @code{n} and @code{ni} contain -optional normal data and @code{p} and @code{pi} contain optional pen vertex data. +optional normal data and @code{p} and @code{pi} contain optional pen +vertex data. If more than one normal or pen is specified for a vertex, the +last one specified is used. An example of this tessellation facility is given in @code{@uref{http://asymptote.sourceforge.net/gallery/triangles.pdf,,triangles}@uref{http://asymptote.sourceforge.net/gallery/triangles.asy,,.asy}}. @cindex @code{thin} @@ -7897,18 +7964,17 @@ parameter or the setting @code{thin} is set to @code{false}. The pens also be used to override these defaults for specific draw commands. @noindent -There are four choices for viewing 3D @code{Asymptote} output: +There are five choices for viewing 3D @code{Asymptote} output: @enumerate + @cindex @code{OpenGL} @cindex @code{render} @cindex @code{outformat} @cindex @code{multisample} @item Use the native @code{Asymptote} adaptive @code{OpenGL}-based renderer (with the command-line option @code{-V} and the default settings -@code{outformat=""} and @code{render=-1}). If you encounter warnings -from your graphics card driver, try specifying @code{-glOptions=-indirect} -on the command line. On @code{UNIX} systems with graphics support for -multisampling, the sample width can be +@code{outformat=""} and @code{render=-1}). On @code{UNIX} systems with +graphics support for multisampling, the sample width can be controlled with the setting @code{multisample}. An initial screen position can be specified with the pair setting @code{position}, where negative values are interpreted as relative to the corresponding @@ -7945,7 +8011,7 @@ The keyboard shortcuts are: @item y: spin about the Y axis @item z: spin about the Z axis @item s: stop spinning -@item m: rendering mode (solid/mesh/patch) +@item m: rendering mode (solid/patch/mesh) @item e: export @item c: show camera parameters @item p: play animation @@ -7961,6 +8027,40 @@ The keyboard shortcuts are: @item Ctrl-q: exit @end itemize +@cindex @code{WebGL} +@cindex @code{HTML5} +@cindex @code{mobile browser} +@item Generate @code{WebGL} interactive vector graphics +output with the the command-line option and @code{-f html} +(or the setting @code{outformat="html"}). The resulting +3D @acronym{HTML} file can then be viewed directly in any modern desktop or +mobile browser, or even embedded within another web page: +@verbatim +<div> +<object data="logo3.html" + style="width:210;height:140;position:relative;top:0;left:0;"> +</object> +</div> +@end verbatim + +Normally, @code{WebGL} files generated by @code{Asymptote} are +dynamically remeshed to fit the browser window dimensions. +However, the setting @code{absolute=true} can be used to force the image to be +rendered at its designed size (accounting for multiple device pixels +per @code{css} pixel). This setting should not be used when +embedding a @code{WebGL} file within another @acronym{HTML} document. + +The interactive @code{WebGL} files produced by @code{Asymptote} use the +default mouse and (many of the same) key bindings as the @code{OpenGL} +renderer. + +By default, viewing the 3D @acronym{HTML} files generated by Asymptote requires +network access to download the @code{asygl} rendering library, which +is normally cached by the browser for future use. +However, the setting @code{offline=true} can be used to embed this +small (about 42kB) library within a stand-alone @acronym{HTML} file +that can be viewed offline. + @cindex @code{antialias} @cindex @code{maxviewport} @cindex @code{maxtile} @@ -7985,8 +8085,6 @@ setting @code{maxviewport}, which restricts the maximum width and height of the viewport. On @code{UNIX} systems some graphics drivers support batch mode (@code{-noV}) rendering in an iconified window; this can be enabled with the setting @code{iconify=true}. -Some (broken) @code{UNIX} graphics drivers may require the command line setting -@code{-glOptions=-indirect}, which requests (slower) indirect rendering. @cindex @code{prc} @cindex @code{views} @@ -8033,7 +8131,7 @@ void size3(picture pic=currentpicture, real x, real y=x, real z=y, @cindex margins @cindex @code{viewportmargin} @cindex @code{viewportsize} -The resulting simplex linear programming problem is then solved to +A 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 @@ -9227,6 +9325,7 @@ variables may also be changed at runtime. @cindex @code{hyperrefOptions} @cindex @code{convertOptions} @cindex @code{gsOptions} +@cindex @code{htmlviewerOptions} @cindex @code{psviewerOptions} @cindex @code{pdfviewerOptions} @cindex @code{pdfreloadOptions} @@ -9234,7 +9333,8 @@ variables may also be changed at runtime. @cindex @code{dvisvgmOptions} The advanced configuration variables @code{dvipsOptions}, @code{hyperrefOptions}, @code{convertOptions}, @code{gsOptions}, -@code{psviewerOptions}, @code{pdfviewerOptions}, @code{pdfreloadOptions}, +@code{htmlviewerOptions}, @code{psviewerOptions}, +@code{pdfviewerOptions}, @code{pdfreloadOptions}, @code{glOptions}, and @code{dvisvgmOptions} allow specialized options to be passed as a string to the respective applications or libraries. The default value of @code{hyperrefOptions} is @@ -9277,7 +9377,7 @@ produced using the @code{-f} option (or @code{outformat} setting). @cindex @code{dvisvgm} @cindex @code{libgs} To produce @acronym{SVG} output, you will need @code{dvisvgm} (version -1.5.3 or later) from @url{http://dvisvgm.sourceforge.net} and must use +2.6.3 or later) from @url{http://dvisvgm.sourceforge.net} and must use the @code{latex} or @code{tex} tex engine. You might need to adjust the configuration variable @code{libgs} to point to the location of your @code{Ghostscript} library @code{libgs.so} (or to an empty @@ -9510,7 +9610,7 @@ pip3 install cson numpy pyqt5 PyQt5.sip @end verbatim Pictures are deconstructed into the @acronym{SVG} image format. -Since @code{Qt5} does not suport @code{SVG} clipping, you will need +Since @code{Qt5} does not support @code{SVG} clipping, you will need the @code{rsvg-convert} utility, which is part of the @code{librsvg2-tools} package on @code{UNIX} systems and the @code{librsvg} package on @code{MacOS}; under @@ -9871,7 +9971,7 @@ Martin Wiebusch, Stefan Knorr, and Supakorn ``Jamie'' Rassameemasmuang. @c LocalWords: nonoverlapping texengine maxtimes maxheight pdb TEXMFCONFIG Jn @c LocalWords: piecewisestraight unitrand graphmarkers antialias nolight newl @c LocalWords: Delaunay Shewchuk convertOptions APPDATA pdfreload tempFile Yn -@c LocalWords: pdfreloadOptions deferred OpenGL Phong Blinn renderer unitbox +@c LocalWords: pdfreloadOptions deferred OpenGL renderer unitbox @c LocalWords: bezulate Shardt's rasterized viewport unitdisk unitplane devel @c LocalWords: unitcylinder unitcone solidcone unitfrustum unitsphere nslices @c LocalWords: DPostScript YZZero externalprc nonrendered nosafe KDE @@ -9945,10 +10045,21 @@ Martin Wiebusch, Stefan Knorr, and Supakorn ``Jamie'' Rassameemasmuang. @c LocalWords: 5unit 144x144 aligndir smoothcontour3 's 3D 2D cmake @c LocalWords: 'load 'asy 'lasy 'auto 5bp 1cm 4g 2S 100pt 3t nan 3x @c LocalWords: 12pt 5mm 25cm 5x 3y 602e 2x 2y 3sin 10cm 204e 10x Ai -@c LocalWords: Ai Ai Ai Ai Ai Ai Ai 5E 5cm 2N 2E 2n 100d 5z 5y nz +@c LocalWords: Ai Ai Ai Ai Ai Ai Ai 5E 5cm 2N 2E 2n 100d 5z 5y nz ' @c LocalWords: 5unit Staats implicitsurface overlapedges maxdepth @c LocalWords: through'' genustwo 144x144 0pt 1filll 's 3D 2D 'load @c LocalWords: 'asy 'lasy 'auto 5bp 1cm 4g 2S 100pt 3t 12pt 5mm 3x @c LocalWords: 25cm 5x 3y 602e 2x 2y 3sin 10cm 204e 10x Ai Ai Ai Ai @c LocalWords: Ai Ai Ai Ai 5E 5cm 2N 2E 2n 100d 5z 5y 5unit 144x144 -@c LocalWords: Frohlich +@c LocalWords: Frohlich codequoteundirected center 0pt 1filll 's 3D +@c LocalWords: acknowledgments Colors 2D Color WebGL uref x86 dnf +@c LocalWords: htmlviewer asygl CPPFLAGS 'load 'asy 'lasy 'auto 5bp +@c LocalWords: 1cm labeling dotfilltype 4g color colors centered 2S +@c LocalWords: 100pt 3t forcemath gray colorless miter 12pt 5mm 3x +@c LocalWords: zeroTransform 25cm Python3 popcount bitreverse 5x 3y +@c LocalWords: 602e 2x 2y 3sin 10cm 204e 10x Ai Ai Ai Ai Ai Ai Ai +@c LocalWords: Ai findall ax 5a centers 5E 5cm 2N 2E 2n HTML5 html +@c LocalWords: logo3 remeshed css 42kB 100d 5z 5y 5unit colored Qt5 +@c LocalWords: behavior beveled usetriangles htmlviewerOptions cson +@c LocalWords: 144x144 pyqt5 numpy pip3 PyQt5 rsvg librsvg2 +@c LocalWords: librsvg Supakorn Jamie'' Rassameemasmuang |