Python] import FreeCAD 선언

■ import FreeCAD 는 무엇인가?

오픈소스 3D CAD 소프트웨어인 FreeCAD의 핵심 기능과 데이터 엔진을 파이썬(Python) 프로그래밍 언어로 불러오는 명령어입니다. 이 한 줄을 실행함으로써 사용자는 마우스를 클릭해 가며 손으로 하던 3D 모델링 작업을 파이썬 코드를 통해 자동화, 제어, 확장할 수 있게 됩니다.

1. FreeCAD 파이썬 API의 시작점

FreeCAD는 내부 엔진이 파이썬과 매우 긴밀하게 결합되어 설계되어 있습니다. 파이썬에서 import FreeCAD를 선언하면 FreeCAD 메인 응용 프로그램(Application) 핵심 모듈에 접근할 수 있게 되며, 다음과 같은 메인 시스템 기능들을 파이썬 코드로 명령할 수 있습니다.

• 새 문서 생성 및 관리: FreeCAD.newDocument()를 통해 새로운 작업 컨테이너(파일)를 만듭니다.
• 3D 오브젝트 및 형상 제어: 점, 선, 면, 벡터(FreeCAD.Vector) 계산 및 각종 3D 객체를 생성하고 수정합니다.
• 재연산(Recompute): 모델의 치수가 바뀌었을 때 구조를 다시 계산하는 FreeCAD.ActiveDocument.recompute() 등의 시스템 명령을 내립니다.

 

2. 주로 어떻게 사용되나?

보통 파이썬 스크립트나 FreeCAD 매크로(Macro)를 작성할 때 가장 첫 줄에 선언됩니다. 전 세계 개발자들과 공식 문서에서는 타이핑의 번거로움을 줄이고 구조를 명확히 하기 위해 as App(Application의 약자)이라는 별명을 붙여 사용하는 것이 표준 관례입니다.

# Python
import FreeCAD as App  # FreeCAD 핵심 엔진 모듈 불러오기

# 새로운 3D 모델링 문서 만들기
doc = App.newDocument("MyProject")

# 3D 공간 상의 좌표(벡터) 정의하기
position = App.Vector(10, 20, 0)

 

3. 화면을 다루는 FreeCADGui와의 차이점

FreeCAD 파이썬 스크립팅에서는 크게 두 가지 메인 모듈을 사용합니다.

• import FreeCAD (주로 as App): 화면에 보이지 않는 백그라운드 데이터, 파일 저장, 수학적 연산, 구조적 객체 생성을 담당합니다.
• import FreeCADGui (주로 as Gui): 사용자의 눈에 보이는 화면(UI), 워크벤치 변경, 3D 뷰포트 시점 조절, 대화상자(알림창) 등을 담당합니다.

---

import FreeCAD as App 1) Import: 모듈 불러오기 2) FreeCAD: 불러올 대상 (외부에서 만든 기능 꾸러미 모듈) 3) as: 별명을 붙여주겠다는 키워드 4) App: 앞으로 내 스크립트 안에서 사용할 FreeCAD 모듈의 별명 일반적인 변수 선언: age = 20 (여기서 20은 데이터 값, age는 변수 이름, 데이터 유형은 int 정수형)

 

---

■ FreeCAD 모듈(App)이 제공하는 "메서드(Method)" 또는 "함수(Function)"

 

# Python
import FreeCAD as App 

# 새로운 3D 모델링 문서 만들기
doc = App.newDocument("MyProject")

newDocument() : 메서드(), 함수(Function)

• 역할: FreeCAD 프로그램 안에서 "새로운 문서(새 파일 프로젝트 바구니)를 만들어라"라고 명령하는 실제 '행동(기능)'입니다.
• 파이썬 문법적 의미: 어떤 모듈이나 객체 뒤에 마침표(.)를 찍고 App.newDocument(...)처럼 사용하는 형식을 메서드(Method)라고 부릅니다.
• App이라는 공구함 속에 들어있는 '새 도면장 개설하기'라는 특수 기능 버튼과 같습니다.

코드 설명 (doc = App.newDocument("MyProject"))

코드 구성 요소	파이썬 문법 기준 명칭	실제 역할 (FreeCAD 기준 비유)
App	모듈 (Module)	FreeCAD의 핵심 기능이 모여 있는 대형 공구함
.	참조 연산자 (Dot Operator)	공구함 '내부'로 접근하는 통로 ("~의")
newDocument	메서드 / 함수 (Method)	"새 문서를 개설하라"는 실제 명령/기능
("MyProject")	인자 / 매개변수 (Argument)	새로 만들 문서의 고유 이름 (옵션 데이터)
doc	변수 (Variable)	생성된 새 문서를 제어하기 위해 쥐고 있는 손잡이

 

코드를 작성하실 때 아래와 같은 계층 흐름으로 개체와 메소드를 호출하게 됩니다.

FreeCAD (App)   └── newDocument() ──> [ Document 객체 생성 ]                           ├── addObject("PartDesign::Body") ──> [ Body 객체 생성 ]                           │                                       └── newObject("Sketcher::SketchObject") ──> [ Sketch 객체 ]                           │                                                                                     ├── addGeometry()                           │                                                                                     └── addConstraint()                           ├── addObject("PartDesign::Pad") ──> [ Pad 객체 생성 ]                           │                                      └── Profile 설정 / Length 설정                           └── recompute() (전체 재연산 및 반영) FreeCADGui (Gui)   ├── activateWorkbench("워크벤치이름")   └── activeDocument().activeView() ──> [ View 객체 ]                                            ├── viewIsometric()                                            └── fitAll() FreeCAD 파이썬 스크립팅은 항상 이 계층 구조를 따라 '문서 열기 ➔ 바디 생성 ➔ 평면에 스케치 그리기 ➔ 구속조건 부여 ➔ 3D 피처 연산 ➔ GUI 화면 정렬 및 리컴퓨트' 순으로 메서드를 체인처럼 연결해 사용하게 됩니다.

 

아래 사이트는 FreeCAD의 핵심(루트) 모듈입니다. FreeCAD 인터프리터에서 "App"으로도 호출할 수 있습니다. 문서와 그 내용(객체)을 조작하는 데 필요한 모든 것이 포함되어 있습니다.

FreeCAD API

 

---