# 悦木云插件代码库

本目录包含可复用的工具库，用于减少代码重复和提高可维护性。

## 已实现的库

### DialogUtils - 对话框工具库

提供对话框创建、居中显示等通用功能。

#### 主要方法

1. **`get_sketchup_window_size`** - 获取 SketchUp 窗口尺寸
   ```ruby
   width, height = YueMuPro::DialogUtils.get_sketchup_window_size
   ```

2. **`calculate_center_position(dialog_width, dialog_height)`** - 计算对话框居中位置
   ```ruby
   left, top = YueMuPro::DialogUtils.calculate_center_position(400, 300)
   ```

3. **`center_dialog(dialog, dialog_width, dialog_height)`** - 居中显示对话框
   ```ruby
   YueMuPro::DialogUtils.center_dialog(@dialog, 400, 300)
   ```

4. **`create_centered_dialog(options, html_content, force_center: true)`** - 创建并居中对话框
   ```ruby
   @dialog = YueMuPro::DialogUtils.create_centered_dialog(
     {
       :dialog_title => "我的对话框",
       :preferences_key => "my_dialog",
       :width => 400,
       :height => 300,
       :scrollable => true,
       :resizable => true
     },
     html_content
   )
   @dialog.show
   ```

5. **`show_centered(dialog, dialog_width, dialog_height)`** - 显示并居中对话框
   ```ruby
   YueMuPro::DialogUtils.show_centered(@dialog, 400, 300)
   ```

#### 使用示例

**旧代码（重复代码）：**
```ruby
屏幕宽度 = Sketchup.active_model.active_view.vpwidth
屏幕高度 = Sketchup.active_model.active_view.vpheight
对话框宽度 = 400
对话框高度 = 300
@dialog = UI::HtmlDialog.new({
  :dialog_title => "我的对话框",
  :width => 对话框宽度,
  :height => 对话框高度,
  :left => (屏幕宽度 - 对话框宽度) / 2,
  :top => (屏幕高度 - 对话框高度) / 2,
  # ...
})
@dialog.set_html(html)
@dialog.set_position((屏幕宽度 - 对话框宽度) / 2, (屏幕高度 - 对话框高度) / 2)
@dialog.show
```

**新代码（使用库）：**
```ruby
@dialog = YueMuPro::DialogUtils.create_centered_dialog(
  {
    :dialog_title => "我的对话框",
    :preferences_key => "my_dialog",
    :width => 400,
    :height => 300,
    :scrollable => true,
    :resizable => true
  },
  html
)
@dialog.show
```

### ConfigUtils - 配置文件工具库

提供配置文件加载、保存等通用功能。

#### 主要方法

1. **`load_yaml_config(config_path, default_config = {})`** - 加载YAML配置文件
   ```ruby
   config = YueMuPro::ConfigUtils.load_yaml_config(config_path, {default: 'value'})
   ```

2. **`save_yaml_config(config_path, config)`** - 保存YAML配置文件
   ```ruby
   YueMuPro::ConfigUtils.save_yaml_config(config_path, config_hash)
   ```

3. **`load_json_config(config_path, default_config = {})`** - 加载JSON配置文件
   ```ruby
   config = YueMuPro::ConfigUtils.load_json_config(config_path, {default: 'value'})
   ```

4. **`save_json_config(config_path, config, pretty: true)`** - 保存JSON配置文件
   ```ruby
   YueMuPro::ConfigUtils.save_json_config(config_path, config_hash)
   ```

5. **`user_config_dir(subdir = 'YueMu_Settings')`** - 获取用户配置目录
   ```ruby
   config_dir = YueMuPro::ConfigUtils.user_config_dir
   ```

6. **`user_config_path(filename, subdir = 'YueMu_Settings')`** - 获取用户配置文件路径
   ```ruby
   config_path = YueMuPro::ConfigUtils.user_config_path('config.yml')
   ```

### OperationUtils - 模型操作工具库

提供模型操作的包装，简化 start_operation/commit_operation/abort_operation 的使用。

#### 主要方法

1. **`execute_operation(operation_name, disable_ui: true, model: nil)`** - 执行模型操作
   ```ruby
   YueMuPro::OperationUtils.execute_operation('我的操作') do
     # 执行操作代码
     model.entities.add_line([0,0,0], [100,100,100])
   end
   ```

2. **`execute_operation_safe(operation_name, disable_ui: true, model: nil)`** - 安全执行模型操作（不抛出异常）
   ```ruby
   result = YueMuPro::OperationUtils.execute_operation_safe('我的操作') do
     # 执行操作代码
   end
   ```

#### 使用示例

**旧代码：**
```ruby
model.start_operation('添加组件', true)
begin
  # 执行操作
  model.entities.add_instance(definition, transformation)
  model.commit_operation
rescue => e
  model.abort_operation
  raise e
end
```

