Pixmap#

Pixmap（「ピクセルマップ」）は、MuPDFの描画機能の中心にあるオブジェクトです。それらは平面的な長方形のピクセルセットを表します。各ピクセルは、その色を定義するバイト数（「コンポーネント」）と、透明度を定義するオプションのアルファバイトで説明されます

PyMuPDFでは、ピクセルマップを作成するためのいくつかの方法が存在します。最初の方法を除いて、すべての方法はオーバーロードされたコンストラクタとして使用できます。ピクセルマップは、以下の方法で作成できます...

ドキュメントページから（メソッド Page.get_pixmap() を使用）
Colorspace (カラースペース) と IRect 情報に基づいて空のものを作成
ファイルから
メモリ内のイメージから
平易なピクセルのメモリ領域から
PDFドキュメント内のイメージから
他のピクセルマップのコピーとして

注釈

3.と4.のポイントに対する入力として多くの画像フォーマットがサポートされています。サポートされている入力画像フォーマットの詳細については、サポートされている入力画像フォーマットのセクションを参照してください。

ピクセルマップの使用例については、FAQ セクションをご覧ください。

メソッド / 属性	短い説明
`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_save()`	Pillowを使用してイメージとして保存します。
`Pixmap.pil_tobytes()`	Pillowを使用してバイトオブジェクトに書き込みます。
`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()`	内部の四角形から作成されたピクセルマップを返します。
`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`	1つの画像行のサイズ
`Pixmap.width`	ピクセルマップの幅
`Pixmap.x`	左上隅のX座標
`Pixmap.xres`	X方向の解像度
`Pixmap.y`	左上隅のY座標
`Pixmap.yres`	Y方向の解像度

クラスAPI

class Pixmap#

__init__(self, colorspace, irect, alpha)#

新しい空のピクマップ: 指定された矩形のサイズと原点を持つ空のピクマップを作成します。したがって、irect.top_left はピクマップの左上隅を示し、その幅と高さは irect.width および irect.height です。イメージ領域は 初期化されず 、データが格納されます。データを初期化するには、clear_with() や set_rect() などを使用してください。

パラメータ:

colorspace (Colorspace (カラースペース)) -- カラースペース。
irect (irect_like) -- ピクマップの位置と寸法。
alpha (bool) -- 透明度バイトを含めるかどうかを指定します。デフォルトは False です。

__init__(self, colorspace, source)#

コピーとカラースペースの設定: カラースペースを変換しながら ソース ピクマップをコピーします。どのカラースペースの組み合わせでも可能ですが、ソースカラースペースは None であってはいけません。

パラメータ:

colorspace (Colorspace (カラースペース)) -- ターゲット となるカラースペース。これは None である場合もあります 。この場合、 "マスク" ピクマップが作成されます。その Pixmap.samples は、ソースのアルファバイトだけで構成されます。
source (Pixmap) -- ソースピクマップ。

__init__(self, source, mask)#

バージョン 1.18.18 で新規追加

コピーとイメージマスクの追加: ソースピクマップをコピーし、マスクピクマップから透明度データを持つアルファチャネルを追加します。

パラメータ:

source (Pixmap) -- アルファチャネルを持たないピクマップ。
mask (Pixmap) -- マスクピクマップ。グレースケールのピクマップである必要があります。

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

コピーとスケーリング: ソースピクマップをコピーし、新しい幅と高さの値にスケーリングします。イメージはそれに応じてストレッチまたは縮小されます。部分的なコピーをサポートしています。ソースカラースペースは None であってもかまいません。

パラメータ:

source (Pixmap) -- ソースピクマップ。
width (float) -- ターゲットの幅。
height (float) -- ターゲットの高さ。
clip (irect_like) -- スケーリングされた ピクマップのこの領域に制限します。

注釈

幅または高さが整数を 表していない 場合（つまり、value.is_integer() != True の場合）、結果のピクマップには アルファチャンネルが含まれます 。

__init__(self, source, alpha=1)#

コピーしてアルファの追加または削除： ソース をコピーし、そのアルファチャンネルを追加または削除します。alpha が source.alpha と等しい場合、同一のコピーになります。アルファチャンネルが追加される場合、その値は255に設定されます。

パラメータ:

