# PictureFan スクリプト仕様


## はじめに

PictureFan では Python によるスクリプトを使用して処理を行うことができます。  
現在の仕様は暫定的なものですので、今後変更される可能性があります。

この文書は Markdown (CommonMark) を使用していますので、Markdown ビューア等を利用すれば見やすくなります。


## 概要

スクリプトをメニューから実行できるようにするためには、Python のスクリプトファイル(*.py)を
スクリプトフォルダ(デフォルトでは .\Scripts)内の所定のサブフォルダに配置します。

* Main  
  メインウィンドウ用スクリプト
* Thumbnails  
  サムネイル用スクリプト
* Viewer  
  単独ビューア

そうすれば、メインウィンドウ及びサムネイルのメニューから [ツール] -> [スクリプト] で実行できるようになります。

.\Python フォルダに Python の実行環境が含まれていますが、これは以下の Python 公式サイトで公開されている
埋め込み用実行環境のファイル(embeddable zip file)と全く同じものです。

[Python Releases for Windows](https://www.python.org/downloads/windows/)

Python はすでに Windows 7 のサポートを打ち切っていますが、PictureFan は Windows 7 も動作環境に含めているため、添付の Python は 3.8 になっています。
Python 3.6 以降であればバージョンを更新したり、もし既にお使いの環境に Python がインストールされていればそれを利用することもできます。
ただし、PictureFan が x86 版の場合は Python も x86 版が必要ですし、
同様に PictureFan が x64 版の場合は x64 版の Python がインストールされている必要があります。

既存の Python を利用する場合は、Users.ini ファイルの PythonDir で設定します。
設定方法に関しては Users.sample.ini ファイルを参照してください。


### pip の利用

付属の Python 実行環境は埋め込み用の環境であるため、pip が含まれていません。  
pip を利用するには、まず Python フォルダ内の python38._pth ファイルの以下の行の先頭の # を削除してください。

~~~
#import site
~~~

get-pip.py を https://bootstrap.pypa.io/get-pip.py からダウンロードして Python フォルダに配置し、以下のように実行します。

~~~
python get-pip.py
~~~

そのままではカレントディレクトリにパスが通らないため、パッケージによってはインストールができません。  
そのため、Python フォルダ内に current.pth ファイルを作成し(拡張子が .pth であればファイル名は異なってもよい)、以下の内容を記述します。

~~~
import sys; sys.path.append('')
~~~

パッケージのインストールは以下のように行います。

~~~
python -m pip install numpy
~~~


### スクリプトの書き方

通常の Python と同様に書きます。  
ファイルのエンコーディングは UTF-8 にしてください。

PictureFan に関係する機能は、モジュール `PictureFan` にありますので、import してください。

~~~
import PictureFan as PF

app = PF.Application()
app.alert("Hello, World.")
~~~


## クラス仕様

`PictureFan` モジュールの以下のクラスが利用できます。

* [Application](#Application-クラス)  
  プログラム全般
* [WindowBase](#WindowBase-クラス)  
  ウィンドウの基底クラス
* [MainWindow](#MainWindow-クラス)  
  メインウィンドウ
* [Image](#Image-クラス)  
  画像
* [ImageFilter](#ImageFilter-クラス)  
  画像フィルタ
* [Color](#Color-クラス)  
  色
* [Palette](#Palette-クラス)  
  パレット
* [Rectangle](#Rectangle-クラス)  
  矩形
* [Matrix](#Matrix-クラス)  
  行列
* [Document](#Document-クラス)  
  ドキュメント
* [Viewer](#Viewer-クラス)  
  単独ビューア
* [PopupMenu](#PopupMenu-クラス)  
  ポップアップメニュー
* [ThumbnailsWindow](#ThumbnailsWindow-クラス)  
  サムネイルウィンドウ
* [ThumbnailsFolder](#ThumbnailsFolder-クラス)  
  サムネイルフォルダ
* [ThumbnailsFile](#ThumbnailsFile-クラス)  
  サムネイルファイル


### Application クラス

アプリケーションの全体的な事柄に関するクラスです。

#### Application.version : str (read only)

PictureFan のバージョンです。"0.37.0" のような文字列です。

#### Application.run_context : str (read only)

スクリプトがどのように実行されたかを表します。以下のいずれかです。

* "Application"  
  アプリケーションのイベントから実行された

* "Batch"  
  一括変換から実行された

* "MainWindow"  
  メインウィンドウから実行された

* "Thumbnails"  
  サムネイルウィンドウから実行された

* "Viewer"  
  単独ビューアから実行された

#### Application.run_event : str (read only)

イベントでスクリプトが実行された場合、そのイベントを表します。  
イベントから実行されたのでなければ `None` になります。

* "Application.Start"  
  アプリレーションの開始時

* "Application.End"  
  アプリケーションの終了時

* "MainWindow.Open"  
  メインウィンドウの表示時

* "MainWindow.Close"  
  メインウィンドウを閉じた時

* "Document.Open"  
  ドキュメントを開いた時

* "Document.Close"  
  ドキュメントを閉じた時

* "Document.FileChange"  
  ドキュメントのファイルを切り替えた時

* "Thumbnails.Open"  
  サムネイルを開いた時

* "Thumbnails.Close"  
  サムネイルを閉じた時

* "Viewer.Open"  
  単独ビューアを開いた時

* "Viewer.Close"  
  単独ビューアを閉じた時

* "Viewer.FileChange"  
  単独ビューアのファイルを切り替えた時

#### Application.alert(message: str, caption: str = "", type: AlertType = AlertType.INFORMATION)

ダイアログでメッセージを表示します。

* `message`  
  表示するメッセージの文字列です。

* `caption`  
  キャプションの文字列です。省略すると "Alert" になります。

* `type`  
  表示するメッセージの種類です。

  * `AlertType.INFORMATION`  
    情報
  * `AlertType.WARNING`  
    警告
  * `AlertType.ERROR`  
    エラー

#### Application.confirm(message: str, caption: str = "") -> bool

[はい] と [いいえ] ボタンのある、問い合わせのダイアログを表示します。

* `message`  
  表示するメッセージの文字列です。

* `caption`  
  キャプションの文字列です。省略すると "問い合わせ" になります。

* 戻り値  
  [はい] が選択された場合は `True` が、それ以外の場合は `False` が返ります。

#### Application.prompt(message: str, caption: str = "", default_value: str = "") -> str

一行の文字列を入力させるダイアログを表示します。

* `message`  
  表示するメッセージです。

* `caption`  
  キャプションの文字列です。省略すると "入力" になります。

* `default_value`  
  デフォルトで入力される文字列を指定します。省略すると空になります。

* 戻り値  
  入力された文字列が返ります。
  キャンセルされた場合は `None` が返ります。

* 例
  ~~~
  app = PictureFan.Application()
  input = app.prompt("何か入力してください")
  if input is not None:
      app.alert(input + "と入力しましたね")
  ~~~

#### Application.open_dialog(filename: str, caption: str = "") -> str

ファイルを開くダイアログを表示します。

* `filename`  
  デフォルトのファイル名を指定します。省略した場合は空になります。
  パスを含めると、そのフォルダが最初に表示されます。
  フォルダのみの指定にする場合は \ で終端させます。

* `caption`  
  キャプションの文字列を指定します。省略した場合はデフォルトになります。

* 戻り値  
  選択されたファイルのパスが返ります。
  キャンセルされた場合は `None` が返ります。

* 例  
  ~~~
  app = PictureFan.Application()
  path = app.open_dialog()
  if path is not None:
      app.open_document(path)
  ~~~

#### Application.choose_folder(folder: str, message: str = "") -> str

フォルダを選択するダイアログを表示します。

* `folder`  
  デフォルトで選択するフォルダを指定します。
  省略した場合は選択なしになります。

* `message`  
  表示するメッセージを指定します。省略した場合は何も表示されません。

* 戻り値  
  選択されたフォルダのパスが返ります。
  キャンセルされた場合は `None` が返ります。

#### Application.choose_color(color: Color, alpha: bool = False) -> Color

色を選択するダイアログを表示します。

* `color`  
  デフォルトの色の `Color` オブジェクトを指定します。

* `alpha`  
  アルファ値も設定させる場合は `True` を指定します。

* 戻り値  
  選択された色を表す `Color` オブジェクトが返ります。
  キャンセルされた場合は `None` が返ります。

* 例  
  ~~~
  app = PictureFan.Application()
  col = PictureFan.Color()
  col.set_rgb(0, 128, 255)
  col = app.choose_color(col)
  if col is not None:
      app.alert("RGB = " + col.red + "," + col.green + "," + col.blue)
  ~~~

#### Application.get_folder(type: str) -> str

特定のフォルダのパスを取得します。

* `type`  
  取得するフォルダを表す文字列を指定します。以下のいずれかです。
  大文字と小文字は区別されません。

  * "app"  
    プログラムのあるフォルダ
  * "plugins"  
    プラグインフォルダ
  * "appdata"  
    アプリケーションデータ
  * "appdata-local"  
    ローカルアプリケーションデータ
  * "common-appdata"  
    全ユーザー共通のアプリケーションデータ
  * "common-desktop"  
    全ユーザー共通のデスクトップフォルダ
  * "common-documents"  
    全ユーザー共通の My Documents
  * "common-favorites"  
    全ユーザー共通のお気に入り
  * "common-music"  
    全ユーザー共通の My Music
  * "common-pictures"  
    全ユーザー共通の My Pictures
  * "common-startmenu"  
    全ユーザー共通のスタートメニュー
  * "common-startmenu-programs"  
    全ユーザー共通のスタートメニューのプログラム
  * "common-startup"  
    全ユーザー共通のスタートアップ
  * "common-templates"  
    全ユーザー共通のテンプレート
  * "common-video"  
    全ユーザー共通の My Video
  * "documents"  
    My Documents
  * "desktop"  
    デスクトップフォルダ
  * "favorites"  
    お気に入り
  * "fonts"  
    フォント
  * "music"  
    My Music
  * "pictures"  
    My Pictures
  * "programs"  
    Program Files
  * "startmenu"  
    スタートメニュー
  * "startmenu-programs"  
    スタートメニューのプログラム
  * "system"  
    システム
  * "video"  
    My Video
  * "windows"  
    Windows

* 戻り値  
  フォルダのパスが返ります。
  取得できなかった場合は空文字列が返ります。

#### Application.get_current_document() -> Document

現在のドキュメントを取得します。

* 戻り値  
  現在のドキュメントの `Document` オブジェクトが返ります。
  無い場合は None が返ります。

#### Application.set_current_image(image: Image, text: str) -> bool

現在の画像を設定します。
現在の画像とは、

* メインウィンドウから実行されている場合は、アクティブなウィンドウの画像
* 一括変換から実行されている場合は、処理対象の画像

を表します。

* `image`  
  設定する画像の `Image` オブジェクトを指定します。

* `text`  
  設定する画像の説明の文字列を指定します。

* 戻り値  
  現在の画像が設定された場合は `True` が、設定できなかった場合は `False` が返ります。

#### Application.get_current_image() -> Image

現在の画像を取得します。

* 戻り値  
  現在の画像の `Image` オブジェクトが返ります。
  画像が無い場合は `None` が返ります。

#### Application.get_main_window() -> MainWindow

メインウィンドウを取得します。

* 戻り値  
  メインウィンドウの `MainWindow` オブジェクトが返ります。

#### Application.thumbnails_window_count : int (read only)

開かれているサムネイルウィンドウの数です。

#### Application.get_thumbnails_window(index: int) -> ThumbnailsWindow

サムネイルウィンドウを取得します。

* `index`  
  取得するウィンドウの番号を指定します。
  0 から `thumbnails_window_count` - 1 の間で指定します。

* 戻り値  
  サムネイルウィンドウの `ThumbnailsWindow` オブジェクトが返ります。

#### Application.get_active_thumbnails_window() -> ThumbnailsWindow

現在アクティブなサムネイルウィンドウを取得します。

* 戻り値  
  サムネイルウィンドウの `ThumbnailsWindow` オブジェクトが返ります。

#### Application.open_thumbnails_window() -> ThumbnailsWindow

新しいサムネイルウィンドウを開きます。

* 戻り値  
  サムネイルウィンドウの `ThumbnailsWindow` オブジェクトが返ります。

#### Application.viewer_count : int (read only)

開かれている単独ビューアの数です。

#### Application.get_viewer(index: int) -> Viewer

単独ビューアを取得します。

* `index`  
  取得する単独ビューアの番号を指定します。
  0 から `viewer_count` - 1 の間で指定します。

* 戻り値  
  単独ビューアの `Viewer` オブジェクトが返ります。

#### Application.get_active_viewer() -> Viewer

現在アクティブな単独ビューアを取得します。

* 戻り値  
  単独ビューアの `Viewer` オブジェクトが返ります。

#### Application.open_viewer(filename: str = "") -> Viewer

新しい単独ビューアを開きます。

* `filename`  
  開くファイルのパスを指定します。省略するとファイルを開いていない状態になります。

* 戻り値  
  単独ビューアの `Viewer` オブジェクトが返ります。

#### Application.set_progress(pos: int, max: int)

進捗状況を設定します。  
プログレスバーなどで進捗状況が分かるようになります。

* `pos`  
  進捗位置を指定します。0 から `max` までの範囲です。

* `max`  
  進捗最大位置を指定します。

* 例  
  ~~~
  app = PictureFan.Application();
  for i in range(100):
      app.set_progress(i, 99);
  ~~~

#### Application.store_data(key: str, data: str, persistent: bool = True)

データを保存します。
次回のスクリプト実行時まで、何らかのデータを保存しておきたい場合に利用できます。

* `key`  
  保存するキー名を指定します。

* `data`  
  保存するデータを指定します。

* `persistent`  
  `True` にした場合、データはプロセスの次回起動時以降も保持されます。
  `False` にした場合、データはプロセスが終了した時点で破棄されます。

#### Application.load_data(key: str) -> str

保存したデータを取得します。

* `key`  
  取得するキー名を指定します。

* 戻り値  
  取得したデータの文字列が返ります。
  データが存在しない場合は `None` が返ります。

#### Application.delete_data(key: str) -> str

保存したデータを削除します。

* `key`  
  削除するキー名を指定します。

#### Application.is_data_exists(key: str) -> bool

データが保存されているか否かを取得します。

* `key`  
  取得するキー名を指定します。

* 戻り値  
  データが保存されている場合は `True` が、保存されていない場合は `False` が返ります。


### WindowBase クラス

ウィンドウの基底クラスです。

#### WindowBase.close(confirm: bool = True)

ウィンドウを閉じます。

* `confirm`  
  保存の確認を行わない場合は `False` を指定します。  
  `True` を指定した場合、設定で保存の確認を行うようにしている場合は確認が行われます。

#### WindowBase.restore()

ウィンドウが最大化及び最小化されている場合、元の大きさに戻します。

#### WindowBase.minimized : bool

ウィンドウの最小化状態です。
最小化されている場合は `True`、それ以外の場合は `False` です。

#### WindowBase.maximized : bool

ウィンドウの最大化状態です。
最大化されている場合は `True`、それ以外の場合は `False` です。

#### WindowBase.width : int

ウィンドウの幅をピクセル単位で表します。

#### WindowBase.height : int

ウィンドウの高さをピクセル単位で表します。

#### WindowBase.left : int

ウィンドウの左位置を、左上を原点としたスクリーン座標のピクセル単位で表します。

#### WindowBase.top : int

ウィンドウの上位置を、左上を原点としたスクリーン座標のピクセル単位で表します。

#### WindowBase.window_handle : int (read only)

ウィンドウのハンドルです。

#### WindowBase.title : str (read only)

ウィンドウのタイトル文字列です。

#### WindowBase.set_position(left: int, top: int, width: int, height: int)

ウィンドウの位置を設定します。

* `left`  
  ウィンドウの左位置をピクセル単位で表します。

* `top`  
  ウィンドウの上位置をピクセル単位で表します。

* `width`  
  ウィンドウの幅をピクセル単位で表します。

* `height`  
  ウィンドウの高さをピクセル単位で表します。

#### WindowBase.activate()

ウィンドウをアクティブにします。


### MainWindow クラス

PictureFan のメインウィンドウです。  
`WindowBase` クラスから派生しています。  
`Application.get_main_window()` で取得します。

#### MainWindow.open_document(filename: str) -> Document

ドキュメントを開きます。

* `filename`  
  開くドキュメントのパスを指定します。

* 戻り値  
  開いたドキュメントの `Document` オブジェクトが返ります。
  ドキュメントが開けなかった場合は `None` が返ります。

#### MainWindow.open_image(image: Image, name: str) -> Document

指定された画像をドキュメントとして開きます。

* `image`  
  開く画像の `Image` オブジェクトを指定します。

* `name`  
  名前の文字列を指定します。

* 戻り値  
  開いたドキュメントの `Document` オブジェクトが返ります。
  ドキュメントが開けなかった場合は `None` が返ります。

#### MainWindow.active_document : Document

現在アクティブなドキュメントの `Document` オブジェクトです。

#### MainWindow.document_count : int (read only)

開かれているドキュメントの数です。

#### MainWindow.get_document(index: int) -> Document

ドキュメントを取得します。

* `index`  
  取得するドキュメントのインデックスを指定します。
  0 が最初のドキュメントで、`document_count` - 1 が最後です。

* 戻り値  
  取得したドキュメントの `Document` オブジェクトが返ります。

#### MainWindow.do_action(action: str)

PictureFan の機能を実行します。

* `action`  
  実行する機能を指定します。
  指定できる文字列は、メインウィンドウのメニュー [ヘルプ] -> [コマンド一覧] で確認できます。


### Image クラス

画像を表すクラスです。

#### Image.create(width: int, height: int, colorspace: Colorspace, bits_per_plane: int, planes_per_pixel: int)

画像を作成します。  
作成された画像は全てのピクセルの値が 0 で初期化されます。

* `width`  
  画像の幅をピクセル単位で指定します。

* `height`  
  画像の高さをピクセル単位で指定します。

* `colorspace`  
  画像の色空間を指定します。以下のいずれかです。

  * `Colorspace.RGB`  
    RGB
  * `Colorspace.GRAYSCALE`  
    グレイスケール(※)
  * `Colorspace.INDEXED`  
    インデックスカラー

  (※) 現在のところ、グレイスケール画像はフィルタ処理などで対応していないものが多くあります。

* `bits_per_plane`  
  画像のプレーン当たりのビット数を指定します。
  RGB 画像の場合は8か16、グレイスケール画像の場合は1/8/16のいずれか、インデックスカラー画像の場合は1/4/8のいずれかです。

* `planes_per_pixel`  
  画像のピクセル当たりのプレーン数を指定します。
  RGB 画像の場合は3か4、グレイスケール画像の場合は1か2、インデックスカラー画像の場合は1です。

#### Image.copy() -> Image

画像の複製を作成します。

* 戻り値  
  複製した画像が返ります。

#### Image.discard()

画像を破棄します。

#### Image.load_from_file(filename: str, format: str = "")

ファイルから画像を読み込みます。

* `filename`  
  ファイルのパスを指定します。

* `format`  
  読み込むフォーマットを指定します。"bmp" / "jpeg" / "png" 等です。
  フォーマットを自動的に判別する場合は空文字列を指定します。

#### Image.load_from_memory(data: bytes, filename: str = "", format: str = "")

メモリから画像を読み込みます。

* `data`  
  読み込むデータを指定します。

* `filename`  
  ファイル名を指定します。フォーマットの判別などに使われます。
  無い場合は空文字列を指定します。

* `format`  
  読み込むフォーマットを指定します。"bmp" / "jpeg" / "png" 等です。
  フォーマットを自動的に判別する場合は空文字列を指定します。

#### Image.save_to_file(filename: str, format: str, options: dict = {})

ファイルに画像を保存します。

* `filename`  
  保存するファイル名を指定します。

* `format`  
  保存するフォーマットを指定します。"bmp" / "jpeg" / "png" 等です。

* `options`  
  保存オプションを指定します。キーと値の辞書を渡します。  
  例えば JPEG の品質を指定するには、`{"Quality": 90}` のようにします。  
  これはコマンドラインによる一括変換の /format-prop での指定と同じです。

#### Image.save_to_memory(format: str, options: dict = None) -> bytes

メモリに画像を保存します。

* `format`  
  保存するフォーマットを指定します。"bmp" / "jpeg" / "png" 等です。

* `options`  
  保存オプションを指定します。
  `save_to_file` の解説を参照してください。

* 戻り値  
  保存したデータが返ります。

#### Image.load_from_clipboard()

クリップボードから画像を読み込みます。

#### Image.copy_to_clipboard()

クリップボードに画像をコピーします。

#### Image.width : int (read only)

画像の幅をピクセル単位で表します。

#### Image.height : int (read only)

画像の高さをピクセル単位で表します。

#### Image.colorspace: Colorspace (read only)

画像の色空間を表します。

#### Image.bits_per_pixel : int (read only)

画像の1ピクセル当たりのビット数を表します。

#### Image.bits_per_plane : int (read only)

画像のプレーン当たりのビット数を表します。

#### Image.planes_per_pixel : int (read only)

画像のピクセル当たりのプレーン数を表します。

#### Image.x_resolution : int

水平方向の解像度を表します。特に指定が無い場合は 0 です。

#### Image.y_Resolution : int

垂直方向の解像度を表します。特に指定が無い場合は 0 です。

#### Image.resolution_unit : ResolutionUnit

解像度の単位を表します。
以下のいずれかです。

  * `ResolutionUnit.UNDEFINED`  
    指定なし
  * `ResolutionUnit.INCH`  
    1 インチ当たりのピクセル数
  * `ResolutionUnit.CENTIMETRE`  
    1 センチメートル当たりのピクセル数
  * `ResolutionUnit.METRE`  
    1 メートル当たりのピクセル数

#### Image.set_palette(palette: Palette)

画像のパレットを設定します。
画像の色空間がインデックスカラーである必要があります。

* `palette`  
  設定するパレットの `Palette` オブジェクトを指定します。  
  パレットに含まれる色の数が画像の色数より少ない場合、残りの色は全て0になります。

#### Image.get_palette() -> Palette

画像のパレットを取得します。

* 戻り値  
  取得したパレットを表す `Palette` オブジェクトが返ります。  
  画像の色空間がインデックスカラーでない場合は `None` が返ります。

#### Image.format : str (read only)

画像がファイルから読み込まれた場合のファイル形式を表します。  
"BMP" / "JPEG" / "PNG" 等の文字列です。
画像がファイルから読み込まれていないかフォーマットが不明の場合は空です。

#### Image.empty : bool (read only)

画像が空であるかどうかを表します。  
画像がまだ作成されていないか、既に破棄されている場合は `True` になります。

#### Image.set_pixel(x: int, y: int, color: Color)

画像のピクセルの色を設定します。  
処理が遅いため、画像全体を描画するようなことを行うと時間が掛かります。

* `x`  
  左位置をピクセル単位で指定します。

* `y`  
  上位置をピクセル単位で指定します。

* `color`  
  設定する色の `Color` オブジェクトを指定します。

#### Image.get_pixel(x: int, y: int) -> Color

画像のピクセルの色を取得します。

* `x`  
  左位置をピクセル単位で指定します。

* `y`  
  上位置をピクセル単位で指定します。

* 戻り値  
  取得した色の `Color` オブジェクトが返ります。

#### Image.selected : bool

範囲選択がされているかどうかを表します。  
範囲が選択されていない画像に対して `selected` を `True` にすると、全体が選択されます。

#### Image.set_selected_rect(rect: Rectangle)

選択範囲を設定します。

* `rect`  
  選択範囲の矩形を指定します。

#### Image.get_selected_rect() -> Rectangle

選択範囲を取得します。

* 戻り値  
  選択範囲の矩形を表す `Rectangle` オブジェクトが返ります。  
  範囲が選択されていない場合は、画像全体を表す矩形が返ります。

#### Image.set_text(type: str, text: str)

画像のテキストを設定します。

* `type`  
  設定するテキストの種類を指定します。以下のものが予め規定されています。

  * "author"  
    作者
  * "comment"  
    コメント
  * "description"  
    説明
  * "title"  
    タイトル  
    過去のバージョンとの互換性のために、"name" を指定しても同じです。

  これら以外にも、任意のキーワードを指定することができます。  
  これは、PNG の tEXt / iTXt / zTXt チャンクにおけるキーワードに相当します。

* `text`  
  設定するテキストを指定します。

#### Image.get_text(type: str) -> str

画像のテキストを取得します。

* `type`  
  取得するテキストの種類を指定します。
  取得できる種類は `set_text` を参照してください 。

* 戻り値  
  取得したテキスト文字列が返ります。  
  指定された種類のテキストが存在しない場合は空文字列が返ります。

#### Image.set_metadata(type: str, data: bytes)

画像にメタデータを設定します。

* `type`  
  設定するメタデータの種類を指定します。以下のいずれかです。

  * "exif"  
    Exif
  * "icc_profile"  
    ICC プロファイル
  * "xmp"  
    XMP  
    設定するデータに Packet Wrapper が含まれない場合、Packet Wrapper が付加されます。

* 'data'  
  設定するデータを指定します。

#### Image.get_metadata(type: str) -> bytes

画像のメタデータを取得します。

* `type`  
  取得するメタデータの種類を指定します。
  取得できる種類は `set_metadata` を参照してください 。

* 戻り値  
  取得したデータが返ります。  
  指定された種類のデータが存在しない場合は `None` が返ります。

#### Image.page_count : int (read only)

画像のページ数です。

#### Image.current_page_index : int

現在のページのインデックスです。0 から `page_count` - 1 までです。

#### Image.add_page(image: Image)

ページを追加します。

* `image`
  追加する画像です。

#### Image.insert_page(index: int, image: Image)

ページを挿入します。

* `index`
  挿入する位置を指定します。0 から `page_count` までです。

* `image`
  挿入する画像です。

#### Image.delete_page(index: int)

ページを削除します。

* `index`
  削除するページのインデックスを指定します。
  0 から `page_count` - 1 までです。

#### Image.remove_page(index: int) -> Image

ページを削除して、その画像を取得します。

* `index`
  削除するページのインデックスを指定します。
  0 から `page_count` - 1 までです。

* 戻り値
  削除したページの画像です。

#### Image.copy_pixels(dst_left: int, dst_top: int, src_image: Image, src_left: int, src_top: int, width: int, height: int)

画像のデータをコピーします。

* `dst_left`  
  コピー先の左位置をピクセル単位で指定します。

* `dst_top`  
  コピー先の上位置をピクセル単位で指定します。

* `src_image`  
  コピー元の画像を指定します。

* `src_left`  
  コピー元の左位置をピクセル単位で指定します。

* `src_top`  
  コピー元の上位置をピクセル単位で指定します。

* `width`  
  コピーする幅をピクセル単位で指定します。

* `height`  
  コピーする高さをピクセル単位で指定します。

#### Image.composite_pixels(dst_left: int, dst_top: int, src_image: Image, src_left: int, src_top: int, width: int, height: int, opacity: float = 1.0)

画像のデータを合成します。

* `dst_left`  
  合成先の左位置をピクセル単位で指定します。

* `dst_top`  
  合成先の上位置をピクセル単位で指定します。

* `src_image`  
  合成元の画像を指定します。

* `src_left`  
  合成元の左位置をピクセル単位で指定します。

* `src_top`  
  合成元の上位置をピクセル単位で指定します。

* `width`  
  合成する幅をピクセル単位で指定します。

* `height`  
  合成する高さをピクセル単位で指定します。

* `opacity`  
  合成する不透明度を 0.0 から 1.0 の範囲で指定します。

#### Image.to_bytes() -> bytes

画像を `bytes` オブジェクトに変換します。

* 戻り値  
  変換された `bytes` オブジェクトが返ります。

#### Image.from_bytes(width: int, height: int, colorspace: Colorspace, bits_per_plane: int, planes_per_pixel: int, data: bytes)

bytes のデータから画像を作成します。  

* `width`  
  画像の幅をピクセル単位で指定します。

* `height`  
  画像の高さをピクセル単位で指定します。

* `colorspace`  
  画像の色空間を指定します。以下のいずれかです。

  * `Colorspace.RGB`  
    RGB
  * `Colorspace.GRAYSCALE`  
    グレイスケール(※)
  * `Colorspace.INDEXED`  
    インデックスカラー

  (※) 現在のところ、グレイスケール画像はフィルタ処理などで対応していないものが多くあります。

* `bits_per_plane`  
  画像のプレーン当たりのビット数を指定します。
  RGB 画像の場合は8か16、グレイスケール画像の場合は1/8/16のいずれか、インデックスカラー画像の場合は1/4/8のいずれかです。

* `planes_per_pixel`  
  画像のピクセル当たりのプレーン数を指定します。
  RGB 画像の場合は3か4、グレイスケール画像の場合は1か2、インデックスカラー画像の場合は1です。

* `data`  
  変換元のデータを指定します。

#### Image.set_pixel_bytes(data: bytes)

bytes のデータを画像のピクセルデータとしてコピーします。  

* `data`  
  コピー元のデータを指定します。

#### Image.to_matrix() -> Matrix

画像を `Matrix` オブジェクトに変換します。

* 戻り値  
  変換された `Matrix` オブジェクトが返ります。

#### Image.to_matrix_rgb() -> Matrix

画像を RGB 形式の `Matrix` オブジェクトに変換します。

* 戻り値  
  変換された `Matrix` オブジェクトが返ります。

#### Image.from_matrix(matrix: Matrix)

`Matrix` オブジェクトから画像を作成します。

#### Image.extract_plane(plane: int) -> Matrix

画像のプレーンを `Matrix` オブジェクトに変換します。

* `plane`  
  変換するプレーンを指定します。

* 戻り値  
  変換された `Matrix` オブジェクトが返ります。

#### Image.extract_plane_rgb(plane: int) -> Matrix

画像の RGB プレーンを `Matrix` オブジェクトに変換します。

* `plane`  
  変換するプレーンを指定します。

* 戻り値
  変換された `Matrix` オブジェクトが返ります。

#### Image.to_1bit(monochrome: bool, dither: str = "") -> Image

画像を1ビットに変換します。

* `monochrome`  
  画像を白黒に変換する場合は `True` を指定します。  
  `False` を指定すると、最適化パレットを使用したインデックスカラー画像になります。

* `dither`  
  ディザの種類を指定します。以下のいずれかが指定できます。
  省略すると単純近似になります。

  * "approx"  
    単純近似
  * "bayer"  
    Bayer
  * "diffuse"  
    デフォルトの誤差拡散法(現在は Floyd-Steinberg)
  * "floyd-steinberg"  
    Floyd-Steinberg
  * "random"  
    ランダムディザ

  また、種類の後に : に続けてディザの強さを指定できます。
  例えば "diffuse:50" のように指定します。
  強さは1から100までで、値が大きいほど強くディザが掛かります。

* 戻り値  
  変換された画像が返ります。

#### Image.to_indexed4(colors: int = 16, dither: str = "") -> Image

画像を4ビットインデックスカラーに変換します。

* `colors`  
  変換後の最大の色数を指定します。
  1 から 16 までの範囲です。

* `dither`  
  ディザの種類を指定します。以下のいずれかが指定できます。
  省略すると単純近似になります。

  * "approx"  
    単純近似
  * "diffuse"  
    デフォルトの誤差拡散法(現在は Floyd-Steinberg)
  * "floyd-steinberg"  
    Floyd-Steinberg

  また、種類の後に : に続けてディザの強さを指定できます。
  例えば "diffuse:50" のように指定します。
  強さは1から100までで、値が大きいほど強くディザが掛かります。

* 戻り値  
  変換された画像が返ります。

#### Image.to_indexed8(colors: int = 256, dither: str = "") -> Image

画像を8ビットインデックスカラーに変換します。

* `colors`  
  変換後の最大の色数を指定します。
  1 から 256 までの範囲です。

* `dither`  
  ディザの種類を指定します。以下のいずれかが指定できます。
  省略すると単純近似になります。

  * "approx"  
    単純近似
  * "diffuse"  
    デフォルトの誤差拡散法(現在は Floyd-Steinberg)
  * "floyd-steinberg"  
    Floyd-Steinberg

  また、種類の後に : に続けてディザの強さを指定できます。
  例えば "diffuse:50" のように指定します。
  強さは1から100までで、値が大きいほど強くディザが掛かります。

* 戻り値  
  変換された画像が返ります。

#### Image.to_rgb8() -> Image

画像を8ビットRGBに変換します。

* 戻り値  
  変換された画像が返ります。

#### Image.to_rgba8() -> Image

画像を8ビットRGBAに変換します。

* 戻り値  
  変換された画像が返ります。

#### Image.to_rgb16() -> Image

画像を16ビットRGBに変換します。

* 戻り値  
  変換された画像が返ります。

#### Image.to_rgba16() -> Image

画像を16ビットRGBAに変換します。

* 戻り値  
  変換された画像が返ります。

#### Image.resize(width: int, height: int, resample: Resample = Resample.NEAREST_NEIGHBOR) -> Image

画像の大きさを変更します。

* `width`  
  画像の幅をピクセル単位で指定します。

* `height`  
  画像の高さをピクセル単位で指定します。

* `resample`  
  再サンプリングの方法を指定します。以下のいずれかです。

  * `Resample.NEAREST_NEIGHBOR`  
    最近傍補間
  * `Resample.BILINEAR`  
    線形補間
  * `Resample.AVERAGING`  
    平均画素法
  * `Resample.TRIANGLE`  
    Triangle
  * `Resample.HERMITE`  
    Hermite
  * `Resample.HANNING`  
    Hanning
  * `Resample.HAMMING`  
    Hamming
  * `Resample.BLACKMAN`  
    Blackman
  * `Resample.GAUSSIAN`  
    Gaussian
  * `Resample.QUADRATIC`  
    Quadratic
  * `Resample.CUBIC`  
    Cubic
  * `Resample.CATROM`  
    Catrom
  * `Resample.MITCHELL`  
    Mithcell
  * `Resample.SINC`  
    Sinc
  * `Resample.LANCZOS2`  
    Lanczos2
  * `Resample.LANCZOS3`  
    Lanczos3
  * `Resample.LANCZOS4`  
    Lanczos4
  * `Resample.LANCZOS8`  
    Lanczos8
  * `Resample.BICUBIC`  
    Bicubic

* 戻り値  
  変換された画像が返ります。

#### Image.crop(left: int, top: int, width: int, height: int) -> Image

画像を切り抜きます。

* `left`  
  切り抜く左位置をピクセル単位で指定します。

* `top`  
  切り抜く上位置をピクセル単位で指定します。

* `width`  
  切り抜く幅をピクセル単位で指定します。

* `height`  
  切り抜く高さをピクセル単位で指定します。

* 戻り値  
  変換された画像が返ります。

#### Image.rotate(angle: float, resample: str = "", back_color: Color = None) -> Image

画像を回転させます。

* `angle`  
  回転させる角度を、時計回りに度(degree)単位で指定します。

* `resample`  
  再サンプリングの方法を指定します。以下のいずれかです。
  省略すると最近傍補間になります。

  * "nearestneighbor"  
    最近傍補間
  * "bilinear"  
    線形補間

* `back_color`  
  背景色を指定します。
  省略すると画像にアルファプレーンがある場合は透明に、ない場合は黒になります。

* 戻り値  
  変換された画像が返ります。

#### Image.flip_vertical()

画像を上下に反転します。

#### Image.flip_horizontal()

画像を左右に反転します。


### ImageFilter クラス

画像にフィルタ処理を行うクラスです。

#### ImageFilter.grayscale(image: Image) -> Image

画像をグレイスケールに変換します。

* `image`  
  変換元の画像です。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.monochrome(image: Image, threshold: int) -> Image

画像を白黒二階調に変換します。

* `image`  
  変換元の画像です。

* `threshold`  
  閾値を指定します。
  この値以上の輝度の色が白となり、この値未満の輝度の色が黒となります。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.sepia(image: Image) -> Image

画像をセピア色に変換します。

* `image`  
  変換元の画像です。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.negative(image: Image) -> Image

画像をネガポジ反転します。

* `image`  
  変換元の画像です。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.enhance_colors(image: Image, hue: float = 0.0, brightness: float = 0.0, saturation: float = 0.0, contrast: float = 0.0) -> Image

色調補正を行います。

* `image`  
  変換元の画像です。

* `hue`  
  色相をシフトする割合を指定します。1.0 が 360 度に当たります。

* `brightness`  
  輝度を調整する割合を指定します。-1.0 と 1.0 の間で指定します。

* `saturation`  
  彩度を調整する割合を指定します。-1.0 と 1.0 の間で指定します。

* `contrast`  
  コントラストを調整する割合を指定します。-1.0 と 1.0 の間で指定します。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.rgb_balance(image: Image, red: int, green: int, blue: int) -> Image

RGB 値を加算します。

* `image`  
  変換元の画像です。

* `red`  
  赤に加算する値を指定します。

* `green`  
  緑に加算する値を指定します。

* `blue`  
  青に加算する値を指定します。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.gamma_correction(image: Image, red: float, green: float, blue: float) -> Image

ガンマ補正を行います。

* `image`  
  変換元の画像です。

* `red`  
  赤のガンマ値を指定します。

* `green`  
  緑のガンマ値を指定します。

* `blue`  
  青のガンマ値を指定します。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.colorize(image: Image, color: Color, black_base: bool) -> Image

単色カラースケールに変換します。

* `image`  
  変換元の画像です。

* `color`  
  変換する色の Color オブジェクトを指定します。

* `black_base`  
  ベースの色を黒にする場合は `True` を、白にする場合は `False` を指定します。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.solarization(image: Image, threshold: int) -> Image

ソラリゼーション処理を行います。

* `image`  
  変換元の画像です。

* `threshold`  
  処理の閾値を指定します。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.swap_rgb(image: Image, type: str) -> Image

RGB の各プレーンを入れ替えます。

* `image`  
  変換元の画像です。

* `type`  
  RGB 値を入れ替えるパターンを指定します。
  R/G/B の三文字を組み合わせた文字列で、各 RGB 値を入れ替えた順番を表します。
  例えば "GRB" と指定すると、G と R が入れ替わり、B はそのままになります。
  今のところ、同じプレーンを複数使用することはできません(例えば "RRB" など)。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.equalize() -> Image

イコライズ処理を行います。

* `image`  
  変換元の画像です。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.normalize() -> Image

ノーマライズ処理を行います。

* `image`  
  変換元の画像です。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.smoothing(image: Image, radius: int, ratio: float = 0.5) -> Image

平滑化処理を行います。

* `image`  
  変換元の画像です。

* `radius`  
  処理を行う半径を指定します。
  あまり大きな値を指定すると処理に非常に時間が掛かりますので注意してください。

* `ratio`  
  適用する割合を指定します。
  0 から 1 の間で指定し、値が大きいほど強く処理が適用されます。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.sharpening(image: Image, radius: int, ratio: float = 0.5) -> Image

先鋭化処理を行います。

* `image`  
  変換元の画像です。

* `radius`  
  処理を行う半径を指定します。
  あまり大きな値を指定すると処理に非常に時間が掛かりますので注意してください。

* `ratio`  
  適用する割合を指定します。
  0 から 1 の間で指定し、値が大きいほど強く処理が適用されます。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.convolve(image: Image, matrix: list) -> Image

畳み込み処理を行います。

* `image`  
  変換元の画像です。

* `matrix`  
  行列を表す `list` です。

* 戻り値  
  変換された画像が返ります。

* 例
  ~~~
  matrix = [[-0.5, 0.0, 0.5], [-1.0, 1.0, 1.0], [0.5, 0.0, -0.5]]
  new_image = PictureFan.ImageFilter().convolve(src_image, matrix)
  ~~~

#### ImageFilter.blur(image: Image, radius: int) -> Image

ぼかし処理を行います。

* `image`  
  変換元の画像です。

* `radius`  
  処理を行う半径を指定します。
  大きな値を指定すると非常に時間が掛かりますので注意してください。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.gaussian_blur(image: Image, radius: int, sigma: float = 0.5) -> Image

ガウスぼかし処理を行います。

* `image`  
  変換元の画像です。

* `radius`  
  ぼかす範囲の半径を指定します。

* `sigma`  
  標準偏差です。
  0 から 1 までの値を指定します。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.motion_blur(image: Image, radius: int, angle: float, sigma: float = 0.5) -> Image

モーションブラー処理を行います。

* `image`  
  変換元の画像です。

* `radius`  
  ぼかす半径を指定します。

* `angle`  
  ぼかす角度を時計回りに度(degree)単位で指定します。

* `sigma`  
  標準偏差です。
  0 から 1 までの値を指定します。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.emboss(image: Image, radius: int, color: bool = False) -> Image

エンボス処理を行います。

* `image`  
  変換元の画像です。

* `radius`  
  処理を行う半径を指定します。

* `color`  
  各 RGB プレーン毎に処理を行う場合は `True` を、プレーンをまとめて処理を行う場合は `False` を指定します。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.sobel(image: Image) -> Image

輪郭検出処理を行います。

* `image`  
  変換元の画像です。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.pixelize(image: Image, width: int, height: int) -> Image

モザイク処理を行います。

* `image`  
  変換元の画像です。

* `width`  
  幅を指定します。

* `height`  
  高さを指定します。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.posterize(image: Image, steps: int) -> Image

ポスタライズ処理を行います。

* `image`  
  変換元の画像です。

* `steps`  
  階調数を指定します。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.median(image: Image, radius: int) -> Image

中間値フィルタ処理を行います。

* `image`  
  変換元の画像です。

* `radius`  
  処理を行う半径を指定します。
  大きな値を指定すると処理に非常に時間が掛かりますので注意してください。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.minimum(image: Image, radius: int) -> Image

最小値フィルタ処理を行います。

* `image`  
  変換元の画像です。

* `radius`  
  処理を行う半径を指定します。
  大きな値を指定すると処理に非常に時間が掛かりますので注意してください。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.maximum(image: Image, radius: int) -> Image

最大値フィルタ処理を行います。

* `image`  
  変換元の画像です。

* `radius`  
  処理を行う半径を指定します。
  大きな値を指定すると処理に非常に時間が掛かりますので注意してください。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.noise(image: Image, type: str, density: float, amount: float) -> Image

ノイズ処理を行います。

* `image`  
  変換元の画像です。

* `type`  
  ノイズの種類を指定します。以下のいずれかです。

  * "color"  
    色のノイズ
  * "brightness"  
    明度のノイズ
  * "hue"  
    色相のノイズ
  * "saturation"  
    彩度のノイズ

* `density`  
  ノイズの密度を指定します。
  0 から 1 までの間で、1 が最も密度が高くなります。

* `amount`  
  ノイズの強さを指定します。
  0 から 1 までの間で、1 が最も強くなります。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.spread(image: Image, amount: int) -> Image

拡散処理を行います。

* `image`  
  変換元の画像です。

* `amount`  
  拡散させる範囲を指定します。

* 戻り値  
  変換された画像が返ります。

#### ImageFilter.oil_paint(image: Image, radius: int) -> Image

油絵調に変換します。

* `image`  
  変換元の画像です。

* `radius`  
  処理を行う半径を指定します。
  大きな値を指定すると処理に非常に時間が掛かりますので注意してください。

* 戻り値  
  変換された画像が返ります。


### Color クラス

色を表すクラスです。

#### Color.set_rgb(red: int, green: int, blue: int, alpha: int = 255)

RGB値を8ビットで設定します。

* `red`  
  赤の値を指定します。

* `green`  
  緑の値を指定します。

* `blue`  
  青の値を指定します。

* `alpha`  
  不透明度の値を指定します。0 で完全な透明、255 で完全な不透明です。

#### Color.set_rgb16(red: int, green: int, blue: int, alpha: int = 65535)

RGB値を16ビットで設定します。

* `red`  
  赤の値を指定します。

* `green`  
  緑の値を指定します。

* `blue`  
  青の値を指定します。

* `alpha`  
  不透明度の値を指定します。0 で完全な透明、65535 で完全な不透明です。

#### Color.red : int

8ビットで表した赤の値です。

#### Color.red16 : input

16ビットで表した赤の値です。

#### Color.green : int

8ビットで表した緑の値です。

#### Color.green16 : int

16ビットで表した緑の値です。

#### Color.blue : int

8ビットで表した青の値です。

#### Color.blue16 : int

16ビットで表した青の値です。

#### Color.alpha : int

8ビットで表した不透明度の値です。

#### Color.alpha16 : int

16ビットで表した不透明度の値です。

#### Color.index : int

インデックスの値です。0 から 255 までの範囲です。


### Palette クラス

パレットを表すクラスです。

#### Palette.get_color(index: int) -> Color

パレットから色を取得します。

* `index`  
  色を取得するインデックスを指定します。

* 戻り値  
  取得した色が返ります。

#### Palette.set_color(index: int, color: Color)

  パレットの色を設定します。

* `index`  
  色を設定するインデックスを指定します。

* `color`  
  設定する色の `Color` オブジェクトを指定します。

#### Palette.count : int

パレットの色の数です。


### Rectangle クラス

矩形を表すクラスです。

#### Rectangle.left : int

左位置を表します。

#### Rectangle.top : int

上位置を表します。

#### Rectangle.right : int

右位置を表します。  
範囲としてはこの値から 1 を引いた値になります。  
例えば、`left` が 0 で `right` が 100 の場合、幅は 100 になり、
範囲としては 0 から 99 までを表すことになります。
このようになっているのは、そうしないと幅 0 を表現できないためです。

#### Rectangle.bottom : int

下位置を表します。  
範囲としてはこの値から 1 を引いた値になります。  
例えば、`top` が 0 で `bottom` が 100 の場合、高さは 100 になり、
範囲としては 0 から 99 までを表すことになります。
このようになっているのは、そうしないと高さ 0 を表現できないためです。

#### Rectangle.width : int

幅を表します。

#### Rectangle.height : int

高さを表します。

#### Rectangle.set(left: int, top: int, width: int, height: int)

矩形を設定します。

* `left`  
  左位置を指定します。

* `top`  
  上位置を指定します。

* `width`  
  幅を指定します。

* `height`  
  高さを指定します。

#### Rectangle.move(horz: int, vert: int)

矩形を移動します。

* `horz`  
  水平方向の移動量を指定します。

* `vert`  
  垂直方向の移動量を指定します。


### Matrix クラス

行列を表すクラスです。
画像データを行列として扱うのに利用します。

#### Matrix.create(rows: int, columns: int, planes: int, type: str)

行列を作成します。通常、直接作成することはありません。

* `rows`  
  行数を指定します。

* `columns`  
  列数を指定します。

* `planes`  
  プレーン数を指定します。

* `type`  
  要素の型を指定します。以下のいずれかです。

  * "uint8"  
    8ビット符号無し整数
  * "uint16"  
    16ビット符号無し整数

#### Matrix.discard()

行列のデータを破棄します。

#### Matrix.copy() -> Matrix

行列を複製します。

* 戻り値  
  複製した Matrix オブジェクトが返ります。

#### Matrix.to_bytes() -> bytes

データを bytes に変換します。

* 戻り値  
  変換した bytes が返ります。

#### Matrix.from_bytes(data: bytes)

bytes からデータを設定します。

* `data`  
  設定するデータの bytes を指定します。

#### Matrix.rows : int (read only)

行数を表します。

#### Matrix.columns : int (read only)

列数を表します。

#### Matrix.planes : int (read only)

プレーン数を表します。

#### Matrix.dimensions : int (read only)

次元数を表します。

#### Matrix.item_size : int (read only)

各アイテムのバイト数を表します。


### Document クラス

ドキュメントを表すクラスです。
`WindowBase` クラスから派生しています。

#### Document.file_path : str (read only)

ファイルのパスです。

#### Document.media_type : str (read only)

ドキュメントのメディアです。以下のいずれかになります。

  * "image"  
    画像
  * "video"  
    動画
  * "audio"  
    音声
  * "text"  
    テキスト
  * "binary"  
    バイナリ
  * "custom"  
    カスタム

#### Document.format : str (read only)

ファイル形式を表します。  
"BMP" / "JPEG" / "PNG" 等の文字列です。
ファイルから読み込まれていないかフォーマットが不明の場合は空です。

#### Document.is_archive : bool (read only)

書庫内のファイルであるかどうかを表します。
書庫内のファイルの場合は True になります。

#### Document.modified : bool

ドキュメントが変更されているかどうかを表します。
ドキュメントが変更されている場合は True になります。

#### Document.get_image() -> Image

ドキュメントの画像を取得します。
取得された画像は実際の画像のコピーです。

#### Document.set_image(image: Image, descript: str = "")

ドキュメントの画像を設定します。
設定されるのは指定した画像のコピーです。

* `image`  
  設定する画像を指定します。

* `descript`  
  設定する画像の説明の文字列を指定します。
  省略すると "スクリプト" になります。

### Document.selected : bool

範囲選択がされているかどうかを表します。  
範囲が選択されていない画像に対して `selected` を `True` にすると、全体が選択されます。

#### Document.set_selected_rect(rect: Rectangle)

ドキュメントの画像の選択範囲を設定します。  
`Document.get_image` で画像を取得してから `Image.set_selected_rect`、`Document.set_image` と呼んで選択範囲を更新するより、画像の複製を行わない分効率的に設定できます。

* `rect`  
  選択範囲の矩形を指定します。

#### Document.get_selected_rect() -> Rectangle

ドキュメントの画像の選択範囲を取得します。  
`Document.get_image` で画像を取得してから `Image.get_selected_rect` を呼ぶより、画像の複製を行わない分効率的に選択範囲を取得できます。

* 戻り値  
  選択範囲の矩形を表す `Rectangle` オブジェクトが返ります。  
  範囲が選択されていない場合は、画像全体を表す矩形が返ります。

#### Document.do_action(action: str)

機能を実行します。

* `action`  
  実行する機能を指定します。
  指定できる文字列は、メインウィンドウのメニュー [ヘルプ] -> [コマンド一覧] で確認できます。

#### Document.set_user_property(name: str, value: Any) -> bool

ユーザープロパティを設定します。

* `name`  
  プロパティ名を指定します。以下のいずれかです。

  * `author`  
    作者(str)
  * `label`  
    ラベル(int) (1〜30)
  * `note`  
    メモ(str)
  * `rating`  
    評価(int) (1〜100)  
    評価の値は星の数と以下のように対応しています。  
    将来的に星を0.5単位で評価できるようにする可能性がありますが、現在のところ20・40・60・80・100のいずれかの値を使用してください。  
    (1〜)20 ★  
    (21〜)40 ★★  
    (41〜)60 ★★★  
    (61〜)80 ★★★★  
    (81〜)100 ★★★★★
  * `tags`  
    タグ(str)
  * `title`  
    タイトル(str)

* `value`  
  設定する値を指定します。`None` を指定するとプロパティが削除されます。

* 戻り値  
  正常にプロパティが設定された場合は `True` が、設定できなかった場合は場合は `False` が返ります。

#### Document.get_user_property(name: str) -> Any

ユーザープロパティを取得します。

* `name`  
  プロパティ名を指定します。指定できる名前は `set_user_property` の解説を参照してください。

* 戻り値  
  プロパティの値が返ります。プロパティが存在しない場合は `None` が返ります。

#### Document.set_user_properties(properties: Dict) -> bool

すべてのユーザープロパティを設定します。

* `properties`  
  設定するプロパティ名をキーとしてその値を格納した dict を指定します。  
  指定できるプロパティは `set_user_property` の解説を参照してください。  
  指定された dict に存在しないプロパティは削除されます。  
  空の dict を指定すると、すべてのプロパティが削除されます。

* 戻り値  
  正常にプロパティが設定された場合は `True` が、設定できなかった場合は場合は `False` が返ります。

#### Document.get_user_properties() -> Dict

すべてのユーザープロパティを取得します。

* 戻り値  
  プロパティ名をキーとしてその値を格納した dict が返ります。  
  利用できるプロパティは `set_user_property` の解説を参照してください。


### Viewer クラス

単独ビューアを表すクラスです。
`Document` クラスから派生しています。
現在のところ追加のメソッドはありません。


### PopupMenu クラス

ポップアップメニューを表すクラスです。
画面上にメニューを表示することができます。

サンプル:

~~~
menu = PictureFan.PopupMenu()
menu.add("menu1", "Menu 1")
menu.add("menu3", "Menu 3")
menu.insert(1, "menu2", "Menu 2")
result = menu.show()
if result != "":
    app.alert(result)
~~~

#### PopupMenu.add(name: str, text: str = "", sub_menu: PopupMenu = None)

メニューの末尾に項目を追加します。

* `name`  
  項目名を指定します。
  項目名とは、各メニュー項目を識別するための文字列です。

* `text`  
  項目に表示する文字列を指定します。
  空の文字列を指定すると、区切りになります。

* `sub_menu`  
  サブメニューとして表示する `PopupMenu` オブジェクトを指定します。
  サブメニュー項目でない場合は `None` を指定します。

#### PopupMenu.insert(index: int, name: str, text: str = "", sub_menu: PopupMenu = None)

メニュー項目を挿入します。

* `index`  
  項目の挿入する位置を指定します。
  最初の項目として挿入する場合は 0 を指定します。

* `name`  
  項目名を指定します。
  項目名とは、各メニュー項目を識別するための文字列です。

* `text`  
  項目に表示する文字列を指定します。
  空の文字列を指定すると、区切りになります。

* `sub_menu`  
  サブメニューとして表示する PopupMenu オブジェクトを指定します。
  サブメニュー項目でない場合は None を指定します。

#### PopupMenu.remove(name: str)

メニュー項目を削除します。

* `name`  
  削除する項目名を指定します。

#### PopupMenu.get_item_pos(name: str) -> int

項目の位置を取得します。

* `name`  
  項目名を指定します。

* 戻り値  
  項目の位置が返ります。一番最初の項目が 0 となります。
  項目が存在しない場合は -1 が返ります。

#### PopupMenu.set_item_checked(name: str, checked: bool)

項目のチェック状態を設定します。

* `name`  
  項目名を指定します。

* `checked`  
  項目をチェックする場合は `True` を、チェックをしない場合は `False` を指定します。

#### PopupMenu.get_item_checked(name: str) -> bool

項目のチェック状態を取得します。

* `name`  
  項目名を指定します。

* 戻り値  
  項目がチェックされている場合は `True` が、チェックされていない場合は `False` が返ります。

#### PopupMenu.set_item_radio_checked(name: str, checked: bool)

項目のラジオボタンスタイルのチェック状態を設定します。

* `name`  
  項目名を指定します。

* `checked`  
  項目をチェックする場合は `True` を、チェックをしない場合は `False` を指定します。

#### PopupMenu.get_item_radio_checked(name: str) -> bool

項目のラジオボタンスタイルのチェック状態を取得します。

* `name`  
  項目名を指定します。

* 戻り値  
  項目がチェックされている場合は `True` が、チェックされていない場合は `False` が返ります。

#### PopupMenu.set_item_enabled(name: str, enabled: bool)

項目の有効状態を設定します。
無効にした項目は文字が薄く表示され、選択できなくなります。

* `name`  
  項目名を指定します。

* `checked`  
  項目を有効にする場合は `True` を、無効にする場合は `False` を指定します。

#### PopupMenu.get_item_enabled(name: str) -> bool

項目の有効状態を取得します。

* `name`  
  項目名を指定します。

* 戻り値  
  項目が有効な場合は `True` が、無効な場合は `False` が返ります。

#### PopupMenu.show(x: int, y: int) -> str
#### PopupMenu.show() -> str

メニューをポップアップ表示します。
引数が無い場合は現在のマウスカーソルの位置に表示します。

* `x`  
  表示する左位置をスクリーン座標で指定します。

* `y`  
  表示する上位置をスクリーン座標で指定します。

* 戻り値  
  選択された項目名が返ります。
  どの項目も選択されなかった場合は空文字列が返ります。

#### PopupMenu.clear()

メニュー項目を全て削除します。

#### PopupMenu.item_count : int (read only)

メニューの項目数です。


### ThumbnailsWindow クラス

サムネイルウィンドウを表すクラスです。
`WindowBase` クラスから派生しています。  
`Application.get_thumbnails_window()` 関数または
`Application.get_active_thumbnails_window()` 関数で取得できます。

#### ThumbnailsWindow.unique_id : int (read only)

ウィンドウを一意に識別するための ID です。  
この ID を比較することで、2つの `ThumbnailsWindow` オブジェクトが同じウィンドウを
参照しているかを調べることができます。

#### ThumbnailsWindow.folder_count : int (read only)

開かれているフォルダ(タブ)の数です。

#### ThumbnailsWindow.get_folder(index: int) -> ThumbnailsFolder

フォルダを取得します。

* `index`  
  取得するフォルダの番号を指定します。
  0 から `folder_count` - 1 の間で指定します。

* 戻り値  
  取得した `ThumbnailsFolder` オブジェクトが返ります。

#### ThumbnailsWindow.set_active_folder_index(index: int)

アクティブなフォルダを設定します。

* `index`  
  設定するフォルダの番号を指定します。
  0 から `folder_count` - 1 の間で指定します。

#### ThumbnailsWindow.get_active_folder_index() -> int

アクティブなフォルダの番号を取得します。

#### ThumbnailsWindow.get_active_folder() -> ThumbnailsFolder

アクティブなフォルダを取得します。

#### ThumbnailsWindow.set_folder_index(index: int, to_index: int)

フォルダの順序を変更します。

* `index`  
  順序を変えるフォルダの番号を指定します。
  0 から `folder_count` - 1 の間で指定します。

* `to_index`  
  移動先の位置を指定します。
  0 から `folder_count` の間で指定します。

#### ThumbnailsWindow.open_folder(path: str) -> ThumbnailsFolder

フォルダを開きます。

* `path`  
  開くフォルダのバスを指定します。

#### ThumbnailsWindow.do_action(action: str)

機能を実行します。

* `action`  
  実行する機能を表す文字列を指定します。
  指定できる文字列は、サムネイルウィンドウのメニュー [ヘルプ] -> [コマンド一覧] で確認できます。


### ThumbnailsFolder クラス

サムネイルのフォルダ(タブ)を表すクラスです。  
`ThumbnailsWindow.get_folder()` 関数または
`ThumbnailsWindow.get_active_folder()` 関数で取得できます。

#### ThumbnailsFolder.unique_id : int (read only)

フォルダを一意に識別するための ID です。  
この ID を比較することで、2つの `ThumbnailsFolder` オブジェクトが同じフォルダを
参照しているかを調べることができます。
同じフォルダが複数開かれている場合は、それぞれのフォルダ毎に異なる値になります。

#### ThumbnailsFolder.type : str (read only)

フォルダの種類です。以下のいずれかになります。

  * "blank"  
    空
  * "category"  
    分類
  * "folder"  
    通常のフォルダ
  * "history"
    ファイル履歴
  * "search"  
    検索結果
  * "stock"  
    ストック

#### ThumbnailsFolder.path : str (read only)

フォルダのパスです。

#### ThumbnailsFolder.file_system_path : str (read only)

フォルダのファイルシステム上のパスです。

#### ThumbnailsFolder.display_path : str (read only)

フォルダの表示用のパスです。

#### ThumbnailsFolder.display_name : str (read only)

フォルダの表示用の名前です。

#### ThumbnailsFolder.item_id_list : bytes (read only)

フォルダの Item ID List です。

#### ThumbnailsFolder.is_archive : bool (read only)

フォルダが書庫か否かを表します。

#### ThumbnailsFolder.file_count : int (read only)

表示されているファイル数を表します。
フィルタが適用されている場合、実際に表示されている数になります。

#### ThumbnailsFolder.selected_file_count : int (read only)

表示され選択されているファイル数を表します。

#### ThumbnailsFolder.get_file(index: int) -> ThumbnailsFile

表示されているファイルを取得します。

* `index`  
  取得するファイルの番号を指定します。
  0 から `file_count` - 1 の間で指定します。

* 戻り値  
  取得した `ThumbnailsFile` オブジェクトが返ります。

#### ThumbnailsFolder.unfiltered_file_count : int (read only)

全てのファイル数を表します。
フィルタが適用されている場合、非表示のファイルも含めた数になります。

#### ThumbnailsFolder.unfiltered_selected_file_count : int (read only)

全ての選択されているファイル数を表します。

#### ThumbnailsFolder.get_unfiltered_file(index: int) -> ThumbnailsFile

ファイルを取得します。

* `index`  
  取得するファイルの番号を指定します。
  0 から `unfiltered_file_count` - 1 の間で指定します。

* 戻り値  
  取得した `ThumbnailsFile` オブジェクトが返ります。

#### ThumbnailsFolder.set_path(path: str, async: bool = True)

フォルダのパスを設定します。  
フォルダの内容が実際に読み込まれるのは、このフォルダのタブがアクティブな場合のみです。  
それ以外の場合、最初にアクティブにされた時か load 関数が呼ばれた時点で読み込まれます。

* `path`  
  設定するパスを指定します。

* `async`  
  非同期で読み込むか否かを指定します。  
  `False` の場合、同期で読み込まれ、読み込みが完了するまで戻りません。
  `True` の場合、非同期で読み込まれ、読み込みが完了する前に戻ります。

#### ThumbnailsFolder.close()

フォルダを閉じます。
最後の 1 つのフォルダは閉じられません。

#### ThumbnailsFolder.refresh(async: bool = True)

フォルダを最新の情報に更新します。

* `async`  
  非同期で更新するか否かを指定します。  
  `False` の場合、同期で更新され、更新が終了するまで戻りません。
  `True` の場合、非同期で更新され、更新が終了する前に戻ります。

#### ThumbnailsFolder.load(async: bool = True)

フォルダの内容を読み込みます。  
通常フォルダは最初に表示される時に読み込まれます。
まだ表示されていないフォルダは、この関数を呼び出して読み込まない限り空となります。

* `async`  
  非同期で読み込むか否かを指定します。  
  `False` の場合、同期で読み込まれ、読み込みが完了するまで戻りません。
  `True` の場合、非同期で読み込まれ、読み込みが完了する前に戻ります。

#### ThumbnailsFolder.is_loaded : bool (read only)

フォルダの内容が読み込まれているか否かを表します。  
通常フォルダは最初に表示される時に読み込まれます。
まだ表示されていないフォルダでは `False` になります。

#### ThumbnailsFolder.group : int

タブグループを表します。
-1 でグループなし、0〜11 でグループの番号を表します。


### ThumbnailsFile クラス

サムネイルのファイルを表すクラスです。  
`ThumbnailsFolder.get_file()` 関数または、
`ThumbnailsFolder.get_unfiltered_file()` 関数で取得できます。

#### ThumbnailsFile.unique_id : int (read only)

ファイルを一意に識別するための ID です。  
この ID を比較することで、2つの `ThumbnailsFile` オブジェクトが同じファイルを
参照しているかを調べることができます。
同じフォルダが複数開かれている場合は、ファイルの実態が同じでも
それぞれのフォルダ毎に異なる値になります。

#### ThumbnailsFile.path : str (read only)

ファイルのパスです。

#### ThumbnailsFile.file_system_path : str (read only)

ファイルのファイルシステム上のパスです。

#### ThumbnailsFile.display_path : str (read only)

ファイルの表示用のパスです。

#### ThumbnailsFile.display_name : str (read only)

ファイルの表示用の名前です。

#### ThumbnailsFile.item_id_list : bytes (read only)

ファイルの Item ID List です。

#### ThumbnailsFile.file_size : int (read only)

ファイルのサイズ(バイト単位)です。

#### ThumbnailsFile.created_time : datetime (read only)

ファイルの作成日時(UTC)です。

#### ThumbnailsFile.modified_time : datetime (read only)

ファイルの更新日時(UTC)です。

#### ThumbnailsFile.is_folder : bool (read only)

フォルダであるか否かを表します。

#### ThumbnailsFile.is_archive : bool (read only)

書庫であるか否かを表します。

#### ThumbnailsFile.is_in_archive : bool (read only)

書庫内のファイルであるか否かを表します。

#### ThumbnailsFile.selected : bool

選択状態を表します。

#### ThumbnailsFile.marking : int

マーク状態を表します。
-1 でマーク無し、0〜11 でマークの番号を表します。

#### ThumbnailsFile.set_user_property(name: str, value: Any) -> bool

ユーザープロパティを設定します。

* `name`  
  プロパティ名を指定します。指定できる名前は `Document.set_user_property` の解説を参照してください。

* `value`  
  設定する値を指定します。`None` を指定するとプロパティが削除されます。

* 戻り値  
  正常にプロパティが設定された場合は `True` が、設定できなかった場合は場合は `False` が返ります。

#### ThumbnailsFile.get_user_property(name: str) -> Any

ユーザープロパティを取得します。

* `name`  
  プロパティ名を指定します。指定できる名前は `Document.set_user_property` の解説を参照してください。

* 戻り値  
  プロパティの値が返ります。プロパティが存在しない場合は `None` が返ります。

#### ThumbnailsFile.set_user_properties(properties: Dict) -> bool

すべてのユーザープロパティを設定します。

* `properties`  
  設定するプロパティ名をキーとしてその値を格納した dict を指定します。  
  指定できるプロパティは `Document.set_user_property` の解説を参照してください。  
  指定された dict に存在しないプロパティは削除されます。  
  空の dict を指定すると、すべてのプロパティが削除されます。

* 戻り値  
  正常にプロパティが設定された場合は `True` が、設定できなかった場合は場合は `False` が返ります。

#### ThumbnailsFile.get_user_properties() -> Dict

すべてのユーザープロパティを取得します。

* 戻り値  
  プロパティ名をキーとしてその値を格納した dict が返ります。  
  利用できるプロパティは `Document.set_user_property` の解説を参照してください。

#### ThumbnailsFile.media_type : str (read only)

ファイルのメディアです。取りうる値は `Document.media_type` を参照してください。  
この値はファイル名から求めたものであり、実際のファイルのメディアと異なる可能性もあります。

#### ThumbnailsFile.get_thumbnail_image() -> Image

ファイルのサムネイル画像を取得します。まだサムネイル画像が読み込まれていない場合は `None` が返ります。  
取得された画像は実際の画像のコピーです。


## 更新履歴

* rev.0.4.6 (PictureFan ver.0.62.0)  2026/6/13
  * Image クラスの set_/get_text に以下の変更を行った
    * キーに description を追加した
    * 任意のキーを指定できるようにした
    * name キーを title に変更した
  * Document クラスに format プロパティを追加した
  * ThumbnailsFolder クラスの type プロパティの値に history を追加した
  * ThumbnailsFile クラスに media_type プロパティと get_thumbnail_image 関数を追加した

* rev.0.4.5 (PictureFan ver.0.60.0)  2026/1/11
  * ディザリングの種類に floyd-steinberg を指定できるようにして、diffuse はデフォルトの誤差関数法の指定とした

* rev.0.4.4 (PictureFan ver.0.58.0)  2025/3/2
  * Image クラスの set_/get_metadata で XMP の設定と取得に対応した

* rev.0.4.3 (PictureFan ver.0.51.0)  2022/12/4
  * Document と ThumbnailsFile クラスに以下のメンバを追加した
    * set_user_property
    * get_user_property
    * set_user_properties
    * get_user_properties
  * WindowBase クラスに activate 関数を追加した

* rev.0.4.2 (PictureFan ver.0.47.0)  2022/3/19
  * ThumbnailsFolder クラスに type プロパティを追加した

* rev.0.4.1 (PictureFan ver.0.44.0)  2021/7/23
  * Application クラスに run_event プロパティを追加した
  * Application.run_context に Application を追加した

* rev.0.4.0 (PictureFan ver.0.43.0)  2021/1/24
  * Viewer クラスを追加した
  * Application クラスに以下のメンバを追加した
    * get_current_document
    * viewer_count
    * get_viewer
    * get_active_viewer
    * open_viewer
  * Application.run_context に Viewer を追加した
  * Document クラスに do_action 関数を追加した

* rev.0.3.3 (PictureFan ver.0.41.0)  2020/2/2
  * Document クラスに selected プロパティと get_/set_selected_rect 関数を追加した

* rev.0.3.2 (PictureFan ver.0.39.0)  2019/7/28
  * ThumbnailsFolder クラスに group プロパティを追加した
  * ThumbnailsWindow クラスに set_folder_index 関数を追加した

* rev.0.3.1 (PictureFan ver.0.38.0)  2019/4/22
  * ThumbnailsFolder.set_path/load に async 引数を追加した

* rev.0.3.0 (PictureFan ver.0.37.0)  2019/2/24
  * スクリプトの言語を Python に変更した

* rev.0.2.2 (PictureFan ver.0.25.0)  2012/11/4
  * Image オブジェクトの Resize に lanczos2/3/4 を追加した

* rev.0.2.1 (PictureFan ver.0.23.0)  2010/8/2
  * Image オブジェクトの Rotate の引数に resample と back_color を追加した  
    また、角度の指定を整数から浮動小数点数に変えた
  * Image オブジェクトの Resize に lanczos8 を追加した
  * いくつかのサンプルコードに間違いがあったのを修正した

* rev.0.2.0 (PictureFan ver.0.20.0)  2010/2/21
  * 48/64ビット画像に対応した
  * Image オブジェクトに以下のメンバを追加した
    * BitsPerPlane
    * PlanesPerPixel
    * To48Bits
    * To64Bits
  * Color オブジェクトに以下のメンバを追加した
    * SetRGB16
    * Red16
    * Green16
    * Blue16
    * Alpha16

* rev.0.1.0 (PictureFan ver.0.16.0)  2009/10/5
  * 最初のバージョン


[EOF]