Amagine3D: 설명과 치수를 주면 수정 가능한 CAD 소스로 하드웨어 케이스를 설계하는 에이전트 프로젝트

9bow · 9월 2, 2026, 9:30오전

Amagine3D 소개

이미지 한 장으로 3D 모델을 만드는 도구는 이제 여러 갈래로 나와 있습니다. 다만 그렇게 나온 결과물은 대부분 메시(Mesh), 즉 삼각형 표면의 덩어리입니다. 감상하거나 게임에 넣기에는 충분한데, 실제로 만들 물건의 케이스로 쓰려면 곤란해집니다. 벽 두께를 0.2mm 키우거나 나사 구멍 위치를 3mm 옮기는 수정이 메시에서는 표면을 직접 손보는 작업이 되고, 안에 들어갈 기판과 배터리의 자리를 확보했는지 확인할 방법도 마땅치 않습니다. 하드웨어 쪽에서 이 수정 가능성을 담당하는 것은 메시가 아니라 파라메트릭 CAD(Parametric CAD), 즉 치수를 변수로 들고 있다가 값을 바꾸면 형상을 다시 계산하는 방식입니다.

Amagine3D 는 자연어 요구사항과 참조 이미지, 핵심 치수를 받아 파라메트릭 CAD 설계를 만들고, 그 과정에서 생성한 파이썬 소스 코드를 그대로 남기는 프로젝트입니다. Amagine 이 하드웨어 제작을 위해 개발하고 있는 3D 기능 계층을 오픈소스로 공개한 것으로, Amagine 쪽은 전자 회로와 케이스, 펌웨어, 조립까지 묶어 다루는 얼리 액세스 단계의 제품이고 지금 공개된 Amagine3D 는 그중 3D 설계 부분에 해당합니다. 현재 공개 버전이 다루는 범위는 스마트 하드웨어의 케이스와 그에 딸린 구조물이며, 프로젝트 자체는 활발한 개발 중이라고 밝히고 있습니다.

설계가 시작되는 순서에 이 프로젝트의 성격이 담겨 있습니다. 겉모양을 먼저 만들고 내부를 비우는 방향이 아니라, 안쪽 부품에서 시작해 거치대와 인터페이스 자리를 배치한 뒤 케이스와 조작부, 열 관리 구조를 만듭니다. 설계가 여러 부품으로 나뉘어야 하면 덮개와 힌지, 걸쇠를 조립 여유와 출력 공차까지 함께 잡아 만듭니다. 여닫는 덮개나 미끄러지는 덮개처럼 움직이는 기구가 들어가면, 정해진 운동 경로를 따라 충돌과 동작 여유를 검사할 수도 있습니다.

Amagine3D가 생성한 BUSY Bar 케이스를 회전시켜 보여주는 데모

위 데모는 저장소가 예시로 공개한 결과물입니다. BUSY Bar 라는 데스크톱 기기의 공개된 정보만으로 Amagine3D 가 만든 케이스이며, 앞면에 디스플레이 영역, 위쪽에 물리 조작부를 두고 내부 부품과 인터페이스를 둘러 공간을 배치한 여러 부품 구성입니다. 저장소는 이 한 번의 생성으로 완전한 build123d 소스 코드와 STEP, STL 파일, 검사 보고서가 함께 나왔다고 적고 있습니다.

Amagine3D가 남기는 산출물과 편집 경로

이 프로젝트가 메시 생성 도구와 다른 점은 생성이 끝난 뒤에 있습니다. 매 생성마다 완전한 파이썬 및 build123d 소스 코드가 보존되고, 핵심 치수는 작업 화면(workbench)에 노출됩니다. 그 값을 조정하면 모델을 다시 호출하지 않고 소스에 반영되어 형상이 다시 만들어집니다. 즉 미세 조정 단계에서는 LLM 호출 비용이 발생하지 않습니다.

내보낼 수 있는 형식은 색상 구성에 따라 다릅니다. 단색 설계는 STEP과 STL로, 다색 설계는 색상 정보를 담은 3MF 파일과 색상 영역별 STL 파일로 내보냅니다. 저장소는 이 두 경로를 skills/text-a3d 와 skills/text-a3d-color 라는 별도의 스킬로 나눠 두었습니다.

기하 연산의 기반은 브라우저가 아니라 정식 CAD 커널입니다. 저장소가 밝힌 핵심 의존성은 다음과 같습니다:

