FreeCAD 헤드리스 모드 사용해보기

■ FreeCAD 헤드리스(Headless) 모드

FreeCAD 프로그램을 직접 실행하지 않고 파이썬으로 3D 모델을 제어하거나 파일을 생성하려면 헤드리스(Headless) 모드와 freecadcmd 명령어(또는 FreeCAD 파이썬 라이브러리)를 사용해야 합니다.

FreeCAD의 헤드리스 모드(freecadcmd)를 사용하여 새로운 문서를 생성 하는 파이썬 코드를 만들어 봅니다. 파이썬 자동화의 가장 첫 단계는 설계자가 "FreeCAD를 실행후, 새로운 문서 파일을 생성후 지정한 경로에 저장하는 과정"을 코드로 완벽하게 똑같이 흉내 내는 것입니다.

●  새로운 문서 만들기 파이썬 코드

import sys
import os

# FreeCAD 1.1 경로 설정 (VS Code 외부 실행용)
FREECAD_PATH = r"C:\Program Files\FreeCAD 1.1\bin"
if FREECAD_PATH not in sys.path:
    sys.path.append(FREECAD_PATH)

import FreeCAD as App

def create_empty_freecad_document():
    # 1. 새로운 FreeCAD 문서 생성
    doc_name = "EmptyDoc"
    doc = App.newDocument(doc_name)
    print(f"[*] 새로운 빈 문서 생성 완료: {doc_name}")

    # 2. 저장 경로 설정 및 파일 저장 (.FCStd 파일)
    output_filename = "empty_result.FCStd"
    current_directory = os.getcwd()
    full_save_path = os.path.join(current_directory, output_filename)
    
    doc.saveAs(full_save_path)
    print(f"[+] 빈 문서 저장 성공: {full_save_path}")

    # 3. 메모리 해제를 위해 문서 닫기
    App.closeDocument(doc_name)

if __name__ == "__main__":
    create_empty_freecad_document()

 

● 새로운 문서 만들기 파이썬 코드 설명

1단계:  설계 프로그램(FreeCAD)의 "엔진"을 파이썬으로 불러오기

import sys
import os

FREECAD_PATH = r"C:\Program Files\FreeCAD 1.1\bin"
if FREECAD_PATH not in sys.path:
    sys.path.append(FREECAD_PATH)

import FreeCAD as App

1. import sys

Python 자체가 제공하는 sys 모듈을 가져옵니다. 여기서는 특히 다음 기능을 사용합니다.

sys.path

sys.path는 Python이 import할 모듈을 찾을 때 검색하는 폴더 목록입니다.

2. import os

import os

운영체제의 파일/폴더를 다루기 위한 os 모듈을 가져옵니다.

3. FreeCAD 설치 경로 지정

FREECAD_PATH = r"C:\Program Files\FreeCAD 1.1\bin"

FreeCAD가 설치된 bin 폴더의 위치를 변수에 저장합니다. 여기서 중요한 것이 "r"입니다. 앞의 "r"은 raw string이라는 의미입니다. Windows 경로에는 "\"가 많이 사용되는데 Python에서는 "\"가 특수문자로 해석될 수 있습니다. 그래서 Windows 경로를 표현할 때: "r"을 붙이는 것이 편리합니다. "FREECAD_PATH"는 변수 입니다.

4. Python의 모듈 검색 경로에 FreeCAD 추가

if FREECAD_PATH not in sys.path:     sys.path.append(FREECAD_PATH)

만일 "sys.path"에 FreeCAD 모듈이 모여 있는 폴더를 못 찾으면, "sys.path.append " "FREECAD_PATH"변수의 값을 추가 합니다. 즉, Python의 검색 경로에 추가하는 것입니다

5. FreeCAD Python 모듈 가져오기

import FreeCAD as App

FreeCAD Python API를 가져옵니다. 그리고 이름을 App으로 줄여서 사용합니다. 사용자 환경의 FreeCAD 1.1에서는 보통 Python에서 사용할 수 있도록 컴파일된 FreeCAD 모듈을 찾습니다. FreeCAD.pyd 같은 컴파일된 Python 확장 모듈입니다.

