741dda5be7
The 0.11.0 release changed what a map position means and six documents still described the model it replaced. Each of these could have caused a real mistake rather than being merely out of date: - IMPORT-API mapped legacy mapleft/maptop to mapx/mapy with no mention of the level, so a scripted import - including the classic-ASP one still to run against production - would have produced markers the map shows as "level unknown". It now maps levelid too and says how to resolve the default level. - API-REFERENCE enumerates the unauthenticated surface in full, because that is what a deploy reviewer reads, and the three public /api/maplevels reads were missing from it. Also records why the write split is asymmetric: repositioning needs assets.edit, creating a level needs admin, since a level's dimensions are the coordinate space every marker on it is expressed in. - CONFIG still presented the four map_* settings as live, telling the reader to re-upload a blueprint in a settings page that no longer drives the map. They are marked superseded and kept for downgrade. - UPGRADE gained a 0.11.0 section: nothing moves on screen, and replacing a blueprint with one of different dimensions moves every marker on that level, so recalibrate from landmarks rather than editing width and height. - PLUGIN-HOOKS now states that a map overlay keys on assetid and must not return coordinates or a level - a second copy of a position is one that can disagree. Adds FLOOR-MAP.md, the operator's page: loading a plan, placing markers, and what to do when the plan changes, with the reasoning left in ADR-017. START-HERE routes to it from the new-site path, and specifically as the page to read BEFORE a floor plan changes.
6.2 KiB
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. 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.
- Add a building if you do not have one. A single-building site needs exactly one, and it can be called anything.
- 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.
- 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:
- 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.
- For each, give the old coordinates and the new ones.
- 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.
- 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 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 and the
generated spec at /api/docs.
If you import positions from another system, send levelid with every
coordinate - see IMPORT-API.