Introduzione agli script di Python¶
Nuovo nella versione 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.
Vediamo più in dettaglio come funzionano queste cose. Diamo un’occhiata al secondo collegamento, il riferimento per le classi di Krita. Qui possiamo osservare tutte le funzioni disponibili nell’istanza di Krita. Se digiti dir(Krita.instance()) in Python, dovrebbe corrispondere a questa pagina quasi completamente: puoi visualizzare la documentazione delle funzioni createDocument(), activeWindow() e action() che abbiamo usato sopra.
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>]
È un elenco di qualcosa, sicuramente, ma come utilizzarlo? Se ritorniamo alla pagine della documentazione API di Krita e diamo uno sguardo alla funzione, documents(), noteremo che esiste in realtà un collegamento attivo sulla classe “Document”. Se segui quel collegamento, noterai che il documento possiede una funzione chiamata name() che restituisce il nome del documento, e le funzioni width() e height() che restituiscono le dimensioni. Se, dunque, volessimo generare un rapporto informativo sui documenti in Krita, potremmo scrivere uno script di questo tipo:
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