はじめに

#![allow(unused)]
fn main() {
// 他のgeo_*クレートは geo_foundation 経由
use geo_foundation::{Point3D, Vector3D};

// geo_ioのみ直接アクセス（例外パターン）
use geo_primitives::{Point3D, TriangleMesh3D, Vector3D};
}

この例外は以下の理由で採用：

パフォーマンス: ファイル形式との直接変換でゼロコピー最適化
責務明確化: I/O 境界層としての特化
実装複雑性回避: 抽象化オーバーヘッドの排除

`cam_solver`

CAM 演算・パス作成 / 編集・ポスト処理・切削シミュレーション

CAM パス生成 / 編集（今後実装予定）
各 CNC コントローラー対応ポスト処理（今後実装予定）
切削シミュレーション（今後実装予定）

`data_exchange`

データインポート/エクスポート（将来実装予定）

STL インポート/エクスポート
OBJ インポート/エクスポート
STEP インポート/エクスポート
IGES インポート/エクスポート
DXF インポート/エクスポート
DWG インポート/エクスポート

注記: 現在はgeo_ioで STL 形式のみ実装済み

レンダリング層

`render`

GPU 描画基盤

wgpu + WGSL による GPU レンダリング
シェーダ管理
頂点データ処理

`stage`

レンダリングステージ管理

RenderStage トレイト
レンダリングパイプライン管理
シーン構成

`viewmodel`

ビュー操作・変換ロジック・MVVM アーキテクチャ

カメラ制御（将来実装予定）
ビュー変換
ユーザーインタラクション（将来実装予定）
MVVM 準拠: Model 層（geo_*）と View 層（render）の架け橋
STL 読み込み・GPU 変換機能（stl_loader）
メッシュデータ変換（mesh_converter）

`redring`

メインアプリケーション

アプリケーションエントリポイント
全クレート統合
ウィンドウ管理

構造設計の方針

型安全性：コンパイル時エラー検出を最大化
責務分離：各クレートが単一の責務を持つ
モジュール性：render は model に依存しない設計
拡張性：将来的な NURBS や WebAssembly 対応を考慮
国際化：英語ベースの命名で国際的な貢献を促進
MVVM アーキテクチャ：View → ViewModel → Model の層分離
例外設計許容：パフォーマンス要件に応じた適切な例外設計（I/O 層など）

アーキテクチャ依存関係

redring (View) → viewmodel → model (geo_*)
            ↘  stage → render

独立: analysis (汎用数値計算)
例外: geo_io (直接geo_primitives依存でゼロコピー最適化)

型分類 / Type Classification System

RedRing では、幾何学要素の分類を明示的な型システムで定義することで、型安全性と構造的明快さを両立しています。

PrimitiveKind

基本幾何プリミティブの分類：

Point：点
Vector：ベクトル
Direction：正規化されたベクトル
Line：直線（線分）
Ray：光線（半無限直線）
InfiniteLine :無限直線

CurveType

曲線要素の分類：

Line：直線
Circle：円
Ellipse：楕円
Arc：円弧
EllipseArc:楕円弧
NurbsCurve：NURBS 曲線

PrimitiveSurfaceType

Plane：無限平面
Triangle：三角形
Rectangle:四辺形

SurfaceType

NurbsSurface：NURBS 曲面
RotateSolid：回転体
CylindricalSurface：円柱面
NurbsSurface：NURBS 曲面
polygonMesh：多角形メッシュ
TriangleMesh：三角形メッシュ（表示用 or 三角形メッシュ操作用）

SolidType

Sphere：球
CylindricalSolid：円柱体
Cone：円錐
Ellipsoid：楕円体
Torus：トーラス
RotateSolid：回転体

基本幾何プリミティブ面要素の分類

エラー型システム

各幾何要素は専用のエラー型を持ちます：

EllipseError：楕円固有のエラー
CircleError：円固有のエラー
NormalizationError：正規化エラー
EllipseArcError：楕円弧エラー

トレイト統合システム

重複する操作は統合トレイトで抽象化：

`Normalizable<T>`

#![allow(unused)]
fn main() {
pub trait Normalizable<T> {
    type Output;
    type Error;
    fn normalize(&self) -> Result<Self::Output, Self::Error>;
}
}

`DistanceCalculation<T, Target>`

#![allow(unused)]
fn main() {
pub trait DistanceCalculation<T, Target> {
    fn distance_to(&self, other: &Target) -> T;
}
}

設計意図

型安全性：コンパイル時の型チェックによるエラー防止
専用性：各幾何要素に特化したエラー情報の提供
拡張性：新しい幾何要素の追加に対応可能な構造
明示性：API の意図と制約を型で表現

設計思想 / Design Philosophy

RedRing の設計は、以下の原則に基づいて構築されています。

1. 責務分離と語義整合

モジュール・型・関数の命名は、語義的に明確であることを最優先
表現と実装の責務を分離し、保守性と拡張性を両立

2. 型安全性と抽象化

