README.md

---
title: Deeplearning Board
emoji: 🧠
colorFrom: pink
colorTo: yellow
sdk: docker
pinned: false
---

# ASL Letter Board

Teachable Machine으로 학습한 ASL 알파벳 이미지 분류 모델을 FastAPI와 React 화면에 연결한 프로젝트입니다.
사용자는 이미지 업로드 또는 웹캠 촬영으로 ASL A-Z 알파벳을 예측하고, 예측 결과를 게시판에 저장해 학습 기록처럼 관리할 수 있습니다.

단어 학습 화면은 특정 단어만 보여주는 방식에서 벗어나, 사용자가 원하는 영어 단어를 입력하면 각 알파벳의 ASL 샘플 이미지를 순서대로 확인하는 방식으로 개선했습니다. 모델 판정이 아직 완전히 안정적이지 않은 점을 고려해, 학습 화면에서는 자동 채점보다 웹캠을 거울처럼 사용해 샘플과 자신의 손 모양을 직접 비교하는 흐름에 집중했습니다.

![Teachable Machine 학습 화면](docs/image/teachable_machine_page.png)

## 주요 기능

- Teachable Machine Keras 모델(`keras_model.h5`) 기반 ASL A-Z 알파벳 이미지 분류
- `labels.txt`를 이용한 클래스 라벨 로딩 및 게시판 필터 생성
- 이미지 업로드, 드래그 앤 드롭, 웹캠 촬영 분석
- 예측 결과 Top 5, 신뢰도, 모델 정보, 추론 시간 표시
- 예측 결과 게시판 저장, 목록 조회, 상세 조회
- 게시글 제목 수정 및 삭제
- 원하는 영어 단어를 입력해 ASL 알파벳 샘플을 순서대로 학습
- 웹캠 거울 모드로 샘플 사진과 내 손 모양 비교
- SQLite 기반 로컬 데이터 저장

## 화면 구성

<table>
  <tr>
    <td width="50%"><img src="docs/image/start.png" alt="Start screen" width="100%"></td>
    <td width="50%"><img src="docs/image/home.png" alt="Home screen" width="100%"></td>
  </tr>
  <tr>
    <td width="50%"><img src="docs/image/classification.png" alt="Classification screen" width="100%"></td>
    <td width="50%"><img src="docs/image/learn.png" alt="Learn screen" width="100%"></td>
  </tr>
  <tr>
    <td width="50%"><img src="docs/image/board.png" alt="Board screen" width="100%"></td>
    <td width="50%"></td>
  </tr>
</table>

주요 경로:

- `/`: 홈 화면
- `/classify`: ASL 알파벳 분류 화면
- `/learning`: 단어 입력형 ASL 학습 화면
- `/board`: 저장된 학습 기록 게시판
- `/post/{id}`: 게시글 상세 화면
- `/webcam-test`: 웹캠 장치 테스트 화면

## 실행 방법

Python 패키지를 설치합니다.

```bash
pip install -r requirements.txt
```

React 화면을 빌드합니다.

```bash
cd frontend
npm install
npm run build
cd ..
```

FastAPI 서버를 실행합니다.

```bash
python -m uvicorn backend.app.main:app --reload
```

브라우저에서 아래 주소로 접속합니다.

```text
http://127.0.0.1:8000
```

웹캠 기능은 브라우저 권한이 필요합니다. 권한 요청이 뜨면 허용해야 촬영 분석과 거울 연습을 사용할 수 있습니다.

개발 중 React dev server를 따로 실행하려면 아래 명령을 사용합니다. Vite proxy가 `/api`, `/word-images`, `/static` 요청을 FastAPI 서버로 전달합니다.

```bash
cd frontend
npm run dev
```

## 모델 파일

Teachable Machine에서 TensorFlow/Keras 형식으로 내보낸 모델 파일을 아래 위치에 둡니다.

```text
ai/model/keras_model.h5
ai/model/labels.txt
```

`labels.txt`는 Teachable Machine 기본 형식을 지원합니다.

```text
0 A
1 B
2 C
...
25 Z
```

서비스는 라벨 파일을 읽어 예측 결과 이름과 게시판 필터를 구성합니다.

## 단어 학습 이미지

단어 학습 화면은 `docs/image/test_image`에 있는 A-Z 테스트 이미지를 알파벳 샘플로 사용합니다. 파일명은 `{알파벳}_test.jpg` 형식을 사용합니다.

```text
docs/image/test_image/
├─ A_test.jpg
├─ B_test.jpg
├─ C_test.jpg
...
└─ Z_test.jpg
```

