Merge pull request #53 from 5G-MAG/xr-media-integration

Initial documentation for XR media integration in 5G

pages/xr-media-integration-in-5g/features/csv2md.py

@@ -0,0 +1,60 @@
+import pandas as pd
+from collections import defaultdict
+import markdown
+import sys 
+from pathlib import Path
+
+# columns = [
+#     "Extension",
+#     "Property",
+#     "Status",
+#     "Requirement",
+#     "Test content" ]
+#     #, "notes" ]
+
+class StringConverter(dict):
+    def __contains__(self, item):
+        return True
+
+    def __getitem__(self, item):
+        return str
+
+    def get(self, default=None):
+        return str
+
+def main(fp, csv2md, md2html):
+
+    mdfp = fp.with_suffix('.md')
+    htmlfp = fp.with_suffix('.html')
+
+    # df = pd.read_csv(fp, usecols=columns, converters=StringConverter())
+
+    if csv2md:
+        df = pd.read_csv(fp, converters=StringConverter())
+        with open(mdfp, 'w') as md:
+            df.to_markdown(buf=md, index=False)
+
+    if md2html:
+        with open(htmlfp, 'w') as fo:
+            with open(mdfp, 'r') as md:
+                data = md.read()
+                data = data.replace("[ ]", "☐")
+                data = data.replace("[x]", "☑")
+                html = markdown.markdown(data, extensions=['markdown.extensions.tables'])
+                fo.write(html)
+
+if __name__ == "__main__":
+
+    assert len(sys.argv) > 1
+    fp = Path(sys.argv[1])
+    assert fp.exists()
+
+    if len(sys.argv) == 2:
+        csv2md = True
+        md2html = True
+    else:
+        csv2md = 'csv2md' in sys.argv
+        md2html = 'md2html' in sys.argv
+
+
+    main(fp, csv2md, md2html)

pages/xr-media-integration-in-5g/index.md

@@ -6,4 +6,4 @@ nav_order: 7
 ---
 
 # XR Media integration in 5G
-<iframe width="100%" height="440" src="https://drive.google.com/file/d/1D8G_rzx77V_W3d3NB59XcTbdUuBdtKgp/preview"></iframe>
+<iframe width="100%" height="440" src="https://drive.google.com/file/d/1D8G_rzx77V_W3d3NB59XcTbdUuBdtKgp/preview"></iframe>

pages/xr-media-integration-in-5g/projects.md

@@ -7,6 +7,8 @@ nav_order: 2
 ---
 
 # 🚧 Related projects