프로젝트	담당 역할
build123d	파라메트릭 CAD 모델링
Open CASCADE Technology 와 CadQuery OCP	정밀 기하 커널과 파이썬 바인딩
Three.js	3D 미리보기, 선택, 측정
trimesh	메시 처리와 검사
lib3mf	3MF 쓰기와 재확인
PI coding agent	에이전트 세션, 스트리밍, 도구 호출

Amagine3D가 정의하는 3D 네이티브 에이전트

저장소는 자신의 구조를 3D 네이티브 에이전트(3D-native Agent), 즉 3D 설계 상태를 중심에 둔 에이전트 구조라고 부릅니다. 이 상태는 현재 버전에 있는 모든 부품의 형상과 부품 사이의 공간 관계를 기록하고, 에이전트의 다음 행동을 결정하며, 실행 결과가 다시 그 상태에 기록됩니다.

설계 작업이 두 층으로 나뉘는 것이 이 구조의 핵심입니다. 자율 내부 루프(autonomous inner loop)는 후보 설계를 만들고, 커밋 단계는 그 후보가 새로운 기준 버전이 될 수 있는지 판정합니다. 둘을 분리해 두면 에이전트가 이미 검사를 통과한 설계를 망가뜨리지 않으면서 반복해서 시도할 수 있습니다.

내부 루프의 한 회차는 현재 설계 상태에서 시작합니다. 에이전트가 부품 사이의 공간 관계를 읽고 어떤 구조를 바꿔야 할지 결정하면, 수정된 모델이 실제 기하 환경에서 실행됩니다. 여기서 시스템은 생성된 결과를 직접 측정하고 조립 간섭과 운동 경로, 내보낸 파일을 검사합니다. 그 결과가 에이전트에게 돌아오고, 요구가 충족되지 않았으면 에이전트는 구체적인 측정값으로 문제 위치를 찾아 해당 영역을 수정한 뒤 다음 회차를 시작합니다. 판정의 근거가 모델이 텍스트로 내리는 자기 평가가 아니라 실제로 생성된 기하라는 점이 이 루프의 설계 의도입니다.

후보 설계가 현재 작업의 검사를 통과하면 커밋 단계로 넘어갑니다. 시스템은 후보를 사용자 제약과 이전 설계 버전과 비교하고, 검사를 통과하면 소스 코드와 제조용 파일까지 함께 새로운 기준으로 저장합니다. 변경이 새 문제를 만들면 이전 결과를 보존한 채 에이전트가 후보를 계속 고치게 합니다. 이미 확정된 구조를 바꾸거나 기존 산출물을 덮어쓰는 동작에는 사용자 승인이 필요할 수 있습니다.

현재 공개 버전은 이 과정의 첫 단계를 파라메트릭 CAD로 구현한 것입니다. 저장소는 지금은 소스 코드가 주된 설계 상태이고 작업이 미리 정해진 단계를 따라 진행된다고 밝히면서, 다음 단계에서는 부품과 그 공간 관계를 계속 갱신되는 3D 월드 모델 상태에 직접 기록하는 방향을 계획으로 제시합니다. 그렇게 되면 에이전트가 대화와 소스 코드에서 설계 전체를 매번 재구성하지 않고도 그 상태 안에서 국소 구조를 수정할 수 있게 된다는 설명입니다.

비슷한 도구들과 Amagine3D의 차이

자연어에서 3D로 가는 도구는 이미 여러 갈래가 있고, Amagine3D는 그중 파라메트릭 CAD 쪽에 서 있습니다. 산출물 형식과 편집 방식에서 서로 다른 점을 정리하면 다음과 같습니다:

도구	주된 산출물	생성 후 수정 방식
Amagine3D	build123d 파이썬 소스, STEP, STL, 3MF	소스의 치수 파라미터를 바꿔 재계산
CADAM	CAD 모델	자연어 기반 웹 애플리케이션
SGS-1	구조화 CAD	생성 모델 출력
Modly	3D 메시 모델	메시 편집

이 표에서 확인할 것은 우열이 아니라 어느 쪽 산출물이 필요한가입니다. 정밀한 치수와 조립 관계가 중요한 기구물에는 파라메트릭 소스가 남는 쪽이 유리하고, 외형만 빠르게 얻으면 되는 작업에는 메시 생성 쪽이 단계가 적습니다. Amagine3D 가 조립 간섭과 운동 경로 검사를 루프 안에 넣어 둔 것은 앞쪽 용도를 겨냥한 선택입니다.

Amagine3D 설치와 실행

필요한 환경은 Node.js 20.19 이상, Python 3.10부터 3.13까지, npm, 최신 데스크톱 브라우저, 그리고 Amagine3D 에이전트 런타임(Runtime) 프로토콜과 호환되는 모델 게이트웨이입니다. 설치 스크립트가 저장소 안에 .venv 를 만들고 고정된 버전의 build123d, OCP, trimesh, lib3mf 를 설치하므로 별도의 데스크톱 CAD 애플리케이션은 필요하지 않습니다:

