Tools (ツール)#

このクラスは、メモリ管理を中心としたユーティリティメソッドと属性のコレクションです。使用を簡素化し、高速化するために、PyMuPDFがインポートされると、自動的に TOOLS という名前でインスタンス化されます。

メソッド/属性	説明
`Tools.gen_id()`	一意の識別子を生成します。
`Tools.store_shrink()`	格納可能キャッシュを縮小します [1]。
`Tools.mupdf_warnings()`	蓄積されたMuPDFの警告を返します。
`Tools.mupdf_display_errors()`	蓄積されたMuPDFの警告を返します。
`Tools.reset_mupdf_warnings()`	STDOUTのMuPDFメッセージを空にします。
`Tools.set_aa_level()`	アンチエイリアシングの値を設定します。
`Tools.set_annot_stem()`	新しい注釈/リンクIDのプレフィックスを設定します。
`Tools.set_small_glyph_heights()`	小さなbbox高さを使用して検索および抽出します。
`Tools.set_subset_fontnames()`	サブセットフォント名タグの抑制を制御します。
`Tools.show_aa_level()`	アンチエイリアシングの値を返します。
`Tools.unset_quad_corrections()`	PyMuPDF固有のコードを無効にします。
`Tools.fitz_config`	PyMuPDFの設定設定
`Tools.store_maxsize`	最大格納可能キャッシュサイズ
`Tools.store_size`	現在の格納可能キャッシュサイズ

クラスAPI

class Tools#

gen_id()#

1回の呼び出しごとに1ずつ増加する一意の正の整数を返す便利なメソッドです。使用例には、データベース内で一意のキーを作成することが含まれます。タイムスタンプを使用するよりも作成が10倍高速であるべきです。

注釈

MuPDFはv1.14.0でこれをサポートを中止したため、次の違いを持つ類似の関数を再実装しました。

これはMuPDFのグローバルコンテキストの一部ではなく、スレッドセーフではありません（とにかくPyMuPDFではスレッドをサポートしていないため、これは問題ではありません）。
これはintとして実装されています。つまり、最大値は sys.maxsize です。この数値がいつか超過される場合、カウンターは1から再開します。

戻り値の型:: int
戻り値:: 一意の正の整数。

set_annot_stem(stem=None)#

v1.18.6で新登場

新しい注釈、フィールド、またはリンクのIDのプレフィックスを設定または問い合わせます。

パラメータ:: stem (str) -- 省略された場合、現在の値が返され、デフォルトは "fitz" です。注釈、フィールド/ウィジェット、およびリンクは技術的にはPDF文書内の同じ種類のオブジェクト（/Annot）のサブタイプです。/Annot オブジェクトは、ページ内で一意の識別子を持つことができます。適用可能なサブタイプごとに、PyMuPDFはそれぞれ "stem-Annn"、"stem-Wnnn"、または "stem-Lnnn" の識別子を生成します。番号 "nnn" は必要な一意性を強制するために使用されます。
戻り値の型:: str
戻り値:: 現在の値。

set_small_glyph_heights(on=None)#

v1.18.5で新登場

テキスト抽出およびテキスト検索メソッドでのbboxの高さを縮小するかどうかを設定または問い合わせます。

パラメータ:: on (bool) -- 省略された場合または None の場合、現在の設定が返されます。他の値の場合、bool() 関数が適用され、グローバル変数を設定します。True の場合、Page.search_for() および Page.get_text() メソッドは フォントサイズ の高さを持つ文字、スパン、行、またはブロックのbboxを返します。False の場合（PyMuPDFがインポートされたときの標準設定）、bboxの高さはフォントのプロパティに基づき、通常は 行の高さ と同じです。
戻り値の型:: bool
戻り値:: True または False。

注釈

直接MuPDFコードをラップするテキスト抽出オプション「xml」、「xhtml」、「html」は、これに影響を受けません。

set_subset_fontnames(on=None)#

バージョン1.18.9で追加されました

テキスト抽出におけるサブセットフォント名のタグを抑制する制御を行います。

