Background Image Calibration

Background Image with Two-point Calibration

When you start from a photo, a floor plan, or a hand-drawn sketch, you can import it as a background image and trace your geometry on top of it. The two-point calibration tool sets the real-world scale of the image so the lines you draw over it carry correct millimetre dimensions.

Feature line from the README: 🖼️ Background image import with two-point calibration.

Importing a background image

1. Open a project.
2. Use File → Import (or drag a PNG / JPG onto the canvas — the handler converts it to a project-local blob).
3. The image is added as a BackgroundImageRef with:
   • A unique id, either a dataUrl or a blobKey (for large images stored in IndexedDB).
   • A world-space position (mm) and rotationDeg.
   • A scaleMmPerPx (initialised to 1 mm/px — that is not accurate yet; calibration fixes that).
   • opacity01, locked and visible toggles.

The image is rendered behind everything else on the canvas. While locked is on, you cannot accidentally drag or resize it from the Select tool.

Two-point calibration

The image is just a raster — the planner has no idea how many millimetres one pixel represents until you tell it. The Calibrate background image tool turns any known segment (door width, ruler in the photo, a printed scale bar…) into the source of truth.

How to calibrate:

1. With a background image present, activate Calibrate background image from the toolbox.
2. Click the first endpoint of a real-world segment on the image.
3. Click the second endpoint.
4. A prompt asks for the real distance (accepts 2400, 2.4 m, 8 ft — the standard parseLength parser is used).
5. The image is re-scaled and re-positioned so that the midpoint of the two clicked points stays anchored. After calibration, every existing shape on the canvas keeps its real-world position; only the image moves and resizes around the anchor.

The math (calibrateImage):

pixelDistance  = hypot(B.x − A.x, B.y − A.y)
newScale       = realDistanceMm / pixelDistance
// Keep midpoint of A/B stationary after rescaling:
midPx          = (A + B) / 2
worldMid       = image.position + midPx * image.scaleMmPerPx
image.position = worldMid − midPx * newScale

The previous scaleMmPerPx is replaced and the calibration data is stored (pointAPx, pointBPx, distanceMm) so you can revisit or re-run the operation at any time.

Working with the image

After calibration:

• The Line, Rectangle, Polygon and Surface tools can trace directly over the image with accurate dimensions.
• Toggle opacity to fade the image while you focus on the drawing.
• Toggle lock to prevent accidental moves; uncalibrated or uncalibrated-yet images can be repositioned with the Select tool.
• Toggle visibility to hide the image entirely for clean presentations.

Where this lives in the codebase

• Schema — src/types/backgroundImage.ts
• Calibration math — src/domain/backgroundImage/calibrateImage.ts
• Canvas layer — src/features/editor/canvas/LayersRoot.tsx
• Tool entry — calibrateImage entry in src/features/info/infoEntries.ts

Related pages

• 2D Drawing Tools
• Surfaces, Openings and Connections