Pixmap¶

픽스맵(“pixel maps”)은 MuPDF의 렌더링 기능의 핵심 객체입니다. 평면 사각형 픽셀 집합을 나타냅니다. 각 픽셀은 색상을 정의하는 여러 바이트(“components”)와 투명도를 정의하는 선택적 알파 바이트로 설명됩니다.

PyMuPDF에서는 픽스맵을 생성하는 여러 방법이 있습니다. 첫 번째를 제외하고 모두 오버로드된 생성자로 사용할 수 있습니다. 픽스맵은 다음에서 생성할 수 있습니다…

문서 페이지에서 (메서드 Page.get_pixmap())
Colorspace (색 공간) 및 IRect 정보를 기반으로 빈 픽스맵
파일에서
메모리 내 이미지에서
일반 픽셀의 메모리 영역에서
PDF 문서 내의 이미지에서
다른 픽스맵의 복사본으로

참고

위의 3번과 4번 항목에 대한 입력으로 여러 이미지 형식이 지원됩니다. 지원되는 입력 이미지 형식 섹션을 참조하세요.

자주 묻는 질문 섹션을 확인하여 픽스맵 사용 예제를 살펴보세요.

Method / Attribute	Short Description
`Pixmap.clear_with()`	픽스맵의 일부 지우기
`Pixmap.color_count()`	사용된 색상 확인
`Pixmap.color_topusage()`	가장 많이 사용된 색상의 비율 확인
`Pixmap.copy()`	다른 픽스맵의 일부 복사
`Pixmap.gamma_with()`	픽스맵에 감마 계수 적용
`Pixmap.invert_irect()`	주어진 영역의 픽셀 반전
`Pixmap.pdfocr_save()`	픽스맵을 OCR된 1페이지 PDF로 저장
`Pixmap.pdfocr_tobytes()`	픽스맵을 OCR된 1페이지 PDF로 저장
`Pixmap.pil_image()`	Pillow 이미지 생성
`Pixmap.pil_save()`	Pillow 이미지로 저장
`Pixmap.pil_tobytes()`	Pillow 이미지로 `bytes` 에 쓰기
`Pixmap.pixel()`	픽셀 값 반환
`Pixmap.save()`	다양한 형식으로 픽스맵 저장
`Pixmap.set_alpha()`	알파 값 설정
`Pixmap.set_dpi()`	이미지 해상도 설정
`Pixmap.set_origin()`	픽스맵 x, y 값 설정
`Pixmap.set_pixel()`	픽셀의 색상 및 알파 설정
`Pixmap.set_rect()`	사각형 내 모든 픽셀의 색상 및 알파 설정
`Pixmap.shrink()`	비율을 유지하면서 크기 축소
`Pixmap.tint_with()`	픽스맵에 틴트 적용
`Pixmap.tobytes()`	다양한 형식으로 메모리 영역 반환
`Pixmap.warp()`	내부의 quad로 만든 픽스맵 반환
`Pixmap.alpha`	투명도 표시기
`Pixmap.colorspace`	픽스맵의 Colorspace (색 공간)
`Pixmap.digest`	픽스맵의 MD5 해시코드
`Pixmap.height`	픽스맵 높이
`Pixmap.interpolate`	보간 방법 표시기
`Pixmap.is_monochrome`	흑백만 있는지 확인
`Pixmap.is_unicolor`	단일 색상만 있는지 확인
`Pixmap.irect`	픽스맵의 IRect
`Pixmap.n`	픽셀당 바이트
`Pixmap.samples_mv`	픽셀 영역의 `memoryview`
`Pixmap.samples_ptr`	픽셀 영역에 대한 Python 포인터
`Pixmap.samples`	픽셀 영역의 `bytes` 복사본
`Pixmap.size`	픽스맵의 전체 길이
`Pixmap.stride`	이미지 한 행의 크기
`Pixmap.width`	픽스맵 너비
`Pixmap.x`	왼쪽 위 모서리의 X 좌표
`Pixmap.xres`	X 방향 해상도
`Pixmap.y`	왼쪽 위 모서리의 Y 좌표
`Pixmap.yres`	Y 방향 해상도

Class API

class Pixmap¶

__init__(self, colorspace, irect, alpha=False)¶

새 빈 픽스맵: 사각형으로 지정된 크기와 원점으로 빈 픽스맵을 생성합니다. 따라서 irect.top_left 는 픽스맵의 왼쪽 위 모서리를 지정하고, 너비와 높이는 각각 irect.width 및 irect.height 입니다. 이미지 영역은 초기화되지 않으며 쓰레기 데이터를 포함합니다 – 예를 들어 clear_with() 또는 set_rect() 를 사용하여 확실히 하세요.

매개변수:

colorspace (Colorspace (색 공간)) – 색상 공간.
irect (irect_like) – 픽스맵의 위치 및 크기.
alpha (bool) – 투명도 바이트를 포함할지 여부를 지정합니다. 기본값은 False 입니다.

__init__(self, colorspace, source)¶

복사 및 색상 공간 설정: 색상 공간을 변환하여 source 픽스맵을 복사합니다. 모든 색상 공간 조합이 가능하지만 소스 색상 공간은 None 이 아니어야 합니다.

