파이썬 OpenCV 설치부터 이미지 읽기·쓰기까지 — 완전 입문 가이드

작성자:

카테고리: AI 기술 공부 노트
태그: OpenCV, 파이썬, 컴퓨터비전, cv2, 이미지처리, 머신러닝전처리
Rank Math 핵심 키워드: 파이썬 OpenCV 설치, cv2 이미지 읽기, OpenCV 튜토리얼
썸네일 프롬프트 (Nanobana):

Dark futuristic cyberpunk background (#070b14). A glowing cyan terminal window showing Python code with import cv2. On the right, a split-panel showing a color photo transforming into a grayscale version. Electric blue (#38bdf8) accent lines. Korean text overlay: “OpenCV 입문”. No people.

이 글에서 배우는 것

  • OpenCV가 뭔지, 왜 머신러닝에서 중요한지
  • Windows / macOS / Linux 환경별 설치 방법
  • cv2.imread() 로 이미지 불러오기
  • cv2.imshow() 로 화면에 띄우기
  • cv2.imwrite() 로 파일로 저장하기
  • 자주 발생하는 오류와 해결법

OpenCV가 뭔가요?

OpenCV(Open Source Computer Vision Library)는 이미지와 영상을 다루는 오픈소스 라이브러리입니다. 인텔이 1999년에 처음 개발했고, 지금은 전 세계 개발자들이 컴퓨터 비전 프로젝트에 가장 많이 쓰는 도구가 됐어요.

머신러닝이나 딥러닝을 공부하다 보면 OpenCV는 거의 필수로 만나게 됩니다. 이유가 뭘까요?

모델에 이미지를 넣기 전에 전처리가 필요하기 때문입니다. 사이즈 조정, 색상 변환, 노이즈 제거 같은 작업을 OpenCV로 처리합니다. Ultralytics YOLO를 써본 분이라면 결과 바운딩 박스를 화면에 그릴 때도 OpenCV를 쓴다는 걸 알 겁니다.

한 줄 정리: OpenCV = 파이썬에서 이미지를 자유자재로 다루는 스위스 아미 나이프

설치 방법

기본 설치 (가장 많이 쓰는 방법)

pip install opencv-python

이걸로 대부분의 상황은 해결됩니다. 설치가 끝나면 아래 명령어로 버전을 확인하세요.

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

4.x.x 형태의 버전 번호가 나오면 성공입니다.

버전 선택 기준

패키지특징추천 대상
opencv-python기본 패키지, GUI 포함대부분의 개발자
opencv-python-headlessGUI 없음, 용량 작음서버·Docker 환경
opencv-contrib-python추가 알고리즘 포함고급 기능 필요할 때

일반적인 학습 목적이라면 opencv-python 하나면 충분합니다.

가상환경 사용 권장

# 가상환경 생성
python -m venv cv-env

# 활성화 (Windows)
cv-env\Scripts\activate

# 활성화 (macOS / Linux)
source cv-env/bin/activate

# OpenCV 설치
pip install opencv-python

가상환경을 쓰면 프로젝트마다 라이브러리 버전을 따로 관리할 수 있어요. 특히 여러 ML 프로젝트를 동시에 진행할 때 충돌을 막을 수 있습니다.

이미지 읽기 — cv2.imread()

설치가 끝났으면 가장 기본인 이미지 불러오기부터 해봅시다.

import cv2

# 이미지 읽기
img = cv2.imread('sample.jpg')

# 이미지 정보 확인
print(type(img))   # <class 'numpy.ndarray'>
print(img.shape)   # (높이, 너비, 채널수) 예: (480, 640, 3)
print(img.dtype)   # uint8

몇 가지 중요한 포인트가 있습니다.

OpenCV는 BGR 순서를 씁니다. 일반적으로 이미지는 RGB(빨강-초록-파랑) 순서인데, OpenCV는 반대로 BGR(파랑-초록-빨강) 순서로 읽습니다. 나중에 matplotlib이나 PIL과 함께 쓸 때 색상이 이상하게 나오는 이유가 바로 이 때문입니다.

이미지는 NumPy 배열입니다. img.shape를 찍어보면 (높이, 너비, 채널수) 형태의 튜플이 나옵니다. 이걸 알면 이미지를 배열 연산으로 자유롭게 다룰 수 있어요.

읽기 옵션

# 컬러 이미지로 읽기 (기본값)
img_color = cv2.imread('sample.jpg', cv2.IMREAD_COLOR)

# 그레이스케일로 읽기
img_gray = cv2.imread('sample.jpg', cv2.IMREAD_GRAYSCALE)

# 알파 채널 포함 (PNG 투명도)
img_alpha = cv2.imread('sample.png', cv2.IMREAD_UNCHANGED)

cv2.IMREAD_GRAYSCALE로 읽으면 shape가 (높이, 너비)가 됩니다. 채널이 없어지는 거예요.

파일 경로 주의사항

# ❌ 이렇게 쓰면 오류 발생 (Windows 백슬래시)
img = cv2.imread('C:\Users\jerry\images\photo.jpg')

# ✅ 올바른 방법 1: 슬래시 사용
img = cv2.imread('C:/Users/jerry/images/photo.jpg')

# ✅ 올바른 방법 2: 원시 문자열
img = cv2.imread(r'C:\Users\jerry\images\photo.jpg')

이미지 화면에 표시 — cv2.imshow()

import cv2

img = cv2.imread('sample.jpg')

# 창 제목과 이미지 지정
cv2.imshow('내 첫 OpenCV 창', img)

# 키 입력 대기 (0 = 무한 대기)
cv2.waitKey(0)

# 모든 창 닫기
cv2.destroyAllWindows()

cv2.waitKey(0)은 필수입니다. 이게 없으면 창이 순식간에 열렸다가 닫혀버려요. 0을 넣으면 키를 누를 때까지 기다리고, 숫자를 넣으면 밀리초 단위로 대기합니다.

여러 창 띄우기

import cv2

img = cv2.imread('sample.jpg')
img_gray = cv2.imread('sample.jpg', cv2.IMREAD_GRAYSCALE)

cv2.imshow('원본 (컬러)', img)
cv2.imshow('그레이스케일', img_gray)

cv2.waitKey(0)
cv2.destroyAllWindows()

창 제목을 다르게 주면 동시에 여러 창을 띄울 수 있습니다.

Jupyter Notebook 사용자 주의: Jupyter에서는 cv2.imshow()가 제대로 동작하지 않을 수 있습니다. 그 경우 matplotlib을 함께 써서 시각화하세요.

import cv2
import matplotlib.pyplot as plt

img = cv2.imread('sample.jpg')
# BGR → RGB 변환 후 표시
img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)

