Back to Details

stl-generator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

STL Generator for Woodworking Jigs

木工夹具STL生成工具

Generate parametric 3D printable jigs and fixtures for woodworking projects using CadQuery.
使用CadQuery为木工项目生成可参数化调整的3D打印夹具。

Target Printer Specifications

目标打印机参数

  • Printer: Elegoo Neptune 4 Pro
  • Build volume: 225mm × 225mm × 265mm
  • Layer height: 0.2mm standard
  • Units: Metric (millimeters)
For complete specifications and design constraints, read 
references/printer_specs.md
.
  • 打印机: Elegoo Neptune 4 Pro
  • 打印尺寸: 225mm × 225mm × 265mm
  • 层高: 标准0.2mm
  • 单位: 公制（毫米）
完整参数和设计限制请查看
references/printer_specs.md
。

Available Pre-Built Scripts

可用的预构建脚本

1. Circle Cutting Jig (
scripts/circle_cutting_jig.py
)

1. 圆形切割夹具（
scripts/circle_cutting_jig.py
）

Creates router jigs for cutting perfect circles - ideal for lampshade rings and circular frames.
Usage:
bash
python scripts/circle_cutting_jig.py <outer_diameter> <inner_diameter> [output.stl]
Example:
bash
python scripts/circle_cutting_jig.py 300 250 lampshade_jig.stl
Features:
  • Adjustable inner/outer diameters
  • Built-in guide ring for router stability
  • Center pivot hole for compass-style cutting
  • Radial slot for router bit clearance
  • Alignment marks every 45°
生成用于切割完美圆形的修边机夹具，非常适合制作灯罩环和圆形框架。
用法:
bash
python scripts/circle_cutting_jig.py <outer_diameter> <inner_diameter> [output.stl]
示例:
bash
python scripts/circle_cutting_jig.py 300 250 lampshade_jig.stl
特性:
  • 可调整内外直径
  • 内置导向环提升修边机稳定性
  • 中心枢轴孔支持圆规式切割
  • 径向开槽为修边机刀头提供避让空间
  • 每45°设置对齐标记

2. Angle Wedge (
scripts/angle_wedge.py
)

2. 角度楔块（
scripts/angle_wedge.py
）

Creates angle guide wedges for compound cuts and angled assembly work.
Usage:
bash
python scripts/angle_wedge.py <angle_degrees> [output.stl]
Example:
bash
python scripts/angle_wedge.py 15 wedge_15deg.stl
Features:
  • Any angle from 1-60 degrees
  • Raised reference edge on hypotenuse
  • Embossed angle label
  • Stable base for accurate positioning
生成用于复合切割和斜向组装的角度导向楔块。
用法:
bash
python scripts/angle_wedge.py <angle_degrees> [output.stl]
示例:
bash
python scripts/angle_wedge.py 15 wedge_15deg.stl
特性:
  • 支持1-60°任意角度
  • 斜边带有凸起参考边缘
  • 压印角度标识
  • 稳定底座确保定位精准

3. Spacing Blocks (
scripts/spacing_block.py
)

3. 定位垫块（
scripts/spacing_block.py
）

Creates precision spacing blocks for consistent assembly gaps and setup.
Usage:
bash
undefined
生成用于保证组装间隙和设置一致性的高精度定位垫块。
用法:
bash
undefined

Single block

单个垫块

python scripts/spacing_block.py <height_mm> [width_mm] [depth_mm] [output.stl]
python scripts/spacing_block.py <height_mm> [width_mm] [depth_mm] [output.stl]

Set of multiple heights

多高度套装

python scripts/spacing_block.py set <h1>,<h2>,<h3> [output.stl]

**Examples**:
```bash
python scripts/spacing_block.py 10 50 30 spacer_10mm.stl
python scripts/spacing_block.py set 5,10,15,20 spacer_set.stl
Features:
  • Embossed dimension labels
  • Finger relief cutouts for easy pickup
  • Orientation markers
  • Can generate matched sets
python scripts/spacing_block.py set <h1>,<h2>,<h3> [output.stl]

**示例**:
```bash
python scripts/spacing_block.py 10 50 30 spacer_10mm.stl
python scripts/spacing_block.py set 5,10,15,20 spacer_set.stl
特性:
  • 压印尺寸标识
  • 带有指扣缺口便于拿取
  • 方向标记
  • 可生成匹配套装

Creating Custom Jigs

