TextWriter (텍스트 라이터)¶

This class is for PDF only.

v1.16.18에서 새로 추가됨

이 클래스는 MuPDF text 객체를 나타냅니다. 기본 아이디어는 (1) 텍스트 준비와 (2) PDF 페이지로의 텍스트 출력을 분리 하는 것입니다.

준비 중에 텍스트 라이터는 임의의 수의 텍스트 조각(“스팬”)을 위치 및 개별 글꼴 정보와 함께 저장합니다. 라이터의 준비된 콘텐츠의 출력 은 호환되는 페이지 크기를 가진 모든 PDF 페이지에 여러 번 수행될 수 있습니다.

텍스트 라이터는 Page.insert_text() 및 유사한 메서드에 대한 우아한 대안입니다:

개선된 텍스트 위치 지정: 텍스트 삽입이 시작되어야 하는 임의의 지점을 선택합니다. 텍스트 저장은 스팬의 마지막 문자 이후의 “커서 위치”를 반환합니다.
자유로운 글꼴 선택: 각 텍스트 스팬은 자체 글꼴과 fontsize 를 가집니다. 이를 통해 더 큰 텍스트를 구성할 때 쉽게 전환할 수 있습니다.
자동 대체 글꼴: 선택한 글꼴이 문자를 지원하지 않으면 대체 글꼴이 자동으로 검색됩니다. 이는 출력에서 인쇄할 수 없는 기호(“TOFUs” – 작은 사각형처럼 보임)를 볼 위험을 크게 줄입니다. PyMuPDF 는 이제 모든 라틴 문자(키릴 문자 및 그리스 문자 포함)와 모든 CJK 문자(중국어, 일본어, 한국어)를 지원하는 범용 글꼴 “Droid Sans Fallback Regular” 를 제공합니다.
키릴 문자 및 그리스 문자 지원: PDF Base 14 글꼴 는 인코딩을 지정하지 않고 키릴 문자 및 그리스 문자에 대한 통합 지원을 제공합니다. 텍스트는 라틴 문자, 그리스 문자 및 키릴 문자의 혼합일 수 있습니다.
투명도 지원: opacity 매개변수가 지원됩니다. 이를 통해 워터마크 스타일의 텍스트를 만드는 편리한 방법을 제공합니다.
양쪽 정렬 텍스트: Page.insert_textbox() 와 같은 단순 글꼴뿐만 아니라 모든 글꼴에 대해 지원됩니다.
재사용성: TextWriter 객체는 PDF 페이지와 독립적으로 존재합니다. 동일한 페이지 또는 다른 페이지, 동일한 PDF 또는 다른 PDF에 여러 번 작성할 수 있으며, 다른 색상이나 투명도를 선택할 수 있습니다.

이 객체를 사용하려면 세 단계가 필요합니다:

생성 시 TextWriter는 텍스트 위치를 계산하기 위한 고정된 페이지 사각형 이 필요합니다. 텍스트 라이터는 이 크기의 페이지에만 쓸 수 있습니다.
원하는 만큼 TextWriter.append(), TextWriter.appendv() 및 TextWriter.fill_textbox() 메서드를 사용하여 TextWriter에 텍스트를 저장합니다.
일부 PDF 페이지에 TextWriter 객체를 출력합니다.

참고

버전 1.17.0부터 TextWriter는 TextWriter.write_text() 의 morph 매개변수를 통한 텍스트 회전을 지원합니다.
Page.write_text() 도 존재하며, 하나 이상의 TextWriter를 결합하여 주어진 사각형과 주어진 회전 각도로 공동으로 작성합니다 – Page.show_pdf_page() 와 매우 유사합니다.