FastAPI는 이 폴더를 `/test-images` 경로로 제공합니다.

```text
http://127.0.0.1:8000/test-images/A_test.jpg
http://127.0.0.1:8000/test-images/Z_test.jpg
```

현재 이미지는 테스트용이라 다소 어두울 수 있습니다. 이후 밝기와 배경을 보정한 A-Z 대표 이미지를 같은 파일명으로 교체하면 화면 로직을 바꾸지 않고 품질을 개선할 수 있습니다.

## API

### 이미지 예측

```http
POST /api/v1/predict
Content-Type: multipart/form-data
```

요청 필드:

- `file`: jpg, jpeg, png 이미지 파일

응답 예시:

```json
{
  "success": true,
  "filename": "sample.png",
  "predicted_class": "A",
  "confidence": 0.9821,
  "top_k": [
    { "label": "A", "score": 0.9821 },
    { "label": "B", "score": 0.0121 }
  ],
  "model": {
    "name": "keras_model.h5",
    "version": "v1"
  },
  "inference_time_ms": 123
}
```

### 라벨 조회

```http
GET /api/v1/predict/labels
```

응답 예시:

```json
{
  "classes": ["A", "B", "C"],
  "count": 3
}
```

### 게시글

```http
GET /api/v1/posts
GET /api/v1/posts?category=A
GET /api/v1/posts/{post_id}
POST /api/v1/posts
PUT /api/v1/posts/{post_id}
DELETE /api/v1/posts/{post_id}
```

게시글 저장 요청 예시:

```json
{
  "title": "ASL A 분류 결과",
  "image_url": "data:image/png;base64,...",
  "prediction": "A",
  "confidence": 0.95
}
```

## 프로젝트 구조

```text
Deeplearning_Board/
├─ ai/
│  └─ model/
│     ├─ keras_model.h5
│     └─ labels.txt
├─ backend/
│  └─ app/
│     ├─ main.py
│     ├─ routers/
│     │  ├─ pages.py
│     │  ├─ post.py
│     │  └─ predict.py
│     └─ services/
│        ├─ classifier_service.py
│        └─ post_service.py
├─ data/
│  └─ app.db
├─ docs/
│  └─ image/
│     ├─ test_image/
│     │  ├─ A_test.jpg
│     │  └─ ...
│     └─ words/
│        ├─ LOVE/
│        ├─ APPLE/
│        └─ manifest.json
├─ frontend/
│  ├─ src/
│  │  ├─ api/client.js
│  │  ├─ main.jsx
│  │  └─ style.css
│  ├─ static/
│  │  ├─ css/style.css
│  │  └─ images/placeholder.jpg
│  ├─ index.html
│  ├─ package.json
│  ├─ package-lock.json
│  └─ vite.config.js
├─ Dockerfile
├─ requirements.txt
└─ README.md
```

## 배포

이 프로젝트는 Hugging Face Spaces의 Docker 환경에 배포했습니다. Docker 빌드는 React 앱을 먼저 빌드한 뒤, FastAPI가 빌드된 정적 파일과 API를 하나의 서버에서 제공합니다.

https://huggingface.co/spaces/eunzzang/Deeplearning_Board

주의:

- 무료 Space는 재시작 시 SQLite 데이터가 초기화될 수 있습니다.
- 장기 저장이 필요하면 별도 데이터베이스나 persistent storage가 필요합니다.
- 첫 빌드는 TensorFlow 설치 때문에 시간이 걸릴 수 있습니다.

## 현재 한계와 향후 개선

- 현재 단어 학습 샘플은 테스트용 이미지라 밝기와 배경 품질을 추가로 보정할 수 있습니다.
- 이미지 분류 모델은 조명, 배경, 손 위치, 카메라 각도에 영향을 받을 수 있습니다.
- 단어 학습 화면의 웹캠은 현재 자동 채점이 아닌 거울 비교 용도입니다.
- 모델 정확도가 충분히 개선되면 글자별 수동 확인 기능을 추가할 수 있습니다.
- 자동체크 모드는 안정적인 예측 성능과 호출 제한 정책이 준비된 뒤 마지막 단계에서 도입하는 것이 적절합니다.

## 참고 사항

- 게시글 데이터는 `data/app.db`에 저장됩니다.
- `data/app.db`는 실행 중 자동 생성됩니다.
- 웹캠은 `http://127.0.0.1` 또는 HTTPS 환경에서 안정적으로 동작합니다.
- Teachable Machine 모델 호환을 위해 `tf-keras`를 사용합니다.
- `__pycache__`와 실행 중 생성 파일은 커밋 대상에서 제외하는 것을 권장합니다.