创建自定义夹具

For custom jig designs not covered by pre-built scripts, write Python code using CadQuery. Read 
references/cadquery_patterns.md
for common patterns and best practices.
对于预构建脚本未覆盖的自定义夹具设计，可使用CadQuery编写Python代码。常见模式和最佳实践请查看
references/cadquery_patterns.md
。

Workflow for Custom Jigs

自定义夹具工作流程

  1. Understand requirements: Get dimensions, constraints, and functional needs
  2. Check printer limits: Verify design fits within 225×225×265mm build volume
  3. Apply design constraints: Use guidelines from 
    references/printer_specs.md
    :
    • Minimum wall thickness: 2-3mm for structural parts
    • Hole clearances: +0.3-0.5mm for hardware
    • Minimum feature size: 1.0mm
    • Text depth: 0.4-0.6mm
  4. Write CadQuery code: Use patterns from 
    references/cadquery_patterns.md
  5. Export to STL: Use 
    cq.exporters.export(part, "filename.stl")
  6. Save to outputs: Move STL file to 
    /mnt/user-data/outputs/
    for user access
  1. 明确需求: 获取尺寸、限制条件和功能需求
  2. 检查打印机限制: 确认设计尺寸符合225×225×265mm的打印范围
  3. 应用设计约束: 遵循
    references/printer_specs.md
    中的指南：
    • 最小壁厚：结构部件为2-3mm
    • 孔位间隙：硬件安装孔需放大0.3-0.5mm
    • 最小特征尺寸：1.0mm
    • 文字深度：0.4-0.6mm
  4. 编写CadQuery代码: 参考
    references/cadquery_patterns.md
    中的模式
  5. 导出为STL: 使用
    cq.exporters.export(part, "filename.stl")
  6. 保存至输出目录: 将STL文件移动到
    /mnt/user-data/outputs/
    以便用户获取

Example: Custom Router Template

示例：自定义修边机模板

python
import cadquery as cq

def create_router_template(length, width, inset, guide_height):
    """Create router template with guide bushings."""
    
    # Base plate
    base = (
        cq.Workplane("XY")
        .rect(length, width)
        .extrude(6)
    )
    
    # Cut out center area
    base = (
        base.faces(">Z")
        .workplane()
        .rect(length - 2 * inset, width - 2 * inset)
        .cutThruAll()
    )
    
    # Add guide walls
    walls = (
        cq.Workplane("XY")
        .workplane(offset=6)
        .rect(length, width)
        .rect(length - 2 * inset, width - 2 * inset)
        .extrude(guide_height)
    )
    
    result = base.union(walls)
    
    # Add mounting holes (corners)
    for x in [-length/2 + 15, length/2 - 15]:
        for y in [-width/2 + 15, width/2 - 15]:
            result = (
                result.faces(">Z")
                .workplane()
                .center(x, y)
                .circle(2.5)  # M5 clearance
                .cutThruAll()
            )
    
    return result
python
import cadquery as cq

def create_router_template(length, width, inset, guide_height):
    """Create router template with guide bushings."""
    
    # Base plate
    base = (
        cq.Workplane("XY")
        .rect(length, width)
        .extrude(6)
    )
    
    # Cut out center area
    base = (
        base.faces(">Z")
        .workplane()
        .rect(length - 2 * inset, width - 2 * inset)
        .cutThruAll()
    )
    
    # Add guide walls
    walls = (
        cq.Workplane("XY")
        .workplane(offset=6)
        .rect(length, width)
        .rect(length - 2 * inset, width - 2 * inset)
        .extrude(guide_height)
    )
    
    result = base.union(walls)
    
    # Add mounting holes (corners)
    for x in [-length/2 + 15, length/2 - 15]:
        for y in [-width/2 + 15, width/2 - 15]:
            result = (
                result.faces(">Z")
                .workplane()
                .center(x, y)
                .circle(2.5)  # M5 clearance
                .cutThruAll()
            )
    
    return result

Generate and export

Generate and export

template = create_router_template(200, 150, 30, 8) cq.exporters.export(template, "router_template.stl")
undefined
template = create_router_template(200, 150, 30, 8) cq.exporters.export(template, "router_template.stl")
undefined

Common Jig Types and Approaches

常见夹具类型及实现方法

Lampshade Jigs

