Rust 3D建模命令宏库kittycad-modeling-cmds-macros使用指南

简介

kittycad-modeling-cmds-macros是一个Rust宏库，用于高效生成CAD建模指令和自动化脚本。它提供了一套声明式宏系统，可以简化3D建模命令的创建过程，特别适合需要批量生成复杂CAD操作的场景。

主要特性

• 类型安全的CAD命令构建
• 减少样板代码
• 编译时错误检查
• 与KittyCAD建模引擎无缝集成
• 支持命令组合和复用

安装

在Cargo.toml中添加依赖：

[dependencies]
kittycad-modeling-cmds-macros = "0.1"

基本用法

1. 创建基本形状

use kittycad_modeling_cmds_macros::*;

// 创建一个立方体
let cube = cmd!(make_cube {
    center: (0.0, 0.0, 0.0),
    size: 10.0
});

// 创建一个球体
let sphere = cmd!(make_sphere {
    center: (5.0, 5.0, 5.0),
    radius: 3.0
});

2. 变换操作

// 平移操作
let moved_cube = cmd!(transform_move {
    target: cube,
    offset: (5.0, 0.0, 0.0)
});

// 旋转操作
let rotated = cmd!(transform_rotate {
    target: moved_cube,
    axis: (0.0, 1.0, 0.0),
    angle_degrees: 45.0
});

// 缩放操作
let scaled = cmd!(transform_scale {
    target: rotated,
    factor: (1.0, 2.0, 1.0)
});

3. 布尔运算

// 并集
let union = cmd!(boolean_union {
    a: cube,
    b: sphere
});

// 差集
let difference = cmd!(boolean_subtract {
    a: cube,
    b: sphere
});

// 交集
let intersection = cmd!(boolean_intersect {
    a: cube,
    b: sphere
});

高级用法

1. 命令组合

// 创建一个组合命令
let complex_shape = cmd!(command_group {
    commands: vec![
        cmd!(make_cube { center: (0.0, 0.0, 0.0), size: 10.0 }),
        cmd!(make_sphere { center: (5.0, 5.0, 5.0), radius: 3.0 }),
        cmd!(boolean_union {
            a: 0, // 引用第一个命令的结果
            b: 1  // 引用第二个命令的结果
        })
    ]
});

2. 参数化设计

// 参数化创建齿轮
fn create_gear(teeth: u32, radius: f64, thickness: f64) -> Command {
    cmd!(command_group {
        commands: vec![
            // 创建齿轮主体
            cmd!(make_cylinder {
                center: (0.0, 0.0, 0.0),
                radius: radius,
                height: thickness
            }),
            // 创建齿槽 (简化示例)
            cmd!(command_repeat {
                count: teeth,
                command: cmd!(make_cube {
                    center: (radius, 0.0, 0.0),
                    size: (radius * 0.2, radius * 0.4, thickness)
                }),
                transform: cmd!(transform_rotate {
                    axis: (0.0, 0.0, 1.0),
                    angle_degrees: 360.0 / teeth as f64
                })
            }),
            // 布尔运算
            cmd!(boolean_subtract {
                a: 0,
                b: 1
            })
        ]
    })
}

3. 导出脚本

// 生成KittyCAD建模脚本
let script = complex_shape.to_script();

// 或者直接导出为JSON
let json = serde_json::to_string(&complex_shape).unwrap();

完整示例demo

下面是一个完整的示例程序，展示如何使用kittycad-modeling-cmds-macros创建一个简单的机械零件：

use kittycad_modeling_cmds_macros::*;
use serde_json;

fn main() {
    // 1. 创建基础零件
    let base = cmd!(make_cylinder {
        center: (0.0, 0.0, 0.0),
        radius: 5.0,
        height: 2.0
    });

    // 2. 创建四个安装孔
    let holes = cmd!(command_group {
        commands: vec![
            // 第一个安装孔
            cmd!(make_cylinder {
                center: (3.0, 3.0, 0.0),
                radius: 0.5,
                height: 2.0
            }),
            // 第二个安装孔
            cmd!(make_cylinder {
                center: (-3.0, 3.0, 0.0),
                radius: 0.5,
                height: 2.0
            }),
            // 第三个安装孔
            cmd!(make_cylinder {
                center: (3.0, -3.0, 0.0),
                radius: 0.5,
                height: 2.0
            }),
            // 第四个安装孔
            cmd!(make_cylinder {
                center: (-3.0, -3.0, 0.0),
                radius: 0.5,
                height: 2.0
            }),
            // 将四个孔合并为一个对象
            cmd!(boolean_union {
                a: 0,
                b: 1
            }),
            cmd!(boolean_union {
                a: 2,
                b: 3
            }),
            cmd!(boolean_union {
                a: 4,
                b: 5
            })
        ]
    });

    // 3. 从基础零件中减去安装孔
    let final_part = cmd!(boolean_subtract {
        a: base,
        b: holes
    });

    // 4. 添加一个中心支柱
    let pillar = cmd!(make_cylinder {
        center: (0.0, 0.0, 1.0),
        radius: 1.5,
        height: 4.0
    });

    let final_assembly = cmd!(boolean_union {
        a: final_part,
        b: pillar
    });

    // 5. 导出为JSON
    let json = serde_json::to_string(&final_assembly).unwrap();
    println!("Generated CAD model: {}", json);
}

最佳实践

1. 模块化设计：将常用操作封装为函数，便于复用
2. 错误处理：利用Rust的类型系统在编译时捕获错误
3. 性能优化：对于复杂模型，考虑使用命令批处理
4. 文档注释：为自定义命令添加详细文档

示例项目结构

my_cad_project/
├── Cargo.toml
├── src/
│   ├── main.rs
│   ├── parts/
│   │   ├── gear.rs      # 齿轮生成器
│   │   ├── bracket.rs   # 支架生成器
│   │   └── mod.rs
│   └── assembly.rs      # 装配逻辑

注意事项

1. 确保使用最新版本的宏库
2. 复杂的布尔运算可能需要性能优化
3. 某些高级CAD功能可能需要直接使用KittyCAD API
4. 调试时可以先构建简单形状验证逻辑

这个宏库特别适合需要程序化生成3D模型的场景，如参数化设计、批量模型生成或CAD自动化工作流。