Pillow 사용법 - Basic 01

Pillow 라이브러리의 기본적인 사용법을 다룬다.

 

2024.06.03 - [Python] - [Python] PIL, Pillow, OpenCV, and Scikit-image

[Python] PIL, Pillow, OpenCV, and Scikit-image

 

관련 gist

https://gist.github.com/dsaint31x/6a4de3886a27731a0a06d1667b24c56f

pillow_basic_01.ipynb

---

기본 기능 소개

1. Image.open() 함수

PIL.Image 모듈에서 제공하는 함수.

파일 경로를 argument로 받아서 PIL.Image.Image 객체를 반환.

PIL.Image.open(fp, formats=None) -> PIL.Image.Image

• 파일 형식을 명시적으로 지정하고 싶다면 formats 매개변수로 지정가능.
• 하지만 다양한 이미지 형식을 자동으로 감지하고 읽을 수 있기 때문에 거의 사용할 일이 없음(제대로 된 확장자가 지정된 경우라면...)
• 파일 경로는 문자열 또는 pathlib 모듈의 Path객체도 가능함.

2024.03.31 - [Python] - [Python] pathlib.Path 사용하기.

[Python] pathlib.Path 사용하기.

---

참고: PIL.Image 모듈의 Image 클래스의 주요 attributes

2025.07.15 - [Python] - Pillow에서 Image 객체의 주요 attribute.

Pillow에서 Image 객체의 주요 attribute.

 

---

2. Image.new() 함수

PIL.Image 모듈에서 제공하는 함수.

완전히 새로운 빈 이미지를 메모리에 생성하므로 그래픽 작업이나 이미지 합성의 기반으로 자주 사용됨

mode, size, color를 argument로 받아서 새로운 PIL.Image.Image 객체를 생성하여 반환.

PIL.Image.new(mode, size, color=0) -> PIL.Image.Image

• mode: 이미지 모드를 지정 (예: 'RGB', 'RGBA', 'L' 등)
• size: 이미지 크기를 (width, height) tuple 객체로 지정
• color: 초기 색상값 지정 (기본값 0으로 검은색)

 

3. paste() 메서드

PIL.Image.Image 객체에서 제공하는 메서드.
다른 이미지를 현재 이미지에 붙여넣기 위해 사용하며, 반환값은 None (현재 이미지를 직접 수정).

앞서 new() 함수와 함께 많이 이용됨.

PIL.Image.Image.paste(im, box=None, mask=None) -> None

• img: 붙여넣을 이미지 객체 (또는 색상값)
• box: 붙여넣을 위치를 지정하는 (left, top) tuple 객체 또는 (left, top, right, bottom) 박스형태의 tuple 객체
• mask: 투명도 마스크로 사용할 이미지 (선택적, 알파 채널이나 그레이스케일 이미지)

이미지 합성, 로고 삽입, 콜라주 제작 등에 널리 사용됨.

원본 이미지를 직접 수정하므로 복사본이 필요한 경우 미리 copy() 메서드 사용 권장

---

4. show() 메서드

PIL.Image.Image 객체의 메서드.

이미지를 확인할 수 있는 창을 띄움.

Image.Image.show(title=None, command=None) -> None

• title: 이미지가 보여지는 window의 타이틀바에 보여질 문자열.
• commnad: 이미지를 표시하는데 사용할 외부 실행파일 경로

이 메서드는 독립된 창을 띄우기 때문에, colab 의 경우엔 제대로 동작하지 않음.

• 최근엔 colab 의 code cell에서
  마지막에 PIL.Image.Image 객체를 evaluation 하면 이미지 확인 가능함.

colab에선 보통은 matplotlib.pyplot의 imshow를 사용해야 함.

import matplotlib.pyplot as plt

plt.imshow(n_img) # NumPy array or PIL.Image.Image
plt.show()

• 편리하게도 PIL.Image.Image 객체는 matplotlib 의 imshow로 직접 넘겨질 수 있음
• 과거엔 NumPy의 ndarray로 바꿔야 했는데...

---

5. save() 메서드

PIL.Image.Image 객체의 메서드.

 

이미지를 encoding하여 파일로 저장함.

Image.Image.save(fp, format=None, **params) -> None

 

다음은 예제 코드임.

fstr = 'output_pil.jpg'

img.save(
    fstr,
    format='JPEG',
    quality=80,
    )

 

---

6. split() 메서드 와 Image.merge() 함수.

split() 메서드는 PIL.Image.Image 객체의 메서드.
호출한 Image 객체의 channel별로 분리하여 Image객체로 만들고 이들을 item으로 가지는 tuple 객체를 반환.

 

merge(mode, bands) 함수는 PIL.Image 모듈의 함수로,
mode에 해당하는 채널수와 같은 갯수의 Image로 구성된 bands를 받아 합쳐줌.

# Convert the image to RGBA
rgba_img = n_img.convert('RGBA')

