Python スクリプトへの導入

バージョン 4.0 で追加.

ベクターとテキストに並んで Kickstarter のゴールの一つとして Python スクリプトの実装を紹介したときに、支援者の投票で圧勝しました。Python だけでほかに何も選ばなかった人もいます。では Python スクリプトとは何でしょうか?

Python スクリプトって何?

Python はスクリプト言語で、タスクを自動化するのに使われます。Krita で Python スクリプトが意味することろは Krita に API を追加し、Krita の部分に Python プログラミングを使ってアクセスできることです。これでドッカーを作り、たくさんの異なるファイルに単純な処理をさせたりエクスポート自体を作ることもできます。VFX やビデオゲームアーティストといったコンピュータグラフィックで働く人はスプライトシートのようなものを作るのに Python を良く使い、エクスポートや他の作業の一部を自動化しています。

Python 自体を説明するのはこのマニュアルの範囲外です。しかし、Python がかなり良く使われるプログラミング言語で初心者にはもってこいであることから、インターネットの検索で 'Python 学ぶ' と検索すればたくさんの教材がすぐに見つかるでしょう。

このマニュアルでは代わりに Krita の自動化と拡張に Python を使うことを主に扱います。まず基礎から始めます: Scripter での Python スクリプトの動かし方です。

Scripter プラグインを有効にする

Scripter プラグインは Python を使うのに必須ではありませんが、Python で試したり遊ぶのにはとても有用です。これは Python で書かれた Python コンソールで、小さなスクリプトを書いて直接実行できます。

scripter を開くには、ツール ‣ スクリプト ‣ Scripter に行きます。もしリストになければ、設定 ‣ Krita の設定を変更... ‣ Python プラグインマネージャ からリストの "Scripter" をオンにします。もしそこにもなければ、最新版の Krita を使用しているか確認してください。

上にテキストエディタ下に出力ウィンドウの scripter が現れます。以下をテキストに入力します:

print("hello world")

大きな再生ボタンか Ctrl + R ショートカットを押すことでスクリプトを実行します。それから下の、出力エリアに次のように表示されるはずです:

==== Warning: Script not saved! ====
hello world

これで Python 環境の print() のような関数を実行させるコンソールができました - でもこれでどうやって Krita を動かすのでしょうか?

Krita 基本のコマンドを実行

To allow Python to communicate with Krita, we will use the Krita module. At the top of every script, we will write from krita import *.

これで Krita.instance() 経由で Krita と話すことができます。Python でのプログラミング能力を2倍にしましょう。

from krita import *

Krita.instance().action('python_scripter').trigger()

2つ目の scripter ウィンドウが開くのが見えるはずです。良いでしょう!これがより発展的な例です。

from krita import *

d = Krita.instance().createDocument(512, 512, "Python test document", "RGBA", "U8", "", 120.0)
Krita.instance().activeWindow().addView(d)

これは新しいドキュメントを開きます。Python を使って Krita の本当に多くの操作を自動化できるのがわかると思います。時間が経つにつれコミュニティが scripter に通すだけで使える様々なスクリプトを書くのを私たちは期待しています。

でもご自身で新しいコマンドを書きたいときは?始めるのに最も良い場所はとてもシンプルです: 他の人が書いた例を検索しましょう!自分がしたいことに使える他の人が書いたコードがあれば多くの時間を節約できます。また /share/krita/pykrita にある Python プラグインに目を通すのもまた良いでしょう。このマニュアルの How to make a Krita Python plugin にもガイドがあります。

でもおそらくもっと情報が必要でしょう。それには import * from Krita のアスタリスクに何が隠れているか知る必要があります。Krita で使える関数や使い方についてもっと知りたいときは、Krita API リファレンスドキュメントに行きます。

Krita の API

これらのページは最初はちんぷんかんぷんに見えるかもしれません。なぜなら Krita の API ドキュメントは Krita が書かれた C++ 言語に基づいているからです。魔法は Python の SIP と呼ばれるツールから起こるのであり、Python に C++ で Krita と会話できるようになります。結果は import krita と関数を呼び出したときに、ドキュメントに書かれている C++ メソッドを実際に使っています。

