# Script

In &chalk;, puoi scrivere script in Ruby o Python (la disponibilità degli interpreti potrebbe dipendere dalla tua distribuzione o da cosa ha installato il tuo amministratore). Qui vedrai una descrizione dell'API degli script.

Alcuni esempi sono distribuiti con &chalk;, e potresti trovarli sotto `/usr/share/apps/chalk/scripts` (o `/opt/kde/share/apps/chalk/scripts`).

## Variabili nel modulo `Krosschalkcore`

- `ChalkDocument` restituisce un oggetto `Document`

- `ChalkScript` restituisce un oggetto `ScriptProgress`

Puoi recuperare un oggetto usando la funzione `get` del modulo `Krosschalkcore`, in Ruby dovrai fare qualcosa come:

    doc = Krosschalkcore::get("DocumentoDiChalk")
    script = Krosschalkcore::get("ScriptDiChalk")

## Funzioni nel modulo `Krosschalkcore`

- Funzione: `getBrush`

  Questa funzione restituisce un `Brush` preso dall'elenco delle risorse di &chalk;. Prende un argomento: il nome del pennello. Per esempio (in Ruby):

      Krosschalkcore::getBrush("Circle (05)")

- Funzione: `getFilter`

  Questa funzione restituisce un `Filter` preso dall'elenco delle risorse di &chalk;. Prende un argomento: il nome del filtro. Per esempio (in Ruby):

      Krosschalkcore::getFilter("invert")

- Funzione: `getPattern`

  Questa funzione restituisce un `Pattern` preso dall'elenco delle risorse di &chalk;. Prende un argomento: il nome del motivo. Per esempio (in Ruby):

      Krosschalkcore::getPattern("Bricks")

- Funzione: `loadBrush`

  Questa funzione carica un `Brush` e lo restituisce. Prende un argomento: il nome file del pennello.

- Funzione: `loadPattern`

  Questa funzione carica un `Pattern` e lo restituisce. Prende un argomento: il nome file del motivo.

- Funzione: `newCircleBrush`

  Questa funzione restituisce un `Brush` di forma circolare. Prende almeno due argomenti: larghezza e altezza. Ne può prendere altri due: larghezza e altezza della sfumatura. Se la sfumatura non è specificata, non verrà usata. Per esempio (in Ruby):

      Krosschalkcore::newCircleBrush(10,20) # crea un cerchio semplice
      Krosschalkcore::newCircleBrush(10,20,5,10) # crea una sfumatura

- Funzione: `newHSVColor`

  Questa funzione restituisce un nuovo `Color` con la tripletta HSV data. Prende tre argomenti: componente di tonalità (da 0 a 255), componente di saturazione (da 0 a 255), componente di valore (da 0 a 255). Per esempio (in Ruby):

      Krosschalkcore::newHSVColor(255,125,0)

- Funzione: `newImage`

  Questa funzione restituisce un nuovo `Image`. Prende quattro argomenti: larghezza, altezza, identificativo dello spazio dei colori, nome dell'immagine. In cambio ottieni un oggetto `Image`. Per esempio (in Ruby):

      Krosschalkcore::newImage(10,20, "RGBA", "kikoo")

- Funzione: `newRectBrush`

  Questa funzione restituisce un nuovo `Brush` di forma rettangolare. Prende almeno due argomenti: larghezza e altezza. Può prenderne altri due: larghezza e altezza della sfumatura. Se la sfumatura non è specificata, non verrà usata. Per esempio (in Ruby):

      Krosschalkcore::newRectBrush(10,20) # crea un rettangolo semplice
       Krosschalkcore::newRectBrush(10,20,5,10) # crea una sfumatura

- Funzione: `newRGBColor`

  Questa funzione restituisce un nuovo `Color` con la tripletta RGB data. Prende tre argomenti: componente del rosso (da 0 a 255), componente del verde (da 0 a 255), componente del blu (da 0 a 255). Per esempio (in Ruby):

      Krosschalkcore::newRGBColor(255,0,0) # crea un colore rosso
      Krosschalkcore::newRGBColor(255,255,255) # crea un colore bianco

## Descrizioni ed elenchi di funzioni per vari oggetti in `Krosschalkcore`