# Split the RGBA image into individual channels
r, g, b, a = rgba_img.split()

# Display each channel
fig, axes = plt.subplots(1, 4, figsize=(20, 5))
axes[0].imshow(r, cmap='gray')
axes[0].set_title('Red channel')
axes[1].imshow(g, cmap='gray')
axes[1].set_title('Green channel')
axes[2].imshow(b, cmap='gray')
axes[2].set_title('Blue channel')
axes[3].imshow(a, cmap='gray')
axes[3].set_title('Alpha channel')

for ax in axes:
    ax.axis('off')

plt.show()

img = Image.merge('RGBA',(r,g,b,a))
plt.figure()
plt.imshow(img)
plt.axis('off')
plt.show()

---

7. convert() 메서드

이미지의 color space를 변경한 새로운 이미지 반환.

Pillow에선 mode를 통해, 이미지가 어떻게 구성되어있는지(채널의 수와 각 채널의 bit수 등이 지정됨)를 나타내는데, 이 mode는 Color Space와 매우 깊이 연관됨.

getbands() 메서드로 채널을 확인 가능: Pillow에선 channel 대신 band라는 용어를 사용함.

 

다음 코드에서 Pillow에서 지원하는 다양한 color space를 확인할 수 있음.

colorspaces = {
  'L': '8-bit 흑백 (0-255)',
  '1': '1-bit 흑백 (0 또는 255)',
  'P': '8-bit 팔레트 모드',
  'RGB': '24-bit 트루컬러 (8bit x 3채널)',
  'RGBA': '32-bit 트루컬러 + 알파채널',
  'CMYK': '32-bit 컬러 (8bit x 4채널)',
  'YCbCr': 'JPEG 표준 색상공간',
  'LAB': 'CIE Lab 색상공간',
  'HSV': 'Hue, Saturation, Value'
}

for mode, _ in colorspaces.items():
  try:
    print(f'{mode}: {n_img.convert(mode).getbands()}')
  except Exception as e:
    print(f'Convert Erropr: {mode=}\n{e}')

 

https://dsaint31.tistory.com/348

[DIP] Color Space or Color Model

---

Pixel 값에 접근하기.

Pillow 의 Image는 개별 pixel 에 접근하여 처리하는 기능이 좋은 편은 아님.

해당 접근이 필요하다면, NumPy의 ndarray로 바꿔서 처리하는게 보다 편하다.

 

1. getpixel() 메서드와 putpixel() 메서드

우선, pixel하나의 값을 읽고 쓸 수 있는 getpixel() 메서드와 putpixel() 메서드를 지원함

from PIL import Image

img = Image.open("test.png").convert("RGB")

# x=50, y=30 의
# (50,30) 위치를 빨간색으로 변경
pixel = img.getpixel((50, 30)) 
print(f"픽셀 (50,30) 값:", pixel)

# (50,30) 위치를 빨간색으로 변경
img.putpixel(
	(50, 30), 
    (255, 0, 0),
)

---

2. load() 메서드

여러 pixel에 반복접근은 load() 메서드를 통해 2D array처럼 접근가능한 view인

PixelAccess 객체를 얻어서 처리하는게 좋음.

from PIL import Image

img = Image.open("test.png").convert("RGB")
pixels = img.load()  # 픽셀 데이터에 접근할 수 있는 PixelAccess 객체 반환

# 예: 이미지 전체를 흑백으로 만드는 루프
for y in range(img.height):
    for x in range(img.width):
        r, g, b = pixels[x, y]
        gray = int(0.299*r + 0.587*g + 0.114*b)
        pixels[x, y] = (gray, gray, gray)

img.show()

 

하지만, 이 방법은 개별 접근인 getpixel()과 putpixel()보다는 빠르지만, NumPy를 얻어서 처리하는 것과 비교해선 떨어짐.

NumPy를 사용하지 않을 때에만 사용하길 권함.

---

Geometrical Transform

1. crop() 메서드

cropping을 수행함.

• 항상 새로운 Image객체를 생성하여 반환
• openCV가 ndarray의 slicing으로 구현하여 view를 반환하는 것과 차이가 있음.

자를 영역의 left top과 right bottom의 x,y 좌표를 넘겨주면 됨.

cropped_image = n_img.crop(  
    (100,100,250,150), # left top x, y, right bottom x, y  
)

---

2. resize() 메서드

이미지의 크기를 변경한다.

이미지의 종횡비(aspect ratio)를 유지하지 않고 지정한 사이즈로 강제 변환하는 점에 주의.

resized_img = img.resize( 
	(150,100), # width, hegith.
)

주요 파라미터는 다음과 같음:

• resample (optional)
  • interpolation 방법. 아래 값 중 하나:
    • PIL.Image.Resamplng.NEAREST : 0, 최근접 이웃
    • PIL.Image.Resamplng.BILINEAR : 2, 선형 보간
    • PIL.Image.Resamplng.BICUBIC : 3 
    • PIL.Image.Resamplng.LANCZOS : 1, 고급 필터 (고해상도 이미지에 적합)

