파이썬 API : 형상 생성 및 조작 - Part Design 워크벤치

FreeCAD에서 대다수 사용자가 GUI를 사용할 때는 Part Design(파트 디자인) 워크벤치를 중심으로 작업하지만, 내부적으로 Python 스크립트를 사용해 프로그래밍 방식으로 형상을 생성하고 조작할 때는 'Part(파트)' 모듈을 기본 베이스로 사용합니다. Part Design 역시 내부적으로는 Part 모듈의 지오메트리 데이터를 다루기 때문입니다.

FreeCAD를 처음 접할 때 가장 헷갈리는 부분 중 하나가 바로 Part(파트) 워크벤치와 Part Design(파트 디자인) 워크벤치의 차이점입니다. 이름은 비슷하지만, 형상을 만들어가는 철학과 접근 방식(매커니즘)이 완전히 다릅니다.

---

1. Part 워크벤치 와 Part Design 워크벤치 핵심 철학의 차이

🧱 Part 워크벤치: CSG (Constructive Solid Geometry) 방식

Part 워크벤치는 "기성품 블록들을 조합하고 깎아내는 방식"입니다. 큐브(상자), 실린더(원기둥), 구체 같은 기본 3D 도형들을 먼저 생성한 뒤, 이들을 서로 합치거나(Union), 빼거나(Cut), 교차(Intersection)시키는 부울 연산(Boolean Operation)을 통해 최종 형상을 만듭니다.

특징: 각 도형이 독립적인 객체로 존재하며, 이를 조합해 나가는 거대한 '조립 트리' 구조를 가집니다. 스케치 없이도 3D 도형만으로 빠르게 모델링할 수 있습니다.

 

📐 Part Design 워크벤치: 피처 기반(Feature-based) 방식

Part Design 워크벤치는 현대 상용 CAD(Soliworks, CATIA 등)와 같은 "스케치 기반의 누적 수정 방식"입니다. 하나의 중심 몸체(Body)를 만들고, 2D 스케치를 그린 뒤, 이를 돌출(Pad)시키거나 깎아내고(Pocket), 구멍을 뚫는(Hole) 등의 '피처(Feature, 특징 이력)'를 차곡차곡 쌓아 올립니다.

특징: 히스토리(작업 이력) 기반입니다. 트리 구조에서 상위 피처(예: 첫 번째 스케치 수치)를 수정하면, 그 아래에 쌓인 모든 작업이 자동으로 재계산되면서 형상이 변합니다. 기계 부품이나 정밀 정량 설계에 절대적으로 유리합니다.

 

2. 데이터 구조와 트리(Tree)의 차이

구분	Part 워크벤치	Part Design 워크벤치
기본 컨테이너	없음 (도형 개별 존재	Body (바디) 라는 필수 컨테이너 안에 귀속됨
작업 형태	부울 연산으로 묶인 복합 트리	위에서 아래로 순차적으로 적용되는 이력 트리
최종 결과물	Part::Feature	PartDesign::Body (최종 피처만 표출)

 

Part에서는 상자와 원기둥을 빼면 트리 기하 구조에 Cut (Box - Cylinder) 형태로 두 도형이 모두 살아있어 각각 제어할 수 있습니다. Part Design에서는 Body 안에서 스케치를 하고 패드를 한 뒤 포켓을 뚫으면, 트리의 최하단 결과물만 활성화되고 이전 단계들은 내부 히스토리로 숨겨집니다

 

3. Python 스크립트 관점에서의 차이

프로그래밍(Python API)으로 넘어가면 이 둘의 관계가 더 명확해집니다. Part는 기초 생명체고, Part Design은 고등 생명체라고 볼 수 있습니다.

1) Part 모듈 (import Part)

Python에서 Part 모듈은 FreeCAD의 기하학적 엔진(OpenCASCADE) 그 자체를 다룹니다.

