🏀 농구 슈팅 자세 분석 서비스 : Basketball_Coach

🎥 웹 서비스 시연 영상

 

pc 시연 영상

 

모바일 시연 영상

 

🏀 서비스 및 레포지토리 URL

🔗 농구 슛폼 분석 서비스

농구 슛폼 분석 프로그램

🔗 Repository 주소

GitHub - yuncic/BASKETBALL-COACH

 

프로젝트 소개

 

꾸준히 농구를 해오면서 가장 많이 고민하고, 가장 자주 흔들리는 부분은 바로 ‘슛 자세’였습니다.

슛폼은 사람마다 다르고 정답이 없습니다.
하지만 모두가 공통적으로 해결하고 싶어하는 질문은 하나입니다.

“지금 내 슛폼이 역학적으로 효율적인가?”

감각이나 감정에 의존한 연습만으로는 이를 알기 어렵습니다.
코치가 항상 옆에 있는 것도 아니고, 영상을 찍어도 막상 무엇을 기준으로 평가해야 할지 알기 어렵습니다.

그래서 저는 슛 동작을 정량적으로 분석해주는 서비스를 만들고 싶었습니다.

이 프로젝트는
사용자가 업로드한 슛 영상을 기반으로

1. 관절 각도 변화 타이밍 분석
(무릎 → 허리 → 어깨 → 팔꿈치 → 릴리즈의 흐름이 얼마나 일관적인가?)

2. 힘 전달 방향 벡터 분석
(팔과 공의 이동 방향, 질량중심과 공의 이동 방향의 정렬 정도는 어떤가?)

이 두 가지 핵심 지표를 바탕으로
슛폼의 힘 전달 효율성과 타이밍의 정확성을 평가합니다.

즉, 이 서비스는 “이 자세가 좋다 / 나쁘다”처럼 정답을 강요하지 않습니다.
대신 역학적 관점에서 얼마나 효율적인지를 정량적인 수치와 피드백으로 알려 줍니다.

“내 슛폼이 객관적으로 어떤 상태인지 알고 싶다”
“비효율적인 부분만이라도 잡아주면 좋겠다”
라는 농구 유저의 현실적인 니즈를 해결하기 위해 탄생한 프로젝트입니다.

---

프로젝트 기술 스택 선택 과정 및 이유

 

이번 오픈 미션에서 나는 단순히 작동하는 프로젝트를 만드는 것을 넘어,
왜 특정 기술을 선택했는지 스스로 설명할 수 있어야 한다는 목표를 세웠다.

 

개발에는 정답이 없고, 항상 내가 처한 상황과 환경에 따라 
같은 기능을 구현하더라도 사용할 수 있는 기술 스택이 천차만별이다.

 

이번 프로젝트를 진행하면서 내가 선택한 기술과 이유를 작성해보았다.

 

 

1. FastAPI를 백엔드로 선택한 이유

 

고려했던 다른 선택지

 

Django, Flask, Node + Express, Spring Boot 등 다양한 백엔드 기술을 고려할 수 있었다.

 

FastAPI를 선택한 배경

 

첫째, 이번 프로젝트는 영상 업로드, 파일 입출력, 분석 결과 반환 등 I/O 작업이 많은 구조이다. FastAPI는 비동기 기반이기 때문에 이러한 작업을 빠르고 안정적으로 처리할 수 있었다.

 

둘째, Pydantic 기반의 강력한 데이터 검증을 제공한다. 분석 결과는 구조가 복잡하기 때문에 타입을 명확하게 정의하는 것이 중요했다.
프리코스에서 배운 "명확한 타입과 책임 분리"의 개념과도 잘 맞았다.

 

셋째, Swagger를 통한 API 문서가 자동으로 생성되어 기능을 테스트하고 확장하는 과정이 쉬웠다.

 

넷째, 백엔드는 이번 미션의 핵심이 아니었기 때문에 빠르게 구성할 수 있는 기술이 필요했다.
FastAPI는 개발 속도가 빠르다는 점에서 목적에 적합했다.

 

결론적으로, FastAPI는 적은 코드로 비동기 처리와 데이터 검증을 동시에 만족시키는 가장 현실적인 선택이었다.

 

2. 프론트엔드를 Vanilla JavaScript와 MVC로 구현한 이유

 

고려했던 다른 선택지

 

React, Vue, Svelte, Next.js 등 현대적인 프레임워크들을 사용할 수 있었다.

 

프레임워크를 사용하지 않은 이유는..

 

이번 프로젝트는 영상 분석 로직 자체가 복잡했고, 해당 부분을 이해하고 구현하는 것만으로도 시간과 에너지가 충분히 필요했다.
프론트엔드까지 프레임워크를 도입하면 전체 구조를 이해하기 어려워질 것이라 판단했다.

 

또한 프리코스에서 배웠던 JavaScript로의 사고 방식을 실제로 활용해보고 싶었다.
Model, View, Controller를 스스로 분리하며 데이터 흐름을 직접 설계하는 경험이 필요하다고 느꼈다.

 

