feat(skills): add pdf room tracing and wall openings skills

2026-10-31 15:39:28 +03:00
parent c75bb03b24
commit fa9dd03d12
6 changed files with 90 additions and 7 deletions
@@ -1,6 +1,6 @@
 {
  "name": "shd-mcp-plugin",
-  "version": "0.5.2",
+  "version": "0.5.4",
  "description": "Ready-to-install SHD workflows backed by the authenticated SHD MCP server.",
  "author": {
    "name": "SHD",
@@ -34,14 +34,17 @@
    "Omni",
    "admin",
    "PDF Scheme Editor",
+    "PDF room tracing",
    "Gitea",
-    "MCP"
+    "MCP",
+    "PDF wall tracing",
+    "PDF openings"
  ],
  "skills": "./skills/",
  "interface": {
    "displayName": "SHD MCP",
    "shortDescription": "SHD projects and operations",
-    "longDescription": "Installable SHD MCP workflows for projects, ProjectBase, AirBase records and dashboards, AI-computed fields, registered Omni actions, Knowledge, guarded project editing, read-only repository inspection, tasks, files, finance, CRM, documents, service catalog, short links, profile, access control, Grafana, Zulip, inventory, notifications, realtime, status monitoring and linked Gitea operations and PDF Scheme Editor plan geometry.",
+    "longDescription": "Installable SHD MCP workflows for projects, ProjectBase, AirBase, Knowledge, tasks, documents, finance, CRM, inventory, analytics, service operations, Grafana, Zulip and linked Gitea; PDF Scheme Editor plan geometry with focused room and wall/window/door tracing.",
    "developerName": "SHD",
    "category": "Productivity",
    "capabilities": [
@@ -49,7 +49,9 @@ SHD scope.
 - short-link, public-alias, rotation and revocation workflows;
 - authenticated profile workflows;
 - agent/controller diagnostics, tunnels, endpoints and runtime actions;
- PDF Scheme Editor plan geometry, rooms, walls, openings, annotations, calibration and lighting-layer workflows;
+- PDF Scheme Editor plan geometry, including focused room tracing and wall, window
+  and door tracing around wall faces, thresholds, columns, boxes, niches and openings,
+  plus annotations, calibration and lighting-layer workflows;
 - status-page monitors, groups, history and incidents;
 - realtime sessions, event cursors and operational activity;
 - Terms documents, revisions, completeness and contract discussions;
@@ -0,0 +1,31 @@
+---
+name: shd-pdf-room-tracing
+description: Trace, review, and correct room polygons from architectural PDF plans in SHD PDF Scheme Editor, especially around wall thickness, door thresholds, columns, boxes, and convector niches.
+metadata: modules=pdf-scheme-editor
+---
+
+# Trace rooms from architectural PDFs
+
+Produce room polygons that follow the room-facing side of the drawn boundaries. Read the source PDF for geometry; existing room annotations are evidence to review, not geometry to copy unless the user explicitly asks for a copy.
+
+## Work from the drawing
+
+- Make one overview pass: render the full plan once, then call `shd_analyze_pdf_scheme_editor_vectors` once for the page to get style groups and paths. Build a checklist of turns, junctions, columns, boxes, convectors, and doors from that data. Inspect a high-resolution crop only for an item the vector data does not settle, with a budget of at most 4 crops per room unless a semantic check fails. Prefer PDF vector paths and dimensions; use the rendered page to identify which side of each line is room interior.
+- Use explicit scale calibration from a printed dimension. Keep PDF page coordinates throughout tracing.
+- Trace the actual outline, including concave, angled, stepped, and recessed parts. Do not simplify a contour into a rectangle when the drawing shows a recess, box, column, or niche.
+- Follow the room-facing boundary of wall bands. A room may touch a wall boundary; it must not cover the wall band. Include the open floor area around a convector/radiator when the drawing shows a room-side niche, and follow the niche edges around the device. Do not infer that every heater creates a niche.
+- Treat a door opening as a shared threshold between the two spaces it connects. At each interior doorway, use one exact threshold segment on both adjacent room polygons and check that both polygons contain the full segment. Keep the wall thickness on either side of the opening outside the rooms. On an exterior entrance, stop at the inside threshold face and keep the exterior landing outside the corridor; floor under an inward-opening door swing still belongs to the corridor.
+- Before tracing, enumerate every convector/radiator visible on the source page from the vector analysis and the overview render, not from a crop per device. For each one, check the full device footprint and the entire vector-defined room-side window recess, including side and end strips around the device; a heater bounding box is not the niche boundary. Do not leave a blank gap under or behind the device. If room boundaries divide a long heater niche, assign each segment to the room it opens into and check the union for gaps.
+- Trace a box, shaft, or column as an indentation in the adjacent room boundary. Do not fill its footprint or create a separate room for it. Verify a sample point inside the box is outside the room polygon and a point just beyond it is inside.
+- At the entrance, verify points just inside the threshold are in the corridor and points on the exterior landing are outside all room polygons. Never let a room contour follow the door leaf or swing arc, and do not carve out interior floor merely because the door swing passes over it.
+- Preserve openings between rooms as boundary thresholds. Do not use dimension lines, text leaders, furniture, devices, door arcs, or annotation overlays as room edges.
+
+## Use the SHD tracing tools safely
+
+- Use `shd_analyze_pdf_scheme_editor_vectors` to inspect vector styles and exact path coordinates. A style group is only a visual clue; confirm it against the rendered source before using it as a wall.
+- Use `shd_trace_pdf_scheme_editor_room_candidates` to evaluate fresh room hints against the PDF wall vectors. Supply room seeds only in clear interior floor areas. Supply an apartment `allowed_polygon` when the outer boundary or entrance could be confused with room interior.
+- If a boundary hint leaves the allowed apartment footprint, intersects itself, overlaps another room, or cannot be related to the drawing, correct it before saving. A geometrically valid polygon is not proof that it matches the PDF.
+- Inspect a source overlay after tracing. Confirm every segment against its local crop, including wall-facing side, thresholds, recessed convectors, structural columns/boxes, and the entrance. Use room area labels as a consistency check, not as a substitute for the drawn outline.
+- When useful, pass `room_inclusion_regions` for the full vector-defined room-side convector recess or other floor areas that must belong to a room, and `room_exclusion_regions` for the exterior landing, wall thickness, column, or box footprint. Take these regions from the analysis results of the same page and document revision, not from repeated renders. Pass `room_shared_boundaries` for each known interior doorway so the tool can catch a one-sided offset or gap. Treat failed semantic checks as a stop condition. Keep a short per-room boundary review and inspect the full apartment overlay plus close-ups before mutating the document.
+- Reuse results. Analysis, room trace, and preview results are cached per document revision. Do not repeat `shd_analyze_pdf_scheme_editor_vectors` for a page you already analysed, and do not request a preview of an area you already checked with the same parameters.
+- For a requested fresh trace, do not copy room polygons from another document. Remove only the specifically authorized room records, keep unrelated annotation types, then add the new room polygons with fresh IDs and optimistic revisions. Re-read and inspect the saved result.
@@ -1,6 +1,6 @@
 ---
 name: shd-pdf-scheme-editor
-description: Use when reading or editing PDF plans, room boundaries, walls, windows, doors, points, cleanup masks, drawings, comments, legends, layers, calibration or lighting links in SHD PDF Scheme Editor.
+description: Use for general SHD PDF Scheme Editor document operations, annotations, calibration, lighting layers and plan review. For room tracing use shd-pdf-room-tracing; for wall, window and door recognition or tracing use shd-pdf-wall-openings.
 metadata: modules=pdf-scheme-editor
 ---

@@ -16,15 +16,19 @@ metadata: modules=pdf-scheme-editor

 ## Trace room boundaries from the drawing

+For detailed room tracing and geometry review, use the focused shd-pdf-room-tracing skill; this section provides the editor-specific tools and data contract.
+
 - Before tracing, call `shd_preview_pdf_scheme_editor_room_boundary` for the full page at `level=z100`. Use the returned page width and height as the coordinate limits; coordinates have a top-left origin and use PDF Scheme Editor page-local units.
 - Zoom in on difficult corners, wall thicknesses, offsets, and built-ins by requesting a smaller crop with `level=z475` or `level=z650`. The crop coordinates use the same page space as room `points`.
- Send a proposed polygon as `preview_points` to see its blue outline over the source image. Revise the polygon until every segment follows the room boundary and excludes wall thickness. When the user says a convector recess belongs to the room, include the complete recess and convector inside the outline; for this Prime Park plan, apply that rule to every room.
+- Send a proposed polygon as `preview_points` to see its blue outline over the source image. Revise the polygon until every segment follows the room boundary and excludes wall thickness. Include a convector and its surrounding floor recess in the room only when the source drawing shows that the recess is part of the room; check each convector independently and do not assume that every heater creates a niche.
 - Compare the preview tool's calibrated `polygon_area_m2` with the room area printed on the plan. If it differs materially, recheck missed recesses, wall thickness, and the calibration endpoints before saving.
 - Preview is read-only. Do not save a proposed room until its whole boundary has been checked against the source image; use the typed room tool for the actual write, then read back and preview the saved points.
 - For complex or stepped rooms, follow each turn of the boundary with separate vertices. Do not replace a concave room with a rectangle or split one room into separate records unless the user asks for that split.

 ## Recognize wall regions and openings

+For focused wall, window, and door recognition and tracing, use `shd-pdf-wall-openings`; this section retains the editor-specific tools and data contract.
+
 - A `wall` annotation is a filled wall-area polygon, not a centerline. Read the plan itself and follow the wall faces, including the exterior perimeter, rather than inferring every wall from room outlines alone.
 - For vector PDFs, call `shd_analyze_pdf_scheme_editor_vectors` and inspect both fill and stroke style groups. Preview candidate groups with `shd_preview_pdf_scheme_editor_vector_style`; styles are visual evidence, not semantic labels. Confirm hatch, paired faces, junctions and openings against high-resolution page crops before tracing.
 - The editor's Build Walls action generates a complement between room polygons and an exterior band with a configured thickness. It is a geometric fallback, not PDF wall recognition; it may approximate angled or irregular boundaries with rectangles. Use it only as a proposal and compare it with the actual drawing.
@@ -0,0 +1,42 @@
+---
+name: shd-pdf-wall-openings
+description: Trace and review wall regions and window or door openings from architectural PDFs in SHD PDF Scheme Editor. Use for recognizing, adding, or correcting walls, columns that form wall regions, windows, hinged doors, and sliding doors; use shd-pdf-room-tracing for room polygons.
+metadata: modules=pdf-scheme-editor
+---
+
+# Trace walls and openings from architectural PDFs
+
+Create wall and opening polygons that match the source drawing and fit the existing room geometry. The tools provide vector candidates and geometric checks; they do not semantically recognize every wall, window, or door without visual review.
+
+## Read and classify the source
+
+- Resolve the exact project and document with `shd_list_pdf_scheme_editor_documents`, then call `shd_get_pdf_scheme_editor_document` with `include_state=true`. Keep its current `base_revision` and each target annotation's `objectRevision`. Read `shd://pdf-scheme-editor/geometry-contract` when field shapes or validation rules are unclear.
+- Use the PDF source as geometry evidence, and inspect the full page before zooming into junctions, columns, window bays, door jambs, and wall returns.
+- For vector PDFs, call `shd_analyze_pdf_scheme_editor_vectors` to inspect fills, strokes, paths, and text anchors. Preview likely fill styles with `shd_preview_pdf_scheme_editor_vector_style`. A style is only a clue: confirm its hatching, paired faces, geometry, and continuity on the rendered PDF.
+- When a fill style is visually confirmed as a wall material, call `shd_trace_pdf_scheme_editor_wall_candidates` with only those style IDs. It can join subpaths that share complete vector edges, including concave contours. It does not decide which fills are walls; ambiguous or partial paths remain unmerged. Review every returned candidate against the PDF.
+- For raster PDFs or missing vector paths, trace polygons from high-resolution source crops. Do not invent geometry from a gap, dimension, label, door arc, furniture, radiator, or overlay.
+- Treat a `wall` as the filled wall-area polygon following its actual faces and thickness, not a centerline. Trace short wall pieces, returns, jambs, columns, and stepped or angled sections when they are visibly part of the wall construction. For a shaft or boxed feature, trace only its drawn solid wall bands; do not fill a visible hollow interior as wall.
+- Treat a window or door as an `opening` polygon in the actual wall gap. Identify it from its frame, leaf, track, swing, or other source symbol. Do not bridge an opening with wall geometry, and do not create an opening from an unexplained gap alone.
+
+## Keep geometry aligned
+
+- Use page-local coordinates from the editor preview. Preserve each change in direction; do not simplify a niche, angled return, narrow pier, or irregular outline into a rectangle.
+- Set calibration only from a known printed dimension or other explicit measured length.
+- Walls may meet room boundaries, but must not overlap room interiors. Keep actual wall thickness outside rooms. Where the source shows adjoining wall and room edges, align them to touch and avoid coordinate gaps.
+- Call `shd_preview_pdf_scheme_editor_wall_opening_candidates` before saving. It shows near-parallel wall-edge snaps within its calibrated tolerance, permits shared boundary contact, and reports positive-area overlap with rooms, openings that overlap wall interiors, or openings that fail to share a non-zero boundary segment with a wall. Snapping is only a small alignment correction: it does not fill missing wall sections and never moves openings.
+- Correct or discard every candidate marked `saveable=false`. Do not change a candidate just to make the checker pass if the source drawing does not support that geometry. If the boundary remains ambiguous, leave it unresolved and report where.
+- Do not use Build Walls as PDF recognition. It fills a geometric complement around room polygons and can miss real wall faces, columns, short pieces, and openings.
+
+## Model windows and doors
+
+- Save both windows and doors as `type=opening`, with `openingKind=window` or `openingKind=door`.
+- For a hinged door, use `doorType=swing` or omit it for the default. If the PDF clearly shows the swing and hinge side, set `doorOrientation` to the matching supported value 0–3; otherwise omit it when adding, or set it to `null` when updating so the editor can choose the adjacent-room side. Never derive the opening direction from the door arc's position alone if the hinge is unclear.
+- For a sliding door, set `doorType=sliding` in the opening write and `door_type=sliding` in the candidate preview. Sliding doors use the track and slide arrows, with no swing arc; omit `doorOrientation`.
+- Trace the opening's actual extent from the frame/threshold or track shown in the PDF. Keep its polygon out of wall interiors while ensuring it meets the wall boundary as required by the preview. Inspect the rendered symbol and orientation after saving.
+
+## Save and verify
+
+- Read current document and annotation revisions before a write. Use the typed `shd_add_pdf_scheme_editor_wall` / `shd_add_pdf_scheme_editor_opening` and matching update tools. Keep page, IDs, `base_revision`, `base_object_revision` for updates, and a unique `idempotency_key` current.
+- Preview proposed wall and opening polygons before writing. A successful preview is not a save and is not proof that the geometry matches the PDF.
+- After writing, read the document again and verify revision, polygons, opening kind/type, orientation, and alignment against the source. Check close-ups and the whole page, including wall segments between windows and around room corners.
+- Do not delete unrelated annotations. Report any unrecognized or ambiguous wall/opening regions instead of silently guessing.