thivakar101/arcsight3d

Purpose and execution surfaces

ArcSight 3D converts uploaded PNG/JPG floor plans into explorable 3D exports. Its active system is a PyQt desktop client, Flask REST backend, PostgreSQL persistence layer, headless Blender generation, and Unity-side runtime visualization. Primary launch points are desktop/app.py and backend/app.py; Unity integration begins with unity/Assets/Scripts/SceneBootstrap.cs.

Client-to-API boundary

The desktop application owns user interaction, background work, and HTTP transport rather than processing locally. desktop/ui/main_window.py drives upload/process/export actions; desktop/workers.py keeps network and generation operations off the UI thread; desktop/api_client.py is the backend contract boundary. Backend routes partition operations into project, processing, health, and export APIs: backend/api/project_routes.py, backend/api/processing_routes.py, and backend/api/export_routes.py.

Backend application and orchestration

Flask initialization, environment-derived configuration, and shared extensions are centered in backend/app.py, backend/config.py, and backend/extensions.py. Controllers adapt HTTP requests to service calls, while services orchestrate persistence and long-running stages: backend/controllers/project_controller.py, backend/services/processing_service.py, and backend/services/export_service.py. This separates route/controller concerns from CV, OCR, and Blender execution.

Project data model and persistence

PostgreSQL is the source of truth for projects, uploaded blueprints, detections, processing state, and exported artifacts. SQLAlchemy entities include backend/models/project.py, backend/models/blueprint.py, and backend/models/processing_job.py; structural entities cover walls, doors, windows, rooms, OCR text, and detected objects. Repository modules isolate database access, notably backend/database/repositories/project_repository.py and backend/database/repositories/object_repository.py. PostgreSQL is provisioned through docker-compose.yml and docker/postgres/init.sql.

Blueprint analysis pipeline

Processing takes an ingested blueprint through image normalization and geometric extraction, coordinated by backend/cv/detection_pipeline.py. Preprocessing prepares the image in backend/cv/preprocessing.py; line and contour stages infer architectural geometry in backend/cv/line_detector.py and backend/cv/contour_detector.py. Resulting coordinates become persisted structural records rather than being passed directly to rendering.

OCR enrichment

OCR is an optional parallel enrichment path over the blueprint image. backend/ocr/ocr_pipeline.py invokes the Tesseract adapter in backend/ocr/tesseract_engine.py, then domain parsers identify dimensions and room labels via backend/ocr/dimension_parser.py and backend/ocr/room_name_parser.py. Tesseract is an external runtime configured through environment variables.

3D export and consumption

An export request uses backend/blender/blender_runner.py to spawn the configured Blender executable headlessly. The Blender-side scene builder, backend/blender/scripts/generate_scene.py, reads persisted project geometry, builds wall/door meshes, and emits GLB or FBX artifacts; export coordination resides in backend/services/export_service.py. Unity consumers load the exported model through unity/Assets/Scripts/RuntimeModelLoader.cs and provide walkthrough controls with unity/Assets/Scripts/FirstPersonController.cs; GLB runtime support may require the external GLTFast package.

Operational boundaries

The backend depends on OpenCV, Tesseract, PostgreSQL, and a locally accessible Blender executable. Docker support covers the database and backend image via docker/backend.Dockerfile; the desktop client and Blender remain host-executed. legacy/ is retained prototype material and is outside the current architecture.