- Oggetto: PaintLayer

  - Funzione: `beginPainting`

  - Funzione: `convertToColorspace`

    Converte l'immagine in uno spazio di colori. Questa funzione prende un argomento: il nome dello spazio di colori di destinazione. Per esempio (in Ruby):

        image.convertToColorspace("CMYK")

  - Funzione: `createHistogram`

    Questa funzione crea un istogramma per questo livello. Prende due argomenti: il tipo di istogramma ("RGB8HISTO"), e 0 se l'istogramma è lineare, o 1 se è logaritmico.

  - Funzione: `createHLineIterator`

    Crea un iteratore su un livello, itererà su una riga. Questa funzione prende tre argomenti: `x` (inizio sulla riga), `y` (posizione verticale della riga), larghezza della riga.

  - Funzione: `createPainter`

    Questa funzione crea un `Painter` che ti permetterà di disegnare sul livello.

  - Funzione: `createRectIterator`

    Crea un iteratore su un livello, itererà su un'area rettangolare. Questa funzione prende quattro argomenti: `x`, `y`, larghezza e altezza del rettangolo.

  - Funzione: `createVLineIterator`

    Crea un iteratore su un livello, itererà su una colonna. Questa funzione prende tre argomenti: `x` (posizione orizzontale della colonna), `y` (inizio nella colonna), altezza della colonna.

  - Funzione: `endPainting`

    Questa funzione chiude la voce di annullamento attuale e la aggiunge alla cronologia.

  - Funzione: `fastWaveletTransformation`

    Restituisce la trasformata veloce wavelet del livello.

  - Funzione: `fastWaveletUntransformation`

    Detrasforma un wavelet veloce in questo livello. Prende un argomento: un oggetto wavelet. Per esempio (in Ruby):

        wavelet = layer.fastWaveletTransformation()
        layer.fastWaveletUntransformation(wavelet)

  - Funzione: `getHeight`

    Restituisce l'altezza del livello.

  - Funzione: `getWidth`

    Restituisce la larghezza del livello.

- Oggetto: `Filter`

  - Funzione: `getFilterConfiguration`

    Questa funzione restituisce il `FilterConfiguration` associato con questo filtro.

  - Funzione: `process`

    Questa funzione applicherà il filtro. Prende almeno un argomento: il livello sorgente. Puoi anche usare questi quattro argomenti: `x`, `y`, `width`, `height`. (`x`, `y`, `width`, `height`) definisce l'area rettangolare su cui il filtro sarà calcolato. Se il rettangolo non è definito, il filtro sarà applicato su tutto il livello originario. Per esempio (in Ruby)

        doc = Krosschalkcore::get("DocumentoChalk")
        image = doc.getImage()
        layer = image.getActivePaintLayer()
        width = layer.getWidth()
        height = layer.getHeight()
        filter = Krosschalkcore::getFilter("invert")
        filter.process(layer, layer)
        filter.process(layer, layer, 10, 10, 20, 20)

- Oggetto: `FilterConfiguration`

  - Funzione: `getProperty`

    Questa funzione restituisce il valore del parametro del `Filter` associato. Prende un argomento: il nome del parametro.

  - Funzione: `setProperty`

    Questa funzione definisce un parametro del `Filter` associato. Prende due argomenti: il nome e il valore del parametro, il cui tipo dipende dal `Filter`.

- Oggetto: `Histogram`

  Questa classe ti permette di accedere all'istogramma di un `PaintLayer`. Esempio (in Ruby):

      doc = krosschalkcore::get("DocumentoChalk")
       image = doc.getImage()
       layer = image.getActiveLayer()
       histo = layer.createHistogram("RGB8HISTO",0)
       min = layer.getMin() * 255
       max = layer.getMax() * 255
       for i in min..max
         print layer.getValue(i)
         print "\n"
       end

  - Funzione: `getChannel`

    Restituisce il canale selezionato.

  - Funzione: `getCount`

    Questa funzione restituisce il numero di pixel usati dall'istogramma.

  - Funzione: `getHighest`

    Questa funzione restituisce il valore massimo dell'istogramma.

  - Funzione: `getLowest`

    Questa funzione restituisce il valore minimo dell'istogramma.

  - Funzione: `getMax`

    Questa funzione restituisce il limite massimo dell'istogramma (i valori a posizioni maggiori del massimo sono nulli). Il valore è nell'intervallo 0,0–1,0.

  - Funzione: `getMean`

    Questa funzione restituisce la media dell'istogramma.

  - Funzione: `getMin`

    Questa funzione restituisce il limite minimo dell'istogramma (i valori a posizioni inferiori del minimo sono nulli). Il valore è nell'intervallo 0,0–1,0.

  - Funzione: `getNumberOfBins`

    Restituisce il numero di colonne dell'istogramma.

  - Funzione: `getTotal`

    Questa funzione restituisce la somma di tutti i valori dell'istogramma.

  - Funzione: `getValue`

    Restituisce il valore di una colonna dell'istogramma. Questa funzione prende un argomento: l'indice, nell'intervallo [0..255].

  - Funzione: `setChannel`

    Seleziona il canale del livello da cui ottenere il risultato dell'istogramma. Questa funzione prende un argomento: il numero del canale.

