appPID

Overview

appPID is a specialized tool for generating lists of data and annotating PDF documents. It allows users to create structured lists, define hierarchies, manage revisions, and export data for database integration. The application supports project-based workflows, where you can load directories of PDF files, add bounding box annotations with metadata, and configure custom fields, typicals, and tagging rules.

appPID also integrates AI-powered inference modules for automatic instrument detection, document upload/processing, and marked PDF generation. An integrated MCP (Model Context Protocol) bridge allows external AI agents to control the application programmatically for automated annotation workflows.

This guide starts with the main window and covers core features, navigation, and how to use integrated dialogs. All instructions focus on user actions and visible interface elements.

Getting Started

• Menu Bar: Access File, Edit, View, Project, AddIn, and Help menus.
• Toolbar (Tools): Quick access buttons for common actions like opening projects, navigating images, saving, creating/editing annotations, and zooming.
• Central Canvas: Displays the loaded PDF page. Use it to draw bounding boxes and view annotations.
• Right Dock: Labels: Lists all annotations (shapes) on the current page with checkboxes for visibility.
• Filter: Type in the filter box to search labels (case-sensitive or exact match options available).
• Right Dock: File List: Shows the project structure as a tree view based on plant hierarchy.
• Bottom Dock: XML Table View: Displays editable metadata from XMP in a table format.
• PDF Search Bar: A toggleable search bar (Ctrl+F) for searching text within the current PDF or across all project PDFs, with match highlighting and navigation.
• Status Bar: Shows messages, cursor coordinates, and annotation details (e.g., width/height during drawing).
• Zoom Widget: In the toolbar, adjust zoom level numerically.

Managing Projects

Creating a New Project

1. Go to Project > New Project (or Ctrl+Alt+N). This starts the new project workflow.
2. A directory selection dialog opens. Choose an empty folder where you want to create the project.
3. If you cancel the directory selection, the process stops, and no project is created.
4. After selecting the directory, a confirmation dialog appears: "Do you want to create new project in folder [selected folder path]?" with Yes/No buttons.
5. Click No to cancel and close the project setup.
6. Click Yes to proceed.

The application initializes essential setup files in the selected folder (e.g., revisionOrder.pkl for revisions and plantHierarchy.pkl for hierarchy structure).

The Revision Order dialog opens automatically for initial configuration:

• Add at least one revision entry (e.g., "A", "B") using the Add Revision button.
• Arrange them in order via drag-and-drop or up/down buttons.
• Click OK to save (requires at least one revision; otherwise, a warning appears).

Next, the Plant Hierarchy dialog opens for initial setup:

• Add sections using the Add Section button.
• Use Properties to name each section.
• Set Start # and End # for character positions in document codes.
• Test with an Example Document field to verify parsing.
• Refresh Table to generate hierarchical paths, add descriptions, and set active statuses (the functionality work after uploads of documents in the project).
• Refresh Graph to preview the tree structure (the functionality work after uploads of documents in the project).
• Click OK to save (validates positions; warns on errors like invalid start/end).

If setup succeeds, the project loads into the main window with empty docks (File List, Labels, XML Table View) until you add PDF files to the folder.

After creation, project tools (e.g., Plant Hierarchy, Field Definer) become enabled in the menu.

Opening an Existing Project

1. Go to Project > Open Project (or Ctrl+U).
2. Select a directory containing project files (must include setup files like revisionOrder.pkl and plantHierarchy.pkl).
3. The application loads PDFs, populates the File List tree, and enables project tools.

Closing a Project

1. Go to File > Close (or Ctrl+W).
2. If unsaved changes exist, a prompt asks to save or discard.
3. The canvas clears, and project tools disable.

Adding and Managing Files