매개변수:

colorspace (Colorspace (색 공간)) – 원하는 대상 색상 공간. 이것은 None 일 수도 있습니다. 이 경우 “마스킹” 픽스맵이 생성됩니다: Pixmap.samples 는 소스의 알파 바이트만으로 구성됩니다.
source (Pixmap.) – 소스 픽스맵.

__init__(self, source, mask)¶

v1.18.18에서 새로 추가됨

복사 및 이미지 마스크 추가: source 픽스맵을 복사하고 마스크 픽스맵의 투명도 데이터로 알파 채널을 추가합니다.

매개변수:

source (Pixmap.) – 알파 채널이 없는 픽스맵.
mask (Pixmap.) – 마스크 픽스맵. 그레이스케일 픽스맵이어야 합니다.

__init__(self, source, width, height[, clip])¶

복사 및 크기 조정: source 픽스맵을 복사하고 새로운 너비와 높이 값을 조정합니다 – 이미지는 그에 따라 늘어나거나 줄어듭니다. 부분 복사를 지원합니다. 소스 색상 공간은 None 일 수 있습니다.

매개변수:

source (Pixmap.) – 소스 픽스맵.
width (float) – 원하는 대상 너비.
height (float) – 원하는 대상 높이.
clip (irect_like) – 결과 픽스맵을 크기 조정된 픽스맵의 이 영역으로 제한합니다.

참고

너비 또는 높이가 정수를 나타내지 않으면(즉, value.is_integer() != True), 결과 픽스맵은 알파 채널을 가집니다.

__init__(self, source, alpha=1)¶

복사 및 알파 추가 또는 제거: source 를 복사하고 알파 채널을 추가하거나 제거합니다. alpha 가 source.alpha 와 같으면 동일한 복사본입니다. 알파 채널이 추가되면 값은 255로 설정됩니다.

매개변수:

source (Pixmap.) – 소스 픽스맵.
alpha (bool) – 대상이 알파 채널을 가질지 여부, 소스 색상 공간이 None 이면 기본값이며 필수입니다.

참고

일반적인 사용에는 별도의 픽스맵에서 색상 및 투명도 바이트를 분리하는 것이 포함됩니다. 일부 애플리케이션은 예를 들어 wxPython 의 wx.Bitmap.FromBufferAndAlpha() 와 같이 이를 요구합니다:

>>> # 'pix' is an RGBA pixmap
>>> pixcolors = pymupdf.Pixmap(pix, 0)    # extract the RGB part (drop alpha)
>>> pixalpha = pymupdf.Pixmap(None, pix)  # extract the alpha part
>>> bm = wx.Bitmap.FromBufferAndAlpha(pix.width, pix.height, pixcolors.samples, pixalpha.samples)

__init__(self, filename)¶

파일에서: filename 에서 픽스맵을 생성합니다. 모든 속성은 입력에서 추론됩니다. 결과 픽스맵의 원점은 (0, 0) 입니다.

매개변수:: filename (str) – 이미지 파일의 경로.

__init__(self, stream)¶

메모리에서: 메모리 영역에서 픽스맵을 생성합니다. 모든 속성은 입력에서 추론됩니다. 결과 픽스맵의 원점은 (0, 0) 입니다.

매개변수:

stream (bytes,bytearray,BytesIO) –

완전하고 유효한 이미지를 포함하는 데이터. 예를 들어 stream = bytearray(open(‘image.file’, ‘rb’).read()) 로 생성되었을 수 있습니다. bytes 타입은 Python 3에서만 지원됩니다. Python 2에서는 bytes == str 이므로 메서드가 스트림을 파일 이름으로 해석합니다.

버전 1.14.13에서 변경됨: 이제 io.BytesIO 도 지원됩니다.

__init__(self, colorspace, width, height, samples, alpha)¶

일반 픽셀에서: samples 에서 픽스맵을 생성합니다. 각 픽셀은 colorspace 및 alpha 매개변수에 의해 제어되는 여러 바이트로 표현되어야 합니다. 결과 픽스맵의 원점은 (0, 0) 입니다. 이 메서드는 다른 프로그램에서 원시 이미지 데이터가 제공될 때 유용합니다 – 자주 묻는 질문 를 참조하세요.

매개변수:

colorspace (Colorspace (색 공간)) – 이미지의 색상 공간.
width (int) – 이미지 너비
height (int) – 이미지 높이
samples (bytes,bytearray,BytesIO) –
이미지의 모든 픽셀을 포함하는 영역. 지정된 경우 알파 값을 포함해야 합니다.

버전 1.14.13에서 변경됨: (1) 이제 io.BytesIO 도 사용할 수 있습니다. (2) 데이터가 이제 픽스맵에 복사 되므로 안전하게 삭제하거나 사용할 수 없게 만들 수 있습니다.
alpha (bool) – 투명도 채널이 포함되는지 여부.

참고

다음 방정식이 참이어야 합니다: (colorspace.n + alpha) * width * height == len(samples).
버전 1.14.13부터 samples 데이터가 픽스맵에 복사 됩니다.

