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

# Massing helpers

> Read the areas of a mass and check its storeys.

## Import

```typescript theme={null}
import {
  storeyTilingError,
  resolveAreaKind,
  AREA_KINDS,
  massQuantities,
  massBuildingCommand,
  toBuildingUse,
  irMassToMassLike,
  massToShell,
  BUILDING_USES,
  MASS_COLORS_BY_USE,
  massSegmentColorCommand,
} from '@opengeometry/floorkit';
```

## storeyTilingError

Storeys must tile their segment exactly; return the mismatch (0 when they do).

```typescript theme={null}
function storeyTilingError(segment: MassSegment): number;
```

## resolveAreaKind

Explicit kind → `parking` use → `parking`; a storey whose top is at or below the site grade (world Y) → `basement`; otherwise `gross`.

```typescript theme={null}
function resolveAreaKind(
  storey: MassStorey,
  segmentUse: BuildingUse | undefined,
  storeyElevation: number,
  grade: number,
): AreaKind;
```

## AREA\_KINDS

What a storey's plate counts as.

```typescript theme={null}
const AREA_KINDS: readonly ['gross', 'balcony', 'core', 'basement', 'parking', 'mechanical'];
```

## massQuantities

Quantities of a stacked-prism mass, where `options.grade` is the world Y of the site grade (default 0) and a storey whose top is at or below it is a basement.

```typescript theme={null}
function massQuantities(
  mass: MassLike,
  options?: {
    grade?: number;
  },
): MassQuantities;
```

## massBuildingCommand

The `add-building` command for a new building with one mass, from an outline drawn in site XZ metres.

```typescript theme={null}
function massBuildingCommand(
  model: Readonly<BuildingModel>,
  outline: readonly PointXZ[] | PolygonProfile,
  options: MassBuildingOptions,
): BuildingCommand;
```

## toBuildingUse

Coerce a BuildingModel use string to a `BuildingUse` (`custom:` prefix for anything unknown).

```typescript theme={null}
function toBuildingUse(use: string | undefined): BuildingUse | undefined;
```

## irMassToMassLike

The `MassLike` view of an `BmBuilding` with a `mass`: segments with their storeys resolved from `building.storeys` by id (in `storeyIds` order).

```typescript theme={null}
function irMassToMassLike(building: BmBuilding): MassLike;
```

## massToShell

Build the shell of `mass` as an `BmBuilding`.

```typescript theme={null}
function massToShell(mass: MassLike, opts?: ShellOptions): BmBuilding;
```

## BUILDING\_USES

```typescript theme={null}
const BUILDING_USES: readonly [
  'residential',
  'office',
  'retail',
  'hotel',
  'civic',
  'industrial',
  'parking',
  'mixed',
  'other',
];
```

## MASS\_COLORS\_BY\_USE

The colour of a mass part by its use, when neither the part nor its mass has a `color`.

```typescript theme={null}
const MASS_COLORS_BY_USE: Readonly<Record<string, BmColor>>;
```

## massSegmentColorCommand

The `replace-mass` command that gives one part of a saved mass the colour `color` (`#rrggbb`), or takes its own colour away when `color` is `undefined`; `undefined` when the part already has that colour.

```typescript theme={null}
function massSegmentColorCommand(
  model: Readonly<BuildingModel>,
  buildingId: string,
  segmentId: string,
  color: BmColor | undefined,
): ReplaceMassCommand | undefined;
```

## Types

### MassBuildingOptions

What `massBuildingCommand` needs besides the outline.

```typescript theme={null}
interface MassBuildingOptions {
  storeyHeight: number;
  storeyCount: number;
  use?: string;
  name?: string;
  baseElevation?: number;
}
```

<ResponseField name="storeyHeight" type="number" required>
  Floor-to-floor height of every storey, in metres; above 0.
</ResponseField>

<ResponseField name="storeyCount" type="number" required>
  How many storeys the mass has; an integer of 1 or more.
</ResponseField>

<ResponseField name="use" type="string">
  Use of the segment and of its storeys, for example `office`.
</ResponseField>

<ResponseField name="name" type="string">
  Name of the new building.
</ResponseField>

<ResponseField name="baseElevation" type="number">
  World Y of the bottom of the mass. Defaults to the site grade, or 0 without a site.
</ResponseField>

### MassStorey

```typescript theme={null}
interface MassStorey {
  id: string;
  name?: string;
  height: number;
  use?: BuildingUse;
  areaKind?: AreaKind;
}
```

<ResponseField name="id" type="string" required />

<ResponseField name="name" type="string" />

<ResponseField name="height" type="number" required>
  Floor-to-floor height, metres.
</ResponseField>

<ResponseField name="use" type="BuildingUse">
  Overrides the owning segment's use for this storey (a retail ground floor under offices).
</ResponseField>

<ResponseField name="areaKind" type="AreaKind">
  Explicit area classification. Derived when absent — see resolveAreaKind.
</ResponseField>

### AreaKind

What a storey's plate counts as.

```typescript theme={null}
type AreaKind = (typeof AREA_KINDS)[number];
```

### MassLike

The structural shape `massQuantities` needs — a `Building`'s config, an `BmMass`, or a plain object.

```typescript theme={null}
interface MassLike {
  id: string;
  name?: string;
  elevation: number;
  segments: MassSegment[];
}
```

<ResponseField name="id" type="string" required />

<ResponseField name="name" type="string" />

<ResponseField name="elevation" type="number" required>
  World Y of the bottom face of `segments[0]`.
</ResponseField>

<ResponseField name="segments" type="MassSegment[]" required />

### ShellOptions

```typescript theme={null}
interface ShellOptions {
  wallThickness?: number;
  slabThickness?: number;
  roofThickness?: number;
  wallMaterial?: WallMaterial | string;
  color?: BmColor;
}
```

<ResponseField name="wallThickness" type="number">
  Default 0.3 m.
</ResponseField>

<ResponseField name="slabThickness" type="number">
  Default 0.25 m.
</ResponseField>

<ResponseField name="roofThickness" type="number">
  Default 0.25 m.
</ResponseField>

<ResponseField name="wallMaterial" type="WallMaterial | string" />

<ResponseField name="color" type="BmColor" />

## Related

* [`BmBuilding`](/floorkit/api/architecture/validate-building-model#bmbuilding)
* [`BmColor`](/floorkit/api/architecture/validate-building-model#bmcolor)
* [`BuildingCommand`](/floorkit/api/editor/pure-edits#buildingcommand)
* [`BuildingModel`](/floorkit/api/architecture/validate-building-model#buildingmodel)
* [`BuildingUse`](/floorkit/api/architecture/building#buildinguse)
* [`MassQuantities`](/floorkit/api/architecture/building#massquantities)
* [`MassSegment`](/floorkit/api/architecture/building#masssegment)
* [`PointXZ`](/floorkit/api/primitives/polygon-maths#pointxz)
* [`PolygonProfile`](/floorkit/api/primitives/polygon-maths#polygonprofile)
* [`ReplaceMassCommand`](/floorkit/api/editor/pure-edits#replacemasscommand)
* [`WallMaterial`](/floorkit/api/architecture/wall#wallmaterial)


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