Skip to content

README.md

Latest commit

 

History

History
292 lines (201 loc) · 6.71 KB

README.md

File metadata and controls

292 lines (201 loc) · 6.71 KB
Raw

Python Backend - Archicad Integration Service

This is the Python backend service that handles Archicad integration for the ts-ifc-api project. It communicates with Archicad via the Archicad API and with the Node.js backend via WebSocket for real-time progress updates.

Status

✅ Production Ready - 100% Complete

Features

  • ✅ Archicad .pln to IFC conversion (bidirectional)
  • ✅ IFC to Archicad .pln import
  • ✅ WebSocket communication with Node.js backend
  • ✅ Real-time conversion progress tracking
  • ✅ Plugin status monitoring
  • ✅ Job management and tracking
  • ✅ Error handling and logging

Prerequisites

  • Python 3.8+ (3.13+ recommended)
  • Archicad 28.4 installed and running
  • Archicad API enabled (Options → Work Environment → Add-On Manager)
  • Node.js backend running on port 3000
  • Archicad Plugin installed and running

Installation

  1. Create a virtual environment:
python -m venv venv-python
  1. Activate the virtual environment:
# Windows
venv-python\Scripts\activate

# Linux/macOS
source venv-python/bin/activate
  1. Install dependencies:
pip install -r requirements.txt
  1. Copy .env.example to .env and configure:
cp .env.example .env
  1. Edit .env with your settings:
FLASK_PORT=5000
NODE_WS_URL=ws://localhost:3000/ws/python-bridge

Usage

Start the Server

python src/server.py

The server will:

  • Start Flask on port 5000 (default)
  • Connect to Node.js WebSocket bridge
  • Wait for Archicad to be available

API Endpoints

Health Check

GET /health

Returns the status of the Python server, Archicad connection, and Node.js WebSocket.

Convert Archicad to IFC

POST /convert/archicad-to-ifc
Content-Type: multipart/form-data

file: <.pln file>
jobId: <optional job ID for tracking>

Converts an Archicad .pln file to IFC format. Progress updates are sent via WebSocket to the Node.js backend.

Trigger Revit Conversion

POST /trigger-revit-conversion
Content-Type: application/json

{
  "ifcPath": "/path/to/file.ifc",
  "outputPath": "/path/to/output.rvt",
  "jobId": "optional-job-id"
}

Triggers an IFC to Revit conversion by sending a command to the Node.js backend, which forwards it to the Revit plugin.

Get Job Status

GET /jobs/<job_id>/status

Retrieves the status of a conversion job from the Node.js backend.

Architecture

WebSocket Communication Flow

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│   Python    │◄───WS───┤   Node.js   │◄───WS───┤   Revit     │
│   Service   │         │   Backend   │         │   Plugin    │
└─────────────┘         └─────────────┘         └─────────────┘
      │                        │
      │                        │
      ▼                        ▼
┌─────────────┐         ┌─────────────┐
│  Archicad   │         │  Frontend   │
│  API        │         │  Clients    │
└─────────────┘         └─────────────┘

Message Types

From Python to Node.js

  • identify - Service identification on connection
  • progress_update - Job progress update
  • job_error - Job error notification
  • trigger_revit_conversion - Request Revit conversion
  • get_job_status - Request job status
  • pong - Heartbeat response

From Node.js to Python

  • connection_ack - Connection acknowledgment
  • trigger_archicad_conversion - Request Archicad conversion
  • ping - Heartbeat check

Architecture

Service Components

server.py

Main Flask application with API endpoints:

  • Health check endpoint
  • Conversion endpoints (PLN ↔ IFC)
  • Job status tracking
  • Error handling

websocket_client.py

WebSocket client for communicating with Node.js backend:

  • Auto-reconnection with exponential backoff
  • Message routing and handling
  • Real-time progress updates
  • Bidirectional communication
  • Heartbeat/ping-pong support

archicad_service.py

Service for interacting with Archicad Plugin:

  • WebSocket connection management
  • .pln to IFC export
  • IFC to .pln import
  • Project operations
  • Progress callbacks
  • Job lifecycle management

Development

Running in Development Mode

# Set debug mode in .env
FLASK_DEBUG=True

# Run server
python src/server.py

Testing WebSocket Connection

You can test the WebSocket connection using a WebSocket client:

const ws = new WebSocket("ws://localhost:3000/ws/python-bridge");

ws.onopen = () => {
  console.log("Connected to Node.js");
  ws.send(
    JSON.stringify({
      type: "identify",
      service: "test-client",
      version: "1.0.0",
    }),
  );
};

ws.onmessage = (event) => {
  console.log("Received:", JSON.parse(event.data));
};

Troubleshooting

Archicad Connection Failed

Problem: Failed to connect to Archicad: Connection refused

Solution:

  1. Ensure Archicad is running
  2. Verify Archicad plugin is installed in Add-Ons folder
  3. Check plugin is loaded: Options → Add-On Manager
  4. Ensure WebSocket server started (check Archicad console/logs)
  5. Check that port 8081 is not blocked by firewall

WebSocket Connection Failed

Problem: WebSocket connection error: Connection refused

Solution:

  1. Ensure Node.js backend is running on port 3000
  2. Check NODE_WS_URL in .env is correct
  3. Verify firewall settings

Conversion Timeout

Problem: Conversion takes too long and times out

Solution:

  1. Large files may take several minutes (this is normal)
  2. Increase timeout in Node.js service if needed
  3. Check Archicad is not showing modal dialogs or user prompts
  4. Monitor progress updates via WebSocket
  5. Consider splitting very large models (> 100MB)

Performance

Typical conversion times:

Project Size Elements Conversion Time
Small < 500 10-30s
Medium 500-2000 30-90s
Large 2000-5000 90-180s
Very Large > 5000 180s+

Future Enhancements

  • Extended unit test coverage
  • Batch processing support
  • Performance optimizations for large models
  • Additional IFC schema versions support
  • Job cancellation from Python side

License

GNU General Public License v3.0 or later

See COPYING for details.

Author

Matheus Piovezan Teixeira