| title | Faces |
|---|---|
| description | The regions that a planar material encloses, and what you can read from them. |
A planar material is one whose edges meet only at shared vertices. Its edges divide the page into regions. faces holds those regions. Each face knows its area, its centroid, its walls and its neighbours. A face is an area: polygon(f) fills it and distanceTo(f) measures from its walls. A material with no closed chain whose edges branch, such as a tiling or a grid, is an area too. Its area is the union of its faces: the outer rim and the holes.
:::note
On one face every reading is a property: face.edges, face.boundaryEdges. On a collection of faces, edges and points are properties too. boundaryEdges() and contours() are calls. A collection of faces is the selection of all its faces, and it has the words of a point or edge selection. Iterate it, or use length, at, map, find, some, every, filter and groupBy. It also has has, rows, union, intersect, without, adjacent, connected, components and extract. They have the same meanings as on the selections page.
:::
/_sig/Material.planarize.mdx
Makes a shared vertex at every crossing and at every place where an endpoint touches an edge. The result is planar, so faces can read it. Edges that do not touch stay apart. Columns carry over, and a new vertex gets interpolated values. Where the edges at a crossing do not agree, the new vertex takes the values of the edge that comes first. A split of that edge gives the same values. A vertex that was there before keeps its own values. point overrides any column. Below, the blue rings are the two new vertices, where four edges meet.
import { sketch, circle, strokes } from 'occlude';
export default sketch({ aspect: [1, 1] }, (t) => {
const two = t.material(circle(38, 50, 30), circle(62, 50, 30));
const planar = two.planarize();
return [strokes(planar), planar.points.filter((p) => p.edges.length === 4).map((p) => circle(p, 2.5, { pen: 'stabilo-88-blue' }))];
});Each piece of an edge answers source: the input edge that it is a piece of. A crossing answers source too, as a selection: the input edges it lies on. An ordinary crossing lies on two edges. Only a rarer meeting, of several lines at one point, gives more. A vertex that survives planarizing has no source: it is the vertex it already was, not a new one.
Below, e.source colours each piece by the circle it came from: a piece of the first curve of the input is blue. p.source marks each crossing with the edges it lies on.
import { sketch, circle, strokes } from 'occlude';
export default sketch({ aspect: [1, 1] }, (t) => {
const two = t.material(circle(38, 50, 30), circle(62, 50, 30));
const first = two.curves.at(0).edges;
const planar = two.planarize();
return [
strokes(planar.edges.filter((e) => first.has(e.source)), { pen: 'stabilo-88-blue' }),
strokes(planar.edges.filter((e) => !first.has(e.source))),
planar.points.filter((p) => p.source !== undefined).map((p) => circle(p, 2 + p.source.length, { pen: 'stabilo-88-green' })),
];
});/_sig/Material.faces.mdx
The bounded regions of a planar material, as a collection. faces is a property. The material makes the collection the first time you read it, and then keeps it. So a face from any read is valid everywhere. Iterate it, or use length, at(i), map, filter and groupBy. If the material has a crossing without a vertex, the read fails and the message tells you to planarize.
Some words know their faces when they make them: t.tiling, t.grid, t.voronoi, t.quadtree and the lattice. These words state their faces, in the order that they made them. A tiling gives them in the order of its generations and a grid row by row. Voronoi gives its cells in the order of the sites. A quadtree gives its cells from the root down, one level at a time. Every other material reads its faces from its drawing. A write that does not change the edges keeps the stated faces: a move, a point write and a face write. A write that changes the edges of a material with stated faces drops them. The faces of the new material then come from its drawing. Each face column goes with the walls, as faces.set() below tells.
import { sketch, circle, polygon, fill, mm } from 'occlude';
export default sketch({ aspect: [1, 1] }, (t) => {
const cells = t.material(circle(38, 50, 30), circle(62, 50, 30)).planarize().faces;
return cells.map((f, i) => polygon(f, { stroke: false, fill: fill('hatch', { angle: i * 60, spacing: mm(1.2) }) }));
});/_sig/Face.index.mdx /_sig/Face.area.mdx /_sig/Face.perimeter.mdx /_sig/Face.bounds.mdx /_sig/Face.centroid.mdx /_sig/Face.contours.mdx /_sig/Face.extract.mdx
One region. area is the outer area minus the holes. centroid is the centroid of that filled area. contours() holds the outer loop and the holes, as a list of closed contours. A face is an area. You can give it as it is to polygon, distanceTo, force.boundary, t.within, clip, mask, t.material and t.sample. t.material(f) gives its walls. To keep the faces of a collection that lie in an area, use t.within(cells, area, { keep }). keep is 'contained' (the default), 'centroid' or 'touching', the same words as for points and edges. face.extract() gives the face as a new material, with its edges, its corners and its columns. A face always has the same winding. The outer loop turns counter-clockwise when y points up, and each hole turns the other way. contours() and the walls of face.extract() both turn this way. A normal from along points to the left of the travel, so on a face's walls it points into the face.
import { sketch, circle, strokes, distanceTo } from 'occlude';
export default sketch({ aspect: [1, 1] }, (t) => {
const cells = t.material(circle(38, 50, 30), circle(62, 50, 30)).planarize().faces;
return cells.map((f) => [
strokes(t.isolines(distanceTo(f), 3)),
circle(f.centroid, 1.5, { pen: 'stabilo-88-blue' }),
]);
});area and perimeter together say how round a face is: a disc scores 1 and a ragged sliver scores near 0. bounds is the box the face sits in. A wide cell takes a hatch across it, and a tall one takes a hatch down it. index is the place of the face in the order of the collection. A Voronoi cell has the place of its site, so every third site gives its cell another pen.
import { sketch, polygon, fill, mm } from 'occlude';
export default sketch({ aspect: [3, 2], seed: 5 }, (t) => {
const cells = t.voronoi(t.relax(t.scatter({ spacing: 22 }), { iterations: 3 }));
return cells.faces.map((f) => {
const round = (4 * Math.PI * f.area) / (f.perimeter * f.perimeter);
const angle = f.bounds.w > f.bounds.h ? 0 : 90;
return polygon(f, { fill: fill('hatch', { angle, spacing: mm(0.5 + 2.2 * round) }), pen: f.index % 3 === 0 ? 'stabilo-88-blue' : undefined });
});
});/_sig/Face.source.mdx /_sig/Face.parent.mdx /_sig/Face.children.mdx /_sig/Face.depth.mdx /_sig/Face.leaf.mdx
source is what the face came from, in the shape that the word that made it gives. A Voronoi cell's source is its site, a point of the sites. A tile's source is the placement that carried the first cell there. A quadtree cell's source is the points it holds, as a selection of the input. A face that a material reads from its drawing has no source.
Faces can nest. A quadtree states every cell from the root to the leaves. parent is the face that holds this one, and undefined at a root. children is the faces that it holds one step down, and it is empty for a leaf. depth counts the steps from the root, 0 at a root. leaf is true for a face that holds no other face. The leaves divide the area with no overlap: faces.filter((f) => f.leaf). A face of a material that does not nest is a root and a leaf. A tiling and a subdivision do not nest. Each face of a tiling is a root, and its generation column counts the reflections from the first cell. subdivide keeps only the new faces, and the source of each new face is the face that it divides. Below, the leaves of a quadtree get a hatch that closes with depth, and each leaf dots its own points. The hatch is blue when all the children of the parent are leaves.
import { sketch, polygon, strokes, dots, fill, mm } from 'occlude';
export default sketch({ aspect: [1, 1], seed: 7 }, (t) => {
const pts = t.scatter((x, y) => Math.max(0, 1 - Math.hypot(x - 32, y - 36) / 45), { spacing: 3 });
const tree = t.quadtree(pts, { capacity: 2 });
const leaves = tree.faces.filter((f) => f.leaf);
return [
leaves.map((f) => polygon(f, {
stroke: false,
fill: fill('hatch', { angle: 45, spacing: mm(Math.max(0.4, 3.2 - 0.5 * f.depth)) }),
// Blue where the parent split into four leaves.
fillPen: f.parent?.children.every((c) => c.leaf) ? 'stabilo-88-blue' : 'pigma-005-black',
})),
strokes(tree),
leaves.map((f) => dots(f.source, { pen: 'stabilo-88-blue' })),
];
});A face that you hold names its face in another state. A face that a material reads from its drawing is the face of its walls. A stated face is a face of its own. So the same face is the same after a move, after a transform, and after a planarize that keeps its walls. index is a place in one state only. To find a face again in another state, give it to the faces of that state: faces.rows(f) or faces.has(f). Below, a round hex net stretches in one move, and each cell finds its rest shape in the net before the move. The hatch is tighter where a cell grew.
import { sketch, polygon, strokes, circle, fill, mm } from 'occlude';
export default sketch({ aspect: [1, 1], seed: 3 }, (t) => {
const net = t.within(t.tiling(6, 3, { side: 5.2, rotate: 30 }), circle(50, 50, 38));
const pulled = net.move((p) => [0.1 * (p.x - 50) * (1 + Math.sin(p.y / 12)), 0.1 * (p.y - 50) * (1 + Math.sin(p.x / 12))]);
const rest = net.faces;
return [
pulled.faces.map((f) => {
const grown = f.area / rest.rows(f).at(0).area;
return polygon(f, { stroke: false, fill: fill('hatch', { angle: 45, spacing: mm(Math.max(0.5, 0.5 + 5 * (1.45 - grown))) }) });
}),
strokes(pulled),
];
});/_sig/Face.edges.mdx /_sig/Face.points.mdx /_sig/Face.boundaryEdges.mdx
face.edges is every edge that belongs to this face: its walls, and any loose edge that runs into it from a wall. A line that touches nothing belongs to no face. To take the edges that lie inside a face by position, use t.within(m.edges, face). face.boundaryEdges is the walls only. A wall is an edge between this face and another face, or between this face and the outside. face.points holds the endpoints of face.edges. A face that holds other faces also has the walls between them in edges.
:::warning
For a plain pile of shapes, edges and boundaryEdges are the same selection. They differ only when a loose line runs into a region. Use boundaryEdges when you want an outline.
:::
Below, one cell with a loose line that runs in from its wall. edges (blue) holds the line. boundaryEdges (black, on top) holds the walls only.
import { sketch, rect, line, strokes, append } from 'occlude';
export default sketch({ aspect: [1, 1] }, (t) => {
const room = append(t.material(rect(15, 15, 70, 70)), t.material(line(15, 50, 60, 50))).planarize();
const cell = room.faces.at(0);
return [strokes(cell.edges, { pen: 'stabilo-88-blue' }), strokes(cell.boundaryEdges)];
});/_sig/Face.adjacent.mdx
The faces on the other side of this face's walls. Two faces are neighbours when they share an edge. A shared corner is not enough. Below, the blue face has the most neighbours, and a hatch marks each of them.
import { sketch, circle, polygon, fill, mm, strokes } from 'occlude';
export default sketch({ aspect: [1, 1] }, (t) => {
const cells = t.material(circle(38, 50, 30), circle(62, 50, 30), circle(50, 26, 18)).planarize().faces;
const most = Math.max(...cells.map((f) => f.adjacent.length));
const middle = cells.filter((f) => f.adjacent.length === most).at(0);
return [strokes(cells.edges), middle.adjacent.map((f) => polygon(f, { stroke: false, fill: fill('hatch', { angle: 45, spacing: mm(1.5) }) })), strokes(middle.boundaryEdges, { pen: 'stabilo-88-blue' })];
});/_sig/faces.edges.mdx /_sig/faces.points.mdx /_sig/faces.boundaryEdges.mdx /_sig/faces.contours.mdx
The same readings for a collection or a selection of faces. edges is every edge that touches a selected face, once. strokes(faces) draws those edges, and it draws each wall one time. boundaryEdges() is the outline of the selected faces as one region. A wall between two selected faces is not part of it. The boundary of a hole is part of it. contours() is that outline as closed loops. polygon reads it to fill the region.
A collection of faces is several areas, so polygon(faces) is a type error. Write polygon(faces.contours()) for the union, or faces.map((f) => polygon(f)) for each face. As points, a collection of faces is the centroids of its faces: dots(faces) and material(faces) put one point in each face. distanceTo(material(faces)) measures to them. faces.points gives the corners.
import { sketch, circle, polygon, fill, mm, strokes } from 'occlude';
export default sketch({ aspect: [1, 1] }, (t) => {
const cells = t.material(circle(38, 50, 30), circle(62, 50, 30)).planarize().faces;
const crescents = cells.filter((f) => Math.abs(f.centroid[0] - 50) > 1);
return [polygon(crescents.contours(), { stroke: false, fill: fill('hatch', { angle: 0, spacing: mm(1.5) }) }), strokes(crescents.boundaryEdges(), { pen: 'pigma-05-black' })];
});/_sig/Selection.adjacent.mdx /_sig/Selection.components.mdx
The faces on the other side of the walls of the selected faces, one step out, the selected faces excluded. Two selected faces that share a wall are each other's inside, not each other's neighbour. sel.union(sel.adjacent()) is the selection grown by a ring, and says so. connected() is the selection and every face that you can reach from it across walls. components() divides the selected faces into pieces that share walls, and keys them 0, 1, 2 …. Below, the blue cells are the selection, and the hatch is its ring.
import { sketch, polygon, rect, fill, mm, strokes } from 'occlude';
export default sketch({ aspect: [1, 1] }, (t) => {
const cells = t.voronoi(t.scatter({ spacing: 14 })).faces;
const seed = t.within(cells, rect(40, 40, 20, 20), { keep: 'centroid' });
const ring = seed.adjacent();
return [strokes(cells.edges), ring.map((f) => polygon(f, { stroke: false, fill: fill('hatch', { angle: 45, spacing: mm(1.2) }) })), strokes(seed.boundaryEdges(), { pen: 'stabilo-88-blue' })];
});Below, the small cells fall into towns, and components() finds each town. Each town gets its own hatch. extract() takes the left town out as a new material, and the sketch draws it again, smaller, in blue.
import { sketch, polygon, strokes, fill, mm, distanceTo } from 'occlude';
export default sketch({ aspect: [1, 1], seed: 12 }, (t) => {
const dense = (x, y) => 0.1 + Math.exp(-((x - 35) ** 2 + (y - 40) ** 2) / 200) + Math.exp(-((x - 68) ** 2 + (y - 66) ** 2) / 150);
const cells = t.voronoi(t.relax(t.scatter(dense, { spacing: 3 }), { iterations: 2, density: dense })).faces;
const towns = cells.filter((f) => f.area < 25).components().filter((town) => town.length > 2);
// The town with a face under the point: a face's distance is positive inside it.
const middle = towns.find((town) => town.some((f) => distanceTo(f)(35, 40) > 0)) ?? towns[0];
return [
strokes(cells, { pen: 'pigma-005-black' }),
towns.map((town) => polygon(town.contours(), { stroke: false, fill: fill('hatch', { angle: 20 + 50 * town.key, spacing: mm(1) }) })),
strokes(middle.extract().scale(0.5, { origin: 'center' }), { pen: 'stabilo-88-blue' }),
];
});/_sig/faces.measure.mdx
Measures each face, and answers the material with the measurements as face columns. Read them on the faces of the answer. Every face gets orientation, elongation, and the largest inscribed circle as inscribedX, inscribedY and inscribedRadius. With a field, each face also gets integral, mean, samples, and the centroid that the field weights as weightedX and weightedY. A face with no weight reads NaN there. The faces keep their order and their names, so measured.faces.rows(f) holds the face f. When you measure a selection, the other faces read 0. step is the side of one raster cell, a length in the units of the material. In a material with a curved space, the call measures area, perimeter, the inscribed circle and the field values in that space. face.area and face.perimeter are too. centroid, orientation and elongation stay in the coordinates.
import { sketch, circle, strokes, line, distance } from 'occlude';
export default sketch({ aspect: [1, 1] }, (t) => {
const cells = t.material(circle(38, 50, 30), circle(62, 50, 30)).planarize().faces;
const light = (x, y) => Math.max(0, 1 - distance([x, y], [20, 20]) / 70);
const measured = cells.measure(light, { step: 0.7 });
return [strokes(cells.edges), measured.faces.map((f) => {
const lit = [f.weightedX, f.weightedY];
return [circle(f.centroid, 1.2), circle(lit, 1.2, { pen: 'stabilo-88-blue' }), line(f.centroid, lit, { pen: 'stabilo-88-blue' })];
})];
});/_sig/Edge.faces.mdx
The faces on the two sides of an edge, as a selection of faces. A wall between two cells has two. An outer wall or a loose edge inside a face has one. An edge that no face touches has none. The material must be planar, and edge.faces builds the face map itself. A material that is not planar fails with the same message as faces. Below, the walls with two faces are blue.
import { sketch, circle, strokes } from 'occlude';
export default sketch({ aspect: [1, 1] }, (t) => {
const m = t.material(circle(38, 50, 30), circle(62, 50, 30)).planarize();
const walls = m.edges.filter((e) => e.faces.length === 2);
return [strokes(m), strokes(walls, { pen: 'stabilo-88-blue' })];
});/_sig/faces.set.mdx
A value that belongs to what the walls enclose. The column follows the material through any edit that leaves the face alone. A stated face keeps its column through a move and a point write. A face that a material reads from its drawing is the face of its walls, so its column follows those walls. It follows a SPLIT of a wall too, because each new wall comes from the wall that it cut.
m.faces.set(column, value, where?, opts?) writes a face column and returns the new material. The value is a number, or a function of the face. The object form writes several columns at once, and every function reads the faces as they were. A where, or a filtered selection of faces, names the faces that the write changes. A value that is not a finite number leaves that face as it was.
The last argument can be { transfer, fallback }. transfer says what a face does when its boundary really changes. 'nearest', the default, takes the value of the old face it shares the most walls with. 'drop' stops there. A face column is dense: every face has a number for every face column. A face that no write reached and that takes nothing from an old face reads fallback, or 0 without one.
A write that changes the edges drops the faces that a word stated, such as the cells of t.voronoi. The new faces then come from the drawing, and each face column goes with the walls as above.
import { sketch, strokes, polygon, fill, mm } from 'occlude';
export default sketch({ aspect: [3, 2], seed: 9 }, (t) => {
const b = t.bounds();
const cells = t.voronoi(t.relax(t.scatter({ spacing: 26 }), { iterations: 4 }));
// Two columns, given once, to the cells as they are now. A second call
// sees the first call's column.
const tinted = cells.faces.set('tone', () => t.rnd()).faces.set({ turn: () => t.rnd(170) });
// Then every wall is split and every inside vertex wanders. The walls are
// new edges, and each one comes from a wall of a cell, so every cell
// keeps the tone it was given.
const cracked = t.steps(1, tinted, (g) => g.split(g.edges), (g) => {
const inner = g.points.filter((p) => p.x > 1 && p.x < b.w - 1 && p.y > 1 && p.y < b.h - 1);
return g.move((p) => [t.noise(p.x / 14, p.y / 14) * 2, t.noise(p.y / 14, p.x / 14) * 2], inner);
});
return [
cracked.faces.map((f) => polygon(f, { fill: fill('hatch', { angle: f.turn, spacing: mm(0.7 + f.tone * 1.6) }), stroke: false })),
strokes(cracked, { pen: 'pigma-005-black' }),
];
});