/viewport-highlighter

name: viewport-highlighter
description: >
  Identify and highlight viewports on construction drawing sheets using
  vision. Detects view boundaries, titles, scales, and view types. Creates
  viewport overlays via AgentCM API. Requires AgentCM (.construction/
  directory). Triggers: 'highlight viewports', 'find views'.

Viewport Highlighter

Purpose

Automate viewport segmentation of construction drawing sheets. Each sheet typically contains 1-12+ distinct views (floor plans, sections, elevations, details, schedules). This skill identifies all views, determines their boundaries, extracts metadata (title, detail number, scale, type), and creates viewport highlights — producing the same result as a user manually drawing and labeling each viewport in the UI.

Does NOT: modify existing viewports, delete viewports, or change element data. Only creates new viewport highlights and populates their metadata.

---

Step 0: Verify AgentCM Mode

This skill **requires AgentCM**. It writes viewport overlays through the AgentCM REST API and has no standalone output path.

**Check for `.construction/` directory at the project root.**

If `.construction/` is absent, **stop immediately** and tell the user: > "viewport-highlighter requires an AgentCM project — `.construction/` directory not found. This skill submits viewport overlays through the AgentCM API and cannot operate without it. Open this project in AgentCM first, then re-run."

If `.construction/` exists:

• Read `.construction/CLAUDE.md` for project context
• Read `.construction/database.yaml` for `query_command`, `project_id`, `api_url`
• Read `.construction/index/sheet_index.yaml` for sheet inventory
• Sheet images at `.construction/rasters/{sheet_number}.png`
• OCR data queryable via `extracted_items` table in PostgreSQL
• Write viewports via REST API

Step 1: User Scopes the Task

User provides sheet scope:

• Specific sheets: "A2.01, A2.02, A5.01"
• By discipline: "all architectural sheets"
• All sheets: "every sheet in the set"

Optional: user can specify which view types to look for (e.g., "only floor plans and sections"). Default: identify ALL views on each sheet.

**Before proceeding:** Confirm the sheet list and any filters with the user. Show the count of sheets to process.

Step 2: Vision — Identify View Boundaries

For each sheet in scope, rasterize to PNG (if not already available) and examine with vision.

# Rasterize on demand if the pre-rendered PNG is missing
${CLAUDE_SKILL_DIR}/../../bin/construction-python \
  ${CLAUDE_SKILL_DIR}/../../scripts/pdf/rasterize_page.py \
  "{pdf_path}" {page_index} --dpi 200 --output /tmp/{sheet_number}.png

**Vision task:** Examine the full sheet image. Identify every distinct view (drawing area) on the sheet. For each view, extract:

| Field | What to look for | Example | |-------|-----------------|---------| | **Title** | View title bar text (usually centered below the view) | "FIRST FLOOR PLAN" | | **Detail Number** | Number in the detail bubble or title bar | "1", "A2.01", "3/A5" | | **Scale** | Scale annotation near the title bar | `1/8" = 1'-0"`, `1/4" = 1'-0"`, "NTS" | | **View Type** | Classification of the drawing content | plan, section, elevation, detail, schedule | | **Bounding Region** | Approximate rectangle enclosing the entire view (normalized 0-1) | `{x: 0.02, y: 0.05, w: 0.48, h: 0.65}` |

View boundary detection signals

Use these visual cues to determine where one view ends and another begins:

1. **Heavy border lines** — thick lines separating drawing areas 2. **Title bars** — horizontal bars with view name, scale, detail number 3. **Detail bubbles** — circles or hexagons with detail/sheet reference 4. **Whitespace gaps** — clear separations between drawing content 5. **Grid systems** — column/row grids define the extents of a plan view 6. **Section cut lines** — long dash-dot lines with directional arrows 7. **Match lines** — indicate where a plan continues on another sheet

View type classification

| View Type | `extractionScope` value | Signals | |-----------|------------------------|---------| | Floor plan | `plan` | Grid lines, room names/numbers, dimension strings, north arrow | | Enlarged plan | `plan` | "ENLARGED" in title, larger scale than base plan, room detail | | Section | `section` | Section cut reference (e.g., "SECTION A-A"), vertical layers, material hatching | | Elevation | `elevation` | "ELEVATION" in title, facade view, material callouts, floor lines | | Detail | `detail` | Detail bubble reference, large scale (3"=1'-0"), construction assembly closeup | | Schedule | `schedule` | Tabular grid, column headers, row data (door schedule, finish schedule) | | Diagram | `other` | Riser diagrams, single-line diagrams, flow diagrams |

Bounding region estimation from vision

When estimating the bounding region as normalized 0-1 coordinates:

• **x** = left edge of view content / sheet width (0.0 = left edge)
• **y** = top edge of view content / sheet height (0.0 = top edge)
• **width** = view content width / sheet width
• **height** = view content height / sheet height (include title bar)

**Include** the title bar and any associated notes/legends within the view. **Exclude** the sheet title block (typically bottom-right corner). **Margins:** Add ~1% padding on each side to avoid clipping content.

Multi-view sheet layout patterns

Common construction sheet layouts to expect:

• **Single view:** One large plan fills most of the sheet
• **2-up vertical:** Two views stacked (e.g., floor plan top, reflected ceiling bottom)
• **2-up horizontal:** Two views side by side (e.g., two elevations)
• **Grid layout:** 4-6 details arranged in a 2x3 or 3x2 grid
• **Mixed:** Large plan on left, 2-3 sections/details stacked on right
• **Schedule + details:** Schedule table in upper portion, details below

Step 3: OCR Anchor Verification

For each vision-identified view, verify and refine metadata using OCR data.

Title verifi