__init__(self, doc, xref)¶

From a PDF image: Create a pixmap from an image contained in PDF doc identified by its xref. All pimap properties are set by the image. Have a look at extract-from-pages.py and extract-from-xref.py to see how this can be used to recover all of a PDF’s images.

매개변수:

doc (Document) – 열린 PDF 문서.
xref (int) – 이미지 객체의 xref. 예를 들어 Document.get_page_images() 를 사용하여 특정 페이지에서 사용된 이미지 목록을 만들 수 있으며, 이것은 각 이미지의 xref 번호도 표시합니다.

clear_with([value[, irect]])¶

samples 영역을 초기화합니다.

매개변수:

value (int) – 지정된 경우 0부터 255까지의 값이 유효합니다. 각 픽셀의 각 색상 바이트는 이 값으로 설정되고, 알파가 있으면 255(불투명)로 설정됩니다. 생략하면 모든 바이트(알파 포함)가 0x00 으로 지워집니다.
irect (irect_like) – 지울 영역. 생략하면 전체 픽스맵을 지웁니다. value 도 지정된 경우에만 지정할 수 있습니다.

tint_with(black, white)¶

sRGB 정수 값으로 주어진 색상으로 검은색 및/또는 흰색을 교체하여 픽스맵을 색칠합니다. 색상 공간 CS_GRAY 및 CS_RGB 만 지원되며, 다른 것은 경고와 함께 무시됩니다.

색상 공간이 CS_GRAY 인 경우 평균 (red + green + blue)/3 이 사용됩니다. 픽스맵은 제자리에서 변경됩니다.

매개변수:

black (int) – 검은색을 이 값으로 교체합니다. 0x000000을 지정하면 변경되지 않습니다.
white (int) – 흰색을 이 값으로 교체합니다. 0xFFFFFF를 지정하면 변경되지 않습니다.

Examples:

tint_with(0x000000, 0xFFFFFF) 는 no-op입니다.

tint_with(0x00FF00, 0xFFFFFF) 는 검은색을 녹색으로 변경하고 흰색은 그대로 둡니다.

tint_with(0xFF0000, 0x0000FF) 는 검은색을 빨간색으로, 흰색을 파란색으로 변경합니다.

gamma_with(gamma)¶

픽스맵에 감마 계수를 적용합니다. 즉, 밝게 하거나 어둡게 합니다. 색상 공간이 None 인 픽스맵은 경고와 함께 무시됩니다.

매개변수:: gamma (float) – gamma = 1.0 은 아무것도 하지 않으며, gamma < 1.0 은 밝게 하고, gamma > 1.0 은 이미지를 어둡게 합니다.

shrink(n)¶

너비와 높이를 모두 2:sup:n 으로 나누어 픽스맵을 축소합니다.

매개변수:: n (int) – 새 픽스맵(samples) 크기를 결정합니다. 예를 들어 값 2는 너비와 높이를 4로 나누어 원본의 16^{분의 1} 크기로 만듭니다. 1보다 작은 값은 경고와 함께 무시됩니다.

참고

이 메서드를 사용하여 비율을 유지하면서 픽스맵의 크기를 줄입니다. 픽스맵은 “제자리에서” 변경됩니다. 원본을 유지하고 더 세밀한 선택을 원하면 위의 해당 복사 생성자를 사용하세요.

pixel(x, y)¶

버전 1.14.5의 새로운 기능: 위치 (x, y)(열, 줄)의 픽셀 값을 반환합니다.

매개변수:

x (int) – 픽셀의 열 번호. range(pix.width) 에 있어야 합니다.
y (int) – 픽셀의 줄 번호. range(pix.height) 에 있어야 합니다.

반환 형식:

list

반환:

색상 값 및 잠재적으로 알파 값의 목록. 길이와 내용은 픽스맵의 색상 공간과 알파의 존재에 따라 다릅니다. RGBA 픽스맵의 경우 결과는 예를 들어 [r, g, b, a] 가 됩니다. 모든 항목은 range(256) 의 정수입니다.

set_pixel(x, y, color)¶

버전 1.14.7의 새로운 기능: 위치 (x, y)(열, 줄)의 픽셀을 조작합니다.

매개변수:

x (int) – 픽셀의 열 번호. range(pix.width) 에 있어야 합니다.
y (int) – 픽셀의 줄 번호. range(pix.height) 에 있어야 합니다.
color (sequence) – range(256) 의 정수 시퀀스로 주어진 원하는 픽셀 값. 시퀀스의 길이는 알파 바이트를 포함하여 Pixmap.n 과 같아야 합니다.

set_rect(irect, color)¶

버전 1.14.8의 새로운 기능: 사각형의 픽셀을 값으로 설정합니다.

매개변수:

irect (irect_like) – 값으로 채울 사각형. 실제 영역은 이 매개변수와 Pixmap.irect 의 교집합입니다. 빈 교집합(또는 잘못된 매개변수)의 경우 변경이 발생하지 않습니다.
color (sequence) – range(256) 의 정수 시퀀스로 주어진 원하는 값. 시퀀스의 길이는 알파 바이트를 포함하여 Pixmap.n 과 같아야 합니다.