Rust の型システムを活用し、誤用を防ぐ API 設計
トレイトによる抽象化で、汎用性と柔軟性を確保

3. 国際化と可読性

英語圏の開発者にも直感的に理解できる命名と構成
ドキュメントは日本語と英語の併記を基本とし、国際貢献を促進

4. 将来拡張への備え

STEP 対応、NURBS 実装、mdBook 多言語化などを視野に入れた構造設計

5. エラー処理ガイドライン

RedRing では型安全性と保守性を重視したエラー処理パターンを採用しています。

専用エラー型の使用

各幾何要素は独自のエラー型を定義し、具体的なエラー情報を提供します：

#![allow(unused)]
fn main() {
// ✅ 推奨: 専用エラー型
impl Ellipse<T> {
    pub fn from_radii(rx: T, ry: T) -> Result<Self, EllipseError> {
        // 楕円固有の検証とエラー報告
    }
}

// ❌ 非推奨: 汎用エラー型
impl Ellipse<T> {
    pub fn from_radii(rx: T, ry: T) -> Result<Self, GeometryError> {
        // エラーの詳細が不明確
    }
}
}

統合トレイトの活用

重複する操作は統合トレイトで抽象化し、型安全性を保ちます：

#![allow(unused)]
fn main() {
// 正規化操作の統合
pub trait Normalizable<T> {
    type Output;
    type Error;
    fn normalize(&self) -> Result<Self::Output, Self::Error>;
}

// 距離計算の統合
pub trait DistanceCalculation<T, Target> {
    fn distance_to(&self, other: &Target) -> T;
}
}

実装原則

責務分離: 各モジュールは単一の責務を持つ
型安全性: コンパイル時エラー検出を最大化
トレイト設計: 共通操作は統合トレイトで抽象化
エラー情報: 具体的で actionable なエラーメッセージ

6. I/O レイヤーの例外的設計パターン

RedRing では、パフォーマンスと責務分離のバランスを取るため、I/O 層に例外的な設計パターンを採用しています。

geo_foundation トレイト設計からの例外

geo_io クレートは、他の geo_* クレートとは異なり、geo_foundation トレイトを経由せず、直接 geo_primitives にアクセスします：

#![allow(unused)]
fn main() {
// geo_io での直接アクセス（例外パターン）
use geo_primitives::{Point3D, TriangleMesh3D, Vector3D};

pub fn load_stl<T: Scalar>(path: &Path) -> Result<TriangleMesh3D<T>, IoError> {
    // ファイル形式との直接的な変換処理
}
}

設計根拠

ゼロコピー最適化: ファイル形式との効率的なデータ変換
境界層の責務: 外部データ形式 ↔ 内部データ構造の変換に特化
パフォーマンス重視: 大量データの高速処理要件
実装複雑性の回避: 抽象化によるオーバーヘッドを排除

MVVM 準拠のアクセスパターン

View 層（redring）は直接 geo_io にアクセスせず、ViewModel 層（viewmodel）を経由：

#![allow(unused)]
fn main() {
// ❌ View層での直接I/Oアクセス（禁止）
// use geo_io::stl;

// ✅ ViewModel経由のアクセス（推奨）
use viewmodel::stl_loader::{load_stl_mesh, StlMeshData};
}

Analysis クレートの汎用性

analysis クレートは数値計算ライブラリとして独立し、特定のドメインに依存しない汎用的な実装を提供：

#![allow(unused)]
fn main() {
// 汎用数値型とトレイト
pub trait Scalar: Copy + Clone + PartialEq + PartialOrd + ... {}
pub trait TolerantEq<T: Scalar> { ... }
}

この設計により、各層の責務が明確になり、パフォーマンスと保守性のバランスが実現されます。

Core/Extension Foundation パターン

RedRing の中核設計原則である Core/Extension Foundation パターンについて説明します。

レンダリング・衝突判定・空間インデックスに必要な基本機能
軽量・高速・必須実装
構築、アクセサ、基本計量、基本包含、基本パラメータ、境界ボックス

Extension Foundation（拡張・高機能）

高度な操作・分析・変換機能
オプション実装・機能豊富
高度な構築、変形、空間関係、次元変換、コレクション操作

ファイル構造

circle_2d.rs              // Core実装（120行）
circle_2d_extensions.rs   // Extension実装（130行）

利用例

Core のみ使用

#![allow(unused)]
fn main() {
use geo_foundation::Point2D;
use geo_foundation::Circle2D;
let circle = Circle2D::new(center, radius)?;
let area = circle.area();
}

Extension を含む使用

#![allow(unused)]
fn main() {
let unit_circle = Circle2D::unit_circle();  // Extension
let scaled = circle.scale(2.0)?;            // Extension
}

メリット

段階的実装: 最小限から段階的に機能追加
用途別最適化: レンダリング用（軽量）vs 解析用（高機能）
保守性向上: 責務分離により理解・修正が容易
拡張性: 新しい Extension を後から追加可能

詳細は CORE_EXTENSION_FOUNDATION_PATTERN.md を参照してください。

Keyboard shortcuts

RedRing