120 lines
4.1 KiB
Markdown
120 lines
4.1 KiB
Markdown
# 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. **백엔드 디렉토리로 이동합니다.**
|
|
|
|
```bash
|
|
cd backend
|
|
```
|
|
|
|
2. **Python 가상 환경을 생성하고 활성화합니다.**
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
source .venv/bin/activate
|
|
```
|
|
|
|
3. **`uv`를 사용하여 종속성을 설치합니다.**
|
|
|
|
```bash
|
|
pip install uv
|
|
uv pip install -r requirements.txt
|
|
```
|
|
*참고: `pyproject.toml` 파일이 있으므로 `uv pip install`을 사용하여 종속성을 설치할 수도 있습니다.*
|
|
|
|
4. **백엔드 서버를 실행합니다.**
|
|
|
|
```bash
|
|
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
|
|
```
|
|
또는
|
|
```bash
|
|
python run.py
|
|
```
|
|
|
|
서버가 `http://localhost:8000`에서 실행됩니다.
|
|
|
|
### 프론트엔드
|
|
|
|
1. **프론트엔드 디렉토리로 이동합니다.**
|
|
|
|
```bash
|
|
cd frontend
|
|
```
|
|
|
|
2. **`npm`을 사용하여 종속성을 설치합니다.**
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. **프론트엔드 개발 서버를 실행합니다.**
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
애플리케이션이 `http://localhost:5173` (또는 다른 사용 가능한 포트)에서 실행됩니다. |