From Context Free Art

Contents 1 Shape Adjustments: Geometry, Color, and Time 1.1 Geometry Adjustments 1.2 Color Adjustments 1.2.1 Targeting a Color 1.2.1.1 Example: Targeting yellow 1.2.2 Some common hues 1.3 Time Adjustment 2 Basic Shape Adjustments vs. Ordered Shape Adjustments 2.1 or what is the difference between [ … ] and [[ … ]]

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	Notes
x num	translation along the x-axis by num
y num	translation along the y-axis by num
z num	translation along the z-axis by num	The z-axis position determines which shape is on top when they overlap. The z-axis position is not stored in the affine transform matrix and does not affect the shape of objects.
size num or s num	scale in x and y by num
size num1 num2 or s num1 num2	scale in x by num1 and in y by num2
size num1 num2 num3 or s num1 num2 num3	scale in x by num1, in y by num2, and in z by num3	The z-axis scale is not stored in the affine transform matrix and does not affect the shape of objects.
rotate num or r num	rotate in the x/y plane num degrees
flip num or 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

Color Adjustments

The color of a shape is represented by a point in the HSBA color space (HSB 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).

hue num

add num to the drawing hue value, modulo 360

saturation 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

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

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.

Abbreviations: 'hue' can be abbreviated as 'h', 'saturation' can be abbreviated as 'sat', 'brightness' can be abbreviated as 'b', and 'alpha' can be abbreviated as 'a'.

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.

hue 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

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

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

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 num1	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.