バイナリ地名・地物データの読み込み対応＆A*アルゴリズムと集落移動描画の改良＆フロー曲線と領域線の色入力対応

[AsPJT]

このプルリクエスト（#153）は、 シミュレーションのパフォーマンス向上（バイナリ対応） と 可視化の品質向上（移動線・色指定・バグ修正） の2つが大きな柱となっています。

具体的な改修内容を3つのポイントに整理して解説します。

---

1. A*アルゴリズムの改良と「棒・ループ」バグの修正

集落の移動経路を計算するAStarクラス（経路探索）と、その描画ロジックに重要な修正が入っています。

• 「棒（Stick）」と「ループ」の防止策（setPath関数）

  • 問題: 以前は、探索失敗時やグリッド変換の誤差により、始点・終点付近で経路が予期せぬ場所（原点0,0など）へ飛んでしまう「棒（Stick）」のような描画アーティファクトや、始点付近でくるりと回ってしまう「ループ」が発生していたようです。
  • 修正:
    • 親ノードが(0,0)の場合の不正アクセスチェックを追加し、異常な経路を遮断。
    • 始点・終点と、A*のグリッド中心点が近すぎる場合（skip_dist_sq以内）、そのグリッド点を間引く処理を追加。これにより、スプライン曲線で結んだ際に端点が不自然に歪むのを防いでいます。
    • 経路が見つからない、またはフィルタリングで点が足りなくなった場合は、単純な直線（Start -> End）にフォールバックする安全装置が強化されました。

• 集落移動の描画リッチ化（drawMovementLines関数）

  • スプライン曲線: 移動履歴を滑らかな曲線（paxg::Spline2D）で描画するように変更されました。
  • 矢印の追加: パスの最後の区間に矢印（drawArrow）が追加され、集落が「どちらの方向に移動したか」が視覚的に明確になりました。

2. バイナリ形式の地名・地物データ読み込み対応

これまでTSV（テキスト）形式のみだったデータ読み込みにおいて、より高速なバイナリ形式のサポートが拡充されました。

• 型付きカラムのサポート:
  • 単なる文字列ではなく、latitude（緯度）、first_year/last_year（年代）、min_size/max_size（表示ズームレベル）といった数値を、バイナリデータとして適切に読み書きする機能（BinaryColumnType）が実装されました。
  • getInt32 や getFloat といった型指定の取得メソッドが追加され、キャストのコストを下げつつ精度を維持しています。
  • 注意点: バイナリ形式では forEachRow による行反復処理がサポートされないため、個別のセル取得メソッドを使用するよう設計が変更されています（警告ログ PAXS_WARNING が追加されています）。

3. フロー曲線と領域線の「色指定」対応

海流（FlowCurves）や文化圏（Territories）の描画色を、データファイル側から柔軟に指定できるようになりました。

• TSVデータの変更:
  • Kuroshio.tsv や Shimotabaru.tsv などのデータファイルに color カラムが追加されました。
  • これまでの black 一辺倒から、#3C6491（海流の青系）や #888888（領域のグレー系）など、具体的なHEXカラーコードが指定されています。
• カラーユーティリティの実装（ColorUtility.hpp）:
  • 16進数のカラーコード（例: #fe78ba）をパースして、エンジンの色オブジェクト（paxg::Color）に変換する機能が追加されました。これで、データ側で視覚表現をコントロールしやすくなります。

---

まとめ

このPRによって、 「集落の移動線が綺麗になり（矢印付き・バグ解消）」 、 「海流や文化圏を色分けして見やすく表示」 できるようになり、かつ 「大規模データの読み込み高速化（バイナリ対応）」 の準備が整ったことになります。

特に移動シミュレーションの可視化において、経路が荒ぶる現象が解消されているはずですので、確認時は集落移動の軌跡の滑らかさに注目すると良いでしょう。

---

新しいバージョンでは、シミュレーションの精度向上と処理速度の改善を目的とした、大きく分けて3つの新機能が追加されています。

1. 遺伝・文化要素の拡張（Y-DNA、土器、稲作）

これまでのバージョンでは「mtDNA（母系）」と「言語」が主な追跡対象でしたが、新バージョンではより詳細な遺伝・文化シミュレーションが可能になっています。

• Y-DNA（父系遺伝）の導入:

• 新たに Y-DNA.tsv や Y-DNA_List.tsv を読み込む機能が追加されました 。

