Design: URLs

Share uses URLs for precise link sharing of model and application state.

We adopt a URL structure similar to Google Apps URL structure:

  http://<host>/<app>/<view>/<model>

Here are some examples for the current host='bldrs.ai', with app='share', view='v' and model='p/index.ifc' or its GitHub equivalent:

  http://bldrs.ai/share/v/p/index.ifc

When the user first visits:

  http://bldrs.ai

they are automatically navigated to the project logo:

  https://bldrs.ai/share/v/p/index.ifc#c:-111.37,14.94,90.63,-43.48,15.73,-4.34

If the path refers to an IFC file the IFC.js loader is used to load the file path and display it.

Model

Models can be either local or remote.

Hosting: Local:

http://host/share/v/p/index.ifc

Here, index.ifc is in the root serving (build) folder of the application, i.e. /docs/index.ifc.

Hosting: GitHub:

http://host/share/v/gh/...

GitHub Paths

GitHub repos are referenced by organization and repository name, followed by branch and version information and “public” for something. To begin with we’ll just support public main branch.

http://host/share/v/gh/<org>/<repo>/<branch>/<filename>

E.g.:

http://host/share/v/gh/bldrs-ai/Share/main/public/index.ifc

The segment “bldrs-ai/Share/main/public/index.ifc” triggers an HTTP fetch to:

http://raw.githubusercontent.com/bldrs-ai/Share/main/public/index.ifc

GitHub Versions

This file:

https://github.com/OlegMoshkovich/Bldrs_Plaza/commits/main/IFC_STUDY.ifc

Has multiple versions, that can be referenced directly by git sha hash path:

v1 https://github.com/OlegMoshkovich/Bldrs_Plaza/blob/5f424a0869345649d78f819d365ea642c4789458/IFC_STUDY.ifc
v2 https://github.com/OlegMoshkovich/Bldrs_Plaza/blob/4566a63cc29a0c7673db8ba992d597b16a671b87/IFC_STUDY.ifc
...

Element Reference

Elements in IFC models are have unique IDs for each element in the building. Adding an ID to the model gives an Element Reference.

https://host/share/v/p/index.ifc/84

Element Path

Appending a sequence of Element IDs to the model path gives an Element Path.

https://host/share/v/p/index.ifc/84/103/138/160

Note, the path is purely navigational, showing containment structure of each element with its parent and children. Meaning, the following two paths are equivalent Element References, but the first URL shows the a:

https://host/share/v/p/index.ifc/84/103/138/160
https://host/share/v/p/index.ifc/160

Search

Search params are anchored on a model or element path:

https://host/share/v/p/index.ifc?q=wall
https://host/share/v/p/index.ifc/84/103?q=wall

GUID search

Raw GUIDs may be searched directly as query strings

# The front box in the Bldrs logo:
https://host/share/v/p/index.ifc?q=2IenVgx2bDVfGVjVGJn15E

State Tokens

Share maintains navigation state in the URL.

Syntax

::  param separator
:   label-value separator
,   list of values separator
=   named value assignment

e.g.
https://host/share/v/p/index.ifc#c:1,2,3::p:x=1.234,z=2.345

Feature State Tokens

Each feature that controls navigation stores its state with a unique prefix. Current prefixes are:

"c": camera
"i": issues
"m": placemark
"p": cut-plane

Camera Token

The camera token encodes the camera position and the target look at position, e.g.:

https://bldrs.ai/share/v/p/index.ifc#c:-111.37,14.94,90.63,-43.48,15.73,-4.34

Issue Token

The issue token encodes the currently active Note, which should be displayed next to the scene, e.g.:

https://bldrs.ai/share/v/p/index.ifc#i:1234

In the current implementation, this issue is also backed by a GitHub issue with the same ID.

Placemark Token

The placemark token encodes the x,y,z location of a place in the scene, marked by an in-scene icon:

https://bldrs.ai/share/v/p/index.ifc#m:1.1,2.2,3.3

There maybe be many placemarks in the scene, but only 1 currently active. The currently active placemark will have a visually emphasized icon. The default icon for the rest will be visually present, but deemphasized.

Possible extensions:

TODO(pablo)...

Maybe multiple active tokens in a single URL?
Maybe optional text label, e.g. m:1,2,3,Hello%20World

Cut-Plane Token

The cut-plane token encodes the currently active cut planes, which reveal cross-sections of the model, e.g.:

https://bldrs.ai/share/v/p/index.ifc#p:y=-5.28,z=5.515

Each cut-plane may be active independent of the others, so a coordinate order is insufficient and the name of the plane must be present to disambiguate.

Application State Tokens

Embedded applications should use a State Token to refer to their state. State Tokens are required for Cross-session persistence.

Small amounts of state should be directly encoded as parameters, e.g. with camera, which includes the coordinates. This state is implicitly persistent across sessions.

Larger amounts of state should be stored in browser datastructures or services, such as IndexedDB, or in Application backends. The State Token can be used as the primary key for CRUD operations against backend stores, but that is the responsibility of the Application author.

Part of URLs.

Bldrs is using a ?feature=<feature name> query param to enable experimental features and allow for progressive launch of complex features.

Feature Flags

Apps

This enables Apps, a Side Drawer for an embedded iframe containing an app that interacts with the Share app.

Status: Work in progress. See these PRs.

Flag: ?feature=apps

e.g.:

https://bldrs.ai/share/v/gh/pablo-mayrgundter/freality/master/bldrs/example.ifc?feature=apps

Then click the App Store button to open the drawer:

Placemarks

This enables placemarks to be created in Notes and added to the scene, a la Google Maps.

Status: Work in progress. See #599.

Flag: ?feature=placemark