パラメータ:: on (bool) -- 省略された場合 None、現在の設定が返されます。True または False の値を評価して、グローバル変数を設定します。True の場合、オプション "dict"、"json"、"rawdict"、"rawjson" は例えば "NOHSJV+Calibri-Light" のように返され、それ以外の場合はデフォルトの "Calibri-Light" のみが返されます。設定は再度変更されるまで有効です。
戻り値の型:: bool
戻り値:: True または False。

注釈

上記に記載されている以外のテキスト抽出バリアントには影響しません。特に、MuPDFコードに基づくオプション "xml"、"xhtml"、"html" には影響しません。これらはフォント名 "Calibri-Light"、またはこの例の場合はファミリー名 Calibri のみを抽出します。

unset_quad_corrections(on=None)#

バージョン1.18.10で追加されました

Page.get_text() テキスト抽出で無意味なものを検出した際に、有効な文字の四角形を再構築しようとするPyMuPDF固有のコードの有効化/無効化を行います。このコードは、存在しない場合があるフォントの特性（ascenderおよびdescender）に依存しており、これらの特性にアクセスしようとするとセグメンテーション違反が発生します。このメソッドはPyMuPDF内のグローバルパラメータを設定し、このコードの実行を抑制します。

パラメータ:: on (bool) -- 省略された場合、または None 、現在の設定が返されます。他の値の場合、bool() 関数が適用され、グローバル変数を設定します。True の場合、PyMuPDFは該当するフォントの特性にアクセスしようとせず、代わりに ascender=0.8 および descender=-0.2 の値を使用します。
戻り値の型:: bool
戻り値:: True または False。

store_shrink(percent)#

現在のサイズを基準に、ストレージキャッシュのサイズを指定した割合で減少させます。

パラメータ:: percent (int) -- 現在のサイズの何パーセントを解放するかを指定します。100以上の場合、ストアは空になります。むしろ、何も変更されません。MuPDFのキャッシング戦略は「最後に使用されたもの」なので、使用頻度の低い要素が最初に削除されます。
戻り値の型:: int
戻り値:: 新しい現在のストアサイズ。状況に応じて、要求された割合よりもサイズが大幅に削減される場合があります。

show_aa_level()#

バージョン1.16.14で新たに追加

現在のアンチエイリアシング値を返します。これらの値は、グラフィックスとテキスト要素のレンダリング品質を制御します。

戻り値の型:: dict
戻り値:: 以下の初期内容を持つ辞書： {'graphics': 8, 'text': 8, 'graphics_min_line_width': 0.0}。

set_aa_level(level)#

バージョン1.16.14で新たに追加

アンチエイリアシングに使用するビット数を設定します。現在はグラフィックスとテキストのレンダリングに同じ値が使用されます。将来のMuPDFリリースで変更されるかもしれません。

パラメータ:: level (int) -- 0から8までの範囲の整数。この範囲外の値は静かに有効な値に変更されます。この値は、現在のセッション全体または再度変更されるまで有効です。

reset_mupdf_warnings()#

バージョン1.16.0で新たに追加

MuPDFの警告メッセージバッファを空にします。

mupdf_display_errors(value=None)#

バージョン1.16.8で新たに追加

MuPDFのエラーを表示するかどうかを表示または設定します。

パラメータ:: value (bool) -- boolでない場合、現在の設定が返されます。Trueの場合、MuPDFのエラーは sys.stderr に表示され、それ以外の場合は抑制されます。いずれの場合も、メッセージは警告ストアに引き続き保存されます。PyMuPDFのインポート時にこの値は True です。
戻り値:: True または False

mupdf_warnings(reset=True)#

バージョン1.16.0で新たに追加

すべての保存されたMuPDFメッセージを、改行が挿入された文字列として返します。

パラメータ:: reset (bool) -- （バージョン1.16.7で新たに追加） ストアを自動的に空にするかどうか。

fitz_config#

PyMuPDFとMuPDFを設定するために使用される実際の値を含む辞書です。インストールの章も参照してください。これは各キーを概説したもので、それぞれがサポートの側面のステータスを記述しています。