반환 형식:

bool

반환:

사각형이 유효하지 않거나 Pixmap.irect 와 빈 교집합이 있으면 False, 그렇지 않으면 True.

참고

이 메서드는 사각형의 각 픽셀에 대해 실행되는 Pixmap.set_pixel() 과 동일하지만 많은 픽셀이 관련된 경우 훨씬 빠릅니다.
이 메서드는 Pixmap.clear_with() 와 유사하게 사용하여 픽스맵을 특정 색상으로 초기화할 수 있습니다: pix.set_rect(pix.irect, (255, 255, 0)) (RGB 예제, 전체 픽스맵을 노란색으로 칠함).

set_origin(x, y)¶

v1.17.7에서 새로 추가됨

픽스맵의 왼쪽 위 점의 x 및 y 값을 설정합니다.

매개변수:

x (int) – x 좌표
y (int) – y 좌표

set_dpi(xres, yres)¶

v1.16.17에서 새로 추가됨
v1.18.0에서 변경됨: PNG 이미지로 저장할 때 이 값들이 이제 저장됩니다.

x 및 y 방향의 해상도(dpi)를 설정합니다.

매개변수:

xres (int) – x 방향 해상도.
yres (int) – y 방향 해상도.

set_alpha(alphavalues, premultiply=1, opaque=None)¶

v1.18.13에서 변경됨

알파 값을 변경합니다. 픽스맵은 알파 채널을 가져야 합니다.

매개변수:

alphavalues (bytes,bytearray,BytesIO) – 새 알파 값. 제공된 경우 길이는 최소 width * height 여야 합니다. 생략(None)하면 모든 알파 값이 255(투명도 없음)로 설정됩니다. 버전 1.14.13에서 변경됨: 이제 io.BytesIO 도 허용됩니다.
premultiply (bool) – v1.18.13의 새로운 기능: 색상 구성 요소를 알파 값으로 사전 곱셈할지 여부.
opaque (list,tuple) – 알파 값을 무시하고 이 색상을 완전히 투명하게 설정합니다. Pixmap.n 길이의 range(256) 정수 시퀀스. 기본값은 None 입니다. 예를 들어 RGB의 일반적인 선택은 opaque=(255, 255, 255) (흰색)입니다.

invert_irect([irect])¶

IRect irect 의 모든 픽셀 색상을 반전합니다. 색상 공간이 None 이면 효과가 없습니다.

매개변수:: irect (irect_like) – 반전할 영역. 생략하면 모든 것을 반전합니다.

copy(source, irect)¶

source 픽스맵의 irect 부분을 이 픽스맵의 해당 영역에 복사합니다. 두 픽스맵은 다른 크기를 가질 수 있으며 각각 CS_GRAY 또는 CS_RGB 색상 공간을 가질 수 있지만 현재 반드시 동일한 알파 속성을 가져야 합니다 [2]. 복사 메커니즘은 다음과 같이 소스와 대상 간의 차이를 자동으로 조정합니다:

CS_GRAY 에서 CS_RGB 로 복사하는 경우, 소스 그레이 음영 값이 세 개의 RGB 구성 요소 바이트 각각에 배치됩니다. 반대의 경우, (r + g + b) / 3 이 대상의 그레이 음영 값으로 사용됩니다.

irect 와 대상 픽스맵의 사각형 사이에서 먼저 “교집합”이 계산됩니다. 이것은 사각형 좌표와 현재 속성 값 Pixmap.x 및 Pixmap.y (이 목적을 위해 Pixmap.set_origin() 을 통해 자유롭게 수정할 수 있음)를 고려합니다. 그런 다음 이 교집합의 해당 데이터가 복사됩니다. 교집합이 비어 있으면 아무 일도 발생하지 않습니다.

매개변수:

source (Pixmap) – 소스 픽스맵.
irect (irect_like) – 복사할 영역.

참고

예제: 두 개의 픽스맵 pix1 과 pix2 가 있고 pix2 의 오른쪽 아래 사분면을 pix1 의 왼쪽 위 지점에서 시작하도록 pix1 에 복사하려는 경우 다음 스니펫을 사용하세요:

>>> # safeguard: set top-left of pix1 and pix2 to (0, 0)
>>> pix1.set_origin(0, 0)
>>> pix2.set_origin(0, 0)
>>> # compute top-left coordinates of pix2 region to copy
>>> x1 = int(pix2.width / 2)
>>> y1 = int(pix2.height / 2)
>>> # shift top-left of pix2 such, that the to-be-copied
>>> # area starts at (0, 0):
>>> pix2.set_origin(-x1, -y1)
>>> # now copy ...
>>> pix1.copy(pix2, (0, 0, x1, y1))

save(filename, output=None, jpg_quality=95)¶

v1.22.0에서 변경됨: JPEG 이미지 직접 지원 이 추가되었습니다. 이미지 품질은 “jpg_quality” 매개변수를 통해 제어할 수 있습니다.

