Python + OpenCV 를 순서대로 익히기 위한 실행 가능한 학습 자료. 레슨 16개 + 실전 프로젝트 3개. 모든 예제는 인터넷 연결 없이 바로 돌아간다.
2019년에 만든 스크립트 2개(cv2ImageFilter.py, cv2ImageMasking.py)에서 출발했다.
두 파일은 legacy/ 에 그대로 보존하고 — 지금 환경에서는 둘 다 실행이 안 된다 —
무엇이 왜 바뀌었는지를 legacy/README.md 에 정리했다.
개선판은 projects/auto_crop.py, projects/redact.py 다.
git clone https://github.com/SungmanHan/opencvStudy.git
cd opencvStudy
python -m venv .venv &&source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python run.py # 레슨 목록
python run.py 1 # 첫 레슨 실행- 샘플 이미지는 코드로 생성된다 (
python run.py samples). 처음 실행할 때 자동으로 만들어진다. - 모든 결과는
outputs/에 PNG 로 저장된다. 창으로 보려면--show를 붙인다. - 각 레슨은 독립 실행 가능하다:
python lessons/07_thresholding.py --show
번호 순서대로 따라가면 된다. 뒤 레슨은 앞 레슨의 결론을 전제로 쓴다.
| # | 레슨 | 답할 수 있게 되는 질문 |
|---|---|---|
| 01 | 입출력 | imread 가 실패하면 무슨 일이 일어나는가? 왜 색이 뒤집혀 보이는가? |
| 02 | 픽셀·ROI·채널 | 슬라이스를 고쳤는데 원본이 왜 같이 바뀌었나? img+50 이 왜 어두워지나? |
| 03 | 색공간 | 특정 색만 뽑으려면? 빨강은 왜 구간을 두 개 잡아야 하나? |
| 04 | 기하 변환 | 축소·확대에 쓸 보간법은? 비스듬한 문서를 어떻게 펴나? |
| 05 | 그리기·텍스트 | 검출 결과를 어떻게 표시하나? 한글은 왜 깨지나? |
| # | 레슨 | 답할 수 있게 되는 질문 |
|---|---|---|
| 06 | 블러·필터 | 노이즈 종류에 따라 어떤 필터를 골라야 하나? |
| 07 | 이진화 | 조명이 고르지 않으면 왜 전역 임계값이 실패하나? |
| 08 | 모폴로지 | 점 노이즈를 지우고 끊긴 획을 잇는 순서는? |
| 09 | 엣지 검출 | Canny 의 두 임계값을 어떻게 정하나? |
| 11 | 히스토그램 | 사진이 어둡다는 걸 어떻게 '수치로' 판정하나? |
| # | 레슨 | 답할 수 있게 되는 질문 |
|---|---|---|
| 10 | 컨투어 | 물체를 세고, 재고, 도형 종류까지 구분하려면? |
| 12 | 비트연산·마스킹 | 원하는 영역에만 처리를 적용하고 자연스럽게 합성하려면? |
| 13 | 동영상 | 파일·웹캠을 읽고 움직임을 찾아 저장하려면? |
| 14 | 특징점 매칭 | 회전·확대된 물체를 어떻게 같은 물체로 인식하나? |
| 15 | 고전 검출 | 템플릿 매칭은 언제 실패하나? 원·직선을 찾으려면? |
| 16 | QR·ArUco·DNN | 2019년식 Haar cascade 예제는 왜 더 이상 안 도나? |
| 스크립트 | 하는 일 | 쓰는 레슨 |
|---|---|---|
auto_crop.py | 여백을 잘라 내용만 남기기 | 07, 08, 10 |
redact.py | 개인정보 영역 가리기(fill/blur/pixelate) | 05, 08, 12 |
doc_scanner.py | 비스듬히 찍은 문서 → 정면 스캔본 | 04, 07, 09, 10 |
python run.py doc_scanner --show
python run.py auto_crop myphoto.jpg --pad 12 --debug
python run.py redact assets/member_card.png --auto --mode fillopencvStudy/
├── run.py 레슨 런처 (목록·실행·샘플 생성·전체 실행)
├── lessons/ 레슨 16개 — 번호 순서대로
├── projects/ 레슨을 조합한 실전 스크립트 3개
├── cvstudy/ 공용 유틸 (샘플 생성, 결과 저장·표시)
├── legacy/ 2019년 원본 + 무엇이 왜 바뀌었는지
├── docs/ 설치 가이드, 함정 치트시트
├── assets/ 생성되는 샘플 (git 제외)
└── outputs/ 실행 결과 (git 제외)
assets/ 의 이미지·동영상은 cvstudy/samples.py 가 그린다.
- 저장소에 바이너리가 없고, 네트워크 없이 첫 실행이 된다
- 정답을 아는 입력을 만들 수 있다 — 동전 5개의 좌표·반지름, 문서의 네 꼭짓점을 미리 알기 때문에
레슨이 자기 결과를 채점한다 (예: 레슨 15
HoughCircles hit 5/5,doc_scanner꼭짓점 오차 1.4px) - 시드가 고정돼 있어 누가 언제 실행해도 같은 그림·같은 수치가 나온다
내 사진으로 해 보려면 대부분의 레슨이 --image 를 받는다.
python run.py 7 --image ~/Pictures/receipt.jpg --showpython run.py # 레슨·프로젝트 목록
python run.py 9 # 9번 레슨
python run.py 9 --show # 창까지 띄우기
python run.py 9 --image a.jpg # 내 이미지로
python run.py samples --force # 샘플 다시 생성
python run.py all # 전 레슨 순차 실행 (동작 확인)
python lessons/09_edges.py -h # 레슨 설명서 (docstring 그대로)- Python 3.10+ (3.12 에서 검증)
- OpenCV 5.0.0, NumPy 2.5, matplotlib, Pillow —
requirements.txt - 화면 없는 서버라면
opencv-python-headless로 바꿔도--show를 빼면 전부 동작한다
| 없어진 API | 대체 |
|---|---|
cv2.CascadeClassifier (+ cv2.data 의 XML) | cv2.FaceDetectorYN(ONNX), cv2.dnn, QR/ArUco |
cv2.HOGDescriptor | cv2.dnn 기반 검출기 |
findContours 의 3-값 반환 (OpenCV 3) | 2-값 contours, hierarchy |
레슨 16 을 실행하면 현재 설치본에서 무엇이 살아 있는지 직접 확인할 수 있다.
- docs/setup.md — 설치 문제 해결(한글 폰트, headless, 카메라 권한, 코덱)
- docs/cheatsheet.md — 자주 밟는 함정 30개 한 장 요약
- legacy/README.md — 2019년 코드가 지금 왜 안 도는가