- Oggetto: `ScriptProgress`

  `ScriptProgress` viene usato per gestire la barra di avanzamento della barra di stato di &chalk;. Per esempio (in Ruby):

      script = Krosschalkcore::get("ChalkScript")
      script.setProgressTotalSteps(1000)
      script.setProgressStage("progressive", 0)
      for i in 1..900
        script.incProgress()
      end
      script.setProgressStage("brutal", 1000)

  - Funzione: `incProgress`

    Questa funzione incrementa l'avanzamento di un passo.

  - Funzione: `setProgress`

    Questa funzione imposta il valore dell'avanzamento. Prende un argomento: il valore dell'avanzamento.

  - Funzione: `setProgressStage`

    Questa funzione imposta il valore dell'avanzamento e visualizza il testo.

  - Funzione: `setProgressTotalSteps`

    Questa funzione imposta il numero di passi richiesti dallo script. Le serve un argomento: il valore massimo dell'avanzamento.

- Oggetto: `Wavelet`

  Questo oggetto contiene i coefficienti di una trasformazione wavelet di un `PaintLayer`.

  - Funzione: `getDepth`

    Restituisce la profondità del livello.

  - Funzione: `getNCoeff`

    Restituisce il valore dell'ennesimo coefficiente. La funzione prende un argomento: l'indice del coefficiente.

  - Funzione: `getNumCoeffs`

    Restituisce il numero di coefficienti in questo wavelet (= dimensione × dimensione × profondità).

  - Funzione: `getSize`

    Restituisce la dimensione del wavelet (dimensione = larghezza = altezza).

  - Funzione: `getXYCoeff`

    Restituisce il valore di un coefficiente. La funzione prende due argomenti: `x` e `y`.

  - Funzione: `setNCoeff`

    Imposta il valore dell'ennesimo coefficiente. La funzione prende due argomenti: l'indice del coefficiente e il suo nuovo valore.

  - Funzione: `setXYCoeff`

    Imposta il valore di un coefficiente. La funzione prende tre argomenti: `x`, `y` e il nuovo valore del coefficiente.

