Shape Adjustments

Forrest Oliphant edited this page Aug 19, 2018 · 6 revisions

Shape Adjustments: Geometry, Color, and Time

There are three categories of shape adjustments: geometric, color, and temporal. Anywhere that you see num there can either be a numeric constant or an expression.

Geometry Adjustments

The geometry of shapes is defined by a two dimensional affine transform which is represented internally as a matrix. z is represented by a separate one dimensional affine transform.

Adjustment                          Meaning
x x1 translation along the x-axis by x1
x x1 y1 translation along the x-axis by x1 and y-axis by y1
x x1 y1 z1 translation along the x-axis by x1, y-axis by y1, and z-axis by z1
y y1 translation along the y-axis by y1
z z1 translation along the z-axis by z1
size num
s num
scale in x and y by num
size x1 y1
s x1 y1
scale in x by x1 and in y by y1
size x1 y1 z1
s x1 y1 z1
scale in x by x1, in y by y1, and in z by z1
rotate num
r num
rotate in the x/y plane num degrees
flip num
f num
reflect in x/y plane across a line through the origin at num degrees
skew num1 num2 shear transform in x/y plane num1 degrees from the y axis and num2 degrees from the x axis
transform x1
trans x1
translate along x-axis by x1
transform x1 y1
trans x1 y1
translate along x-axis by x1 and y-axis by y1
transform x1 y1 x2 y2
trans x1 y1 x2 y2
transform from unit square at origin to a square with one corner at (x1,y1) and the adjacent corner at (x2,y2)
transform x1 y1 x2 y2 x3 y3
trans x1 y1 x2 y2 x3 y3
transform from unit square at origin to a parallelogram with one corner at (x1,y1), the adjacent corner at (x2,y2), and the opposite corner at (x3,y3)

† The z-axis position determines which shape is on top when they overlap. The z-axis position and scale are not stored in the affine transform matrix and do not affect the shape of objects.

The following diagram demonstrates 1 and 2 argument transform adjustments (translation, but no rotation, scaling, or skew), 4 argument transform adjustments (translation, rotation, and scaling, but no skew), and 6 argument transform adjustments (translation, rotation, scaling, and skew).

Transform Adjustments

Color Adjustments

Context Free uses the HSBA color space (HSB/HSV color plus alpha, or opacity). The HSBA coordinates are [0,360) for hue, [0,1] for saturation, [0,1] for brightness, and [0,1] for alpha (opacity).

Adjustment            Meaning
hue num
h num
add num to the drawing hue value, modulo 360
saturation num
sat num
range [-1,1]. If num<0 then change the drawing saturation num% toward 0. If num>0 then change the drawing saturation num% toward 1.
brightness num
b num
range [-1,1]. If num<0 then change the drawing brightness num% toward 0. If num>0 then change the drawing brightness num% toward 1.
alpha num
a num
range [-1,1]. If num<0 then change the drawing alpha num% toward 0. If num>0 then change the drawing alpha num% toward 1.
hue num1 num2 num3
h num1 num2 num3
Equivalent to hue num1 saturation num2 brightness num3
hue num1 num2 num3 num4
h num1 num2 num3 num4
Equivalent to hue num1 saturation num2 brightness num3 alpha num4

Targeting a Color

There are four more drawing color adjustments for changing the drawing color components with respect to the target color. This is useful if you have a recursive shape rule that adjusts a color component, and you don't want to overshoot a value. For example, the drawing hue is red and you want the drawing hue to trend toward yellow, but never go past yellow to green.

Adjustment            Meaning
hue num target
h num target
range [-1,1]. If num<0 then change the drawing hue num% toward the target hue moving clockwise around the color wheel. If num>0 then change the drawing hue num% toward the target hue counter-clockwise around the color wheel.
saturation num target
sat num target
range [-1,1]. If num>0 then change the drawing saturation num% toward the target saturation. If num<0 then change the drawing saturation num% toward 0 or 1, whichever is closer.
brightness num target
b num target
range [-1,1]. If num>0 then change the drawing brightness num% toward target brightness. If num<0 then change the drawing brightness num% toward 0 or 1, whichever is closer.
alpha num target
a num target
range [-1,1]. If num>0 then change the drawing alpha num% toward the target alpha. If num<0 then change the drawing alpha num% toward 0 or 1, whichever is closer.