메서드 / 속성	간략 설명
`append()`	수평 쓰기 모드에서 텍스트 추가
`appendv()`	수직 쓰기 모드에서 텍스트 추가
`fill_textbox()`	사각형 채우기 (수평 쓰기 모드)
`write_text()`	TextWriter를 PDF 페이지로 출력
`color`	텍스트 색상 (변경 가능)
`last_point`	마지막으로 작성된 문자가 여기서 끝남
`opacity`	텍스트 투명도 (변경 가능)
`rect`	이 TextWriter가 사용하는 페이지 사각형
`text_rect`	지금까지 차지한 영역

클래스 API

class TextWriter¶

__init__(self, rect, opacity=1, color=None)¶

매개변수:

rect (rect-like) – 텍스트 위치 계산에 내부적으로 사용되는 사각형.
opacity (float) – 여기에 저장할 텍스트의 투명도를 설정합니다. [0, 1) 구간 밖의 값은 무시됩니다. 예를 들어 0.5 값은 50% 투명도를 의미합니다.
color (float,sequ) – 텍스트의 색상. 모든 색상은 부동 소수점 0 <= color <= 1 로 지정됩니다. 단일 부동 소수점은 일부 회색 레벨을 나타내고, 시퀀스는 길이를 통해 색 공간을 암시합니다.

append(pos, text, font=None, fontsize=11, language=None, right_to_left=False, small_caps=0)¶

v1.18.9에서 변경됨
v1.18.15에서 변경됨

수평 쓰기로 일부 새 텍스트를 추가합니다.

매개변수:

pos (point_like) – 텍스트의 시작 위치, 첫 번째 문자의 왼쪽 하단 점.
text (str) – 임의 길이의 문자열. “pos” 위치에서 시작하여 작성됩니다.
font – Font. 생략하면 pymupdf.Font("helv") 가 사용됩니다.
fontsize (float) – fontsize, 양수, 기본값 11.
language (str) – 사용할 언어, 예: 영어의 경우 “en”. 의미 있는 값은 ISO 639 표준 1, 2, 3 또는 5를 준수해야 합니다. 향후 사용을 위해 예약됨: 현재로서는 알려진 바에 따르면 효과가 없습니다.
right_to_left (bool) – (v1.18.9에서 새로 추가) 텍스트를 오른쪽에서 왼쪽으로 작성할지 여부. 아랍어나 히브리어와 같은 언어에 적용됩니다. 기본값은 False 입니다. True 인 경우 텍스트 내의 모든 라틴 문자 부분이 자동으로 변환됩니다. 다른 결과는 없습니다. 즉, TextWriter.last_point 는 여전히 가장 오른쪽 문자이며 정렬도 수행되지 않습니다. 따라서 TextWriter.fill_textbox() 를 대신 사용하는 것이 좋을 수 있습니다.
small_caps (bool) –
(v1.18.15에서 새로 추가) 글꼴에서 문자의 작은 대문자 버전을 찾습니다. 존재하면 해당 값을 사용합니다. 그렇지 않으면 원래 문자(이 글꼴 또는 대체 글꼴)가 사용됩니다. 대체 글꼴은 작은 대문자를 반환하지 않습니다. 예를 들어, 이 코드 조각:
```
>>> doc = pymupdf.open()
>>> page = doc.new_page()
>>> text = "PyMuPDF: the Python bindings for MuPDF"
>>> font = pymupdf.Font("figo")  # choose a font with small caps
>>> tw = pymupdf.TextWriter(page.rect)
>>> tw.append((50,100), text, font=font, small_caps=True)
>>> tw.write_text(page)
>>> doc.ez_save("x.pdf")
```
이 PDF 텍스트를 생성합니다:

반환:

text_rect 및 last_point. (v1.18.0에서 변경:) 지원되지 않는 글꼴에 대해 예외를 발생시킵니다 – Font.is_writable 을 통해 확인됩니다.

appendv(pos, text, font=None, fontsize=11, language=None, small_caps=0)¶

v1.18.15에서 변경됨

수직, 위에서 아래로 쓰기로 일부 새 텍스트를 추가합니다.

매개변수:

