pdf-engineering-review

name: pdf-engineering-review description: Mark and annotate PDF engineering drawings with precise location tracking. Adds review comments, callouts, and markup at exact coordinates. Exports review reports with location references for each comment. advancedOnly: true

PDF Engineering Drawing Review Skill

Mark up engineering drawings and technical PDFs with precise location-based comments and annotations.

Capabilities

• Precise Location Marking: Add comments at exact X,Y coordinates on any page
• Visual Annotations: Circles, rectangles, arrows, and callout lines
• Comment Tracking: Export all comments with their exact locations
• Review Reports: Generate summary reports with location references
• Multi-Page Support: Handle large engineering drawing sets
• Coordinate Systems: Support for different units (points, inches, mm)
• Artifact Panel Display: Show markups visually in the artifact panel with clickable pins

Quick Start

Add a Comment at Specific Location

from scripts.pdf_reviewer import PDFReviewer

reviewer = PDFReviewer("drawing.pdf")

# Add a comment at exact coordinates (x=200, y=300 on page 1)
reviewer.add_comment(
    page=0,
    x=200, y=300,
    text="Dimension appears incorrect - should be 45mm not 40mm",
    author="John Engineer",
    color="red"
)

# Add a circle highlight around an area
reviewer.add_circle_markup(
    page=0,
    x=200, y=300,
    radius=25,
    label="A1",
    color="red"
)

# Save the annotated PDF
reviewer.save("drawing_reviewed.pdf")

# Export review report with all locations
reviewer.export_review_report("review_report.json")

Review Report Format

The exported review report contains exact locations:

{
  "document": "drawing.pdf",
  "review_date": "2025-01-15T10:30:00",
  "reviewer": "John Engineer",
  "total_comments": 5,
  "comments": [
    {
      "id": "A1",
      "page": 1,
      "location": {
        "x": 200,
        "y": 300,
        "x_inches": 2.78,
        "y_inches": 4.17,
        "quadrant": "upper-left"
      },
      "type": "comment",
      "text": "Dimension appears incorrect",
      "severity": "major",
      "status": "open"
    }
  ]
}

Annotation Types

1. Text Comments (Sticky Notes)

reviewer.add_comment(page, x, y, text, author, color)

Adds a sticky note annotation at the exact location.

2. Circle Markup

reviewer.add_circle_markup(page, x, y, radius, label, color)

Draws a circle around an area of concern with an optional label.

3. Rectangle Markup

reviewer.add_rect_markup(page, x, y, width, height, label, color)

Highlights a rectangular region.

4. Arrow/Callout

reviewer.add_arrow(page, from_x, from_y, to_x, to_y, text, color)

Draws an arrow pointing to a specific location with callout text.

5. Cloud/Revision Markup

reviewer.add_revision_cloud(page, points, label, color)

Draws a revision cloud around an area (common in engineering reviews).

6. Dimension Callout

reviewer.add_dimension_note(page, x, y, expected, actual, unit)

Specialized annotation for dimension discrepancies.

Coordinate System

PDF Coordinates

• Origin (0,0) is at the bottom-left of the page
• X increases to the right
• Y increases upward
• Units are in points (72 points = 1 inch)

Converting Units

from scripts.coordinates import CoordinateHelper

helper = CoordinateHelper(page_width=612, page_height=792)  # Letter size

# Convert inches to points
x_pts, y_pts = helper.inches_to_points(2.5, 4.0)

# Convert mm to points
x_pts, y_pts = helper.mm_to_points(50, 100)

# Get location description
desc = helper.describe_location(x_pts, y_pts)
# Returns: "Upper-left quadrant, 2.5in from left, 4.0in from bottom"

Engineering Drawing Workflow

Step 1: Load Drawing and Inspect

reviewer = PDFReviewer("assembly_drawing.pdf")
info = reviewer.get_document_info()
print(f"Pages: {info['pages']}")
print(f"Page size: {info['width']}x{info['height']} points")

Step 2: Convert to Images for Coordinate Reference

# Generate reference images to identify coordinates visually
reviewer.export_pages_as_images("pages/", dpi=150, grid=True)