스크립트로 점, 선, 면을 직접 제어하고, 위에서 설명한 makeBox(), makeCipher() 같은 로우 레벨(Low-level) 데이터를 생성합니다. 파라메트릭(연동형) 이력을 관리하기보다는, 메모리에 순수한 3D 토폴로지 형상 자체를 물리적으로 계산해 낼 때 씁니다.

 

2) Part Design 모듈 (import PartDesign)

Python에서 PartDesign은 Part 모듈이 만들어내는 지오메트리를 '스케치와 피처 이력'이라는 시스템으로 편리하게 통제하는 상위 래퍼(Wrapper) 역할을 합니다.

스크립트로 Part Design을 제어하려면 먼저 ActiveDocument.addObject('PartDesign::Body', 'Body')로 바디를 만들고, 그 안에 스케치 객체를 추가한 뒤, Pad 피처를 추가하는 등 GUI에서 마우스로 누르던 행동을 그대로 코드로 모사해야 합니다.

 

4. 언제 무엇을 써야 할까

 

1) Part 워크벤치를 쓸 때:

• 아주 간단한 3D 도형 조합(예: 3D 프린터용 단순 가이드, 브래킷 확장).
• 외부에서 가져온 STEP/IGES 파일(기록이 없는 통짜 파일)을 자르거나 합치는 조작을 할 때.
• Python 스크립트 코딩으로 완전히 자동화된 수학적 기하 형상을 생성할 때.

2) Part Design 워크벤치를 쓸 때:

• 치수 관리가 엄격해야 하는 실제 기계 부품 설계.
• 설계 과정에서 치수나 모양이 자주 바뀔 가능성이 있는 파라메트릭 모델링.
• 일반적인 대다수의 3D 모델링 작업 중심.

 

---

스케치 기반 연동 방식(Sketch-based Parametric Modeling)은 현대 3D CAD(FreeCAD의 Part Design, SolidWorks, Fusion360 등)의 핵심 모델링 메커니즘입니다.

이를 Python 스크립트로 구현한다는 것은 GUI에서 "1) 스케치 생성 -> 2) 제약조건(치수) 부여 -> 3) 패드(돌출) 같은 피처 적용" 과정을 코드로 그대로 실행하는 것을 의미합니다.

수학적 좌표를 직접 계산해 선을 긋는 앞선 'Part 모듈' 방식과 달리, 치수 변수만 바꾸면 전체 형상이 자동으로 업데이트되는 강력한 자동화를 구현할 수 있습니다. FreeCAD Python 스크립트로 이를 구현하는 프로세스를 단계별로 설명합니다.

---

스케치 기반 연동 방식 구현 5단계 흐름

Python으로 이 방식을 구현할 때는 PartDesign 모듈과 Sketcher 모듈을 함께 사용합니다.

1단계: 바디(Body) 생성

Part Design 구조의 가장 기본 컨테이너인 Body를 만듭니다. 모든 스케치와 피처는 이 바디 안에 귀속되어야 합니다.

import FreeCAD as App
import PartDesign
import Sketcher

# 활성 문서 가져오기
doc = App.ActiveDocument

# 1. PartDesign 바디 생성 및 문서에 추가
body = doc.addObject('PartDesign::Body', 'MyBody')
doc.recompute()

 

2단계: 스케치(Sketch) 생성 및 평면 설정

어느 평면(예: XY 평면)에 그림을 그릴지 지정하여 스케치 객체를 만듭니다

# 2. 바디 내부에 스케치 객체 생성
sketch = doc.addObject('Sketcher::SketchObject', 'MySketch')

# 스케치를 바디의 하위 요소로 등록
body.addObject(sketch)

# XY 평면(기본 가상 평면)에 스케치 배치하기
sketch.Support = (doc.Origin.OriginFeatures[0], ['']) # 0번이 보통 XY_Plane입니다
sketch.MapMode = 'FlatFace'
doc.recompute()

 

3단계: 스케치 내부 기하 구조 및 제약조건(치수) 추가

이 부분이 핵심입니다. 선을 그리고, 그 선에 "가로 길이는 50mm"라는 치수(제약조건)를 연동합니다.

