Babylon.jsにWebXR Depth Sensing Featureを実装し、コミットしていく作業ログ

こちらのBabylon.js Forumの投稿がきっかけで、Babylon.jsにコミットすることになった
コミット内容は、WebXR Depth Sensing Moduleの実装をラップしたWebXR Featureを実装するというもの
https://forum.babylonjs.com/t/webar-demo-of-creating-depth-image-of-real-world-using-depth-sensing/34745

実は以前からこのissueは上がっていたのだが、先送りにされているなぁという風に見える
https://github.com/BabylonJS/Babylon.js/issues/11876

このissueがきっかけというわけではないんだけど、
前から気になっていたので使って見て、なんとなく実装方法を調べたらなんとなく行けそうな気がした
そんな流れでした

該当PRはこちら
https://github.com/BabylonJS/Babylon.js/pull/13159

とりあえず一通り自分の中では実装ができたので、PRのDraftを外してレビュー段階に突入
CIでlintが失敗していたので修正

メンテナのRaananさんからコメントが届いた

Thank you so much for thie PR! Great work :-)
We try not to provide the dev directly with WebXR objects but abstract the usage as much as we can.
For example - CPU usage, it seems like we can "init" the XRCPUDepthInformation object internally, and then, once available, provide the getDepthInMeters directly, or at least abstract that to the dev.
Regarding GPU, we should not provide a WebGL2Texture to the user, but a babylon texture that the user can use. Internally, the user can have access to the internal texture, but the public API should be a babylon object and not a WebXR/WebGL object.
We should provide something extra to the dev, otherwise there is no difference between using the feature and implementing it yourself.

要約すると、

• Babylon.jsではWebXR Device APIのメソッドをそのまま提供するのは避けている
• 特別な機能を提供しないと実装する意味があまりなくなってしまう
• だからCPU depth usageでは get depth in meterなどをダイレクトに提供したり、GPUはTextureにラップしたりしたい

EngineにはWebGLTextureをInternalTextureに、InternalTextureはTextureに変換できる

ここら辺をWebGL系には実装したい

ひとまずAPI仕様を提案してみた
前回と違い、イベント駆動でpush型での取得ではなく
pull型で取得するような感じ

どうかな。。。

いろいろあって一回PRがクローズされた
ちょっと時間を空けすぎてしまったのと、おそらくbabylonのリポジトリでちょっとしたコミット整理が行われた？のかもしれない
PRのログもなんか変な感じになってて、GitHubのsync機能を使っても自分のforkリポジトリでコンフリクトが起きてしまっていた

これでは本体にコミットできないのでローカルでコンフリクトを解決してupstreamとforkのmasterを同期させることに
記事はこちらを参考にしている
https://dev-yakuza.posstree.com/git/sync-fork-repository/

これ、一生手動でコンフリクトを解決しなくちゃいけないかもしれない
なぜかrebaseに一回成功しても次のコミットでまたコンフリクトする
これは無理だなと思った

repo cleanup、いったい何が起きたんだろうか……

ということで惜しいけどfork先のリモートリポジトリごと消去してforkしなおすことにする
これは無理だと思ったので

fork先のリポジトリが消えるとPR消える......？そんなことはないとおもうんだけど、もしそうなったら怖いので
コミットの履歴を何とかしてバックアップしたいなぁ

fork/feature/webxr-depth-sensing->fork/masterへの差分は普通に見ることができたので
一応変更は追えそう

今のところGitHubにはforkを解除する方法はなくて、基本的にリポジトリを削除するしかない
ここの方法が良さそうだった

fork先をimportする方法は失敗した
かなり時間がかかってて心配だったけど、githubから失敗したよってメールが来た×２回

それで次にupstreamのないローカルリポジトリをpushしようと思たが、こんな感じのエラーに
おそらく上限に引っかかったんだと思われる

いやぁ難儀だなBabylonのリポジトリ
まぁ歴史があるし仕方がないのか……

これ、詰みでは？
もうしょうがないから差分はローカルで見ることにするかぁ？

一応zennにも取っておくことにする

変更があったのは全部で５種類のファイル

/**
 * BEGIN WebXR Depth Sensing Moudle
 * https://www.w3.org/TR/webxr-depth-sensing-1/
 */

type XRDepthUsage = "cpu-optimized" | "gpu-optimized";
type XRDepthDataFormat = "luminance-alpha" | "float32";

type XRDepthStateInit = {
    readonly usagePreference: XRDepthUsage[];
    readonly dataFormatPreference: XRDepthDataFormat[];
};

interface XRSessionInit {
    depthSensing?: XRDepthStateInit;
}