source (Pixmap) -- ソースのピクマップ。
alpha (bool) -- 対象にアルファチャンネルがあるかどうか、デフォルトで、ソースのcolorspaceが 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)#

ファイルから: ファイル名から pixmap を作成します。すべてのプロパティは入力から推測されます。生成される pixmap の原点は (0, 0) です。

パラメータ:: filename (str) -- 画像ファイルのパス。

__init__(self, stream)#

メモリから: メモリ領域から pixmap を作成します。すべてのプロパティは入力から推測されます。生成される pixmap の原点は (0, 0) です。

パラメータ:

stream (bytes,bytearray,BytesIO) --

完全で有効な画像を含むデータ。例えば、stream = bytearray(open('image.file', 'rb').read()) などで作成できます。Python 2 では bytes はサポートされていないため、Python 3 のみ 対応しています。なぜなら、Python 2 では bytes == str となり、このメソッドはストリームをファイル名と解釈する可能性があるからです。

バージョン 1.14.13 で変更: io.BytesIO もサポートされるようになりました。

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

生のピクセルから: サンプル から pixmap を作成します。各ピクセルは、カラースペース と alpha パラメーターによって制御されるバイト数で表現される必要があります。生成される pixmap の原点は (0, 0) です。このメソッドは、他のプログラムによって生の画像データが提供される場合に有用です - FAQ を参照してください。

パラメータ:

colorspace (Colorspace (カラースペース)) -- 画像のカラースペース。
width (int) -- 画像の幅
height (int) -- 画像の高さ
samples (bytes,bytearray,BytesIO) --
画像のすべてのピクセルを含む領域。指定されている場合はアルファ値を含める必要があります。

バージョン 1.14.13 で変更: (1) io.BytesIO も使用できるようになりました。 (2) データは pixmap に コピーされる ようになり、安全に削除または利用不可能になります。
alpha (bool) -- 透明チャネルを含めるかどうか。

注釈

以下の式が 成り立つ必要があります : (colorspace.n + alpha) * width * height == len(samples)。
バージョン 1.14.13 以降、サンプルデータは pixmap に コピーされます 。

__init__(self, doc, xref)#

PDFイメージから： PDFドキュメント内の xref で識別されるイメージからピクスマップを作成します。ピクスマップのすべてのプロパティはイメージによって設定されます。これがどのように使用されるかを確認するには、extract-img1.py と extract-img2.py をご覧ください。これにより、PDFのすべてのイメージを復元できます。

パラメータ:

doc (Document (ドキュメント)) -- 開かれた PDF ドキュメント。
xref (int) -- 画像オブジェクトの xref。たとえば、Document.get_page_images() を使用して特定のページで使用されるすべてのイメージのリストを作成し、各イメージの xref 番号も表示できます。

clear_with([value[, irect]])#

サンプル領域を初期化します。

パラメータ:

value (int) -- 指定された場合、0から255の値が有効です。各ピクセルの各カラーバイトはこの値に設定され、存在する場合はアルファが255（非透明）に設定されます。省略された場合、すべてのバイト（アルファを含む）が 0x00 にクリアされます。
irect (irect_like) -- クリアする領域。ピクスマップ全体をクリアするには省略します。value も指定されている場合のみ指定できます。

tint_with(black, white)#

ピクスマップを色付けして、黒と/または白を sRGB整数値 として指定された色で置き換えます。CS_GRAY と CS_RGB のカラースペースのみサポートされており、他のカラースペースは警告付きで無視されます。

カラースペースが CS_GRAY の場合、平均（赤+緑+青）/3が取得されます。ピクスマップはその場で変更されます。

パラメータ:

black (int) -- 黒をこの値で置き換えます。0x000000を指定しても変更はありません。
white (int) -- 白をこの値で置き換えます。0xFFFFFFを指定しても変更はありません。

例：

tint_with(0x000000, 0xFFFFFF) は操作なしです。

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)#

Shrink the pixmap by dividing both, its width and height by 2:sup:n.

パラメータ:: n (int) -- 新しいPixmap（サンプル）のサイズを決定します。例えば、値が2の場合、幅と高さを4分の1に分割し、元のサイズの16分の1のサイズになります。1未満の値は警告として無視されます。

注釈