git clone https://github.com/amagine-ai/Amagine3D.git
cd Amagine3D
npm install
cp .env.example .env
npm run dev

.env 를 설정한 뒤 브라우저에서 http://127.0.0.1:6160 을 엽니다. 로컬 API는 기본값으로 http://127.0.0.1:6161 에서 대기합니다. 첫 실행에서 .venv 를 준비하고, 이후 실행은 의존성 지문이 바뀌지 않았으면 그것을 재사용합니다.

서버 설정에서 지정하는 값은 다음과 같습니다:

LLM_API_KEY=...
LLM_MODEL=openai/gpt-5.5
LLM_BASE_URL=https://gateway.example.com/v1
LLM_API_TYPE=openai-responses
LLM_THINKING_LEVEL=medium
TAVILY_API_KEY=... # optional; enables the Web refs control

PORT=6161
WEB_PORT=6160
AGENT_RUN_TIMEOUT_MS=1800000

이 값들은 로컬 Express 서버만 읽습니다. TAVILY_API_KEY 를 설정하면 입력창에 웹 참조(Web refs) 조작이 나타나고, 그 회차에서 이를 켜면 에이전트가 CAD 변경 전에 검색을 먼저 수행해 치수와 규격 출처를 순위와 함께 돌려주며, 사용 가능한 참조 이미지를 최대 3장까지 멀티모달 모델에 전달합니다. 이미지가 없어도 CAD 스킬 작업 흐름은 막히지 않습니다. 저장소는 API 키를 클라이언트 측 환경 변수로 노출하지 말고 .env 를 커밋하지 말라고 명시하고 있습니다.

전체 구조는 React와 Vite 로 만든 UI, Express API, 3D 네이티브 에이전트 런타임, 세션 단위로 분리된 파이썬 CAD 작업 공간의 순서로 이어집니다. 에이전트 세션마다 자기 작업 공간을 쓰고, CAD 스크립트는 서버가 관리하는 파이썬 환경에서 실행되며, 브라우저는 Three.js 로 생성된 모델을 그립니다. 모델 접근 자격증명은 서버에 남습니다. 더 자세한 내용은 저장소의 위협 모델 문서와 보안 신고 정책에 정리되어 있습니다.

Amagine3D는 누구에게 유용한가

3D 프린터로 뽑을 케이스가 필요하고 나중에 치수를 손볼 일이 있을 것 같은 하드웨어 프로젝트에 Amagine3D는 시도해 볼 만한 선택입니다. 파라메트릭 소스가 남으니 첫 결과가 완벽하지 않아도 치수만 바꿔 다시 만들 수 있고, 조립 간섭과 출력 공차를 루프 안에서 검사하므로 출력 후에야 문제를 발견하는 경우를 줄일 수 있습니다.

반대로 모델 게이트웨이를 따로 준비할 수 없는 환경에서는 Amagine3D를 바로 쓸 수 없습니다. 실행 요건에 에이전트 런타임 프로토콜과 호환되는 모델 게이트웨이가 포함되어 있고, .env 에 API 키와 기본 URL을 직접 채워야 합니다. 다루는 범위도 아직 스마트 하드웨어 케이스와 그에 딸린 구조물에 맞춰져 있으므로, 기계 부품이나 건축 형상 같은 다른 영역을 기대하면 맞지 않습니다. 검증된 환경도 데스크톱 Chrome과 Edge로 한정되어 있습니다.

Amagine3D의 라이선스

Amagine3D는 Apache 라이선스 2.0으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

단, npm과 pip으로 별도 설치되는 오픈소스 구성 요소는 각자의 라이선스를 따르며 Apache 라이선스 2.0으로 대체되지 않습니다. 실행 중인 애플리케이션은 /licenses 경로에서 라이선스 페이지를 제공하고, 라이선스 원문과 npm 목록은 저장소의 public/licenses/에, 배포 경계와 서드파티 고지는 서드파티 고지 문서에 정리되어 있으므로, 상업적으로 배포하기 전에는 그 목록을 확인해야 합니다.

Amagine 홈페이지 (Amagine3D를 개발하는 하드웨어 제작 제품, 얼리 액세스)

Amagine3D 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

이 도구를 직접 설치해 사용해보셨다면, 파이토치 한국 사용자 모임 회원들을 위해 경험이나 팁을 댓글로 남겨주세요!