3Dモデルを使ったTEI/XMLの作成ガイド

このガイドでは、3Dモデルに対してアノテーションを付与し、TEI/XML形式で出力する方法を説明します。

概要

3Dアノテーション機能を使うと、3Dモデル上の特定の位置や領域にテキスト情報を関連付けることができます。作成したアノテーションはTEI（Text Encoding Initiative）準拠のXML形式でエクスポートでき、学術的なデジタルアーカイブに活用できます。

ワークフロー

1. GLBファイルを用意
       ↓
2. アノテーションエディタで編集
       ↓
3. XMLエクスポート
       ↓
4. （オプション）XSL作成
       ↓
5. ビューアで表示

1. 3Dモデルの準備

対応フォーマット

現在、GLB形式（glTF Binary）のみ対応しています。

OBJやFBXなどの他形式からは、Blenderなどの3Dソフトウェアで変換してください
ファイルサイズは50MB以下を推奨

GLBファイルの圧縮（推奨）

Webでの表示を高速化するため、GLBファイルの圧縮を強く推奨します。

圧縮ツール: gltf-transform または glTF-Pipeline

gltf-transformを使った圧縮例:

# インストール
npm install -g @gltf-transform/cli

# Draco圧縮を適用（メッシュデータの圧縮）
gltf-transform optimize input.glb output.glb --compress draco

# テクスチャも含めて最適化
gltf-transform optimize input.glb output.glb --compress draco --texture-compress webp

圧縮効果の例:

ファイル	圧縮前	圧縮後	削減率
サンプルモデル	28MB	8.8MB	約69%

圧縮により、ページの読み込み時間が大幅に改善されます。

モデルの配置

GLBファイルはURLでアクセスできる場所に配置します。

配置先の例:

自分のWebサーバー
GitHub Pages
Amazon S3、Google Cloud Storage などのクラウドストレージ
このプロジェクトの public/data/models/ ディレクトリ

注意: アノテーションエディタからアクセスする場合、CORS（Cross-Origin Resource Sharing）の設定が必要な場合があります。同一ドメインに配置するか、適切なCORSヘッダーを設定してください。

2. アノテーションエディタの使い方

エディタを開く

3Dアノテーションエディタにアクセスします。

モデルの読み込み

2つの方法があります：

URL指定: GLBファイルのURLを入力して「読み込み」をクリック
ファイルアップロード: ローカルのGLBファイルをドラッグ&ドロップ、またはファイル選択

アノテーションの種類

3種類のアノテーションを作成できます：

種類	説明	用途
Point	単一の点	特定の位置をマーク
Box	2点で定義される直方体	領域の範囲指定
Polygon	3点以上で定義される多角形	複雑な形状の領域

Point（ポイント）の追加

ツールバーで「+ ポイント」をクリック
モデル上の目的の位置をクリック
右パネルでID・ノート・半径を入力
「追加」をクリック

Box（ボックス）の追加

ツールバーで「+ ボックス」をクリック
最初のコーナーをクリック
対角のコーナーをクリック
詳細を入力して「追加」をクリック

Polygon（ポリゴン）の追加

ツールバーで「+ ポリゴン」をクリック
頂点を順番にクリック（最低3点）
詳細を入力して「追加」をクリック

アノテーションの編集・削除

左パネルのリストからアノテーションを選択
「編集」で内容を変更
「削除」で削除

3. XMLエクスポート

エクスポート手順

ツールバーの「XMLエクスポート」をクリック
新しいタブにXMLが表示されます
コピーまたは保存してください

出力されるXML構造

エクスポートされるXMLは、IIIF 3D マニフェストと連携する構造になっています：

<?xml version="1.0" encoding="UTF-8"?>
<!-- エクスポート時の出力例 -->
<facsimile xmlns="http://www.tei-c.org/ns/1.0">
  <surface xml:id="surface-3d" type="threejs"
           corresp="your-model.glb">

    <!-- ポイント型 -->
    <zone xml:id="zone-point-1" type="point"
          ana="points3d:0.5,1.2,0.3" radius="0.05">
      <note>説明テキスト</note>
    </zone>

    <!-- ボックス型 -->
    <zone xml:id="zone-box-1" type="box"
          ana="points3d:0.1,0.2,0.3 0.8,0.9,0.6">
      <note>領域の説明</note>
    </zone>

    <!-- ポリゴン型 -->
    <zone xml:id="zone-poly-1" type="polygon"
          ana="points3d:0.1,0.5,0.2 0.3,0.5,0.2 0.2,0.8,0.2">
      <note>多角形領域の説明</note>
    </zone>

  </surface>
</facsimile>

IIIF 3Dマニフェストとの連携