**新代码：**
```ruby
YueMuPro::OperationUtils.execute_operation('添加组件') do
  model.entities.add_instance(definition, transformation)
end
```

### PathUtils - 路径工具库

提供文件路径处理的通用功能。

#### 主要方法

1. **`plugin_path(*parts)`** - 获取插件资源路径
   ```ruby
   path = YueMuPro::PathUtils.plugin_path('material', 'guiti.skm')
   ```

2. **`material_path(filename)`** - 获取材质文件路径
   ```ruby
   path = YueMuPro::PathUtils.material_path('guiti.skm')
   ```

3. **`model_path(filename)`** - 获取模型文件路径
   ```ruby
   path = YueMuPro::PathUtils.model_path('s10.skp')
   ```

4. **`icon_path(filename)`** - 获取图标文件路径
   ```ruby
   path = YueMuPro::PathUtils.icon_path('logo.png')
   ```

5. **`html_path(filename)`** - 获取HTML文件路径
   ```ruby
   path = YueMuPro::PathUtils.html_path('login.html')
   ```

6. **`config_path(filename)`** - 获取配置文件路径
   ```ruby
   path = YueMuPro::PathUtils.config_path('config.json')
   ```

7. **`to_file_url(path)`** - 转换为 file:// URL
   ```ruby
   url = YueMuPro::PathUtils.to_file_url(path)
   ```

#### 使用示例

**旧代码：**
```ruby
skm_path = File.join(File.dirname(__FILE__), "material", "guiti.skm")
```

**新代码：**
```ruby
skm_path = YueMuPro::PathUtils.material_path('guiti.skm')
```

### GeometryUtils - 几何工具库

提供组件尺寸计算、角度计算等几何相关功能。

#### 主要方法

1. **`calculate_scale_factors(transformation)`** - 计算变换矩阵的缩放因子
   ```ruby
   scale_x, scale_y, scale_z = YueMuPro::GeometryUtils.calculate_scale_factors(transformation)
   ```

2. **`calculate_dimensions(bounds, scale_x, scale_y, scale_z, to_mm: true, precision: 2)`** - 计算组件实际尺寸
   ```ruby
   dims = YueMuPro::GeometryUtils.calculate_dimensions(bounds, scale_x, scale_y, scale_z)
   # => {width: 100.0, height: 200.0, depth: 50.0}
   ```

3. **`calculate_z_rotation_angle(transformation)`** - 计算Z轴旋转角度
   ```ruby
   angle = YueMuPro::GeometryUtils.calculate_z_rotation_angle(transformation)
   ```

4. **`calculate_total_dimensions(bounds, precision: 2)`** - 计算边界框总尺寸
   ```ruby
   dims = YueMuPro::GeometryUtils.calculate_total_dimensions(bounds)
   ```

5. **`get_entity_dimensions(entity, include_angle: true, include_transformation: false, invalidate_bounds: false)`** - 获取组件完整尺寸信息
   ```ruby
   info = YueMuPro::GeometryUtils.get_entity_dimensions(entity)
   # => {name: "组件", width: 100.0, height: 200.0, depth: 50.0, min_point: ..., angle: 0}
   ```

6. **`calculate_total_bounds(entities)`** - 计算多个组件的总边界框
   ```ruby
   total_bounds = YueMuPro::GeometryUtils.calculate_total_bounds(entities)
   ```

7. **`get_total_dimensions(entities)`** - 获取多个组件的总尺寸和角度
   ```ruby
   width, height, depth, min_point, angle = YueMuPro::GeometryUtils.get_total_dimensions(entities)
   ```

#### 使用示例

**旧代码（A1.rb中的重复代码）：**
```ruby
# 获取缩放因子
scale_x = (Geom::Vector3d.new(1, 0, 0)).transform!(entity.transformation).length
scale_y = (Geom::Vector3d.new(0, 1, 0)).transform!(entity.transformation).length
scale_z = (Geom::Vector3d.new(0, 0, 1)).transform!(entity.transformation).length

# 计算宽度、高度和深度
width = entity.definition.bounds.width * scale_x * 25.4
height = entity.definition.bounds.height * scale_y * 25.4
depth = entity.definition.bounds.depth * scale_z * 25.4

# 计算Z轴的旋转角度
xaxis = entity.transformation.xaxis
angle = Math.atan2(
  (Geom::Vector3d.new(1, 0, 0) * xaxis) % Geom::Vector3d.new(0, 0, 1),
  xaxis % Geom::Vector3d.new(1, 0, 0)
).radians.round
```

**新代码（使用库）：**
```ruby
info = YueMuPro::GeometryUtils.get_entity_dimensions(entity)
width = info[:width]
height = info[:height]
depth = info[:depth]
angle = info[:angle]
```

## 待实现的库

- **ComponentUtils** - 组件操作工具

