# 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` (또는 다른 사용 가능한 포트)에서 실행됩니다.