interface XRSession {
    readonly depthUsage: XRDepthUsage;
    readonly depthDataFormat: XRDepthDataFormat;
}

interface XRDepthInformation {
    readonly width: number;
    readonly height: number;

    readonly normDepthBufferFromNormView: XRRigidTransform;
    readonly rawValueToMeters: number;
}

interface XRCPUDepthInformation extends XRDepthInformation {
    readonly data: ArrayBuffer;

    getDepthInMeters(x: number, y: number): number;
}

interface XRFrame {
    getDepthInformation(view: XRView): ?XRCPUDepthInformation;
}

interface XRWebGLDepthInformation extends XRDepthInformation {
    readonly texture: WebGLTexture;
}

interface XRWebGLBinding {
    getDepthInformation(view: XRView): ?XRWebGLDepthInformation;
}

/**
 * BEGIN WebXR Depth Sensing Moudle
 * https://www.w3.org/TR/webxr-depth-sensing-1/
 */

1149行目から

import { WebXRFeatureName, WebXRFeaturesManager } from "./../webXRFeaturesManager";
import { Observable } from "../../Misc/observable";
import type { WebXRSessionManager } from "../webXRSessionManager";
import { WebXRAbstractFeature } from "./WebXRAbstractFeature";
import { Tools } from "../../Misc/tools";

/**
 * Options for Depth Sensing feature
 */
export interface IWebXRDepthSensingOptions {
    /**
     *  The desired depth sensing usage for the session
     */
    usagePreference: XRDepthUsage[];
    /**
     * The desired depth sensing data format for the session
     */
    dataFormatPreference: XRDepthDataFormat[];
}

/**
 * WebXR Feature for WebXR Depth Sensing Module
 */
export class WebXRDepthSensing extends WebXRAbstractFeature {
    /**
     * An observable which triggered when the CPU depth information is acquired from XRFrame
     */
    public onCPUDepthInformationObservable: Observable<XRCPUDepthInformation> = new Observable();

    /**
     *An observable which triggered when the WebGL depth information is acquired from XRFrame
     */
    public onWebGLDepthInformationObservable: Observable<XRWebGLDepthInformation> = new Observable();

    /**
     * XRWebGLBinding which is used for acquiring WebGLDepthInformation
     */
    private _glBinding?: XRWebGLBinding;

    /**
     * The module's name
     */
    public static readonly Name = WebXRFeatureName.DEPTH_SENSING;

    /**
     * The (Babylon) version of this module.
     * This is an integer representing the implementation version.
     * This number does not correspond to the WebXR specs version
     */
    public static readonly Version = 1;

    /**
     * Creates a new instance of the depth sensing feature
     * @param _xrSessionManager the WebXRSessionManager
     * @param options options for WebXR Depth Sensing Feature
     */
    constructor(_xrSessionManager: WebXRSessionManager, public readonly options: IWebXRDepthSensingOptions) {
        super(_xrSessionManager);
        this.xrNativeFeatureName = "depth-sensing";

        // https://immersive-web.github.io/depth-sensing/
        Tools.Warn("depth-sensing is an experimental and unstable feature.");
    }

    /**
     * attach this feature
     * Will usually be called by the features manager
     *
     * @returns true if successful.
     */
    public attach(force?: boolean | undefined): boolean {
        if (!super.attach(force)) {
            return false;
        }

        const isDepthUsageAndFormatNull = this._xrSessionManager.session.depthDataFormat == null || this._xrSessionManager.session.depthUsage == null;
        if (isDepthUsageAndFormatNull) {
            return false;
        }

        this._glBinding = new XRWebGLBinding(this._xrSessionManager.session, this._xrSessionManager.scene.getEngine()._gl);

        return true;
    }

    /**
     * Dispose this feature and all of the resources attached
     */
    public dispose(): void {
        this.onCPUDepthInformationObservable.clear();
        this.onWebGLDepthInformationObservable.clear();
    }

    protected _onXRFrame(_xrFrame: XRFrame): void {
        const referenceSPace = this._xrSessionManager.referenceSpace;

        const pose = _xrFrame.getViewerPose(referenceSPace);
        if (pose == null) {
            return;
        }

        for (const view of pose.views) {
            const depthUsage = this._xrSessionManager.session.depthUsage;
            switch (depthUsage) {
                case "cpu-optimized":
                    this._getAndNotifyCPUDepthInformation(_xrFrame, view);
                    break;

                case "gpu-optimized":
                    if (this._glBinding == null) {
                        const context = this._xrSessionManager.scene.getEngine()._gl;
                        this._glBinding = new XRWebGLBinding(this._xrSessionManager.session, context);
                    }

                    this._getAndNotifyWebGLDepthInformation(_xrFrame, view, this._glBinding);
                    break;

                default:
                    Tools.Error("Unknown depth usage");
            }
        }
    }