픽스맵을 이미지 파일로 저장합니다. 선택한 출력에 따라 일부 또는 모든 색상 공간이 지원되며 다른 파일 확장자를 선택할 수 있습니다. 아래 표를 참조하세요.

매개변수:

filename (str,Path,file) – 저장할 파일. 문자열, pathlib.Path 또는 Python 파일 객체로 제공할 수 있습니다. 후자 두 경우에는 파일 이름이 해당 객체에서 가져옵니다. 파일 이름의 확장자는 이미지 형식을 결정하며, output 매개변수로 재정의할 수 있습니다.
output (str) – 원하는 이미지 형식. 기본값은 파일 이름의 확장자입니다. 이 값과 파일 확장자가 모두 지원되지 않으면 예외가 발생합니다. 가능한 값은 지원되는 출력 이미지 형식 을 참조하세요.
jpg_quality (int) – 원하는 이미지 품질, 기본값 95. JPEG 이미지에만 적용되며, 그렇지 않으면 무시됩니다. 이 매개변수는 품질과 파일 크기를 교환합니다. 값 98은 무손실에 가깝습니다. 더 높은 값이 더 나은 품질로 이어지지는 않습니다.

예외 발생:

ValueError – 지원되지 않는 이미지 형식의 경우.

tobytes(output='png', jpg_quality=95)¶

버전 1.14.5의 새로운 기능: 지정된 형식의 bytes 메모리 객체로 픽스맵을 반환합니다 – save() 와 유사합니다.
v1.22.0에서 변경됨: 직접 JPEG 지원 이 추가되었습니다. 이미지 품질은 새로운 매개변수 “jpg_quality”를 통해 조정할 수 있습니다.

매개변수:

output (str) – 원하는 이미지 형식. 기본값은 “png”입니다. 가능한 값은 지원되는 출력 이미지 형식 을 참조하세요.
jpg_quality (int) – 원하는 이미지 품질, 기본값 95. JPEG 이미지에만 적용되며, 그렇지 않으면 무시됩니다. 이 매개변수는 품질과 파일 크기를 교환합니다. 값 98은 무손실에 가깝습니다. 더 높은 값이 더 나은 품질로 이어지지는 않습니다.
output – 요청된 이미지 형식. 기본값은 “png”입니다. 다른 가능한 값은 지원되는 출력 이미지 형식 을 참조하세요.

예외 발생:

ValueError – 지원되지 않는 이미지 형식의 경우.

반환 형식:

bytes

pdfocr_save(filename, compress=True, language='eng', tessdata=None)¶

v1.19.0에서 새로 추가됨
v1.22.5에서 변경됨: Tesseract의 tessdata에 대한 새로운 매개변수 지원.

Tesseract를 사용하여 텍스트 인식을 수행하고 이미지를 OCR 텍스트 레이어가 있는 1페이지 PDF로 저장합니다.

매개변수:

filename (str,fp) – 저장할 파일을 식별합니다. 문자열 또는 “wb”로 열린 파일에 대한 포인터(io.BytesIO() 객체 포함)일 수 있습니다.
compress (bool) – 결과 PDF를 압축할지 여부, 기본값은 True 입니다.
language (str) – 이미지에 나타나는 언어. Tesseract 형식으로 지정해야 합니다. 기본값은 영어의 경우 “eng”입니다. 여러 언어의 경우 “+”로 구분된 Tesseract 언어 코드를 사용하세요(예: 영어와 스페인어의 경우 “eng+spa”).
tessdata (str) – Tesseract의 언어 지원 폴더 이름. 생략된 경우 이 정보는 환경 변수 TESSDATA_PREFIX 로 존재해야 합니다.

참고

Tesseract가 설치되지 않았거나 환경 변수 “TESSDATA_PREFIX”가 tessdata 폴더 이름으로 설정되지 않고 매개변수로 제공되지 않으면 실패합니다.

pdfocr_tobytes(compress=True, language='eng', tessdata=None)¶

v1.19.0에서 새로 추가됨
v1.22.5에서 변경됨: Tesseract의 tessdata에 대한 새로운 매개변수 지원.

Tesseract를 사용하여 텍스트 인식을 수행하고 이미지를 OCR 텍스트 레이어가 있는 1페이지 PDF로 변환합니다. 내부적으로 Pixmap.pdfocr_save() 를 호출합니다.

반환:

메모리의 1페이지 PDF 파일. doc=pymupdf.open("pdf", pix.pdfocr_tobytes()) 와 같이 열 수 있으며, page=doc[0] 에서 텍스트 추출을 수행할 수 있습니다.

참고

다른 가능한 사용법은 일부 PDF에 삽입하는 것입니다. 다음 스니펫은 폴더의 이미지를 읽어 OCR 텍스트 레이어가 포함된 새 PDF의 페이지로 저장합니다:

doc = pymupdf.open()
for imgfile in os.listdir(folder):
   pix = pymupdf.Pixmap(imgfile)
   imgpdf = pymupdf.open("pdf", pix.pdfocr_tobytes())
   doc.insert_pdf(imgpdf)
   pix = None
   imgpdf.close()
doc.save("ocr-images.pdf")

pil_image()¶