完全なTEI/XMLを作成する際は、IIIFマニフェストへの参照を追加します：

<facsimile sameAs="https://example.com/iiif/3/0001/manifest.json">
  <surface xml:id="surface-3d" type="threejs"
           sameAs="https://example.com/iiif/3/0001/manifest.json/scene/1">
    <graphic url="https://example.com/models/your-model.glb"
             mimeType="model/gltf-binary"/>

    <zone xml:id="zone-point-1" type="point"
          ana="points3d:0.5,1.2,0.3" radius="0.05">
      <note>説明テキスト</note>
    </zone>
    <!-- 他のzone要素 -->
  </surface>
</facsimile>

属性の説明

facsimile要素

属性	説明
`sameAs`	IIIF 3Dマニフェストへのリンク

surface要素

属性	説明
`xml:id`	サーフェスの識別子
`type`	`threejs`（3Dビューア用）
`sameAs`	IIIF 3Dマニフェスト内のシーンへのリンク

graphic要素

属性	説明
`url`	GLBファイルのURL
`mimeType`	`model/gltf-binary`

zone要素

属性	説明
`xml:id`	一意の識別子
`type`	アノテーションの種類（point/box/polygon）
`ana`	3D座標（`points3d:x,y,z` 形式、スペース区切りで複数）
`radius`	ポイント型の場合の半径

注意: TEI標準では points 属性は2D座標を想定しています。TEI All スキーマのバリデーションを通すため、3D座標は ana 属性に points3d: プレフィックス付きで格納しています。

4. 完全なTEI/XMLの作成

エクスポートされるのは <facsimile> 部分のみです。完全なTEI/XMLを作成するには、テキスト本文と組み合わせ、IIIFマニフェストへの参照を追加します：

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/data/xsl/your-style.xsl"?>
<?xml-model href="http://www.tei-c.org/release/xml/tei/custom/schema/relaxng/tei_all.rng"
            type="application/xml" schematypens="http://relaxng.org/ns/structure/1.0"?>
<TEI xmlns="http://www.tei-c.org/ns/1.0">
  <teiHeader>
    <fileDesc>
      <titleStmt>
        <title>作品タイトル</title>
      </titleStmt>
      <publicationStmt>
        <p>公開情報</p>
      </publicationStmt>
      <sourceDesc>
        <p>原資料の情報</p>
      </sourceDesc>
    </fileDesc>
  </teiHeader>

  <text>
    <body>
      <!-- corresp属性でアノテーションと紐付け -->
      <p corresp="#zone-point-1">
        この文章はポイント1に関連しています。
      </p>
      <p corresp="#zone-poly-1">
        この文章は多角形領域に関連しています。
      </p>
    </body>
  </text>

  <!-- IIIF 3Dマニフェストへのリンク付きfacsimile -->
  <facsimile sameAs="https://example.com/iiif/3/0001/manifest.json">
    <surface xml:id="surface-3d" type="threejs"
             sameAs="https://example.com/iiif/3/0001/manifest.json/scene/1">
      <graphic url="https://example.com/models/your-model.glb"
               mimeType="model/gltf-binary"/>

      <zone xml:id="zone-point-1" type="point"
            ana="points3d:0.5,1.2,0.3" radius="0.05">
        <note>説明テキスト</note>
      </zone>
      <!-- 他のzone要素 -->
    </surface>
  </facsimile>
</TEI>

IIIF 3Dマニフェストについて

IIIF 3D拡張を使用すると、3Dモデルのメタデータを標準化された形式で記述できます。TEI/XMLの facsimile 要素からマニフェストへリンクすることで：

3Dモデルのメタデータ（タイトル、著作権など）を外部で管理
複数のビューア間での相互運用性を確保
他のIIIFリソース（画像、動画など）との統合

マニフェストURL構造の例:

https://example.com/iiif/3/0001/manifest.json          # マニフェスト
https://example.com/iiif/3/0001/manifest.json/scene/1  # シーン（surface@sameAs用）

テキストとの関連付け

corresp 属性を使って、テキスト要素とアノテーションを関連付けます：

テキスト側: <p corresp="#zone-point-1">
アノテーション側: <zone xml:id="zone-point-1">

5. XSLスタイルシートの作成（オプション）

テキストの表示スタイルをカスタマイズするには、XSLTスタイルシートを作成します。

TEI 3D Viewerとの連携

TEI 3D Viewerでテキストと3Dモデルを連動させるには、XSLで corresp 属性を data-corresp 属性に変換する必要があります。これにより、テキストをクリックすると対応する3D位置にフォーカスできます。