전체적으로 프론트엔드에서는 내가 만든 코드가 전부 눈에 보이고, 스스로 통제하고 있다는 감각을 얻는 것을 중요하게 생각했다.

 

3. YOLOv8 Pose와 OpenCV를 선택한 이유

 

고려했던 다른 기술

 

Mediapipe, OpenPose, DeepLabCut, 자체 모델 학습 등이 있었다.

 

YOLOv8 Pose 선택 이유

 

YOLOv8은 설치가 간단하고 프레임 처리 속도도 빠르며, 슛폼 분석에 필요한 관절 포인트들을 정확하게 추정하는 데 적합했다.
경량 모델인 YOLOv8n-pose는 분석 속도와 정확도 모두 안정적인 수준이었다.

 

OpenCV 선택 이유

 

OpenCV는 영상 프레임 처리, 패널 합성, 최종 mp4 저장 등 필요한 기능을 모두 제공한다.
다양한 이미지 라이브러리가 존재하지만, 프레임 단위로 조작하고 바로 영상으로 저장하는 흐름을 자연스럽게 연결해주는 것은 OpenCV뿐이었다.

 

4. VideoWriter를 사용해 영상 결과물을 생성한 이유

 

다른 라이브러리로는 moviepy, imageio, ffmpeg CLI 등이 있었다.
그러나 moviepy는 속도가 느리고 메모리 사용량이 많았고, ffmpeg 직접 호출은 배포 환경마다 설정이 달라 유지보수가 어려웠다.

 

OpenCV의 VideoWriter는 YOLO로 처리한 프레임을 그대로 받아 자연스럽게 mp4 파일로 저장할 수 있어 가장 현실적인 선택이었다.

 

5. 서버 배포 과정에서 Render 대신 Railway를 선택한 이유

 

처음 Render를 선택한 이유

 

FastAPI용 템플릿이 제공되고, 무료 플랜이 있으며, UI가 친절하고 GitHub 기반 자동 배포가 가능했다. 개발 편의성만 놓고 보면 Render가 적합해 보였다.

 

Render에서 겪은 문제들

 

그러나 실제 배포 과정에서는 여러 문제를 겪었다.

1. PyTorch와 Ultralytics 모델 설치 시간이 매우 오래 걸림

2. Pipeline 시간이 초과되어 자동 종료됨

3. Python 버전과 PyTorch 버전 충돌

4. OpenCV 인코더가 지원되지 않아 VideoWriter가 동작하지 않음

5. CPU 성능이 다소 부족한 탓에 영상 분석 속도가 느림

 

여러 차례 재배포와 패키지 버전 조정을 시도했지만 끝내 안정적으로 동작하지 않았다.

 

Railway로 이동한 이유

 

Railway는 CPU 성능이 Render보다 훨씬 충분했고, PyTorch와 YOLOv8 설치도 별다른 충돌 없이 진행되었다. OpenCV 인코더도 정상적으로 동작했으며, 빌드 속도도 빠르고 무료 크레딧으로 필요한 만큼 테스트할 수 있었다.

 

결과적으로 실제로 영상 분석이 가능한 서버 환경은 Railway였다.

 

6. PyTorch safe_globals 설정이 필요했던 이유

 

PyTorch 2.1 이후부터는 torch.load의 동작이 강화되어 외부 모델을 로드할 때 해당 모델이 사용하는 클래스들을 명시적으로 허용해야 한다. YOLO 모델은 다양한 내부 모듈(C2f, Bottleneck, SPPF 등)을 사용하기 때문에 safe_globals에 모든 관련 클래스를 추가해줘야 했다.

 

대안으로는 PyTorch 버전을 낮추거나, 모델을 다른 포맷(ONNX, TensorRT 등)으로 변환하는 방식이 있었지만, 설정이 복잡하거나 배포 환경에서 더 많은 문제가 발생할 가능성이 컸다.

 

따라서 YOLO 내부 모듈을 자동으로 탐색해 safe_globals에 등록하는 방식을 선택했고, 이 방식은 실제 배포 환경에서 안정적으로 모델을 로드할 수 있었다.

 

마무리

 

이번 기술 선택 과정의 핵심 기준은 다음과 같았다.

1. 지금의 나에게 맞는 기술인지

2. 2주 안에 배포까지 가능한지

3. 유지보수가 가능한지

4. 분석 로직이라는 핵심을 방해하지 않는지

 

나는 완벽한 기술을 선택한 것이 아니라, 지금의 나에게 가장 맞는 기술을 선택했다.
그 과정에서 기술적 난관도 많았고, 여러 번 방향을 바꾸기도 했지만, 결국 영상이 분석되고 결과가 나오는 실제 서비스를 배포하는 데 성공했다. 이 경험은 앞으로 더 나은 프로젝트를 만들기 위한 중요한 발판이 될 것이다.

 

 

추가 (25.11.26)

성능 최적화를 마치고 그에 대한 내용을 정리한 글 입니다.

 

https://blog091.tistory.com/28

🏀 Basketball Coach 성능 최적화 기록