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

# Viewport placement

> Fit a drawing into a viewport and convert between model and paper.

## Import

```typescript theme={null}
import {
  placeDrawing,
  viewportTransform,
  inverseViewportTransform,
  fitTransform,
  fitViewportScale,
  viewCenterOf,
  viewSourceToDrawingRequest,
  modelToPaper,
} from '@opengeometry/floorkit';
```

## placeDrawing

Place a viewport's `VectorDrawing` (model metres) into its `frame` (paper mm).

```typescript theme={null}
function placeDrawing(
  drawing: VectorDrawing,
  viewport: Viewport,
  policy?: SheetPolicy,
): PlacedDrawing;
```

## viewportTransform

The model→paper point transform for a viewport: model metres centred in the `frame` at `viewport.scale`, then rotated by `viewport.rotationDeg`.

```typescript theme={null}
function viewportTransform(drawing: VectorDrawing, viewport: Viewport): (point: Point2) => Point2;
```

## inverseViewportTransform

Inverse of viewportTransform: map a paper-mm point back to model metres for the same viewport.

```typescript theme={null}
function inverseViewportTransform(
  drawing: VectorDrawing,
  viewport: Viewport,
): (paper: Point2) => Point2;
```

## fitTransform

Compute the stage transform that fits a page into a viewport, centred.

```typescript theme={null}
function fitTransform(
  viewport: FitViewport,
  pageMm: {
    width: number;
    height: number;
  },
  { pixelsPerMm, padding, minScale, maxScale }: FitOptions,
): FitTransform | null;
```

## fitViewportScale

The scale and aim that fit a drawing inside a frame, snapped to a real scale.

```typescript theme={null}
function fitViewportScale(
  drawing: VectorDrawing,
  frame: Viewport['frame'],
  options?: {
    paddingMm?: number;
    system?: UnitSystem;
  },
): {
  scale: number;
  scaleId?: string;
  viewCenter: Point2;
};
```

## viewCenterOf

The model point that lands at the centre of the viewport's frame.

```typescript theme={null}
function viewCenterOf(drawing: VectorDrawing, viewport: Viewport): Point2;
```

## viewSourceToDrawingRequest

Map a viewport's `ViewSource` to a core DrawingRequest.

```typescript theme={null}
function viewSourceToDrawingRequest(
  source: ViewSource,
  options?: {
    cutElevation?: number;
    hideHidden?: boolean;
  },
): DrawingRequest;
```

## modelToPaper

Model length (metres) → paper length (millimetres) at a drawing scale.

```typescript theme={null}
function modelToPaper(modelMeters: number, scale: number): number;
```

## Types

### SheetPolicy

Resolved once per sheet (and again per viewport that names its own style).

```typescript theme={null}
interface SheetPolicy {
  style: PaperStyle;
  paperColor: string;
  ground: 'screen' | 'print' | 'both';
  sheetSalt: number;
  viewportTextInk: string;
  unresolved: string[];
}
```

<ResponseField name="style" type="PaperStyle" required>
  The flattened style: no `extends` left, every layer merged.
</ResponseField>

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

<ResponseField name="ground" type="'screen' | 'print' | 'both'" required />

<ResponseField name="sheetSalt" type="number" required>
  `hashString(sheet.id)` — the salt every hand stroke on this sheet shares.
</ResponseField>

<ResponseField name="viewportTextInk" type="string" required>
  Ink for model-anchored `drawing.texts`, which never pass through `penFor`.
</ResponseField>

<ResponseField name="unresolved" type="string[]" required>
  Style ids, `extends`, hatch keys and colours that could not be resolved. Warned once per sheet;
  the render falls back rather than failing.
</ResponseField>

### PlacedDrawing

A viewport's drawing mapped into paper space (mm), ready to emit.

The package does not export this type by name.

```typescript theme={null}
interface PlacedDrawing {
  primitives: DrawingPrimitive[];
  readonly lines: VectorLine[];
  texts: VectorText[];
  clip?: {
    x: number;
    y: number;
    width: number;
    height: number;
  };
  pen?: PenContext;
}
```

<ResponseField name="primitives" type="DrawingPrimitive[]" required>
  Standardized primitives in paper mm, with lineweight resolved.
</ResponseField>

<ResponseField name="lines" type="VectorLine[]" required />

<ResponseField name="texts" type="VectorText[]" required />

<ResponseField
  name="clip"
  type="{
x: number;
y: number;
width: number;
height: number;
}"
>
  Clip rectangle (the viewport frame) when `viewport.clip` is set.
</ResponseField>

<ResponseField name="pen" type="PenContext">
  The style context the primitives were resolved under.
</ResponseField>

### FitViewport

Viewport dimensions in screen pixels.

```typescript theme={null}
interface FitViewport {
  width: number;
  height: number;
}
```

### FitOptions

```typescript theme={null}
interface FitOptions {
  pixelsPerMm: number;
  padding: number;
  minScale: number;
  maxScale: number;
}
```

<ResponseField name="pixelsPerMm" type="number" required>
  Layer scale — how many screen pixels one paper millimetre occupies at 1×.
</ResponseField>

<ResponseField name="padding" type="number" required>
  Fraction of the viewport to fill, leaving breathing room.
</ResponseField>

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

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

### FitTransform type

The stage transform that frames a page: uniform scale plus a top-left offset.

```typescript theme={null}
interface FitTransform {
  scale: number;
  x: number;
  y: number;
}
```

## Related

* [`DrawingPrimitive`](/floorkit/api/drawings/draw-project-view#drawingprimitive)
* [`DrawingRequest`](/floorkit/api/drawings/draw-project-view#drawingrequest)
* [`PaperStyle`](/floorkit/api/drawings/sheet-documents#paperstyle)
* [`PenContext`](/floorkit/api/drawings/pens-and-hatches#pencontext)
* [`Point2`](/floorkit/api/annotations/dimension-geometry#point2)
* [`UnitSystem`](/floorkit/api/annotations/dimension-geometry#unitsystem)
* [`VectorDrawing`](/floorkit/api/drawings/draw-project-view#vectordrawing)
* [`VectorLine`](/floorkit/api/drawings/draw-project-view#vectorline)
* [`VectorText`](/floorkit/api/drawings/draw-project-view#vectortext)
* [`Viewport`](/floorkit/api/drawings/sheet-documents#viewport)
* [`ViewSource`](/floorkit/api/drawings/sheet-documents#viewsource)


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