Layers

Work with layers by adding, modifying, and deleting

The scripting API for layers allows you to create, edit, and delete layers. Most of the commands are accessible with either using actions or through the Krita Node API.

Getting access to layers

There are a few different ways to access layers.

application = Krita.instance()
currentDoc = application.activeDocument()

# get the current selected layer, called a 'node'
currentLayer = currentDoc.activeNode()

# gets layers that are not nested
# you will need to loop through them if you want all layers
nodesList = currentDoc.topLevelNodes()

# find a node by name
# this will also search child/nested layers
layerFoundByName = currentDoc.nodeByName("Paint 2")

Another common scenario is going through all layers and doing stuff. This is a simple use case of going through all layers and locking them.

application = Krita.instance()
currentDoc = application.activeDocument()

# gets layers that are not nested
# you will need to loop through them if you want all layers
topLevelLayers = currentDoc.topLevelNodes()

for layer in topLevelLayers:
  layer.setLocked(True)

While this code will work great if we only have one level, it will not go into group layers and update those children. We will need to just add a bit more code to go inside those and do a similar thing

application = Krita.instance()
currentDoc = application.activeDocument()

# grab all top level nodes
topLevelLayers = currentDoc.topLevelNodes()

for layer in topLevelLayers:
  layer.setLocked(True)
  
  # grab the layer children to see if we need to set those
  layerChildren = layer.childNodes() 
    
  if len( layerChildren ) > 0:
      # we have children, so loop through those
      for child in layerChildren:
          child.setLocked(True)

This is just doing more loops inside of loops looking through children. This will go one level deep. Of course there could be two, three, or more levels deep of children. We won't go into all the ways this could work, but you would have to create a recursive function that would keep going deeper as long as there are more children.

Doing actions on layers

Now that you know a few ways to access layers, you probably want to do things with them. For simple operations, there are many things you can do with simply using actions

application = Krita.instance()

# a few avaialable actions you could do
application.action('merge_layer').trigger()

application.action('duplicatelayer').trigger()

application.action('copy_layer_clipboard').trigger()

application.action('move_layer_up').trigger()

When you use actions like above, It is important to know that the action is done ONLY on the currently selected layer. When you grab a layer, you first need to select it as the active layer. Then you can perform the actions. Like this.

application = Krita.instance()
currentDoc = application.activeDocument()

# find a node by name
layerFoundByName = currentDoc.nodeByName("Paint 2")

# change our active layer selection to the layer we found
currentDoc.setActiveNode(layerFoundByName)

# now all our layer actions will affect Paint 2
application.action('duplicatelayer').trigger()

Changing properties on layers

We have the ability to access and change a lot of the layer's properties with more precision. In this next example, we are going to create a document, then change the opacity of the current layer.

# create new document createDocument(width, height, name, colorSpace, bitDepth, colorProfile, DPI)
newDocument = Krita.instance().createDocument(1280, 1024, "Document name", "RGBA", "U8", "", 300.0)
Krita.instance().activeWindow().addView(newDocument) # shows it in the application

# do things with a layer
currentLayer = newDocument.activeNode()
currentLayer.setOpacity(128) # 0-255 translates to 0-100%
newDocument.refreshProjection() # redraw the canvas on the screen with the new opacity change

After the document is created, we grab active layer, called a “node” and change the opacity. Notice the last line with “refreshProjection()”. If that line is not there, you would not see your canvas updated on screen. The reason this exists is you might want to do 5-10 things with the canvas. It is much faster if Krita can do everything first before it spends time drawing all those pixels on the canvas.

There are a lot of properties you can change from the Krita Node API. See this API reference to see all the available things you can do with layers/nodes.

Removing layers and performing more actions

We went over how to grab and perform actions on layers. Deleting a layer is just another action. This is how you would find a layer you want to delete, then delete it.

application = Krita.instance()
currentDoc = application.activeDocument()

# find a node by name
layerFoundByName = currentDoc.nodeByName("Paint 2")

# change our active layer selection to the layer we found
currentDoc.setActiveNode(layerFoundByName)

# Delete this layer
application.action('remove_layer').trigger()

There are a lot of actions that can be done with layers. To see a list of them all, head over to the action dictionary page and do a search for "layer". use the id for the action name in your scripting.

< Previous Lesson

Signals and slots

Next Lesson >

Selections

Have questions, need help, or find a typo?

Head to the Krita artists where we have a dedicated area for plugin development and give any feedback you might have.

MAIN CONCEPTS

PLUGIN DEVELOPMENT

REFERENCES

;