• In a loaded project, PDFs are scanned from the project directory.
• To add new PDFs: Go to Project > Upload new documents (Ctrl+Shift+U).
• File List: Expand/collapse the tree to browse by hierarchy generated according roules defined in Plant Hirarchy.
• Double-click a file in the File List to load it on the canvas.
• Navigate loaded files: Use Next Image (D) or Previous Image (A) shortcuts, or toolbar buttons.
• Updating File Names: Go to Project > Update Document (Ctrl+Shift+Q) to edit document, revision, and sheet properties.
• Copy Files: Project > Copy Document (Ctrl+Shift+C) to duplicate with new properties.
• Copy Annotations: Project > Open annotation (Ctrl+Shift+O) copy annotation of a file to current one.
• Delete Document: Project > Delete current document (Ctrl+Shift+D) removes the current PDF from the project.
• Update References Revision: Project > Update References revision (Ctrl+Alt+U) updates reference objects to the last available revision.

Working with Annotations

Viewing PDFs

• Zoom: Use Ctrl++ / Ctrl+-, or the zoom widget. Fit to Window (Ctrl+Alt+F) or Fit to Width (Ctrl+Shift+F).
• Original Size: Ctrl+= resets zoom to 100%.
• Pan: Click and drag on the canvas (open hand cursor).
• Mouse Wheel Zoom: Hold Ctrl and scroll to zoom in/out centered on the cursor position.

Creating Annotations

• Enter Create Mode: Toolbar button or W shortcut.
• Draw a bounding box: Click and drag on the canvas.
  • Hold Ctrl for square shapes (toggle via Edit > Draw Squares or Ctrl+Shift+R).
  • Status bar shows dimensions and coordinates.
• Objects labels appear in the Tag dock as list items and can be filtered by filter above.
• Each new shape is assigned to the first available category. Use the Edit dialog to change category and fill in field values.

Editing Objects

• Select: Click on an object (blue highlight).
• Move: Drag the object (closed hand cursor).
• Resize: Drag corners (pointing hand cursor).
• Edit Objects: Double-click the listed tags in Tags dock or after object selection: right-click > Edit, Toolbar button or Ctrl+E. Opens a dialog with Category, Typical, field values, and reference configuration.
• Delete: Select and press Toolbar button or right-click > Delete.
• Copy: Select and Ctrl+C, or right-click > Copy. The shape is stored in a class-level clipboard that survives page/document switches.
• Paste: Ctrl+V pastes the copied shape at the current cursor position. The pasted shape is automatically clamped to stay within the document bounds.
• Paste Here: Right-click on the canvas and select "Paste here" to paste the copied shape at the cursor location.
• Change Status: Selected object right click > Change State (Ctrl+G) to update status (color-coded: red/orange/green for Unchecked/PartiallyChecked/Checked).
• Check/Uncheck All: Ctrl+A checks all shapes, Ctrl+H unchecks all shapes.
• Advanced Mode: Toggle via Ctrl+Shift+A to switch between beginner and advanced toolbar layouts.

Text Selection Mode

The Text Selection mode allows you to select and copy text directly from the PDF document rendered on the canvas.

• Activate: View > Select Text or T. The cursor changes to an I-beam.
• Usage: Click and drag on the canvas to select text. Selected text is highlighted in blue.
• The selected text can be copied and used to fill in annotation field values.
• Deactivate: Press T again or switch to Create/Edit mode.

PDF Search

The PDF Search Bar provides full-text search within the current PDF or across all PDFs in the project.

• Toggle: View > Search in PDF or Ctrl+F.
• Search Field: Type your query and press Enter to search. Press Enter again to navigate to the next match.
• Case Sensitive: Check the "Aa" checkbox for case-sensitive matching.
• Whole Word: Check the "W" checkbox for whole-word matching only.
• Scope Toggle: Click "Current PDF" to toggle between searching the current document or "All PDFs" in the project. In All-PDFs mode, a results tree panel appears showing matches grouped by file.
• Navigation: Use the Previous/Next buttons (or Shift+Enter / Enter) to navigate between matches. The current match count is displayed.
• Cross-File Navigation: In All-PDFs mode, clicking a result in the tree opens the corresponding PDF and highlights the match.
• Highlight: The active match is highlighted with an orange/yellow rectangle on the canvas.
• Close: Press Escape or click the close button to hide the search bar and clear all highlights.

Shape Display Modes

appPID supports two visual display modes for annotation shapes on the canvas, configurable via View > Shape Display:

• Normal Shapes: Shapes are displayed as traditional bounding boxes with outlines, fill, vertices, and optional labels.
• Emoji Shapes: Shapes are displayed using the emoji icon assigned to their category (configured in the Field Definer). The emoji is centered in the shape's bounding box. Outlines and vertices are only shown when the shape is selected.

The display mode is remembered across sessions and applies to all shapes on the canvas.

Project Configuration Dialogs

Use these from the Project menu to customize your project. These dialogs allow you to define the structure, rules, and templates for objects and data management.

Plant Hierarchy (Ctrl+Alt+H)

The Plant Hierarchy dialog allows you to define and manage hierarchical structures for organizing documents based on their codes. It provides a tabbed interface where each tab represents a document category, and you can configure sections for parsing document numbers into a tree view.

Opening the Dialog

The dialog is accessed through the Project menu > Plant Hierarchy. When opened, it displays:

• Tab widget: Each tab represents a document category. A hierarchy rule set can be defined for each document category.
• Section table: Rows for defining hierarchy levels with start/end positions in the document code
• Example Document field: Test parsing with a sample code.
• Refresh Table/Graph buttons: Generate previews.
• OK/Cancel buttons: Save or discard changes.

Working with Categories

• Tabs: Switch between categories using the tabs.
• Add Category: Click to create a new tab for a document type.
• Delete Category: Select a tab and click to remove it.

Defining Sections

• Add Section: Click to add a row in the table.
• Properties: Click to name the section (e.g., "Area" for level 1).
• Start #: Enter the starting character position (0-indexed) in document codes.
• End #: Enter the ending position (exclusive).
• Output: Automatically shows extracted text from the Example Document.

Testing and Previewing

• Example Document: Enter a sample code (e.g., "A01-100-CW-001"); outputs update in real-time.
• Refresh Table: Generates a table with hierarchical paths.
• Description: Enter meaningful names (e.g., "Process Area 1").
• Active: Check to include in the tree; uncheck to skip (promotes children).
• Refresh Graph: Builds a tree view preview (e.g., Process Area 1 > Unit 100 > Cooling System > Document).

Saving and Validation

• Click OK to save.
• Validation: Ensures start < end, valid integers, no errors in outputs.

Best Practices

• Plan hierarchy based on document numbering (e.g., fixed-width codes).
• Use consistent separators in codes.
• Test with multiple examples.
• Mark deprecated sections inactive.

Revision Order (Ctrl+Alt+R)

The Revision Order dialog allows you to manage and organize revision entries in a numbered list format. You can add, delete, rearrange revisions, and save the changes to your project.

Accessing the Dialog

The dialog opens when you select the Project menu > Revision Order.

Interface Components

• Main List Area: Displays all revision entries in a numbered list format (e.g., "1. First Revision").
• Control Buttons: Move Up/Down, Add Revision, Delete Revision.
• Action Buttons: OK (✓) to save, Cancel (↶) to discard.

How to Use

• Viewing Revisions: Loads existing revisions in order.
• Rearranging: Drag-and-drop or use up/down buttons; numbering updates automatically.
• Adding: Click Add Revision, enter name in pop-up, click OK; adds to bottom.
• Deleting: Select and click Delete Revision; renumbers remaining.
• Saving: Click OK; requires at least one revision (warning if empty).
• Canceling: Click Cancel to discard changes.

Best Practices

• Use descriptive names.
• Focus on logical order (numbering is automatic).
• Keyboard: Enter to confirm add, Esc to cancel.

Field Definer (Ctrl+Alt+P)

The Field Definer is a comprehensive configuration dialog for defining and managing objects categories and their associated fields. It provides a tabbed interface where each tab represents a category (object type), and within each tab you can define the fields that will be used for objects of that category.

Opening the Dialog

The dialog is accessed through the Project menu > Field Definer. When opened, it displays:

• Tab widget: Each tab represents a category.
• Field tables: Within each tab, a table defines all fields for that category.
• Management buttons: Add/delete categories, manage descriptions.
• OK/Cancel buttons: Save changes or discard.

Understanding the Interface