灯罩夹具

  • Circle cutting: Use 
    circle_cutting_jig.py
    for ring frames
  • Angle guides: Use 
    angle_wedge.py
    for tapered shade angles
  • Spacing: Use 
    spacing_block.py
    for consistent rib spacing
  • 圆形切割: 使用
    circle_cutting_jig.py
    制作环形框架
  • 角度导向: 使用
    angle_wedge.py
    处理锥形灯罩角度
  • 间隙定位: 使用
    spacing_block.py
    保证肋条间距一致

Router Jigs

修边机夹具

  • Edge guides: Rectangular frame with adjustable fence
  • Template guides: Match standard template bushing sizes (16mm OD common)
  • Bit clearance: 7-8mm slots for 1/4" shanks, 13-14mm for 1/2"
  • 边缘导向器: 带可调挡板的矩形框架
  • 模板导向器: 匹配标准模板衬套尺寸（常见外径16mm）
  • 刀头避让: 1/4"刀柄需7-8mm开槽，1/2"刀柄需13-14mm开槽

Assembly Jigs

组装夹具

  • Right angle corners: 90° blocks with reference edges
  • Spacing sets: Multiple blocks for consistent gaps
  • Alignment pins: 6mm diameter pins, 10mm height standard
  • 直角定位: 带参考边缘的90°垫块
  • 间隙套装: 多规格垫块保证间隙一致
  • 对齐销: 标准6mm直径，10mm高度

Clamping Aids

夹紧辅助工具

  • Cauls: Flat plates with finger reliefs
  • Pressure distributors: Curved or stepped surfaces
  • Clamp blocks: Sacrificial blocks with protective surfaces
  • 压块: 带指扣缺口的平板
  • 压力分配器: 曲面或阶梯状表面
  • 夹块: 带保护表面的牺牲垫块

Design Best Practices

设计最佳实践

Structural Integrity

结构完整性

  • Use 3-4 perimeter walls for strength
  • Add chamfers/fillets (1-2mm) to reduce stress concentrations
  • Orient layer lines perpendicular to primary load direction
  • Minimum 5mm base thickness for flatness
  • 使用3-4层外围壁提升强度
  • 添加1-2mm倒角/圆角减少应力集中
  • 使层线方向与主要受力方向垂直
  • 底座最小厚度5mm以保证平整度

Printability

可打印性

  • Keep overhangs under 45° to avoid supports
  • Add 0.2mm draft angle for parts that nest
  • Avoid unsupported bridges over 30mm
  • Orient largest flat surface on print bed
  • 悬垂角度控制在45°以下以避免使用支撑
  • 嵌套零件需添加0.2mm拔模角
  • 避免跨度超过30mm的无支撑桥接
  • 将最大平面朝向打印床

Woodworking Functionality

木工功能性

  • Smooth reference surfaces (no text or features on work contact areas)
  • Add visual alignment marks (notches, text, contrasting surfaces)
  • Include finger reliefs on small parts for easy handling
  • Consider clamping access (25mm+ clearance)
  • 参考表面需光滑（工作接触区域不得有文字或特征）
  • 添加视觉对齐标记（缺口、文字、对比表面）
  • 小型零件添加指扣缺口便于操作
  • 预留至少25mm的夹紧操作空间

Hardware Integration

硬件集成

Common hole sizes (add 0.3-0.5mm clearance):
  • M3: 3.3mm hole
  • M4: 4.3mm hole
  • M5: 5.3mm hole
  • #8 wood screw: 4.5mm hole
  • 1/4"-20 bolt: 6.6mm hole
常见孔位尺寸（需增加0.3-0.5mm间隙）:
  • M3: 3.3mm孔
  • M4: 4.3mm孔
  • M5: 5.3mm孔
  • #8木螺丝: 4.5mm孔
  • 1/4"-20螺栓: 6.6mm孔

File Organization

文件组织规范

When generating STL files:
  1. Work in 
    /home/claude/
    during development
  2. Test scripts by running them to verify output
  3. Copy final STLs to 
    /mnt/user-data/outputs/
    before presenting to user
  4. Name files descriptively: Include key dimensions or purpose
    • Good: 
      lampshade_jig_300mm_OD.stl
    • Good: 
      wedge_22.5_degrees.stl
    • Poor: 
      jig1.stl