これを使用して比を保持したままPixmapのサイズを縮小します。Pixmapは「その場で」変更されます。元のピクセルを保持し、より詳細な選択肢を持つ場合は、上記のコピーコンストラクタを使用してください。

pixel(x, y)#

バージョン1.14.5 で新規追加：位置（x、y）（列、行）のピクセルの値を返します。

パラメータ:

x (int) -- ピクセルの列番号。範囲 range(pix.width) 内である必要があります。
y (int) -- ピクセルの行番号、範囲 range(pix.height) 内である必要があります。

戻り値の型:

list

戻り値:

色の値と、必要に応じてアルファ値のリスト。その長さと内容は、Pixmap の色空間とアルファの存在に依存します。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

戻り値:

irectが無効であるか、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) -- 新しいアルファ値。指定された場合、その長さは少なくとも 幅×高 さでなければなりません。省略した場合（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 内のすべてのピクセルの色を反転させます。colorspaceが None の場合は効果がありません。

パラメータ:: irect (irect_like) -- 反転する領域。すべて反転するには省略します。

copy(source, irect)#

ソース ピクマップの irect 部分を、このピクマップの対応する領域にコピーします。2つのピクマップは異なる寸法を持つことができ、それぞれが CS_GRAY または CS_RGB カラースペースを持つことができますが、現在は同じアルファプロパティ [2] を持っている必要があります。コピー機構は、次のようにソースとターゲットの間の不一致を自動的に調整します。

CS_GRAY から CS_RGB にコピーする場合、ソースのグレーシェード値は、3つのRGBコンポーネントバイトの各々に配置されます。逆の場合、（r + g + b）/ 3 がターゲットのグレーシェード値として取られます。

irect とターゲットピクマップの長方形の間で、まず「交差」を計算します。これは、長方形の座標と現在の属性値 Pixmap.x および Pixmap.y （これを目的のために Pixmap.set_origin() を介して自由に変更できます）を考慮に入れます。その後、この交差のデータがコピーされます。交差が空の場合、何も起こりません。

パラメータ:

source (Pixmap) -- ソースのピクマップ。
irect (irect_like) -- コピーする領域。

注釈

例： pix1 と pix2 という2つのピクマップがあるとし、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」パラメータを使用して制御できます。

Pixmapを画像ファイルとして保存します。選択した出力に応じて、一部またはすべてのカラースペースがサポートされ、異なるファイル拡張子を選択できます。詳細については以下の表をご覧ください。

パラメータ:

filename (str,Path,file) -- 保存先のファイル。文字列、pathlib.Path 、またはPythonファイルオブジェクトとして提供できます。後の2つの場合、ファイル名は対応するオブジェクトから取得されます。ファイル名の拡張子は画像フォーマットを決定し、出力パラメータで上書きできます。
output (str) -- 望ましい画像フォーマット。デフォルトはファイル名の拡張子です。この値とファイル拡張子の両方がサポートされていない場合、例外が発生します。サポートされている出力画像フォーマットを参照してください。
jpg_quality (int) -- 望ましい画像品質、デフォルトは95です。JPEG画像にのみ適用され、それ以外の場合は無視されます。このパラメータは品質とファイルサイズをトレードオフにします。値が98の場合、ほぼロスレスです。より高い値は品質を向上させることはありません。

例外:

ValueError -- サポートされていない画像フォーマットの場合。

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

新機能（バージョン1.14.5）：指定されたフォーマットのピクマップをバイトメモリオブジェクトとして返します。これは 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"（英語）です。複数の言語を使用する場合、"eng+spa" のように "+" で区切った Tesseract 言語コードを使用します（英語とスペイン語の場合など）。
tessdata (str) -- folder name of Tesseract's language support. If omitted, this information must be present as environment variable 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()) 、そしてそのページ=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_save(*args, unmultiply=False, **kwargs)#

v1.17.3 で新しく追加されました

Pillow を使用して pixmap を画像ファイルとして書き込みます。これは MuPDF でサポートされていない出力に使用します。例として、以下が挙げられます。

JPX、J2K、WebP などの形式
EXIF 情報の保存
dpi 情報を提供しない場合、pixmap に格納されている xres、yres の値が自動的に使用されます。

A simple example: pix.pil_save("some.webp", optimize=True, dpi=(150, 150)).