• Tab Structure: Each tab = One category.
• Field Table Columns: Field (name), Description, Group, Function (dropdown: Custom/Key/Document/Group), Active (checkbox), Deletion (button).

Working with Categories

• Adding a New Category: Click "Add Category"; new tab with empty table.
• Deleting a Category: Select tab, click "Delete Category"; removes tab and affects XML/configurations on save.
• Managing Category Descriptions & Emojis: Click "Manage Category & Emoji"; rename the category and optionally assign an emoji icon from the built-in picker — the emoji appears directly on the category tab for quick visual identification and is used in Emoji display mode on the canvas.

Defining Fields

• Adding a Row (Field): Click "Add Row"; fill details.
• Field Name: Required, unique within category.
• Description: Optional explanation.
• Group: Optional for sections (e.g., "General Info").
• Function: Select one; exactly one Key/Document/Group per category.
• Active: Check for visible.
• Deletion: Click to mark for delete (turns red, "Redeem" to undo).

Validation Rules

• On OK: Checks one Key/Document/Group, no empty/duplicate names, unique categories.

Field Modification and Tracking

• Renaming: Updates all references on save (data, tagging, typicals).
• Save: Applies changes; fixes errors first.

Best Practices

• Use descriptive names.
• Organize with groups.
• Deprecate via inactive checkbox.

Tagging Compositor (Ctrl+Alt+C)

The Tagging Compositor is an advanced dialog for creating and managing complex tagging procedures across different object categories. It allows you to define custom tagging formats with multiple fields, separators, and formatting rules.

Accessing the Dialog

The dialog opens when you select the Project menu > Tagging Compositor.

Interface Structure

• Category Tabs: Top-level for object categories.
• Tagging Procedure Tabs: Within categories.
• Field Rows: Configurable options per procedure.

Control Buttons

• Add/Delete Category: Manage tabs.
• Add/Delete Tagging Procedure: Add new (select field), remove current.
• OK/Cancel: Save/discard.

Field Configuration Options

• Add Field: New row with Alphanum ("Letter"/"Number"/"-"), Characters (max), Min characters, Function (dropdown incl. "Costum"), Description, Separator ("Dash"/"Underscore"/"Space"/"Null"), Justify Text ("Yes"/"No"), Delete.

How to Use

• Adding Category: New tab.
• Deleting Category: Removes with procedures.
• Adding Procedure: Select available field in dialog.
• Deleting Procedure: Removes tab.
• Configuring Rows: Set options; add/delete as needed.
• Saving: Validates unique descriptions/functions (except "Costum"); warns on duplicates.

Best Practices

• Clear descriptions.
• Logical field order.
• Appropriate separators/limits.

Typical Definer (Ctrl+Alt+T)

The Typical Definer is a comprehensive dialog for creating and managing typical configurations across different object categories. It allows you to define standardized templates with structured data, tagging rules, and reusable components for efficient project management.

Accessing the Dialog

The dialog opens when you select the Project menu > Typical Definer.

Interface Structure

• Category Tabs: Top-level.
• Typical Tabs: Within categories.
• Data Tables: Records with fields.

Table Interface

• Deletion Column: Delete buttons.
• Field Columns: From category setup.
• Key Field Buttons: "Define Tag Rule".

Row Management Buttons

• Add Row: New record.
• Copy Info: From another typical.

How to Use

• Category Navigation: Switch tabs.
• Adding Typical: New tab with empty table.
• Renaming: Use Manage Description.
• Deleting: Removes with data.
• Adding Records: Click Add Row; enter data.
• Deleting Records: Click Delete in row.
• Defining Tag Rules: Click "Define Tag Rule"; sub-dialog for functions/values.
• Copying: Select source typical.

Advanced Features

• Key Composition Dialog: Function dropdown ("Costum" for manual), Value, Add Field/Delete.
• Typical Changes: When a typical-based shape is edited, individual field overrides (typical_changes) are tracked per child record. These overrides are propagated back to the parent shape on save, so edits made on reference shapes in other documents are reflected in the parent typical.
• Save: Validates (e.g., no duplicates, tagging procedures exist).

