마우스 대신 Python 코드로 기구물을 설계하다: build123d 파라메트릭 CAD와 Klipper 고속 3D 프린팅 워크플로우
사진 스튜디오와 암실, 현장 인테리어 설비를 운영하다 보면 기성품으로 대체할 수 없는 비규격 기구물이 상시 필요합니다. 천장 조명 브래킷부터 대구경 광학 필터 어댑터, 뷰카메라 렌즈 보드, 내화학성 교반 지그까지 요구 치수가 매번 달라집니다.
초기에는 마우스 기반 GUI CAD와 순정 FDM 프린터를 썼으나, 치수 1개만 바꿔도 하위 필렛(Fillet)과 참조 트리가 깨지고 대형 갠트리 진동으로 오차가 흔들렸습니다. 이 글에서는 Klipper 기구학 개조 & 파라메트릭 스튜디오 CAD 프로젝트를 통해 Python 코드(build123d · FreeCAD 매크로) 형상 버전 관리와 MGN12H · ADXL345 기반 Klipper 진동 제어로 ±0.05mm 정밀도와 고속 출력을 확보한 파이프라인을 정리합니다.
1. 마우스 클릭 CAD의 한계(TNP)와 Python 코드 전환 배경
스튜디오 바텐 파이프(Ø25mm, Ø32mm, Ø38mm) 브래킷이나 광학 마운트는 체결 볼트가 M4에서 M5로 바뀌거나 1/4-20 UNC 인서트 사양으로 수시로 파생됩니다. 이때 GUI 히스토리 기반 CAD의 치명적 병목은 **위상 명명 문제(Topological Naming Problem, TNP)**입니다. 마우스로 특정 면(Face_6)을 클릭해 홀과 필렛을 준 뒤 상단 스케치 두께를 바꾸면, 커널이 면 번호를 재할당해 하위 트리가 붕괴합니다.
초기에는 FreeCAD 매크로로 반복 치수를 제어했고, 이후 동일한 OpenCascade(OCCT) BREP 커널 위에서 선언적 문법을 제공하는 **build123d**로 통합했습니다. 메쉬 기반 OpenSCAD와 달리 정밀 필렛과 CNC 발주용 .step 추출을 Python 코드로 완결할 수 있습니다.
| 비교 항목 | GUI 히스토리 기반 CAD (마우스 클릭) | Python build123d 코드 기반 CAD |
|---|---|---|
| 형상 참조 방식 | 클릭 시점의 내부 면 번호(Face_6) 고정 참조 | 기하 조건자(faces().sort_by(Axis.Z)[-1]) 동적 탐색 |
| 치수 변경 안정성 | 스케치 수정 시 필렛·참조 트리 연쇄 붕괴(TNP) | 위상 조건으로 재탐색해 치수·홀 변경 시에도 무결성 유지 |
| 다규격 파생 빌드 | 파일 복제 후 수동 편집 및 개별 STL 추출 반복 | 단일 스크립트 실행으로 다규격 .step / .stl 일괄 생성 |
| 열수축·공차 전파 | 스케치마다 오프셋 수동 기입으로 누락 위험 존재 | shrinkage · clearance 변수가 전 피처 수식에 자동 반영 |
| 버전 및 이력 관리 | 바이너리 파일로 세부 치수 변경 비교 불가 | 순수 .py 텍스트로 Git diff 기반 0.05mm 공차 추적 |
핵심 포인트: 코드 기반 CAD의 본질은 불안정한 면 번호 대신
'Z축 최상단 평면과 만나는 외곽 수직 모서리'처럼 기하 의도(Design Intent)를 코드로 선언하는 데 있습니다. 치수가 바뀌어도 트리가 깨지지 않으며 이력이 Git 커밋으로 보존됩니다.
2. 변수 테이블 기반 STEP·STL 일괄 생성 패턴
기하 모델링 로직과 **규격·공차 변수 테이블(dataclass)**을 분리해 파이프 직경, M4/M5 볼트, 히트셋 인서트 홀, 수축 계수(shrinkage), 조립 유격(clearance = 0.20)만 입력하면 출력용 솔리드가 즉시 생성됩니다.

