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.
136 lines
6.2 KiB
Markdown
136 lines
6.2 KiB
Markdown
# 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).
|