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

# Dimension strings

> Make overall, chain and facade dimension strings for a drawing.

These functions make the dimension annotations of a drawing. `overallDimensions` gives the full width and the full height. The other functions give a string of dimensions along an edge or a facade.

## Import

```typescript theme={null}
import {
  overallDimensions,
  chainDimensions,
  facadeDimensions,
  facadeDimensionExtent,
  facadeRuns,
} from '@opengeometry/floorkit';
```

## Example

```typescript theme={null}
import {
  overallDimensions,
  type VectorDrawing,
  type Viewport,
  type Sheet,
} from '@opengeometry/floorkit';

export function addOverallDimensions(
  drawing: VectorDrawing,
  viewport: Viewport,
  sheet: Sheet,
): void {
  sheet.annotations.push(
    ...overallDimensions(drawing, viewport, {
      offset: 8,
      fontSize: 2.5,
      precision: 0,
    }),
  );
}
```

## Notes

* Model points are in metres. Offsets and text sizes are in paper millimetres.
* The dimensions keep the points that the drawing had at the time of the call. Make them again after the model changes.
* Replace the old annotations when you make new ones. This prevents duplicate ids.

## overallDimensions

Overall width + height measures from the drawing's **real model extents** (its bounds).

```typescript theme={null}
function overallDimensions(
  drawing: VectorDrawing,
  viewport: Viewport,
  options: MeasureOptions,
): MeasureAnnotation[];
```

## chainDimensions

An **exterior dimension chain** along one edge of the drawing — the running string of measurements an issued plan carries outside its façade, breaking at each wall junction and each opening jamb.

```typescript theme={null}
function chainDimensions(
  drawing: VectorDrawing,
  viewport: Viewport,
  options: ChainOptions,
): MeasureAnnotation[];
```

## facadeDimensions

One dimension string per exterior run, offset to the OUTSIDE of the plan.

```typescript theme={null}
function facadeDimensions(
  storey: DimensionableStorey,
  viewport: Viewport,
  options: FacadeDimensionOptions,
): MeasureAnnotation[];
```

## facadeDimensionExtent

The outermost paper offset `facadeDimensions` will use, so a caller can place the overall dimension beyond it.

```typescript theme={null}
function facadeDimensionExtent(
  storey: DimensionableStorey,
  viewport: Viewport,
  options: FacadeDimensionOptions,
): number;
```

## facadeRuns

The straight runs of exterior wall, each with the stations a dimension string breaks at.

```typescript theme={null}
function facadeRuns(
  storey: DimensionableStorey,
  options?: {
    minRun?: number;
    exteriorPset?: [string, string];
    checkRooms?: boolean;
    onDropped?: (dropped: FacadeDropped) => void;
  },
): FacadeRun[];
```

## Types

### MeasureOptions

The package does not export this type by name.

```typescript theme={null}
interface MeasureOptions {
  offset: number;
  fontSize: number;
  precision?: number;
  idPrefix?: string;
}
```

<ResponseField name="offset" type="number" required>
  Perpendicular offset of the dimension line, in paper mm.
</ResponseField>

<ResponseField name="fontSize" type="number" required>
  Label height, in paper mm.
</ResponseField>

<ResponseField name="precision" type="number">
  Decimal places on the millimetre value. Default 0.
</ResponseField>

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

### MeasureAnnotation

A viewport-linked dimension: `from`/`to` are saved points in the viewport's **model** space (metres).

```typescript theme={null}
interface MeasureAnnotation {
  id: string;
  kind: 'measure';
  styleId?: string;
  viewportId: string;
  from: Point2;
  to: Point2;
  offset: number;
  fontSize: number;
  precision?: number;
  label?: string;
}
```

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

<ResponseField name="kind" type="&#x22;measure&#x22;" required />

<ResponseField name="styleId" type="string">
  Named style in `PaperDocument.dimensionStyles`. Absent uses the default.
</ResponseField>

<ResponseField name="viewportId" type="string" required>
  Viewport whose drawing + transform resolve this dimension.
</ResponseField>

<ResponseField name="from" type="Point2" required />

<ResponseField name="to" type="Point2" required />

<ResponseField name="offset" type="number" required>
  Perpendicular offset of the dimension line, in paper mm.
</ResponseField>

<ResponseField name="fontSize" type="number" required>
  Label height, in paper mm.
</ResponseField>

<ResponseField name="precision" type="number">
  Decimal places on the measured mm value. Default 0.
</ResponseField>

<ResponseField name="label" type="string">
  Optional label override; default = measured model distance in mm.
</ResponseField>

### ChainOptions

The package does not export this type by name.

```typescript theme={null}
interface ChainOptions extends MeasureOptions {
  along: ChainEdge;
  band?: number;
  tolerance?: number;
  minSpan?: number;
}
```

<ResponseField name="along" type="ChainEdge" required>
  The edge the chain runs along.
</ResponseField>

<ResponseField name="band" type="number">
  Depth searched inward from that edge, in metres. Only geometry reaching into this band contributes
  a breakpoint, so a chain measures the façade it sits against rather than every wall on the floor.
  Default 1.0 — one band comfortably deeper than the thickest wall in the Swiss Dwellings sample
  (0.91 m).
</ResponseField>

<ResponseField name="tolerance" type="number">
  Breakpoints closer together than this (metres) are one breakpoint. Default 0.02.
</ResponseField>