パラメータ:: unmultiply (bool) -- If the pixmap's colorspace is RGB with transparency, the alpha values may or may not already be multiplied into the color components ref/green/blue (called "premultiplied"). To enforce undoing premultiplication, set this parameter to True. To learn about some background, e.g. look for "Premultiplied alpha" here.

For details on other parameters see the Pillow documentation.

Since v1.22.0, PyMuPDF supports JPEG output directly. We recommended to no longer use this method for JPEG output -- for performance reasons and for avoiding unnecessary external dependencies.

例外:: ImportError -- Pillow がインストールされていない場合

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

v1.17.3 で新しく追加されました

Return an image as a bytes object in the specified format using Pillow. For example stream = pix.pil_tobytes(format="WEBP", optimize=True, dpi=(150, 150)). Also see above. For details on other parameters see the Pillow documentation.

例外:: ImportError -- Pillow がインストールされていない場合
戻り値の型:: bytes

warp(quad, width, height)#

v1.19.3 で新しく追加されました

四角形を "ワープ" して、四角形の角が新しい pixmap の角になるようにします。対象 pixmap の IRect は (0, 0, width, height) になります。

パラメータ:

quad (quad_like) -- Pixmap.irect の内部にある座標を持つ凸四角形（境界点も含む）
width (int) -- 望ましい幅
height (int) -- 望ましい高さ

戻り値:

新しいピクスマップで、四角形の角が時計回りにピクスマップの角にマップされます: quad.ul -> irect.tl、quad.ur -> irect.tr など。

戻り値の型:

Pixmap

color_count(colors=False, clip=None)#

v1.19.2で導入
v1.19.3で変更

Pixmapのユニークな色とそのカウントを特定します。

パラメータ:

colors (bool) -- （v1.19.3で変更） True の場合、色ピクセルとその使用回数の辞書を返し、それ以外の場合はユニークな色の数だけを返します。
clip (rect_like) -- Pixmap.irect 内の四角形。指定した場合、そのピクセルのみが考慮されます。これにより、指定されたPixmapのサブ四角形を直接調査できます。

戻り値の型:

dict or int

戻り値:

色の数、または pixel: count の項目を持つ辞書。pixelキーは Pixmap.n の長さの bytes オブジェクトです。

注釈

ピクセルのタプルを復元するには、i番目の項目に対して tuple(colors.keys()[i]) を使用します。

応答時間はPixmapのsamplesサイズに依存し、非常に大きなPixmapの場合は1秒以上かかることがあります。
該当する場合、異なるアルファ値を持つピクセルは異なる色として扱われます。

color_topusage(clip=None)#

v1.19.3 で新しく追加されました

最も頻繁に使用される色とその相対頻度を返します。

パラメータ:: clip (rect_like) -- Pixmap.irect 内の四角形。指定した場合、そのピクセルのみが考慮されます。これにより、指定されたPixmapのサブ四角形を直接調査できます。
戻り値の型:: tuple
戻り値:: 比率 0 < ratio <= 1 および色のピクセル値を持つタプル。これを使用して画像が「ほぼ」単一の色であるかどうかを判断します。応答 (0.95, b"x00x00x00") は、すべてのピクセルの95%が黒であることを示します。こちらの例を参照してください：「Pixmapsの使用方法：テキストの可視性の確認」

alpha#

Pixmapに透明情報が含まれているかどうかを示します。

Type:: bool

digest#

PixmapのMD5ハッシュコード（16バイト）。これは一意の識別に使用される技術的な値です。

Type:: bytes

colorspace#

Pixmapのカラースペース。この値は、イメージが イメージマスク または ステンシルマスク として扱われる場合、None になることがあります（現在、抽出されたPDFドキュメントイメージのみが該当）。

Type:: Colorspace (カラースペース)

stride#

Pixmap.samples 内の画像データの1行の長さを含みます。これは主に計算目的で使用されます。次の式が真です：

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バイトは1つのピクセルを定義します。各続くnバイトは、スキャンラインの順序で別のピクセルを生成します。連続するスキャンラインはパディングなしで続きます。たとえばRGBAカラースペースの場合、samples は …、R、G、B、A、… のようなバイトのシーケンスで、4つのバイト値R、G、B、Aが1つのピクセルを定義します。