Example: Targeting yellow

For example, the following code applied consistently when drawing shapes, will change the initial hue 0 (red) quickly to yellow (hue 60) but not let it go past yellow towards green:

MyShape [ h 0.99 60 ] // yellow hues

More on targeting colors can be found in the tutorial Targeting a color.

Some common hues

Remember that the initial hue is always 0, i.e red. Some common hues follow:

Hue number Primary Secondary Tertiary
0 Red
30 Orange
("Red-Yellow")
60 Yellow
90 Yellow-Green
120 Green
150 Aqua
("Green-Cyan")
180 Cyan
210 Turquoise
("Cyan-Blue")
240 Blue
270 Violet
("Blue-Magenta")
300 Magenta
330 Reddish Purple
("Magenta-Red")
360 (=0) Red

Time Adjustment

When rendering an animation the timeline for the animation is divided into frames and each frame is rendered into the movie (or into discrete png files). Each shape has a birth time, where it starts to be drawn; and a death time, where it stops being drawn. This is defined as a pair of one dimensional affine transforms that share the same scale element. The birth time can be -∞, which means that the shape is drawn from the start of the animation until it dies. The death time can be ∞, which means that the shape is drawn from birth until the end of the animation.

Adjustment            Meaning
time num1 num2 translate birth time by num1 and death time by num2, in current time scale
timescale num multiply current time scale by num

Basic Shape Adjustments vs. Ordered Shape Adjustments

or what is the difference between [ … ] and [[ … ]]

The simplified manner for handling geometric shape adjustments is to take each adjustment and apply it to create the final shape geometry in a fixed and easy to understand order. In this example:

shape foo {
    bar [ x 1 y 2 rot 30 s 2 0.5 skew 10 0 flip 45 ]
}

The bar shape is first translated (1, 2), then it is rotated 30 degrees, then it is scaled (2, 0.5), then it is skewed 10 degrees from the y-axis, and finally it is reflected across a 45 degree line. It doesn't matter if you shuffle the adjustments, they are still applied in this fixed order:

shape foo {
    bar [ flip 45 x 1 rot 30 y 2 skew 10 0 s 2 0.5 ]   // same as above
}

If you have multiple instances of an adjustment (multiple scales, multiple x-axis translates, etc.) then only the last one is used. The other are dropped with a warning message. This translate/rotate/scale/skew/flip (TRSSF) adjustment order simplifies CFDG design by allowing you to not worry about what order you place the adjustments.

But being able to control the order that the adjustments are applied to create the final shape geometry is also very useful and can lead to some powerful idioms. Context Free/CFDG also has a syntax for specifying a list of shape adjustments where the adjustment order is significant:

shape spike {
    SQUARE []
    spike [[ x 0.5 s 0.95 x 0.5 ]]
}

Each time the spike rule is drawn it draws a square then draws another spike shifted over by 0.5, shrunk by 0.95, and shifted over again by 0.5, but the second shift is done in the scaled geometry. The end result is a line of shrinking squares that are perfectly abutted edge-to-edge. You can change the scaling from 0.95 to some other value and they will still be perfectly abutted. If you tried to do this in the simple adjustment order:

shape spike {
    SQUARE []
    spike [ x 0.975 s 0.95 ]
}

you would have to carefully compute the translation whenever you change the scale. Another useful idiom is to put a rotation before a translation and/or scale to work in polar geometry:

startshape flower
 
shape flower {
    // petals
    CIRCLE [[ r  30 x 0.5 s 1 0.25 ]]
    CIRCLE [[ r  90 x 0.5 s 1 0.25 ]]
    CIRCLE [[ r 150 x 0.5 s 1 0.25 ]]
    CIRCLE [[ r 210 x 0.5 s 1 0.25 ]]
    CIRCLE [[ r 270 x 0.5 s 1 0.25 ]]
    CIRCLE [[ r 330 x 0.5 s 1 0.25 ]]
    //center
    CIRCLE [ s 0.25 b 1 ]
}

These are just two of many possible ways to use ordered shape adjustments.

There is no order dependence on color coordinate changes (hue, brightness, etc.) so color changes are treated the same in both basic and ordered shape adjustment lists.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.