Step 3: Add Review Comments

# Add comments with unique IDs for tracking
reviewer.add_comment(0, 150, 400, "Missing weld symbol", author="QA", label="R1")
reviewer.add_circle_markup(0, 150, 400, 30, label="R1", color="red")

reviewer.add_comment(0, 450, 200, "Tolerance too tight for manufacturing",
                     author="QA", label="R2", severity="major")
reviewer.add_rect_markup(0, 430, 180, 60, 40, label="R2", color="orange")

Step 4: Save and Export Report

reviewer.save("assembly_drawing_reviewed.pdf")
report = reviewer.export_review_report("review_report.json")
reviewer.export_review_summary("review_summary.md")  # Markdown summary

Artifact Output Format

IMPORTANT: When generating PDF review results, you MUST use the pdf-review artifact type with proper metadata structure. DO NOT generate React components for PDF reviews.

Correct Artifact Format

<artifact type="pdf-review" title="Engineering Drawing Review - [Document Name]">
{
  "reviewData": {
    "document": "drawing.pdf",
    "document_path": "/path/to/drawing.pdf",
    "review_date": "2025-01-15T10:30:00Z",
    "reviewer": "Engineering QA",
    "document_info": {
      "filename": "drawing.pdf",
      "pages": 3,
      "width": 612,
      "height": 792,
      "width_inches": 8.5,
      "height_inches": 11
    },
    "total_comments": 5,
    "comments_by_severity": {
      "critical": 1,
      "major": 2,
      "minor": 2
    },
    "comments_by_page": {
      "1": 3,
      "2": 2
    },
    "comments": [
      {
        "label": "A1",
        "page": 1,
        "location": {
          "x_points": 200,
          "y_points": 300,
          "x_inches": 2.78,
          "y_inches": 4.17,
          "x_mm": 70.6,
          "y_mm": 105.8,
          "quadrant": "upper-left"
        },
        "type": "comment",
        "text": "Dimension appears incorrect - verify tolerance",
        "author": "Engineering QA",
        "severity": "major",
        "status": "open",
        "created_at": "2025-01-15T10:30:00Z"
      }
    ]
  }
}
</artifact>

Key Requirements

1. Always use type="pdf-review" - Never use type="react" for PDF reviews
2. Include complete reviewData - The metadata must include all fields shown above
3. Use proper coordinate format - Include both points and unit conversions (inches, mm)
4. Include severity levels - Use: critical, major, minor, info, question
5. Provide location quadrant - Helps users locate comments visually

Severity Colors

• critical (red): Safety issues, code violations, structural concerns
• major (orange): Significant errors requiring correction
• minor (yellow): Minor issues, clarifications needed
• info (blue): Informational notes, suggestions
• question (purple): Questions requiring response

Artifact Panel Integration

When used in Advanced Chat mode, PDF review markups are displayed in the artifact panel with:

• Visual markup overlay: Pins and shapes at exact coordinates on the PDF image
• Comment list panel: Sidebar showing all comments with severity badges
• Click navigation: Click a pin to scroll to the comment, click comment to highlight pin
• Export options: Download annotated PDF or review report

Scripts Reference

Best Practices

1. Use consistent labels: Follow a naming convention (A1, A2, B1, etc.)
2. Combine annotations: Use comment + circle together for visibility
3. Use appropriate colors: Red for critical, orange for major, yellow for minor
4. Include context: Make comments specific and actionable
5. Export reports: Always generate JSON/Markdown reports for tracking
6. Reference zones: Use grid references for large drawings

File Locations

• Main library: /scripts/pdf_reviewer.py
• Coordinate utilities: /scripts/coordinates.py
• Batch processor: /scripts/batch_review.py
• Reference docs: /references/annotation_types.md

Requirements

PyMuPDF>=1.23.0  # Primary PDF library (imported as fitz)
Pillow>=10.0.0   # Image export

Limitations

• Cannot modify locked/encrypted PDFs without password
• Annotation appearance may vary slightly between PDF viewers
• Very large drawings (E-size, architectural) may need coordinate scaling