Best Practices

• Consistent formats.
• Use copy for variations.
• Define rules first.

Relationship Definer (Ctrl+Alt+L)

The Relationship Definer lets you declare how two object categories are linked to each other — which fields carry data across from one object type to another. When a save event occurs on a document containing objects involved in a relationship, appPID automatically propagates field values to the related objects in other documents, keeping your data consistent across the project.

Accessing the Dialog

Open via Project menu > Relationship Definer. The dialog requires at least one category to be defined in the Field Definer before use.

Interface Structure

• Relationship Tabs: Each tab represents one named relationship between two object categories.
• Object 1 / Object 2 dropdowns: Select the two categories participating in the relationship. The same category can appear on both sides (self-referential relationships are supported).
• Links Table: Rows that map a field from Object 1 to a field from Object 2, with a direction setting for each link.

Management Buttons

• Add Relationship: Creates a new tab (e.g., "Relationship 1") with empty configuration.
• Delete Relationship: Removes the currently active tab and its data.
• Manage Relationship Description: Rename the current relationship tab to something meaningful (e.g., "Valve to Pipe").
• OK / Cancel: Save or discard all changes.

Configuring Links

• Add Link: Inserts a new row into the links table. Each row has three settings:
  • Native (1): A field from Object 1 (Key field is excluded — only data fields appear).
  • Field Foreign (2): A field from Object 2 (Key field also excluded).
  • Direction: "1 to 2" means the value flows from Object 1's field into Object 2's field; "2 to 1" reverses this. When a save occurs, only links whose direction matches the role of the object being saved will propagate data.
• Delete: Removes that link row from the table.
• Changing Object 1 or Object 2: The field dropdowns in all existing link rows refresh automatically to reflect the new category's fields.

Validation Rules

• At least one link must be defined per relationship (a relationship with no links is invalid).
• Duplicate link pairs (same Native + Foreign field combination) within the same relationship are not allowed.
• Categories must be defined in Field Definer before relationships can be configured.

How Relationships Work at Runtime

When you save a document, appPID inspects each object on the page. For any object whose primary key appears in the relationship database (relationships_db), the application finds the linked foreign object in another document and copies field values according to the direction rules. If the foreign object belongs to a Typical, the Typical records are also examined for a matching primary key before the update is applied. The relationship database is automatically deduplicated on save.

Data Management and Export

XML Table View

• Bottom dock: Shows XMP metadata in a table.
• Category Dropdown: Filter by type.
• Edit: Double-click cells; bulk edit via Set Filtered Values.
• Filter: Double-click headers for menus (sort, search, checkboxes).
• Groups: Bold rows expand to show typical children (italics).
• Save/Reset: Commit or discard changes.
• Right-Click: Freeze/hide columns, quick filters.

Exporting Data

• Edit > Export PCD (Ctrl+Shift+E).
• Export Database Dialog: Select category, include typical roots.
• Save to CSV: New files get headers; append to existing without.
• Output: Fields with processed tags, TYPICAL column.

Saving and Auto-Save

• File > Save (Ctrl+S): Saves XMP to current PDF.
• Auto-Save: Enable via File > Auto Save mode. When enabled, saves automatically when navigating between documents (Next/Previous Image).
• Copy Annotations: Project > Copy Annotation (Ctrl+Shift+O) copies annotations from another file to the current one.
• Reset All: File > Reset All resets application settings and restarts the app.
• Recent Files: File > Open Recent shows recently opened project files for quick access.

Export/Import Documents

appPID integrates several AI-powered inference modules accessible through the AddIn menu. These modules run as external processes and communicate with the main application through a parallel processing system.

Upload New Documents (Ctrl+Shift+U)

Located in the AddIn menu, this feature allows you to upload new PDF documents into the project. Select one or more PDF files, and the application processes and imports them into the project directory.

• Access: AddIn > Upload new documents or Ctrl+Shift+U.
• File Dialog: Select PDF files to upload.
• After processing, a confirmation dialog asks if you want to reload the project to include the new documents.

Retrieve Document (Ctrl+Alt+D)

