ifcurl/PLAN.md

IFC URL — Development Plan

Overview

IFC URL requires work across four distinct areas:

1. A Python core library and CLI tool
2. A preview service with Gitea integration
3. Desktop app integration (Bonsai, IFC Viewer)
4. The federation extension to IFCDOCUMENTREFERENCE

The Python core is the foundation for all other work. The Gitea integration and desktop app work can proceed in parallel once the core exists.

Language ownership

Component	Language	Rationale
URL parsing, git fetch, selector execution, rendering	Python	Built on IfcOpenShell
Bonsai plugin	Python	Bonsai is a Blender/Python addon
CLI tool	Python	Wraps the core library
Preview service	Python	Wraps the core library
Gitea plugin	Go	Gitea is written in Go; the plugin only calls an HTTP endpoint
Web viewer integration	JavaScript	Future, not in current scope

The Python core is a strong candidate for eventual contribution to IfcOpenShell, but this is not a prerequisite for any phase.

---

Phase 1 — Python core and CLI tool

Build a Python library that resolves an ifc:// URL and produces a rendered PNG. This validates the spec against real IFC files and is the foundation for all subsequent work.

Library responsibilities

• Parse an ifc:// URL into its components
• Infer git transport from URL structure (SSH, HTTPS, local)
• Fetch the IFC file from the repository at the specified ref
• Execute the IfcOpenShell selector against the loaded model
• Apply camera (perspective and orthographic), clipping planes, and visibility mode
• Render a static PNG

CLI interface

ifc-url render "ifc://example.com/org/repo@abc123?path=model.ifc&selector=IfcWall&fov=60"
ifc-url render "ifc://example.com/org/repo@heads/main?path=model.ifc&camera=0,0,8,0,0,-1,0,1,0&scale=50"

Notes

• IfcOpenShell handles selector execution, model parsing, and geometry
• Rendering requires a headless approach; options include IfcOpenShell's own geometry processing with a software or headless OpenGL renderer
• Git access uses the platform credential store for HTTPS and ssh-agent or key files for SSH
• The CLI accepts the URL as a plain string so it can be called from non-Python contexts

---

Phase 2 — Preview service

Wrap the Phase 1 library in an HTTP service for use by Gitea and other consumers.

Endpoint

POST /preview
body: { url: "ifc://..." }
response: image/png

Caching

Tier	Cache key	Contents	Notes
2	commit hash	Parsed model structure	Shared across requests
3	commit hash + selector	Resolved GUID set
4	full URL hash	Rendered PNG	Not applied to mutable refs

Mutable refs (@heads/, @HEAD) must not be cached at tier 4 since the underlying commit may change. Commit hash refs are immutable and can be cached indefinitely at all tiers.

Authentication

• Co-located with Gitea — uses the requesting user's Gitea session token, passed from the Gitea plugin
• Standalone — sideloaded token configuration per git host

---

Phase 3 — Gitea integration

Add ifc:// link detection and preview embedding to Gitea.

Go plugin responsibilities

• Detect ifc:// links in post and comment content
• Call the preview service with the URL and the current user's session token
• Embed the returned PNG inline with a link that opens the URL
• Degrade gracefully when the preview service is unavailable (show the raw URL rather than failing)

Notes

• The plugin has no IFC awareness; all IFC logic lives in the preview service
• Repeated embeds of the same URL across different posts do not trigger re-renders — the preview service cache handles deduplication
• The preview service may run as a companion process on the same host or as a separately configured external service

---

Phase 4 — Bonsai integration

Add ifc:// handling to Bonsai.

Protocol handler

Register ifc:// as an OS protocol handler on installation (Windows, macOS, Linux). On receiving a URL, resolve the git source, load the model, and apply the view state from the URL parameters.

"Copy view URL"

A button that generates an ifc:// URL from the current Bonsai state:

• Git remote, ref, and file path of the open model
• Active selection converted to an IfcOpenShell selector
• Current camera converted to the camera + fov or scale format, in IFC world coordinates
• Active clipping planes as clip parameters
• Current visibility mode

The button always generates a commit hash ref by default. Generating a @heads/ ref is a secondary option for authoring links intended to track a branch.

Federation

When opening a model via ifc://, Bonsai resolves IFCDOCUMENTREFERENCE locations using the repo and ref from the root file's URL as context. ifc:// locations in linked model references are resolved recursively.

---

Phase 5 — IFC Viewer integration

Equivalent to Phase 4 for the IFC Viewer desktop application.

---

Phase 6 — Federation extension

Extend the IFCDOCUMENTREFERENCE location field in Bonsai to accept ifc:// URLs, enabling cross-repo and cross-server federation.

Tasks

• When saving a linked model reference, offer the option to write the location as an ifc:// URL rather than a relative path
• When a relative path would traverse above the repository root, prompt the user to convert it to an ifc:// URL
• Resolve ifc:// location fields through the Phase 4 URL resolver

The transformation matrix in IFCDOCUMENTREFERENCE is unaffected by this change. Phase 4 must be complete before this phase begins.

---

Future work

BCF export

An additional preview service endpoint returning a BCF file:

POST /bcf
body: { url: "ifc://..." }
response: application/zip

Resolves the selector to a GUID set and constructs a BCF viewpoint from the camera, clipping planes, and visibility state. No implementation is planned before Phase 2 is complete.

Web viewer integration

JavaScript integration with web-based IFC viewers (IFC.js, xeokit) and browser-side forum embedding. Not in current scope.

IfcOpenShell contribution

Once the Python core is stable, the URL parsing and resolution logic is a candidate for contribution to IfcOpenShell as a shared utility. This is not a prerequisite for any phase.