AIで作る3D素材をZIPで渡す前に、glTFが参照する2ファイルを照合したサンプル

AIで作る3D素材をZIPで渡す前に、glTFが参照する2ファイルを照合したサンプル

3DモデルをZIPで渡しても、購入者の画面で質感だけ消えることがあります。こうした不具合は、見た目ではなく、モデルが参照するファイルの置き場所で起きます。

ここでは実際の販売物ではなく、AIで作った3D素材を配る場面を想定したサンプルを使います。glTFはJSONで書かれた3Dデータ形式です。形状データを置くbufferや、画像を置くimageは、uriで別ファイルを参照できます。KhronosのglTF 2.0仕様でも、この2種類はURIでリソースを指す場所です。

最初は、JSONとして読めれば十分だと思いました。でも../mesh.binやhttps://を許すと、ZIPだけでは完結しません。配るフォルダの外を読ませる指定も、商品側に残す理由がありませんでした。

参照先を2か所だけ拾う

今回のサンプルは、buffersとimagesのuriだけを見ます。data:で始まる埋め込みデータはこのサンプルでは許しません。外部のURL、先頭が/のパス、バックスラッシュ、..を含む相対パスも止めます。

import json
import sys
from pathlib import PurePosixPath


def is_safe_uri(uri):
    if not isinstance(uri, str) or not uri:
        return False
    if uri.startswith(("data:", "http:", "https:", "file:", "/", "\\")):
        return False
    path = PurePosixPath(uri)
    return ".." not in path.parts and "\\" not in uri


def main(path):
    doc = json.loads(open(path, encoding="utf-8").read())
    bad = []
    for kind in ("buffers", "images"):
        for i, item in enumerate(doc.get(kind, [])):
            uri = item.get("uri")
            if uri is not None and not is_safe_uri(uri):
                bad.append(f"{kind}[{i}].uri={uri!r}")
    if bad:
        print("ERROR 外部または親ディレクトリを指すURIがあります")
        print("\n".join(bad))
        return 2
    print("OK buffers/images のURIは配布フォルダ内の相対パスです")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1]))

販売前の検査としては、商品のZIPを展開した直後にこのコードを走らせます。その後にKhronosのglTF Validatorで形式そのものを検証します。URIの配布ルールと、glTF仕様への適合は別に見るためです。

配布フォルダ内だけを指す正常なサンプル

ok/model.gltfには、同じZIPに入るmesh.binとtextures/card.pngを置きます。

{
  "asset": {"version": "2.0"},
  "buffers": [{"uri": "mesh.bin", "byteLength": 0}],
  "images": [{"uri": "textures/card.png"}]
}
python3 check_gltf_refs.py ok/model.gltf; echo "exit=$?"
OK buffers/images のURIは配布フォルダ内の相対パスです
exit=0

この結果だけでは、mesh.binやPNGが本当にZIPに入っていることまでは分かりません。次の段階で、検査対象のURIごとにファイルの存在も確かめる予定です。ここを一度に作ろうとすると、URIのルールと同梱漏れの原因が混ざります。

確認対象を分けると、購入者から「画像が出ない」と言われた時にも追いやすくなります。URIの検査で止まれば参照先の書き方を直します。存在確認で止まれば、ZIPへ入れるファイルを見直します。止まった理由を、配布前に分けておくための小さな境界です。

..と外部URLは同時に止める

失敗用のbad/model.gltfには、親ディレクトリを指すバイナリと、外部URLの画像を置きます。どちらも購入者へ渡すZIPだけでは解決できません。

{
  "asset": {"version": "2.0"},
  "buffers": [{"uri": "../mesh.bin", "byteLength": 0}],
  "images": [{"uri": "https://example.invalid/card.png"}]
}
python3 check_gltf_refs.py bad/model.gltf; echo "exit=$?"
ERROR 外部または親ディレクトリを指すURIがあります
buffers[0].uri='../mesh.bin'
images[0].uri='https://example.invalid/card.png'
exit=2

..だけを見ても、外部のテクスチャは残ります。反対にURLだけを見ても、ZIPを展開する場所に依存する参照が残ります。販売前に止めるなら、2種類を同じ終了コードで落とすほうが扱いやすいです。

AIに任せる範囲を小さくする

AIへ3D素材の作成を頼む時は、モデルの見た目と同じくらい、納品するフォルダ構成を指定したいです。ただ、生成されたJSONをそのまま信用するより、配布前に機械的な検査を1つ置くほうが安全です。

このサンプルは、glTFのすべてを検査しません。拡張機能やGLB、埋め込み画像は別の条件が必要です。小さな商品で最初に確認する対象を、外部参照の2か所に絞りました。

参照

この記事をシェア