This feature downloads PDF documents into the project from an external source. It runs without a file dialog and processes documents directly.

• Access: AddIn > Download pdf or Ctrl+Alt+D.
• After completion, a confirmation dialog asks if you want to reload the project.

Download Marked PDF (Ctrl+Shift+D)

This feature creates a copy of the current PDF with all annotation labels visually marked on the document, allowing you to export a reviewed/marked-up version of the PDF.

• Access: AddIn > Create Marked PDF or Ctrl+Shift+D.
• Select a PDF file, and the application generates a new PDF with visible label annotations.
• After completion, a confirmation dialog asks if you want to reload the project.

Advanced Features

Cross-Document References

Separately from category-level relationships, individual shapes can carry a reference to a master shape in another document. A referenced shape mirrors the label data of its master and is rendered with a "pattern" style to indicate it is derived. The reference system handles three key lifecycle events automatically:

• Creating References: In the Edit Shape dialog (Ctrl+E), check "Reference to another object", select the target Object (by primary key) and Revision, then click "Set". The shape becomes a reference shape linked to the master.
• On master rename: When a master shape's primary key is edited and saved, appPID scans all other project files for shapes that reference that primary key. If any are found, a confirmation dialog lists the affected files and shapes; confirming updates the stored reference key in all of them.
• On master deletion: Similarly, deleting a master shape triggers a scan for dependent referenced shapes. Confirming the dialog removes those shapes from their respective files.
• Update References to Last Revision: Project > Update References revision (Ctrl+Alt+U) scans the current file and advances any stale reference revisions (e.g., pointing to revision "A" when revision "B" now exists) to the most recent revision available in the project.

Reference shapes automatically propagate typical_changes back to their parent shape on save, so field edits made on reference shapes in other documents are reflected in the parent typical's record overrides.

MCP Bridge / AI Agent Integration

appPID includes a built-in MCP (Model Context Protocol) bridge that exposes a TCP server on port 34220, allowing external AI agents to control the application programmatically. This enables automated annotation workflows, batch processing, and AI-assisted tagging.

How It Works

• The bridge starts automatically when appPID launches, listening on 127.0.0.1:34220.
• External agents connect via TCP socket and send JSON commands.
• Commands are executed in the Qt main thread for thread safety.
• When an agent is connected, auto-save is automatically enabled to ensure changes are persisted. The previous auto-save state is restored when the agent disconnects.

Available Commands

• get_app_state: Returns current application state (project loaded, current file, image index, box count, etc.).
• open_project: Opens a project directory.
• load_pdf: Loads a specific PDF file.
• save_file: Saves the current document.
• export_data: Triggers the export routine.
• get_boxes: Returns all annotation boxes on the current canvas.
• new_shape: Creates a new annotation box.
• new_reference_shape: Creates a cross-document reference shape.
• modify_shape: Modifies an existing annotation box.
• delete_shape: Removes annotation box(es).
• verify_document: Marks the current document as verified.
• query_pdf: Searches for text in a PDF using regex.
• get_pixmap: Renders a region of a PDF page as an image.
• get_project_settings: Returns project configuration (field definer, plant hierarchy, typicals, relationships, etc.).
• get_project_documents: Lists all PDF documents in the project.
• get_project_records: Returns all records from the project view for every category.
• get_relationship_graph: Returns the project relationship graph (nodes, edges, documents for vector DB).
• modify_field_definer: Updates field definitions.
• modify_plant_hierarchy: Updates plant hierarchy configuration.
• modify_revision_order: Updates revision order.
• modify_tagging_compositor: Updates tagging composition.
• modify_typical_definer: Updates typical definitions.
• modify_relationship_definer: Updates relationship type definitions.
• update_relationships_db: Updates resolved relationship instance links.
• project_new: Creates a new project.
• next_image / prev_image: Navigates between documents.
• simulate_click: Simulates clicking a UI button by label.

Keyboard Shortcuts

Help Menu

• Help > User Guide: Opens the online documentation in your browser.
• Help > Information: Shows app name and version.
• Help > Keyboard shortcuts: Displays a dialog listing all active keyboard shortcuts.