bruno/ifcurl
1
0
Fork 0
mirror of https://github.com/brunopostle/ifcurl.git synced 2026-07-12 02:08:13 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: reorganise README to lead with Forgejo features

Browse source 
Move visual diffs, inline previews, viewer, and collaboration workflow to
the top. ifc:// URL spec, Python library, and preview service follow as
supporting detail. Add missing items: storey isolation, ref autocomplete,
visibility dropdown, /select and /render_diff endpoints, cache CLI.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Bruno Postle 2026-04-27 07:32:12 +01:00
parent 7e9e814a4b
commit 9c7b07e753
2 changed files with 130 additions and 194 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.beads/issues.jsonl
View file

@ -47,7 +47,7 @@
{"id":"ifcurl-5u6","title":"Evaluate replacing ifc_url.go markdown extension with JS injection","description":"ifc_url.go is a Goldmark AST extension that replaces ifc:// URLs in rendered markdown with preview figure elements (img + link). This requires patching and recompiling Forgejo. A JS alternative in footer.tmpl could handle the [title](ifc://...) markdown link case by scanning document.querySelectorAll('a[href^=\"ifc://\"]') and replacing matched anchors with figure elements at runtime — no Go changes needed. The limitation: bare ifc://... text in markdown won't be auto-linked by Goldmark (unknown scheme renders as plain text), so bare URLs would need text-node scanning in JS, which is fiddly and causes a render flash. Decision: replace with JS if users can commit to always using [title](ifc://...) link syntax; keep Go extension if bare URLs in markdown are a real use case.","status":"open","priority":3,"issue_type":"task","owner":"bruno@postle.net","created_at":"2026-04-27T06:05:32Z","created_by":"Bruno Postle","updated_at":"2026-04-27T06:05:32Z","dependency_count":0,"dependent_count":0,"comment_count":0}
{"id":"ifcurl-71f","title":"Extract footer.tmpl JS into a separate ifcurl.js asset file","description":"footer.tmpl is 200 lines of JavaScript wrapped in a single \u003cscript\u003e tag. Moving it to /var/lib/forgejo/custom/public/assets/ifcurl.js (served at /assets/ifcurl.js) would reduce footer.tmpl to a one-liner \u003cscript src='/assets/ifcurl.js'\u003e\u003c/script\u003e. Benefits: proper editor syntax highlighting and linting, no HTML-escaping concerns, cleaner separation of concerns. Two files to deploy instead of one, but that's manageable.","status":"open","priority":3,"issue_type":"task","owner":"bruno@postle.net","created_at":"2026-04-27T06:05:05Z","created_by":"Bruno Postle","updated_at":"2026-04-27T06:05:05Z","dependency_count":0,"dependent_count":0,"comment_count":0}
{"id":"ifcurl-5a6","title":"viewer: wrap ifc:// text in anchor tags for future browser URL handler","description":"At some point we will register a browser protocol handler for ifc:// URLs so they can open desktop tools (Bonsai etc). In preparation, all ifc:// URLs generated alongside embedded snapshots should be wrapped in \u003ca href=\"ifc://...\"\u003e anchor tags. Currently they will not do anything (no handler registered), but having them as links now means the UI is ready when the handler exists, and users can at least see and copy the URL.","status":"closed","priority":3,"issue_type":"task","assignee":"Bruno Postle","owner":"bruno@postle.net","created_at":"2026-04-27T05:36:42Z","created_by":"Bruno Postle","updated_at":"2026-04-27T05:59:25Z","started_at":"2026-04-27T05:39:30Z","closed_at":"2026-04-27T05:59:25Z","close_reason":"Closed","dependency_count":0,"dependent_count":1,"comment_count":0}
{"id":"ifcurl-tga","title":"docs: reorganise README to lead with Forgejo features","description":"The project is now primarily a Forgejo mod that enables IFC previews in commit and PR pages. The README should lead with what this enables for users (embedded snapshots, visual diffs, clickable model links), then move into the ifc:// URL specification as the technical foundation. The current README leads with the URL spec which buries the headline feature.","status":"open","priority":3,"issue_type":"task","owner":"bruno@postle.net","created_at":"2026-04-27T05:36:41Z","created_by":"Bruno Postle","updated_at":"2026-04-27T05:36:41Z","dependency_count":0,"dependent_count":0,"comment_count":0}
{"id":"ifcurl-tga","title":"docs: reorganise README to lead with Forgejo features","description":"The project is now primarily a Forgejo mod that enables IFC previews in commit and PR pages. The README should lead with what this enables for users (embedded snapshots, visual diffs, clickable model links), then move into the ifc:// URL specification as the technical foundation. The current README leads with the URL spec which buries the headline feature.","status":"closed","priority":3,"issue_type":"task","assignee":"Bruno Postle","owner":"bruno@postle.net","created_at":"2026-04-27T05:36:41Z","created_by":"Bruno Postle","updated_at":"2026-04-27T06:31:47Z","started_at":"2026-04-27T06:07:49Z","closed_at":"2026-04-27T06:31:47Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
{"id":"ifcurl-0n8","title":"viewer: storey filter has no 'show all' / reset option","description":"Clicking a storey row in the model overview panel isolates that storey via hider.isolate(). There is no way to reset back to the full model view. Clicking the active storey row should toggle it off (show all), and/or a 'show all' button should appear at the top of the Storeys section when a storey is active. Note: the storey click handler at line ~1016 already has toggle-off logic (if activeRow === row → hider.set(true)) but it only works if you click the same row a second time — the bug is that clicking a different storey, then trying to go back, leaves no 'all storeys' option visible.","status":"closed","priority":3,"issue_type":"bug","assignee":"Bruno Postle","owner":"bruno@postle.net","created_at":"2026-04-26T07:33:19Z","created_by":"Bruno Postle","updated_at":"2026-04-26T08:40:03Z","started_at":"2026-04-26T08:01:13Z","closed_at":"2026-04-26T08:40:03Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
{"id":"ifcurl-21x","title":"viewer: smooth transition when URL settings change","description":"Changing the visibility dropdown, selector, or other settings triggers a full page reload, causing the screen to go blank for several seconds while the model re-fetches and re-parses. Options: (a) CSS fade-in on load only — minimal change; (b) capture canvas snapshot before navigate and show as placeholder during reload; (c) in-place model reload without page navigation — best UX but requires refactoring main() to support hot-reload. Option (b) requires preserveDrawingBuffer:true in the WebGL renderer.","status":"closed","priority":3,"issue_type":"feature","assignee":"Bruno Postle","owner":"bruno@postle.net","created_at":"2026-04-26T07:13:24Z","created_by":"Bruno Postle","updated_at":"2026-04-26T07:17:15Z","started_at":"2026-04-26T07:15:10Z","closed_at":"2026-04-26T07:17:15Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
{"id":"ifcurl-npy","title":"viewer: add zoom-all / reset-view button","description":"When the camera has panned or zoomed away from the building, there is no way to get back to a full view of the model. Add a 'zoom all' or 'reset view' button in the toolbar that calls cameraControls.fitToBox(model.box, true) to fit the entire model back in view.","status":"closed","priority":3,"issue_type":"feature","assignee":"Bruno Postle","owner":"bruno@postle.net","created_at":"2026-04-26T07:12:59Z","created_by":"Bruno Postle","updated_at":"2026-04-26T07:17:14Z","started_at":"2026-04-26T07:15:07Z","closed_at":"2026-04-26T07:17:14Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}

322
README.md
View file

@ -1,50 +1,151 @@
# ifcurl
**ifcurl** is a URL scheme, tools, and server integration for addressing shareable views of IFC building models stored in git repositories.
**ifcurl** is a Forgejo mod that adds 3D model awareness to BIM workflows on git. When IFC files are committed or compared, diff pages show colour-coded visual renders of what changed. Paste an `ifc://` URL into any issue, PR comment, or markdown file and Forgejo renders it as a linked preview image. Every preview is a clickable link that opens the model in an interactive WebGL viewer at the exact viewpoint encoded in the URL.
---
## What you get
### Visual diffs on commit and PR pages
When an `.ifc` file changes in a commit or pull request, the diff page automatically shows a rendered snapshot of the change — added geometry in green, removed in red. The image links directly to the 3D viewer at the head version of the file, and the `ifc://` URL for that view is shown below the image.
### Inline previews in markdown
Paste a bare `ifc://` URL or write `[label](ifc://…)` in any issue, PR comment, or `.md` file:
```
ifc://github.com/brunopostle/simple-ifc@heads/main?path=building.ifc&selector=IfcWall&fov=60
```
An `ifc://` URL encodes everything needed to reproduce a specific model view: the git source, the file, which elements to show, and the camera position. Like a permalink for BIM — paste it, share it, embed it in documentation.
Forgejo renders it as a `<figure>` with a preview image linked to the interactive viewer, and the `ifc://` URL shown below as a clickable link.
### "View in 3D" button
A **View in 3D** button appears on every `.ifc` file page alongside Raw / Permalink / History.
### Browser viewer
A self-contained WebGL IFC viewer (`viewer.html`) served as a Forgejo asset at `/assets/viewer.html`.
**Features:**
- Toolbar with raw ifc:// URL input and structured fields (repo, ref, path, selector) — editing any field reloads the model; ref input has branch/tag autocomplete
- Selector filtering — `IfcWall`, `IfcWall+IfcSlab`; visibility dropdown (`highlight` / `ghost` / `isolate`) for non-selected elements
- Clipping planes — **✂ clip** button, double-click on model surface to place; drag handles to adjust; planes serialised back into the URL
- FOV control, camera sync — the URL in the browser bar always reflects the current view and is shareable
- **Model overview panel** — type counts and storey list; click any storey to isolate it, click again to show all
- **Click to identify** — click any element to see its IFC type, name, and GlobalId; copy GlobalId to clipboard for use in selectors
- **⎘ copy** button — copies the current ifc:// URL to clipboard
- **Issue** button — opens a new issue on the git host with the ifc:// URL pre-filled
- **BCF export** — exports the current view as a BCF 2.1 file for import into Revit, Navisworks, etc.
- Drag-and-drop ifc:// URLs onto the page
- Download progress for large IFC files
### Collaboration workflow
`ifc://` URLs function as view permalinks that can be embedded anywhere: Forgejo issues and comments, pull request discussions, markdown documentation, Slack, or email.
1. Open the viewer and navigate to the view you want to share
2. Add clipping planes or a selector to isolate the relevant geometry
3. Click **⎘** to copy the ifc:// URL, or **Issue** to open a pre-filled issue
4. Paste the URL into a Forgejo issue, PR comment, or any markdown file
**Referencing specific elements:** click any element to see its GlobalId, then paste it directly as `selector=325Q7Fhnf67OZC$$r43uzK`. Use `visibility=highlight`, `ghost`, or `isolate` to control how the selection is displayed.
**BCF export for external tools:** the **BCF** button exports a BCF 2.1 file that can be attached to a Forgejo issue or imported into Revit, Navisworks, Solibri, or any BCF-compatible tool.
---
## Architecture
## Forgejo integration
Four interlocking components:
A source patch and set of assets for Forgejo. See [`forgejo/README.md`](forgejo/README.md) for full apply, build, and deployment instructions.
| Component | Language | What it does |
|---|---|---|
| **Python library + CLI** | Python | Parse ifc:// URLs, fetch IFC from git, render PNG |
| **Preview service** | Python | HTTP server — PNGs on demand |
| **Forgejo integration** | Go + assets | Inline markdown previews, "View in 3D" button |
| **Browser viewer** | JavaScript | Interactive WebGL viewer, served as a Forgejo asset |
### Quick setup
```
Markdown source:
[Section cut](ifc://host/org/repo@heads/main?path=building.ifc&clip=0,0,3,0,0,-1)
│
Forgejo renders (via Go patch): │
<figure> │
<img src="/preview?url=..."> ──────┤── preview service renders PNG
<a href="/assets/viewer.html?url=…"> browser viewer (WebGL, interactive)
</figure>
```bash
# Apply the Go source patch
cp forgejo/modules/markup/markdown/ifc_url{,_test}.go /path/to/forgejo/modules/markup/markdown/
cd /path/to/forgejo && git apply /path/to/ifcurl/forgejo/go.patch
# Build Forgejo
go build -tags 'sqlite sqlite_unlock_notify' \
-ldflags "-X 'forgejo.org/modules/setting.StaticRootPath=/usr/share/forgejo'" \
-o forgejo . && sudo cp forgejo /usr/bin/forgejo
# Deploy assets (no rebuild needed)
sudo cp forgejo/custom/public/assets/viewer*.* /etc/forgejo/public/assets/
sudo cp forgejo/templates/custom/footer.tmpl /var/lib/forgejo/custom/templates/custom/
sudo systemctl restart forgejo
# Install and start preview service as a systemd unit
sudo cp forgejo/server-config/ifcurl-preview.service /etc/systemd/system/
# edit ExecStart --allowed-hosts to match your Forgejo hostname, then:
sudo systemctl enable --now ifcurl-preview
```
The viewer is also reachable directly — paste or type an `ifc://` URL into its toolbar, or drag one onto the page.
Add to `/etc/forgejo/conf/app.ini`:
```ini
[ifcurl]
PREVIEW_SERVICE_URL = http://localhost:8000
; Optional: Forgejo API token for a read-only machine user.
; The preview service will use this token to fetch IFC files from private
; repositories on this Forgejo instance. The token is appended as a query
; parameter in the <img src> URL generated by the markdown extension, so it
; is visible in page source. Only set this on trusted private instances.
; SERVICE_TOKEN = <forgejo-api-token>
```
**Private repositories:** create a machine user with read access and set `SERVICE_TOKEN` to its API token. Alternatively, configure credentials in `~/.config/ifcurl/tokens.json` under the service user account.
### Authentication in the viewer
When the viewer is served from the same Forgejo instance (`https://git.example.com/assets/viewer.html`), it shares the browser session cookie — private repositories work automatically for authenticated users.
IFC files on other platforms (GitHub, GitLab, a different Forgejo instance) are fetched directly from the browser; only public repositories work for external hosts.
### Preview service
An HTTP service that renders `ifc://` URLs to PNG, intended for co-location with a Forgejo instance.
```bash
pip install "ifcurl[service]"
ifcurl serve --allowed-hosts git.example.com # restrict to your Forgejo host
ifcurl serve --host 0.0.0.0 --port 9000 --allowed-hosts git.example.com
```
| Endpoint | Description |
|---|---|
| `POST /preview` | Render an ifc:// URL to PNG |
| `GET /preview?url=ifc://…` | Same, via query string (used by Forgejo `<img>` tags) |
| `POST /bcf` | Generate a BCF 2.1 zip from an ifc:// URL viewpoint |
| `GET /select?url=ifc://…` | Resolve a complex selector server-side; returns JSON list of GlobalIds |
| `GET /render_diff?base=ifc://…&head=ifc://…` | Render a colour-coded diff PNG (added green, removed red) |
**Caching:**
| Tier | Key | Contents | Notes |
|---|---|---|---|
| 2 | commit hash + path | IFC bytes | In-memory LRU |
| 3 | commit hash + path + selector | Resolved element set | In-memory LRU |
| 4 | SHA-256 of full URL | Rendered PNG | Filesystem; immutable refs only |
Tier 4 is never written for mutable refs (`@heads/`, `@HEAD`).
---
## ifc:// URL scheme
An `ifc://` URL encodes everything needed to reproduce a specific model view: the git source, the file, which elements to show, and the camera position. Like a permalink for BIM — paste it, share it, embed it in documentation.
Full specification: [`SPECIFICATION.md`](SPECIFICATION.md)
```
ifc://[user@]host/org/repo@<ref>?<parameters>
```
Transport is inferred from the URL structure — no prefix needed:
Transport is inferred from the URL structure:
| URL form | Transport |
|---|---|
@ -83,6 +184,11 @@ Fetch an IFC file from a git repository and render it to PNG.
pip install "ifcurl[render]"
ifcurl render "ifc://github.com/brunopostle/simple-ifc@heads/main?path=_test_simple.ifc"
ifcurl render "ifc://..." -o output.png
# Manage the local git repository cache
ifcurl cache list # show cached repos with size and last-access time
ifcurl cache prune --max 5 # remove oldest repos until cache is under 5 GB
ifcurl cache clear # remove all cached repos
```
Use as a library:
@ -103,13 +209,9 @@ png = render(model, selector=url.selector, clips=url.clips or None,
camera=url.camera, fov=url.fov, visibility=url.visibility)
```
Remote repositories are cloned as bare repos to the OS cache directory
(`~/.cache/ifcurl/` on Linux) on first use. Mutable refs (`@heads/`, `@HEAD`)
trigger a `git fetch`; immutable refs (commit hashes, tags) use the cache
as-is.
Remote repositories are cloned as bare repos to the OS cache directory (`~/.cache/ifcurl/` on Linux) on first use. Mutable refs (`@heads/`, `@HEAD`) trigger a `git fetch`; immutable refs (commit hashes, tags) use the cache as-is.
For private repositories, configure tokens per host in
`~/.config/ifcurl/tokens.json`:
For private repositories, configure tokens per host in `~/.config/ifcurl/tokens.json`:
```json
{ "hosts": { "github.com": "ghp_…", "gitlab.example.com": "glpat_…" } }
@ -117,172 +219,6 @@ For private repositories, configure tokens per host in
---
## Preview service
An HTTP service that renders `ifc://` URLs to PNG, intended for co-location
with a Forgejo/Gitea instance.
```bash
pip install "ifcurl[service]"
ifcurl serve --allowed-hosts git.example.com # restrict to your Forgejo host
ifcurl serve --host 0.0.0.0 --port 9000 --allowed-hosts git.example.com
```
Pass `--allowed-hosts` as a comma-separated list of hostnames (with optional
`:port`) the service is allowed to fetch from. This prevents the preview
endpoint from being used to reach internal services. Omitting it allows all
non-private remote hosts.
### Endpoints
| Endpoint | Description |
|---|---|
| `POST /preview` | Render an ifc:// URL to PNG |
| `GET /preview?url=ifc://…` | Same, via query string (used by Forgejo `<img>` tags) |
| `POST /bcf` | Generate a BCF 2.1 zip from an ifc:// URL viewpoint |
### Caching
| Tier | Key | Contents | Notes |
|---|---|---|---|
| 2 | commit hash + path | IFC bytes | In-memory LRU |
| 3 | commit hash + path + selector | Resolved element set | In-memory LRU |
| 4 | SHA-256 of full URL | Rendered PNG | Filesystem; immutable refs only |
Tier 4 is never written for mutable refs (`@heads/`, `@HEAD`).
---
## Forgejo integration
A source patch for Forgejo that adds:
- **Inline markdown preview** — `[label](ifc://…)` and bare `ifc://…` in
markdown render as `<figure>` preview images linked to the browser viewer.
- **"View in 3D" button** — appears on `.ifc` file view pages alongside Raw /
Permalink / History.
- **Browser viewer asset** — `viewer.html` + `viewer-url.js` served at
`/assets/viewer.html`.
See [`forgejo/README.md`](forgejo/README.md) for full apply, build, and
deployment instructions.
### Quick summary
```bash
# Apply the Go source patch
cp forgejo/modules/markup/markdown/ifc_url{,_test}.go /path/to/forgejo/modules/markup/markdown/
cd /path/to/forgejo && git apply /path/to/ifcurl/forgejo/go.patch
# Build Forgejo
go build -tags 'sqlite sqlite_unlock_notify' \
-ldflags "-X 'forgejo.org/modules/setting.StaticRootPath=/usr/share/forgejo'" \
-o forgejo . && sudo cp forgejo /usr/bin/forgejo
# Deploy assets (no rebuild needed)
sudo cp forgejo/custom/public/assets/viewer*.* /etc/forgejo/public/assets/
sudo cp forgejo/templates/custom/footer.tmpl /var/lib/forgejo/custom/templates/custom/
sudo systemctl restart forgejo
# Install and start preview service as a systemd unit
sudo cp forgejo/server-config/ifcurl-preview.service /etc/systemd/system/
# edit ExecStart --allowed-hosts to match your Forgejo hostname, then:
sudo systemctl enable --now ifcurl-preview
```
Add to `/etc/forgejo/conf/app.ini`:
```ini
[ifcurl]
PREVIEW_SERVICE_URL = http://localhost:8000
; Optional: Forgejo API token for a read-only machine user.
; The preview service will use this token to fetch IFC files from private
; repositories on this Forgejo instance. The token is appended as a query
; parameter in the <img src> URL generated by the markdown extension, so it
; is visible in page source. Only set this on trusted private instances.
; SERVICE_TOKEN = <forgejo-api-token>
```
**Private repositories:** for the preview service to access private repos on
this Forgejo instance, create a machine user with read access and set
`SERVICE_TOKEN` to its API token. The service will use this token when
fetching IFC files server-side. Alternatively, configure the preview service's
own credentials in `~/.config/ifcurl/tokens.json` under the service user
account — the service already reads host tokens from that file on startup.
---
## Browser viewer
A self-contained WebGL IFC viewer (`viewer.html`) built on
[`@thatopen/components`](https://github.com/ThatOpenCompany/that-open-engine).
No build step — loads dependencies from CDN.
**Features:**
- Toolbar with raw ifc:// URL input and structured fields (repo, ref, path,
selector) — editing any field reloads the model
- Selector filtering — `IfcWall`, `IfcWall+IfcSlab` (type-name union only in the
browser viewer; full IfcOpenShell attribute/property filters are applied
server-side by the preview service and are reflected in the URL but not
applied visually in the viewer)
- Clipping planes — `✂ clip` button, double-click on model surface to place;
drag handles to adjust; planes serialised back into the URL
- FOV control, camera sync — the URL in the browser bar always reflects the
current view and is shareable
- Drag-and-drop ifc:// URLs onto the page
- **Click to identify** — click any element to see its IFC type, name, and
GlobalId in a side panel; copy GlobalId to clipboard for use in selectors
- **⎘ copy** button — copies the current ifc:// URL to clipboard
- **Issue** button — opens a new issue on the git host with the ifc:// URL
pre-filled in the body (works for Forgejo, GitHub, GitLab)
- **BCF export** — exports the current view (camera, clipping planes, selected
elements) as a BCF 2.1 file for import into Revit, Navisworks, etc.
- Download progress — shows percentage or MB while fetching large IFC files
### Collaboration workflow
`ifc://` URLs function as view permalinks that can be embedded anywhere:
Forgejo issues and comments, pull request discussions, markdown documentation,
Slack, or email.
**Basic flow:**
1. Open the viewer and navigate to the view you want to share
2. Add clipping planes or a selector to isolate the relevant geometry
3. Click **⎘** to copy the ifc:// URL, or **Issue** to open a pre-filled issue
4. Paste the URL into a Forgejo issue, PR comment, or any markdown file —
Forgejo will render it inline as a linked preview image
**Referencing specific elements:**
Click any element to see its GlobalId. Copy the GlobalId and paste it directly
as the `selector=` value — a bare 22-character GlobalId selects that one element
(e.g., `selector=325Q7Fhnf67OZC$$r43uzK`). Use `visibility=highlight`, `ghost`,
or `isolate` to control how the selection is displayed.
**BCF export for external tools:**
Use the **BCF** button to export a BCF 2.1 file. The resulting `.bcf` can be
attached to a Forgejo issue as a file, or imported into Revit, Navisworks,
Solibri, or any BCF-compatible tool to communicate the exact viewpoint and
element selection to contractors or consultants using proprietary software.
### Authentication
When the viewer is served from the same Forgejo instance
(`https://git.example.com/assets/viewer.html`), it shares the browser session
cookie. Any IFC file that the logged-in user can access on that Forgejo instance
loads without extra configuration — private repositories work automatically for
authenticated users.
IFC files hosted on other platforms (GitHub, GitLab, a different Forgejo
instance) are fetched directly from the browser. Only public repositories work
for external hosts; there is currently no authentication path for external
private repositories in the browser viewer.
---
## Development
```bash