FreeCAD.newDocument()

대신

App.newDocument()

가 사용됩니다.

"설계실 책상(VS Code)에서 작업 중인데, FreeCAD라는 전문 장비가 다른 창고에 있으니 "거기 통로(sys.path) 연결 좀 해줘!"라고 길을 터주는 작업입니다. 이 연결이 끝나면 파이썬 코드가 FreeCAD의 기능을 마음껏 부릴 수 있게 됩니다."

※ FreeCAD 헤드리스(Headless) 모드의 전체 흐름

일반 Python 실행       │       ▼ sys.path 확인       │       ▼ C:\Program Files\FreeCAD 1.1\bin       │       │ sys.path에 추가       ▼ Python이 FreeCAD 모듈 검색       │       ▼ import FreeCAD as App       │       ▼ FreeCAD Python API 사용       │       ├── App.newDocument()       ├── App.ActiveDocument       ├── App.openDocument()       ├── App.closeDocument()       └── App.saveAs()

---

2단계:  마우스 클릭 대신 명령어로 새 문서 생성하기

doc_name = "EmptyDoc"
doc = App.newDocument(doc_name)

FreeCAD Python API를 이용해서 새로운 FreeCAD 문서(Document)를 메모리에 생성하는 코드 입니다.

1.문자열 저장

doc_name = "EmptyDoc"

Python 변수 doc_name에 문자열 "EmptyDoc"을 저장합니다. EmptyDoc은 새로 만들 FreeCAD Document의 이름으로 사용하기 위한 값입니다.

2. 새로운 FreeCAD 문서를 생성

doc = App.newDocument(doc_name)

실제로 FreeCAD 문서를 생성합니다. "App"는 FreeCAD 모듈을 의미합니다. App.newDocument()는 FreeCAD에게 "새로운 Document를 하나 만들어줘." 라고 요청하는 것입니다. " doc_name "을 전달 했으므로 "Document 이름은 EmptyDoc으로 만들어줘."

다음과 같이 출력할 수 있습니다.

출력	결과
print(doc) print(doc.Name) print(doc.Label)	<Document object> EmptyDoc EmptyDoc

 

• doc → Document 객체
• doc.Name → 내부 이름
• doc.Label → 화면에 표시되는 이름

3단계:  내가 원하는 이름과 경로로 파일 저장하기

FreeCAD Document를 실제 .FCStd 파일로 저장한 후, FreeCAD에서 해당 Document를 닫는 과정입니다.

output_filename = "empty_result.FCStd"
current_directory = os.getcwd()
full_save_path = os.path.join(current_directory, output_filename)

doc.saveAs(full_save_path)
App.closeDocument(doc_name)

 

1. 저장할 파일 이름 지정

output_filename = "empty_result.FCStd"

저장할 파일 이름을 변수에 넣습니다. 파일 이름 = empty_result.FCStd, 아직 저장 위치는 지정하지 않았습니다.

2. 현재 작업 폴더 확인

current_directory = os.getcwd()

os.getcwd()는 Python이 현재 작업하고 있는 현재 디렉터리(Current Working Directory) 를 반환합니다.
아래 코드로 현재의 디렉토리를 확인 할 수 있습니다

print(current_directory)

예시)  current_directory  : G:\00PythonProjects\freecad_py311

3. 파일의 전체 경로 만들기

full_save_path = os.path.join(current_directory, output_filename)

"full_save_path" 에는 실제로 저장할 전체 파일 경로가 들어갑니다.

4. FreeCAD Document 저장

doc.saveAs(full_save_path)

이 부분에서 실제로 .FCStd 파일이 만들어집니다. 위 코드를 통해 디스크에 저장하는 것입니다.

5. Document 닫기

App.closeDocument(doc_name)

저장이 끝났으므로 FreeCAD에서 해당 Document를 닫습니다. FreeCAD에 열려 있는 EmptyDoc Document를 닫아라.

 

프로그렘 실행결과

---

by korealionkk@gmail.com