    private _getAndNotifyCPUDepthInformation(frame: XRFrame, view: XRView): void {
        const cpuDepthInfo = frame.getDepthInformation(view);
        if (cpuDepthInfo == null) {
            return;
        }

        this.onCPUDepthInformationObservable.notifyObservers(cpuDepthInfo);
    }

    private _getAndNotifyWebGLDepthInformation(frame: XRFrame, view: XRView, glBinding: XRWebGLBinding): void {
        const webglDepthInfo = glBinding.getDepthInformation(view);
        if (webglDepthInfo == null) {
            return;
        }

        this.onWebGLDepthInformationObservable.notifyObservers(webglDepthInfo);
    }

    /**
     * Extends the session init object if needed
     * @returns augmentation object for the xr session init object.
     */
    public getXRSessionInitExtension(): Promise<Partial<XRSessionInit>> {
        const isDepthUsageDeclared = this.options.usagePreference != null && this.options.usagePreference.length !== 0;
        const isDataFormatDeclared = this.options.dataFormatPreference != null && this.options.dataFormatPreference.length !== 0;
        return new Promise((resolve) => {
            if (isDepthUsageDeclared && isDataFormatDeclared) {
                resolve({ depthSensing: this.options });
            } else {
                resolve({});
            }
        });
    }
}

WebXRFeaturesManager.AddWebXRFeature(
    WebXRDepthSensing.Name,
    (xrSessionManager, options) => {
        return () => new WebXRDepthSensing(xrSessionManager, options);
    },
    WebXRDepthSensing.Version,
    false
);

これはもう新規ファイルなのでこれだけ

↑をfeaturesとしてexportする

export * from "./WebXRLightEstimation";
export * from "./WebXREyeTracking";
export * from "./WebXRWalkingLocomotion";
export * from "./WebXRDepthSensing";
export * from "./WebXRLayers";

WebXRFeatureNameに登録

/**
     * The name of the depth sensing feature
     */
    public static readonly DEPTH_SENSING = "xr-depth-sensing";

ヨシ！これですっきりしたんでforkリポジトリを消しましたぁ！

forkが消えても普通にPRとかは生きてるっぽいな
まぁそりゃそうなのかもだけど

久しぶりにbabylonの開発環境を整えるので、ｎｐｍ link周りの情報を集めていた
https://qiita.com/keitakn/items/7114b47cfd9429cfe474
https://qiita.com/keitakn/items/7114b47cfd9429cfe474

babylonのbuildSystem.mdにはこんな感じに書かれているので、これをやろうと思う
npm linkの-wオプションはワークスペースの指定っぽいんだよな
これを付ければcoreワークスペースだけlinkできるってことっぽい

babylonjsの指示通りにnpx nx build coreしたあとにnpm link -w @babylonjs/coreしてみた
普通にできた
ちなみにnpm run prepublishOnly~~はコマンドがないといわれてできなかった

そのごnpm viteで作ったvanilla-tsなプロジェクトにnpm link @babylonjs/coreしてみたらふつうに入った。すごい
ちゃんとsymlinkな表示にもなっている

前はコード変更してビルドしなおしても反映されないということもあったけど、今回はなぜか普通に成功した
まぁなぜかというか本来こうあるべきなんだけど

とりあえずPRクローズ前の状態まで持ってきた
link先のプロジェクトでもうまく型補完が効いているのでいい感じ

おそらくfeatureの有効化の処理はこれで正解な気がする
問題はWebXRDepthSensingの提供するAPIなので、これから底の部分を作りこんでいく

WebGLTextureからTextureを生成する方法について言及があるForum
https://forum.babylonjs.com/t/native-webgltexture-to-babylonjs-texture/29148

上のフォーラム的には、engineでwrapなんちゃらを呼び出してWebGLTexture→InternalTextureに変換して
Textureのコンストラクタに指定すればできるよとのこと

InternalTexture→Textureなんだけど、Textureクラスにはそのような仕組みは用意されていないみたい
だけどBaseTextureのコンストラクタではいけそうなので、簡単にやるならBaeTextureかなぁ
https://doc.babylonjs.com/typedoc/classes/BABYLON.BaseTexture#constructor

BaseTextureはreadPixelsメソッドもあるし、マテリアルのテクスチャデータとしてもつかわれるのでこれはこれでありかなぁと

