Skip to content

Osprey Forge - User Guide

Overview

Osprey Forge is an AI-powered tool for extracting asset hierarchies from P&ID (Piping and Instrumentation Diagram) documents. It automates the detection of equipment, instruments, and their relationships, preparing data for import into PI Asset Framework.

Getting Started

1. Opening a Document in Forge

  1. Navigate to Documents page
  2. Locate your P&ID file (PDF format)
  3. Click the document to open it in the viewer
  4. In the top-left corner, click "Open in Osprey Forge"
  5. The Forge editor will load with your P&ID

Core Workflows

2. Extracting Text from P&IDs

For PDFs with Embedded Text:

  1. Click Extract dropdown → Embedded Text
  2. Text regions are automatically detected and highlighted in green rectangles
  3. Click any rectangle to view/edit the extracted text in the right panel

For Scanned/Image-Based PDFs:

  1. Click Extract dropdown → OCR (Optical Character Recognition)
  2. Wait for AI processing (may take 30-60 seconds)
  3. Text is extracted and highlighted in green rectangles
  4. Review low-confidence extractions using Review Extraction button

3. Defining and Detecting Symbols

Method 1: Manual Symbol Definition

  1. Double-click anywhere on the canvas to create a custom rectangle
  2. Resize the rectangle to frame your symbol of interest (e.g., an instrument bubble)
  3. Press keyboard shortcut to classify:
    • I = Instrument (blue)
    • E = Equipment (orange)
    • O = Off-page Connector (purple)
    • A = Annotation (gray)

Method 2: Detect Similar Symbols

  1. Select one or more classified rectangles (your template symbols)
  2. Click Detect dropdown → Detect Similar
  3. AI finds visually similar symbols across the page
  4. Review and adjust results

Method 3: Detect from Symbol Library

  1. First, build your library by selecting a symbol → Save to Library
  2. Name it (e.g., "Pressure Indicator PI") and set asset type
  3. Click Detect dropdown → Detect from Library
  4. Select which symbols to detect (e.g., all instruments)
  5. Set confidence threshold (0.7 recommended)
  6. Click Detect Selected

4. Automated Processing Workflow

For fastest results, use the Auto Process button:

  1. Click Auto Process (runs 4 steps automatically):
    • Step 1: Detect embedded text
    • Step 2: Detect all symbols from your library
    • Step 3: Group text labels with nearby symbols
    • Step 4: Remove unclassified text
  2. Results: Equipment and instruments with associated text labels, ready for export

5. Associating Instruments to Equipment

Multi-select items:

  1. Hold Ctrl and click to select 1 equipment + multiple instruments
  2. Click Associate button (appears in right panel)
  3. Instruments are now linked to the equipment
    • Equipment shows solid border
    • Click equipment to see all associated instruments
    • Click instrument to see parent equipment

Edit associations:

  • Click any associated item
  • Use Remove button in the associations list
  • Or click Clear Associations to unlink all

6. Mapping Instruments to PI Tags

  1. Select equipment with associated instruments
  2. Click Auto-Map Instruments in right panel
  3. AI matches instrument names to PI tags using LLM
  4. Review confidence scores (green = high, yellow = medium, red = low)
  1. Click instrument tag input field → Search Tags
  2. Enter search criteria:
    • Tag name (supports regex if enabled)
    • Description
    • Engineering units
    • Point source
  3. Click Search
  4. Select matching tag from results table

Tag Search Options:

  • Use Regex: Enable pattern matching (e.g., PI-10[0-9]{2})
  • Case Sensitive: Exact case matching
  • Hide SCAN=0: Filter out non-scanning tags
  • Hide DQ Issues: Filter tags with data quality problems
  • Logical AND: All criteria must match (vs. any criteria)

7. Setting Equipment Types and Attributes

  1. Click on any equipment rectangle
  2. In right panel, select Equipment Type from dropdown:
    • Pump, Valve, Tank, Heat Exchanger, Compressor, etc.
  3. Equipment type determines which attributes appear for instruments:
    • Pump: Discharge Pressure, Suction Pressure, Flow, Speed, Amps, etc.
    • Heat Exchanger: Inlet Temp, Outlet Temp, Differential Pressure, etc.
  4. For each instrument, assign its attribute (e.g., "Discharge Pressure")

8. Grouping Text Highlights

Auto-Grouping:

  1. Click Group Text → Group Text Under Symbols
  2. Text near symbols is automatically associated

Manual Grouping:

  1. Select multiple text rectangles (Ctrl+Click)
  2. Click Manual Group button
  3. Text is combined into single rectangle
  4. Edit combined text if needed

Smart Grouping:

  1. Click Group Text → Group Overlapping
  2. AI groups text by proximity, alignment, and font similarity

9. Saving and Version Control

Save Annotations:

  • Click Save button (top-right)
  • Annotations saved with version number
  • Unsaved changes indicator appears after edits

View Version History:

  1. Click View Version History
  2. See all saved versions with timestamps
  3. Click version to view (read-only)
  4. Revert to previous version if needed

10. Exporting Data

Export for PI Asset Framework:

  1. Click Export dropdown → Export Text Highlights
  2. Choose CSV format for PI AF import
  3. File includes:
    • Equipment hierarchy
    • Associated instruments
    • Attribute mappings
    • PI tag references

Export for JSON:

  • Choose JSON format for custom integrations
  • Includes all metadata and relationships

Advanced Features

Search & Navigation

Search Current Page:

  1. Enter text in search box (top-right)
  2. Click Search Page
  3. Matching rectangles pulse in red
  4. Use to find specific tags/equipment

Search All P&IDs:

  1. Click Search All P&IDs
  2. Search across entire document library
  3. Filter by current file or all files
  4. Click result to jump to that page/document

Review Extraction Quality

  1. Click Review Extraction (appears after text extraction)
  2. View all extractions sorted by confidence
  3. Filter Show Only Low Confidence (<70%)
  4. Edit text directly in review dialog
  5. Re-run OCR on low confidence items
  6. Click Focus on Canvas to locate item
  7. Save all changes at once

Symbol Library Management

  • Click Symbol Library button
  • View all saved symbols
  • Filter by type (instrument/equipment/etc.)
  • Search by name
  • Delete unused symbols
  • Use symbols for batch detection across multiple P&IDs

Canvas Controls

  • Zoom: Mouse wheel or Zoom In/Out buttons
  • Pan: Click and drag (or Ctrl+drag)
  • Fit to Width: Auto-scale to fit horizontally
  • Fit to Screen: Auto-scale to fit entire page
  • Rotate: CW/CCW rotation for landscape drawings
  • Reset: Clear all annotations and start over

Keyboard Shortcuts

  • I - Mark as Instrument
  • E - Mark as Equipment
  • O - Mark as Off-page Connector
  • A - Mark as Annotation
  • Ctrl+Click - Multi-select
  • Double-click - Create custom rectangle
  • Enter - Trigger search