# The floor map: buildings, levels and marker positions

The map shows where things physically are. This page is for whoever maintains it:
loading a floor plan, adding a second floor or a second building, and moving the
markers when the plan changes.

The reasoning behind the model is in
[ADR-017](adr/ADR-017-buildings-and-levels.md). This page is the operator's view.

## The model in three sentences

A **building** holds one or more **levels**. A level owns a floor-plan image (one
per theme) and the pixel size of that image. A marker's position is an X and Y in
the pixels of ONE level, so every position names the level it belongs to.

That last point is the whole design. Coordinates alone are meaningless: `1200,900`
is a spot on the ground floor and a different spot on the second floor. A marker
whose level is unknown shows as **level unknown** and is not drawn, because
drawing it on the default plan would look completely correct while pointing at
the wrong part of the building.

## Loading a floor plan

**Settings > Buildings and levels.**

1. Add a building if you do not have one. A single-building site needs exactly
   one, and it can be called anything.
2. Add a level. Give it a name people use out loud - "Ground floor", "Mezzanine",
   "Second floor" - and a sort order that puts the list in the order someone
   would walk it. Name and order are separate on purpose: levels are not reliably
   numbered, and leaving gaps in the order lets you insert one later without
   renumbering everything.
3. Upload the plan, per theme. A light-theme image is enough to start; if there
   is no dark version, the light one is used in both.

**The level takes its pixel size from the image you upload, while the level is
still empty.** Once markers are on it, an upload whose size does not match reports
the mismatch and changes nothing. That is deliberate - see below.

Supported: PNG, JPEG, GIF, WEBP and SVG. An SVG is served with headers that stop
it executing as script, so a plan exported from a CAD tool is safe to use.

## Placing markers

Two ways, both fine:

- **One at a time**, from the asset's own form: the map-position picker opens on
  the level the marker is already on, and you can switch level inside the picker.
  The saved position states which drawing it is on.
- **Many at once**, in the map editor. Filter to what you are working through -
  unplaced, needs-review, or one level - search for a specific thing, place it,
  and confirm. Placing a marker by hand counts as confirming it.

A location can carry a position too, which acts as the default for assets in it.

## When the floor plan changes

This is the case that needs care, and the reason the tooling exists.

**A new plan of the SAME dimensions**: upload it and you are done. Markers keep
their coordinates and still line up.

**A new plan of DIFFERENT dimensions, or a real move**: the coordinates are pixels
of the old image, so every marker is now in the wrong place relative to the
drawing. Do NOT fix this by editing the level's width and height - that just
reinterprets every existing position against a new scale.

Use **Recalibrate** in the map editor:

1. Pick two or more **landmarks** - features you can find on both the old and the
   new plan. Corners of the building, a doorway, a column. Two is the minimum;
   three or four spread across the plan is better.
2. For each, give the old coordinates and the new ones.
3. Review the **dry run**. It lists every marker's old and new position and flags
   anything that would land off the drawing. Nothing has changed yet.
4. Apply it. The previous positions are snapshotted first.

The transform is worked out separately for the X and Y axes from your landmarks,
and never guessed from the image dimensions. That matters in the exact case this
was built for: a plan that gained a floor below it got taller without anything
being rescaled, and a size-derived scale would have stretched everything
vertically.

After a recalibration every affected marker is marked **needs review**, because a
transform is a good starting guess and nothing in the coordinates can tell you
which machines actually moved. Work the needs-review filter, correct what is off,
and confirm as you go.

## Undo

Every bulk change snapshots the positions first, and a restore snapshots before
it restores, so an undo is itself undoable. The history is in the map editor:
what caused each snapshot, when, and whether it has been restored. A restore puts
back the level and the review state, not only the coordinates.

Assets deleted since a snapshot are reported and skipped rather than failing the
whole restore.

## Adding a second building or a second floor

Add it, upload its plan, then move the markers that belong on it. In the map
editor, markers on other levels are badged, so you can see what still needs
moving.

Do not stack two floors onto one tall image. It looks simpler and it makes the
level implicit in the Y coordinate - "above 2550 means upstairs" - which nothing
can validate and which breaks the moment either plan is redrawn.

## Things that are not levels

- **Locations** are where something is in words ("Cell 4", "Gage lab"). A level is
  which drawing. A location can name a level, but they are different things.
- **Business units** are organisational, not physical.

## Known limits

- The printer-installer map (the standalone program that installs printers by
  clicking a floor plan) has one plan compiled into it and does not know about
  levels. It is accurate for the default level only. See
  [PRINTER-INSTALLER](PRINTER-INSTALLER.md) section 6.
- The first-run setup wizard still asks for one site-wide blueprint; those
  settings no longer drive the map. Use Settings > Buildings and levels.
- Map PDF export covers the level you are looking at.

## For integrators

`GET /api/maplevels` is unauthenticated - the printer installer draws a plan
before anyone logs in - and returns every building with its levels, each level's
blueprint paths, native size and marker count, plus which level is the default.
Writes require an admin. Repositioning is `/api/mappositions/*` and needs
`assets.edit`. Full parameters in [API-REFERENCE](API-REFERENCE.md) and the
generated spec at `/api/docs`.

If you import positions from another system, send `levelid` with every
coordinate - see [IMPORT-API](IMPORT-API.md).
