Introdução à Programação em Python

Novo na versão 4.0.

Quando oferecemos a programação em Python como um dos passatempos do Kickstarter, havia a hipótese de ser implementada a seguir aos vectores e ao texto, mas passou à frente de tudo na altura. Algumas pessoas até escolheram Python e mais nada. Por isso, o que é exactamente a programação em Python?

O que é a Programação em Python?

O Python é uma linguagem de programação que poderá ser usada para automatizar as tarefas. O que a programação em Python significa no Krita é que foi adicionada uma API ao Krita, o que é uma espécie de programação que permite ao Python aceder a componentes do Krita. Com isto, podemos criar áreas acopláveis, efectuar tarefas frequentes com uma grande variedade de ficheiros diferentes e até criar os nossos módulos de exportação. As pessoas que lidam com computação gráfica, como o VFX e os artistas de jogos, usam o Python para um monte de coisas, como páginas de imagens dos jogadores, automatizar partes da exportação, entre outras coisas.

Está fora do âmbito deste manual ensinar-lhe o Python em si. Contudo, dado que o Python é uma linguagem de programação bastante popular e é óptima para principiantes, existem quantidades enormes de material de aprendizagem que pode encontrar rapidamente com uma pesquisa sobre “aprender Python” na Internet.

Este manual focar-se-á sim em como usar o Python para automatizar e estender o Krita. Para tal, iremos primeiro começar pelas bases: Como correr comandos em Python no programador.

Como Activar o “Plugin” do Programador

O “plugin” do programador não é necessário para usar o Python, mas é bastante útil para testar e brincar com o Python. É uma consola de Python, criada em Python, que pode ser usada para criar pequenos programas e executá-los na hora.

Para abrir o programador, vá a Ferramentas ‣ Programas ‣ Programador. Se não o encontrar aí, vá a Configuração ‣ Configurar o Krita… ‣ Gestor de “Plugins” em Python e active o «Programador» na lista para o activar. Se não estiver lá o “plugin” do programador, certifique-se que está a usar uma versão actualizada do Krita.

O programador irá aparecer com uma pequena janela de edição de texto no topo e uma janela de resultados em baixo. Introduza o seguinte na área de texto:

print("olá mundo")

Carregue no botão grande de reprodução ou carregue em Ctrl + R para executar o programa. Depois, em baixo, na área de resultados, deverá aparecer o seguinte:

==== Atenção: Programa não gravado! ====
olá mundo

Agora temos uma consola que consegue correr funções como o print() no ambiente de Python - mas como é que conseguimos usá-la para gerir o Krita?

Executar comandos básicos do Krita

Para permitir ao Python comunicar com o Krita, iremos usar o módulo do Krita. No topo de cada programa, iremos escrever: from krita import *.

Isto permite-nos aceder ao Krita.instance(). Vamos experimentar duplicar as nossas competências de programação em Python.

from krita import *

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

Deverá ver uma segunda janela do programador aberta. Muito bom! Agora está aqui um exemplo ligeiramente mais avançado.

from krita import *

d = Krita.instance().createDocument(512, 512, "Documento de teste em Python", "RGBA", "U8", "", 120.0)
Krita.instance().activeWindow().addView(d)

Isto irá agora abrir um novo documento. Claramente o Python dá-lhe um boa quantidade de controlo para automatizar o Krita. Com o tempo, esperamos que a comunidade crie todos os tipos de programas que possa usar, bastando para tal colá-los no programador.

Mas e se quiser criar comandos novos para si? O melhor local para começar é muito simples: procure por exemplos feitos por outras pessoas! Poderá poupar bastante tempo se alguém já tiver criado código no qual se possa basear. Também vale a pena olhar para os “plugins” de Python, que se localizam em /share/krita/pykrita. Existe também um manual passo-a-passo para o Como criar um “plugin” do Krita em Python aqui no manual.

Mas é provável que necessite de mais informações. Para tal, iremos ver o que está escondido atrás do asterisco quando executa import * from Krita. Para saber quais as funções do Krita que estão disponíveis e como usá-las, irá querer ver directamente a documentação de referência da API do Krita.

