asymptote: label
4.4 label
=========
void label(picture pic=currentpicture, Label L, pair position,
align align=NoAlign, pen p=currentpen, filltype filltype=NoFill)
Draw Label 'L' on picture 'pic' using pen 'p'. If 'align' is
'NoAlign', the label will be centered at user coordinate 'position';
otherwise it will be aligned in the direction of 'align' and displaced
from 'position' by the 'PostScript' offset 'align*labelmargin(p)'. The
constant 'Align' can be used to align the bottom-left corner of the
label at 'position'. The Label 'L' can either be a string or the
structure obtained by calling one of the functions
Label Label(string s="", pair position, align align=NoAlign,
pen p=nullpen, embed embed=Rotate, filltype filltype=NoFill);
Label Label(string s="", align align=NoAlign,
pen p=nullpen, embed embed=Rotate, filltype filltype=NoFill);
Label Label(Label L, pair position, align align=NoAlign,
pen p=nullpen, embed embed=L.embed, filltype filltype=NoFill);
Label Label(Label L, align align=NoAlign,
pen p=nullpen, embed embed=L.embed, filltype filltype=NoFill);
The text of a Label can be scaled, slanted, rotated, or shifted by
multiplying it on the left by an affine transform (
Transforms).
For example, 'rotate(45)*xscale(2)*L' first scales 'L' in the x
direction and then rotates it counterclockwise by 45 degrees. The final
position of a Label can also be shifted by a 'PostScript' coordinate
translation: 'shift(10,0)*L'. An explicit pen specified within the
Label overrides other pen arguments. The 'embed' argument determines
how the Label should transform with the embedding picture:
'Shift'
only shift with embedding picture;
'Rotate'
only shift and rotate with embedding picture (default);
'Rotate(pair z)'
rotate with (picture-transformed) vector 'z'.
'Slant'
only shift, rotate, slant, and reflect with embedding picture;
'Scale'
shift, rotate, slant, reflect, and scale with embedding picture.
To add a label to a path, use
void label(picture pic=currentpicture, Label L, path g, align align=NoAlign,
pen p=currentpen, filltype filltype=NoFill);
By default the label will be positioned at the midpoint of the path.
An alternative label position (in the sense of 'point(path p, real t)')
may be specified as a real value for 'position' in constructing the
Label. The position 'Relative(real)' specifies a location relative to
the total arclength of the path. These convenient abbreviations are
predefined:
position BeginPoint=Relative(0);
position MidPoint=Relative(0.5);
position EndPoint=Relative(1);
Path labels are aligned in the direction 'align', which may be
specified as an absolute compass direction (pair) or a direction
'Relative(pair)' measured relative to a north axis in the local
direction of the path. For convenience 'LeftSide', 'Center', and
'RightSide' are defined as 'Relative(W)', 'Relative((0,0))', and
'Relative(E)', respectively. Multiplying 'LeftSide' and 'RightSide' on
the left by a real scaling factor will move the label further away from
or closer to the path.
A label with a fixed-size arrow of length 'arrowlength' pointing to
'b' from direction 'dir' can be produced with the routine
void arrow(picture pic=currentpicture, Label L="", pair b, pair dir,
real length=arrowlength, align align=NoAlign,
pen p=currentpen, arrowbar arrow=Arrow, margin margin=EndMargin);
If no alignment is specified (either in the Label or as an explicit
argument), the optional Label will be aligned in the direction 'dir',
using margin 'margin'.
The function 'string graphic(string name, string options="")' returns
a string that can be used to include an encapsulated 'PostScript' (EPS)
file. Here, 'name' is the name of the file to include and 'options' is
a string containing a comma-separated list of optional bounding box
('bb=llx lly urx ury'), width ('width=value'), height ('height=value'),
rotation ('angle=value'), scaling ('scale=factor'), clipping
('clip=bool'), and draft mode ('draft=bool') parameters. The 'layer()'
function can be used to force future objects to be drawn on top of the
included image:
label(graphic("file.eps","width=1cm"),(0,0),NE);
layer();
The 'string baseline(string s, string template="\strut")' function
can be used to enlarge the bounding box of labels to match a given
template, so that their baselines will be typeset on a horizontal line.
See 'Pythagoras.asy' for an example.
One can prevent labels from overwriting one another with the
'overwrite' pen attribute (overwrite).
The structure 'object' defined in 'plain_Label.asy' allows Labels and
frames to be treated in a uniform manner. A group of objects may be
packed together into single frame with the routine
frame pack(pair align=2S ... object inset[]);
To draw or fill a box (or ellipse or other path) around a Label and
return the bounding object, use one of the routines
object draw(picture pic=currentpicture, Label L, envelope e,
real xmargin=0, real ymargin=xmargin, pen p=currentpen,
filltype filltype=NoFill, bool above=true);
object draw(picture pic=currentpicture, Label L, envelope e, pair position,
real xmargin=0, real ymargin=xmargin, pen p=currentpen,
filltype filltype=NoFill, bool above=true);
Here 'envelope' is a boundary-drawing routine such as 'box', 'roundbox',
or 'ellipse' defined in 'plain_boxes.asy' (envelope).
The function 'path[] texpath(Label L)' returns the path array that
TeX would fill to draw the Label 'L'.
The 'string minipage(string s, width=100pt)' function can be used to
format string 's' into a paragraph of width 'width'. This example uses
'minipage', 'clip', and 'graphic' to produce a CD label:
[CDlabel]
size(11.7cm,11.7cm);
asy(nativeformat(),"logo");
fill(unitcircle^^(scale(2/11.7)*unitcircle),
evenodd+rgb(124/255,205/255,124/255));
label(scale(1.1)*minipage(
"\centering\scriptsize \textbf{\LARGE {\tt Asymptote}\\
\smallskip
\small The Vector Graphics Language}\\
\smallskip
\textsc{Andy Hammerlindl, John Bowman, and Tom Prince}
http://asymptote.sourceforge.net\\
",8cm),(0,0.6));
label(graphic("logo."+nativeformat(),"height=7cm"),(0,-0.22));
clip(unitcircle^^(scale(2/11.7)*unitcircle),evenodd);
Info Catalog
asymptote: clip
asymptote: Drawing commands