lightningpixel/modly

Modly – AI 기반 이미지에서 3D 메시 생성 데스크톱 앱

무엇인가요 – Modly는 Windows, Linux, Apple-Silicon macOS에서 작동하는 크로스플랫폼 데스크톱 애플리케이션으로, 단일 사진을 3D 메시로 변환할 수 있습니다. 모든 처리는 오픈소스 AI 모델을 사용해 로컬 GPU에서 실행되므로 클라우드 서비스가 필요하지 않습니다.

작동 방식 – UI는 Electron/Node.js로 구축되어 Python 백엔드(FastAPI)와 통신합니다. 백엔드는 선택한 확산 기반 3D 생성 모델(Hunyuan3D, TripoSG, Trellis2 등)을 로드하고, 제공한 이미지에 대해 추론을 수행합니다. 생성된 메시는 검사, 평활화, 단순화가 가능하며 GLB/OBJ 파일로 저장할 수 있습니다.

주요 기능

• 로컬 GPU 추론 – NVIDIA, AMD(ROCm 경유), Apple-Silicon GPU를 지원합니다.
• 확장 시스템 – 모델과 처리 단계는 확장 (GitHub 리포지토리에 manifest.json 포함)으로 패키징됩니다. 여러 최신 3D 생성기용 공식 확장이 목록에 있으며, 사용자는 자신만의 확장을 추가할 수 있습니다.
• 다중 소스 모델 가중치 – 확장은 여러 Hugging Face 리포지토리에서 모델의 일부를 가져올 수 있으며, 다운로드 전에 무결성 검사를 수행합니다.
• 공유 가중치 그룹 및 변형 – 확장은 여러 노드 간에 공통 파일을 공유하고, 양자화된 변형(Q4_K_M, Q5_K_M 등)을 크기/VRAM 힌트와 함께 노출할 수 있습니다.
• 워크플로우 에디터 – 드래그 앤 드롭 그래프에서 이미지 → 메시 생성 → 장면에 추가와 같은 노드를 연결할 수 있습니다.
• CLI 에이전트 – 순수 Python 명령줄 도구(tools/modly-cli/agent.py)로 앱을 프로그래밍 방식으로 제어할 수 있습니다(헬스 체크, 모델 목록, 생성 실행, 실행 상태 쿼리 등).
• 실시간 RAM 인디케이터 – 상단 바에 현재 메모리 사용량을 표시합니다.
• 앱 내 메시 후처리 – 평활화 및 단순화 기능이 내장되어 있습니다.

시작하기

1. 리포지토리 복제 또는 다운로드 (또는 릴리스 페이지에서 설치 프로그램 사용).
2. JavaScript 종속성 설치: npm install.
3. Python 백엔드 설정:

   cd api
   python -m venv .venv
   source .venv/bin/activate   # Windows에서는 .venv\Scripts\activate
   pip install -r requirements.txt
   

4. 개발 버전 실행: npm run dev (또는 launch.bat / launch.sh로 패키지된 앱 실행).

플랫폼 참고 사항

• AMD GPU – 자동 감지; 별도의 ROCm 설치 없이 ROCm 호환 PyTorch 웨어를 사용합니다.
• macOS – Apple-Silicon만 지원; 앱은 네이티브 윈도우 제어를 사용합니다.
• 패키징 – macOS Apple-Silicon 빌드는 npm run package:mac로 생성할 수 있습니다.

Modly 확장하기

• manifest.json과 필요한 엔트리 파일(모델 노드, 프로세스 노드 등)을 포함하는 GitHub 리포지토리 생성.
• UI에서 설치: 모델 → GitHub에서 설치 → 리포지토리 URL 붙여넣기.
• 확장은 다음을 선언할 수 있습니다:
  • model_sources: Hugging Face에서 가중치 다운로드.
  • weight_groups: 여러 노드 간 파일 공유.
  • weight_variants: 양자화 또는 정밀도 변형 노출, 크기/VRAM 메타데이터 옵션 제공.

CLI 사용 예시

# 앱이 실행 중인지 확인
python tools/modly-cli/agent.py health

# 사용 가능한 모델 목록 보기
python tools/modly-cli/agent.py model list

# 이미지에서 메시 생성
python tools/modly-cli/agent.py generate --image ./cat.png --output ./cat.glb

CLI는 실행 ID, 상태, 오류 메시지를 포함한 기계 판독 가능한 JSON을 출력하므로 자동화 스크립트나 에이전트에 적합합니다.

커뮤니티 및 지원 – 공지사항, 버그 리포트, 사용자 피드백을 위한 Discord 서버 제공.

라이선스 – MIT. 포크는 라이선스 요구 사항에 따라 원본 Modly 프로젝트에 출처를 유지해야 합니다.

---

위 모든 세부 정보는 리포지토리의 README에서 직접 인용되었습니다.