Spero: RealSense 객체 분류 및 추적

이 프로젝트는 Intel RealSense 깊이 카메라를 사용하여 객체 분류 및 추적을 수행하는 전체 파이프라인을 구현합니다. 데이터 수집, 데이터셋 관리, 모델 학습(PyTorch 사용), 실시간 추론 및 객체 추적을 위한 도구들이 포함되어 있습니다.

주요 기능

• 데이터 수집: RGB 및 Depth 데이터를 ROI 라벨링과 함께 쉽게 캡처할 수 있는 도구.
• 데이터셋 관리: 데이터를 학습(train)/검증(val)/테스트(test) 세트로 분할하는 유틸리티.
• 모델 학습: PyTorch를 사용하여 MobileNetV2, ResNet18, 또는 ResNet50 모델 학습.
• 실시간 추론: RealSense 카메라를 사용한 실시간 객체 분류.
• 객체 추적: 템플릿 매칭을 사용하여 분류된 객체를 실시간으로 추적.

사전 요구사항

하드웨어

• Intel RealSense Depth Camera (예: D435, D435i, D415)

소프트웨어

• Windows 10/11 또는 Linux
• Python 3.8 이상
• Intel RealSense SDK 2.0

설치 방법

1. 가상환경 생성

   # Windows
   python -m venv .venv
   .venv\Scripts\activate
   
   # Linux/Mac
   python3 -m venv .venv
   source .venv/bin/activate

2. 의존성 패키지 설치

   pip install -r requirements.txt

3. Jupyter 커널 등록 (Jupyter Notebook 사용 시)

   python -m ipykernel install --user --name=spero --display-name="Python (Spero)"

   • 이 단계는 Jupyter Notebook에서 프로젝트를 실행하려는 경우에만 필요합니다.
   • 커널 등록 후 Jupyter Notebook을 실행하고 "Python (Spero)" 커널을 선택하세요.
   • 등록된 커널 확인: jupyter kernelspec list

사용 가이드

Jupyter Notebook 실행

1. Jupyter Notebook 시작

   jupyter notebook

   • 브라우저가 자동으로 열리며 Jupyter 인터페이스가 표시됩니다.

2. 노트북 파일 열기

   • Project_Spero.ipynb 파일을 클릭하여 엽니다.

3. 커널 선택

   • 노트북 상단 메뉴에서 Kernel → Change kernel → Python (Spero) 선택
   • 또는 우측 상단의 커널 이름을 클릭하여 "Python (Spero)" 선택

4. 셀 실행

   • 각 셀을 순서대로 실행: Shift + Enter
   • 전체 셀 실행: 메뉴에서 Cell → Run All

주요 작업 흐름

1. 데이터 수집

Project_Spero.ipynb 파일에서 데이터 수집 셀을 실행합니다.

• [L]: 클래스 라벨 설정 (폴더명)
• 마우스 드래그: 관심 영역(ROI) 선택
• [S]: 선택한 ROI 저장 (Color + Depth)
• [C]: 선택 초기화
• [Q]: 종료

라벨 설정 → ROI 선택 → ROI 저장 → ROI 초기화 → ...

데이터는 dataset/ 디렉터리에 저장됩니다.

2. 데이터셋 준비

Project_Spero.ipynb 파일에서 데이터셋 분할 셀을 실행합니다.

실행 후 dataset_split/ 디렉터리 아래에 train, val, test 하위 폴더가 생성됩니다.

3. 모델 학습

Project_Spero.ipynb 파일에서 모델 학습 셀을 실행합니다.

• 기본 모델: MobileNetV2 (사전 학습됨)
• 최고 성능 모델은 models/best_model.pth로 저장됩니다.
• 스크립트 내의 config 딕셔너리에서 하이퍼파라미터를 수정할 수 있습니다.

4. 실시간 추론

Project_Spero.ipynb 파일에서 실시간 추론 셀을 실행합니다.

객체 주위에 박스를 그려서 분류합니다.

5. 객체 추적

Project_Spero.ipynb 파일에서 객체 추적 셀을 실행합니다.

• 마우스 드래그: 분류할 객체 선택
• [T]: 선택한 객체 추적 시작/중지
• [R]: 추적 중 객체 재분류

디렉터리 구조

spero/
├── Project_Spero.ipynb      # 메인 Jupyter Notebook (데이터 수집, 학습, 추론, 추적)
├── requirements.txt         # Python 의존성 목록
├── source/                  # Python source 코드 폴더(참조용)
├── dataset/                 # 수집된 원본 데이터
├── dataset_split/           # 분할된 데이터셋 (train/val/test)
└── models/                  # 저장된 학습 모델