API do Krita

Estas páginas poderão parecer estar cheias de termos técnicos à primeira vista. Isto é porque a documentação da API do Krita é derivada da linguagem em C++ com que foi feito o Krita. A magia acontece por causa de uma ferramenta do Python chamada SIP, que permite que o Python fale em C++ e, por sua vez, com o Krita. O resultado final é que, quando invocamos o import krita e chamamos as funções, estamos de facto a usar os métodos em C++ apresentados nessa documentação.

Vejamos como isto funciona com mais detalhe. Vamos dar uma vista de olhos na segunda ligação, a referência da classe Krita. Aí poderemos ver todas as funções disponíveis na instância do Krita. Se escrever dir(Krita.instance()) em Python, deverá corresponder a esta página em grande medida - poderá ver a documentação das funções createDocument(), activeWindow() e action() que usámos anteriormente.

Um dos pontos mais confusos é ver todas as classes de C++ que o Krita usa, incluindo as classes do Qt que começam por Q. Mas aí está a beleza do SIP: ele tenta fazer a tradução dessas classes para o Python o mais simples e intuitivas que for possível. Por exemplo, poderá ver que a função filters() devolve uma QStringList. Contudo, o SIP converte essas QStringLists para listas de cadeias de caracteres normais do Python!

from krita import *

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

Devolve o resultado como:

['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']

Contudo, algumas vezes a conversão não corre assim tão bem.

from krita import *

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

dando-lhe algo como o seguinte:

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

É uma lista de algo, mas como é que se pode usá-la? Se voltarmos atrás à página da documentação da API do Krita e olhar para a função “documents()0, veremos que existe de facto uma ligação que poderá carregar para a classe “document”. Se seguir essa ligação <https://api.kde.org/extragear-api/graphics-apidocs/krita/libs/libkis/html/classDocument.html>`_, verá que o “Document” tem uma função chamada “name()” que devolve o nome do documento, bem como funções “width()” e “height()”, que devolvem as dimensões. Como tal, se quiséssemos criar um relatório informativo sobre os documentos no Krita, poderíamos criar um programa como o seguinte:

from krita import *

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

Iremos obter um resultado como o seguinte:

==== Atenção: Programa não gravado! ====
Sem nome
 2480x3508
desenho21
 3508x2480
Manhã azul
 1600x900

Esperamos que isto lhe dê uma ideia de como navegar pela documentação da API agora.

A API do Krita tem muitas mais classes; podê-las-á encontrar se for à lista de classes em cima e à esquerda, ou então simplesmente carregando no nome delas para obter a a documentação da sua API. As funções print() ou dir() são suas amigas aqui também. Esta linha irá imprimir uma lista com todas as acções no Krita - poderá trocar um desses comandos em vez do “python_scripter” do exemplo acima.

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

O módulo inspect do Python foi desenhado para este tipo de tarefas. Aqui está uma função útil para mostrar informações sobre uma classe na consola.

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

getInfo(Krita.instance())

Finalmente, para além da documentação da LibKis, a documentação do Qt, dado que o Krita usa o PyQt para expor praticamente toda a API do Qt ao Python. Poderá criar janelas completas com botões e formulários desta forma, usando as mesmas ferramentas que o Krita está a usar! Poderá ler a documentação do Qt e a documentação do PyQt para mais informações sobre o assunto, e definitivamente estudar os “plugins” incluídos para ver como funcionam.

Detalhes Técnicos

Programação em Python no Windows

Para ter a programação em Python a funcionar no Windows 7/8/8.1, precisa de instalar o ambiente de execução Universal C Runtime na página Web da Microsoft. (O Windows 10 já a traz de raiz.)

Python 2 e 3

Por omissão, o Krita foi compilado para o Python 3.

Contudo, é possível compilá-lo com o Python 2. Para o fazer, terá de adicionar o seguinte à linha de configuração do cmake:

-DENABLE_PYTHON_2=ON