cpuモードだった場合は16bit整数値配列なので、画素配列に変換してtextureを作る必要がある
RawTextureに便利メソッドがあるのでそれが使えそう

ArrayBufferViewが渡せるので、DepthInfo.dataをそのまま渡せるのかな

このあと

• usageとformatごとにどういうやり方でテクスチャデータを生成するかを整理する
• WebGLTexture→InternalTextureのAPIを調べる

やっぱりなぜかデスクトップのVSCodeだと、rg.exeが無限に生成されてメモリ破壊されるわね......
https://twitter.com/ninisan_drumath/status/1612399466514087936

テクスチャ生成方法の整理をする
（CPU、GPU）×（luminance-alpha、float32）の4通り

CPUモード でluminance-alpha

WebXRCPUDepthInfoをXRFrameから取得
DepthInfo.dataから深度値配列（ArrayBufferView）を取得
RawTexture.CreateLuminanceAlphaTexture()でテクスチャを生成

CPUモードでfloat32

WebXRCPUDepthInfoをXRFrameから取得
DepthInfo.dataから深度値配列を取得
RawTexture.CreateRGBATextureでテクスチャを生成

GPUモードでluminancealpha・float32

WebGLDepthInfoをXRWebGLBindingから取得
WebGLTextureをInternalTextureに変換し、InternalTextureをコンストラクタ引数にBaseTextureを生成

WebGLTextureからTextureの構成についてのforum、もう一個あった
ちょっと汚さそうだけどできるみたい
wrapWebGLTexture使ってダメだったらこっちやりたいわね
https://forum.babylonjs.com/t/constructing-a-texture-from-webgltexture/17991/13

engine.wrapWebGLTexture
https://doc.babylonjs.com/typedoc/classes/BABYLON.Engine#wrapWebGLTexture

このPlaygroundがwrapWebGLTextureをやっている
canvasを2dコンテキストで生成して描画して、それをWebGLTextureにしてInternalTextureを生成してBaseTextureを生成している
これは参考になるな
https://playground.babylonjs.com/#MBXLI0#0

publicなAPIの整理をする

フィールド・プロパティ

メソッド

キャッシュしたDepthInfoからAPIを露出させる作業していました
きれいな実装なのかちょっとわからないけど進めています
まぁもともとの実装を参考にしているので作業ゲー感はあります

テクスチャの実装はやめに取り掛かりたいなぁ
そしてデバッグをしなければ

デスパで久しぶりにビルドの時にメモリが破壊される奴に出会った
また苦戦していると、VSCodeのAuto Import拡張機能をdisableにしたら治った
マジか......

そのあと色々やってたら、なぜかlinkしてもシンボリックリンクの先でディレクトリが空になってる自体に遭遇
たぶんビルド時にメモリリークの問題で中断したのが良く無くて、変な感じに残ったキャッシュのせいで
中途半端なキャッシュが読み込まれてそれが実行成功だと勘違いされていた可能性がある

そうしたらリンクは成功した

そしたらなぜか次にDepthSensingFweatureだけビルドされていないという事態に陥った
普通に困った

なぜかdevサーバーだとWebXRDepthSensingがexportされていないというシンタックスエラーがブラウザで出る
だけどビルドした後でnpm run previewしてみると普通に動いている。
この現象はいったい......

とはいえDepth sensingでデバッグできるまでになった～～～～

ノーパソで作業
AndroidをワイヤレスデバッグでつないでWebView Debuggerでデバッグしてる
ノーパソではいい感じに動いている

なぜかgetDepthInMetersが動いていないのでここは治さなきゃ

depth bufferからRawTextureを作成するやつ
widthとheightは設定できていそうだけど、readPixelsでバッファが取得できていない

現状を整理

• widthとかheightみたいな基本的ななデータはちゃんと取れていることがわかった
• getDepthInMetersみたいな関数はXRFrameがアクティブでなくなってしまうために使用できない
• DepthBufferはキャッシュできているがテクスチャの生成で失敗している
  • CreateLuminanceAlphaTextureの使い方（特にArrayBufferViewの中身）が違うのかもしれない

このPlaygroundが参考になりそうな気がした
https://playground.babylonjs.com/#0NHRHE#0

このsandboxでちょっと試していたりした
なぜかLuminaceAlphaなテクスチャでReadPixelsすると何も返ってきてくれないんだよなぁ
https://playground.babylonjs.com/#2T5E69

一応TSのTypeｄArrayは相互変換可能か

戦略として、深度画像はRGBAで作る
その時にはUint8ArrayにArrayBufferを変換して使う
どんな画像になるかはわからないけども

