OpenCV + opencv_contrib 직접 빌드 및 Python 바인딩 오류 정리 (feat. SURF 사용)

필자가 학교 프로젝트를 진행하다가 surf를 로컬에서 돌리기 위해서 opencv의 버전을 내리는 과정 중에 발생한 문제들이 여러가지 있었는데 그 문제들과 해결 과정을 나열하겠다.

gpt와 함께 의논(?)하며 발생했던 모든 것에 대해서 정리한 것이니 많은 분들에게 도움이 되었으면 좋겠다.

 

그리고 빌드하는 것에 대해서도 간단히 설명할 것이다.

 

 

1. 설치 환경

• Ubuntu 20.04
• Python 3.6 (Conda 가상환경)
• OpenCV 3.4.x
• OpenCV Contrib 모듈 포함
• SURF, SIFT 등 사용을 위해 OPENCV_ENABLE_NONFREE=ON 설정

2. 주요 문제 및 해결 요약

발생 위치	문제	증상	해결 방법
CMake 구성	C++ 버전 미설정	constexpr not allowed 등의 컴파일 에러	CMAKE_CXX_STANDARD=11 명시
CMake 구성	Python3 경로 설정 누락	cv2 모듈 없음, 바인딩 생성 안됨	PYTHON3_EXECUTABLE, INCLUDE_DIR, LIBRARY, PACKAGES_PATH 명시
CMake 구성	Numpy 미설치	numpy not found, 바인딩 생성 안됨	Conda 환경에서 pip install numpy 또는 conda install numpy
CMake 구성	Python 라이브러리 경로 잘못 지정	Libraries: NO, 바인딩 실패	정확한 libpython3.6m.so 경로 지정 필요
make install 후	cv2 임포트 실패	Python에서 No module named 'cv2'	.so 파일이 Conda site-packages에 없거나 경로 미설정
쉘 실행 시	cv2 찾지 못함	Python에서는 있음, 터미널 실행에서는 없음	PYTHONPATH 환경변수 설정 필요

3. 설치 순서 및 해결 방법 정리

1. 소스코드 준비

git clone https://github.com/opencv/opencv.git
git checkout 3.4.2  # 또는 원하는 태그

git clone https://github.com/opencv/opencv_contrib.git
git checkout 3.4.2

2. CMake 구성 (build 디렉토리 생성 후)

cmake -D CMAKE_BUILD_TYPE=RELEASE \
      -D CMAKE_INSTALL_PREFIX=/usr/local \
      -D OPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules \
      -D OPENCV_ENABLE_NONFREE=ON \
      -D PYTHON3_EXECUTABLE=$CONDA_PREFIX/bin/python3 \
      -D PYTHON3_INCLUDE_DIR=$CONDA_PREFIX/include/python3.6m \
      -D PYTHON3_LIBRARY=$CONDA_PREFIX/lib/libpython3.6m.so \
      -D PYTHON3_PACKAGES_PATH=$CONDA_PREFIX/lib/python3.6/site-packages \
      -D BUILD_opencv_python3=ON \
      -D BUILD_opencv_python_bindings_generator=ON \
      -D CMAKE_CXX_STANDARD=11 \
      ../opencv

확인 포인트 (CMake 출력에서):

• Python 3: 항목에서 Interpreter, Libraries, numpy, packages path 모두 채워져야 함
• To be built: 항목에 python3, xfeatures2d, python_bindings_generator 포함되어야 함
• Unavailable: 에 python3이 나오면 실패

3. 빌드 및 설치

make -j$(nproc)
sudo make install

4. 바인딩 확인

ls $CONDA_PREFIX/lib/python3.6/site-packages/cv2*.so

 

5. Python 테스트 코드

python -c "import cv2; print(cv2.__version__); print(cv2.xfeatures2d.SURF_create())"

6. 환경변수 설정 (터미널에서 cv2 인식 안 될 때)

export PYTHONPATH=$CONDA_PREFIX/lib/python3.6/site-packages:$PYTHONPATH

 

기타 실수 & 주의사항

실수	설명
opencv-python 설치된 상태	pip로 설치된 OpenCV가 우선 로딩됨, 반드시 삭제 (pip uninstall opencv-python)
numpy 설치 누락	바인딩 생성 안 됨
make clean 안 함	설정 바꾸고 다시 빌드할 땐 꼭 rm -rf build/* 후 다시 cmake
sudo make install 안 함	.so 파일이 설치되지 않음