# 3. 스케치에 선(Geometry) 추가 (시작 X,Y, 끝 X,Y)
# 아래 명령은 선을 추가하고 그 선의 고유 인덱스를 반환합니다.
line_index = sketch.addGeometry(Part.LineSegment(App.Vector(0,0,0), App.Vector(30,0,0)), False)

# 4. 수평 제약조건 부여 (선이 삐뚤어지지 않게 고정)
sketch.addConstraint(Sketcher.Constraint('Horizontal', line_index))

# 5. [연동의 핵심] 치수 제약조건 부여 (가로 길이를 50mm로 강제 제한)
# 'DistanceX' 제약조건: line_index 선의 시작점(1)과 끝점(2) 사이의 X축 거리를 50으로 설정
sketch.addConstraint(Sketcher.Constraint('DistanceX', line_index, 1, line_index, 2, 50.0))
doc.recompute()

 

4단계: 피처(Feature) 연동 - 돌출(Pad)하기

완성된 스케치를 기반으로 두께를 주어 3D로 만듭니다. 이 피처는 스케치 데이터와 '연동'되어 있습니다.

# 6. 돌출(Pad) 피처 생성 및 바디에 추가
pad = doc.addObject('PartDesign::Pad', 'MyPad')
body.addObject(pad)

# Pad의 부모(기반) 데이터를 방금 만든 스케치로 지정
pad.Profile = sketch
pad.Length = 20.0 # 돌출 높이 20mm
doc.recompute()

 

5단계: 수치 변경 및 자동 연동 재계산 (Parametric)

스케치 기반 연동 방식의 진가가 발휘되는 단계입니다. 처음에 설정한 스케치의 치수나 Pad의 높이 값만 바꾸고 재계산을 누르면 모델 전체가 알아서 변합니다.

# 프로그램 실행 중이나 외부 입력에 의해 수치를 바꾸고 싶을 때:
# 스케치의 1번째 제약조건(치수) 값을 50mm에서 120mm로 변경
sketch.setDatum(1, 120.0) 

# Pad의 돌출 높이도 20mm에서 45mm로 변경
pad.Length = 45.0

# 문서 재계산 실행 -> 3D 모델이 실시간으로 변경됨!
doc.recompute()

 

💡 스케치 기반 연동 방식 코딩의 장단점

 

1. 장점:

• 설계 변경에 유연함: 제품의 기본 외곽 사이즈 변수(Width, Height)만 상단에 선언해 두면, 하위의 구멍 위치, 필렛 크기 등이 수학적으로 연동되어 스크립트 한 줄로 수백 개의 형상 버전을 찍어낼 수 있습니다.
• GUI와의 호환성: 스크립트로 생성한 파일이지만 사용자가 FreeCAD GUI로 열었을 때 일반적인 '스케치 수정'을 통해 모델을 편집할 수 있습니다.

2. 단점 (Part 모듈 방식 대비):

• 토폴로지 명명 문제(Topological Naming Problem): 코드로 스케치를 깎아내거나 수정하다가 면(Face)이나 선(Edge)의 번호(예: Face1)가 바뀌면 뒤이어 오는 피처들이 길을 잃고 에러가 날 확률이 높습니다. 코드가 상대적으로 까다롭고 엄격합니다.

 

 

만약 완전히 자동화된 파라메트릭 설계를 코딩하고 싶다면, FreeCAD 내부의 Spreadsheet(스프레드시트) 워크벤치를 매개체로 쓰는 것이 가장 좋습니다. Python 스크립트로는 Spreadsheet 객체의 셀 값(A1 = 50, B1 = 20)만 변경하게 만들고, FreeCAD 내부 스케치 치수들은 그 스프레드시트 셀을 참조(Spreadsheet.Width)하도록 GUI에서 짜놓는 방식입니다. 이 방식이 코드가 가장 깔끔하고 에러가 적습니다. 아래 그림 참고

 

참고자료

 

Scripting and macros

 

by korealionkk@gmail.com