> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ploterr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Materials and patterns

> Name the materials of a building once, give walls and roofs their patterns and cut hatches, and add the fascia, gutter and downpipe of a roof.

A material is an entry of the building model's `materials` list: a name, a finish, a colour, the pattern it draws on the faces you see and the hatch it draws where a section cuts it. A wall or a roof names a material by its key. Elevations then show brick courses on the walls and tile courses on the roof, the roof plan shows the tiles on each slope, and sections hatch the cuts. The fascia, soffit, bargeboards, gutters and downpipes of a roof are its `trim`.

[Live example](https://floorkit-examples.ploterr.com/floorkit/guides/materials-and-patterns?embed=1)

## Before you start

You have the house of [Add a roof](https://docs.ploterr.com/floorkit/guides/add-a-roof.md): one closed wall `room-walls` with a door and a window, and the gable roof `main-roof`.

## Name the materials

Each material has a key. The key shares the id namespace of the model, so it cannot be the id of an element.

```typescript theme={null}
import type {
  BmMaterial,
  BmRoof,
  BuildingSession,
  ProjectFile,
  SavedDrawingView,
} from '@opengeometry/floorkit';

export const houseMaterials: Record<string, BmMaterial> = {
  'facing-brick': { name: 'Red facing brick', surfacePattern: 'brick', cutHatch: 'brick' },
  'clay-tiles': { name: 'Plain clay tiles', finish: 'smooth', surfacePattern: 'plain-tile' },
  render: { name: 'Painted render', finish: 'white', surfacePattern: 'render' },
};

export function addMaterials(session: BuildingSession): void {
  for (const [materialId, definition] of Object.entries(houseMaterials))
    session.apply({ kind: 'add-material', materialId, definition }, session.revision);
}
```

## Give the walls and the roof their materials

`replace-wall-settings` replaces every setting of a wall, so keep the other settings and set `material`. The roof takes the tiles and its trim: a 200 mm fascia and a square gutter on each eave, a bargeboard on each gable, a closed soffit and one downpipe on the first edge of the outline, 1 metre from its start.

```typescript theme={null}
export function useMaterials(session: BuildingSession, roof: BmRoof): void {
  const storey = session.snapshot().buildings[0]?.storeys.find(({ id }) => id === 'ground');
  const wall = storey?.walls?.find(({ id }) => id === 'room-walls');
  if (!wall) throw new Error('There is no room wall to dress.');
  const {
    id,
    points: _points,
    closed: _closed,
    arcs: _arcs,
    openings: _openings,
    ...settings
  } = wall;
  session.apply(
    {
      kind: 'replace-wall-settings',
      buildingId: 'building',
      storeyId: 'ground',
      wallId: id,
      settings: { ...settings, material: 'facing-brick' },
    },
    session.revision,
  );
  session.apply(
    {
      kind: 'replace-element',
      buildingId: 'building',
      storeyId: 'ground',
      list: 'roofs',
      elementId: roof.id,
      element: {
        ...roof,
        material: 'clay-tiles',
        trim: {
          fascia: { depth: 0.2 },
          soffit: true,
          bargeboard: { depth: 0.2 },
          gutter: { profile: 'square', size: 0.1 },
          downpipes: [{ edge: 0, along: 1 }],
        },
      },
    },
    session.revision,
  );
}
```

`replace-material` changes a material everywhere it is used, in one step. `remove-material` refuses a material that an element still names: the refusal is `invalid-target` with a `material-in-use` issue that lists them.

## Draw them

An elevation and a roof plan of the house show the patterns. They need no setting.

```typescript theme={null}
export const materialViews: SavedDrawingView[] = [
  {
    id: 'elevation-materials',
    name: 'South elevation',
    kind: 'elevation',
    origin: [3, -3],
    lookDirection: [0, 1],
    crop: { left: -4.5, right: 4.5, bottom: -5.5, top: 0.5 },
  },
  { id: 'roof-plan', name: 'Roof plan', kind: 'roof-plan', buildingId: 'building' },
];

export function addMaterialViews(project: ProjectFile): ProjectFile {
  return { ...project, version: 3, views: [...project.views, ...materialViews] };
}
```

## Rules

* `name` is shown in notes and schedules and cannot be empty (`bad-material-name`). `surfacePattern` is one of `none`, `brick`, `stone`, `render`, `weatherboard`, `tile-hanging`, `plain-tile`, `interlocking-tile`, `slate` and `glazing-bars` (`bad-surface-pattern`); `cutHatch` is a name of `DRAWING_HATCH_NAMES` (`bad-cut-hatch`).
* A wall, a layer of a wall type, a roof, a dormer and the band of a bay name a material by its key in `material`. A roof material that is neither a `RoofMaterial` nor a key is refused with `unknown-material`; a wall material that is not a key keeps today's warning and draws as before.
* A model with no `materials`, or whose materials no element names, draws exactly as before.
* Patterns are lines in metres, clipped exactly to the faces you see: courses run level along the face and are spaced along it, so on a slope along the slope. The lines are inked at 0.13 mm whatever the class of their element. The table of spacings is on [Pens and hatches](https://docs.ploterr.com/floorkit/api/drawings/pens-and-hatches.md).
* Elevations draw a pattern on every face that does not face down. Sections draw it only on faces that face up, such as roofs, so the inside of a room stays blank. A round wall draws its courses and the dots of render, but no joints or bars.
* The roof plan draws the pattern on each slope, with courses parallel to the eave of the slope, clear of rooflights, dormers and chimney stacks. A flat roof draws none. Give a glazed roof, such as a conservatory, a material with `glazing-bars`: its bars run down the slope.
* A section hatches a cut wall, layer or roof with the `cutHatch` of its material, or the solid poché when the material has none.
* `cutHatch` can also be `stud` (a zigzag between the two faces of the cut) or `batt` (insulation loops). To draw a material with another hatch or fill on paper only, set it in the paper style's `materials`, for example `materials: { WOOD: { hatch: 'stud' } }`; see [Paper styles](https://docs.ploterr.com/floorkit/api/drawings/paper-styles.md).
* A solid cut with no colour prints the cut poché `#4d4d4d`, not black.
* The fascia and the gutter run along each eave edge, the bargeboard along each gable edge and follows the top of the roof, and the soffit closes the overhang under each eave. A downpipe stands under the gutter at `along` metres from the start of its outline edge and runs down to the site ground under it: the surface through the site's `groundPoints`, else the site `elevation`. A downpipe on a gable edge is refused with `downpipe-on-gable`. One whose `along` passes the end of its edge is not built, and the build warns `downpipe-past-edge`; one whose gutter is not above the ground is not built either, and the build warns `downpipe-under-ground`. With `swanNeck: true` a downpipe leaves the gutter outlet, bends back under the overhang at 30° below level and runs down 25 mm off the wall face (the roof outline), and that bend must be above the ground; without it, the downpipe drops straight from the gutter. With `endsAt: 'roof-below'` a downpipe stops on the highest roof of the building under it, such as a lower extension roof, with a socket 0.22 m above that roof; where no roof lies under it, the build is refused with `downpipe-no-roof-below` at its `endsAt`. Absent or `ground`, it runs to the ground.
* `gutter.edges` puts the gutter on the outer-ring edges you list only, such as the low edge of a flat roof: `gutter: { profile: 'half-round', size: 0.112, edges: [2] }`. A flat roof without it takes the gutter on every edge. An index that is not an outline edge is refused with `bad-roof-edge`, a gable with `gutter-on-gable` and an edge listed twice with `bad-gutter`. With `edges` set, a downpipe on an edge without the gutter is refused with `downpipe-without-gutter`. The gutter ends flush with the fascia of an edge beside it that has no gutter.
* A dormer takes its own `trim`: a fascia and a gutter on the eaves of its roof and downpipes from that gutter down to the host roof slope. See [Add a roof](https://docs.ploterr.com/floorkit/guides/add-a-roof.md#dormers).
* A roof joined to another (`trimTo`) trims its trim with it, as it trims its own body. An edge that lies inside the other roof gets no trim, so a gable buried in it has no bargeboard.
* `ridge: { height, width? }` lays a ridge tile along each level ridge, in the roof colour: its top is `height` above the ridge and its sides stand `width` apart (absent: twice `height`), down to the slopes. Elevations draw its top and its foot on the slopes, sections cut it, and it shows in 3D.
* A roof with arcs or rounded corners takes no trim: `trim` on it is refused with `trim-on-curved-roof`.
* The roof plan draws the outer edge of the gutter along each eave. Elevations and sections draw the fascia, soffit, bargeboard, the gutter in each of its profiles and the downpipes. A half-round or ogee gutter draws its top and bottom edges and its ends in an elevation that sees its eave square on, its exact profile in one that looks along it, and its profile where a section cuts across it.

## Limits

* A `half-round` or `ogee` gutter on an eave that the view sees at a slant (neither square on nor end on) is not drawn in that view, with the warning `The gutter of roof "…" is not drawn in this view`; the rest of the roof draws. Use `square` for a gutter on such an eave.
* Where a section cuts a `half-round` or `ogee` gutter, its cut profile draws as straight pieces no more than 0.01 mm from the true curve, not as exact arcs.
* In a section, only a layer of a wall type carries its `material`, so a paper style's `materials` does not reach the section cut of a single-material wall, roof or slab.
* A `batt` loop is drawn as 32 straight pieces per loop.
* A half-hip edge takes the fascia and the gutter of an eave; its small gable has no bargeboard.
* Patterns print through furniture blocks in front of a face, and run on behind a downpipe: a downpipe hides the lines behind it but cuts nothing out of the faces behind it.
* A swan neck is three pipes that overlap at its two bends, so an elevation draws short seam lines inside the pipe outline at each bend.
* A view of a roof with a swan-neck downpipe warns `A seen face of "…" is left without its surface region`, and the neck draws as lines without its fill.

## Next

> [card] [Pens and hatches](https://docs.ploterr.com/floorkit/api/drawings/pens-and-hatches.md)
>
> The pattern spacings and the hatches of a cut.

> [card] [Use wall types](https://docs.ploterr.com/floorkit/guides/wall-types.md)
>
> Layers of a wall, each with its material.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.