ifcurl/SPECIFICATION.md

IFC URL — Specification

1. Overview

IFC URL is a URL scheme for addressing a specific view of an IFC model stored in a Git repository. A single URL encodes the model source, an optional element selection, and an optional camera viewpoint.

The scheme identifier is ifc://.

---

2. Git source encoding

Transport inference

The git transport is inferred from the URL structure. No transport prefix is required.

URL form	Inferred transport
ifc://user@host/org/repo	SSH
ifc://host/org/repo	HTTPS
ifc:///path/to/repo	Local file

The presence of user@ userinfo signals SSH. A bare hostname signals HTTPS. An empty authority (triple slash) signals a local file path.

Credentials are never embedded in the URL. Authentication is handled by the platform's git credential store (desktop apps) or by sideloaded tokens (preview service).

SCP-style SSH addresses (git@host:org/repo) are normalised to ifc://git@host/org/repo when generating URLs.

Ref format

Refs follow git's namespace structure to prevent ambiguity between branches and tags that share a name.

Ref type	Form	Example
Branch	@heads/<name>	@heads/main
Tag	@tags/<name>	@tags/v1.2
Commit hash	@<hash>	@abc123def
Default branch	@HEAD	@HEAD

The @ character delimits the repository path from the ref. It is always present.

Full structure

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

---

3. Parameters

All parameters are optional. A URL with no parameters opens the model at its default view with no selection.

path

Path to the IFC file within the repository, relative to the repository root.

path=models/architectural/building.ifc

May be omitted when the target is a federated root file whose linked model references are defined within the IFC itself (see section 5).

selector

An IfcOpenShell selector expression, percent-encoded. The selector syntax is specified at:

https://docs.ifcopenshell.org/ifcopenshell-python/selector_syntax.html

Selectors are single-line expressions. Filters within a group are comma-separated; groups are joined with + for union.

selector=IfcWall
selector=IfcWall,+Name="Core+Wall"
selector=IfcWall+IfcSlab
selector=IfcWall,+Pset_WallCommon.FireRating=2HR
selector=325Q7Fhnf67OZC$$r43uzK

When omitted, no selection is applied.

camera

Nine comma-separated decimal values defining the camera in IFC world coordinates (see section 4):

camera=px,py,pz,dx,dy,dz,ux,uy,uz

Values	Meaning
px,py,pz	Camera position
dx,dy,dz	View direction vector (unit vector)
ux,uy,uz	Up vector (unit vector)

camera must be accompanied by either fov (perspective) or scale (orthographic). Their presence signals the projection type. Exactly one must be present if camera is present.

When camera is omitted entirely, the viewer fits the view to the selection if a selector is present, or shows the model's default view otherwise.

fov

Field of view in degrees. Signals perspective projection.

fov=60

scale

View-to-world scale. Signals orthographic projection. The value represents how many model units correspond to one unit in the normalised view, equivalent to BCF's ViewToWorldScale.

scale=50

clip

A clipping plane, defined by a point on the plane and a normal vector pointing toward the visible side. All values are in IFC world coordinates.

clip=px,py,pz,nx,ny,nz

Repeatable. Multiple clip parameters define the intersection of their half-spaces.

clip=0,0,3,0,0,-1&clip=0,0,0,0,0,1

visibility

Controls how selected and unselected elements are displayed.

Value	Behaviour
highlight	Show all elements, highlight selection (default)
ghost	Show selection normally, dim all other elements
isolate	Show only selected elements, hide all others

When omitted, highlight is assumed.

---

4. Coordinate system

All spatial values (camera, clip) are expressed in the IFC project's world coordinate system, consistent with BCF viewpoint conventions. Local coordinate systems, object placements, and georeferenced survey coordinates are not used.

Where an IFC file uses IfcMapConversion (IFC 4.1+) to define a georeferenced coordinate system, camera and clipping plane values remain in IFC world coordinates, not in the mapped survey coordinate system.

---

5. Federation

Federated models are referenced within the IFC file itself using IFCDOCUMENTINFORMATION with a LINKED_MODEL purpose, associated with the root IFCPROJECT entity via IFCRELASSOCIATESDOCUMENT. The location is carried in IFCDOCUMENTREFERENCE:

#46471=IFCDOCUMENTINFORMATION('X','model.ifc',$,$,$,$,'LINKED_MODEL',$,$,$,$,$,$,$,$,$,$);
#46472=IFCRELASSOCIATESDOCUMENT('0mypTfsjT...',$,$,$,(#10510),#46471);
#46473=IFCDOCUMENTREFERENCE('../conservatory-ifc/model.ifc','<4x4 matrix>',$,$,#46471);

The second field of IFCDOCUMENTREFERENCE is a 4x4 transformation matrix (sixteen comma-separated values) that positions the linked model in the shared coordinate system. This is resolved entirely by the viewer.

Location field values

The location field (first field of IFCDOCUMENTREFERENCE) supports:

• Relative path — resolved relative to the root IFC file's directory within the repository, using the same repo and ref context
• Absolute local path — resolved on the local filesystem (desktop use only)
• ifc:// URL — resolved as a full IFC URL, enabling cross-repo and cross-server federation

When a relative path would traverse above the repository root, an ifc:// URL must be used instead. This is the primary motivation for supporting ifc:// in the location field.

---

6. BCF interoperability

The camera and selection in an IFC URL map directly to BCF viewpoint concepts.

IFC URL to BCF viewpoint:

1. Resolve the selector against the model to obtain a set of GUIDs
2. Construct a BCF PerspectiveCamera or OrthogonalCamera from the camera parameters
3. Add clipping planes if present
4. Populate Components/Selection with the resolved GUIDs

BCF viewpoint to IFC URL:

1. Extract the GUID list from Components/Selection
2. Construct an IfcOpenShell GUID selector
3. Convert the BCF camera to camera, fov or scale parameters
4. Convert clipping planes to clip parameters

---

7. Viewer compliance

A compliant viewer must:

• Register ifc:// as an OS-level protocol handler
• Resolve the git source (repo, ref, path) and fetch the IFC file
• Resolve an IfcOpenShell selector against the loaded model
• Apply perspective camera (camera + fov)
• Apply orthographic camera (camera + scale)
• Apply clipping planes (clip)
• Apply visibility mode (highlight, ghost, isolate)
• Resolve relative IFCDOCUMENTREFERENCE paths using the root file's repo and ref context
• Resolve ifc:// IFCDOCUMENTREFERENCE locations

Optional extensions:

• Semantic colouring
• Advanced visual styles beyond the three visibility modes

---

8. Complete examples

Open a model at the default view:

ifc://example.com/org/project@heads/main?path=models/building.ifc

Perspective view of selected walls:

ifc://git@example.com/org/project@abc123def?path=models/building.ifc&selector=IfcWall,+Name="Core+Wall"&camera=10,20,5,0,-1,0,0,0,1&fov=60&visibility=ghost

Orthographic plan view at level 2 with a clipping plane:

ifc://example.com/org/project@tags/v2.0?path=models/building.ifc&camera=0,0,8,0,0,-1,0,1,0&scale=50&clip=0,0,5,0,0,-1

Local file, default branch:

ifc:///home/alice/projects/office@HEAD?path=model.ifc