openscad-collision-detection

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OpenSCAD 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 collisions
Result: 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:
  1. Visualize intersections using
    intersection()
    to reveal overlap volumes
  2. Ghost reference geometry using
    %
    modifier for transparent context
  3. Highlight collisions with color coding (red = problem, yellow = clearance)
  4. Measure clearances with echo statements and visual indicators
  5. Create reusable patterns for common woodworking scenarios
  6. Integrate with project libraries (woodworkers-lib, BOSL2, labels.scad)
  7. Validate assemblies before fabrication or room layout
提供系统化的碰撞检测方法:
  1. 可视化相交区域:使用
    intersection()
    显示重叠体积
  2. 透明化参考几何体:使用
    %
    修饰符显示透明背景
  3. 颜色编码高亮碰撞:红色表示问题,黄色表示间隙
  4. 测量间隙:通过echo语句和视觉指示器
  5. 创建可复用模式:针对常见木工场景
  6. 与项目库集成(woodworkers-lib、BOSL2、labels.scad)
  7. 在制造或布局前验证装配体

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

调试修饰符

ModifierEffectUse Case
%
Transparent (ghost)Show reference geometry
#
Highlight (red)Emphasize specific object
!
Show onlyIsolate object for testing
*
DisableTemporarily 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 collision
openscad
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

视觉反馈

ColorMeaning
RedCollision/interference
YellowClearance zone
GreenMoving parts
BlueFixed structure
TransparentReference 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 deep
openscad
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 -
    color("red", 0.5)
    not
    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
    assert()
    statements
  • 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
--backend CGAL
as fallback.
Preview 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
assert()
to enforce clearance minimums:
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");