Apppublic

tae3lee/VisionVelocity

sourceHugging Faceupdated 2mo agoView on Hugging Face

0likes

App README

🌊 강의 유속 측정 앱 (River Velocity Measurement App)

비디오에서 강물의 흐름 속도를 자동으로 측정하는 웹 애플리케이션입니다.

📋 기능

—🎬 비디오 업로드: MP4, AVI, MOV, MKV 등 모든 일반 영상 형식 지원
—📊 자동 유속 측정: 광학 유동(Optical Flow) 기술을 이용한 정확한 측정
—📈 결과 분석: 시간별 추이, 분포 히스토그램, 통계 지표
—📥 데이터 내보내기: CSV 형식으로 원본 데이터 다운로드
—📄 리포트 생성: 측정 결과 및 설정 정보 포함

🚀 빠른 시작

1. 설치

bash

git clone https://github.com/yourusername/river-velocity-app.git
cd river-velocity-app
pip install -r requirements.txt

2. 실행

bash

streamlit run app.py

그러면 자동으로 브라우저가 열리고 웹 앱이 시작됩니다. 보통 http://localhost:8501에서 실행됩니다.

3. 사용하기

1.📹 비디오 업로드: 강물 영상을 업로드합니다
2.⚙️ 설정: 프레임 속도와 스케일을 입력합니다
3.🚀 측정 시작: "유속 측정 시작" 버튼을 클릭합니다
4.📊 결과 확인: 측정 결과를 확인하고 다운로드합니다

📏 스케일 측정 방법 (중요!)

정확한 유속 측정을 위해서는 스케일(픽셀당 거리)을 알아야 합니다.

단계별 가이드

1.강에 알려진 길이의 물체 배치
2.1미터 길이의 자
3.표시 막대
4.또는 다른 알려진 크기의 물체

1.비디오 촬영
2.정면에서 촬영 (45도 이상 각도 피하기)
3.스케일 물체가 명확하게 보이도록
4.최소 10초 이상 촬영

1.픽셀 거리 측정
2.이미지 편집 프로그램 (Photoshop, GIMP 등)에서 비디오의 한 프레임 저장
3.스케일 물체가 몇 픽셀인지 측정

1.스케일 계산

   스케일 = 실제 거리(미터) / 픽셀 수

예시

—1미터가 100픽셀 → 1 / 100 = 0.01 m/px = 1 cm/픽셀 입력
—1미터가 50픽셀 → 1 / 50 = 0.02 m/px = 2 cm/픽셀 입력

📝 기술 사항

알고리즘

—광학 유동 (Lucas-Kanade): 이웃한 프레임 간의 특징점 추적
—중앙값 필터: 이상치 제거를 통한 안정적인 측정
—검증 범위: 0~5 m/s (타당하지 않은 데이터 자동 제거)

주요 라이브러리

—Streamlit: 웹 인터페이스
—OpenCV: 비디오 처리 및 광학 유동
—NumPy: 수치 계산
—Matplotlib: 그래프 시각화

📊 출력 결과

제공되는 통계

—평균 유속: 전체 측정 구간의 평균
—중앙값: 이상치에 강건한 중심값
—최소/최대 유속: 측정 범위
—표준편차: 유속 변동성
—데이터 개수: 유효한 측정 포인트 수

그래프

1.시간별 유속: 측정 시간에 따른 유속 변화
2.분포 히스토그램: 유속 분포도

⚠️ 제한사항 및 주의사항

측정 오차 원인

—카메라 움직임
—영상 품질 (해상도, 노이즈)
—부정확한 스케일 설정
—빠른 카메라 팬닝

개선 방법

—✅ 삼각대 사용 (카메라 고정)
—✅ 충분한 해상도 (720p 이상 권장)
—✅ 정확한 스케일 측정
—✅ 정상적인 조명 조건
—✅ 명확한 입자 또는 흐름 특징

🔧 설정 파라미터

파라미터	기본값	범위	설명
FPS	30	10-120	비디오 프레임 속도
스케일	1.0 cm/px	0.1-10	1픽셀이 현실에서 몇 cm인지
프레임 간격	1	1-10	1=모든 프레임, 2=1개씩 건너뜀

📂 프로젝트 구조

river-velocity-app/
├── app.py                    # Streamlit 메인 애플리케이션
├── requirements.txt          # Python 의존성
├── README.md                # 이 파일
├── .gitignore              # Git 무시 파일
└── uploads/                # 임시 비디오 파일 폴더 (자동 생성)

🐛 문제 해결

앱이 시작되지 않음

bash

# Python 버전 확인 (3.8 이상)
python --version

# 의존성 재설치
pip install -r requirements.txt --upgrade

비디오를 열 수 없음

—비디오 형식 확인 (MP4, AVI, MOV, MKV)
—파일 크기 확인 (너무 크면 실패 가능)
—비디오 코덱 확인 (일반적인 코덱 사용)

측정 결과가 이상함

—스케일 값 확인
—FPS 값 확인
—영상 품질 확인
—영상 내 명확한 흐름 특징 확인

💡 사용 팁

1.정확한 스케일 측정: 가장 중요한 부분입니다!
2.충분한 길이 촬영: 최소 10초, 30초 이상 권장
3.여러 번 측정: 같은 장소에서 여러 번 촬영 후 비교
4.메타데이터 확인: 파일 정보에서 정확한 FPS 확인
5.데이터 백업: 중요한 결과는 CSV로 저장

📄 라이선스

MIT License - 자유롭게 사용, 수정, 배포 가능합니다.

👨‍💻 기여

개선 사항이나 버그 리포트는 Issues에서 제출해주세요. Pull Request도 환영합니다!

📧 문의

문제가 있으면 GitHub Issues를 통해 보고해주세요.

마지막 업데이트: 2024년

버전: 1.0.0