キー	サポートが含まれているのは...
plotter-g	グレーカラースペースのレンダリング
plotter-rgb	RGBカラースペースのレンダリング
plotter-cmyk	CMYKカラースペースのレンダリング
plotter-n	オーバープリントのレンダリング
pdf	PDFドキュメント
xps	XPSドキュメント
svg	SVGドキュメント
cbz	CBZドキュメント
img	IMGドキュメント
html	HTMLドキュメント
epub	EPUBドキュメント
jpx	JPEG2000画像
js	JavaScript
tofu	すべてのTOFUフォント
tofu-cjk	CJKフォントのサブセット（中国、日本、韓国）
tofu-cjk-ext	CJKフォント拡張
tofu-cjk-lang	CJKフォントの言語拡張
tofu-emoji	TOFU絵文字フォント
tofu-historic	TOFU歴史的フォント
tofu-symbol	TOFUシンボルフォント
tofu-sil	TOFU SILフォント
icc	ICCプロファイル
py-memory	Pythonメモリ管理を使用 [2]
base14	Base-14フォント（常にtrueである必要があります）

For an explanation of the term "TOFU" see this Wikipedia article:

In [1]: import pymupdf
In [2]: TOOLS.fitz_config
Out[2]:
{'plotter-g': True,
 'plotter-rgb': True,
 'plotter-cmyk': True,
 'plotter-n': True,
 'pdf': True,
 'xps': True,
 'svg': True,
 'cbz': True,
 'img': True,
 'html': True,
 'epub': True,
 'jpx': True,
 'js': True,
 'tofu': False,
 'tofu-cjk': True,
 'tofu-cjk-ext': False,
 'tofu-cjk-lang': False,
 'tofu-emoji': False,
 'tofu-historic': False,
 'tofu-symbol': False,
 'tofu-sil': False,
 'icc': True,
 'py-memory': False,
 'base14': True}

戻り値の型:: dict

store_maxsize#

Maximum storables cache size in bytes. PyMuPDF is generated with a value of 268'435'456 (256 MB, the default value), which you should therefore always see here. If this value is zero, then an "unlimited" growth is permitted.

戻り値の型:: int

store_size#

Current storables cache size in bytes. This value may change (and will usually increase) with every use of a PyMuPDF function. It will (automatically) decrease only when Tools.store_maxsize is going to be exceeded: in this case, MuPDF will evict low-usage objects until the value is again in range.

戻り値の型:: int

セッションの例#

>>> import pymupdf
# print the maximum and current cache sizes
>>> pymupdf.TOOLS.store_maxsize
268435456
>>> pymupdf.TOOLS.store_size
0
>>> doc = pymupdf.open("demo1.pdf")
# pixmap creation puts lots of object in cache (text, images, fonts),
# apart from the pixmap itself
>>> pix = doc[0].get_pixmap(alpha=False)
>>> pymupdf.TOOLS.store_size
454519
# release (at least) 50% of the storage
>>> pymupdf.TOOLS.store_shrink(50)
13471
>>> pymupdf.TOOLS.store_size
13471
# get a few unique numbers
>>> pymupdf.TOOLS.gen_id()
1
>>> pymupdf.TOOLS.gen_id()
2
>>> pymupdf.TOOLS.gen_id()
3
# close document and see how much cache is still in use
>>> doc.close()
>>> pymupdf.TOOLS.store_size
0
>>>

脚注

[1]

このメモリ領域はMuPDF内部で使用され、既に読み取られ解釈されたオブジェクトのキャッシュとして機能し、パフォーマンスを向上させます。最も重いオブジェクトのタイプは画像およびフォントです。アプリケーションがMuPDFライブラリを起動するとき（私たちの場合、これは import pymupdf の一部として発生します）、この領域の最大サイズを指定する必要があります。 PyMuPDFはメモリ消費を制限するためにデフォルト値（256 MB）を使用します。ここで提供されているメソッドを使用してストアの使用状況を制御または調査できます。たとえば、文書が閉じられ、関連するすべてのオブジェクトが削除された後でも、ストアの使用状況がゼロにならないことがあります。したがって、別の文書を開く前にこれを強制したいかもしれません。

Do you have any feedback on this page?

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.