pos (point_like) – 텍스트의 시작 위치, 첫 번째 문자의 왼쪽 하단 점.
text (str) – 문자열. “pos” 위치에서 시작하여 작성됩니다.
font – Font. 생략하면 pymupdf.Font("helv") 가 사용됩니다.
fontsize (float) – fontsize, 양수 부동 소수점, 기본값 11.
language (str) – 사용할 언어, 예: 영어의 경우 “en”. 의미 있는 값은 ISO 639 표준 1, 2, 3 또는 5를 준수해야 합니다. 향후 사용을 위해 예약됨: 현재로서는 알려진 바에 따르면 효과가 없습니다.
small_caps (bool) – (v1.18.15에서 새로 추가) append() 를 참조하세요.

반환:

text_rect 및 last_point. (v1.18.0에서 변경:) 지원되지 않는 글꼴에 대해 예외를 발생시킵니다 – Font.is_writable 을 통해 확인됩니다.

fill_textbox(rect, text, *, pos=None, font=None, fontsize=11, align=0, right_to_left=False, warn=None, small_caps=0)¶

1.17.3에서 변경: 사각형 내에서 쓰기를 시작할 위치를 지정하는 새 매개변수 pos.
v1.18.9에서 변경: 사각형에 맞지 않는 줄 목록을 반환합니다. 오른쪽에서 왼쪽으로 쓰기 지원(예: 아랍어, 히브리어).
v1.18.15에서 변경: 글꼴에서 지원하는 경우 작은 대문자를 선호합니다.

수평 쓰기 모드로 주어진 사각형을 텍스트로 채웁니다. 이는 append() 의 대안으로 사용할 수 있는 편의 메서드입니다.

매개변수:

rect (rect_like) – 채울 영역. 텍스트의 어떤 부분도 이 영역 밖에 나타나지 않습니다.
text (str,sequ) – 텍스트. (UTF-8) 문자열 또는 문자열의 리스트/튜플로 지정할 수 있습니다. 문자열은 먼저 splitlines() 를 사용하여 리스트로 변환됩니다. 각 리스트 항목은 새 줄에서 시작합니다(강제 줄바꿈).
pos (point_like) – (v1.17.3에서 새로 추가) 이 지점에서 저장을 시작합니다. 기본값은 사각형 왼쪽 상단 근처의 점입니다.
font – Font, 기본값 pymupdf.Font("helv").
fontsize (float) – fontsize.
align (int) – 텍스트 정렬. TEXT_ALIGN_LEFT, TEXT_ALIGN_CENTER, TEXT_ALIGN_RIGHT 또는 TEXT_ALIGN_JUSTIFY 중 하나를 사용합니다.
right_to_left (bool) – (v1.18.9에서 새로 추가) 텍스트를 오른쪽에서 왼쪽으로 작성할지 여부. 아랍어나 히브리어와 같은 언어에 적용됩니다. 기본값은 False 입니다. True 인 경우 모든 라틴 문자 부분이 자동으로 반전됩니다. 정렬(오른쪽 정렬을 원하는 경우)을 여전히 설정해야 하며, 자동으로 발생하지 않습니다 – 다른 정렬 옵션도 계속 사용할 수 있습니다.
warn (bool) –
on text overflow do nothing (None), warn (True), or raise an exception (False). Overflow text will never be written. Changed in v1.18.9:
- 기본값은 None 입니다.
- 오버플로우 줄 목록이 반환됩니다.
- When None or True the partial text will be written.
- When False, and an exception is raised, the text will not be written.
small_caps (bool) – (v1.18.15에서 새로 추가) append() 를 참조하세요.

반환 형식:

list

반환:

v1.18.9에서 새로 추가 – 사각형에 맞지 않는 줄 목록. 각 항목은 문자열과 그 길이(페이지에서)를 포함하는 튜플 (text, length) 입니다.

참고

