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=""); 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=""); 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="");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; real granularity; ... }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 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 by nonselfintersecting cyclic paths
(according to the zerowinding
fill rule) into subregions
bounded by cyclic paths of length 4
or less.
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, real granularity=tubegranularity);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:
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, we recommend installing the latest SVN (antialiased)
version of the freeglut
library
(see 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:
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
beyond the screen
dimensions (indicated by maxtile=(0,0)
. 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.
8.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 (see configuration file), or specified in the script before
three.asy
(or graph3.asy
) is imported.
Version 2008/10/08 or later of the movie15
package is also
required (see 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 LaTeX usage for an easier way
to embed three-dimensional Asymptote
pictures within LaTeX
.
The open-source PRC specification is available from
http://livedocs.adobe.com/acrobat_sdk/9/Acrobat9_HTMLHelp/API_References/PRCReference/PRC_Format_Specification/.
render=0
. Only limited hidden surface
removal facilities are currently available with this approach
(see 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.
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 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)
(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)
(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)
(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)
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)
orthographic((x,y,z),up,target,zoom,viewportshift,showtarget,center)
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)
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)
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, bool group=true, filltype filltype=NoFill);adds picture
pic
as seen with FrontView
aligned above the
projection TopView
and to the right of the projection RightView
.
Alternatively, the function
void addAllViews(picture dest=currentpicture, picture src, real xmargin=0, real ymargin=xmargin, bool group=true, filltype filltype=NoFill);may be used to exhibit all six standard views, with FrontView, TopView, RightView in the upper row and BackView, BottomView, LeftView in the lower row.
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:
shift(triple v)
v
;
xscale3(real x)
x
in the x direction;
yscale3(real y)
y
in the y direction;
zscale3(real z)
z
in the z direction;
scale3(real s)
s
in the x, y, and z directions;
scale(real x, real y, real z)
x
in the x direction,
by y
in the y direction, and by z
in the z
direction;
rotate(real angle, triple v)
angle
in degrees about an axis v
through the origin;
rotate(real angle, triple u, triple v)
angle
in degrees about the axis u--v
;
reflect(triple u, triple v, triple w)
u
, v
, and w
.
Three-dimensional TeX Labels, which are by default drawn as
Bezier surfaces directly on the projection plane, can be transformed
from the XY
plane by any of the above transforms or mapped to a
specified two-dimensional plane with the 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));
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.
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 2, 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)+opacity(0.5)); xaxis3(Label(XY()*"$x$",align=-3Y),red,above=true); yaxis3(Label(XY()*"$y$",align=-3X),red,above=true); dot(z);
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
.
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);