ship-hull-generator 2.1.3

Add your description here

ship-hull-generator

C-ShipGen をベースに改良した、船体形状の STL データ生成プログラムです。
拡散モデル（Diffusion Model）を用いて、ユーザーが指定した設計仕様を満たす船体形状を自動生成します。

---

概要

本プログラムは以下の流れで船体の STL ファイルを生成します。

1. ユーザーが船の主要目（全長・幅・喫水・深さ・排水体積・速度）を入力する
2. 条件付き誘導拡散モデル（Conditional Guided DDPM）が設計仕様を満たす船型パラメータを多数サンプリングする
3. 生成サンプルの実現可能性（幾何拘束）チェックを行い、不適切なものを除外する
4. 幾何寸法の誤差（MEAP）や抵抗値に基づいて最適な形状を選択する
5. 選択した形状を STL ファイルとして出力する

---

ベースとなった C-ShipGen について

C-ShipGen は、条件付き誘導拡散モデルを用いたパラメトリック船型設計システムです。
指定した主要目（長さ・幅・喫水・深さ・ブロック係数・設計速度）を満たしつつ、総抵抗サロゲートモデルの勾配を活用して低抵抗な船体形状を生成します。

---

本プログラムの主な改良点

オリジナルの C-ShipGen に対して以下の改良を加えています。

• 形状選択ロジックの強化
  生成サンプルの選択方法として以下の2段階フィルタを実装しました。
  • 幾何拘束フィルタ（geometric_constraint）：体積・幅・深さの誤差（MEAP）が指定閾値以内の形状のみを候補とする
  • 選択方法の切り替え（resist_min）：候補の中から抵抗値最小の形状を選ぶか、ID昇順で選ぶかを選択できる

使い方

セットアップ

本プロジェクトは uv でパッケージ管理を行っています。

1. ディレクトリに移動

   cd ship-hull-stl-generator
   

2. 仮想環境の作成

   uv venv
   

3. 仮想環境の有効化

   source .venv/bin/activate
   

4. 依存パッケージのインストール（uv.lock に基づく再現インストール）

   uv sync
   

基本的な使用例

from tools.stl_generator import StlGenerator

# 初期化（モデルのロードはここで1度だけ行われる）
generator = StlGenerator(
    data_dir="./data",
    model_dir="./TrainedModels",
    output_dir="./outputs",
    num_samples=512,        # 生成するサンプル数
    num_generate=1,         # 最終的に出力するSTL数
    resist_min=True,        # True: 抵抗値最小を選択 / False: ID昇順で選択
    geometric_constraint=True,  # True: 幾何拘束フィルタを適用
    meap_threshold=5.0,     # 幾何誤差の許容閾値 [%]
    random_seed=42
)

# 入力パラメータ: [LOA(m), BOA(m), T(m), Dd(m), Vol(m^3), U(m/s)]
input_data = [333, 42.624, 11.28, 29.064, 97561, 16]  # ニミッツ級空母

result = generator.generate(input_data, label="Nimitz")
print(result)

入力パラメータの説明

パラメータ	単位	説明
LOA	m	船の全長（Length Overall）
BOA	m	船の最大幅（Beam Overall）
T	m	喫水（水面下の深さ）
Dd	m	深さ（甲板までの高さ）
Vol	m³	排水体積
U	m/s	設計速度

設計例

# カヤック
input_data = [3.8, 0.787, 0.15, 0.438, 0.166, 1.5]

# ネオパナマックス型コンテナ船
input_data = [366, 50, 15.2, 40, 182114, 10.3]

# 沿岸警備艦 (NSC)
input_data = [127, 16, 6.9, 11, 4488, 14.4]

# ROPAX フェリー
input_data = [72, 20, 3.2, 4.8, 3917, 6.17]

---

生成オプション

オプション	デフォルト	説明
num_samples	512	拡散モデルが生成するサンプル数。多いほど良い形状が見つかりやすいが処理時間が増加する
num_generate	1	最終的に出力する STL ファイルの数
resist_min	False	True: 抵抗値が最小の形状を優先選択。False: IDの小さい順に選択
geometric_constraint	True	True: 体積・幅・深さの誤差が meap_threshold 以内の形状のみを候補にする
meap_threshold	5.0	幾何拘束フィルタの誤差許容閾値（%）
random_seed	42	乱数シード。同じ値を指定すると再現性が保たれる

---

出力結果

generate() は以下の辞書を返します。

{
    "label": "Nimitz",
    "hulls": [
        {
            "index": 42,                        # サンプルのインデックス
            "stl_local_path": "outputs/..stl",  # STLファイルのパス
            "LOA": 333.0,                       # 生成形状の全長 [m]
            "LOA_with_bulb": 335.2,             # バルブ付き全長 [m]
            "beam": 42.5,                       # 幅 [m]
            "depth": 29.1,                      # 深さ [m]
            "volume": 97200.0,                  # 排水体積 [m³]
            "total_resistance": 12500.0,        # 予測総抵抗値 [N]
            "LOA_MEAP": 0.5,                    # 全長の誤差 [%]
            "LOA_with_bulb_MEAP": 0.7,          # バルブ付き全長の誤差 [%]
            "beam_MEAP": 1.2,                   # 幅の誤差 [%]
            "depth_MEAP": 0.3,                  # 深さの誤差 [%]
            "volume_MEAP": 2.1                  # 排水体積の誤差 [%]
        }
    ],
    "overall_meaps": { ... },  # 有効サンプル全体のMEAP平均
    "average_meaps": { ... }   # 出力STLのMEAP平均
}

また outputs/ ディレクトリには以下のファイルが保存されます。

ファイル	内容
*_Hull_*.stl	生成された船体の STL ファイル
*_Conditioning_Only_DesVec.npy	条件付けのみで生成した設計ベクトル
*_Drag_Guidance_DesVec.npy	誘導付き生成の設計ベクトル（有効サンプルのみ）
*_Rt_pred.npy	予測抵抗値（有効サンプルのみ）

---

動作環境

• Python 3.13 以上

参考文献

• N. J. Bagazinski and F. Ahmed, "C-ShipGen: A Conditional Guided Diffusion Model for Parametric Ship Hull Design." arXiv:2407.03333, 2024.