SCRIBE - Technical Documentation & Codebase Overview

Context for LLMs: This repository is a lightweight, browser-based STEP file viewer and annotation tool ("PDF for CAD"). It uses a Python Flask backend with CadQuery/OCP for geometry processing and a Three.js frontend for rendering.

Core Philosophy: Treat STEP files as authoritative documents. Metadata (tolerances, threads, colors) is injected directly into the STEP file structures or persisted via sidecar SQLite DB, keyed by geometry hashes.

---

📂 File Structure & Logic Map

/
├── app.py                  # Flask routes (entry point)
├── core/                   # Core application logic (modular)
│   ├── state.py            # ModelState singleton & global state
│   ├── loader.py           # STEP loading, tessellation, metadata recovery
│   ├── exporter.py         # STEP export with metadata injection
│   ├── metadata.py         # 3-strategy metadata embed/extract
│   └── utils.py            # Color conversion & utilities
├── face_db.py              # SQLite face fingerprinting & metadata
├── requirements.txt        # Python dependencies (cadquery-ocp, flask, gunicorn)
├── Dockerfile              # GCP deployment container (python:3.11-slim)
├── .dockerignore            # Exclude venv, dev files
├── static/
│   ├── js/
│   │   └── viewer.js       # Three.js viewer + all UI logic
│   └── css/
│       ├── style.css        # Core light theme & layout
│       └── style_expansion.css  # Panel expansion styles
├── templates/
│   └── index.html          # Single-page application
├── tests/
│   ├── run_tests.py        # Main test runner script
│   ├── sample.step         # Default loaded model
│   └── test_*.py           # Unit & integration tests
├── uploads/                # User-uploaded files (persistent)
└── stepviewer.db           # SQLite DB (generated at runtime)

---

🧠 Core Logic & Systems

1. Backend (Modular Architecture)

Framework: Flask + Gunicorn
Geometry Kernel: Open Cascade (OCCT) via cadquery & OCP

Module	Purpose
app.py	Flask routes, API endpoints
core/loader.py	load_step_xcaf() — STEP reading, face tessellation, metadata recovery
core/exporter.py	export_step_xcaf() — STEP writing with metadata injection
core/metadata.py	3-strategy metadata embed/extract (entity, description, comment)
core/state.py	ModelState singleton holding the XDE document and face data
core/utils.py	Color conversion helpers
face_db.py	SQLite face fingerprinting, exact + fuzzy matching

Key Functions

• load_step_xcaf(path) (core/loader.py):
  • Reads STEP using STEPCAFControl_Reader with XDE document.
  • Extracts embedded metadata via extract_meta_from_step() before OCC reads the file.
  • Iterates topological faces (TopExp_Explorer).
  • Hashing: Generates a stable geometry hash for each face.
  • Metadata Recovery Priority: Embedded STEP (hash-based) > Embedded STEP (index-based) > SQLite DB (exact+fuzzy).
  • Tessellation: Converts BRep to Mesh for Three.js.
• export_step_xcaf() (core/exporter.py):
  • Writes XDE document with colors via STEPCAFControl_Writer.
  • Injects metadata via 3 strategies (see Metadata System below).
• inject_meta_into_step() / extract_meta_from_step() (core/metadata.py):
  • Strategy 1: PROPERTY_DEFINITION → DESCRIPTIVE_REPRESENTATION_ITEM (SolidWorks-compatible)
  • Strategy 2: [SVFM:<base64>] in PRODUCT description field (universally preserved)
  • Strategy 3: /* __STEPVIEWER_META_START__ ... */ comment block (fast SCRIBE-to-SCRIBE)

2. Frontend (viewer.js + index.html)

Framework: Vanilla JS + Three.js (WebGL)

Rendering Pipeline

1. loadModel(): Fetches JSON from /upload (Vertices, Normals, Indices, Metadata).
2. buildScene(): Creates THREE.BufferGeometry per face with userData.
3. fitCameraToGroup(): Positions camera at Isometric (-1, -1, 1) default.

Interaction

• Arcball Controls: ArcballControls.js for tumbling rotation.
• Raycasting: Click → highlight face (pink glow), populate right panel.
• View Buttons: Floating bar (F/B/L/R/T/Bo/Iso) for quick camera presets.

3. Feature: Tolerance Heat Map

• Tight (≤ 0.005"): Red (configurable)
• Loose (> 0.005"): Gray (configurable)
• None: Ghosted/transparent
• Filtering by tolerance type via checkboxes.

4. Feature: Hole Wizard

• Groups faces by thread metadata (e.g. "UNC 1/4-20").
• Color picker per group, visibility toggle, delete action.
• Counts unthreaded cylindrical faces.

5. Admin Cleanup Tools

• 3-scope metadata cleanup: DB only, File only, or All (nuke).
• Strips all 3 metadata strategies from the STEP file.
• Clears in-memory model.face_meta to prevent re-injection on export.
• Before/after verification via extract_meta_from_step().

---

💾 Database Schema (stepviewer.db)

Table: face_meta

Column	Type	Description
id	INTEGER	Primary Key
face_hash	TEXT UNIQUE	16-char hex geometry fingerprint
meta	TEXT	JSON: {color, thread, tolerance, ...}
surf_type	TEXT	Surface type (Plane, Cylinder, etc.)
cx, cy, cz	REAL	Centroid coordinates
area	REAL	Surface area
dx, dy, dz	REAL	Bounding box dimensions
n_edges	INTEGER	Edge count
n_verts	INTEGER	Vertex count
created_at	TIMESTAMP	Creation timestamp
updated_at	TIMESTAMP	Last update timestamp

---

🔄 API Endpoints

Method	Endpoint	Description
GET	/	Serve main app (auto-loads tests/sample.step)
GET	/<uuid>	Load model by UUID
POST	/upload	Upload STEP file, returns face mesh data + UUID
GET	/model/<uuid>	Get face data for a persisted model
POST	/set_color	Set face color(s)
POST	/set_thread	Set threading metadata
POST	/set_tolerance	Set tolerance metadata (batch)
GET	/thread_options	Get thread dropdown options
GET	/tolerance_options	Get tolerance dropdown options
GET	/holes	Get hole analysis data
POST	/export	Export annotated STEP (UUID filename)
POST	/test_cube	Generate test cube (internal)
GET	/test_sample	Load tests/sample.step (internal)
POST	/api/admin/clear_metadata	Admin: Wipe DB + strip file + clear memory
GET	/db_stats	Database statistics

🧪 Running Tests

Tests are located in tests/ and require the Flask server running on port 5555.

# Start the server
venv\Scripts\python.exe app.py

# Run the full suite (in another terminal)
venv\Scripts\python.exe tests/run_tests.py

# Or use pytest directly
venv\Scripts\python.exe -m pytest tests/ -v