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 3b — Web IFC viewer

Add a 3D viewer that opens in a separate browser window when viewing an .ifc file in Forgejo.

Architecture

• Forgejo Go patch: when rendering the file view for a .ifc file, inject a "View in 3D" button that opens http://localhost:8000/viewer?url=ifc://... in a new tab. The ifc:// URL encodes the current host, repo, ref, and file path.

• /viewer endpoint in the ifcurl preview service: returns a self-contained HTML page. No server-side IFC processing — the browser does all rendering.

• Browser rendering: the viewer page loads @thatopen/components (and its web-ifc + Three.js peer dependencies) from a CDN via an ES module importmap. It constructs the Forgejo raw file URL from the ifc:// URL parameters and fetches the IFC bytes directly from Forgejo.

Current scope (Phase 3b)

• Display the full model for whatever ref is shown in Forgejo.
• Basic orbit/pan/zoom camera controls.
• No filtering or selection UI yet.

Future scope

• Element filtering and selection using @thatopen/components classifier and highlighter APIs.
• Camera state serialised to an ifc:// URL so the user can copy a view link (feeds into Phase 4 Bonsai "Copy view URL").
• Diff highlighting driven by ifcmerge output (see Phase 3c).

---

Phase 3c — ifcmerge integration

ifcmerge is a git custom merge driver that resolves conflicts in .ifc files that git's built-in 3-way merge cannot handle. Where two branches have both modified an IFC file (a fork), git would report an unresolvable conflict; ifcmerge performs a semantics-aware merge and produces a valid merged IFC file.

Git merge driver configuration

Register ifcmerge as the git merge driver for .ifc files on the Forgejo server:

# /etc/gitconfig or ~forgejo/.gitconfig
[merge "ifcmerge"]
    name = IFC merge driver
    driver = ifcmerge %O %A %B %L

# .gitattributes in each repo, or server-side gitattributes
*.ifc merge=ifcmerge

With this in place, Forgejo's existing "merge automatically" path will invoke ifcmerge via git when merging .ifc files, and the PR merge button will work without any Go-side changes for the common case.

Forgejo integration

• Verify that Forgejo's merge-ability check (the "these branches can be merged automatically" indicator) correctly reflects ifcmerge's ability to merge .ifc files — investigate whether the check runs a trial merge via git or uses a heuristic.
• If needed, patch Forgejo to run a trial git merge --no-commit to get an accurate result for IFC files.

3D diff view (future)

• After a merge completes, surface a "View merge in 3D" button in the PR using the Phase 3b viewer.
• Use @thatopen/components highlighter to colour added, removed, and modified elements differently, driven by comparing the merged IFC against either parent.

---

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.