For version 0.7.0.
To top.  Up: ..Shapes

..Shapes..Graphics

Nested namespaces
PDF Tag
Core bindings
NO_ARROW TeX clip clipodd fill fillodd fillstroke import import_raster newGroup null pointpicture spot @spot stroke
Summary of extensions
..Shapes..Graphics / arrowheads
triangleArrow
..Shapes..Graphics / metapostarrow
MetaPostArrow
..Shapes..Graphics / shapesarrow
ShapesArrow
A graphical object in Shapes is basically something thay can be drawn on a 2d canvas. Many of these objects get created by first working out their geometry using things in ..Shapes..Geometry, and then stroking or filling to get the graphics.
Sections:    Elementary 2d    Empty and pointlike graphics    Clipping    Painting paths    Externally created content

Elementary 2d

null
Type:§Drawable
An empty 2d graphics value. Useful in folds, for instance.
See also:..Shapes..Graphics3D..null
newGroup
This is a hot value.
Spawns:§•Group

Empty and pointlike graphics

pointpicture
Type:§Drawable
An invisible 2d graphics value with a point-like bounding box at the origin.
spot
::§Coords → §Drawable
Dynamic references:none
Paints a round spot at the given coordinates. The width and color of the spot is as if the spot was a stroke, see stroke.
Note that spots can also be made by stroking a closed singelton path with a round cap style. That is, 
[spot pt]
is equivalent to 
@cap:CAP_ROUND | [stroke emptypath--pt--cycle]
Also note that using spot is much more efficient than using fill on a circular path.
Rather than making the origin the default value for the argument, the dynamic variable @spot is provided to make the dynamic nature of the expression more obvious compared to [spot].
Some pdf viewers fail to do the obvious thing when a singleton path is painted with a stroke, and if you are targeting such viewers you could either change the implementation of spot using the command line option --spot-pair=yes, or use stroke on a path between two points at the same location instead of using spot, like so: 
@cap:CAP_ROUND | [stroke pt--(+(0m,0m))]
See also:@spot
@spot
Used by:
Type:§Drawable
Default binding:dynamic [spot (0m,0m)]
Constraint:Cannot be changed!
A function call with fixed arguments (or no arguments at all) is like a dynamic variable, and then a dynamic variable is generally preferred over the function call since using a dynamic variable emphasizes the dynamic nature of the expression. Since the need for a spot at the origin (which can then be transformed to any desired position) is so frequent, this dynamic variable is simply an alternative to calling spot with the origin as argument.
The value of this dynamic variable will depend on other dynamic variables, compare spot.

Clipping

clip
obj::§Drawable mask::( §Path ∪ §Text ∪ §SoftMask ) → §Drawable
Dynamic references:none
Clips obj according to mask.
When mask is a §Path, the nonzero winding rule is used.
When mask is a §Text, Shapes follows pdf with respect to the interpreation of the ..Shapes..Text..@rendering captured in mask. That is, the text will be painted as usual as a background to the clipped obj. Hence, if one is interested in pure clipping, the corresponding rendering mode is obtained by [textmode] (see ..Shapes..Text..textmode). Since clipping with respect to a text is assumed to be a way of painting that text, the bounding box becomes that of mask in this case, no matter what parts of this mask that acutally has any content.
If the goal is to crop obj to control the size of the end result, then ..Shapes..Layout..bboxed should be used instead.
At the moment, we refrain from including an example of clipping with a §SoftMask since the implementation of this feature seems buggy in most pdf viewers. (At least it would be good if the tool we use to generate bitmap images for this documentation was able to produce correct results before we include an example.)
Clipping with the nonzero winding rule
Angry
When clipping a path with clip, the nonzero winding rule is applied.
Source: show/hide — visit
Clipping with respect to text
Angry
Clipping with respect to a text is typically a way of painting that text. Clipping is combined with the effect of painting the text as usual, but as the topmost part of this figure shows, the none rendering mode can be used to do pure clipping.
Source: show/hide — visit
See also:..Shapes..Layout..bboxed clipodd ..Shapes..Geometry..winding
clipodd
obj::§Drawable mask::§Path → §Drawable
Dynamic references:none
Clips obj according to mask, applying the even-odd winding rule.
Clipping with the even-odd winding rule
Angry
When clipping a path with clipodd, the even-odd winding rule is applied.
Source: show/hide — visit
See also:clip ..Shapes..Geometry..winding

Painting paths

