xrfragment/doc/RFC_XR_Fragments.txt
2026-11-09 12:07:49 +01:00

1160 lines
50 KiB
Text
Raw Blame History

▄ ▄ ▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄ ▄▄▄▄▄▄ ▄▄▄ ▄▄▄ ▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄ ▄ ▄▄▄▄▄▄
▓ ▓ ▓ ▓ ▓ ▓ ▓ ▓ ▓ ▓ ▄▄▄ ▓ ▓ ▓ ▓ ▓ ▓ ▓ ▓▄▄▄▄▄ ▓▄▄▄▄▄
▄▀▀▀▀▀▄ ▒ ▒ ▒▀▀▀ ▒ ▒ ▒▀▀▀▀▀▒ ▒ ▒ ▒ ▒ ▒▄▄▄▄▄▒ ▒ ▒ ▒ ▒
░ ░ ░ ░ ░ ░ ░ ░▄▄▄▄░ ░ ░ ░▄▄▄▄▄▄ ░ ░ ░▄▄▄▄▄ ▄▄▄▄▄░
All-in-one-spec
9th November 2026 at 11:59am
Reference
Download [1]HTML, [2]TXT
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 [3]URI Fragments.
Almost every idea in this document is demonstrated at [4]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:
1. for 3D viewers/browser to manipulate the camera or objects of a 3D scene (via URI fragments)
2. implicitly: by mapping 3D objectnames (of a 3D scene/file) to URI fragments (3D deeplinking)
3. explicitly: by scanning href metadata inside 3D scene-files to enable interactions
4. explicitly: by scanning for XR hints metadata inside 3D scene-files to distinguish contextual rendering (AR vs VR e.g.)
5. externally: progressively enhance a 3D (file) into an experience via [5]sidecarfiles
Aspect 1 was pioneered and implemented by JanusXR / James Baicoianu via [6]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:
1. addressibility and [7]hypermediatic navigation of 3D scenes/objects: [8]URI Fragments using src/href spatial metadata
2. unlocking spatial potential of the (originally 2D) hashtag (which jumps to a chapter) for navigating XR documents
3. 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 [9]W3C Media Fragments and [10]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
[11]glTF, [12]usdz, [13]obj, [14]collada, [15]THREE.json, [16]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
1. implicit: it has at least one [17]sidecar-file
2. explicit: an object has an [18]href extra.
3. explicit: it has at least one [19]system folder (one objectname starting with underscore)
* = last wins in case of non-unique names
Loading a file
When an XR player (myplayer.exe e.g.) is launched (without a specific file), it should poll for a default file (myplayer.glb e.g.).
Sidecar files
These are optional auto-loaded files to enable hasslefree publishing of [24]XR Movie applications.
The application should poll for only those [25]3D file-formats it supports.
__________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________
Webviewer example
1. https://my.org/demo.html loads demo.glb
2. https://my.org/demo.html?file=foo.glb loads foo.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 [26]sidecar file-logic applies
Slideshow
when a loaded file ends with a number (foo1.glb) automatically check for the existence of foo2.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 [27]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 [28]XR Movies:
__________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________
via [29]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
1. if at least one `href` custom property/extra is found in a 3D scene
2. 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 [30]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 [31]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 [32]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/getfattr is xattr on mac, and Set-Content/Get-content on Windows. See [33]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 [34]XR Movies)
Unless an object has multiple animations (actions e.g.), then just play the first or with name default.
protocol:// my.org/world.glb #room2
URLs are the heart of XR Fragment-based 3D Hypermedia:
* it allows navigating the XR browser to a (different) 3D scene (world.glb e.g.)
* it allows teleporting the user to a different location (room2 e.g.)
* it allows back/forward navigation
* it allows addressibility (for 3d objects inside a file)
Examples:
https://linux.world/#roomF&t=1,100
linuxapp://conference/nixworkshop?newuser#roomC&t=2,200
androidapp://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 [39]parser
Below is the related section of the spec (full spec here: [40]HTML, [41]TXT)
IFRAME: [42]doc/RFC_XR_Fragments.html#list-of-uri-fragments
For more info see [43]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 (#building e.g.) allow for very convenient, guess-able [44]filters to reference/show/hide objects within a 3D scene.
For more examples see [45]filters and [46]the reference-menu (by feature)
Below is the related section of the spec (full spec here: [47]HTML, [48]TXT)
IFRAME: [49]doc/RFC_XR_Fragments.html#fragment-to-metadata-mapping
default portals
To render a portal, the easiest way is [50]JanusXR-style portals:
clickable planes which teleport the user to a different position or file. This is the whole idea behind [51]href and [52]XRF microformat metadata.
result1.glbresult2.glb
In blender you can create a plane, and [53]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.
Undefined widget 'videojs'
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 [54]child objects in materialless mesh objects are only visible in mesh
XR portal [55]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 [56]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.
[xrlens.png]
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:
IFRAME: [57]./example/aframe/sandbox/index.html?index.glb
set the position of the camera.
level1 spawnpoints
protocol :// my.org/world.glb #bar
Spawn user at object (with name) bar after loading (and replacing the current scene with) world.glb
level2 href spawnpoints
[B5vTCkruO9skAAAAAElFTkSuQmCC]
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.]
[58]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 at 0,0,0 or at objectname spawn) 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 [59]href value (to trigger via click) in a 3D model Editor (Blender e.g.):
Undefined widget 'videojs'
IMPORTANT: please respect [60]collidable floor / objects. Also notice that #pos=roomB has been deprecated in favor of #roomB to simplify the spec.
Developers only:
[61]<5D> example implementation
[62]<5D> discussion
Spec
Below is the related section of the spec (full spec here: [63]HTML, [64]TXT)
IFRAME: [65]doc/RFC_XR_Fragments.html#navigating-3d
How can applications discover 3D experiences on a network?
Answer: spatial microformats
The XRF microformat is an [66]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 [67]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 [68]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:
result1.glbresult2.glb
NOTE: for more customizability [69]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 [70]href metadata attribute.
( ) JanusXR ( ) THREE.js ( ) AFRAME ( ) MML ( ) Blender3D
<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 [71]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 [72]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>
All modern 3D editors can attach metadata to objects, and export these as 'extras' with the 3D file.
[B5vTCkruO9skAAAAAElFTkSuQmCC]
An Easy nocode way to add metadata is [73]by adding custom properties in blender e.g.. This is demonstrated in the getting started video:
Undefined widget 'videojs'
custom property type functionality
[74]href string (uri or [75]predefined view) href navigation / portals / teleporting to other XR documents
3D documents using href are spec-compliant but similar variants (<Link url="..."> in [76]JanusXR JML e.g) are considered spec-compatible
Object metadata can also be added/exported programmatically, for example in [77]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: [78]HTML, [79]TXT)
IFRAME: [80]doc/RFC_XR_Fragments.html
Adding links to 3D objects
Clicking an 3D object with href-data, will teleport the user to that file and/or object.
__________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________
[B5vTCkruO9skAAAAAElFTkSuQmCC]
__________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________
( ) JanusXR ( ) THREE.js ( ) AFRAME ( ) MML ( ) Blender3D
<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 [81]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 [82]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>
All modern 3D editors can attach metadata to objects, and export these as 'extras' with the 3D file.
[B5vTCkruO9skAAAAAElFTkSuQmCC]
An Easy nocode way to add metadata is [83]by adding custom properties in blender e.g.. This is demonstrated in the getting started video:
Undefined widget 'videojs'
property type example value
href string (uri) #bar
#pyramid
xrf://#-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 [84]level0: File), it will be treated as an [85]Object import
Spec
See the full spec here: [86]HTML, [87]TXT
solutions in the spec were abducted from [88]this and [89]this survey result
Demo
Undefined widget 'videojs'
capture of [90]aframe/sandbox
XR Viewer implementation
spec action feature
level0+1 hover 3D file [91]href show the preview PNG thumbnail (if any). See [92]level0: File)
level0+1 launch 3D file [93]href replace the current scene with a new 3D file (href: other.glb e.g.)
level2 click internal 3D file [94]href (#roomB e.g.) teleport the camera to the origin of object(name roomB). See [95]teleport camera.
level2 click external 3D file [96]href (foo.glb e.g.) replace the current scene with a new 3D file (href: other.glb e.g.)
level2 hover external 3D file [97]href show the preview PNG thumbnail (if any sidecar [98]level0: File)
level2 click [99]href hashbus: execute without changing the toplevel URL location (href: xrf://#someObjectName e.g.)
level3 click [100]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 #roomC navigation, which benefit back/forward browser-buttons), see [101]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 href metadata 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: #platformB
* aria-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 starting aria-description with a verb (for easy transcripts).
Undefined widget 'videojs'
Here's the relevant part of the spec:
IFRAME: [102]doc/RFC_XR_Fragments.html#two-button-navigation
The spec also defines a simple text-input interface which allows navigation via speech or text-input:
IFRAME: [103]doc/RFC_XR_Fragments.html#accessibility-interface
set the position of the camera.
level1 spawnpoints
protocol :// my.org/world.glb #bar
Spawn user at object (with name) bar after loading (and replacing the current scene with) world.glb
level2 href spawnpoints
[B5vTCkruO9skAAAAAElFTkSuQmCC]
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.]
[104]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 at 0,0,0 or at objectname spawn) 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 [105]href value (to trigger via click) in a 3D model Editor (Blender e.g.):
Undefined widget 'videojs'
IMPORTANT: please respect [106]collidable floor / objects. Also notice that #pos=roomB has been deprecated in favor of #roomB to simplify the spec.
Developers only:
[107]<5D> example implementation
[108]<5D> discussion
Spec
Below is the related section of the spec (full spec here: [109]HTML, [110]TXT)
IFRAME: [111]doc/RFC_XR_Fragments.html#navigating-3d
Guided & interactive XR navigation is possible when using [112]href in WebVTT subtitle-files.
Potential
* guided XR tours across multiple files/URLs
* timeline for spawnpoints
* rich storytelling / e-learning
Example using [113]sidecar files:
myscene.xrf.glb
myscene.xrf.vtt
myscene.xrf.ogg
Since .xrf. (or at least one [114]href) is a heuristic for loading [115]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 [116]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.
(*) JanusXR ( ) THREE.js ( ) AFRAME ( ) MML ( ) Blender3D
<!-- 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 [117]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 [118]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.
All modern 3D editors can attach metadata to objects, and export these as 'extras' with the 3D file.
[B5vTCkruO9skAAAAAElFTkSuQmCC]
Similar to [119]href: instead of href, create an extra class-property with a string-value (ar e.g.), to opt out of the default inherited vr 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: #*foo implies that object foo has class: '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
class: 'vr ar portal embed'skysky will not be renderedwhen the user is viewingin AR modedesigner notesdesigner notes will not be renderedin viewer becauseof class overrideclass: 'hide'ARonboardingwill ONLY be shownwhen loaded inAR sessionnot when loaded intoVR, portal or anotherscene.(all objects inherit these default classes)class: 'vr portal embed'class: 'vr ar portal embed'(all objects inherit these default classes)(all objects inherit these default classes)class: 'vr ar portal embed'class: 'ar'
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 [120]native vs XRF features
How to deal with overlapping functionality?
Well, native (extensions) take precende, otherwise 'fallback' applies.
Examples
Native feature XRF Solution
[121]<Link url="..."> in [122]JanusXR JML href: ... (3Dfile extra)
<Link href="..."/> (JML) use <Link url="...">, otherwise href="...", otherwise href: ...
[123]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 0 has texture explaining link/portal
* plane at 0 0 0.01 uses href link
* plane at 0 0 0.02 uses OMI_LINK link
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: [124]HTML, [125]TXT)
IFRAME: [126]doc/RFC_XR_Fragments.html#overlap-with-fileformat-specific-extensions
For more info see [127]How it works
multilangual 3D file
How to enable multilangual 3D experiences?
Answer: by adding extra objectnames/metadata which include a language postfix ([128]ISO 639-1 language 2char-code).
Example object-metadata:
* aria-description: this is a cube
* aria-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.
References
Visible links:
1. RFC_XR_Fragments.html
2. RFC_XR_Fragments.txt
3. https://en.wikipedia.org/wiki/URI_fragment
4. https://xrfragment.org/
5. https://en.wikipedia.org/wiki/Sidecar_file
6. https://github.com/jbaicoianu/janusweb
7. https://github.com/coderofsalvation/hypermediatic
8. https://en.wikipedia.org/wiki/URI_fragment
9. https://www.w3.org/TR/media-frags/
10. https://www.rfc-editor.org/rfc/rfc6570
11. https://www.khronos.org/gltf/
12. https://openusd.org/release/spec_usdz.html
13. https://en.wikipedia.org/wiki/Wavefront_.obj_file
14. https://www.khronos.org/collada
15. https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4
16. https://en.wikipedia.org/wiki/X3D
17. RFC_XR_Fragments.html#sidecar%20files
18. RFC_XR_Fragments.html#href
19. RFC_XR_Fragments.html#system%20folders
20. RFC_XR_Fragments.html#application%20sidecar%20file
21. RFC_XR_Fragments.html#next%20file%20%28slideshow%29
22. RFC_XR_Fragments.html#sidecar%20files
23. RFC_XR_Fragments.html#timelines
24. RFC_XR_Fragments.html#XR%20Movies
25. RFC_XR_Fragments.html#%F0%9F%93%9C%20level0%3A%20File
26. RFC_XR_Fragments.html#sidecar%20files
27. https://f3d.app/
28. RFC_XR_Fragments.html#XR%20Movies
29. RFC_XR_Fragments.html#href
30. RFC_XR_Fragments.html#XR%20Movies
31. RFC_XR_Fragments.html#multilangual
32. RFC_XR_Fragments.html#href
33. https://www.lesbonscomptes.com/pxattr/index.html
34. RFC_XR_Fragments.html#XR%20Movies
35. RFC_XR_Fragments.html#implicit%20deeplinks
36. RFC_XR_Fragments.html#portal%20rendering
37. RFC_XR_Fragments.html#teleport%20camera%20spawnpoint
38. RFC_XR_Fragments.html#XRF%20microformat
39. RFC_XR_Fragments.html#%F0%9F%94%A8%20XR%20Fragments%20parser
40. RFC_XR_Fragments.html
41. RFC_XR_Fragments.txt
42. RFC_XR_Fragments.html#list-of-uri-fragments
43. RFC_XR_Fragments.html#How%20it%20works
44. RFC_XR_Fragments.html#filters
45. RFC_XR_Fragments.html#filters
46. RFC_XR_Fragments.html#%F0%9F%93%A1 by feature (heuristics)
47. RFC_XR_Fragments.html
48. RFC_XR_Fragments.txt
49. RFC_XR_Fragments.html#fragment-to-metadata-mapping
50. RFC_XR_Fragments.html#%F0%9F%8C%8E%20JanusXR%20immersive%20web
51. RFC_XR_Fragments.html#href
52. RFC_XR_Fragments.html#XRF%20microformat
53. RFC_XR_Fragments.html#%F0%9F%93%9C%20level2%3A%20explicit%20hyperlinks
54. RFC_XR_Fragments.html#child%20objects
55. RFC_XR_Fragments.html#href
56. https://coderofsalvation.codeberg.page/xrfragment-haxe/example/aframe/sandbox/index.html?./../../assets/index.glb
57. index.html?index.glb
58. https://my.org/worldX.glb#roomY
59. RFC_XR_Fragments.html#href
60. RFC_XR_Fragments.html#collidable%20%2F%20walkable%20objects
61. https://github.com/coderofsalvation/xrfragment/blob/main/src/3rd/js/three/xrf/pos.js
62. https://github.com/coderofsalvation/xrfragment/issues/5
63. RFC_XR_Fragments.html
64. RFC_XR_Fragments.txt
65. RFC_XR_Fragments.html#navigating-3d
66. RFC_XR_Fragments.html#Progressive%20enhancement
67. https://gmpg.org/xfn/
68. https://icosa.gallery/
69. https://coderofsalvation.github.io/janus-guide/#/build/room?id=link
70. RFC_XR_Fragments.html#href
71. https://coderofsalvation.github.io/janus-guide/
72. RFC_XR_Fragments.html#%F0%9F%A7%B0 AFRAME
73. https://docs.blender.org/manual/en/2.79/data_system/custom_properties.html
74. RFC_XR_Fragments.html#href
75. RFC_XR_Fragments.html#predefined_view
76. RFC_XR_Fragments.html#%F0%9F%8C%8E%20JanusXR%20immersive%20web
77. https://threejs.org/
78. RFC_XR_Fragments.html
79. RFC_XR_Fragments.txt
80. RFC_XR_Fragments.html
81. https://coderofsalvation.github.io/janus-guide/
82. RFC_XR_Fragments.html#%F0%9F%A7%B0 AFRAME
83. https://docs.blender.org/manual/en/2.79/data_system/custom_properties.html
84. RFC_XR_Fragments.html#%F0%9F%93%9C%20level0%3A%20File
85. RFC_XR_Fragments.html#%23%21
86. RFC_XR_Fragments.html
87. RFC_XR_Fragments.txt
88. https://i.imgur.com/E3En0gJ.png
89. https://i.imgur.com/lpnTz3A.png
90. sandbox
91. RFC_XR_Fragments.html#href
92. RFC_XR_Fragments.html#%F0%9F%93%9C%20level0%3A%20File
93. RFC_XR_Fragments.html#href
94. RFC_XR_Fragments.html#href
95. RFC_XR_Fragments.html#teleport%20camera
96. RFC_XR_Fragments.html#href
97. RFC_XR_Fragments.html#href
98. RFC_XR_Fragments.html#%F0%9F%93%9C%20level0%3A%20File
99. RFC_XR_Fragments.html#href
100. RFC_XR_Fragments.html#href
101. RFC_XR_Fragments.html#hashbus
102. RFC_XR_Fragments.html#two-button-navigation
103. RFC_XR_Fragments.html#accessibility-interface
104. https://my.org/worldX.glb#roomY
105. RFC_XR_Fragments.html#href
106. RFC_XR_Fragments.html#collidable%20%2F%20walkable%20objects
107. https://github.com/coderofsalvation/xrfragment/blob/main/src/3rd/js/three/xrf/pos.js
108. https://github.com/coderofsalvation/xrfragment/issues/5
109. RFC_XR_Fragments.html
110. RFC_XR_Fragments.txt
111. RFC_XR_Fragments.html#navigating-3d
112. RFC_XR_Fragments.html#href
113. RFC_XR_Fragments.html#sidecar%20files
114. RFC_XR_Fragments.html#href
115. RFC_XR_Fragments.html#sidecar%20files
116. RFC_XR_Fragments.html#href
117. https://coderofsalvation.github.io/janus-guide/
118. RFC_XR_Fragments.html#%F0%9F%A7%B0 AFRAME
119. RFC_XR_Fragments.html#href
120. RFC_XR_Fragments.html#native%20vs%20XRF%20features
121. https://janusxr.org/docs/build/roomtag/index.html#Link
122. https://janusxr.org/
123. https://omigroup.github.io/gltf-extensions/OMI_link
124. RFC_XR_Fragments.html
125. RFC_XR_Fragments.txt
126. RFC_XR_Fragments.html#overlap-with-fileformat-specific-extensions
127. RFC_XR_Fragments.html#How%20it%20works
128. https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes
Hidden links:
130. RFC_XR_Fragments.html