Next: Transforms, Previous: Guides and paths, Up: Programming
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)
. A number of named rgb colors are defined near
the top of the default base file plain.asy
:
black,gray,white,red,green,blue,yellow,magenta,cyan,brown,darkgreen, darkblue,orange,purple,chartreuse,fuchsia,salmon,lightblue,lavender,pink,
along with the primitive cmyk colors:
Cyan,Magenta,Yellow,Black.
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.
pen linetype(string s, bool scale=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 (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)
.
For convenience, in plain.asy
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 baselineskip=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.
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)
.
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 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"));
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.