픽스맵에서 Pillow 이미지를 생성합니다. PIL / Pillow가 설치되어 있어야 합니다.

예외 발생:: ImportError – Pillow가 설치되지 않은 경우.
반환:: PIL.Image 객체

pil_save(*args, unmultiply=False, **kwargs)¶

Pillow를 사용하여 픽스맵을 이미지 파일로 씁니다. MuPDF에서 지원하지 않는 출력에 이 메서드를 사용하세요. 예는 다음과 같습니다

JPX, J2K, WebP 등의 형식.
EXIF 정보 저장.
dpi 정보를 제공하지 않으면 픽스맵에 저장된 xres, yres 값이 자동으로 사용됩니다.

간단한 예제: pix.pil_save("some.webp", optimize=True, dpi=(150, 150)).

매개변수:: unmultiply (bool) – 픽스맵의 색상 공간이 투명도가 있는 RGB인 경우, 알파 값이 이미 색상 구성 요소 빨강/녹색/파랑(소위 “사전 곱셈”)에 곱해져 있을 수도 있고 아닐 수도 있습니다. 사전 곱셈을 취소하려면 이 매개변수를 True 로 설정하세요. 배경에 대한 자세한 내용은 예를 들어 이 페이지 에서 “Premultiplied alpha” 를 찾아보세요.

다른 매개변수에 대한 자세한 내용은 Pillow 문서를 참조하세요.

v1.22.0부터 PyMuPDF는 JPEG 출력을 직접 지원합니다. 성능상의 이유와 불필요한 외부 종속성을 피하기 위해 JPEG 출력에는 이 메서드를 더 이상 사용하지 않는 것을 권장합니다.

예외 발생:: ImportError – Pillow가 설치되지 않은 경우.

pil_tobytes(*args, unmultiply=False, **kwargs)¶

v1.17.3에서 새로 추가됨

Pillow를 사용하여 지정된 형식의 bytes 객체로 이미지를 반환합니다. 예를 들어 stream = pix.pil_tobytes(format="WEBP", optimize=True, dpi=(150, 150)). 위 내용도 참조하세요. 다른 매개변수에 대한 자세한 내용은 Pillow 문서를 참조하세요.

예외 발생:: ImportError – Pillow가 설치되지 않은 경우.
반환 형식:: bytes

warp(quad, width, height)¶

v1.19.3에서 새로 추가됨

quad를 “왜곡”하여 quad 모서리가 새 픽스맵의 모서리가 되도록 새 픽스맵을 반환합니다. 대상 픽스맵의 IRect 는 (0, 0, width, height) 가 됩니다.

매개변수:

quad (quad_like) – Pixmap.irect 내부(경계 점 포함)에 좌표가 있는 볼록 quad.
width (int) – 원하는 결과 너비.
height (int) – 원하는 결과 높이.

반환:

quad 모서리가 시계 방향으로 픽스맵 모서리에 매핑된 새 픽스맵: quad.ul -> irect.tl, quad.ur -> irect.tr 등.

반환 형식:

Pixmap

color_count(colors=False, clip=None)¶

v1.19.2에서 새로 추가됨
v1.19.3에서 변경됨

픽스맵의 고유 색상과 개수를 확인합니다.

매개변수:

colors (bool) – (v1.19.3에서 변경됨) True 이면 색상 픽셀과 사용 횟수의 딕셔너리를 반환하고, 그렇지 않으면 고유 색상의 개수만 반환합니다.
clip (rect_like) – Pixmap.irect 내부의 사각형. 제공된 경우 해당 픽셀만 고려됩니다. 이를 통해 하위 픽스맵을 구축하는 대신 주어진 픽스맵의 하위 사각형을 직접 검사할 수 있습니다.

반환 형식:

dict or int

반환:

색상 개수 또는 pixel: count 항목이 있는 딕셔너리. 픽셀 키는 Pixmap.n 길이의 bytes 객체입니다.

참고

픽셀의 튜플 을 복구하려면 i번째 항목에 대해 tuple(colors.keys()[i]) 를 사용하세요.

응답 시간은 픽스맵의 samples 크기에 따라 달라지며 매우 큰 픽스맵의 경우 1초 이상 걸릴 수 있습니다.
해당되는 경우 다른 알파 값을 가진 픽셀은 다른 색상으로 처리됩니다.

color_topusage(clip=None)¶

v1.19.3에서 새로 추가됨

가장 자주 사용되는 색상과 상대적 빈도를 반환합니다.

매개변수:: clip (rect_like) – Pixmap.irect 내부의 사각형. 제공된 경우 해당 픽셀만 고려됩니다. 이를 통해 하위 픽스맵을 구축하는 대신 주어진 픽스맵의 하위 사각형을 직접 검사할 수 있습니다.
반환 형식:: tuple
반환:: 0 < ratio <= 1 이고 pixel 이 색상의 픽셀 값인 튜플 (ratio, pixel). 이를 사용하여 이미지가 “거의” 단색인지 결정하세요: 응답 (0.95, b"x00x00x00") 는 모든 픽셀의 95%가 검은색임을 의미합니다. 예제는 픽스맵 사용 방법: 텍스트 가시성 확인 를 참조하세요.

