README.md

floor_plan version 1.0 · 5 KB

1	# Floor plan: a LocalEye custom module
2
3	A map of your building you can click - an office, a shop, a school, a warehouse, a house. Put the floor plan in, draw the
4	rooms, doors, aisles and other areas (Lobby, Receiving...), and place each camera with the way it points and how far it sees. Then anyone signed in can:
5
6	- click an area to watch every camera that covers it, live, side by side, with a link to each camera's recording at a
7	time you pick ("Receiving at 2:15 PM yesterday");
8	- click a camera to watch it;
9	- see areas and cameras glow while a camera sees motion.
10
11	People only see the cameras they're allowed to see (Settings → Users → Cameras). It works through localeye.cam remote access too.
12
13	## Install
14
15	1. Copy this `floor_plan` folder into the NVR's `custom-modules/` folder:
16	- Debian / Linux: `/opt/localeye/custom-modules/floor_plan/`, then `sudo chown -R nvr:nvradmin /opt/localeye/custom-modules`
17	- Windows: `C:\localeye\custom-modules\floor_plan\`
18	2. Settings → Modules → Floor plan → enter your password → Trust & load (from the NVR's own network, not through
19	localeye.cam). Or on the server: `venv/bin/python manage.py custom-modules trust floor_plan`, then restart `localeye-web`.
20	3. Switch it on. Map appears in the menu.
21
22	### Had it as "Warehouse map"?
23
24	This is the same module under a new name (id `floor_plan`, was `warehouse_map`). Copy the `floor_plan` folder in, **delete the
25	old `warehouse_map` folder**, then Trust & load and switch on Floor plan. The first time it starts it brings your maps over
26	(from the old `warehouse_maps` table, which is then left empty) and copies their floor plan pictures from
27	`data/custom-modules/warehouse_map/plans/` (that old folder is left alone - delete it once the maps look right).
28
29	## Making the map (admins)
30
31	Map → Make the first map → ✎ Edit map:
32
33	- 🖼 Floor plan…: a PNG, JPEG or WebP picture of the floor plan (up to 25 MB). Got a PDF or a CAD drawing? Export or
34	screenshot it as a picture first. You don't need it to start: draw now, add the plan later - everything keeps its place
35	relative to the map.
36	- ▭ Area: drag a rectangle (a room, an aisle). ⬠ Shape: click each corner of an odd-shaped area, then the first
37	corner again (or Enter). Click an area to name it, colour it, move it (drag) or reshape it (drag its corners).
38	- 📷 Camera: pick the camera on the right, click where it's mounted, then drag its round handle to point it - the further
39	you drag, the further it sees. "Sees across" sets how wide its view is. View-only cameras (they don't record) can go on the
40	map too: they show live, without a recording link. (Needs an NVR from 2026-10-16 or later; older ones list only recording cameras.)
41	- Snap (on by default): corners and sides snap onto other areas' edges and the map's border (a dashed line shows it),
42	otherwise onto a grid that gets finer as you zoom in. Hold Alt to place something freely. A ▭ area stays a rectangle:
43	drag a corner to resize it, the square handle in the middle of a side to move just that side. A crooked 4-corner area
44	has ▭ Square it up.
45	- Label: an area's name runs across; a tall, narrow area (racks, a lane) turns it sideways by itself (Auto), or choose
46	Across, Sideways, reading up or reading down. A name longer than its area shrinks a little to fit.
47	- An area's cameras are the ones whose view reaches into it. If that's not right (a wall in the way), choose Pick them myself.
48	- Save (Ctrl+S). ↶ Undo (Ctrl+Z), Delete key removes what's picked, Esc stops drawing. If someone else saved the same map
49	while you were editing, Save says so instead of overwriting their work.
50
51	Several maps (buildings, floors, the yard): + New map, then choose one at the top.
52
53	## Files
54
55	\| File \| What \|
56	\|---\|---\|
57	\| `module.yaml` \| name, the `floor_plans` table (and `warehouse_maps`, only to bring old maps over), everyone can use it (admins edit), remote: true \|
58	\| `module.py` \| the page (`/x/floor_plan/`), the floor plan picture (`/x/floor_plan/plan/<id>`) and the API (`/api/x/floor_plan/maps...`) \|
59	\| `mapdata.py` \| what a map may contain (checked before saving) and reading a picture's type and size \|
60	\| `templates/map.html`, `static/map.js`, `static/map.css` \| the page \|
61
62	Floor plan pictures are kept in the module's data folder (`data/custom-modules/floor_plan/plans/`), the maps in the
63	`floor_plans` table; both survive NVR updates. Updating the module: replace the files, then trust it again.
64
65	Test: `JP Spy Modules/tests/floor_plan_test.py` (run from the `JP Spy Modules` folder; `LOCALEYE_DIR` if the NVR code isn't at `../JP Spy System`).