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か所に絞りました。