この領域は、PIL（Python Imaging Library）などの他のグラフィックライブラリに渡すことができ、ピクマップを他の画像形式で保存するなどの追加の処理を行うのに使用できます。

注釈

基本データは通常、この属性にアクセスするたびに bytes のコピーが作成される大きなメモリ領域です。たとえば、RGBAでレンダリングされた文字ページのsamplesサイズはほぼ1.4 MBです。したがって、新しい変数に代入するか、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 の代わりに使用でき、同等です。

また、len(pix.samples) == len(pix.samples_mv) です。

この2 MBのJPEGからのこの例をご覧ください： memoryview は 10000倍高速 です:

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)

Type:: memoryview

samples_ptr#

新機能 v1.18.17

ピクセル領域へのPythonポインターです。これは特別な整数形式で、サポートするアプリケーション（PyQtなど）がサンプル領域に直接アクセスし、非常に高速に画像を構築できるように使用できます。例えば:

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つの方法ですが、(2)はピクセル領域の追加のコピーを回避するため、通常 何百倍も高速 です。

Type:: int

size#

これは pixmap の長さ を含んでいます。通常、これは 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#

Number of components per pixel. This number depends on colorspace and alpha. If colorspace is not None (stencil masks), then Pixmap.n - Pixmap.alpha == pixmap.colorspace.n is true. If colorspace is None, then 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（ファイル名） または Pixmap（バイト配列） を使用してピクスマップを直接作成します。その後、ピクスマップには画像によって決定されるプロパティが含まれます。
pymupdf.open(...) を使用してこのようなファイルを開きます。その結果、単一のページを含むドキュメントとして表示されます。このページのピクスマップを作成すると、このコンテキストで利用可能なすべてのオプションを使用できます：行列を適用、色空間とアルファを選択、ピクスマップをクリップエリアに制限などが含まれます。

SVG画像 は、直接ピクスマップとしてではなく、上記の方法2でのみサポートされています。ただし、ピクスマップの場合と同様、その結果は ラスターイメージ です [1]。

サポートされている出力画像フォーマット#

いくつかの画像出力フォーマットがサポートされています。画像を直接ファイルに書き込むオプション（Pixmap.save()）またはバイトオブジェクトを生成するオプション（Pixmap.tobytes()）があります。どちらのメソッドも、希望の フォーマット を識別する文字列を受け入れます（下のフォーマット列）。ただし、すべてのピクスマップの色空間、透明度サポート（アルファ）、および画像フォーマットの組み合わせが可能であるわけではないことに注意してください。

フォーマット	カラースペース	アルファ	拡張子	説明
jpg, jpeg	gray, rgb, cmyk	なし	.jpg, .jpeg	Joint Photographic Experts Group
pam	gray, rgb, cmyk	あり	.pam	Portable Arbitrary Map
pbm	gray, rgb	なし	.pbm	Portable Bitmap
pgm	gray, rgb	なし	.pgm	Portable Graymap
png	gray, rgb	あり	.png	Portable Network Graphics
pnm	gray, rgb	なし	.pnm	Portable Anymap
ppm	gray, rgb	なし	.ppm	Portable Pixmap
ps	gray, rgb, cmyk	なし	.ps	Adobe PostScript Image
psd	gray, rgb, cmyk	あり	.psd	Adobe Photoshop Document

注釈

すべての画像ファイル形式がすべてのOSプラットフォームでサポートされているわけではありません（または少なくとも一般的ではありません）。たとえば、PAMおよびPortable Anymap形式はWindowsでは珍しいか、またはまったく知られていません。
特にCMYKカラースペースに関連することについて、常にCMYK pixmapを rgb_pix = pymupdf.Pixmap(pymupdf.csRGB、cmyk_pix) に変換し、その後、その形式で保存できます。
ご覧のように、MuPDFの画像サポート範囲は入力と出力で異なります。両方の方法でサポートされているものの中で、PNGとJPEGはおそらく最も人気があります。
また、tkinterの PhotoImage メソッドへの入力として「ppm」形式を使用することをお勧めします。tkimg = tkinter.PhotoImage(data=pix.tobytes("ppm")) のように（チュートリアルも参照してください）。これは 非常に 高速です（PNGよりも60倍速いです）。

脚注

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.