Krita Scripting Components

This record is a part of the materials for Krita Scripting Series. Before reading further, make sure to study materials published before.

With decent enough understanding of python, let’s dive into components that make the Krita Scripting itself.

The components are Krita, Window, View, Document, Node and Action.

The entry point for scripting at all is the Krita application instance.

from krita import Krita

def run():
    app: Krita = Krita.instance()
    print(app)

run()

To get access to all other components you need to first get the instance of the application. First and major component that you get is the Window component. By referencing to a window you can get access to the views. Another helpful aspect is to reference qwindow(), the Qt handle for Krita’s widgets. This can come in handy if you want to manually trigger the click event on the Toolbox or perform other actions with the UI directly. This is the hacky way of getting around some of the aspect of the Krita Scripting that are not yet supported by Python API.

from krita import Krita, Window

def run():
    app: Krita = Krita.instance()
    win: Window = app.activeWindow()
    qwin = win.qwindow()
    print(app)
    print(win)
    print(qwin)

run()

With the reference to the view you can access the foreground and background color that are currently selected in the editor. You can also change these colors. As well as manipulate the brush size or orientation. Reference currently selected layers.

from krita import Krita, Window, View

def run():
    app: Krita = Krita.instance()
    win: Window = app.activeWindow()
    view: View = win.activeView()
    print(view)

run()

The document is the alias to Krita image. The reference to the document here is the reference to active image you have opened in the application. More often than not you will refer to active document. However, you are not limited to it and can reference to other documents as well.

With the instance of the Document class you can perform most of the operations that are relevant to the image. The most operations we will be interested in are creating the layers.

from krita import Krita, Document

def run():
    app: Krita = Krita.instance()
    doc: Document = app.activeDocument()
    print(doc)

run()

In Krita Python API the layers are referred as Nodes. Essentially, a node is the reference to particular layer. We will use terms layer and node interchangeably.

To get the list of all selected layers you use reference to view. To make new layer you use the reference to document. When adding new layer you need to specify the parent layer. To add the layer to main list you can use root layer. Child layers can be added to a group. Masks can be added as children to any layer.

from pprint import pprint
from krita import Krita, View, Document, Node

def run():
    app: Krita = Krita.instance()
    view: View = app.activeWindow().activeView()
    doc: Document = app.activeDocument()
    
    selected_nodes = view.selectedNodes()
    pprint(selected_nodes)

    root = doc.rootNode()
    print(root)
    node = doc.createNode("New Paint Layer", "paintlayer")
    print(node)
    root.addChildNode(node, None)

run()

Here we demonstrate how to get access to selected layers (line 9) and add new layer. We first get the reference to the root node (line 12), then we create a new layer (line 14). Notice that when make a new layer it will not be added to the layers list right away. You should add this layer to the parent manually. This extra step let as perform extra operations on the node before we show it to the artist.

The createNode() method of the document object has two arguments. First, is the name of the layer to be displayed in the layers docker. Second, is the type of the layer (we mentioned it above).

To add the the node to the parent (the root in our case) we call the addChildNode by the parent and provide the layer we want to add.

addChildNode has two arguments, the node we want to add and the reference to the node that we want to be below our own layer. We set the None here, in this case the layer will be placed on top of the list.

You probably noticed on the line 6 that we get access to the view right away, bypassing the window reference. This is a common practice when you need the reference of the object without keeping the intermediate reference. This is called method chaining.

What is going on here is the following. We have the reference to the app and use it to get the reference to the active window, without storing the reference to the active window we use it to get the reference to the active view right away.

Note on imports.

As you can see, when want to have particular class from the Krita (or any other modules) we explicitly list the names of these classes and functions. We recommend to use this approach since this way your code will be easier to read and you will have a better understanding what kind of class where is coming from.

This is a counter-example for this kind of import

from PyQt5 import *
from krita import *

You might see this kind of import on the forums. Usually people do it to safe time. We recommend to figure out each of the imports (when using such examples) and replace asterisk with proper import names.

Final words

Krita has way more components to the scripting. Nevertheless, these are the entry points to all others. By using these classes and following their methods and what they return you eventually entangle the whole Python API world.

Onward, Operations with Layers.