基本的なXSLテンプレート

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:tei="http://www.tei-c.org/ns/1.0"
    xmlns:xml="http://www.w3.org/XML/1998/namespace"
    exclude-result-prefixes="tei">

  <xsl:output method="html" encoding="UTF-8"/>

  <xsl:template match="/">
    <html>
      <head>
        <style>
          body {
            font-family: serif;
            line-height: 1.8;
            padding: 2rem;
          }
          /* 縦書きにする場合 */
          .vertical {
            writing-mode: vertical-rl;
          }
        </style>
      </head>
      <body>
        <xsl:apply-templates select="//tei:text/tei:body"/>
      </body>
    </html>
  </xsl:template>

  <!-- 段落テンプレート -->
  <xsl:template match="tei:p">
    <p>
      <xsl:apply-templates select="@*"/>
      <xsl:apply-templates/>
    </p>
  </xsl:template>

</xsl:stylesheet>

属性の一括処理（推奨）

要素ごとに corresp 属性の処理を書くのではなく、属性テンプレートを使って一括処理できます：

<!-- ================================================== -->
<!-- 属性テンプレート（一括処理） -->
<!-- ================================================== -->

<!-- xml:id → id -->
<xsl:template match="@xml:id">
    <xsl:attribute name="id">
        <xsl:value-of select="."/>
    </xsl:attribute>
</xsl:template>

<!-- corresp → data-corresp -->
<xsl:template match="@corresp">
    <xsl:attribute name="data-corresp">
        <xsl:value-of select="."/>
    </xsl:attribute>
</xsl:template>

<!-- その他の属性は無視 -->
<xsl:template match="@*"/>

各要素テンプレートでは、以下の1行で全属性を処理できます：

<xsl:apply-templates select="@*"/>

汎用TEI要素テンプレート

特定のテンプレートを書いていないTEI要素にも自動で属性を保持させるには、フォールバックテンプレートを追加します：

<!-- ================================================== -->
<!-- 汎用TEI要素テンプレート（フォールバック） -->
<!-- ================================================== -->

<!-- text配下の未定義TEI要素はspanに変換（facsimile等は除外） -->
<xsl:template match="tei:text//tei:*" priority="-1">
    <span>
        <xsl:apply-templates select="@*"/>
        <xsl:apply-templates/>
    </span>
</xsl:template>

<!-- facsimile等のメタデータ要素は無視 -->
<xsl:template match="tei:facsimile"/>
<xsl:template match="tei:teiHeader"/>

これにより：

新しいTEI要素が出てきても、自動で <span> に変換され、属性も保持される
新しい属性（例: @ref → data-ref）を追加したい場合、属性テンプレートを1つ追加するだけ

特別なスタイルが必要な要素

見た目をカスタマイズしたい要素には、個別のテンプレートを定義します：

<!-- タイトル用（特別なクラスを付与） -->
<xsl:template match="tei:head">
    <div class="title-column">
        <xsl:apply-templates select="@*"/>
        <xsl:apply-templates/>
    </div>
</xsl:template>

<!-- 人名（ハイライト表示） -->
<xsl:template match="tei:persName">
    <span class="person-name">
        <xsl:apply-templates select="@*"/>
        <xsl:apply-templates/>
    </span>
</xsl:template>

<!-- 日付 -->
<xsl:template match="tei:date">
    <span class="date">
        <xsl:apply-templates select="@*"/>
        <xsl:apply-templates/>
    </span>
</xsl:template>

要素	個別テンプレートが必要な理由
`head`	タイトル用の大きなフォント
`dateline`	署名・日付用のスタイル
`persName`	人名のハイライト
その他	汎用テンプレートで自動処理

XSLファイルの配置

public/data/xsl/
├── your-style.xsl

6. ビューアでの表示

作成したTEI/XMLはTEI 3Dビューアで表示できます。

使い方

URLパラメータでXMLファイルを指定：

/tei-3d-viewer?url=/data/xml/your-file.xml

ビューアの機能

3Dモデルとテキストの同時表示
テキストクリックで対応する3D位置にフォーカス
アノテーション領域のハイライト表示

サンプルファイル

以下のサンプルを参考にしてください：

犬田布岬の歌 - ポリゴンアノテーションの例
繁多忠利先生銅像碑文 - 記念碑テキストの例

トラブルシューティング

モデルが読み込めない

GLB形式であることを確認
ファイルサイズが大きすぎないか確認
CORSエラーの場合は同一ドメインに配置

アノテーションが表示されない

ana 属性の座標形式を確認（points3d:x,y,z スペース区切り）
xml:id が重複していないか確認
corresp 属性のファイル名が正しいか確認

テキストとの紐付けが動作しない

corresp 属性の値が # で始まっているか確認
xml:id と corresp の値が一致しているか確認