• box (optional)
  • 원본 이미지에서 잘라낼 영역을 (left, upper, right, lower)로 지정 가능
  • box로 지정된 영역을 잘라내고 이를 resize
  • 지정하지 않으면 원본 전체가 대상

https://dsaint31.tistory.com/811

[DIP] Interpolation (on Image)

---

참고: thumbnail() 메서드

PIL.Image.Image 객체에서 제공하는 메서드.
이미지의 aspect ratio(종횡비)를 유지하면서 지정된 크기 내로 축소 (축소만 가능)하여 썸네일을 생성하며,

반환값은 None (현재 이미지를 직접 수정).

PIL.Image.Image.thumbnail(
    size, 
    resample=PIL.Image.Resampling.LANCZOS, 
    reducing_gap=2.0,
) -> None

 

• size: 최대 크기를 지정하는 (width, height) 튜플
• resample: interpolation 방법(리샘플링 알고리즘) 지정 (기본값: LANCZOS)
• reducing_gap: 다단계 축소 시 사용할 비율 (성능 최적화용)

 

종횡비(aspect ratio)를 자동으로 유지한다는 장점이 있으나 확대는 안됨.

원본 이미지를 직접 수정하므로 원본 보존이 필요한 경우 미리 copy() 메서드 사용 필요

 

웹용 이미지 최적화나 미리보기 생성에 자주 사용됨

---

3. rotation() 메서드

CCW 회전을 수행. 

radian이 아닌 degree임.

img = Image.open("test.png")

# 45도 ccw, 이미지 크기를 확장해 잘리지 않게 함, 빈 공간은 회색으로 채움
rotated = img.rotate(45, expand=True, fillcolor=(200,200,200))

주요 파라메터는 다음과 같음

• angle (필수)
  • 시계반대방향으로 회전할 각도(단위: degrees)
  • 예) angle=90 → 90도 반시계 회전
• resample (optional)
  • interpolation 방법. 아래 값 중 하나:
    • PIL.Image.NEAREST : 0, 최근접 이웃
    • PIL.Image.BILINEAR : 2, 선형 보간
    • PIL.Image.BICUBIC : 3 
    • PIL.Image.LANCZOS : 1, 고급 필터 (고해상도 이미지에 적합)
    • 위의 네임은 구버전임. 현재는 PIL.Image.Resamplng 밑에 놓임.
• expand (기본: False)
  • True로 하면 회전 후 이미지 크기를 자동으로 늘려 원본 전체가 잘리지 않도록 함.
  • False면 원본 크기 유지 → 회전 후 잘려나갈 수 있음.
• center (optional)
  • 회전 중심점 지정 (튜플 형태: (x, y))
  • 지정하지 않으면 이미지의 중심을 기준으로 회전
• translate (optional)
  • 회전 후 (x, y) 픽셀만큼 이동
• fillcolor (optional, Pillow 5.2.0 이상)
  • expand=True 상태에서 회전 후 생기는 빈 영역의 색상을 지정
  • 예) fillcolor=(255,255,255) → 흰색으로 빈 영역 채움

---

4. transpose() 메서드

PIL.Image.Image 객체에서 제공하는 메서드.
이미지를 회전, 뒤집기,전치 등의 변환을 행하여 새로운 PIL.Image.Image객체를 반환.

PIL.Image.Image.transpose(method) -> PIL.Image.Image

• method: 변환 방식을 지정하는 옵션
• 주요 변환 옵션은 다음과 같음:
  • PIL.Image.FLIP_LEFT_RIGHT,
  • PIL.Image.FLIP_TOP_BOTTOM,
  • PIL.Image.ROTATE_90,
  • PIL.Image.ROTATE_180,
  • PIL.Image.ROTATE_270,
  • PIL.Image.TRANSPOSE,
  • PIL.Image.TRANSVERSE : anti-dialog 를 기준으로 뒤집기임.

원본 이미지는 수정되지 않고 변환된 새로운 이미지 객체를 생성하여 반환

이미지 회전이나 미러링 효과가 필요한 경우 자주 사용됨

rotate() 메서드와 달리 정확한 90도 단위 회전과 뒤집기에 최적화.

 

같이 보면 좋은 자료들

2025.07.01 - [Python] - Pillow 사용법 - Basic 02 - copy, ImageDraw

Pillow 사용법 - Basic 02 - copy, ImageDraw

 

2025.07.01 - [Python] - Pillow 사용법 - Basic 03 - Image Enhance

Pillow 사용법 - Basic 03 - Image Enhance

2025.08.06 - [Python] - pyperclip-Python에서 clipboard사용하기

pyperclip-Python에서 clipboard사용하기

2025.08.28 - [Python] - [urllib] request 모듈

[urllib] request 모듈