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