alpha()

Syntax

alpha(opacity)

Description

Sets the default opacity for all subsequent drawing operations. The new opacity value becomes part of the global state and can be reset to the default by calling alpha(1.0).

While other transparency effects can be achieved by setting the stroke() or fill() color to a non-opaque value, the alpha() command affects the translucency of the object as if it were a layer in Illustrator (rather than affecting the stroke and fill independently).

Context Manager

When used as part of a with statement, alpha() treats all the drawing that occurs within the block as a single layer. As a result, overlapping objects will be flattened before the translucency is applied.

Tutorial

Example

rect(10,10, 50,50, fill='red') # at full opacity
alpha(.5)
rect(35,35, 50,50, fill='black') # half opacity
with alpha(.5): # entire layer at half opacity
    rect(10,10, 50,50, fill='red')
    rect(35,35, 50,50, fill='black')

blend()

Syntax

blend(mode)

Description

Blending operations affect how ‘old’ content on the canvas shows through new content drawn on top of it. By default the canvas uses the traditional ‘painter’s algorithm’ in which each new drawing operation obscures anything below it in proportion to its opacity.

Setting an alternate blend mode changes the rules for determining how colors combine. Different modes will use color, opacity, depth-ordering, or a combination of attributes. Call blend() with a mode-name string to set a custom blend mode.

Context Manager

When used as part of a with statement, blend() will first render the drawing within the indented block as a single layer (using the normal blend mode). The layer’s contents are then composited to the canvas using the specified mode.

Tutorial

Example

To demonstrate the different available modes, we’ll repeatedly draw the same foreground and backdrop images atop one another, changing only the blend mode. Note that the current alpha() level will also affect your results. Here’s a pair of test images drawn at full opacity.

backdrop.png foreground.png

Call blend() with one of the following strings as an argument to achieve the desired compositing effect:

image("backdrop.png")
blend("…")
image("foreground.png")
normal
copy
xor
multiply
screen
overlay
darken
lighten
difference
exclusion
color-dodge
color-burn
soft-light
hard-light
hue
saturation
color
luminosity
source-in
source-out
source-atop
plus-darker
plus-lighter
destination-over
destination-in
destination-out
destination-atop
clear

clip()

Syntax

with clip(stencil, channel="alpha"):

Description

Sets the clipping region for a block of drawing commands.

All drawing operations within the block will be constrained by a Bezier, Image, or Text object passed as the stencil argument. If clipping to a path, only content within the filled bounds of the stencil path will be rendered (strokes will be ignored). When clipping to an image, drawing operations will have high opacity in places where the mask value is also high.

The optional channel arg applies only to image-based stencils and specifies which component of the stencil’s pixels should be used for this calculation. If omitted it defaults to "alpha" (if available) or "black" level (if the image is opaque).

When an object is used as a stencil arg, it is ‘consumed’ by the operation and will not be directly visible on the canvas. As a result, it’s perfectly safe to include calls to Primitives or the image() command in the arguments list for clip().

See Also

The mask() command uses the same syntax as clip() but has an opposite effect.

Example

with clip(poly(64,64, 50, sides=5)):
    image('plaid.png')
with clip(image('logo-stencil.png')):
    image('plaid.png')
using the logo-stencil.png image
font("Avenir", "bold", 112)
with clip(text('Hi', 5, 100)):
    image('plaid.png')

mask()

Syntax

with mask(stencil, channel="alpha"):

Description

Sets an inverted clipping region for a block of drawing commands.

All drawing operations within the block will be constrained by a Bezier, Image, or Text object passed as the stencil argument. If masking to a path, only content drawn outside of the filled path will be visible. When masking to an image, drawing operations will have high opacity in places where the mask value is low.

The optional channel arg applies only to image-based stencils and specifies which component of the stencil’s pixels should be used for this calculation. If omitted it defaults to "alpha" (if available) or "black" level (if the image is opaque).

When an object is used as a stencil arg, it is ‘consumed’ by the operation and will not be directly visible on the canvas. As a result, it’s perfectly safe to include calls to Primitives or the image() command in the arguments list for mask().

See Also

The clip() command uses the same syntax as mask() but has an opposite effect.

Example

with mask(poly(64,64, 50, sides=5)):
    image('plaid.png')
with mask(image('logo-stencil.png')):
    image('plaid.png')
using the logo-stencil.png image
font("Avenir", "bold", 112)
with mask(text('Hi', 5, 100)):
    image('plaid.png')

shadow()

Syntax

shadow(color, blur=10, offset=(5,5))

Description

Sets a global drop-shadow style for drawing primitives. The color argument can be a single value, or a tuple containing valid args for the color() command. The optional blur argument controls the sharpness of the shadowed region.

The offset arg, if specified, sets the relative position of the shadow. It can be either a single number (with positive values corresponding to down/right and negative to up/left) or a 2-tuple with separate x & y offsets. If the offset is omitted, it will default to the same value as the blur.

Calling shadow() affects the global state. Any subsquent drawing operations will include a drop-shadow until you call noshadow() or shadow(None) to disable the effect.

Context Manager

When used as part of a with statement, the shadow() command’s effects will be limited to drawing commands within the block. In addition, the shadow will be applied to drawing operations as a ‘layer’ rather than to the individual graphics objects.

Tutorial

Example

# draw each rect with its own dropshadow
pen(5, fill='#08a', stroke='#eee')
shadow('#999', blur=6, offset=4)
rect(60,10, 50,50)
rect(10,10, 50,50)
rect(35,35, 50,50, fill=None)
# draw a single dropshadow for the entire layer
pen(5, fill='#08a', stroke='#eee')
with shadow('#999', blur=6, offset=4):
    rect(60,10, 50,50)
    rect(10,10, 50,50)
    rect(35,35, 50,50, fill=None)
with shadow('green'):
    poly(30,30, 15)
with shadow(('black',.5), blur=5):
    poly(90,30, 15)
with shadow('red', blur=0, offset=(5,10)):
    poly(30,90, 15)
with shadow('blue', blur=20, offset=0):
    poly(90,90, 15)

Shadow

Syntax

Shadow(color, blur=10, offset=(5,5))

Description

A drop-shadow which can be passed to the shadow() command.

Properties

s.color
s.blur
s.offset

Methods

s.copy()

beginclip()

Syntax

beginclip(path)

Description

Using the beginclip() and endclip() commands define a clipping mask. The supplied parameter defines the path to be used as a clipping mask. Each of the shape commands returns a path that can be used with beginclip() - setting the draw parameter of a shape command simply returns the path without actually drawing the shape. Any shapes, paths, texts and images between beginclip() and endclip() are clipped, this means that any part that falls outside the clipping mask path is not drawn.

Returns

a Stencil object containing the mask

PlotDevice Equivalent

The beginclip() command has been subsumed into the new clip() command. Rather than calling beginclip() and endclip() to constrain the drawable area, you can call clip() as part of a with statement.

Example

superfolia
p = oval(20, 20, 80, 80, plot=False)
beginclip(p)
image("header.jpg", -130, 0)
endclip()

endclip()

Syntax

endclip()

Description

The endclip() command is the companion to beginclip() and may only be called after the latter. When endclip() is called, subsequent shapes, paths, texts and images are no longer clipped to the path supplied to beginclip().

noshadow()

Syntax

noshadow()

Description

Clears any previously defined shadow() effects. This command is a shorthand equivalent to calling shadow(None).

Tutorial