alpha¶

픽스맵에 투명도 정보가 포함되어 있는지 나타냅니다.

Type:: bool

digest¶

픽스맵의 MD5 해시코드(16바이트). 고유 식별에 사용되는 기술적 값입니다.

Type:: bytes

colorspace¶

픽스맵의 색상 공간. 이미지가 소위 이미지 마스크 또는 스텐실 마스크 로 처리되는 경우(현재 추출된 PDF 문서 이미지에만 적용) 이 값은 None 일 수 있습니다.

Type:: Colorspace (색 공간)

stride¶

Pixmap.samples 의 이미지 데이터 한 행의 길이를 포함합니다. 주로 계산 목적으로 사용됩니다. 다음 표현식이 참입니다:

len(samples) == height * stride
width * n == stride

Type:: int

is_monochrome¶

v1.19.2에서 새로 추가됨

검은색과 흰색만 있는 그레이 픽스맵에 대해 True 입니다.

Type:: bool

is_unicolor¶

v1.19.2에서 새로 추가됨

모든 픽셀이 동일한 경우(모든 색상 공간) True 입니다. 해당되는 경우 다른 알파 값을 가진 픽셀은 다른 색상으로 처리됩니다.

Type:: bool

irect¶

픽스맵의 IRect 를 포함합니다.

Type:: IRect

samples¶

모든 픽셀의 색상 및 (Pixmap.alpha 가 true인 경우) 투명도 값. width * height * n 바이트 영역입니다. 각 n 바이트는 하나의 픽셀을 정의합니다. 연속된 각 n 바이트는 스캔라인 순서로 또 다른 픽셀을 생성합니다. 후속 스캔라인은 패딩 없이 서로 이어집니다. 예를 들어 RGBA 색상 공간의 경우, samples 는 …, R, G, B, A, … 와 같은 바이트 시퀀스이며, 네 개의 바이트 값 R, G, B, A가 하나의 픽셀을 정의합니다.

이 영역은 PIL(Python Imaging Library)과 같은 다른 그래픽 라이브러리에 전달하여 다른 이미지 형식으로 픽스맵을 저장하는 등의 추가 처리를 수행할 수 있습니다.

참고

기본 데이터는 일반적으로 큰 메모리 영역이며, 이 속성에 접근할 때마다 bytes 복사본이 생성됩니다: 예를 들어 RGB로 렌더링된 레터 페이지는 samples 크기가 거의 1.4MB입니다. 따라서 새 변수에 할당하거나 memoryview 버전 Pixmap.samples_mv (v1.18.17에서 새로 추가됨)를 사용하세요.
기본 데이터에 대한 모든 변경 사항은 이 속성에 다시 접근한 후에만 사용할 수 있습니다. 이것은 memoryview 버전을 사용하는 것과 다릅니다.

Type:: bytes

samples_mv¶

v1.18.17에서 새로 추가됨

Pixmap.samples 와 유사하지만 Python memoryview 형식입니다. 픽스맵의 메모리를 가리키도록 구축됩니다 – 복사본이 아닙니다. 따라서 생성 속도는 픽스맵 크기와 무관하며 픽셀에 대한 모든 변경 사항이 즉시 사용 가능합니다.

bytearray(pix.samples_mv) 또는 bytes(pixmap.samples_mv) 와 같은 복사본은 pix.samples 와 동일하며 대신 사용할 수 있습니다.

We also have len(pix.samples) == len(pix.samples_mv).

2MB JPEG의 이 예제를 보세요: memoryview가 만 배 빠릅니다:

In [3]: %timeit len(pix.samples_mv)
367 ns ± 1.75 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)
In [4]: %timeit len(pix.samples)
3.52 ms ± 57.5 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)

Pixmap이 파괴된 후 memoryview를 사용하려는 시도는 ValueError로 실패합니다.

Type:: memoryview

samples_ptr¶

v1.18.17에서 새로 추가됨

픽셀 영역에 대한 Python 포인터. 이것은 지원 애플리케이션(예: PyQt)이 samples 영역을 직접 주소 지정하여 이미지를 매우 빠르게 구축할 수 있도록 하는 특수 정수 형식입니다. 예제:

img = QtGui.QImage(pix.samples, pix.width, pix.height, format) # (1)
img = QtGui.QImage(pix.samples_ptr, pix.width, pix.height, format) # (2)

위의 두 가지 모두 동일한 Qt 이미지를 생성하지만 (2)는 픽셀 영역의 추가 복사를 피하기 때문에 수백 배 빠를 수 있습니다.

경고: Pixmap이 파괴된 후 Python 포인터는 무효화되며 사용을 시도하면 Python 인터프리터가 충돌할 수 있습니다.

Type:: int

size¶

len(pixmap) 을 포함합니다. 이것은 일반적으로 len(pix.samples) 에 객체의 다른 속성을 정의하는 플랫폼별 값을 더한 것과 같습니다.

Type:: int

width¶

w¶

픽셀 단위의 영역 너비.

Type:: int

height¶

h¶

픽셀 단위의 영역 높이.

Type:: int

