简体中文 | English

SheetWeave

Weave tiled drawing sheets into one complete vector PDF.

---

SheetWeave is an agent skill, not a standalone app you are expected to operate by hand. Give your agent a drawing PDF and ask it to use $sheetweave; the skill provides the workflow, scripts, and review checkpoints needed to recover the layout and produce a merged vector PDF.

🧭 What Problem Does It Solve?

Many construction, architecture, and engineering PDFs are split into local/detail sheets. The hard part is not just stitching images together; it is recovering where each sheet belongs while keeping the final drawing sharp and vector-based.

Your situation	What SheetWeave helps the agent do
The PDF includes an overview/index page	Check the likely overview pages first, usually page 1 or the last page.
Overview labels are machine-readable	Match detail pages by extracted sheet codes or numeric markers.
Labels are visible but code cannot extract them	Ask a vision model or human to read the labels and produce a layout JSON.
There is no usable overview page, or the overview has no labels	Use overlap-based neighbor matching between detail sheets.
Some sheets connect only through small overlaps	Use targeted bridge recovery instead of slow full high-DPI rendering.
The final result must stay vector	Place original PDF pages onto a larger LaTeX/TikZ canvas.

In one sentence:

SheetWeave is a drawing-layout recovery skill, not a raster screenshot stitcher.

🟢 Easiest Install

If you are not a developer, do not start with terminal commands. Open your agent and say:

Please install the SheetWeave skill from https://github.com/WorkHaH/SheetWeave, then use it to merge my drawing PDF into one vector PDF.

Or in Chinese:

请帮我安装 https://github.com/WorkHaH/SheetWeave 这个 skill，然后用它把我的图纸 PDF 拼成一张完整的矢量 PDF。

The agent should install the skill, check the required PDF tools, and tell you if anything is missing.

⚙️ Install Manually

Recommended:

npx skills add WorkHaH/SheetWeave

Manual install:

git clone https://github.com/WorkHaH/SheetWeave.git ~/.agents/skills/sheetweave

For a project-local skill, place it under:

.agents/skills/sheetweave/

Restart or reload your agent after installation so it can discover SKILL.md.

💬 Ask Your Agent To Use It

Typical prompts:

Use $sheetweave to merge this drawing PDF into one vector PDF: ./drawings.pdf

用 $sheetweave 处理这个 PDF，把里面的局部图纸拼成一张完整的矢量 PDF。

Use $sheetweave on ./drawings.pdf. If the overview matching is ambiguous, prepare a VLM layout request instead of guessing.

🔍 Review The Result

The agent should inspect summary.json and the PNG preview before treating the vector PDF as final.

🧵 How It Works

📦 What The Agent Produces

output/run/
  summary.json                 # mapping, edges, components, final paths
  final/
    full-merged.pdf            # vector result when one component is solved
    full-merged.tex            # generated LaTeX/TikZ source
    full-merged.png            # raster review preview only
    layout-contact.png         # overview-guided contact sheet when available
  groups/group-XX/             # written when disconnected components remain
  vlm-request.json             # written when overview mapping needs help

🛠️ Runtime Environment

The skill includes Python scripts because PDF rendering, overlap matching, and vector assembly need deterministic tooling. Your agent may check or install these dependencies when needed.

Requirement	Purpose
Python 3.10+	Runs the bundled scripts.
numpy, opencv-python, Pillow, pypdf	Image matching and PDF manipulation.
pdfinfo, pdftoppm, pdftotext	PDF metadata, preview rendering, text extraction.
pdflatex	Final vector PDF assembly.

If you want to prepare the machine manually:

pip install -r scripts/requirements.txt

👁️ Manual / VLM Overview Mapping

When a first-page or last-page overview has labels that are visible to a person but not reliably extractable by code, SheetWeave should not guess the layout. The agent should read references/overview_layout_prompt.md, ask a vision model or human to map overview labels/regions to PDF pages, and rerun with --overview-layout-json.

If the overview truly has no labels, use the traditional overlap-matching route instead.

✅ Quality Bar

A good SheetWeave run should:

• Produce a single final/full-merged.pdf when the drawing set is connected.
• Keep the final PDF vector-based by embedding original PDF pages.
• Write summary.json with enough diagnostics to audit accepted, bridge, and synthetic edges.
• Preserve review artifacts so a human can verify alignment before using the result.
• Degrade gracefully into groups or a VLM request when the layout is not solved.

🗂️ Repository Layout

sheetweave/
  SKILL.md                         # skill entry point loaded by agents
  README.md                        # English GitHub documentation
  README.zh-CN.md                  # Chinese GitHub documentation
  agents/openai.yaml               # OpenAI Codex UI metadata
  scripts/
    sheetweave.py                  # main deterministic helper
    merge_drawings.py              # overlap scoring and raster diagnostics
    merge_pdf_drawings.py          # PDF helpers and overview parsing
    vector_pdf_export.py           # vector PDF assembly
    requirements.txt               # Python dependencies
  references/
    overview_layout_prompt.md      # prompt for manual/VLM mapping

⚠️ Current Limitations

• Very large canvases may hit LaTeX page-size limits depending on the TeX distribution.
• Synthetic bridge edges are geometric inferences; review summary.json and full-merged.png for critical work.
• The repository intentionally excludes real drawing PDFs and generated outputs. Add only public fixtures with clear licenses.