<ResponseField name="minSpan" type="number">
  A link shorter than this (metres) is dropped, folding into its neighbour: a 2 cm jamb return is a
  construction detail, not a dimension. Default 0.05 — deliberately BELOW the kernel's 0.10 m
  minimum wall, so every wall the model can express still earns its own dimension. Raise it past
  0.10 and a chain silently swallows every partition, which is how a dimensioned drawing loses its
  partitions.
</ResponseField>

### DimensionableStorey

The package does not export this type by name.

```typescript theme={null}
interface DimensionableStorey {
  walls?: DimensionableWall[];
  spaces?: DimensionableSpace[];
}
```

<ResponseField name="walls" type="DimensionableWall[]" />

<ResponseField name="spaces" type="DimensionableSpace[]">
  Rooms, used to confirm a wall really is on the façade — see `outerSideIsOpen`.
</ResponseField>

### FacadeDimensionOptions

The package does not export this type by name.

```typescript theme={null}
interface FacadeDimensionOptions extends MeasureOptions {
  minRun?: number;
  onDropped?: (dropped: FacadeDropped) => void;
  exteriorPset?: [string, string];
}
```

<ResponseField name="minRun" type="number">
  Ignore runs shorter than this, in metres. Default 0.6 — a doorway. A 1.5 m floor dropped
  `s24485-w6`, a 1225 mm façade WITH a window in it.
</ResponseField>

<ResponseField name="onDropped" type="(dropped: FacadeDropped) => void">
  Called for every façade left undimensioned, so a caller can report it rather than let it vanish.
</ResponseField>

<ResponseField
  name="exteriorPset"
  type="[
string,
string
]"
>
  Which pset flags an exterior wall.
</ResponseField>

### FacadeDropped

Why a façade was not dimensioned.

The package does not export this type by name.

```typescript theme={null}
interface FacadeDropped {
  wallId?: string;
  reason: 'too-short' | 'room-behind' | 'not-tagged' | 'illegible';
  detail: string;
}
```

### FacadeRun

The package does not export this type by name.

```typescript theme={null}
interface FacadeRun {
  wallId?: string;
  start: Point2;
  end: Point2;
  length: number;
  stations: number[];
  openings: number;
  thickness: number;
}
```

<ResponseField name="wallId" type="string">
  The wall this run belongs to.
</ResponseField>

<ResponseField name="start" type="Point2" required>
  Run ends in drawing space — `BmWall` points are world XZ and the drawing maps `&#123;x, y:
      z&#125;`.
</ResponseField>

<ResponseField name="end" type="Point2" required />

<ResponseField name="length" type="number" required>
  True length along the run, in metres.
</ResponseField>

<ResponseField name="stations" type="number[]" required>
  Ascending stations along the run, always beginning at 0 and ending at `length`.
</ResponseField>

<ResponseField name="openings" type="number" required>
  How many openings put jambs on this run.
</ResponseField>

<ResponseField name="thickness" type="number" required>
  The wall's thickness, so a caller can clear the dimension line off the FACE rather than the
  centreline — otherwise clearance shrinks as walls get thicker.
</ResponseField>

### ChainEdge

Which edge of the drawing a dimension chain runs along.

The package does not export this type by name.

```typescript theme={null}
type ChainEdge = 'top' | 'bottom' | 'left' | 'right';
```

### DimensionableWall

The package does not export this type by name.

```typescript theme={null}
interface DimensionableWall {
  id?: string;
  points: Array<[number, number]> | Point2[];
  closed?: boolean;
  thickness: number;
  openings?: DimensionableOpening[];
  psets?: Record<string, Record<string, unknown>>;
}
```

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

<ResponseField
  name="points"
  type="Array<[
number,
number
]> | Point2[]"
  required
/>

<ResponseField name="closed" type="boolean">
  A closed wall's last segment runs from the final point back to the first.
</ResponseField>

<ResponseField name="thickness" type="number" required />

<ResponseField name="openings" type="DimensionableOpening[]" />

<ResponseField name="psets" type="Record<string, Record<string, unknown>>" />

### DimensionableSpace

The package does not export this type by name.

```typescript theme={null}
interface DimensionableSpace {
  profile?: {
    outerRing?: Array<[number, number]> | Point2[];
  };
  type?: string;
  psets?: Record<string, Record<string, unknown>>;
}
```

<ResponseField
  name="profile"
  type="{
outerRing?: Array<[
number,
number
]> | Point2[];
}"
/>

<ResponseField name="type" type="string">
  Room type, if known. An OUTDOOR type behind a wall does not make it internal.
</ResponseField>

<ResponseField name="psets" type="Record<string, Record<string, unknown>>" />

### DimensionableOpening

The subset of `BmStorey` this needs.

The package does not export this type by name.

```typescript theme={null}
interface DimensionableOpening {
  offset: number;
  width: number;
  frameWidth?: number;
}
```

<ResponseField name="offset" type="number" required />

<ResponseField name="width" type="number" required>
  CLEAR opening, between the frames — not the hole in the wall.
</ResponseField>

<ResponseField name="frameWidth" type="number">
  Frame on each side. The structural opening is `width + 2 * frameWidth`. ABSENT IS NOT ZERO: the
  kernel cuts the void at `frameWidth ?? DEFAULT_FRAME_WIDTH` (0.05), so treating an absent frame as
  0 reproduces exactly the 100 mm error this module was fixed for — just on documents that do not
  spell the frame out.
</ResponseField>

## Related

* [`Point2`](/floorkit/api/annotations/dimension-geometry#point2)
* [`VectorDrawing`](/floorkit/api/drawings/draw-project-view#vectordrawing)
* [`Viewport`](/floorkit/api/drawings/sheet-documents#viewport)


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