stream: Guerilla Standardisation
area: Internet
status: informational
author: Leon van Kammen
workgroup: Internet Engineering Task Force
value: XRFRAGMENTS-leonvankammen-00
Abstract
Version: 0.6
An open specification for hyperlinking & deeplinking 3D fileformats.
This is a specification for interactive URI-controllable 3D files, to enable spatial webs for local-first XR hypermedia browsers.
XR Fragments allows us to better use implicit metadata inside 3D scene(files), by mapping it to proven technologies like URI Fragments.
Almost every idea in this document is demonstrated at https://xrfragment.org
Introduction
How can we add more control to existing text and 3D scenes, without introducing new dataformats?
Historically, there's many attempts to create the ultimate 3D fileformat.
The lowest common denominator is: designers describing/tagging/naming things using plain text.
XR Fragments exploits the fact that all 3D models & markuplanguages already contain such metadata:
** Deeplinking 3D objects by mapping objectnames to URI fragments**
For a better-readable, better-updated spec see the website https://xrfragment.org
How does it work
XR Fragments utilizes URLs on various levels:
- for 3D viewers/browser to manipulate the camera or objects of a 3D scene (via URI fragments)
- implicitly: by mapping 3D objectnames (of a 3D scene/file) to URI fragments (3D deeplinking)
- explicitly: by scanning
hrefmetadata inside 3D scene-files to enable interactions - explicitly: by scanning for XR hints metadata inside 3D scene-files to distinguish contextual rendering (AR vs VR e.g.)
- externally: progressively enhance a 3D (file) into an experience via sidecarfiles
Aspect 1 was pioneered and implemented by JanusXR / James Baicoianu via janusweb well before the formal specification was established. As a key architect of these early concepts, James’s work laid the groundwork for the standard we use today. We owe him a great deal of thanks for his early contributions.
Applications can adopt XR Fragments at various levels, depending on application needs. However, Level1 is considered the soul of XR fragments: other levels are optional and not required to consider something 'XR Fragment compatible' (3D objects & camera reference-able via URL).
Spatial Referencing 3D objects
3D files/scenes contain an hierarchy of objects.
XR Fragments assumes the following objectname-to-URI-Fragment mapping, in order to deeplink 3D objects:
my.io/scene.fbx (or my.io/scene.html delivering a three.js scene)
+─────────────────────────────+
│ sky │ src: http://my.io/scene.fbx#sky (includes building,mainobject,floor)
│ +─────────────────────────+ │
│ │ building │ │ src: http://my.io/scene.fbx#building (includes mainobject,floor)
│ │ +─────────────────────+ │ │
│ │ │ mainobject │ │ │ src: http://my.io/scene.fbx#mainobject (includes floor)
│ │ │ +─────────────────+ │ │ │
│ │ │ │ floor │ │ │ │ src: http://my.io/scene.fbx#floor (just floor object)
│ │ │ │ │ │ │ │
│ │ │ +─────────────────+ │ │ │
│ │ +─────────────────────+ │ │
│ +─────────────────────────+ │
+─────────────────────────────+
Every 3D fileformat supports named 3D objects, and this name allows URLs (fragments) to reference them (and their children objects).
In case of the href-attribute (see level2: explicit hyperlinks) we use this reference to teleport the player/camera to that location (of the referenced object).
What does it solve
It solves:
- addressibility and hypermediatic navigation of 3D scenes/objects: URI Fragments using src/href spatial metadata
- unlocking spatial potential of the (originally 2D) hashtag (which jumps to a chapter) for navigating XR documents
- refraining from introducing an opiniated scripting-engine for mundane tasks (and preventing its inevitable security-headaches)
XR Fragments views XR experiences through the lens of 3D deeplinked URI's, rather than thru a specific scripting- or game-engine, or protocol-specific browsers (https webbrowser e.g.).
To aid adoption, the standard comprises of various (optional) support-levels, which incorporate existing standards like W3C Media Fragments and URI Templates (RFC6570) to promote spatial addressibility, sharing, navigation, filtering and databinding objects for (XR) Browsers.
XR Fragments is in a sense, a heuristical 3D format or meta-format, which leverages heuristic rules derived from any 3D scene or well-established 3D file formats, to extract meaningful features from scene hierarchies.
These heuristics, enable features that are both meaningful and consistent across different scene representations, allowing higher interop between fileformats, 3D editors, viewers and game-engines.
Level0: file
Capable 3D fileformats
glTF, usdz, obj, collada, THREE.json, X3D e.g. are capable of XR Fragments.
The requirements of any 3D file is: a scenegraph with 1 or more named objects.
XR Fragment Compatible
A 3D scene-file can be considered XR Fragment-compatible when it matches one of these heuristics
- implicit: it has at least one sidecar-file
- explicit: an object has an href extra.
- explicit: it has at least one system folder (one objectname starting with underscore)
- = last wins in case of non-unique names
Loading a file
When an XR player (
myplayer.exee.g.) is launched (without a specific file), it should poll for a default file (myplayer.glbe.g.).
Sidecar files
These are optional auto-loaded files to enable hasslefree publishing of XR Movie applications.
The application should poll for only those 3D file-formats it supports.
Webviewer example
https://my.org/demo.htmlloadsdemo.glbhttps://my.org/demo.html?file=foo.glbloadsfoo.glb
Linux/Mac example
$ ls -la
myplayer
myplayer.glb
$ ./myplayer <-- automatically loads myplayer.glb
$ ./myplayer foo.glb <-- no sidecar logic
Windows example
> dir
myplayer.exe
myplayer.glb
> myplayer.exe <-- automatically loads myplayer.glb
> myplayer.exe foo.glb <-- no sidecar logic
NOTE: after loading a file the usual sidecar file-logic applies
Slideshow
when a loaded file ends with a number (
foo1.glb) automatically check for the existence offoo2.glb)
This will allow simple 3D slideshows:
foo1.glb
foo2.glb
foo3.glb
foo4.glb
But with [sidecar files](#sidecar files) this also allows for XR movie series:
foo-episode1.glb
foo-episode1.vtt
foo-episode1.ogg
foo-episode2.glb
foo-episode2.vtt
foo-episode2.ogg
and so on
F3D
The opensource F3D 3D viewer supports level0 'next file' by invoking:
$ f3d --animation-autoplay foo-episode*.glb
In a similar spirit of the XR Fragment spec: F3D supports multiple 3D file formats, so the 3D slideshow can exist of different 3D fileformats.
Sidecar files
These are optional auto-loaded files to enable hasslefree XR Movies:
via href metadata
scene.glb <--- 'href' extra [heuristic] detected inside!
scene.png <--- then poll preview thumbnail
scene.ogg <--- then poll soundtrack to plays when global 3D animation starts)
scene.vtt <--- then poll fallback subtitles for accessibility or screenreaders
scene.json <--- then poll sidecar JSON-file with explicit metadata
heuristics
- if at least one `href` custom property/extra is found in a 3D scene
- The viewer should poll for the above mentioned sidecar-file extensions (and present accordingly)
via chained extension
scene.xrf.glb <--- 'href' extra [heuristic] detected inside!
scene.xrf.png <--- then poll preview thumbnail
scene.xrf.ogg <--- then poll soundtrack to plays when global 3D animation starts)
scene.xrf.vtt <--- then poll fallback subtitles for accessibility or screenreaders
scene.xrf.json <--- then poll sidecar JSON-file with explicit metadata
A fallback-mechanism to turn 3D files into XR Movies without editing them.
heuristics
the chained-extension heuristic .xrf. should be present in the filename (scene.xrf.glb e.g.)
JSON sidecar-file
NOTE: the following approach is only recommended for archivist/userupload scenarios where the 3D file itself should not be altered.
For developers, a json-sidecar-file can allow for defining explicit XR Fragments metadata (>level1), outside of the 3D file. This can be done via (objectname/metadata) key/value-pairs in a JSON sidecar-file:
{
"aria-description": "description of scene",
"button": {
"href": "#roomB",
"aria-description": "description of room"
}
}
This will make object button clickable, and teleport the user to object roomB.
So after loading experience.glb the existence of experience.json is detected, to apply the explicit metadata.
The sidecar will define (or override already existing) extras, which can be handy for multi-user platforms (offer 3D scene customization/personalization to users).
In THREE.js-code this would boil down to:
scene.userData['aria-description'] = "description of scene"
scene.getObjectByName("button").userData.href = "#roomB"
now the XR Fragments parser can process the XR Fragments userData 'extras' in the scene
multilanguage example
Applications or webservers can use symbolic links or (webpaths) for language-directories:
scene.glb
scene.json
es/scene.glb --> ../scene.glb
es/scene.png
es/scene.ogg
es/scene.vtt
es/scene.json --> ../scene.json
However, embedding the multilanguage postfixes are preferred for portability reasons: see multilangual
via subdocuments/xattr
More secure protocols (Nextgraph e.g.) don't allow for simply polling files. In such case, subdocuments or extended attributes should be polled:
NOTE: in the examples below we use the href-heuristic, but also the
.xrf.chained-extension applies here.
myspreadsheet.ods
└── explainer.glb <--- 'href' extra [heuristic] detected inside!
├── explainer.ogg (soundtrack to play when global 3D animation starts)
├── explainer.png (preview thumnbnail)
├── explainer.json (sidecar JSON-file with explicit metadata)
└── explainer.vtt (subtitles for accessibility or screenreaders)
If only extended attributes (xattr) are available, the respective referenced file can be embedded:
$ setfattr -n explainer.ogg -v "soundtrack.ogg" explainer.glb
$ setfattr -n explainer.png -v "thumbnail.png" explainer.glb
$ setfattr -n explainer.vtt -v "subtitles.vtt" explainer.glb
NOTE: Linux's
setfattr/getfattrisxattron mac, andSet-Content/Get-contenton Windows. See pxattr for lowlevel access.
when a loaded file contains a timeline (animations/subtitles e.g.), then:
All timelines must play (looped) by default (to enable XR Movies)
Unless an object has multiple animations (actions e.g.), then just play the first or with name default.
URLs are the heart of XR Fragment-based 3D Hypermedia:
- it allows navigating the XR browser to a (different) 3D scene (
world.glbe.g.) - it allows teleporting the user to a different location (
room2e.g.) - it allows back/forward navigation
- it allows addressibility (for 3d objects inside a file)
Examples:https://linux.world/#roomF&t=1,100linuxapp://conference/nixworkshop?newuser#roomC&t=2,200androidapp://page1?tutorial#roomB&t=1,100
Implicit and Explicit adressibility is the core of the XR Fragments spec, as well as user teleportation:
Software uses level1 for deeplinking objects, or to teleport the user: here's pseudocode for a level1 XR Fragments browser in THREE.js:
// by default the (VR) user gets position at 0,0,0 at the loaded scene (+VR userheight)
url = 'world.glb#roomB&car'
file = url.split("#")[0]
xrf = new URLSearchParams( url.split("#")[1] )
refs = ([...xrf.keys()]).filter( (k) => !k.match(/(t)/) ) // skip mediafrags
// set last (nonoperator) objectname as camera-location
for( i in refs ){
scene.setActiveCameraByName(refs[i]) // teleport
obj = extractObject(scene,refs[i]) // or purely deeplink
}
for robust parsing of XR Fragments use a http query-language parser, or the polyglot parser
Below is the related section of the spec (full spec here: HTML, TXT)
For more info see How it works
Every 3D object, material or camera can be adressed by URI fragments (#myobject e.g.) which are derived from the 3D scene objectnames (implicit metadata).
These are inferred at runtime from the 3D scene-nodes (object names, object metadata etc).
Free fragments and features generated for you..How great is that? 🎉
my.io/scene.usdz Embeddable as:
+─────────────────────────────+
│ sky │ src: http://my.io/scene.udsz#sky (includes building,mainobject,floor)
│ +─────────────────────────+ │
│ │ building │ │ src: http://my.io/scene.udsz#building (includes mainobject,floor)
│ │ +─────────────────────+ │ │
│ │ │ mainobject │ │ │ src: http://my.io/scene.udsz#mainobject (includes floor)
│ │ │ +─────────────────+ │ │ │
│ │ │ │ floor │ │ │ │ src: http://my.io/scene.udsz#floor (just floor object)
│ │ │ │ │ │ │ │
│ │ │ +─────────────────+ │ │ │ href: http://my.io/scene.udsz#-mainobject (hides mainobject when clicked)
│ │ +─────────────────────+ │ │
│ +─────────────────────────+ │
+─────────────────────────────+
Fragments (
#buildinge.g.) allow for very convenient, guess-able filters to reference/show/hide objects within a 3D scene.
For more examples see filters and the reference-menu (by feature)
Below is the related section of the spec (full spec here: HTML, TXT)
default portals
To render a portal, the easiest way is JanusXR-style portals:
clickable planes which teleport the user to a different position or file. This is the whole idea behind href and XRF microformat metadata.
In blender you can create a plane, and attach a href hyperlink to it
non-euclidian portals
NOTE: this **extension** is optional, and can be used in a progressive enchanched way across (non)supporting viewers.
Portals avoid XR clutter. Rinsema's effect: "To observe much is to absorb little"
A materialless mesh with the following heuristics will render as an immersive portal:
| Portaltype | Heuristics | Result |
| XR lens | child objects in materialless mesh | objects are only visible in mesh |
| XR portal | href value | the other mesh will be used as camera-point (location will have 1.6m camera-height added) |
NOTE: in 3D engines this is refererred to as rendering to a designated stencil.
You can see this demonstrated in index.glb or the demo-video & viewer below:
NOTE: designers are adviced to always accompany a button to the portal (see video), to keep things backwards compatible with barebones (non-portal-supporting) XRF viewers.
Examples
Example scene hierarchy:
my.io/scene.usdz
+─────────────────────────────+
│ world1 │
│ +─────────────────────────+ │
│ │ myportalmesh------------------+ href: #portalpoint
| | | |
│ +─────────────────────────+ │ myportalmesh renders world2
│ world2 │ inside from portalpoint's of view
│ +─────────────────────────+ │ (if myportalmesh has no material)
│ │ cube │ │
| | portalpoint | |
│ +─────────────────────────+ │
+─────────────────────────────+
Lenses
Will render objects inside of the portal (children) ONLY inside of the portal.

Example scene hierarchy:
my.io/scene.usdz
+─────────────────────────────+
│ world1 │
│ +─────────────────────────+ │
│ │ myportal | | myportal renders someinfo inside
| | +──────────+ | | as portal
| | | someinfo | | | (if myportal has no material)
| | +──────────+ | |
│ +─────────────────────────+ │
+─────────────────────────────+
Demo viewer
Press the 'Teleport down there'-button (in the lens) and witness the portals afterwards yourself:
set the position of the camera.
level1 spawnpoints
Spawn user at object (with name)barafter loading (and replacing the current scene with)world.glb
level2 href spawnpoints
| objectname | optional | functionality |
| spawn | yes | Specifies default camera-position (if exist). Detected after loading scene (world.glb e.g.), if no URI hashtag is present (world.glb#roomC e.g.) |
| URI fragment | type | functionality |
| #roomB | string | position camera to position of object with name roomB |
| #cam2 | string | position camera to position of camera with name cam02, and make it active camera [follow animation e.g.] |
| https://my.org/worldX.glb#roomY | string | position camera to position of object roomC after replacing the current scene with worldX.glb |
the usercamera (usually default at0,0,0or at objectnamespawn) is repositioned to the origin and upvector of the target object, and only in VR/AR its height gets adjusted (~1.6m height is subtracted, to compensate for camera-rig )
To enable VR elevators e.g., make sure:
the camera is attach/parented to that object (so it animates along with the object)
You can add this URI Fragment to the top-level URLbar, or as href value (to trigger via click) in a 3D model Editor (Blender e.g.):
IMPORTANT: please respect collidable floor / objects. Also notice that#pos=roomBhas been deprecated in favor of#roomBto simplify the spec.
Developers only:
» example implementation
» discussion
Spec
Below is the related section of the spec (full spec here: HTML, TXT)
How can applications discover 3D experiences on a network?
Answer: spatial microformats
The XRF microformat is an optional text heuristics which applications can detect across various usecases.
via HTML webpage
If the browser/application requests an webpage (https://nlnet.nl e.g.) it should check for the rel-me microformat :
<link rel="alternate" as="spatial-entrypoint" href="scene.xrf.glb">
This way the application loads https://nlnet.nl/scene.xrf.glb when the user types nlnet.nl into the URLbar.
Optionally, type can be specified for dynamically generated 3D files:
<link rel="alternate" as="spatial-entrypoint" href="https://worlds.org/scene.php#platformB" type="model/gltf+binary" />
The type-attribute is for fallback-purposes.
Viewer-supported 3D file-extensions (.glb e.g.) will ALWAYS take precedence over the (non)presence of the type attribute.
The reason is that platforms (Mastodon 'labels' e.g.) don't allow specifying type-attributes.
Another reason is that XR Fragments is filetype-agnostic, so flexibility is expected on the viewer-side.
NOTE: in case of multiple 3D files mentioned in
<link rel="me", only the first (supported 3D filetype) will be chosen.
Collections
Example of a webpage with collection of 3D models (like icosa.gallery):
<link rel='alternate' as='spatial-portal' href="result1.glb"/>
<link rel='alternate' as='spatial-portal' href="result2.glb"/>
<link rel='alternate' as='spatial-portal' href="result3.glb#buildingA"/>
<link rel='alternate' as='spatial-portal' href="result3.glb#buildingB"/>
<!-- optional: pagination hints -->
<link rel='next' as='spatial-portal' href="..."/>
<link rel='prev' as='spatial-portal' href="..."/>
<link rel="pages" min="1" max="46" items="8" />
3D engines (games/apps) can render these like clickable portals, for example JanusXR-style portals:
NOTE: for more customizability JML <link> will allow for positioning/thumbnailed portals:
<fireboxroom>
<assets>
<assetimage src="/img/thumb1.jpg" id="img1"/>
<assetimage src="/img/thumb2.jpg" id="img2"/>
</assets>
<room skybox="true" pos="0 0 0" showavatar="false" use_local_asset="room_plane">
<link url="/myverse/janusxr_tutorial1/" thumb_id="img1" title_col="0.4 0.37 0.4" pos="0 0 0.001" draw_glow="true" scale="3 3 0.1" />
<link url="/myverse/janusxr_tutorial2/" thumb_id="img2" title_col="0.4 0.37 0.4" pos="3 0 0.001" draw_glow="true" scale="3 3 0.1" />
</room>
</fireboxroom>
Mixing multiple spatial microformats:
<link rel="alternate" as="spatial-entrypoint" href="scene.xrf.glb"/>
<link rel="me" href="myavatar.vrm"/>
<!-- JanusXR JML https://github.com/jbaicoianu/janusweb
<fireboxroom>
<room>
<object id="scene.xrf.glb" pos="0 0 0"/>
</room>
</fireboxroom>
-->
via WebFinger
When John has an account on foo.com, how can other applications request his 3D homepage by simply entering john@foo.com?
Answer: it can be requested at
https://foo.com/.well-known/webfinger?resource=acct:john@foo.com, resulting in:
{
"subject": "acct:john@foo.com",
"aliases": [
"https://mastodon.example/social/john",
"https://john.foo.com",
"https://3d.john.foo.com/model/scene.glb"
],
"properties": {
"http://schema.org/name": "John Doe",
"http://schema.org/description": "Developer, 3D Enthusiast, and Social Explorer"
},
"links": [
{
"rel": "http://ostatus.org/schema/1.0/subscribe",
"template": "https://mastodon.example/social/john/{uri}"
},
{
"rel": "self",
"type": "text/html",
"href": "https://john.foo.com"
},
{
"rel": "me",
"type": "text/html",
"href": "https://john.foo.com"
},
{
"rel": "me",
"type": "model/gltf+binary",
"href": "https://3d.john.foo.com/model/avatar.vrm"
},
{
"rel": "scene",
"type": "model/gltf+binary",
"href": "https://3d.john.foo.com/model/scene.xrf.glb"
}
]
}
This way the application will load https://3d.john.foo.com/model/scene.glb when the user types john@foo.com into the user field.
via Text (URI)
As a fallback, for an application to trigger loading a 3D scene is by detecting URI's of 3D scene-files any text:
foo.glb(or any other popular 3D extension)https://foo.com/scene.glb(or any other popular protocol)
This way, the application can highlight the link whenever it detects the URI (in a text-file or text-section of a 3D model)
What if we embed XR Fragment URI's inside a 3D or XML file?
level2 promotes adding clickable hyperlinks, via the href metadata attribute.
<room>
<object id="plane" js_id="button" href="#building"/>
<object id="cube" js_id="building"/>
<link url="foo.glb#spawn"/>
</room>
Clicking the plane will teleport the user to object building.
Clicking the portal (<link>) will clear the scene, load foo.glb and teleport the user to object spawn.
For more info about JanusXR
cube = scene.getObjectByName("cube")
sphere = scene.getObjectByName("sphere")
// add URI's with XR Fragments
cube.userData.href = '#platform2'
sphere.userData.href = "foo.glb#spawn'
// local teleport!
cube.onClick = () => {
camera.position.copy( scene.getObjectByName("platform2").position )
}
// remote teleport!
sphere.onClick = await () => {
scene.clear()
await scene.load('foo.glb')
camera.position.copy( scene.getObjectByName("spawn").position )
}
Clicking the cube will teleport the user to object 'platform2'.
Clicking the sphere will clear the scene, load foo.glb and teleport the user to object spawn.
NOTE: gltf-models fully support href's in this implementation but href in markup is not supported (yet: JanusXR is a safer bet)
<a-scene>
<a-cube href="#building"/>
<link href="foo.glb#spawn"/>
</a-scene>
Clicking the cube will teleport the user to object building.
Clicking the portal (<link>) will clear the scene, load foo.glb and teleport the user to object spawn.</div>
NOTE: no implementation (yet)
<m-cube href="#building"></m-cube>
<m-sphere href="foo.glb#spawn"></m-cube>
Clicking the cube will teleport the user to object building.
Clicking the sphere will clear the scene, load foo.glb and teleport the user to object spawn.</div>
An Easy nocode way to add metadata is by adding custom properties in blender e.g.. This is demonstrated in the getting started video:
| custom property | type | functionality |
|---|---|---|
| href | string (uri or predefined view) | href navigation / portals / teleporting to other XR documents |
3D documents using
hrefare spec-compliant but similar variants (<Link url="...">in JanusXR JML e.g) are considered spec-compatible
Object metadata can also be added/exported programmatically, for example in AFRAME/THREE.js can export GLB/USDZ/OBJ/COLLADA-files with them, after setting myobject.userData.href = "#nameofplane" e.g.
Spec
Below is the related section of the spec (full spec here: HTML, TXT)
Adding links to 3D objects
Clicking an 3D object with href-data, will teleport the user to that file and/or object.
<room>
<object id="plane" js_id="button" href="#building"/>
<object id="cube" js_id="building"/>
<link url="foo.glb#spawn"/>
</room>
Clicking the plane will teleport the user to object building.
Clicking the portal (<link>) will clear the scene, load foo.glb and teleport the user to object spawn.
For more info about JanusXR
cube = scene.getObjectByName("cube")
sphere = scene.getObjectByName("sphere")
// add URI's with XR Fragments
cube.userData.href = '#platform2'
sphere.userData.href = "foo.glb#spawn'
// local teleport!
cube.onClick = () => {
camera.position.copy( scene.getObjectByName("platform2").position )
}
// remote teleport!
sphere.onClick = await () => {
scene.clear()
await scene.load('foo.glb')
camera.position.copy( scene.getObjectByName("spawn").position )
}
Clicking the cube will teleport the user to object 'platform2'.
Clicking the sphere will clear the scene, load foo.glb and teleport the user to object spawn.
NOTE: gltf-models fully support href's in this implementation but href in markup is not supported (yet: JanusXR is a safer bet)
<a-scene>
<a-cube href="#building"/>
<link href="foo.glb#spawn"/>
</a-scene>
Clicking the cube will teleport the user to object building.
Clicking the portal (<link>) will clear the scene, load foo.glb and teleport the user to object spawn.</div>
NOTE: no implementation (yet)
<m-cube href="#building"></m-cube>
<m-sphere href="foo.glb#spawn"></m-cube>
Clicking the cube will teleport the user to object building.
Clicking the sphere will clear the scene, load foo.glb and teleport the user to object spawn.</div>
An Easy nocode way to add metadata is by adding custom properties in blender e.g.. This is demonstrated in the getting started video:
| property | type | example value |
href | string (uri) | #bar#pyramidxrf://#-someobject://somefile.gltf#foo |
Interaction behaviour
1. when clicking a href-value (#bar e.g.), the user(camera) is teleport to the referenced object.
2. when clicking a remote href-value (https://foo.org/hello.glb#bar e.g.), then that 3D file replaces the current scene (+user(camera) is teleported to any referenced object roomB).
XR Safety Exception: when linking to a 3D file which has zero signs of XR Fragments (see 📜 level0: File), it will be treated as an Object import
Spec
See the full spec here: HTML, TXT
Demo
Undefined widget 'videojs'
capture of aframe/sandbox
XR Viewer implementation
| spec | action | feature |
| level0+1 | hover 3D file href | show the preview PNG thumbnail (if any). See 📜 level0: File) |
| level0+1 | launch 3D file href | replace the current scene with a new 3D file (href: other.glb e.g.) |
| level2 | click internal 3D file href (#roomB e.g.) | teleport the camera to the origin of object(name roomB). See teleport camera. |
| level2 | click external 3D file href (foo.glb e.g.) | replace the current scene with a new 3D file (href: other.glb e.g.) |
| level2 | hover external 3D file href | show the preview PNG thumbnail (if any sidecar 📜 level0: File) |
| level2 | click href | hashbus: execute without changing the toplevel URL location (href: xrf://#someObjectName e.g.) |
| level3 | click href | set the global 3D animation timeline to its Media Fragment value (#t=2,3 e.g.) |
NOTE: hashbus links (xrf://#foo&bar) don't change the toplevel URL, which makes it ideal for interactions (in contrast to typical#roomCnavigation, which benefit back/forward browser-buttons), see hashbus for more info.
XRF viewer pseudocode
scene.traverse( (n) => {
if( n.userData.href ){
n.addEventListener('click', () => scene.teleport(n.userData.href) )
}
})XR Fragment-capable clients offer increased XR Accessibility via aria-description-metadata, and the so-called 2-button navigation:
TAB and ENTER actions allow for cycling/executing objects with
hrefmetadata contextually, meaning that only relevant objects are candidates for this (allowing comfortable tab-navigation inside huge worlds with large amounts of buttons). The buttons are remappable, and can also be triggered via speech.
Example of metadata of an accessible button:
href: #platformBaria-description: is a space where the history of mankind is explained
Selecting the button will display/read to the user:
#platformB is a space where the history mankind is explained.
The spec encourages startingaria-descriptionwith a verb (for easy transcripts).
Here's the relevant part of the spec:
The spec also defines a simple text-input interface which allows navigation via speech or text-input:
set the position of the camera.
level1 spawnpoints
Spawn user at object (with name)barafter loading (and replacing the current scene with)world.glb
level2 href spawnpoints
| objectname | optional | functionality |
| spawn | yes | Specifies default camera-position (if exist). Detected after loading scene (world.glb e.g.), if no URI hashtag is present (world.glb#roomC e.g.) |
| URI fragment | type | functionality |
| #roomB | string | position camera to position of object with name roomB |
| #cam2 | string | position camera to position of camera with name cam02, and make it active camera [follow animation e.g.] |
| https://my.org/worldX.glb#roomY | string | position camera to position of object roomC after replacing the current scene with worldX.glb |
the usercamera (usually default at0,0,0or at objectnamespawn) is repositioned to the origin and upvector of the target object, and only in VR/AR its height gets adjusted (~1.6m height is subtracted, to compensate for camera-rig )
To enable VR elevators e.g., make sure:
the camera is attach/parented to that object (so it animates along with the object)
You can add this URI Fragment to the top-level URLbar, or as href value (to trigger via click) in a 3D model Editor (Blender e.g.):
IMPORTANT: please respect collidable floor / objects. Also notice that#pos=roomBhas been deprecated in favor of#roomBto simplify the spec.
Developers only:
» example implementation
» discussion
Spec
Below is the related section of the spec (full spec here: HTML, TXT)
Guided & interactive XR navigation is possible when using href in WebVTT subtitle-files.
Potential
- guided XR tours across multiple files/URLs
- timeline for spawnpoints
- rich storytelling / e-learning
Example using sidecar files:
myscene.xrf.glb
myscene.xrf.vtt
myscene.xrf.ogg
Since .xrf. (or at least one href) is a heuristic for loading sidecar files, the webvtt subtitles (myscene.xrf.vtt) can be displayed while the experience plays (syncronized with myscene.xrf.ogg):
WEBVTT
00:01.000 --> 00:04.000 href:#spawn
<v narrator voice>welcome to a special experience.
one
two
three
00:06.000 --> 00:12.000
Let me take you to the divine..
00:13.000 --> 00:14.000 href:#fadeAudioOut&inside
Here we are
00:14.000 --> 00:19.000
Now lets open a portal
to a remote location
00:19.000 --> 00:25.000 href:https://xrfragment.org
That portal will take us
to https://xrfragment.org
Just click it..
00:25.100 --> 00:30.000
Welcome to another Janus URL
Here href is used as CUE setting, which the player can act upon.
How to know whether a 3D file is a full scene or just a prop?
When should a 3D file hide its skybox?
How does a file know whether its embedded or not?
How to hide an object in AR-mode only?
How to ''hide'' an object by default, after loading a scene?
Answer: somehow tagging the file, or object with predefined classes ; universal XR keywords.
<!-- xr layers: vr ar portal embed -->
<room>
<!-- override: dont show in AR by leaving 'ar' out -->
<object id="room_and_sky" class="vr portal embed">
<!-- override: only show in AR -->
<text text="welcome in AR mode" class="ar"/>
</room>
Here the JML browser is instructed to opt out certain elements, depending on the context.
For more info about JanusXR
cube = scene.getObjectByName("cube")
sphere = scene.getObjectByName("sphere")
// you can set the classes manually in case your glTF
// does not have them (yet)
scene.userData.class = "vr ar portal embed" // default
cube.userData.class = 'ar' // only ar
sphere.userData.class = "vr portal embed' // hide in ar
const modes = getModes() // ['ar'] (somehow determine viewing context)
scene.traverse( (obj) => { // trickle down classes to children
if( obj.userData.class ){
obj.userData.classes = obj.userData.class.replace(/ /,' ').split(' ')
modes.map( (mode) => {
if( ! ~obj.userData.classes.indexOf(mode) ) obj.visible = false
})
obj.traverse( (child) => {
child.userData.classes = obj.userData.classes )
child.visible = false
})
}
})
The cube will only be visible in AR, while the sphere also in VR, when renderered in a portal, or when embedded in another scene.
NOTE: not implemented yet in this implementation but href in markup is not supported (yet: JanusXR is a safer bet)
<a-scene> <!-- assumed default class="vr ar portal embed" -->
<a-cube layer="ar"/> <!-- show only in AR -->
<a-sphere layer="vr portal embed"/>
</a-scene>
The cube will only be visible in AR, while the sphere also in VR, when renderered in a portal, or when embedded in another scene.
NOTE: no implementation (yet)
<m-cube layer="ar"/> <!-- show only in AR -->
<m-sphere layer="vr portal embed"/>
The cube will only be visible in AR, while the sphere also in VR, when renderered in a portal, or when embedded in another scene.
Similar to href: instead of
href, create an extraclass-property with a string-value (are.g.), to opt out of the default inheritedvr ar portal embed-value (from the scene-root, even when its not explicitly defined).
Predefined hints: XR layers
| hint/class | desktop mode |
VR mode |
AR mode |
usecase |
|---|---|---|---|---|
vr |
show | show | hide | render object+children |
ar |
hide | hide | show | render object+children |
embed |
show | show | show | render object+children when loaded in another scene |
portal |
show | show | show | render object+children inside portal |
collection |
hide | hide | hide | object+children are not part of a scene/experience (think importing into inventory, openbrush brushes e.g.). |
hide |
hide | hide | hide | hide object+children |
Any element without any of these class-values is considered visible in all layers. Once class-value(s) are detected it'll work as a layer-mask: class: 'vr ar' will be visible in desktop-,VR- and AR-mode.
NOTE: there's is no CSS: class attributes without CSS means no cascade inheritance; above class-definitions will apply to the element itself (and its children, which can override by defining their own XR layer class-definitions).
Predefined hints: XR object interactions
| hint/class | spec | document default | usecase |
|---|---|---|---|
grabbable |
v1 | unset | allow single handtracking-pinch to reposition object, or via buttonhold + controllermove/mousemove |
stretchable |
v1 | unset | allow both handtracking-pinch to stretch object, or via buttonhold + controllermove/mousemove |
collidable |
v1 | unset | hints that grabbable and stretchable should halt upon collisions |
NOTE:
href: #*fooimplies that objectfoohasclass: 'grabbable'
Usecases
- 3D previews:
class: 'vr ar'prevents rendering (heavy) items when displayed in a portal (or embedded into another scene). - extra info:
class: 'portal'displays onboarding texts/info ONLY when rendered in a portal.
Examples
XR Fragments is not a fileformat-specific extension, it's a spec for deeplinking any 3D file.
The level2 metadata (See reference) is easy to embed in any 3D editor (not only blender) than it would be to support new GLTF extensions.
This is not to say extensions are bad (they are superior in certain cases).
Just like URLs allow fileformat-agnostic navigation, 3D asset 'extras' are fileformat-agnostic too, which together allow for XR Fragments.
To deal with extensions/overlapping features see native vs XRF features
How to deal with overlapping functionality?
Well, native (extensions) take precende, otherwise 'fallback' applies.
Examples
| Native feature | XRF | Solution |
|---|---|---|
| <Link url="..."> in JanusXR JML | href: ... (3Dfile extra)<Link href="..."/> (JML) |
use <Link url="...">, otherwise href="...", otherwise href: ... |
| OMI_Link gltf extension | href: .... |
use OMI_Link, otherwise href |
Common advice is to 'stack' (portal)links to achieve graceful degradation:
- plane at
0 0 0has texture explaining link/portal - plane at
0 0 0.01useshreflink - plane at
0 0 0.02usesOMI_LINKlink
That way there's click 'fallthrough': the user will click whichever the engine supports.
Below is the related section of the spec (full spec here: HTML, TXT)
For more info see How it works
multilangual 3D file
How to enable multilangual 3D experiences?
Answer: by adding extra objectnames/metadata which include a language postfix (ISO 639-1 language 2char-code).
Example object-metadata:
aria-description: this is a cubearia-description-nl: dit is een kubus
Example object-name:
Given a scene with objectnames banner and banner-nl
href: #+banner
If the language is set to nl and banner-nl exists too, then that will be selected/operated instead.
How to determine the language?
This should be a setting of the browser. For example, to get the language from a webbrowser:
navigator.language.substr(0,2) // 'en'
NOTE: this is completely optional, and works via progressive enhancement.