2.1. build123d 스튜디오 브래킷 & 광학 마운트 코드
from dataclasses import dataclass
from pathlib import Path
from build123d import *
@dataclass(frozen=True)
class MountSpec:
name: str
pipe_dia: float # 파이프/경통 외경 (mm)
wall_t: float # 벽 두께 (mm)
height: float # 적층 높이 (mm)
bolt_dia: float # 볼트 규격 (M4=4.0, M5=5.0)
cbore_dia: float # 카운터보어 직경 (mm)
insert_dia: float # 히트셋 인서트 홀 직경 (mm)
insert_depth: float # 인서트 깊이 (mm)
shrinkage: float = 1.004 # 열수축 (PETG=1.004, ASA=1.007)
clearance: float = 0.20 # 끼워맞춤 공차 (mm)
def build_studio_mount(spec: MountSpec) -> Part:
inner_r = (spec.pipe_dia * spec.shrinkage) / 2.0 + spec.clearance
outer_r = inner_r + spec.wall_t
ear_span = outer_r + 14.0
with BuildPart() as part:
with BuildSketch(Plane.XY):
Circle(radius=outer_r)
with Locations((ear_span / 2.0, 0)):
Rectangle(ear_span, 18.0)
Circle(radius=inner_r, mode=Mode.SUBTRACT)
with Locations((ear_span / 2.0, 0)):
Rectangle(ear_span, 2.4, mode=Mode.SUBTRACT)
extrude(amount=spec.height)
with Locations(Plane.XZ.offset(-9.0)):
with Locations((outer_r + 6.5, spec.height / 2.0)):
CounterBoreHole(
radius=(spec.bolt_dia + spec.clearance) / 2.0,
counter_bore_radius=(spec.cbore_dia + spec.clearance) / 2.0,
counter_bore_depth=4.2,
depth=18.0,
)
top_face = part.faces().sort_by(Axis.Z)[-1]
with Locations(top_face):
with PolarLocations(radius=(inner_r + outer_r) / 2.0, count=2, start_angle=120, angular_range=120):
Hole(radius=(spec.insert_dia * spec.shrinkage) / 2.0, depth=spec.insert_depth)
outer_edges = (
part.edges()
.filter_by(Axis.Z)
.filter_by_position(Axis.X, minimum=outer_r - 1.0, maximum=ear_span + 2.0)
)
fillet(outer_edges, radius=1.8)
return part.part
PRESETS = [
MountSpec("batten_32mm_m5_petg", 32.0, 6.0, 24.0, 5.0, 9.0, 5.6, 6.5, 1.004, 0.20),
MountSpec("optic_rod_25mm_m4_asa", 25.0, 5.5, 20.0, 4.0, 7.5, 5.6, 6.5, 1.007, 0.20),
]
out_dir = Path("./dist/studio-mounts")
out_dir.mkdir(parents=True, exist_ok=True)
for spec in PRESETS:
solid = build_studio_mount(spec)
export_step(solid, out_dir / f"{spec.name}.step")
export_stl(solid, out_dir / f"{spec.name}.stl", tolerance=0.01, angular_tolerance=0.05)
2.2. 소재·노즐별 끼워맞춤 공차(Clearance) 기준표
0.4mm 노즐(적층 0.2mm) 실측 검증 매트릭스입니다. 발열과 내구성을 위해 실전 파츠는 PETG와 ASA를 주력으로 씁니다.
| 결합 부위 및 목적 | PLA (1.002) | PETG (1.004) | ASA (1.007) | 반영 기준 (0.4mm 노즐) |
|---|---|---|---|---|
| 베어링·핀 압입 (Press Fit) | +0.05 mm | +0.06 mm | +0.08 mm | 가압 조립 무유격 간극 |
| 필터 회전 링 (Sliding Fit) | +0.12 mm | +0.12 mm | +0.15 mm | 무윤활 회전 감쇠 확보 |
| 파이프·볼트 홀 (Standard) | +0.18 mm | +0.20 mm | +0.20 mm | 걸림 없는 표준 clearance |
| M4 히트셋 인서트 홀 내경 | Ø 5.50 mm | Ø 5.60 mm | Ø 5.65 mm | 외경 6.0mm 인서트 열압입 |
| 77mm 광학 나사산 (P=0.75) | 내열 한계 제외 | +0.14 mm 오프셋 | +0.16 mm 오프셋 | 경통 체결용 0.12mm 적층 |
3. 대형 박스 프레임 개조: MGN12H 리니어 레일과 Direct Drive
정밀한 STL도 프린터 기구에 유격이 있으면 무의미합니다. 대구경 파츠 일체형 출력을 위해 **350×350×400mm 박스 프레임 기체(Ender-5 Plus 베이스)**에 3대 기구학 개조를 적용했습니다.
- X/Y축 MGN12H 리니어 레일: 편마모로 홀을 왜곡시키던 순정 POM 롤러를 450mm 고탄소강 MGN12H 리니어 레일로 교체해 고속 이동 중 유격을 0mm 수준으로 잠갔습니다.
- Direct Drive 익스트루더 직결: 800mm 보우덴 튜브를 제거하고 경량 다이렉트 드라이브로 개조해 리트랙션을
6.5mm → 0.6mm로 단축, PETG 실뜨기를 차단했습니다. - 듀얼 Z축 동기화 (
z_tilt_adjust): 독립 스테퍼 제어로 350mm 베드의 좌우 평행도를 출력 전 자동 보정합니다.
4. ADXL345 공진 계측과 Klipper Input Shaper · Pressure Advance
대형 갠트리의 고속 이동 시 고유 진동은 표면에 물결 주름(Ringing)을 남기고 홀 내경을 깎아먹습니다. Klipper 환경에서 툴헤드에 ADXL345 가속도계를 SPI 직결해 10~130Hz 공진을 계측하고, X축(46.2 Hz)에는 선예도가 높은 MZV 필터를, 질량이 큰 Y축(38.4 Hz)에는 감쇠 폭이 넓은 EI 필터를 적용했습니다. 코너 팽창을 막는 PETG 기준 동적 압력 보정치는 **pressure_advance = 0.042**로 도출했습니다.
# Klipper printer.cfg — 기구학 · 공진 제어 · 압출 보정 설정 발췌
[printer]
kinematics: cartesian
max_velocity: 250
max_accel: 4500
square_corner_velocity: 5.0
[adxl345]
cs_pin: rpi:None
spi_bus: spidev0.0
[resonance_tester]
accel_chip: adxl345
probe_points: 175, 175, 30
[input_shaper]
shaper_freq_x: 46.2
shaper_type_x: mzv
shaper_freq_y: 38.4
shaper_type_y: ei
[extruder]
nozzle_diameter: 0.400
filament_diameter: 1.750
pressure_advance: 0.042
pressure_advance_smooth_time: 0.040
[firmware_retraction]
retract_length: 0.60
retract_speed: 35
핵심 포인트: CAD 코드의
clearance = 0.20변수가 일관된 치수로 재현되려면 프린터의 Input Shaper와 Pressure Advance 보정이 선행되어야 합니다. 진동과 코너 팽창이 잡혀야 가속도를1,200에서4,500 mm/s²로 높여도 ±0.05mm 정밀도가 유지됩니다.
5. 현장 배치 성과 및 엔지니어링 요약
파라메트릭 CAD와 Klipper 파이프라인 통합 후 주요 성과는 다음과 같습니다.
- 리드타임 단축 (
1~2주 → 4시간): 뷰카메라 편심 렌즈 보드(ASA 차광 구조), 77mm/82mm 필터 회전 링(0.12mm공차), 비규격 인테리어 브래킷(0.20mm공차)을 당일 설계·출력해 즉시 투입합니다. - 고속·고정밀 단판 출력:
4,500 mm/s²가속도에서 진동을 92% 이상 감쇠시키고 재출력 없이 표준 광학 나사산 및 규격 볼트와 유격 없는 체결을 달성했습니다. - 설계의 코드 자산화: 전 파츠가 Git 내 Python 모듈로 축적되어, CNC 가공 발주 시에도 동일 스크립트에서 무손실
.step원본을 즉시 추출합니다.