필요한 만큼 자주 이 메서드를 사용하세요 – 기술적 제한은 없습니다(시스템의 메모리 제약 제외). append() 와 텍스트 상자를 혼합하고 둘 다 여러 개를 가질 수 있습니다. 텍스트 위치 지정은 삽입 지점에 의해서만 제어됩니다. 따라서 순서를 따를 필요가 없습니다. (v1.18.0에서 변경:) 지원되지 않는 글꼴에 대해 예외를 발생시킵니다 – Font.is_writable 을 통해 확인됩니다.

write_text(page, opacity=None, color=None, morph=None, overlay=True, oc=0, render_mode=0)¶

TextWriter 텍스트를 페이지에 작성합니다. 이는 유일한 필수 매개변수입니다. 다른 매개변수는 TextWriter가 생성될 때 사용된 값을 임시로 재정의하는 데 사용할 수 있습니다.

매개변수:

page – 이 Page 에 작성합니다.
opacity (float) – 이 출력에 대해 TextWriter의 값을 재정의합니다.
color (sequ) – 이 출력에 대해 TextWriter의 값을 재정의합니다.
morph (sequ) – 행렬을 적용하여 텍스트 모양을 수정합니다. 제공된 경우 이것은 점과 같은 fixpoint 와 행렬과 같은 matrix 를 가진 시퀀스 (fixpoint, matrix) 여야 합니다. 일반적인 예는 fixpoint 주위로 텍스트를 회전하는 것입니다.
overlay (bool) – 전경(기본값) 또는 배경에 배치합니다.
oc (int) – (v1.18.4에서 새로 추가) OCG 또는 OCMD 의 xref.
render_mode (int) –
PDF Tr 연산자 값. 값: 0 (기본값), 1, 2, 3 (보이지 않음).

text_rect¶

현재 차지하고 있는 영역.

반환 형식:: Rect

last_point¶

“커서 위치” – 마지막으로 작성된 문자(오른쪽 하단) 이후의 Point.

반환 형식:: Point

opacity¶

텍스트 투명도 (수정 가능).

반환 형식:: float

color¶

텍스트 색상 (수정 가능).

반환 형식:: float,tuple

rect¶

이 TextWriter가 생성된 페이지 사각형. 수정하면 안 됩니다.

반환 형식:: Rect

참고

TextWriter를 다루는 일부 데모 스크립트를 보려면 TextWriter 데모 스크립트 를 참조하세요.

투명도와 색상은 이 객체의 모든 텍스트 에 적용됩니다.
다른 색상/투명도가 필요한 경우 별도의 TextWriter를 생성해야 합니다. 색상이 변경되어야 한다고 판단할 때마다 이전에 반환된 last_point 를 새 텍스트 스팬의 위치로 사용하여 해당 TextWriter에 텍스트를 추가하세요.
항목이나 텍스트 상자를 추가하는 것은 임의의 순서로 발생할 수 있습니다: 위치 매개변수만 텍스트가 나타나는 위치를 제어합니다.
글꼴과 fontsize 는 동일한 TextWriter 내에서 자유롭게 변경할 수 있습니다. 이를 사용하여 다른 속성을 가진 텍스트가 동일한 표시 줄에 나타나도록 할 수 있습니다: pos 를 그에 따라 지정하고, 예를 들어 이전에 추가된 항목의 last_point 로 설정하세요.
TextWriter.fill_textbox() 의 pos 인수를 사용하여 첫 번째 텍스트 문자의 위치를 설정할 수 있습니다. 이를 통해 다른 TextWriter (텍스트 라이터) 객체의 콘텐츠로 동일한 텍스트 상자를 채울 수 있으므로 여러 색상, 투명도 등을 허용합니다.
MuPDF 는 이 기능으로 모든 글꼴을 지원하지 않습니다. 예를 들어 Type3 글꼴은 지원하지 않습니다. v1.18.0부터는 글꼴 속성 Font.is_writable 을 통해 이를 확인할 수 있습니다. 이 속성은 TextWriter (텍스트 라이터) 메서드를 사용할 때도 확인됩니다.

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.