openscad-collision-detection

What this skill does

# OpenSCAD Collision Detection

Detect and visualize geometric intersections in OpenSCAD models for woodworking and assembly validation.

## 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.

## Table of Contents

1. [When to Use This Skill](#1-when-to-use-this-skill)
2. [What This Skill Does](#2-what-this-skill-does)
3. [Core Techniques](#3-core-techniques)
4. [Reusable Patterns](#4-reusable-patterns)
5. [Woodworking Scenarios](#5-woodworking-scenarios)
6. [Debugging Workflow](#6-debugging-workflow)
7. [Supporting Files](#7-supporting-files)
8. [Expected Outcomes](#8-expected-outcomes)
9. [Integration Points](#9-integration-points)
10. [Requirements](#10-requirements)
11. [Red Flags to Avoid](#11-red-flags-to-avoid)

## 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

## Core Techniques

### intersection() - Reveal Overlaps

Returns geometry only where objects overlap:

```openscad
// Show collision volume
color("red") intersection() {
    drawer();
    cabinet_interior();
}
// If result has volume → collision exists
```

### 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
```

### BOSL2 Utilities

```openscad
include <BOSL2/std.scad>

debug_this() drawer();  // Shows bounding box + transparent object
ghost() cabinet();      // Semantic equivalent to %
```

## Reusable Patterns

### Pattern 1: Basic Collision Checker

```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();
}
```

### Pattern 2: Clearance Visualization

```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);
    }
}
```

### Pattern 3: Conditional Debug Mode

```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);
    }
}
```

### Pattern 4: Assembly Interference Check

```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();
}
```

## 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"));
}
```

### 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]);
    }
}
```

### 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]);
        }
    }
}
```

## Debugging Workflow

Follow this systematic 5-step process:

### Step 1: Isolate Components

```openscad
!drawer();  // Show only drawer (use ! modifier)
```

### Step 2: Ghost Reference Geometry

```openscad
%cabinet_interior();
drawer();
```

### Step 3: Check Intersection

```openscad
color("red") intersection() {
    cabinet_interior();
    drawer();
}
// No volume = no collision
```

### Step 4: Measure Clearance

```openscad
drawer_width = 764;
interior_width