| title | Sketch |
|---|---|
| description | The sketch function, its config, units, controls and the layout helpers. |
A sketch is a function that returns shapes. sketch(config, (t) => tree) describes it. The engine draws nothing until the sketch renders. The tree can nest arrays to any depth. The engine flattens the tree and draws it in order. It skips a falsy entry, so condition && shape includes a shape only when the condition holds.
/_sig/sketch.mdx
The config sets the drawable and the seed. aspect: [w, h] fixes the shape of the drawable. The drawable then sits centred on whatever paper renders it. paper names the sheet instead. margin is an inset from the paper edge. seed is a number, a string, or 'url' to read the studio's ?seed=. pens declares the sketch's pens by name.
import { sketch, circle, line } from 'occlude';
export default sketch({ aspect: [1, 1], seed: 12 }, (t) => [
circle(50, 50, 30),
t.times(6, (k) => k % 2 === 0 && line(10, 20 + k * 12, 90, 20 + k * 12)),
]);The sketch function can be async and use await. Some 3D words, such as t.hatch, run a job in the background and return a promise. A sketch that calls them uses an async function: sketch(config, async (t) => tree).
import { sketch, circle } from 'occlude';
export default sketch({ aspect: [1, 1] }, async (t) => {
const radius = await Promise.resolve(40);
return circle(50, 50, radius);
});/_sig/mm.mdx /_sig/inch.mdx
A bare number is a percentage of the short side of the drawable. On a square drawable both axes run 0 to 100. On a 2:1 drawable the long axis runs to 200. mm(v) and inch(v) are physical sizes, the same on any paper. Use bare units to compose. Use physical units for what must keep its size on paper: hatch spacing, dot sizes, a wobble. t.len(v) converts a physical size to drawable units for arithmetic. Change the paper, and the top row keeps its proportion of the drawable while the bottom row keeps its spacing in millimetres. This page draws on a 180 mm drawable.
import { sketch, circle, label, mm } from 'occlude';
export default sketch({ aspect: [1, 1] }, (t) => [
label('10 UNITS', 8, 22, 4), t.times(9, (k) => circle(10 + k * 10, 36, 2)),
label('10 MM', 8, 58, 4), t.times(9, (k) => circle(10 + k * t.len(mm(10)), 72, mm(4), { pen: 'stabilo-88-blue' })),
]);/_sig/paper.mdx /_sig/pen.mdx
paper declares the sheet for the config: a width and a height in physical units, and a colour. pen declares a pen from its nib width and colour, for the config's pens. The studio's pen library also supplies names, and a sketch can use a library name with no declaration. The first entry of pens is the pen for a shape that names none. Without pens, that pen is the library's first pen. The examples on this site use four of them: pigma-005-black (0.2 mm), pigma-05-black (0.45 mm), stabilo-88-blue and stabilo-88-green.
import { sketch, paper, pen, mm, inch, circle } from 'occlude';
export default sketch({ paper: paper({ width: inch(5), height: inch(3) }), pens: { main: pen({ width: mm(0.5), color: '#2457D6' }) }, margin: 8 }, (t) => {
const b = t.bounds();
return t.times(9, (k, u) => circle(b.h / 2 + u * (b.w - b.h), b.h / 2, b.h / 2 - 4, { pen: 'main' }));
});/_sig/ui.mdx
Marks a literal as tweakable. In the studio it gets a slider. The slider rewrites the literal in the code, so the tuned sketch saves as seen. Anywhere else it returns its value.
import { sketch, circle, ui } from 'occlude';
export default sketch({ aspect: [1, 1], seed: 2 }, (t) => {
const count = ui(24, { min: 3, max: 80, step: 1 });
const size = ui(4, { min: 1, max: 12 });
return t.times(count, () => circle(t.rnd(10, 90), t.rnd(10, 90), size * t.rnd(0.4, 1)));
});/_sig/Toolkit.probe.mdx
Returns the value and records it under a label. After a render, the studio's controls panel shows the count, the minimum, the mean, the maximum and a histogram for each label. Use it to learn what a field gives before you map it. A material, such as the points of along(), goes to the studio's debug inspector instead. It changes nothing, and it is free to leave in.
import { sketch, circle } from 'occlude';
export default sketch({ aspect: [1, 1], seed: 2 }, (t) => t.grid({ cols: 14, rows: 14 }).faces.map((f) => {
const [x, y] = f.centroid;
return circle(x, y, 0.5 + 2.5 * t.probe('noise', (t.noise(x / 18, y / 18) + 1) / 2));
}));/_sig/Toolkit.bounds.mdx /_sig/Toolkit.grid.mdx
bounds() is the drawable in the sketch's units and frame: { x, y, w, h, cx, cy }, the corner, the size and the middle. Read it when a drawing must fill whatever drawable it lands on. The answer is a rect, so it is an area: t.within(m, t.bounds()) cuts to the drawable. grid({ cols, rows, gap? }) covers the drawable with cells, as one material. Its faces are the cells, row by row. Each face has the face columns i (across) and j (along y), and its bounds is the rect of the cell, { x, y, w, h, cx, cy }. j counts down the page, or up the page in a yUp sketch. Two cells that touch share one wall, so strokes draws the wall once and f.adjacent answers. A gap moves the cells apart, and then they share nothing. For cells that are not rectangles, use t.tiling (see Geometry).
Under origin: 'center', the corner of the drawable is (-w/2, -h/2) and its middle is (0, 0). bounds() answers in that frame, and every word that covers the drawable (grid, tiling, scatter, voronoi and the fields) reads it. Below, the grid covers the drawable of a centred, y-up sketch.
import { sketch, rect, circle } from 'occlude';
export default sketch({ aspect: [1, 1] }, (t) => {
const b = t.bounds();
return [rect(2, 2, b.w - 4, b.h - 4), t.grid({ cols: 6, rows: 6, gap: 3 }).faces.map((f) => circle(f.centroid, Math.min(f.bounds.w, f.bounds.h) / 2))];
});import { sketch, rect, circle, line } from 'occlude';
export default sketch({ aspect: [3, 2], origin: 'center', yUp: true }, (t) => {
const b = t.bounds();
return [
rect(b.x + 2, b.y + 2, b.w - 4, b.h - 4),
t.grid({ cols: 6, rows: 4, gap: 3 }).faces.map((f) => circle(f.centroid, Math.min(f.bounds.w, f.bounds.h) / 3)),
line(0, 0, 0, b.h / 2 - 2, { pen: 'stabilo-88-blue' }),
];
});/_sig/Toolkit.times.mdx /_sig/Toolkit.range.mdx
times(n, fn) calls fn(k, u) n times and returns the results. k is the index and u runs from 0 to 1 across the run. range(n) and range(a, b, step?) give integer sequences. Both refuse a runaway count.
import { sketch, line } from 'occlude';
export default sketch({ aspect: [1, 1] }, (t) => [t.times(16, (k, u) => line(10, 10 + u * 80, 90, 50)), t.range(0, 100, 10).map((x) => line(x, 92, x, 96, { pen: 'stabilo-88-blue' }))]);The geometry a sketch draws in is a frame setting. space names the metric, and projection names the chart of the sheet. Both live on the config beside paper and pens. They have a page of their own: Reference: Geometry.