Let's see how this stuff works in more detail. Let's take a look at the second link, the Krita class reference. There we can see all the functions available to the Krita instance. If you type dir(Krita.instance()) in Python, it should match this page very closely - you can view the documentation of the functions createDocument(), activeWindow(), and action() which we used above.

One of the more confusing things is seeing all the C++ classes that Krita uses, including the Qt classes that start with Q. But here is the beauty of SIP: it tries to make the translation from these classes into Python as simple and straightforward as possible. For example, you can see that the function filters() returns a QStringList. However, SIP converts those QStringLists into regular python list of strings!

from krita import *

print(Krita.instance().filters())

出力は:

['asc-cdl', 'autocontrast', 'blur', 'burn', 'colorbalance', 'colortoalpha', 'colortransfer',
'desaturate', 'dodge', 'edge detection', 'emboss', 'emboss all directions', 'emboss horizontal and vertical',
'emboss horizontal only', 'emboss laplascian', 'emboss vertical only', 'gaussian blur', 'gaussiannoisereducer',
'gradientmap', 'halftone', 'height to normal', 'hsvadjustment', 'indexcolors', 'invert', 'lens blur', 'levels',
'maximize', 'mean removal', 'minimize', 'motion blur', 'noise', 'normalize', 'oilpaint', 'perchannel', 'phongbumpmap',
'pixelize', 'posterize', 'raindrops', 'randompick', 'roundcorners', 'sharpen', 'smalltiles', 'threshold', 'unsharp',
'wave', 'waveletnoisereducer']

しかし、時々変換はスムーズにはいきません。

from krita import *

print(Krita.instance().documents())

こんな感じになります:

[<PyKrita.krita.Document object at 0x7f7294630b88>,
<PyKrita.krita.Document object at 0x7f72946309d8>,
<PyKrita.krita.Document object at 0x7f7294630c18>]

これは何かのリストでしょう、ええ、でもどうやって使えと? Krita の API ドキュメントページに戻って関数 documents() を見ると、実際にクリックできる 'Document' クラスがあります。リンク をたどり、ドキュメントの名前を返す関数 name()、解像度を返す関数 width() と height() があるのがそのドキュメントで見られます。つまりもし Krita でドキュメントについての情報を生成してレポートさせるには、このようなスクリプトを書くことができます:

from krita import *

for doc in Krita.instance().documents():
    print(doc.name())
    print(" "+str(doc.width())+"x"+str(doc.height()))

出力はこのようになります:

==== Warning: Script not saved! ====
Unnamed
 2480x3508
sketch21
 3508x2480
Blue morning
 1600x900

これが API ドキュメントの見方についての良いヒントになれば幸いです。

Krita's API has many more classes, you can get to them by going to the top-left class list, or just clicking their names to get to their API docs. The functions print() or dir() are your friends here as well. This line will print out a list of all the actions in Krita -- you could swap in one of these commands instead of 'python_scripter' in the example above.

[print([a.objectName(), a.text()]) for a in Krita.instance().actions()]

Python モジュール inspect はこのような作業のために作られました。コンソールにクラスに関する情報を出力する便利な機能がこれです。

import inspect
def getInfo(target):
    [print(item) for item in inspect.getmembers(target) if not item[0].startswith('_')]

getInfo(Krita.instance())

最後に、LibKis documentation の補足として、Qt documentation では、Krita が PyQt を使ってほぼすべての Qt API を Python に触れさせています。この方法でウィンドウ全体のボタンとフォームを、Krita が使っているツールと全く同じものを作れます!詳しくは Qt documentationPyQt documentation で読むことができ、また含まれるプラグインについてもどのように動くのか学べます。

技術的な詳細

Windows 上の Python スクリプト

Python スクリプトを Windows 7/8/8.1 で動かすには、マイクロソフトのウェブサイトからユニバーサル C ランタイム をインストールする必要があります。(Windows 10 には既に含まれています)

Python 2 と 3

By default, Krita is compiled for python 3.

However, it is possible to compile it with python 2. To do so, you will need to add the following to the cmake configuration line:

-DENABLE_PYTHON_2=ON