Introdução ao script Python¶
Adicionado na versão 4.0.
Quando oferecemos scripts em Python como uma das metas estendidas do Kickstarter que poderíamos implementar junto com vetores e texto, ele conquistou a votação dos apoiadores com folga. Algumas pessoas até escolheram apenas Python e nada mais. Então, o que exatamente são scripts em Python?
O que é scripting em Python?¶
Python é uma linguagem de script que pode ser usada para automatizar tarefas. O que a linguagem de script Python no Krita significa é que adicionamos uma API ao Krita, que é um pouco de programação que permite que o Python acesse partes do Krita. Com isso, podemos criar painéis, executar tarefas simples em diversos arquivos e até mesmo escrever nossos próprios exportadores. Pessoas que trabalham com computação gráfica, como artistas de efeitos visuais e videogames, usam muito Python para criar coisas como folhas de sprites, automatizar partes de exportação e muito mais.
Está fora do escopo deste manual ensinar Python em si. No entanto, como Python é uma linguagem de programação extremamente popular e ótima para iniciantes, há muito material de aprendizagem disponível que pode ser encontrado rapidamente com uma simples busca na internet por “aprender Python”.
Este manual se concentrará em como usar o Python para automatizar e estender o Krita. Para isso, começaremos com o básico: como executar comandos Python no editor de script.
Como habilitar o plugin do editor de script¶
O plugin do editor de script não é necessário para usar Python, mas é muito útil para testar e experimentar com Python. É um console Python, escrito em Python, que pode ser usado para escrever pequenos scripts e executá-los dinamicamente.
Para abrir o scripter, navegue até . Se não o vir listado, acesse e ative a opção “Editor de script” na lista. Se não vir o plugin do do editor de script, certifique-se de estar usando uma versão atualizada do Krita.
O editor de script abrirá uma janela de editor de texto na parte superior e uma janela de saída na parte inferior. Insira o seguinte na área de texto:
print("olá mundo")
Pressione o botão grande de reprodução ou pressione o atalho Ctrl + R para executar o script. Em seguida, na área de saída, o seguinte deverá aparecer:
==== Warning: Script not saved! ====
olá mundo
Agora temos um console que pode executar funções como print() no ambiente Python - mas como podemos usá-lo para gerenciar o Krita?
Executando comandos básicos do Krita¶
Para permitir que o Python se comunique com o Krita, usaremos o módulo Krita. No topo de cada script, escreveremos from krita import *.
Isso nos permite conversar com o Krita por meio de Krita.instance(). Vamos tentar aprimorar nossas habilidades de codificação com Python.
from krita import *
Krita.instance().action('python_scripter').trigger()
Você deverá ver uma segunda janela do scripter aberta. Muito legal! Aqui está um exemplo um pouco mais avançado.
from krita import *
d = Krita.instance().createDocument(512, 512, "Documente teste do Python", "RGBA", "U8", "", 120.0)
Krita.instance().activeWindow().addView(d)
Isso abrirá um novo documento. Claramente, o Python oferece bastante controle para automatizar o Krita. Com o tempo, esperamos que a comunidade escreva todos os tipos de scripts que você possa usar simplesmente colando-os no editor de script.
Mas e se você quiser escrever novos comandos para si mesmo? O melhor lugar para começar é muito simples: procure exemplos escritos por outras pessoas! Você pode economizar muito tempo se outra pessoa tiver escrito código no qual você possa basear seu trabalho. Também vale a pena dar uma olhada nos plugins Python, que estão localizados em /share/krita/pykrita. Há também um guia passo a passo para Como criar um plugin Python para o Krita aqui no manual.
Mas é provável que você precise de mais informações. Para isso, precisaremos ver o que está escondido atrás do asterisco quando você importa * do Krita. Para saber quais funções do Krita estão disponíveis e como usá-las, consulte a documentação de referência da API do Krita.
API do Krita¶
Essas páginas podem parecer um monte de jargões à primeira vista. Isso ocorre porque a documentação da API do Krita vem da linguagem C++ subjacente em que o Krita foi escrito. A mágica acontece graças a uma ferramenta Python chamada SIP, que permite que o Python se comunique em C++ e com o Krita. O resultado final é que, quando importamos o krita e chamamos funções, estamos, na verdade, usando os métodos C++ listados nessa documentação.
Vamos ver como isso funciona em mais detalhes. Vamos dar uma olhada no segundo link, a Referência da classe Krita. Lá, podemos ver todas as funções disponíveis para a instância do Krita. Se você digitar dir(Krita.instance()) em Python, o resultado deve ser muito semelhante ao desta página - você pode consultar a documentação das funções createDocument(), activeWindow() e action() que usamos acima.
Uma das coisas mais confusas é ver todas as classes C++ que o Krita usa, incluindo as classes Qt que começam com Q. Mas aqui está a beleza do SIP: ele tenta tornar a tradução dessas classes para Python o mais simples e direta possível. Por exemplo, você pode ver que a função filters() retorna uma QStringList. No entanto, o SIP converte essas QStringLists em uma lista de strings Python comum!
from krita import *
print(Krita.instance().filters())
Saída 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']
No entanto, às vezes a conversão não ocorre tão facilmente.
from krita import *
print(Krita.instance().documents())
resulta em algo assim:
[<PyKrita.krita.Document object at 0x7f7294630b88>,
<PyKrita.krita.Document object at 0x7f72946309d8>,
<PyKrita.krita.Document object at 0x7f7294630c18>]
É uma lista de algo, claro, mas como usá-la? Se voltarmos à página do Krita no Apidocs e observarmos a função documents(), veremos que há um link clicável na classe “Document”. Se você seguir esse link, verá que o documento tem uma função chamada name(), que retorna o nome do documento, e as funções width() e height(), que retornam as dimensões. Portanto, se quiséssemos gerar um relatório de informações sobre os documentos no Krita, poderíamos escrever um script como este:
from krita import *
for doc in Krita.instance().documents():
print(doc.name())
print(" "+str(doc.width())+"x"+str(doc.height()))
Obtemos uma saída como:
==== Warning: Script not saved! ====
Unnamed
2480x3508
sketch21
3508x2480
Blue morning
1600x900
Espero que isso lhe dê uma ideia de como navegar pelos documentos da API agora.
A API do Krita possui muito mais classes. Você pode acessá-las acessando a lista de classes no canto superior esquerdo ou simplesmente clicando nos nomes para acessar a documentação da API. As funções print() ou dir() também são suas amigas aqui. Esta linha exibirá uma lista de todas as ações no Krita — você pode usar um destes comandos em vez de ‘python_scripter’ no exemplo acima.
[print([a.objectName(), a.text()]) for a in Krita.instance().actions()]
O módulo Python inspect foi projetado para esse tipo de tarefa. Aqui está uma função útil para imprimir informações sobre uma classe no console.
import inspect
def getInfo(target):
[print(item) for item in inspect.getmembers(target) if not item[0].startswith('_')]
getInfo(Krita.instance())
Por fim, além da documentação do LibKis, a documentação do Qt, já que o Krita usa PyQt para expor quase toda a API do Qt ao Python. Você pode construir janelas inteiras com botões e formulários dessa forma, usando as mesmas ferramentas que o Krita usa! Você pode ler a documentação do Qt e a documentação do PyQt para mais informações sobre isso, e também estudar os plugins incluídos para ver como eles funcionam.
Detalhes técnicos¶
Scripts Python no Windows¶
Para que o script Python funcione no Windows 7/8/8.1, você precisará instalar o Universal C Runtime do site da Microsoft. (O Windows 10 já vem com ele.)
Python 2 e 3¶
Por padrão, o Krita é compilado para o python 3.
No entanto, é possível compilá-lo com o Python 2. Para fazer isso, você precisará adicionar o seguinte à linha de configuração cmake:
-DENABLE_PYTHON_2=ON