FreeCAD & Python] VScode 사용 하기 #3

■ import FreeCAD as App

import FreeCAD as App을 통해 FreeCAD의 기능 모듈을 가져옵니다. 이 코드는 FreeCAD의 핵심 Python 모듈을 가져오면서, 이름을 App으로 별칭(alias)을 지정하는 것입니다.

import FreeCAD

 

FreeCAD의 기본 기능 모듈을 불러옵니다.
이 모듈에는 문서 관리, 벡터/매트릭스 연산, 객체 생성, 속성 접근 등 FreeCAD의 핵심 API가 들어 있습니다.

as App

불러온 모듈을 App이라는 이름으로 사용하겠다는 뜻입니다.
FreeCAD 스크립트에서는 관례적으로 FreeCAD 대신 App을 많이 씁니다.

 

● doc = App.openDocument("파일경로.fcstd")

이 코드는 기존에 저장된 FreeCAD 파일(.FCStd)을 열고, 그 문서를 doc이라는 변수에 저장하는 것입니다.

• openDocument() : 지정한 경로의 .FCStd 파일을 열어 문서로 불러오는 함수
• "파일경로.fcstd" : 열고 싶은 FreeCAD 파일의 전체 경로 (또는 상대 경로)
• doc = : 열린 문서를 doc 변수에 저장해서 이후에 사용할 수 있게 함

지정한 .FCStd 파일을 열어서 doc이라는 이름으로 문서 객체를 가져온다는 뜻입니다.

 왜 App.openDocument라고 쓸까요? (네임스페이스와 모듈)

앞서 import FreeCAD as App을 통해 FreeCAD 모듈을 불러왔다고 했습니다. 파이썬에는 수많은 함수와 변수가 존재하기 때문에, 이름이 겹치는 것을 방지하기 위해 "소속(이름공간)"을 표시해 줍니다.

• App: "지금부터 내가 사용하는 명령어는 App(FreeCAD) 모듈 안에 들어있는 거야"라는 소속을 뜻합니다.
• . (점): "App 모듈 안에 있는"이라는 접근 연산자입니다.
• openDocument: App 모듈 안에 속해 있는 함수 이름입니다.

즉, 이건 부모-자식 간의 '상속' 관계라기보다는 "도서관(App) 안에서 특정 책(openDocument)을 꺼내 온다"는 개념에 가깝습니다.

openDocument 같은 함수를 App.(모듈 이름) 없이 단독으로(그냥 openDocument()처럼) 사용하는 것은 불가능합니다.

단독으로 사용할 수 없는 이유

1. 파이썬이 함수를 찾지 못함: 파이썬은 기본적으로 컴퓨터 메모리나 현재 실행 중인 코드 안에 openDocument라는 이름의 함수가 직접 정의되어 있는지 찾습니다. 하지만 이 함수는 파이썬 기본 기능이 아니라 FreeCAD 모듈(꾸러미) 안에 들어있는 함수입니다. 따라서 "어디에 있는 함수인지" 소속을 밝혀주지 않으면 파이썬은 이 함수가 뭔지 알 수 없어 에러(NameError)를 발생시킵니다.
2. 이름 충돌 방지: 세상에는 수많은 프로그램과 라이브러리가 있고, 그 안에는 이름이 똑같은 함수들이 존재할 수 있습니다. App.을 앞에 붙여주어야 "내가 지금 쓰려는 건 다른 게 아니라 FreeCAD(App)의 openDocument야"라고 정확히 지정해 줄 수 있습니다.

---

■FreeCAD Python API 구조

FreeCAD의 Python API는 모듈(Module) 기반으로 설계되어 있으며, App(코어) 과 Gui(GUI) 를 명확히 분리한 것이 가장 큰 특징입니다. GUI 없이 콘솔 모드로도 실행할 수 있도록 설계되었기 때문입니다.

1. 핵심 구조 (가장 중요)

FreeCAD (App)          ← 코어 (데이터, 기하학, 문서 관리) └── FreeCADGui (Gui)   ← GUI (화면 표시, 선택, 뷰, 명령)

모듈	import 방법	역할
FreeCAD	import FreeCAD as App	문서, 객체, 속성, 벡터, 행렬 등 데이터와 기하학
FreeCADGui	import FreeCADGui as Gui	3D 뷰, 선택(Selection), ViewProvider, 명령 실행 등 화면 관련

 

App.ActiveDocument → 데이터의 문서
Gui.ActiveDocument → 같은 문서의 화면 표현 부분

2. 자주 사용하는 import 패턴

import FreeCAD as App import FreeCADGui as Gui import Part import Draft import Sketcher # 필요에 따라 from FreeCAD import Base, Vector, Placement, Rotation

 

3. 전체 흐름 요약

 

• App 모듈로 문서와 객체를 만들고 데이터를 조작
• Part / Mesh / Sketcher 등 전문 모듈로 기하학 생성
• doc.recompute()로 재계산
• Gui 모듈로 화면 표시, 선택, ViewProvider 제어

---

■ object (FreeCAD 에서)

용어	의미	비유
Document (문서)	.FCStd 파일 하나	파일 전체 = 그릇을 담는 상자
Object (객체)	문서 안에 들어 있는 개별 요소	상자 안에 들어 있는 각각의 물건

 

● object 를 설명하는 예시 코드

import FreeCAD as App # 1. 문서(파일)를 연다 → 이게 Document doc = App.openDocument("모델.fcstd") # 2. 문서 안에 있는 객체들을 가져온다 → 이게 Object box = doc.getObject("Box")          # 상자 객체 cylinder = doc.getObject("Cylinder") # 원기둥 객체 sketch = doc.getObject("Sketch")     # 스케치 객체 doc → FreeCAD 파일(Document) box, cylinder, sketch → 그 파일 안에 들어 있는 객체(DocumentObject)

 

● 객체 개념을 FreeCAD에 적용

 

• 객체 = 문서 안에 존재하는 하나의 요소 (Box, Part, Sketch 등)
• 속성(Attribute/Property) = 객체가 가지고 있는 정보
  예: box.Length, box.Width, box.Height, box.Placement
• 메서드(Method) = 객체가 할 수 있는 동작
  예: box.recompute(), doc.addObject(), obj.touch()
• 인스턴스 = 실제로 만들어진 구체적인 객체
  예: myBox = doc.addObject("Part::Box", "MyBox")

 

import FreeCAD as App
import Part

doc = App.newDocument("테스트")          # 새 문서(파일) 생성

# 객체 생성 (인스턴스 만들기)
box = doc.addObject("Part::Box", "MyBox")

# 속성 설정 (Attribute/Property)
box.Length = 10
box.Width = 20
box.Height = 30

# 문서 재계산 (메서드 - Method)
doc.recompute()

 

 

 

---

 

By korealionkk@gmail.com