openscad-collision-detection
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseOpenSCAD Collision Detection
OpenSCAD碰撞检测
Detect and visualize geometric intersections in OpenSCAD models for woodworking and assembly validation.
检测并可视化OpenSCAD模型中的几何相交情况,用于木工与装配验证。
Quick Start
快速开始
Add collision checking to any OpenSCAD model in 3 steps:
openscad
// 1. Create reusable checker module
module check_collision(show_overlap=true) {
if (show_overlap) {
color("red", 0.8) intersection() {
children(0);
children(1);
}
}
%children(0); // Ghost first object
children(1); // Solid second object
}
// 2. Apply to your objects
check_collision() {
drawer(); // Moving part
cabinet_interior(); // Fixed structure
}
// 3. Preview (F5) - red regions show collisionsResult: Transparent reference geometry + solid moving part + red overlap visualization.
通过3步为任意OpenSCAD模型添加碰撞检测:
openscad
// 1. 创建可复用的检查器模块
module check_collision(show_overlap=true) {
if (show_overlap) {
color("red", 0.8) intersection() {
children(0);
children(1);
}
}
%children(0); // 以透明模式显示第一个对象(参考几何体)
children(1); // 显示第二个实体对象
}
// 2. 将模块应用到你的对象
check_collision() {
drawer(); // 活动部件
cabinet_interior(); // 固定结构
}
// 3. 预览(F5)- 红色区域表示碰撞结果: 透明参考几何体 + 实体活动部件 + 红色重叠区域可视化。
Table of Contents
目录
When to Use This Skill
何时使用该技能
Explicit Triggers
显式触发场景
- "Check collision between drawer and cabinet"
- "Detect interference in door swing"
- "Verify clearance for shelf spacing"
- "Show overlaps in assembly"
- "Check if drawer fits in cabinet"
- "Door hinge collision check"
- "Workbench against wall clearance"
- "检查抽屉与柜体的碰撞"
- "检测门摆动时的干涉"
- "验证搁板间距的间隙"
- "显示装配中的重叠区域"
- "检查抽屉是否适配柜体"
- "铰链碰撞检查"
- "工作台与墙面的间隙检查"
Implicit Triggers
隐式触发场景
- Designing cabinets with drawers
- Creating furniture assemblies
- Planning room layouts with furniture placement
- Validating mechanical clearances
- Debugging "won't fit" issues
- Testing parametric designs with varying dimensions
- 设计带抽屉的柜体
- 制作家具装配体
- 规划带家具的房间布局
- 验证机械间隙
- 调试“无法适配”问题
- 测试尺寸可变的参数化设计
Debugging Scenarios
调试场景
- Drawer won't close (hits back panel)
- Door hits adjacent object when opening
- Shelf spacing too tight for items
- Hinge cup interferes with door panel
- Workbench depth exceeds available space
- Parametric model generates invalid dimensions
- 抽屉无法关闭(碰到后挡板)
- 开门时碰到相邻物体
- 搁板间距过窄无法容纳物品
- 铰链杯与门板干涉
- 工作台深度超出可用空间
- 参数化模型生成无效尺寸
What This Skill Does
该技能的作用
Provides systematic approach to collision detection:
- Visualize intersections using to reveal overlap volumes
intersection() - Ghost reference geometry using modifier for transparent context
% - Highlight collisions with color coding (red = problem, yellow = clearance)
- Measure clearances with echo statements and visual indicators
- Create reusable patterns for common woodworking scenarios
- Integrate with project libraries (woodworkers-lib, BOSL2, labels.scad)
- Validate assemblies before fabrication or room layout
提供系统化的碰撞检测方法:
- 可视化相交区域:使用显示重叠体积
intersection() - 透明化参考几何体:使用修饰符显示透明背景
% - 颜色编码高亮碰撞:红色表示问题,黄色表示间隙
- 测量间隙:通过echo语句和视觉指示器
- 创建可复用模式:针对常见木工场景
- 与项目库集成(woodworkers-lib、BOSL2、labels.scad)
- 在制造或布局前验证装配体
Core Techniques
核心技术
intersection() - Reveal Overlaps
intersection() - 显示重叠区域
Returns geometry only where objects overlap:
openscad
// Show collision volume
color("red") intersection() {
drawer();
cabinet_interior();
}
// If result has volume → collision exists仅返回物体重叠部分的几何体:
openscad
// 显示碰撞体积
color("red") intersection() {
drawer();
cabinet_interior();
}
// 若结果有体积 → 存在碰撞Debug Modifiers
调试修饰符
| Modifier | Effect | Use Case |
|---|---|---|
| Transparent (ghost) | Show reference geometry |
| Highlight (red) | Emphasize specific object |
| Show only | Isolate object for testing |
| Disable | Temporarily hide geometry |
openscad
%cabinet_interior(); // Ghost
#drawer(); // Highlight| 修饰符 | 效果 | 使用场景 |
|---|---|---|
| 透明显示(幽灵模式) | 展示参考几何体 |
| 高亮显示(红色) | 强调特定对象 |
| 仅显示该对象 | 隔离对象进行测试 |
| 禁用显示 | 临时隐藏几何体 |
openscad
%cabinet_interior(); // 透明显示柜体内部
#drawer(); // 高亮显示抽屉BOSL2 Utilities
BOSL2工具
openscad
include <BOSL2/std.scad>
debug_this() drawer(); // Shows bounding box + transparent object
ghost() cabinet(); // Semantic equivalent to %openscad
include <BOSL2/std.scad>
debug_this() drawer(); // 显示边界框 + 透明对象
ghost() cabinet(); // 与%语义相同Reusable Patterns
可复用模式
Pattern 1: Basic Collision Checker
模式1:基础碰撞检查器
openscad
module check_collision(show_overlap=true, overlap_color="red") {
if (show_overlap) {
color(overlap_color, 0.8) intersection() {
children(0);
children(1);
}
}
%children(0); // Ghost first object
children(1); // Solid second object
}Usage:
openscad
check_collision() {
drawer_extended();
cabinet_side_panel();
}openscad
module check_collision(show_overlap=true, overlap_color="red") {
if (show_overlap) {
color(overlap_color, 0.8) intersection() {
children(0);
children(1);
}
}
%children(0); // 透明显示第一个对象
children(1); // 显示第二个实体对象
}用法:
openscad
check_collision() {
drawer_extended();
cabinet_side_panel();
}Pattern 2: Clearance Visualization
模式2:间隙可视化
openscad
module show_clearance(clearance=2, zones=true) {
// Original objects
%children(0);
children(1);
// Clearance zones
if (zones) {
color("yellow", 0.2)
offset(r=clearance)
projection(cut=false)
children(0);
}
// Collision check
color("red") intersection() {
children(0);
children(1);
}
}openscad
module show_clearance(clearance=2, zones=true) {
// 原始对象
%children(0);
children(1);
// 间隙区域
if (zones) {
color("yellow", 0.2)
offset(r=clearance)
projection(cut=false)
children(0);
}
// 碰撞检查
color("red") intersection() {
children(0);
children(1);
}
}Pattern 3: Conditional Debug Mode
模式3:条件调试模式
openscad
DEBUG_COLLISION = true; // Toggle at file top
module conditional_check() {
if (DEBUG_COLLISION) {
color("red") intersection() {
children(0);
children(1);
}
%children(0);
children(1);
} else {
children(0);
children(1);
}
}openscad
DEBUG_COLLISION = true; // 在文件顶部切换开关
module conditional_check() {
if (DEBUG_COLLISION) {
color("red") intersection() {
children(0);
children(1);
}
%children(0);
children(1);
} else {
children(0);
children(1);
}
}Pattern 4: Assembly Interference Check
模式4:装配干涉检查
openscad
module assembly_check(explode=false) {
spacing = explode ? 50 : 0;
// Check overlaps when assembled (explode=false)
if (!explode) {
color("red", 0.8) intersection() {
children(0);
children(1);
}
}
children(0);
translate([spacing, 0, 0]) children(1);
}
// Usage
assembly_check(explode=$preview) {
cabinet_shell();
drawer_assembly();
}openscad
module assembly_check(explode=false) {
spacing = explode ? 50 : 0;
// 装配状态下检查重叠(explode=false)
if (!explode) {
color("red", 0.8) intersection() {
children(0);
children(1);
}
}
children(0);
translate([spacing, 0, 0]) children(1);
}
// 用法
assembly_check(explode=$preview) {
cabinet_shell();
drawer_assembly();
}Woodworking Scenarios
木工场景
Drawer Clearance Check
抽屉间隙检查
openscad
include <woodworkers-lib/std.scad>
module drawer_clearance_check(cabinet_dim, drawer_dim, panel=18) {
interior_w = cabinet_dim[0] - 2 * panel;
interior_d = cabinet_dim[1] - panel;
interior_h = cabinet_dim[2] - 2 * panel;
// Ghost cabinet interior
%color("blue", 0.2)
translate([panel, 0, panel])
cube([interior_w, interior_d, interior_h]);
// Show drawer
color("green", 0.5) cube(drawer_dim);
// Highlight collision
color("red") intersection() {
translate([panel, 0, panel]) cube([interior_w, interior_d, interior_h]);
cube(drawer_dim);
}
// Echo clearances
side_clearance = (interior_w - drawer_dim[0]) / 2;
echo(str("Side clearance: ", side_clearance, "mm per side"));
}openscad
include <woodworkers-lib/std.scad>
module drawer_clearance_check(cabinet_dim, drawer_dim, panel=18) {
interior_w = cabinet_dim[0] - 2 * panel;
interior_d = cabinet_dim[1] - panel;
interior_h = cabinet_dim[2] - 2 * panel;
// 透明显示柜体内部
%color("blue", 0.2)
translate([panel, 0, panel])
cube([interior_w, interior_d, interior_h]);
// 显示抽屉
color("green", 0.5) cube(drawer_dim);
// 高亮碰撞区域
color("red") intersection() {
translate([panel, 0, panel]) cube([interior_w, interior_d, interior_h]);
cube(drawer_dim);
}
// 输出间隙信息
side_clearance = (interior_w - drawer_dim[0]) / 2;
echo(str("侧边间隙: ", side_clearance, "mm/侧"));
}Door Swing Interference
门摆动干涉检查
openscad
module door_swing_check(door_width, swing_angle=90, adjacent_pos=500) {
// Door sweep volume
color("yellow", 0.3)
rotate([0, 0, swing_angle])
cube([door_width, 5, 720]);
// Adjacent object
translate([adjacent_pos, 0, 0])
color("green", 0.5)
cube([200, 400, 720]);
// Check interference
color("red") intersection() {
rotate([0, 0, swing_angle]) cube([door_width, 5, 720]);
translate([adjacent_pos, 0, 0]) cube([200, 400, 720]);
}
}openscad
module door_swing_check(door_width, swing_angle=90, adjacent_pos=500) {
// 门摆动范围体积
color("yellow", 0.3)
rotate([0, 0, swing_angle])
cube([door_width, 5, 720]);
// 相邻物体
translate([adjacent_pos, 0, 0])
color("green", 0.5)
cube([200, 400, 720]);
// 检查干涉
color("red") intersection() {
rotate([0, 0, swing_angle]) cube([door_width, 5, 720]);
translate([adjacent_pos, 0, 0]) cube([200, 400, 720]);
}
}Shelf Spacing Validation
搁板间距验证
openscad
module shelf_spacing_check(cabinet_dim, shelf_positions, item_height, panel=18) {
// Draw shelves
for (z = shelf_positions) {
translate([0, 0, z])
%planeBottom([cabinet_dim[0], cabinet_dim[1], panel]);
}
// Check spacing
for (i = [0:len(shelf_positions)-2]) {
spacing = shelf_positions[i+1] - shelf_positions[i] - panel;
if (spacing < item_height) {
echo(str("WARNING: Shelf ", i, " spacing (", spacing,
"mm) < item height (", item_height, "mm)"));
// Highlight insufficient spacing
translate([0, 0, shelf_positions[i] + panel])
color("red", 0.5)
cube([cabinet_dim[0], cabinet_dim[1], spacing]);
}
}
}openscad
module shelf_spacing_check(cabinet_dim, shelf_positions, item_height, panel=18) {
// 绘制搁板
for (z = shelf_positions) {
translate([0, 0, z])
%planeBottom([cabinet_dim[0], cabinet_dim[1], panel]);
}
// 检查间距
for (i = [0:len(shelf_positions)-2]) {
spacing = shelf_positions[i+1] - shelf_positions[i] - panel;
if (spacing < item_height) {
echo(str("警告: 第", i, "层搁板间距(", spacing,
"mm) < 物品高度(", item_height, "mm)"));
// 高亮间距不足区域
translate([0, 0, shelf_positions[i] + panel])
color("red", 0.5)
cube([cabinet_dim[0], cabinet_dim[1], spacing]);
}
}
}Debugging Workflow
调试工作流
Follow this systematic 5-step process:
遵循以下5步系统化流程:
Step 1: Isolate Components
步骤1:隔离组件
openscad
!drawer(); // Show only drawer (use ! modifier)openscad
!drawer(); // 仅显示抽屉(使用!修饰符)Step 2: Ghost Reference Geometry
步骤2:透明化参考几何体
openscad
%cabinet_interior();
drawer();openscad
%cabinet_interior();
drawer();Step 3: Check Intersection
步骤3:检查相交区域
openscad
color("red") intersection() {
cabinet_interior();
drawer();
}
// No volume = no collisionopenscad
color("red") intersection() {
cabinet_interior();
drawer();
}
// 无体积表示无碰撞Step 4: Measure Clearance
步骤4:测量间隙
openscad
drawer_width = 764;
interior_width = 782;
clearance = interior_width - drawer_width;
echo(str("Total clearance: ", clearance, "mm (", clearance/2, "mm per side)"));
if (clearance < 4) {
echo("ERROR: Insufficient clearance!");
}openscad
drawer_width = 764;
interior_width = 782;
clearance = interior_width - drawer_width;
echo(str("总间隙: ", clearance, "mm (每侧", clearance/2, "mm)"));
if (clearance < 4) {
echo("错误: 间隙不足!");
}Step 5: Iterate with Parameters
步骤5:参数化迭代
openscad
DRAWER_CLEARANCE = 2; // mm per side
module drawer_with_clearance(interior_width) {
width = interior_width - 2*DRAWER_CLEARANCE;
cube([width, 400, 100]);
}openscad
DRAWER_CLEARANCE = 2; // 每侧间隙(mm)
module drawer_with_clearance(interior_width) {
width = interior_width - 2*DRAWER_CLEARANCE;
cube([width, 400, 100]);
}Supporting Files
支持文件
examples/examples.md
examples/examples.md
Comprehensive collision detection examples:
- Drawer clearance checks (side, top, depth)
- Door swing interference (hinges, adjacent objects)
- Shelf spacing validation (item heights, bin clearance)
- Hinge collision detection (cup-to-door, door-to-frame)
- Room layout validation (workbench against wall)
- Assembly interference (multi-part checking)
全面的碰撞检测示例:
- 抽屉间隙检查(侧边、顶部、深度)
- 门摆动干涉(铰链、相邻物体)
- 搁板间距验证(物品高度、收纳箱间隙)
- 铰链碰撞检测(杯体与门板、门板与框架)
- 房间布局验证(工作台与墙面)
- 装配干涉(多部件检查)
references/reference.md
references/reference.md
Technical reference:
- OpenSCAD boolean operations (intersection, difference, union)
- Manifold vs CGAL engine comparison
- Performance optimization techniques
- Color coding standards for collision detection
- Mathematical clearance calculations
- Integration with BOSL2 and woodworkers-lib
技术参考:
- OpenSCAD布尔运算(intersection、difference、union)
- Manifold与CGAL引擎对比
- 性能优化技巧
- 碰撞检测的颜色编码标准
- 间隙计算的数学方法
- 与BOSL2和woodworkers-lib的集成
Expected Outcomes
预期结果
Successful Collision Detection
成功的碰撞检测
No collision:
ECHO: "Side clearance: 2.0mm per side"
ECHO: "Top clearance: 5.0mm"
ECHO: "Depth clearance: 10.0mm"Preview shows no red regions.
Collision detected:
ECHO: "WARNING: Drawer collision detected!"
ECHO: "Overlap volume: 15mm × 18mm × 100mm"
ECHO: "Reduce drawer width by 15mm"Preview shows red overlap region.
无碰撞:
ECHO: "侧边间隙: 2.0mm/侧"
ECHO: "顶部间隙: 5.0mm"
ECHO: "深度间隙: 10.0mm"预览无红色区域。
检测到碰撞:
ECHO: "警告: 检测到抽屉碰撞!"
ECHO: "重叠体积: 15mm × 18mm × 100mm"
ECHO: "将抽屉宽度减少15mm"预览显示红色重叠区域。
Visual Feedback
视觉反馈
| Color | Meaning |
|---|---|
| Red | Collision/interference |
| Yellow | Clearance zone |
| Green | Moving parts |
| Blue | Fixed structure |
| Transparent | Reference geometry |
| 颜色 | 含义 |
|---|---|
| 红色 | 碰撞/干涉 |
| 黄色 | 间隙区域 |
| 绿色 | 活动部件 |
| 蓝色 | 固定结构 |
| 透明 | 参考几何体 |
Integration Points
集成点
With woodworkers-lib
与woodworkers-lib集成
openscad
include <woodworkers-lib/std.scad>
module ww_collision_check(outer_dim, inner_dim) {
// Outer box (cabinet)
%color("blue", 0.2) {
planeBottom(outer_dim);
planeTop(outer_dim);
planeLeft(outer_dim, t=-1, b=-1);
planeRight(outer_dim, t=-1, b=-1);
}
// Inner box (drawer)
color("green", 0.5) {
planeBottom(inner_dim);
// ... other planes
}
}openscad
include <woodworkers-lib/std.scad>
module ww_collision_check(outer_dim, inner_dim) {
// 外部箱体(柜体)
%color("blue", 0.2) {
planeBottom(outer_dim);
planeTop(outer_dim);
planeLeft(outer_dim, t=-1, b=-1);
planeRight(outer_dim, t=-1, b=-1);
}
// 内部箱体(抽屉)
color("green", 0.5) {
planeBottom(inner_dim);
// ... 其他平面
}
}With labels.scad
与labels.scad集成
openscad
include <lib/labels.scad>
module labeled_collision_check() {
labeled_cuboid([800, 400, 100],
name="DRAWER",
box_color="green"
);
translate([0, 0, 100])
labeled_cuboid([800, 400, 18],
name="SHELF",
box_color="brown"
);
// Collision check
color("red") intersection() {
cube([800, 400, 100]);
translate([0, 0, 100]) cube([800, 400, 18]);
}
}openscad
include <lib/labels.scad>
module labeled_collision_check() {
labeled_cuboid([800, 400, 100],
name="DRAWER",
box_color="green"
);
translate([0, 0, 100])
labeled_cuboid([800, 400, 18],
name="SHELF",
box_color="brown"
);
// 碰撞检查
color("red") intersection() {
cube([800, 400, 100]);
translate([0, 0, 100]) cube([800, 400, 18]);
}
}With BOSL2 Attachments
与BOSL2附件集成
openscad
include <BOSL2/std.scad>
diff()
cuboid([100, 100, 50])
attach(TOP) tag("remove")
cyl(d=20, h=30); // Check if penetrates too deepopenscad
include <BOSL2/std.scad>
diff()
cuboid([100, 100, 50])
attach(TOP) tag("remove")
cyl(d=20, h=30); // 检查是否过度穿透Requirements
要求
Tools
工具
- OpenSCAD 2025.x (Manifold engine for fast intersections)
- BOSL2 library (optional, for debug_this/ghost utilities)
- woodworkers-lib (optional, for cabinet/furniture patterns)
- OpenSCAD 2025.x(Manifold引擎用于快速布尔运算)
- BOSL2库(可选,用于debug_this/ghost工具)
- woodworkers-lib(可选,用于柜体/家具模式)
Knowledge
知识
- Basic OpenSCAD syntax (modules, translate, cube)
- CSG operations (union, difference, intersection)
- Debug modifiers (%, #, !, *)
- Color syntax with alpha channel
- 基础OpenSCAD语法(模块、translate、cube)
- CSG运算(union、difference、intersection)
- 调试修饰符(%, #, !, *)
- 带alpha通道的颜色语法
Environment
环境
- Preview mode (F5) for fast iteration
- Console output visible for echo statements
- 预览模式(F5)用于快速迭代
- 可见的控制台输出以查看echo语句
Red Flags to Avoid
需避免的问题
- Not checking clearances before fabrication - Always validate fits
- Ignoring echo warnings - Console output reveals dimension problems
- Using render (F6) for collision checks - Preview (F5) is 10-100x faster
- Forgetting alpha channel in colors - not
color("red", 0.5)color("red") - Testing only best-case scenarios - Check extreme parameter values
- Nesting intersection() unnecessarily - Slows down renders significantly
- Not parameterizing clearances - Hardcoded values make iteration difficult
- Skipping validation in parametric designs - Add statements
assert() - Assuming preview accuracy - Render (F6) for final validation if critical
- Not documenting clearance requirements - Add comments explaining minimums
- 制造前不检查间隙 - 始终验证适配性
- 忽略echo警告 - 控制台输出会暴露尺寸问题
- 使用渲染(F6)进行碰撞检查 - 预览(F5)速度快10-100倍
- 忘记颜色的alpha通道 - 使用而非
color("red", 0.5)color("red") - 仅测试最佳场景 - 检查极端参数值
- 不必要地嵌套intersection() - 会显著降低渲染速度
- 不对间隙进行参数化 - 硬编码值会增加迭代难度
- 跳过参数化设计的验证 - 添加语句
assert() - 假设预览完全准确 - 关键间隙需使用渲染(F6)进行最终验证
- 不记录间隙要求 - 添加注释说明最小间隙
Notes
注意事项
Manifold Engine: OpenSCAD 2025+ uses Manifold by default for 10-100x faster boolean operations. If intersection results look wrong, try as fallback.
--backend CGALPreview vs Render: Collision detection is usually sufficient in preview mode (F5). Only use render (F6) for final validation of critical clearances.
Color Consistency: Use red for collisions, yellow for clearances, green for moving parts, blue for fixed structure throughout all models.
Documentation: Add echo statements for all clearance calculations. Future you will thank present you.
Parametric Validation: Use to enforce clearance minimums:
assert()openscad
assert(clearance >= 4, "Drawer clearance must be >= 4mm");Manifold引擎: OpenSCAD 2025+默认使用Manifold,布尔运算速度提升10-100倍。若相交结果异常,可尝试使用作为备选。
--backend CGAL预览 vs 渲染: 碰撞检测通常在预览模式(F5)下即可满足需求。仅在验证关键间隙时使用渲染(F6)。
颜色一致性: 在所有模型中统一使用红色表示碰撞、黄色表示间隙、绿色表示活动部件、蓝色表示固定结构。
文档: 为所有间隙计算添加echo语句,未来的你会感谢现在的自己。
参数化验证: 使用强制最小间隙要求:
assert()openscad
assert(clearance >= 4, "抽屉间隙必须≥4mm");