mirror of https://github.com/brunopostle/ifcurl.git synced 2026-07-12 02:08:13 +00:00

Bruno Postle 7e83c00487 Python core library and ifcurl CLI

- URL parser (IfcUrl) handling all ifc:// forms: SSH, HTTPS, local;
  all ref types; camera, selector, clip, visibility parameters
- Git fetcher using GitPython with OS-appropriate bare-clone cache
  (platformdirs) and fetch-on-mutable-ref behaviour
- Renderer adapted from ifcquery: explicit camera, clipping planes,
  highlight/ghost/isolate visibility modes, type entity support
- ifcurl CLI: `ifcurl render "<url>" [-o output.png]`
- LICENSE file (LGPLv3+)

Generated with the assistance of an AI coding tool.

2026-04-15 21:24:35 +01:00

2.9 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

pip install -e ".[render]"       # install with rendering dependencies
python -m pytest tests/          # run all tests
python -m pytest tests/test_url.py -v  # run URL parser tests
ifcurl render "ifc://..."       # render a URL to ifcurl-render.png
ifcurl render "ifc://..." -o out.png

Project overview

ifcurl implements the ifc:// URL scheme — a way to address a specific view of an IFC model stored in a Git repository. A single URL encodes the git source, an optional IfcOpenShell selector, and an optional camera viewpoint.

Full spec: SPECIFICATION.md. Full development plan: PLAN.md.

URL structure

ifc://[user@]host/org/repo@<ref>?<parameters>

Transport is inferred: user@host → SSH, bare host → HTTPS, empty authority (ifc:///path) → local file. Refs use git namespace form: @heads/<branch>, @tags/<tag>, @<hash>, @HEAD.

Key query parameters: path (IFC file in repo), selector (IfcOpenShell selector expression), camera (9 floats: position, direction, up), fov (perspective) or scale (orthographic), clip (repeatable clipping plane, 6 floats), visibility (highlight/ghost/isolate).

Development phases

Phase	Description	Language
1	Python core library + CLI	Python
2	HTTP preview service with caching	Python
3	Gitea plugin for inline preview embedding	Go
4	Bonsai integration (OS protocol handler + "Copy view URL")	Python
5	IFC Viewer integration	Python
6	`IFCDOCUMENTREFERENCE` federation extension	Python

Phase 1 is the foundation for all other phases. Phases 3–6 cannot begin until Phase 1 exists.

Phase 1 — Python core responsibilities

Parse ifc:// URL into components
Infer git transport and fetch the IFC file at the specified ref
Execute an IfcOpenShell selector against the loaded model
Apply camera, clipping planes, and visibility mode
Render a static PNG (headless / software OpenGL)

CLI entry point: ifcurl render "<url>"

Caching (Phase 2)

Tier 2: commit hash → parsed model structure (shared across requests)
Tier 3: commit hash + selector → resolved GUID set
Tier 4: full URL hash → rendered PNG (never applied to mutable refs like @heads/ or @HEAD)

Key domain facts

All spatial values (camera, clip) are in IFC world coordinates, matching BCF viewpoint conventions — not georeferenced survey coordinates.
The selector parameter uses IfcOpenShell selector syntax. + joins selector groups (union); , separates filters within a group.
IFCDOCUMENTREFERENCE location fields may be relative paths (resolved within the same repo/ref), absolute local paths (desktop only), or ifc:// URLs (cross-repo federation).
BCF ↔ IFC URL conversion is defined in SPECIFICATION.md §6.

2.9 KiB Raw Blame History Unescape Escape