-## XR: Repositories with ISO/IEC 23090-14:2023 functionalities - Release 1.0.0
-All issues related to the release of version 1.0.0 of the XR repositories dealing with functionalities defined in ISO/IEC 23090-14
+
+## XR : reference XR Player implemented in Unity3D
+
+All issues related to the release of development of the Unity3D XR Player supporting [functionalities defined in ISO/IEC 23090-14](features)
 * [Kanban board](https://github.com/orgs/5G-MAG/projects/22)

pages/xr-media-integration-in-5g/repositories.md

@@ -9,22 +9,24 @@ nav_order: 3
 # ⭐ Related repositories
 Note that these repositories are currently private and under testing. Early access can be requested at: https://www.5g-mag.com/early-access
 
+See also: [xr-player-overview](tutorials/xr-player-overview) 
+
 ## XR Unity Player: [rt-xr-unity-player](https://github.com/5G-MAG/rt-xr-unity-player)
 * [Information and how to download, build, install and run](https://github.com/5G-MAG/rt-xr-unity-player#readme)
 * [Releases](https://github.com/5G-MAG/rt-xr-unity-player/releases)
 
-## XR Blender Exporter: [rt-xr-blender-exporter](https://github.com/5G-MAG/rt-xr-blender-exporter)
-* [Information and how to download, build, install and run](https://github.com/5G-MAG/rt-xr-blender-exporter#readme)
-* [Releases](https://github.com/5G-MAG/rt-xr-blender-exporter/releases)
-
-## Efficient glTF 3D import / export package for Unity: [rt-xr-gITFast](https://github.com/5G-MAG/rt-xr-gITFast)
+## A fork of Unity's glTF parser: [rt-xr-gITFast](https://github.com/5G-MAG/rt-xr-gITFast)
 * [Information and how to download, build, install and run](https://github.com/5G-MAG/rt-xr-gITFast#readme)
 * [Releases](https://github.com/5G-MAG/rt-xr-gITFast/releases)
 
-## XR MAF Plugin: [rt-xr-maf-plugin](https://github.com/5G-MAG/rt-xr-maf-plugin)
-* [Information and how to download, build, install and run](https://github.com/5G-MAG/rt-xr-maf-plugin#readme)
-* [Releases](https://github.com/5G-MAG/rt-xr-maf-plugin/releases)
-
-## XR MAF Native: [rt-xr-maf-native](https://github.com/5G-MAG/rt-xr-maf-native)
+## Media pipelines factory and plugins implementing the MAF API: [rt-xr-maf-native](https://github.com/5G-MAG/rt-xr-maf-native)
 * [Information and how to download, build, install and run](https://github.com/5G-MAG/rt-xr-maf-native#readme)
-* [Releases](https://github.com/5G-MAG/rt-xr-maf-native/releases)
+* [Releases](https://github.com/5G-MAG/rt-xr-maf-native/tags)
+
+## Test content: [rt-xr-content](https://github.com/5G-MAG/rt-xr-content)
+* [Information](https://github.com/5G-MAG/rt-xr-content#readme)
+* [Releases](https://github.com/5G-MAG/rt-xr-maf-native/tags)
+
+## Blender Exporter: [rt-xr-blender-exporter](https://github.com/5G-MAG/rt-xr-blender-exporter)
+* [Information and how to download, build, install and run](https://github.com/5G-MAG/rt-xr-blender-exporter#readme)
+* [Releases](https://github.com/5G-MAG/rt-xr-blender-exporter/releases)

pages/xr-media-integration-in-5g/specifications.md

@@ -5,6 +5,8 @@ parent: XR Media Integration in 5G
 has_children: false
 nav_order: 0
 ---
+
 # 📑 Specifications and relevant references
 * Information about relevant specifications can be found at the [Standards Wiki](https://github.com/5G-MAG/Standards/wiki/XR-(eXtended-Reality):-Relevant-Specifications)
 * A list of relevant 3GPP Work Items can be found at [Standards Wiki](https://github.com/5G-MAG/Standards/wiki/XR-(eXtended-Reality):-Relevant-Work-Items)
+* The XR Player supports loading interactive 3D scenes in the format specified in [ISO/IEC 23090-14:2023](https://www.iso.org/standard/86439.html).

pages/xr-media-integration-in-5g/tutorials.md

@@ -5,7 +5,4 @@ parent: XR Media Integration in 5G
 has_children: true
 nav_order: 4
 ---
-
-# ▶️ Using the tools
 Check the [TUTORIALS & DEVELOPER XCHANGES](https://www.5g-mag.com/tutorials) in the 5G-MAG website and the information below.
-* We are working on it...

pages/xr-media-integration-in-5g/tutorials/xr-player-overview.md

@@ -0,0 +1,69 @@
+---
+layout: default
+title:  XR Player project overview
+parent: Tutorials
+grand_parent: XR Media Integration in 5G
+has_children: false
+nav_order: 0
+---
+
+# XR Player : project overview
+
+## Scene description format
+
+The Scene Description format standardized by [ISO/IEC JTC 1/SC29/WG03](https://www.iso.org/committee/45316.html) MPEG Systems in [ISO/IEC 23090-14](https://www.iso.org/standard/86439.html) specifies a framework enabling the composition of 3D scenes for immersive experiences, anchoring 3D assets in the real world, facilitating rich interactivity, supporting real-time media delivery.
+
+It establishes interfaces like the Media Access Function (MAF) API to enable cross-platform interoperability, ensuring efficient retrieval and processing of media data, by decoupling the Presentation Engine from media pipeline.
+
+
+## XR Player implementation
+
+![Alt text](../images/rt-xr-overview.jpg) 
+
+The XR Player is implemented as a Unity3D project: [rt-xr-unity-player](https://github.com/5G-MAG/rt-xr-unity-player).
+
+The unity project builds on the following dependencies:
+* [rt-xr-glTFast](https://github.com/5G-MAG/rt-xr-gITFast): parsing and instantiating of 3D scenes in Unity.
+* [rt-xr-maf-native](https://github.com/5G-MAG/rt-xr-maf-native): a C++ Media Access Functions (MAF) API implementation, extensible with custom media pipeline plugins. 
+
+
+
+
+### Test content
+
+* [rt-xr-content](https://github.com/5G-MAG/rt-xr-content): test content implementing the scene description format.
+
+
+See the [features page](features) for implementation status of the scene description format.
+
+
+## MAF API & Media pipelines
+
+The Media Access Functions (MAF) API is specified in ISO/IEC 23090-14:2023.
+
+It's purpose is to decouple the presentation engine from media pipeline management, it allows the Presentation Engine to:
+- pass View informations to the media pipelines (eg. to optimize fetching media )
+- read media buffers updated by the media pipelines
+
+
+The MAF API is protocol and codec agnostic, media can be fetched a remote URL.
+
+
+
+### Media player implementation
+
+#### MediaPlayer component 
+
+The MediaPlayer component is part of the Presentation Engine layer:
+
+![Alt text](../images/rt-xr-presentation-engine.jpg)
+
+The MediaPlayer component uses the MAF API implemented by Media Pipelines:
+
+![Alt text](../images/rt-xr-maf-implementation.jpg)
+
+The XR Player uses a C++ implementation of the MAF API. It uses a factory / plugin pattern to allow development of media pipelines.
+
+The mechanism by which a media pipeline is instantiated and buffers initialized, is out of the scope of ISO/IEC 23090-14.
+
+For more on the MAF API implementation, review the [rt-xr-maf-native](https://github.com/5G-MAG/rt-xr-maf-native) repository.

pages/xr-media-integration-in-5g/tutorials/xr-player-win11-openXR.md

@@ -0,0 +1,81 @@
+---
+layout: default
+title:  Using the XR Player on windows
+parent: Tutorials
+grand_parent: XR Media Integration in 5G
+has_children: false
+nav_order: 0
+---
+
+The XR Player Windows release supports rendering on an HMD by default if an OpenXR runtime is installed. 
+
+This tutorial covers usage of XR Player on Windows, rendering on a Meta Quest HMD using Meta Quest Link. 
+
+When no OpenXR runtime is detected, the player runs in a regular desktop window.
+
+
+## Requirements
+
+- Windows 11
+
+In order to support Meta Quest link:
+
+- a Meta Quest headset ( 2, 3 and Pro are confirmed to work)
+- a machine compatible with the [Meta Quest link requirements](https://www.meta.com/en-gb/help/quest/articles/headsets-and-accessories/oculus-link/requirements-quest-link/)
+- the [Oculus PC app for Meta Quest Link](https://www.meta.com/en-gb/help/quest/articles/headsets-and-accessories/oculus-rift-s/install-app-for-link/)
+
+
+### Meta Quest Link support
+
+- Follow the instructions on [Meta's support article](https://www.meta.com/en-gb/help/quest/articles/headsets-and-accessories/oculus-rift-s/install-app-for-link/). The step by step [developer tutorial](https://developer.oculus.com/documentation/unity/unity-link/) also provides some usefull screenshots if you aren't familiar with the Meta Quest platform - note that beta features aren't needed.
+- Meta Quest Link supports a USB mode as well as a [WiFi](https://www.meta.com/en-gb/help/quest/articles/headsets-and-accessories/oculus-link/connect-with-air-link/) mode. 
+- [Adjust graphics perfomance settings](https://www.meta.com/en-gb/help/quest/articles/headsets-and-accessories/oculus-link/link-performance-preferences/) depending on your computer's configuration.
+
+
+## Getting Started
+
+**1. Get the player**
+
+Download the [latest release](https://github.com/5G-MAG/rt-xr-unity-player/tags) or [build](https://github.com/5G-MAG/rt-xr-unity-player?tab=readme-ov-file#build) the XR player.
+
+
+**2. Get the test content**
+
+[Download the latest test content](https://github.com/5G-MAG/rt-xr-content/archive/refs/heads/main.zip) from github's rt-xr-content repository.
+
+**3. Locate the test content to the player directory**
+
+By default the player expects the `rt-xr-content` directory to be located next to the executable so that double clicking on `rt-xr-player.exe` launches without further configuration.
+
+![XR player default content location](../images/xr-player-usage-locate-content.png)
+
+**4. [Start the Meta Quest Link Mode](#meta-quest-link-support) on the headset**
+
+**5. Launch the `rt-xr-player.exe` application**
+
+
+### Command line usage
+
+Launching custom scenes is normaly achieved from the command line, typically PowerShell on windows.
+In that case the content can be located anywhere on the file system or downloaded over http:
+
+#### Launch a scene available over http
+
+![http scene](../images/xr-player-usage-cli-http.png)
+
+
+### Using a custom launcher shortcut
+
+If you downloaded an XR Player release, a drag and drop launcher is provided.
+
+Such a launcher is just create a file with a `.bat` extension and the following content:
+```
+%~dp0rt-xr-player.exe --gltf "%1"
+pause 
+```
+
+> "%1" means the dropped argument, and could be replaced by an URI.
+
+
+![Drag and drop scene](../images/xr-player-usage-drag-n-drop-scene.png)
+