生成STL文件时需遵循：
  1. 开发阶段在
    /home/claude/
    目录下工作
  2. 测试脚本运行以验证输出结果
  3. 最终STL文件需复制到
    /mnt/user-data/outputs/
    目录后再交付给用户
  4. 文件命名需清晰: 包含关键尺寸或用途
    • 规范示例: 
      lampshade_jig_300mm_OD.stl
    • 规范示例: 
      wedge_22.5_degrees.stl
    • 不规范示例: 
      jig1.stl

CadQuery Quick Reference

CadQuery速查指南

For detailed patterns and examples, read 
references/cadquery_patterns.md
.
Basic structure:
python
import cadquery as cq
详细模式和示例请查看
references/cadquery_patterns.md
。
基础结构:
python
import cadquery as cq

Create base

Create base

part = cq.Workplane("XY").box(50, 30, 10)
part = cq.Workplane("XY").box(50, 30, 10)

Add features on top

Add features on top

part = ( part.faces(">Z") .workplane() .circle(5) .cutThruAll() )
part = ( part.faces(">Z") .workplane() .circle(5) .cutThruAll() )

Export

Export

cq.exporters.export(part, "output.stl")

**Essential methods**:
- `.box(w, d, h)` - rectangular solid
- `.circle(r)` - circle sketch
- `.rect(w, h)` - rectangle sketch  
- `.extrude(height)` - extrude 2D to 3D
- `.cutThruAll()` - cut through entire part
- `.fillet(radius)` - round edges
- `.chamfer(distance)` - bevel edges
- `.translate((x, y, z))` - move part
- `.rotate((cx,cy,cz), (ax,ay,az), angle)` - rotate around axis
cq.exporters.export(part, "output.stl")

**核心方法**:
- `.box(w, d, h)` - 长方体
- `.circle(r)` - 圆形草图
- `.rect(w, h)` - 矩形草图  
- `.extrude(height)` - 将2D草图拉伸为3D模型
- `.cutThruAll()` - 贯穿切割整个零件
- `.fillet(radius)` - 倒圆角
- `.chamfer(distance)` - 倒斜角
- `.translate((x, y, z))` - 移动零件
- `.rotate((cx,cy,cz), (ax,ay,az), angle)` - 绕轴旋转

Troubleshooting

故障排除

"Module 'cadquery' not found"

"Module 'cadquery' not found"

bash
pip install --break-system-packages cadquery
bash
pip install --break-system-packages cadquery

STL appears hollow in slicer

STL在切片软件中显示为空心

  • This is normal - slicers add infill during slicing
  • The generated STL is a shell (surface model)
  • 这是正常现象：切片软件会在切片过程中添加填充
  • 生成的STL是外壳（表面模型）

Features too small to print

特征尺寸过小无法打印

  • Check minimum feature size: 1.0mm
  • Increase wall thickness to at least 2-3mm
  • Verify hole diameters are >= 2mm
  • 检查最小特征尺寸：1.0mm
  • 将壁厚增加至至少2-3mm
  • 确认孔直径≥2mm

Part doesn't fit on print bed

零件无法放入打印床

  • Check dimensions against 220×220mm effective area
  • Consider splitting large jigs into sections
  • Rotate part to minimize footprint
  • 检查尺寸是否符合220×220mm有效打印区域
  • 考虑将大型夹具拆分为多个部件
  • 旋转零件以减小占地面积

When to Read Reference Files

何时查阅参考文件

  • Always read 
    references/printer_specs.md
    when starting a new jig design
  • Read 
    references/cadquery_patterns.md
    when writing custom CadQuery code
  • Refer to examples in pattern files for complex geometries
  • 开始新夹具设计时，务必查看
    references/printer_specs.md
  • 编写自定义CadQuery代码时，查看
    references/cadquery_patterns.md
  • 处理复杂几何形状时，参考模式文件中的示例

Output Format

输出格式

After generating STL file(s), always:
  1. Move final STLs to 
    /mnt/user-data/outputs/
  2. Provide download link: 
    [View your file](computer:///mnt/user-data/outputs/filename.stl)
  3. Include brief summary: dimensions, purpose, estimated print time
  4. Suggest print settings if relevant (infill %, supports, orientation)
生成STL文件后，请务必执行以下步骤：
  1. 将最终STL文件移动到
    /mnt/user-data/outputs/
  2. 提供下载链接: 
    [View your file](computer:///mnt/user-data/outputs/filename.stl)
  3. 包含简要说明：尺寸、用途、预计打印时间
  4. 如有必要，建议打印设置（填充率、支撑、摆放方向）