ということで16bitのdepthをRGBAに焼きこんだら邪悪なテクスチャができた！

深度画像とは違うんだけど、まぁテクスチャにすることはできた

readPixelsはできないけど、depth値をモノクロで描画することはできるよなぁと思い、実装してみた
いい感じ

なおこれは誇張に表現しているので、実際のdepth画像はもっと黒っぽくなると思う

LuminanecTextureやLuminanceAlphaTextureを作ったときにreadPixelsができない問題の再現PGを作成した
https://playground.babylonjs.com/#TPJ26Z#1

• OS: Windows 11 Home
• Browser: Chrome 109.0.5414.75
• Babylon.js: 5.43.0

フォーラムに報告
https://forum.babylonjs.com/t/readpixels-doesnt-works-with-luminance-alpha-texture/37599

RTextureで深度画像を生成

Textureの生成処理を洗練させてきているフェーズ
GPUモードでデバッグできないのがちょっとな点だけど、割といい感じ

やりたいことリスト

• depth textureを作る際に圧縮する数値ファクタをユーザが指定できるようにする
• テクスチャを生成するかどうかを指定できるようにする
• getDepthInMeteersの実装
• GPUモードでデバッグできないか検証

ちょっと時間が空いてしまいました
いい加減PR出したい気持ちになっています

なのであまり凝ったことはせずに、シンプルな方法で実装してメンテナの人の意見を聴こうかなーって思っているところです

あと、最近スマホAR系のカメラアクセスAPIでは取得画像がなぜか90度回転している問題があるあるらしいことが分かったのと、スマホのOrientation（横向きか縦向き）によって変える必要が出てきたぽい話

WebAPIではScreen.orientationで取得できるみたいです
https://developer.mozilla.org/ja/docs/Web/API/Screen/orientation

TextureFormatとTextureTypeの対応があった
https://registry.khronos.org/webgl/specs/latest/2.0/#TEXTURE_TYPES_FORMATS_FROM_DOM_ELEMENTS_TABLE

ん－ただこれの通りにやってもうまくいかんな

floatにすると色の限界を超えてもreadPixelsで値が保存されるっぽい

floatいいな
rawValueTometersかけてfkoatバッファで保存するのもあり

ここら辺はキメの問題かなぁ
とりまじっそうしよ

CPUモードではRawTextureのバッファにfloatで記録するようにした
これはluminance-alphaでもfloat32でもどっちでも
rawValueToMetersをかけることによって統一している

floatにする利点は以下二つ

• 表示上は2.55で打ち切られる→Depth画像としていい感じに映る
• バッファ上は打ち切られることなく情報は残る
  • つまり表示上は3m以上は真っ赤になるけど、readPixelsすると3m以上の深度値も残ってるということ

実際に部屋の中で表示してみた結果がこちら

これでDepthテクスチャの問題は解決
PR出す前にgetDepthInMetersの取得方法を自分なりに提示したい
こいつはメソッドだからかわからないけど、キャッシュしたDepthInfoから呼び出すとXRFrameが無効でエラーが出てしまう
つまり有効なXRFrameを取得して、そいつが生きている間じゃないと実行できないので
これはイベントで通知するのがいいと思っている

想定していた方法で実装していたら、IllegalInvocationエラーが出た
getDepthInMeterメソッドをObserverとして通知する時は、かならずthisをbindさせる必要があるみたいなのでそうした
https://qiita.com/uhyo/items/a41cf51399de6f3fbd60

getDepthInMetersの実装も完了

今のところのAPI仕様

ということで、おおよそ理想通りに実装できた＆動いたので
PRを投げました
https://github.com/BabylonJS/Babylon.js/pull/13563

メンテナのRaananさんから8件のレビューをいただいた

パッと見、そんなに大きな指摘はなかったなという印象
それこそ一番最初のPRでは全体のAPI構成を変えなくてはいけない、大掛かりな変更になったが
今回は細かい指摘であったり、データ形式の変更などのものが多かった
なので割と早めに対応

ここまで順調に対応していき、とうとうマージ！

スカッシュマージなのでコミット数は反映されないけど、確かに自分のコードが刻まれた瞬間だった

ということで、ここからはDepth sensingに関するdocsを書いていきます

ドキュメントを作成してみたので、docsにプルリクを出してみた
https://github.com/BabylonJS/Documentation/pull/789

無事にBabylon.js v5.49.1としてリリースされました🎉
https://github.com/BabylonJS/Babylon.js/releases

これにてこちらのscrapはクローズ。
いや～長かったな