- Oggetto: `Painter`

  - Funzione: `convolve`

    Questa funzione applica un nucleo di convoluzione a un'immagine. Prende almeno tre argomenti: un elenco di nuclei (tutti gli elenchi devono avere le stesse dimensioni), fattore e scostamento.

    Il valore di un pixel sarà dato dalla funzione seguente: K×P/fattore+scostamento, dove K è il nucleo e P l'intorno.

    Può prendere i seguenti argomenti opzionali: `borderOp` (controlla quanto convolvere i pixel sul bordo di un'immagine: 0 = usa il colore predefinito, 1 = usa il pixel sul lato opposto dell'immagine, 2 = usa il pixel del bordo, 3 = evita i bordi dei pixel). `channel` (1 per colore, 2 per alfa, 3 per entrambi), `x`, `y`, `width`, `height`.

  - Funzione: `setFillThreshold`

    Imposta la soglia di riempimento. Prende un solo argomento: la soglia.

  - Funzione: `fillColor`

    Inizia a riempire con un colore. Prende due argomenti: `x` e `y`.

  - Funzione: `fillPattern`

    Inizia a riempire con un motivo. Prende due argomenti: `x` e `y`.

  - Funzione: `paintPolyline`

    Questa funzione disegnerà una polilinea. Prende due argomenti: un elenco di posizioni x e un elenco di posizioni y.

  - Funzione: `paintLine`

    Questa funzione disegnerà una linea. Prende cinque argomenti: `x1`, `y1`, `x2`, `y2`, e `pressure`.

  - Funzione: `paintBezierCurve`

    Questa funzione disegnerà una curva di Bezier. Prende dieci argomenti: `x1`, `y1`, `p1`, `cx1`, `cy1`, `cx2`, `cx2`, `x2`, `y2`, `p2`, dove (`x1`,`y1`) è la posizione iniziale, `p1` è la pressione all'inizio, (`x2`,`y2`) è la posizione finale, `p2` è la pressione alla fine. (`cx1`,`cy1`) e (`cx2`,`cy2`) sono le posizioni ai punti di controllo.

  - Funzione: `paintEllipse`

    Questa funzione disegnerà un ellisse. Prende cinque argomenti `x1`, `y1`, `x2`, `y2`, `pressure`, dove (`x1`,`y1`) e (`x2`,`y2`) sono le posizioni dei due centri.

  - Funzione: `paintPolygon`

    Questa funzione disegnerà un poligono. Prende due argomenti: un elenco di posizioni x e un elenco di posizioni y.

  - Funzione: `paintRect`

    Questa funzione disegnerà un rettangolo. Prende cinque argomenti: `x`, `y`, `width` `height`, `pressure`.

  - Funzione: `paintAt`

    Questa funzione disegnerà in un certo punto. Prende tre argomenti: `x`, `y`, `pressure`.

  - Funzione: `setPaintColor`

    Questa funzione imposta il colore del tratto (detto anche colore di primo piano). Prende un argomento: un `Color`.

  - Funzione: `setBackgroundColor`

    Questa funzione imposta il colore di sfondo. Prende un argomento: un `Color`.

  - Funzione: `setPattern`

    Questa funzione imposta il motivo usato per lo riempimento. Prende un argomento: un oggetto `Pattern`.

  - Funzione: `setBrush`

    Questa funzione imposta il pennello usato per disegnare. Prende un argomento: un oggetto `Brush`.

  - Funzione: `setPaintOp`

    Questa funzione definisce l'operazione di disegno. Prende un argomento: il nome dell'operazione.

  - Funzione: `setDuplicateOffset`

    Questa funzione definisce lo scostamento del duplicato. Prende due argomenti: lo scostamento orizzontale e quello verticale.

  - Funzione: `setOpacity`

    Questa funzione imposta l'opacità del disegno. Prende un argomento: l'opacità, in un intervallo da 0 a 255.

  - Funzione: `setStrokeStyle`

    Questa funzione imposta lo stile del tratto. Prende un argomento: 0 per nessuno, 1 per pennello.

  - Funzione: `setFillStyle`

    Questa funzione imposta lo stile di riempimento del `Painter`. Prende un argomento: 0 per nessuno, 1 per riempire con il colore di primo piano, 2 per riempire con il colore di sfondo, 3 per riempire con un motivo.

- Oggetto: `Iterator`

  Questo oggetto ti permette di cambiare i valori dei pixel uno alla volta. Il nome di alcune funzioni dipende dallo spazio dei colori; per esempio, se lo spazio dei colori del livello è RGB, avrai `setR`, `setG` e `setB`, e per CMYK: `setC`, `setM`, `setY` e `setK`. Nella documentazione sotto assumeremo che lo spazio viene chiamato ABC, con tre canali: A, B e C.

  - Funzioni: `setA`, `setB`, `setC`

    Queste funzioni prendono un argomento: il nuovo valore di uno dei canali di questo pixel.

  - Funzione: `setABC`

    Imposta il valore di tutti i canali. Questa funzione prende un argomento: un array con i nuovi valori di tutti i canali.

  - Funzioni: `getA`, `getB`, `getC`

    Restituisce il valore di uno dei canali di questo pixel.

  - Funzione: `getABC`

    Restituisce un array con i valori di tutti i canali.

  - Funzione: `darken`

    Scurisci un pixel. Questa funzione prende almeno un argomento: `shade` (quantità usata per scurire tutti i canali dei colori). Questa funzione può prendere il seguente argomento opzionale: `compensation` (per limitare l'oscuramento).

  - Funzione: `invertColor`

    Inverti il colore di un pixel.

  - Funzione: `next`

    Aumenta la posizione, vai al prossimo pixel.

  - Funzione: `isDone`

    Restituisci vero se l'iteratore è alla fine (non ci sono più pixel).

## Risorse

Ecco dei suggerimenti o elenchi parziali di risorse per &chalk;.

Per `Brush` e `Pattern`: puoi avere il nome del pennello o del motivo associato dal selettore nella barra degli strumenti di &chalk;.

Un elenco di identificativi per gli spazi dei colori di &chalk;: LABA, RGBA, RGBA16, RGBAF32, RGBAF16HALF, LMSAF32, GRAYA, GRAYA16, CMYK, CMYKA16.