x¶

픽셀 단위의 왼쪽 위 모서리 X 좌표. 직접 변경할 수 없습니다 – Pixmap.set_origin() 을 사용하세요.

Type:: int

y¶

픽셀 단위의 왼쪽 위 모서리 Y 좌표. 직접 변경할 수 없습니다 – Pixmap.set_origin() 을 사용하세요.

Type:: int

n¶

픽셀당 구성 요소 수. 이 숫자는 색상 공간과 알파에 따라 다릅니다. 색상 공간이 None 이 아니면(스텐실 마스크) Pixmap.n - Pixmap.alpha == pixmap.colorspace.n 이 참입니다. 색상 공간이 None 이면 n == alpha == 1 입니다.

Type:: int

xres¶

dpi(인치당 도트) 단위의 수평 해상도. resolution 도 참조하세요. 직접 변경할 수 없습니다 – Pixmap.set_dpi() 를 사용하세요.

Type:: int

yres¶

dpi(인치당 도트) 단위의 수직 해상도. resolution 도 참조하세요. 직접 변경할 수 없습니다 – Pixmap.set_dpi() 를 사용하세요.

Type:: int

interpolate¶

이미지가 “선형 보간”을 사용하여 그려지면 True 로 설정되는 정보 전용 불리언 플래그. False 이면 “최근접 샘플링”이 사용됩니다.

Type:: bool

지원되는 입력 이미지 형식¶

다음 파일 유형은 픽스맵을 구성하기 위한 입력 으로 지원됩니다: BMP, JPEG, GIF, TIFF, JXR, JPX, PNG, PAM 및 모든 Portable Anymap 패밀리(PBM, PGM, PNM, PPM). 이 지원은 두 가지 방식입니다:

Pixmap(filename) 또는 Pixmap(bytearray) 로 직접 픽스맵을 생성합니다. 픽스맵은 이미지에 의해 결정된 속성을 갖게 됩니다.
pymupdf.open(…) 로 이러한 파일을 엽니다. 결과는 단일 페이지를 포함하는 문서로 나타납니다. 이 페이지의 픽스맵을 생성하면 이 컨텍스트에서 사용 가능한 모든 옵션을 제공합니다: 행렬 적용, 색상 공간 및 알파 선택, 픽스맵을 클립 영역으로 제한 등.

SVG 이미지 는 위의 방법 2를 통해서만 지원되며 픽스맵으로 직접 지원되지 않습니다. 하지만 기억하세요: 이것의 결과는 픽스맵의 경우처럼 항상 래스터 이미지 입니다 [1].

지원되는 출력 이미지 형식¶

다수의 이미지 출력 형식이 지원됩니다. 이미지를 파일에 직접 쓰기(Pixmap.save()) 또는 bytes 객체 생성(Pixmap.tobytes()) 중 선택할 수 있습니다. 두 메서드 모두 원하는 형식을 식별하는 문자열(아래 Format 열)을 허용합니다. 픽스맵 색상 공간, 투명도 지원(알파) 및 이미지 형식의 모든 조합이 가능한 것은 아닙니다.

Format	Colorspaces	alpha	Extensions	Description
jpg, jpeg	gray, rgb, cmyk	no	.jpg, .jpeg	Joint Photographic Experts Group
pam	gray, rgb, cmyk	yes	.pam	Portable Arbitrary Map
pbm	gray, rgb	no	.pbm	Portable Bitmap
pgm	gray, rgb	no	.pgm	Portable Graymap
png	gray, rgb	yes	.png	Portable Network Graphics
pnm	gray, rgb	no	.pnm	Portable Anymap
ppm	gray, rgb	no	.ppm	Portable Pixmap
ps	gray, rgb, cmyk	no	.ps	Adobe PostScript Image
psd	gray, rgb, cmyk	yes	.psd	Adobe Photoshop Document

참고

모든 OS 플랫폼에서 모든 이미지 파일 유형이 지원되거나 일반적이지는 않습니다. 예를 들어 PAM 및 Portable Anymap 형식은 Windows에서 드물거나 알려지지 않았습니다.
특히 CMYK 색상 공간에 대해 항상 rgb_pix = pymupdf.Pixmap(pymupdf.csRGB, cmyk_pix) 로 CMYK 픽스맵을 RGB 픽스맵으로 변환한 다음 원하는 형식으로 저장할 수 있습니다.
볼 수 있듯이 MuPDF의 이미지 지원 범위는 입력과 출력에 따라 다릅니다. 양쪽 모두 지원되는 것 중에서 PNG와 JPEG가 가장 인기 있을 것입니다.
tkinter의 PhotoImage 메서드에 입력으로 “ppm” 형식을 사용하는 것도 권장합니다: tkimg = tkinter.PhotoImage(data=pix.tobytes(“ppm”)) (튜토리얼도 참조). 이것은 매우 빠릅니다(PNG보다 60배 빠름).

Footnotes

This software is provided AS-IS with no warranty, either express or implied. This software is distributed under license and may not be copied, modified or distributed except as expressly authorized under the terms of that license. Refer to licensing information at artifex.com or contact Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States for further information.