stroke
path::§Path head:NO_ARROW::§ArrowHead tail:NO_ARROW::§ArrowHead → §Drawable
Dynamic references:none
Paints the path argument by stroking it. Properties such as color (..Shapes..Traits..@stroking), width, &c are taken from the dynamic environment.
The arguments head and tail define arrowheads at the corresponding ends of the stroke. An arrowhead is defined by a function that takes the path as argument, and returns a tuple with fields picture and cut. Here, picture shall be the grahpics that is the actual arrowhead, while cut tells how much the stroke shall be shortened to not interfere with the arrowhead. Note that the arrowhead and the stroke usually overlap, but that it is not desirable that the stroke goes all the way to the point of the arrowhead.
path::§Path3D head:NO_ARROW::§ArrowHead3D tail:NO_ARROW::§ArrowHead3D → §Drawable3D
Dynamic references:none
Compare with the 2d case.
Note that defining arrow heads is much more intricate in 3d than in 2d, and generally requires knowledge of from what angle the arrowhead will later be viewed. If one is really eager to work around this “problem”, then what one is typically looking for is a way to delay the definition of the arrowhead until the viewing angle is known. The key to the solution is ..Shapes..Graphics3D..facing.
fill
path::§Path → §Drawable
Dynamic references:none
Paints the path (that shall be closed) argument by filling it using the nonzero winding rule. The fill color is taken from .
Filling with the nonzero winding rule
Angry
When filling a path with fill, the nonzero winding rule is applied. This example is a reconstruction of the corresponding example in the pdf reference.
Source: show/hide — visit
See also:..Shapes..Geometry..winding
path::§Path3D tiebreaker:0::§Length → §Drawable3D
Dynamic references:none
Paints the path (that shall be closed) argument by filling it nonzero winding rule. The fill color is taken from ..Shapes..Traits..@nonstroking.
Note that although winding rules don't really make any sense in 3d, some rule must nevertheless be applied to the path once it has been projected to 2d. Then, the nonzero winding rule is the simplest and hence most reasonable choice.
fillstroke
path::§Path head:NO_ARROW::§ArrowHead tail:NO_ARROW::§ArrowHead → §Drawable
Dynamic references:none
A combination of fill followed by stroke.
path::§Path3D head:NO_ARROW::§ArrowHead3D tail:NO_ARROW::§ArrowHead3D → §Drawable3D
Dynamic references:none
A combination of fill followed by stroke.
fillodd
::§Path → §Drawable
Dynamic references:none
Paints the path (that shall be closed) argument by filling it with the color ..Shapes..Traits..@nonstroking, using the even-odd rule.
Filling with the even-odd rule
Angry
When filling a path with fillodd, the even-odd rule is applied. This example is a reconstruction of the corresponding example in the pdf reference.
Source: show/hide — visit
See also:..Shapes..Geometry..winding
NO_ARROW
Type:§ArrowHead
Value that can be passed to stroke to indicate that no arrowhead shall be drawn. This special value will be recognized, and handled efficiently.

Externally created content

TeX
::§String → §Drawable
Dynamic references:none
Sends the string to and returns the resulting piece of typeset text.
The origin of the produced label is the same as in LaTeX; at the leftmost point of the baseline. Unfortunately, fonts lie about their bounding boxes to make them look smaller, and this will cause the produced label to be slightly cropped when imported. At the moment, I can't think of a good way to get around this problem, since a tight bounding box is important for layout purposes. By controlling the size of the bleed box using ..Shapes..Layout..@TeX_bleed, you can at least try to avoid the problem of the final result getting cropped too tight.
If the expression is a string literal, it is handled more efficiently than if the string must be obtained by evaluation.
import
::§String → ( ::§Integer → §Drawable )
Dynamic references:none
The given string should name a pdf file, and the pages of the file will be returned as a vector-function, mapping 0 to the first page in the document, 1 to the second page, and so forth.
Vector functions have a field called size which will give the page count in the document.
import_raster
filename::§String resolution:1 bp::§Length override:true::§Boolean kind:void::§Symbol → §RasterImage
Dynamic references:none
The argument filename should name file with raster image data. If kind is void, the file type is inferred from the filename extension. Currently, the only supported formats are png and jpeg, which may be selected using the symbols 'PNG or 'JPEG.
The length resolution is the size of each pixel, both horizontally and vertically, unless override is false and the imported file specifies the resolution instead. If override is false, but a jpeg file only specifies the aspect ratio of the pixels, the resolution will be computed such that the area of each pixel equals the area of a square pixel with side resolution.
The origin is at the lower left corner of the image. The physical dimensions of the image will be the product of the density and the number of pixels in the corresponding dimensions of the image.
Get Shapes at SourceForge.net. Fast, secure and Free Open Source software downloads