Skip to content

setup.md

Latest commit

 

History

History
121 lines (83 loc) · 4.76 KB

setup.md

File metadata and controls

121 lines (83 loc) · 4.76 KB
Raw

설치와 문제 해결

1. 기본 설치

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python run.py samples          # 샘플 생성 확인
python run.py 1                # 첫 레슨

설치 확인:

python -c "import cv2, numpy; print(cv2.__version__, numpy.__version__)"

2. opencv-python 배포판 고르기

패키지 포함 언제
opencv-python 메인 모듈 + GUI(imshow) 기본값. 데스크톱
opencv-python-headless 메인 모듈, GUI 없음 서버·CI·도커 (--show 불가, 나머지는 동일)
opencv-contrib-python 메인 + contrib(ximgproc, tracking 등) contrib 모듈이 필요할 때

⚠️ 동시에 두 개 이상 설치하지 말 것. 같은 cv2 패키지를 덮어써 import 가 깨진다. 바꿔 설치할 때는 먼저 전부 제거한다.

pip uninstall -y opencv-python opencv-python-headless opencv-contrib-python
pip install opencv-python

3. 자주 겪는 문제

imshow 가 아무것도 안 뜬다 / 창이 회색이다

waitKey 를 호출하지 않았다. imshow 는 그리기를 요청만 하고 실제 렌더링은 waitKey 안의 이벤트 루프에서 일어난다.

cv2.imshow("win", img)
cv2.waitKey(0)          # 이 줄이 없으면 창이 그려지지 않는다
cv2.destroyAllWindows()

headless 빌드에서는 cv2.error: The function is not implemented 가 난다. 이 저장소는 그 경우를 감지해 안내만 하고 계속 진행한다 — outputs/ PNG 로 확인하면 된다.

한글이 ??? 로 나온다

cv2.putText 의 Hershey 폰트에는 한글 글리프가 없다. 버그가 아니라 사양이다. Pillow 로 TrueType 을 렌더링해 합성해야 한다 — cvstudy.put_text_kr() 이 그 구현이다.

시스템에서 폰트를 못 찾으면 영문으로 대체된다. 다음 경로 중 하나에 한글 폰트가 있어야 한다.

OS 경로
macOS /System/Library/Fonts/AppleSDGothicNeo.ttc (기본 존재)
Ubuntu sudo apt install fonts-nanum → /usr/share/fonts/truetype/nanum/NanumGothic.ttf
Windows C:/Windows/Fonts/malgun.ttf (기본 존재)

다른 폰트를 쓰려면 cvstudy/display.py 의 _find_korean_font() 후보 목록에 추가한다.

한글·유니코드 경로에서 imread 가 None 을 준다

주로 Windows. imread/imwrite 대신 파일 I/O 를 파이썬에 맡긴다.

img = cv2.imdecode(np.fromfile(path, dtype=np.uint8), cv2.IMREAD_COLOR)

ok, buf = cv2.imencode(".png", img)
Path(path).write_bytes(buf.tobytes())

웹캠이 안 열린다

  • macOS: 첫 실행 시 카메라 권한 팝업 → 허용. 터미널 앱마다 따로 물어본다. (시스템 설정 → 개인정보 보호 및 보안 → 카메라)
  • 다른 프로그램이 카메라를 점유 중이면 열리지 않는다. cap.release() 를 빠뜨린 이전 실행도 원인이 된다.
  • 인덱스는 0 부터 순서대로 시도한다: python run.py 13 --camera 1

동영상 저장 파일이 0바이트다 / 재생이 안 된다

세 가지 중 하나다.

  1. writer.release() 를 호출하지 않았다 (헤더가 안 써진다) → try/finally
  2. VideoWriter 해상도와 실제 write 하는 프레임 크기가 다르다 → 조용히 빈 파일
  3. 코덱 미지원 → writer.isOpened() 로 먼저 확인. mp4v(.mp4) → XVID(.avi) 순으로 시도

ValueError: setting an array element with a sequence ... inhomogeneous shape

np.array(contours) 처럼 길이가 다른 배열들을 하나로 만들려 했다. NumPy 1.24 부터 예외다. 컨투어 점을 합칠 때는 np.vstack(contours) 를 쓴다. (legacy/README.md §1)

cv2.error: (-215:Assertion failed) size.width>0 && size.height>0

거의 항상 imread 가 None 을 돌려준 것이다(경로 오타·권한·깨진 파일). 읽자마자 검사한다.

img = cv2.imread(path)
if img is None:
    raise SystemExit(f"읽기 실패: {path}")

cv2.CascadeClassifier 가 없다는 에러

OpenCV 5 에서 제거됐다. 오래된 튜토리얼을 옮기는 중이라면 레슨 16 을 참고해 cv2.FaceDetectorYN(ONNX) 또는 cv2.dnn 으로 바꾼다. 4.x 를 계속 쓰려면 pip install "opencv-python<5".

4. 선택 사항 — DNN 모델

레슨 16 의 얼굴 검출 부분은 ONNX 모델이 있어야 실행된다. OpenCV Zoo 의 YuNet(face_detection_yunet_*.onnx, 약 300KB)을 받아 경로를 넘긴다.

python run.py 16 --model /path/to/face_detection_yunet_2023mar.onnx --image myphoto.jpg

모델을 넘기지 않으면 그 단계만 건너뛰고 나머지는 정상 실행된다.