• 男性移民の性比バイアスを表現する applyImmigrantGenderBias 関数が追加され、渡来人の性別構成（男性が多いなど）を確率的に操作できるようになりました 。

• 結果出力にも Y-DNA の統計が含まれるようになっています 。

• 土器文化（Pottery）のシミュレーション:

• 各地区に pottery_lineage_initial（初期土器系統）が設定できるようになりました 。

• エージェント生成時に、在地系か渡来系かに応じて土器系統を選択するロジック（selectPotteryLineage）が追加されています 。

• 土器作りを行う性別（女性のみ、男性のみ、両方）を判定する isPotteryGenderAllowed が追加されました 。

• 一定期間ごとに土器文化が伝播する propagatePottery 機能も実装されています 。

• 稲作形態の区別:

• 農耕の種類として、陸稲（Ine）と水田（Paddy）を区別する selectRiceType が追加されました 。

• シミュレーションのステップ数に応じて、水田稲作への移行が表現されています 。

2. 並列処理による高速化（OpenMP対応）

シミュレーションの大規模化に対応するため、計算処理の並列化と最適化が施されています。

• OpenMPによるマルチスレッド化:

randomizeSettlements（集落のランダム配置）などの重い処理が、OpenMPを使って並列化されました（#ifdef _OPENMP）。

• スレッドごとに異なる乱数生成器を使用する thread_local_gens_ と getThreadLocalGen が導入され、並列処理時の乱数の安全性（スレッドセーフ）が確保されています 。

• キャッシュと検索の最適化:

• 人口計算を毎回行わず、キャッシュ（cached_population_num）を利用して高速化する仕組みが導入されました 。

• 地区IDから集落グリッドを高速に引けるように district_to_grids_ というマップが追加され、集落検索の計算量（O(n)）が削減されています 。

3. 地理・移動コストの精緻化（海流コスト）

マップ上の移動ロジックにおいて、より現実的な地形・海流の影響が考慮されるようになりました。

• 海流コスト（Current Costs）:

• 地区データ（District）に current_costs という配列が追加されました 。

• 8方向（東、南東、南...）それぞれの移動コストを保持できるようになり、海流に乗る移動と逆らう移動の難易度差などをシミュレーションに反映できる構造になっています 。

---

まとめると：
以前読み込めなかったファイルは、**「父系遺伝（Y-DNA）や土器文化などの詳細な人類学データ」を扱えるようになり、かつ「並列計算による高速化」**が実装された、より高度なシミュレーションエンジンに進化しています。

[Copilot]

Pull request overview

This PR implements three major improvements to the simulation system: (1) Binary data format support for faster loading of place names and locale data, (2) A pathfinding bug fixes* to eliminate "stick" and "loop" visual artifacts in settlement movement rendering, and (3) Hex color string support for flow curves and territories to enable data-driven color customization.

Key Changes

• Fixed A* pathfinding artifacts by adding parent node validation, endpoint proximity filtering, and fallback to direct lines when paths are invalid
• Optimized agent lookup performance with O(1) hash map indexing and marriage candidate caching
• Added binary table reader/writer infrastructure with typed columns for coordinates, dates, and sizes
• Implemented hex color parsing (#RRGGBB format) for visual customization of map features

Reviewed changes

Copilot reviewed 31 out of 60 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
Library/PAX_SAPIENTICA/Simulation/Algorithm/AStar.hpp	Complete A* rewrite with priority queue, parent validation, endpoint filtering, and stick/loop prevention
Library/PAX_SAPIENTICA/Simulation/Entity/Settlement.hpp	Agent indexing optimization, marriage cache, and A* integration improvements
Library/PAX_SAPIENTICA/IO/Data/BinaryTable.hpp	New binary format reader with typed columns and optimized memory layout
Library/PAX_SAPIENTICA/IO/Data/UnifiedTable.hpp	TSV/binary format abstraction layer with automatic format detection
Library/PAX_GRAPHICA/ColorUtility.hpp	Hex color string parser (#RRGGBB/#RRGGBBAA support)
Library/PAX_MAHOROBA/Map/Content/Feature/TerritoryFeature.hpp	Color parsing integration for territory rendering
Library/PAX_MAHOROBA/Map/Content/Feature/FlowCurveFeature.hpp	Color parsing integration for flow curve rendering
Data/Settings/*.tsv	Updated to use hex color strings instead of "black"

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.