一般

概要

このプロジェクトは、純粋なJavaScriptで3DCG描画やモデルデータの管理、各種ファイルフォーマット対応（OBJ, MQO, JSON等）を可能にするシンプルな3DCGライブラリです。主な構成要素は、ジオメトリ（メッシュ・頂点・面）、マテリアル、ライト、カメラ、シーン管理、システムユーティリティ、各種データローダー/エクスポーターなどです。

アーキテクチャ全体図（概要）

[S3System] ──┬─> [S3Scene] ─┬─> [S3Model] ──> [S3Mesh]
             │               │                ├─> [S3Vertex]
             │               │                ├─> [S3TriangleIndex]
             │               │                └─> [S3Material]
             │               ├─> [S3Light]
             │               └─> [S3Camera]
             ├─> [S3MeshLoader] <─ [OBJ/MQO/JSON File]
             └─> [Utility: Math, Vector, Matrix, Angles]

コアモジュールの責務

S3System

システムの中核クラス。
- 各種ファクトリ（シーン/モデル/メッシュ/頂点/マテリアル/ライト/カメラ等の生成）。
- 座標変換（平行移動、回転、スケール、射影、ビューポート等）、MVP計算、カリングなど。
- 2D Canvas描画のサポート（ラインレンダ、軸描画など）。
- 描画モードや座標系（OpenGL/DirectX系）切り替え等のシステム設定。

S3Scene

シーン（描画単位）の管理クラス。
- 複数モデル・ライト・カメラの登録、シーン全体の保持。
- シーンの空化やモデル/ライト追加、カメラ切替が可能。

S3Model

ワールド座標変換を含む3Dオブジェクト単位。
- 位置・回転（オイラー角）・スケール・メッシュ情報を保持。

S3Mesh

ジオメトリ（立体形状）のまとまり。
- 頂点（S3Vertex）、面（S3TriangleIndex）、マテリアル（S3Material）をまとめる。
- 面の反転や複数素材対応、確定化フラグなど。

S3Vertex / S3TriangleIndex

頂点座標、面情報の基本クラス。
- 頂点（S3Vertex）：位置（S3Vector）だけを持つシンプルなimmutableオブジェクト。
- 三角形面（S3TriangleIndex）：3頂点インデックス、UV座標、マテリアルインデックスを保持。

S3Material

マテリアル（材質・テクスチャ等）のプロパティを管理。
- 拡散色、環境光、鏡面、発光、反射率、テクスチャ画像等。

S3Texture

画像やテクスチャデータの管理。
- 各種Image型やURLの対応、2の累乗への自動変換等。

S3Light

シーン内の光源情報管理。
- 種類（環境光/平行光源/点光源）、強度、方向、色などを保持。

S3Camera

視点情報・射影/ビュー/ビューポート行列管理。
- 視点、注視点、視野角、ニア・ファークリップ、各種行列取得APIあり。

数学系ユーティリティ

S3Vector / S3Matrix / S3Angles など
- ベクトル・行列計算、オイラー角変換、線形補間など汎用的な3DCG数値処理を提供。

メッシュローダー（データ入出力）

S3MeshLoader（Facadeパターン的役割）

各種3Dフォーマット（OBJ/MQO/JSON）を一元的にS3Meshインスタンスへ変換（インポート）、逆に各形式へのエクスポート（出力）を提供。

S3MeshLoaderOBJ

Wavefront OBJ形式の読み書き。テキスト→メッシュへの変換、各要素の解析。

S3MeshLoaderMQO

Metasequoia MQO形式の読み書き。テキスト→メッシュ、素材パラメータやUVも一部対応。

S3MeshLoaderJSON

シンプルなJSONメッシュデータ対応。自前データ構造用。

拡張性について

追加フォーマット： S3MeshLoaderに新しいローダーを追加すれば良い設計。
レンダラ置換： デフォルトは2D Canvas描画だが、S3GLSystemなどでWebGL拡張も容易。
独自モデル・マテリアル： S3Model/S3Material/S3Meshを継承し独自拡張可能。
シーン構成/ユーティリティ： 数学系やカメラ制御等もモジュール分離で独自実装しやすい。

モジュール依存関係と流れ

S3Systemがすべてのファクトリ・管理・計算の中核となり、インスタンス生成も担当。
S3Sceneが、各モデル・ライト・カメラを保持し、S3Systemからの描画要求で内容を渡す。
S3MeshLoaderを通じて、外部3Dデータを読み込み、S3Meshへ展開。
各モデルは自身のS3Meshを持ち、ワールド変換行列はS3Systemで算出。
描画時は、S3Systemがモデル・カメラ・シーン情報からMVP行列等を組み立て、Canvasにライン/シェーディング等を描く。