plt.imshow(img_rgb)
plt.axis('off')
plt.show()

이미지 저장 — cv2.imwrite()

import cv2

img = cv2.imread('sample.jpg')

# 그레이스케일로 변환 후 저장
img_gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
result = cv2.imwrite('output_gray.jpg', img_gray)

if result:
    print("저장 성공!")
else:
    print("저장 실패 — 경로를 확인하세요")

cv2.imwrite()는 저장 성공 여부를 True / False로 반환합니다. 항상 확인하는 습관을 들이세요.

저장 품질 조절 (JPEG)

# JPEG 품질 설정 (0~100, 기본 95)
cv2.imwrite('output_high.jpg', img, [cv2.IMWRITE_JPEG_QUALITY, 95])
cv2.imwrite('output_low.jpg',  img, [cv2.IMWRITE_JPEG_QUALITY, 30])

품질을 낮추면 파일 용량이 줄어들지만 화질이 떨어집니다. ML 데이터셋 만들 때 용량 조절이 필요하면 유용하게 쓸 수 있어요.

전체 코드 한눈에 보기

import cv2

# 1. 이미지 읽기
img = cv2.imread('sample.jpg')

if img is None:
    print("이미지를 불러올 수 없습니다. 경로를 확인하세요.")
else:
    print(f"이미지 크기: {img.shape}")  # (높이, 너비, 채널)

    # 2. 화면에 표시
    cv2.imshow('원본', img)

    # 3. 그레이스케일 변환
    img_gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
    cv2.imshow('그레이스케일', img_gray)

    # 4. 저장
    cv2.imwrite('output.jpg', img_gray)
    print("그레이스케일 이미지를 output.jpg로 저장했습니다.")

    # 5. 창 닫기
    cv2.waitKey(0)
    cv2.destroyAllWindows()

img is None 체크는 꼭 넣으세요. 파일 경로가 틀리거나 파일이 없을 때 imread()는 오류를 발생시키지 않고 None을 반환합니다. 체크 없이 그냥 쓰면 나중에 엉뚱한 오류가 터집니다.

자주 발생하는 오류와 해결법

“ModuleNotFoundError: No module named ‘cv2′”

pip install opencv-python

가상환경을 사용 중이라면 해당 환경이 활성화된 상태에서 설치했는지 확인하세요.

이미지 창이 바로 꺼진다

cv2.waitKey(0) 을 빠뜨렸을 가능성이 높습니다. 반드시 imshow() 뒤에 추가하세요.

이미지 색상이 이상하게 보인다

matplotlib으로 표시할 때 BGR → RGB 변환을 빠뜨린 경우입니다.

img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
plt.imshow(img_rgb)

imread()가 None을 반환한다

  • 파일 경로에 오타가 없는지 확인
  • 한글 경로는 오류를 일으킬 수 있음 → 영문 경로 사용 권장
  • 파일 확장자가 실제와 다른 경우 (.jpg인데 .png로 저장)

정리

이번 글에서 배운 것을 정리하면 다음과 같습니다.

  • pip install opencv-python 으로 설치
  • cv2.imread() 로 이미지 읽기 — NumPy 배열로 반환됨
  • OpenCV는 BGR 순서를 사용한다는 점 기억하기
  • cv2.imshow() + cv2.waitKey(0) 세트로 화면 표시
  • cv2.imwrite() 로 이미지 저장

다음 글에서는 색상 변환(BGR→HSV)과 직선·원·텍스트를 이미지 위에 그리는 방법을 다룹니다. 실제로 YOLO 탐지 결과를 화면에 표시할 때 쓰는 기법이에요.

다음 포스팅 예고: OpenCV 색상 변환 & 기본 도형 그리기
이 시리즈의 전체 목록은 [AI 기술 공부 노트] 카테고리에서 확인하세요.

뉴스레터를 구독하면 다음 편이 올라올 때 바로 알림을 받을 수 있습니다. 아래 구독 버튼을 눌러주세요!

댓글 남기기