3D 모델 뷰어

이 프로젝트는 three.js와 React를 사용하여 3D 모델을 렌더링하는 웹 애플리케이션입니다. 백엔드는 FastAPI를 사용하여 모델 파일을 제공합니다.

프로젝트 구조

• frontend/: React와 three.js를 사용한 프론트엔드 애플리케이션
• backend/: FastAPI를 사용한 백엔드 API 서버

기술 스택 및 문서

Frontend (React + three.js)

프론트엔드는 React를 기반으로 하며, @react-three/fiber를 사용하여 3D 씬을 렌더링합니다. 주요 컴포넌트와 기능은 다음과 같습니다.

Components

• HomePage (src/pages/HomePage.tsx)

  • 애플리케이션의 메인 페이지입니다.
  • 역할: 모델 선택 상태(selectedModel)를 관리하고, 선택된 모델의 데이터를 가져오는 로직을 조정합니다. ModelSelector와 ModelViewer를 배치합니다.

• ModelSelector (src/components/controls/ModelSelector.tsx)

  • 역할: 사용자에게 사용 가능한 모델 목록을 드롭다운으로 보여주고 선택할 수 있게 합니다.
  • Props:
    • selectedModel (string): 현재 선택된 모델의 이름.
    • onModelChange ((modelName: string) => void): 모델 변경 시 호출되는 콜백 함수.
  • 동작: 마운트 시 백엔드에서 모델 목록을 가져옵니다.

• ModelViewer (src/components/model/ModelViewer.tsx)

  • 역할: 3D 캔버스를 생성하고 모델을 렌더링합니다. 조명(Ambient, Spot, Point)과 카메라 컨트롤(OrbitControls)을 포함합니다.
  • Props:
    • objData (string): 렌더링할 OBJ 파일의 텍스트 데이터.
  • 동작: objData 문자열을 파싱하여 3D 메쉬로 변환 후 렌더링합니다. 데이터가 없으면 폴백 박스를 표시합니다.

API Client (src/api/modelAPI.ts)

• fetchModelList(): 사용 가능한 모델 이름 목록을 가져옵니다.
• fetchModel(modelName): 특정 모델의 .obj 파일 내용을 텍스트로 가져옵니다.

---

Backend (FastAPI)

백엔드는 /models 디렉토리에 있는 OBJ 파일을 서빙하는 역할을 합니다.

API Endpoints (app/api/v1/endpoints/model.py)

• GET /api/v1/models

  • 설명: 서버에 저장된 사용 가능한 모든 OBJ 모델의 이름 목록을 반환합니다.
  • 응답 예시: ["cube", "pyramid", "teddy"]

• GET /api/v1/models/{model_name}

  • 설명: 지정된 이름의 OBJ 모델 파일을 다운로드(반환)합니다.
  • 파라미터: model_name (확장자 .obj는 생략 가능)
  • 응답: application/octet-stream (OBJ 파일 내용)

• GET / (app/main.py)

  • 설명: 서버 상태 확인용 루트 엔드포인트입니다.
  • 응답: {"Hello": "World"}

로컬 환경에서 실행하기

이 애플리케이션은 WSL(Windows Subsystem for Linux) 환경에서 테스트되었습니다.

백엔드

1. 백엔드 디렉토리로 이동합니다.

   cd backend

2. Python 가상 환경을 생성하고 활성화합니다.

   python -m venv .venv
   source .venv/bin/activate

3. uv를 사용하여 종속성을 설치합니다.

   pip install uv
   uv pip install -r requirements.txt

   참고: pyproject.toml 파일이 있으므로 uv pip install을 사용하여 종속성을 설치할 수도 있습니다.

4. 백엔드 서버를 실행합니다.

   uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

   또는

   python run.py

   서버가 http://localhost:8000에서 실행됩니다.

프론트엔드

1. 프론트엔드 디렉토리로 이동합니다.

   cd frontend

2. npm을 사용하여 종속성을 설치합니다.

   npm install

3. 프론트엔드 개발 서버를 실행합니다.

   npm run dev

   애플리케이션이 http://localhost:5173 (또는 다른 사용 가능한 포트)에서 실행됩니다.