シンプルな利用例

import S3 from "./S3.js";
const sys = new S3.System();
const scene = sys.createScene();
const camera = sys.createCamera();
scene.setCamera(camera);

const mesh = sys.createMesh();
// ... meshに頂点・面・マテリアル追加 ...

const model = sys.createModel();
model.setMesh(mesh);
scene.addModel(model);

sys.setCanvas(document.getElementById("canvas"));
sys.drawScene(scene);

まとめ

責務分離・シンプル設計。
数値系/ジオメトリ/シーン管理/各種ローダーは独立性高く拡張容易。
WebGL化や独自レンダラ、拡張フォーマット対応も視野に入れた柔軟アーキテクチャ。

WebGL 拡張

概要

WebGL 実装系 (S3GL* クラス群) について説明します。

純粋な JS のクラス構成（ES Modules 構成）
抽象レイヤー（基本形状・メッシュ・カメラ・ライト・マテリアル etc...）
WebGL レイヤー（GL バッファ／シェーダ／テクスチャ／描画パイプライン管理）

アーキテクチャ全体図

+-----------------------------------------------------------+
|                        S3GLSystem                        |
| (WebGL全体の管理／描画パイプライン・GLContext管理)        |
+---------------------+---------+--------------------------+
                      |         |
           +----------+         +--------------+
           |                                    |
    +------v-------+                      +-----v------+
    |  S3GLScene   |                      |  S3GLMesh  |
    |(Scene全体管理|                      |(メッシュ/VBO|
    +------+-------+                      +-----+------+
           |                                    |
    +------v-----------+                +-------v---------+
    |  S3GLModel       |                | S3GLTriangle... |
    |(モデル/形状/変換) |                |(三角形インデックス)|
    +------------------+                +-----------------+
           |                                    |
    +------v----------+                +--------v-------+
    |  S3GLMaterial   |                |  S3GLVertex    |
    |  (材質・uniform) |                |  (頂点情報)    |
    +-----------------+                +----------------+

レイヤ・主な責務

1. 抽象・システムレイヤ（`S3System`など）

シーン管理（S3Scene）・モデル/カメラ/ライト生成
行列演算・座標変換（モデル/ビュー/プロジェクション）
頂点・メッシュ・マテリアルのファクトリ機能

2. WebGLレイヤ（`S3GL*` クラス群）

GLContext の初期化・管理（S3GLSystem）
GLバッファ生成／VBO/IBO 化（S3GLMesh）
GLシェーダ・プログラム管理（S3GLShader, S3GLProgram）
シーン/モデル/マテリアル/ライトの uniform 変換（getUniforms 系）
GLリソース（テクスチャ/バッファ）管理・破棄

ファイル構成

S3GLSystem.js: WebGL描画システム本体
S3GLMesh.js: GL用メッシュ（VBO/IBO管理、属性生成）
S3GLModel.js: GL用モデル（uniforms生成）
S3GLMaterial.js: GL用マテリアル（uniforms生成・テクスチャ管理）
S3GLScene.js: GL用シーン管理
S3GLProgram.js: シェーダ・GLプログラム管理
S3GLVertex.js, S3GLTriangleIndex.js, S3GLTriangleIndexData.js: 頂点・面・属性生成
S3GLArray.js: GL用データ変換・型管理
S3GLTexture.js: GL用テクスチャ
S3GLLight.js: GL用ライト

主要クラスの役割

S3GLSystem

WebGL 描画全体の管理者
- GLContext の初期化／プログラム切り替え
- 描画モード・カリング・深度・背景色管理
- プログラムへのバインド・描画ループ処理
- 各種ファクトリ（メッシュ/モデル/カメラ etc...）

S3GLScene

シーン単位のデータ統括
- モデル・カメラ・ライトの管理
- 全 uniform 生成（getUniforms：カメラ方向やライト配列を uniform 形式で返す）

S3GLModel

オブジェクト（形状）の位置・スケール・回転・メッシュ参照
- 複数のマテリアルを集約し、uniform を生成
- ワールド座標変換行列もここで算出

S3GLMesh

WebGLに適したメッシュ（頂点配列・インデックス配列）
- VBO/IBO 生成・バッファ管理
- 各三角形ごとに法線/接線/従法線なども計算
- 頂点ハッシュにより、異なる属性毎に頂点をユニーク化

S3GLTriangleIndex / S3GLTriangleIndexData

三角形インデックス情報（各面ごとのUV, マテリアル等を含む）
- 面単位/頂点単位で法線・接線等も格納

S3GLVertex

各頂点の 3D 位置ベクトルを GL フォーマットで管理
- attribute へのバインド用データ（Float32Array化など）

S3GLMaterial

色/拡散/反射/発光/環境光/テクスチャ等の uniform 化
- テクスチャ有無を含むデータをまとめて返す
- GLSL シェーダ側の uniform 変数名と一致

S3GLTexture

画像から WebGL テクスチャ生成／管理

S3GLLight

平行光源/点光源/環境光などの uniform 生成

S3GLProgram

頂点・フラグメントシェーダの管理／GLSL uniform・attribute バインド管理
- GLSL 変数名ごとに型・ロケーション・バインド関数を自動管理
- VBO/IBO の bind, uniform の bind をすべて管理

データフロー／描画パイプライン例

S3GLSystem: setCanvas, setProgram, setBackgroundColor などシステム初期化
メッシュ・モデル生成: createMesh, createModel、ファイル/データからメッシュ生成（例: MQOローダ）
マテリアル・テクスチャ・ライトのセット
シーン生成／モデル・ライト登録
drawScene(scene) でシーン全体描画
- (a) Uniforms: シーン/カメラ/ライト/マテリアルの uniform をプログラムにバインド
- (b) VBO/IBO バインド: メッシュごとに属性・インデックスバッファをGLへ
- (c) Draw Call: drawElements 実行で WebGL へ描画指示

const s3 = new S3GLSystem();
const program = s3.createProgram();
program.setVertexShader("...");
program.setFragmentShader("...");
s3.setProgram(program);

const mesh = s3.createMesh(); // 頂点・インデックス・マテリアル追加
const model = s3.createModel();
model.setMesh(mesh);

const scene = s3.createScene();
scene.setCamera(s3.createCamera());
scene.addModel(model);

s3.drawScene(scene); // ⇒ 描画パイプラインがすべて自動処理

モジュール依存関係

math/ : S3Vector, S3Matrix, S3Math など数学系
basic/ : S3Vertex, S3Material, S3TriangleIndex, S3Mesh, S3Model, S3Scene, S3Camera など
GL用: S3GLSystem, S3GLMesh, S3GLModel, S3GLScene, S3GLMaterial, S3GLTexture, S3GLTriangleIndex, S3GLVertex, S3GLLight, S3GLProgram, S3GLShader, S3GLArray, S3GLTriangleIndexData

設計の特徴・意図

抽象（basic）とWebGL層（GL）を明確に分離
- 抽象的な3D形状操作（座標/変換/論理）と、WebGL用最適化データ（バッファ/テクスチャ/シェーダ/GL管理）を分けて設計
可搬性／汎用性
- 例えば「CPU計算のみで画像を出す」用途や、「将来の他API対応」も見据えている
データの immutable 準拠（頂点/三角形/マテリアル）と、mutableな Scene/Model/Camera
GLSLシェーダ変数との自動バインド管理（S3GLProgramで自動解析）

通常の3D描写のデモ

以下で実際を確認できます。

demo1

sample1.mjs

// --- ライブラリの読み込み ---
// UI操作用ライブラリ
import GuiBlocks from "./libs/GuiBlocks.min.js";
// 入力デバイス（マウスやタッチ）操作用ライブラリ
import InputDetect from "./libs/InputDetect.min.js";
// 3DCGエンジン本体（あなたが作ったS3ライブラリ）
import S3 from "./libs/S3.min.js";

/**
 * S3ライブラリ内の数値計算クラスのデモ関数
 * 行列の作成・計算・逆行列など、基本的な数値処理のサンプルを表示します。
 */
const testMath = function() {
    console.log("Math のサンプル");

    // 4x4行列の生成
    const m4 = new S3.Matrix(
        3, -2, -6, 4,
        -7, -6, 8, 21,
        -4, -7, 9, 11,
        2, -3, -5, 8
    );

    console.log("行列を作成");
    console.log(m4.toString());

    // 4x4行列の行列式を計算（det4）
    console.log("4x4行列の行列式");
    console.log(m4.det4().toString());

    // 4x4行列の逆行列を計算（inverse4）
    console.log("4x4行列の逆行列");
    console.log(m4.inverse4().toString());

    // 行列同士の掛け算
    console.log("行列の掛け算");
    console.log(m4.mulMatrix(m4).toString());

    // 3x3行列の生成
    const m3 = new S3.Matrix(
        1, 2, 1,
        2, 1, 0,
        1, 1, 2
    );

    // 3x3行列の行列式
    console.log("3x3行列の行列式");
    console.log(m3.det3().toString());

    // 3x3行列の逆行列
    console.log("3x3行列の逆行列");
    console.log(m3.inverse3().toString());
};

/**
 * メイン処理（ウィンドウ表示・3D描画）
 */
const main = function() {
    testMath(); // まず数値計算デモを実行

    console.log("S3 クラスのサンプル");

    // スクロールを抑止（マウスやタッチ操作が3D操作用イベントとして優先されるようにする）
    InputDetect.noScroll();

    // --- GUIパネル（描画用キャンバス）を作成 ---
    // 640x480ピクセルの描画パネル（HTML canvas）を作成
    const panel = new GuiBlocks.Canvas();
    // id="scomponent" の要素内にこのパネルを追加
    panel.putMe("scomponent", GuiBlocks.PUT_TYPE.IN);
    // サイズ単位をピクセルで設定
    panel.setUnit(GuiBlocks.UNIT_TYPE.PX);
    panel.setPixelSize(640, 480);  // 実際のピクセルサイズ
    panel.setSize(640, 480);       // 論理サイズ

    {
        // HTMLCanvasElementを取得
        const canvas = panel.getCanvas();

        // S3システム本体（描画エンジン管理クラス）を作成
        const sys = new S3.System();
        // カメラ操作用コントローラを作成
        const controller = new S3.CameraController();
        // カメラ（視点）を生成
        const camera = sys.createCamera();

        // S3システムにcanvasを登録（描画の出力先を指定）
        sys.setCanvas(canvas);
        // カメラ操作コントローラにもcanvasを登録（マウス操作取得）
        controller.setCanvas(canvas);

        // システムの座標系モードをOpenGL互換に設定（右手系、逆順カリングなど）
        sys.setSystemMode(S3.SYSTEM_MODE.OPEN_GL);
        // DirectX互換の場合はこちら
        // sys.setSystemMode(S3.SYSTEM_MODE.DIRECT_X);

        // --- 3Dモデルデータの作成と読み込みデモ ---
        console.log("json形式での読み書きのテスト");
        // サンプル用の簡単なポリゴン（四面体っぽい）データ
        const meshdata = {
            Indexes:{
                body:[
                    [ 0, 1, 2],
                    [ 3, 1, 0],
                    [ 3, 0, 2],
                    [ 3, 2, 1]
                ]
            },
            Vertices:[
                [  0,  0,  -5],
                [  0, 20,  -5],
                [ 10,  0,  -5],
                [  0,  0, -20]
            ]
        };

        let mesh;
        // JSONデータからS3Meshにインポート
        console.log(".json");
        mesh = S3.MeshLoader.inputData(sys, meshdata, "json");
        // S3MeshをJSON形式でエクスポート（逆変換）
        console.log(S3.MeshLoader.outputData(mesh, "json"));

        // MQO形式（Metasequoia 3Dモデラー用）のエクスポートテスト
        console.log("MQOでの出力テスト");
        console.log(".mqo");
        console.log(S3.MeshLoader.outputData(mesh, "mqo"));

        // MQOファイルのインポートテスト（ファイルは ./resource/teapot.mqo を想定）
        console.log("MQOでの入力テスト");
        mesh = S3.MeshLoader.inputData(sys, "./resource/teapot.mqo");

        // --- モデル（位置・回転・スケールを持つ3Dオブジェクト）を作成 ---
        const model = sys.createModel();
        model.setMesh(mesh);    // 形状データをセット
        model.setScale(5);      // 全体スケールを5倍に設定

        // --- カメラ（視点）の初期設定 ---
        camera.setEye(new S3.Vector( 20,  30,  50));   // 視点（カメラ位置）を設定
        camera.setCenter(new S3.Vector( 0,  0,  0));   // 注視点（カメラが向く中心）を設定
        controller.setCamera(camera);                  // カメラコントローラにカメラを登録

        // --- シーン（3D空間）を作成してモデルとカメラを配置 ---
        const scene = sys.createScene();
        scene.setCamera(camera);        // シーンにカメラをセット
        scene.addModel(model);          // モデルをシーンに追加

        /**
         * 画面を定期的に再描画する関数（アニメーションループ）
         * モデルを回転させたり、カメラコントローラで動的に視点操作できる
         */
        const redraw = function() {
            // コントローラの入力に合わせてカメラを更新
            scene.setCamera(controller.getCamera());
            sys.clear();           // 描画バッファをクリア
            model.addRotateY(3);   // モデルをY軸回転させる（毎フレーム3度）
            sys.drawAxis(scene);   // XYZ軸を描画（デバッグ・可視化用）
            sys.drawScene(scene);  // シーン全体を描画（全モデルを表示）
        };

        console.log(model);

        // 50ミリ秒ごとにredraw()を実行（1秒あたり約20回の描画更新＝アニメーション）
        setInterval(redraw, 50);
    }
};

// メイン関数実行（最初に呼ばれる）
main();

WebGLの3D描写のデモ