20장. 교육 콘텐츠 설계와 종합 실습

단계별 실습 짜기와 흔한 오류

가구를 조립할 때 설명서는 "1단계: 다리 네 개를 상판에 끼운다. 이렇게 보이면 됩니다(그림)"처럼 단계마다 확인 그림을 둡니다. 3단계에서 나사가 남으면 2단계 그림과 견줘 어디서 틀렸는지 바로 압니다. 이 교안의 실습을 #### 1단계. 부터 4단계까지로 나누고 단계마다 출력을 둔 것도 같은 까닭입니다.

그림의 네 단계가 실습 하나의 기본 뼈대입니다. 여기서 설명서의 단계가 #### N단계. 이고, "이렇게 보이면 됩니다" 그림이 단계마다의 확인 출력(text 블록)입니다. 이렇게 어려운 과제를 작은 단계로 받쳐 주는 방법을 비계라고 부릅니다. 수강생이 익숙해지면 단계를 하나씩 합쳐 발판을 걷어 냅니다.

수강생이 자주 막히는 곳

수업 전에 "어디서 막힐까"를 미리 적어 두면, 질문이 몰릴 때 표를 띄워 한 번에 안내할 수 있습니다. 아래는 이 교안의 앞 장에서 다룬 흔한 오류입니다.

증상	까닭	고치는 법	다룬 곳
`'NoneType' object has no attribute 'shape'`	`cv2.imread` 가 실패해 `None` 을 돌려줌	읽은 직후 `if img is None` 으로 확인	1장, 2장
사과가 파랗게 보인다	BGR 그림을 그대로 `plt.imshow` 에 넣음	`cv2.COLOR_BGR2RGB` 로 바꿔 넣기	1장, 3장
파일이 분명히 있는데 `None`	Windows 에서 경로에 한글이 있음	작업 폴더를 옮겨 상대 경로 쓰기, `np.fromfile` + `cv2.imdecode`	1장
가장 밝던 칸이 검게 바뀐다	`uint8` 넘침(250 + 60 → 54)	`cv2.add`, `np.clip` 으로 포화 연산	1장, 5장
흑백 그림이 보라·노랑으로 보인다	`cmap="gray"` 를 빠뜨림	`plt.imshow(gray, cmap="gray")`	1장
`No module named 'cv2'`	패키지를 깐 가상환경과 실행한 파이썬이 다름	VS Code 에서 `.venv` 고르기	1장
창이 뜨지 않고 멈춘다	`cv2.imshow` 뒤 `waitKey` 를 기다림	Matplotlib 으로 띄우기	1장, 15장

짧은 예시

단계마다 "통과/막힘"과 고칠 곳을 찍는 작은 확인 함수를 만들어 둡니다. 수강생은 "막힘"이 처음 나온 줄만 보면 됩니다.

Python

import cv2
import numpy as np

def check(step, ok, hint):
    """확인 결과를 한 줄로 찍는다. 막히면 고칠 곳을 함께 알려 준다."""
    print(f"[{'통과' if ok else '막힘'}] {step}" + ("" if ok else f" → {hint}"))
    return ok

img = cv2.imread("fruit_stand.png")
check("1단계 읽기", img is not None, "작업 폴더가 data 인지, 파일 이름이 맞는지 보세요")
check("1단계 컬러인가", img is not None and img.ndim == 3, "IMREAD_GRAYSCALE 로 읽지 않았는지 보세요")
check("1단계 자료형", img is not None and img.dtype == np.uint8, "uint8 이어야 합니다")

wrong = cv2.imread("fruit_stnad.png")    # 일부러 이름을 틀려 본다
check("오타 난 파일 읽기", wrong is not None, "이름을 확인하세요")

주의할 점

확인 출력은 짧게 둡니다. 배열 전체를 찍으면 화면이 숫자로 가득 차서 중요한 줄을 놓칩니다. shape, dtype, 최솟값·최댓값 정도면 됩니다.
없는 파일을 읽을 때 OpenCV 가 [ WARN:0@...] 같은 글을 따로 찍을 수 있습니다. 오류가 아니라 알림이라고 미리 알려 줍니다.