In Asymptote
, pens provide a context for the four basic drawing
commands (see 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
.
Pens may be added together with the binary operator +
.
This will mix 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.
pen gray(real g)
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)
r
, g
, b
, lies in the interval [0,1].
pen cmyk(real c, real m, real y, real k)
c
, m
, y
, k
,
lies in the interval [0,1].
pen invisible();
\phantom
command in TeX).
The default color is black
; this may be changed with the routine
defaultpen(pen)
.
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.
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.
pen linetype(string s, bool scale=true, bool adjust=true)
,
where s
is a string of integer or real numbers separated by spaces.
The first number specifies how far (if scale
is true
, in
units of the pen linewidth; 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(""); pen dotted=linetype("0 4"); pen dashed=linetype("8 8"); pen longdashed=linetype("24 8"); pen dashdotted=linetype("8 8 0 8"); pen longdashdotted=linetype("24 8 0 8");
The default linetype is solid
; this may be changed with
defaultpen(pen)
.
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
we define
static void defaultpen(real w) {defaultpen(linewidth(w));} static pen operator +(pen p, real w) {return p+linewidth(w);} static pen operator +(real w, pen p) {return linewidth(w)+p;}so that one may set the linewidth like this:
defaultpen(2); pen p=red+0.5;
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)
.
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)
.
PostScript
fill rule is returned on
calling fillrule
with an integer argument:
pen zerowinding=fillrule(0); pen evenodd=fillrule(1); pen zerowindingoverlap=fillrule(2); pen evenoddoverlap=fillrule(3);
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.
A label is considered to be inside the region only if all four
corners of its (possibly rotated) bounding box are within the region.
The fill rules zerowindingoverlap
and evenoddoverlap
are respectively identical to zerowinding
and evenodd
,
except that a label is considered to be inside the region whenever
its center is within the region. While this allows labels to
extend beyond the clipping region, any actual overlap is ignored when
determining picture bounds. The default fill rule, zerowinding
, may
be changed with defaultpen(pen)
.
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.
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. 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.
LaTeX
NFSS
font is returned
by calling the function pen font(string encoding, string family,
string series="m", string shape="n")
. The default setting,
font("OT1","cmr","m","n")
, corresponds to 12pt Computer Modern Roman;
this may be changed with defaultpen(pen)
. Support for
standardized international characters is provided by the
unicode
package (see 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");
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 default
PostScript
preamble frame patterns
,
with optional left-bottom margin lb
and right-top margin rt
.
void add(frame preamble=patterns, 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 pattern.asy
. The tiled pattern can
even incorporate shading (see 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; guide 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"));
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
.
overwrite
, which takes a single argument:
Allow
defaultpen(pen)
.
Suppress
SuppressQuiet
Move
PostScript
coordinates) it could result in a larger figure than requested.
MoveQuiet
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.