Introduzione agli script di Python¶
Added in version 4.0.
Quando offrimmo gli script di Python come uno dei «stretchgoal» su Kickstarter che potevamo implementare assieme ai vettori e al testo, essi vinsero grazie ai voti a valanga dei sostenitori. Addirittura alcuni scelsero solo Python e nient’altro. Cosa sono dunque esattamente gli script di Python?
Cosa sono gli script di Python?¶
Python è un linguaggio di script che può essere utilizzato per automatizzare processi. Gli script di Python hanno acquisito un significato in Krita quando abbiamo aggiunto un’API a Krita, che è un po` di codice che permette a Python l’accesso a parti di Krita. Con questo possiamo creare aree di aggancio, eseguire umili attività su un sacco di file diversi e persino scrivere i nostri strumenti di esportazione personalizzati. Chi lavora con la computer grafica, come gli artisti di VFX e di video game, usa molto Python per creare cose tipo fogli sprite, automatizzare parti di esportazioni e altro ancora.
Insegnare l’uso di Python non è l’obbiettivo di questo manuale. Tuttavia, dato che Python è un linguaggio di programmazione molto popolare e ottimo per i principianti, esiste moltissima documentazione sull’argomento facilmente reperibile con la semplice digitazione di «imparare python» su un motore di ricerca internet.
Questo manuale si concentrerà invece sull’utilizzo di Python per automatizzare e ampliare Krita. Per fare questo, partiremo dalla base: come eseguire i comandi python nel creatore di script.
Come abilitare l’estensione Creatore di script¶
Il Creatore di script non è necessario per usare Python, ma è molto utile per eseguire delle prove con esso. È una console python, scritta in Python, che può essere utilizzata per scrivere piccoli script ed eseguirli al volo.
Per aprire il creatore di script, vai al menu . Se non è elencato, vai a e attiva «Creatore script» nell’elenco per abilitarlo. Se non riesci a vedere l’estensione, assicurati di avere installato una versione aggiornata di Krita.
Il creatore di script si aprirà con una finestra per la modifica del testo in alto e una finestra del risultato in basso. Digita il seguente testo nell’area di testo:
print("ciao mondo")
Premi il pulsante di riproduzione o premi la scorciatoia Ctrl + R per eseguire lo script. Nell’area del risultato in basso deve apparire:
==== Warning: Script not saved! ====
ciao mondo
Ora abbiamo una console in grado di avviare funzioni tipo print() dall’ambiente python. Ma come lo utilizziamo per gestire Krita?
Eseguire comandi per Krita di base¶
Per permettere a Python di comunicare con Krita, useremo il modulo Krita. All’inizio di ogni script, scriveremo from krita import *.
Questo ci consente di dialogare con Krita tramite Krita.instance(). Proviamo a raddoppiare le nostra abilità di programmazione con Python.
from krita import *
Krita.instance().action('python_scripter').trigger()
Dovresti vedere aprirsi una seconda finestra del creatore di script. Molto bene! Ecco un esempio un po` più avanzato.
from krita import *
d = Krita.instance().createDocument(512, 512, "documento test di Python", "RGBA", "U8", "", 120.0)
Krita.instance().activeWindow().addView(d)
Questo comando aprirà un nuovo documento. Python ti offre chiaramente molto controllo per l’automazione di Krita. Col tempo, ci attendiamo che la comunità scriva tanti tipi di script da utilizzare semplicemente incollandoli nel creatore di script.
Ma se volessi scrivere personalmente nuovi comandi? Il posto migliore dove iniziare è semplice: cerca esempi scritti da altre persone! Puoi risparmiare un sacco di tempo se trovi del codice già scritto su cui basare il tuo lavoro. Vale la pena cercare anche tra le estensioni di Python, che si trovano in /share/krita/pykrita. Esiste anche una guida dettagliata per Come creare un’estensione python per Krita qui nel manuale.
Ma probabilmente hai necessità di ulteriori informazioni. Per questo, dobbiamo vedere cosa si cela dietro l’asterisco quando scrivi import * from Krita. Per sapere quali sono e come usare le funzioni disponibili di Krita, devi accedere alla documentazione di riferimento dell’API di Krita.
API di Krita¶
Queste pagine (in inglese) possono sembrare un gergo molto tecnico, a prima vista. Ciò deriva dal fatto che la documentazione API di Krita proviene dal linguaggio C++ soggiacente in cui Krita è scritto. La magia si avvera grazie a uno strumento python chiamato SIP, che permette a Python di parlare in C++ e dialogare con Krita. Il risultato finale è che quando scriviamo import krita e richiamiamo le funzioni, stiamo in realtà utilizzando i metodi C++ elencati in quella documentazione.
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.
Una delle cose che confondono di più è vedere tutte le classi C++ che usa Krita, incluse le classi Qt che iniziano con Q. Ma è qui che sta la bellezza di SIP: tenta di tradurre queste classi in Python nel modo più semplice e diretto possibile. Per esempio, puoi notare che la funzione filters() restituisce una QStringList. SIP converte, tuttavia, queste QStringLists in normali liste python di stringhe!
from krita import *
print(Krita.instance().filters())
Restituisce il risultato:
['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']
A volte, comunque, la conversione non va esattamente liscia.
from krita import *
print(Krita.instance().documents())
Restituisce qualcosa come questo:
[<PyKrita.krita.Document object at 0x7f7294630b88>,
<PyKrita.krita.Document object at 0x7f72946309d8>,
<PyKrita.krita.Document object at 0x7f7294630c18>]
It is a list of something, sure, but how to use it? If we go back to the Krita apidocs page and look at the function, documents() we’ll see there’s actually a clickable link on the “Document” class. If you follow that link, you’ll see that the document has a function called name() which returns the name of the document, and functions width() and height() which return the dimensions. So if we wanted to generate an info report about the documents in Krita, we could write a script like this:
from krita import *
for doc in Krita.instance().documents():
print(doc.name())
print(" "+str(doc.width())+"x"+str(doc.height()))
Otteniamo un risultato tipo:
==== Warning: Script not saved! ====
Unnamed
2480x3508
sketch21
3508x2480
Blue morning
1600x900
Speriamo che questo ti abbia dato un’idea su come navigare tra la documentazione delle API.
L’API di Krita ha molte altre classi, puoi ottenerle andando nella parte superiore sinistra dell’elenco delle classi, oppure facendo clic sul loro nome per avere i documenti delle loro API. Anche le funzioni print() o dir() qui sono tue amiche. Questa riga stamperà un elenco di tutte le azioni presenti in Krita: puoi scambiare uno di questi comandi al posto di “python_scripter” nell’esempio riportato in precedenza.
[print([a.objectName(), a.text()]) for a in Krita.instance().actions()]
Il modulo python inspect è stato progettato per questo genere di attività. Ecco una funzione utile per stampare nella console informazioni su una classe.
import inspect
def getInfo(target):
[print(item) for item in inspect.getmembers(target) if not item[0].startswith('_')]
getInfo(Krita.instance())
Per finire, oltre alla documentazione LibKis, la documentazione Qt, dato che Krita usa PyQt per far comunicare quasi tutte le API Qt con Python. Con questo metodo puoi costruire intere finestre con pulsanti e formulari, utilizzando praticamente gli stessi strumenti che utilizza Krita! Per maggiori informazioni su questi aspetti, consulta la documentazione Qt e la documentazione PyQt, per imparare con chiarezza le estensioni incluse e osservarne il funzionamento.
Dettagli tecnici¶
Script di Python in Windows¶
Per ottenere script python funzionanti in Windows 7/8/8.1, devi installare Universal C Runtime dal sito web di Microsoft (Windows 10 lo comprende già).
Python 2 e 3¶
Per impostazione predefinita, Krita è compilato per Python 3.
Puoi comunque compilarlo con Python 2. Per farlo devi aggiungere il comando seguente alla riga di configurazione di cmake:
-DENABLE_PYTHON_2=ON