界面交互指南
上图为 macOS 上的真实运行界面，模型由内置 scripts/0composite.lua 示例生成。
JellyCAD 提供了直观的图形界面，方便用户进行三维模型的可视化编辑和交互操作。本指南将介绍界面的各个区域及其常用操作方法。
界面布局
JellyCAD 的主界面包含以下区域：
1. 自定义标题栏
窗口顶部使用与应用深色主题一致的自定义标题栏，替代系统默认标题栏。标题显示当前文件名、工作目录和 JellyCAD 名称；文件有未保存的修改时，标题开头显示 *。
| 操作 | 功能 |
|---|---|
| 拖动标题栏的文字或空白区域 | 移动窗口 |
| 双击标题栏 | 最大化／还原窗口 |
点击右上角 − | 最小化窗口 |
| 点击右上角方框按钮 | 最大化／还原窗口 |
点击右上角 × | 关闭窗口 |
| 拖动窗口边缘或四角 | 调整非最大化窗口的大小 |
关闭窗口仍会检查未保存的修改，可选择保存、放弃修改或取消关闭。若脚本正在执行，应用会请求停止并在脚本结束后关闭窗口。
2. 侧边工具栏
位于窗口左侧，从上到下提供文件管理器、脚本编辑器、版本控制、终端、形状信息和帮助面板入口。
3. 工作区
位于窗口中部左侧，包含以下功能：
- 脚本编辑器 - 编写和编辑 Lua 建模脚本
- 文件管理器 - 选择工作目录，打开或管理脚本文件
- 版本控制 - 查看 Git 工作区状态和文件改动
- 终端窗口 - 显示脚本执行输出和错误信息
- 形状信息 - 显示选中对象的详细信息（顶点、边、面等）
- 帮助 - 查看使用说明和版本信息
4. 3D视图区
位于窗口右侧，用于实时显示和操作三维模型：
- 模型预览 - 显示脚本生成的三维模型
- 坐标轴指示器 - 显示当前视图的方向（X/Y/Z轴）
- 网格地面 - 提供空间参考
- 交互控制 - 支持鼠标操作进行视图变换
5. 状态栏
底部显示脚本执行状态；右侧 Auto preview 复选框控制打开或保存脚本后的自动预览。编辑器底部另有 Lua 诊断、编码和缩进状态。
脚本编辑器
脚本编辑器是 JellyCAD 的核心工作区域，用于编写 Lua 建模脚本。
基本操作
新建脚本
- 点击左侧文件管理器按钮，选择工作目录
- 在文件列表空白处右键选择 New File，或双击空白处；文件列表获得焦点时也可按
Ctrl+N - 输入文件名并确认，然后在编辑器中编写 Lua 代码
打开脚本
- 在文件管理器中点击 Open Folder 选择工作目录
- 双击列表中的
.lua文件，或右键选择 Open - 文件会在脚本编辑器中打开，窗口标题同步显示文件名
保存脚本
- 点击顶部工具栏的 Save 按钮
- 或使用快捷键
Ctrl+S - 首次保存时会弹出文件保存对话框
运行脚本
- 按
F5键或点击运行按钮 - 脚本执行结果会显示在3D视图区
- 错误信息会显示在终端窗口
编辑功能
编辑器内置 Lua 分析，无需额外安装语言服务器。顶部 Code 菜单和编辑区右键菜单提供以下命令（macOS 的 Ctrl 组合键对应 Command；以菜单显示为准）：
| 功能 | 操作 |
|---|---|
| 自动缩进 | Enter 按 Lua 代码块缩进；输入 end、else、elseif、until 或闭括号时自动回退缩进 |
| 缩进／取消缩进 | Tab／Shift+Tab，支持多行选择，使用 4 个空格 |
| 代码折叠 | 点击行号右侧三角；Ctrl+Shift+[ 折叠／展开当前行，Ctrl+Shift+] 展开全部 |
| 括号／引号匹配 | 自动补齐 ()、[]、{}、单引号和双引号；支持包裹选区、跳过已有闭符号、成对删除及匹配高亮 |
| 自动补全 | 输入时弹出，或按 Ctrl+Space；方向键选择，Enter／Tab 确认，Esc 关闭 |
| 函数参数提示 | 输入 (、, 时显示签名及当前参数序号，或按 Ctrl+Shift+Space |
| 跳转定义 | 光标放在变量／函数名上按 F12 |
| 查找引用 | Shift+F12，在 References 列表中点击结果跳转（包含定义位置） |
| 语法检查 | 编辑后自动检查，或按 Ctrl+Shift+M；底部 Lua 状态链接打开 Problems 列表 |
| 代码格式化 | Ctrl+Shift+F，统一代码块缩进，支持一次撤销 |
| 注释／取消注释 | Ctrl+/ |
| 查找文本 | Ctrl+F |
补全包含 Lua 关键字、常用标准库、JellyCAD 构造函数、方法目录和当前作用域内的变量／函数。参数提示支持当前脚本定义的函数、常用标准函数和 JellyCAD API；标有 JellyCAD 的方法提示来自 API 目录，不表示已推断接收对象类型。
定义和引用分析限于当前脚本，区分局部变量、函数参数、循环变量及嵌套作用域，也支持直接命名的表方法；不解析跨文件 require、动态索引、表别名或运行时生成的成员。未找到静态定义时会在状态栏提示。
语法检查使用与运行脚本相同版本的 Lua 编译器，只编译、不执行代码；红色波浪线显示首个语法错误，黄色波浪线提示没有引用的局部变量（忽略参数和 _ 开头的名称）。悬停查看详情，或在 Problems 列表中点击定位。编辑后旧引用结果会清除，避免跳到过期位置。
格式化采用保守的缩进整理，保留表达式间距、字符串／长字符串及注释内容，保留文件原有 LF／CRLF 和末尾换行；存在语法错误时先提示修正。折叠只影响显示，不修改文件；编辑或跳转到隐藏内容时会展开代码。
示例代码
-- 创建一个简单的圆角立方体
b = box.new(10, 10, 10)
b:fillet(1, {})
b:color("blue")
b:show()3D视图操作
3D视图区提供了丰富的交互功能，让你可以从各个角度观察和操作模型。
视图控制
旋转视图
- 鼠标右键拖拽 - 自由旋转视图
- 旋转时可以从任意角度观察模型
平移视图
- 鼠标左键 - 平移视图
缩放视图
- 鼠标滚轮 - 放大或缩小视图
视图快捷操作
右键点击3D视图区，弹出菜单提供以下功能：
- Fit All - 自适应显示所有对象
- View Front/Back - 切换到前视图/后视图
- View Top/Bottom - 切换到俯视图/仰视图
- View Left/Right - 切换到左视图/右视图
- View Isometric - 切换到等轴测视图
选择模式
3D视图支持多种选择模式，用于选中和操作模型的不同部分。
切换选择模式
右键点击3D视图区，在弹出菜单中选择：
Select Shapes - 形状选择模式（默认）
- 选中整个形状对象
- 用于移动、复制、删除整个模型
Select Faces - 面选择模式
- 选中形状的某个面
- 可查看面的面积、法向量等信息
- 用于面级别的操作和分析
Select Edges - 边缘选择模式
- 选中形状的某条边
- 可查看边的类型、长度、起止点等信息
- 用于圆角、倒角等边缘操作（参见圆角和倒角操作）
Select Vertices - 顶点选择模式
- 选中形状的某个顶点
- 可查看顶点的精确坐标
- 用于顶点级别的分析
选择操作
- 单击 - 选中单个对象
- Ctrl + 单击 - 多选（添加到选择集）
- 单击空白处 - 取消选择
形状信息查看
当选中某个形状、面、边或顶点后，工作区会显示详细信息：
形状信息示例：
- 类型（Solid、Face、Edge、Vertex）
- 体积（对于实体）
- 表面积
- 包围盒尺寸
- 质心位置
边缘信息示例：
{
type = 'line', -- 边缘类型
first = {0, 0, 0}, -- 起点坐标
last = {10, 0, 0}, -- 终点坐标
length = 10.0, -- 边长
tol = 1e-6 -- 容差
}插入边缘信息到编辑器：
- 在边缘选择模式下选中边缘
- 点击工作区的 Insert edge info to editor 按钮
- 边缘信息会自动插入到编辑器光标位置
- 可直接用于圆角、倒角等操作
工作区面板
工作区提供了多个功能面板，帮助你查看信息和调试脚本。
终端窗口
终端窗口显示脚本执行的输出信息：
输出内容：
- Lua 脚本的
print()输出 - 函数执行结果
- 警告信息
- 错误信息和堆栈跟踪
常见错误信息：
-- 语法错误
[Error] unexpected symbol near '='
-- 运行时错误
[Error] attempt to call a nil value形状信息面板
显示当前选中对象的详细几何信息：
实体信息：
- 体积（Volume）
- 表面积（Surface Area）
- 面数量（Number of Faces）
- 边数量（Number of Edges）
- 顶点数量（Number of Vertices）
位置姿态：
- 质心坐标（Center of Mass）
- 包围盒范围（Bounding Box）
- 当前位置（Position）
- 当前旋转（Rotation）
快捷键参考
文件操作
| 快捷键 | 功能 |
|---|---|
Ctrl+N | 文件列表获得焦点时新建文件 |
Ctrl+S | 保存文件 |
F2 | 文件列表获得焦点时重命名选中的文件 |
编辑操作
| 快捷键 | 功能 |
|---|---|
Ctrl+Z | 撤销 |
Ctrl+Y | 重做 |
Ctrl+C | 复制 |
Ctrl+V | 粘贴 |
Ctrl+X | 剪切 |
Ctrl+F | 查找 |
脚本执行
按 F5 或点击 Run 显式运行脚本；勾选 Auto preview 时，打开或保存文档会自动执行预览。
使用技巧
1. 快速原型开发
- 在编辑器中编写简短代码段
- 根据3D视图调整参数
- 迭代优化设计
2. 调试模型
- 使用
print()输出中间结果 - 使用
:show()分步显示模型 - 通过形状信息面板检查尺寸
- 使用选择模式检查细节
3. 参数化建模
-- 使用变量控制尺寸
width = 10
height = 20
depth = 5
radius = 1
box.new(width, height, depth)
:fillet(radius, {})
:show()4. 批量显示
-- 一次显示多个对象
box1 = box.new(5, 5, 5):color("red")
box2 = cylinder.new(2, 8):x(10):color("blue")
box3 = sphere.new(3):x(20):color("green")
show({box1, box2, box3})5. 使用注释
-- 良好的注释习惯
-- 创建基座
base = cylinder.new(50, 35)
-- 创建孔洞
hole = cylinder.new(10, 40):z(-5)
-- 布尔运算
result = base:cut(hole)
result:show()常见问题
Q: 模型显示不完整或看不见？
A: 尝试以下方法：
- 右键点击3D视图，选择 Fit All
- 检查脚本是否调用了
:show()方法 - 检查对象的位置是否超出视野范围
- 检查透明度设置是否过高
Q: 脚本执行报错如何处理？
A: 查看终端窗口的错误信息：
- 检查语法错误（如缺少括号、逗号等）
- 检查函数名和参数是否正确
- 检查变量是否已定义
- 参考 脚本函数文档
Q: 如何导出高质量的STL文件？
A: 使用 export_stl() 并设置合适的参数：
export_stl("model.stl", {
type = "binary",
radian = 0.01 -- 越小越精细
})Q: 选择的边缘信息不准确？
A: 调整容差参数：
-- 增大 tol 值以提高匹配率
edge_info = {
type = 'line',
first = {0, 0, 0},
last = {10, 0, 0},
tol = 1e-2 -- 从默认的 1e-6 增大到 1e-2
}