# Programació amb scripts

En el &chalk;, podeu escriure scripts en Ruby o Python (la disponibilitat dels intèrprets pot dependre d'on els ha instal·lat el vostre administrador o la vostra distribució a la màquina). Aquí trobareu una descripció de l'scripting API.

Alguns exemples es distribueixen amb el &chalk;, i els haurieu de trobar a `/usr/share/apps/chalk/scripts` (o `/opt/kde/share/apps/chalk/scripts`).

## Variables en el mòdul `Krosschalkcore`

- `ChalkDocument` retorna un objecte `Document`

- `ChalkScript` retorna un objecte `ScriptProgress`

Podeu obtenir un objecte usant la funció `get` del mòdul `Krosschalkcore`. En Ruby haureu d'escriure alguna cosa com aquesta:

    doc = Krosschalkcore::get("ChalkDocument")
    script = Krosschalkcore::get("ChalkScript")

## Funcions en el mòdul `Krosschalkcore`

- Funció: `getBrush`

  Aquesta funció retorna un `Brush` agafat de la llista de recursos del &chalk;. Agafa un argument: el nom del pinzell. Per exemple (en Ruby):

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

- Funció: `getFilter`

  Aquesta funció retorna un `Filter` agafat de la llista de recursos del &chalk;. Agafa un argument: el nom del filtre. Per exemple (en Ruby):

      Krosschalkcore::getFilter("invert")

- Funció: `getPattern`

  Aquesta funció retorna un `Pattern` agafat de la llista de recursos del &chalk;. Agafa un argument: el nom del patró. Per exemple (en Ruby):

      Krosschalkcore::getPattern("Bricks")

- Funció: `loadBrush`

  Aquesta funció carrega un `Brush` agafat de la llista de recursos del &chalk;. Agafa un argument: el nom del pinzell.

- Funció: `loadPattern`

  Aquesta funció carrega un `Pattern` i llavors el retorna. Agafa un argument: el nom de fitxer del patró.

- Funció: `newCircleBrush`

  Aquesta funció retorna un `Brush` amb forma circular. Agafa almenys dos arguments: ample i alçada. Pot agafar-ne dos més: amplada i alçada de l'ombra. Si no està especificada l'ombra, no s'usarà cap ombra. Per exemple (en Ruby):

      Krosschalkcore::newCircleBrush(10,20) # create a plain circle
      Krosschalkcore::newCircleBrush(10,20,5,10) # create a gradient

- Function: `newHSVColor`

  Aquesta funció retorna un nou `Color` amb la tripleta HSV donada. Agafa tres arguments: component de matís (0 a 255), component de saturació (0 a 255), component de valor (0 a 255). Per exemple (en Ruby):

      Krosschalkcore::newHSVColor(255,125,0)

- Funció: `newImage`

  Aquesta funció retorna una nova `Image`. Agafa quatre arguments: amplada, alçada, identificació de l'espai de color, nom de la imatge. I de retorn obteniu un objecte `Image`. Per exemple (en Ruby):

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

- Funció: `newRectBrush`

  Aquesta funció retorna un `Brush` amb forma rectangular. Agafa almenys dos arguments: ample i alçada. Pot agafar-ne dos més: amplada i alçada de l'ombra. Si no està especificada l'ombra, no s'usarà cap ombra. Per exemple (en Ruby):

      Krosschalkcore::newRectBrush(10,20) # create a plain rectangle
       Krosschalkcore::newRectBrush(10,20,5,10) # create a gradient

- Funció: `newRGBColor`

  Aquesta funció retorna un nou `Color` amb la tripleta RGB donada. Agafa tres arguments: component de vermell (0 a 255), component de blau (0 a 255), component de verd (0 a 255). Per exemple (en Ruby):

      Krosschalkcore::newRGBColor(255,0,0) # create a red color
      Krosschalkcore::newRGBColor(255,255,255) # create a white color

## Descripcions i llistes de funció per a diversos objectes en `Krosschalkcore`

- Objecte: PaintLayer

  - Funció: `beginPainting`

  - Funció: `convertToColorspace`

    Converteix la imatge a un espai de color. Aquesta funció agafa un argument: el nom de l'espai de color de destí. Per exemple (en Ruby):

        image.convertToColorspace("CMYK")

  - Funció: `createHistogram`

    Aquesta funció crea un Histograma per a aquesta capa. Agafa dos arguments: el tipus d'histograma ("RGB8HISTO"), i 0 si l'histograma és liniar, o 1 si és logarítmic.

  - Funció: `createHLineIterator`

    Crea un iterator sobre una capa, interactuarà en una fila. Aquesta funció agafa tres arguments: `x` (comença a la fila), `y` (posició vertical de la fila), amplada de la fila.

  - Funció: `createPainter`

    Aquesta funció crea un `Painter` que us permetrà de dibuixar a la capa.

  - Funció: `createRectIterator`

    Crea un iterator sobre una capa, iteractuarà sobre un àrea rectangular. Aquesta funció agafa quatre arguments: `x`, `y`, amplada del rectangle, alçada del rectangle.

  - Funció: `createVLineIterator`

    Crea in iterator sobre una capa, interactuarà sobre una columna. Aquesta funció agafa tres arguments: `x` (posició horitzontal de la columna), `y` (inici de la columna), alçada de la columna.

  - Funció: `endPainting`

    Aquesta funció tanca l'entrada actual de desfés i l'afegeix a l'historial.

  - Funció: `fastWaveletTransformation`

    Retorna la transformació ràpida d'ona de la capa.

  - Funció: `fastWaveletUntransformation`

    Destransforma una ona ràpida a la seva capa. Agafa un argument: un objecte d'ona. Per exemple (en Ruby):

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

  - Funció: `getHeight`

    Retorna l'alçada de la capa.

  - Funció: `getWidth`

    Retorna l'amplada de la capa.

- Objecte: `Filter`

  - Funció: `getFilterConfiguration`

    Aquesta funció retorna el `FilterConfiguration` associat amb aquest filtre.

  - Funció: `process`

    Aquesta funció aplicarà el filtre. Agafa almenys un argument: la capa font. També podeu usar aquests quatre aguments: `x`, `y`, `amplada`, `alçada`. (`x`,`y`,`amplada`,`alçada`) defineix l'àrea rectangular sobre la qual es computarà el filtre. Si el rectangle no està definit, llavors el filtre s'aplicarà sobre tota la capa font. Per exemple (en Ruby):

        doc = Krosschalkcore::get("ChalkDocument")
        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 )

- Objecte: `FilterConfiguration`

  - Funció: `getProperty`

    Aquesta funció retorna el valor d'un paràmetre del `Filter` associat. Agafa un argument: el nom del paràmetre.

  - Funció: `setProperty`

    Aquesta funció defineix un paràmetre del `Filter` associat. Agafa dos arguments: el nom del paràmetre i el valor, el tipus del qual depén del `Filter`.

- Objecte: `Histogram`

  Aquesta classe us permet d'accedir l'histogram d'un `PaintLayer`. Exemple (en Ruby):

      doc = krosschalkcore::get("ChalkDocument")
       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

  - Funció: `getChannel`

    Retorna el canal seleccionat.

  - Funció: `getCount`

    Aquesta funció retorna el número de píxels usats per l'histograma.

  - Funció: `getHighest`

    Aquesta funció retorna el valor més alt de l'histograma.

  - Funció: `getLowest`

    Aquesta funció retorna el valor més baix de l'histograma.

  - Funció: `getMax`

    Aquesta funció retorna el límit màxim de l'histograma (els valors de posició més gran que el màxim són nuls). El valor és en el rang entre 0.0 i 1.0.

  - Funció: `getMean`

    Aquesta funció retorna la mitjana de l'histograma.

  - Funció: `getMin`

    Aquesta funció retorna el límit mínim de l'histograma (els valors de posició més petits que el mínim són nuls). El valor és en el rang entre 0.0 i 1.0.

  - Funció: `getNumberOfBins`

    Retorna el número de bins de l'histograma.

  - Funció: `getTotal`

    Aquesta funció retorna la suma de tots els valors de l'histograma.

  - Funció: `getValue`

    Retorna el valor d'un bin de l'histograma. Aquesta funció agafa un argumnet: l'índex, en el rang [0..255].

  - Funció: `setChannel`

    Selecciona el canal de la cap on posar el resultat de l'histograma. Aquesta funció agafa un argument: el número de canal.

- Objecte: `ScriptProgress`

  `ScriptProgress` s'usa per a gestionar la barra de progrés de la barra d'estatus en el &chalk;. Per exemple (en Ruby):

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

  - Funció: `incProgress`

    Aquesta funció incrementa el progrés en un pas.

  - Funció: `setProgress`

    Aquesta funció arranja el valor del progrés. Agafa un argument: el valor del progrés.

  - Funció: `setProgressStage`

    Aquesta funció arranja el valor del progrés i mostra el text.

  - Funció: `setProgressTotalSteps`

    Aquesta funció arranja el número de passes que requerirà l'script. Agafa un argument: el valor màxim del progrés.

- Objecte: `Wavelet`

  Aquest objecte conté els coeficients d'una transformació d'ona d'una `PaintLayer`.

  - Funció: `getDepth`

    Retorna la profunditat de la capa.

  - Funció: `getNCoeff`

    Retorna el valor de l'enèssim coeficient. Aquesta funció agafa un argument: l'índex del coeficient.

  - Funció: `getNumCoeffs`

    Retorna el número de coeficients en aquesta ona (= size * size * depth).

  - Funció: `getSize`

    Retorna la mida de l'ona (size = width = height).

  - Funció: `getXYCoeff`

    Retorna el valor d'un coeficient. Aquesta funció agafa dos arguments: `x` i `y`.

  - Funció: `setNCoeff`

    Arranja el valor de l'enèssim coeficient. Aquesta finció agafa dos arguments: l'índex del coeficient i el nou valor del coeficient.

  - Funció: `setXYCoeff`

    Arranja el valor d'un coeficient. La funció agafa tres arguments: `x`, `y`, i el nou valor del coeficient.

- Objecte: `Painter`

  - Funció: `convolve`

    Aquesta funció aplica un nucli de convulsió a una imatge. Agafa almenys tres arguments: una llista de nuclis (totes les llistes han de tenir la mateixa mida), el factor i la compensació.

    El valor dun píxel vindrà donat per la següent funció: K * P / factor + compensació, on K és el nucli i P és el veïnat.

    Pot agafar els següents arguments opcionals: `borderOp` (control·la com convolucionar els píxels a la vora d'una imatge: 0 = usa el color per omissió, 1 = usa el píxel de la part oposada de la imatge, 2 = usa el píxel de la vora, 3 = evita els píxels de la vora), `channel` (1 per al color, 2 per alfa, 3 per ambdós), `x`, `y`, `ample`, `alçada`.

  - Funció: `setFillThreshold`

    Arranja el llindar ple. Agafa un argument: el llindar.

  - Funció: `fillColor`

    Comença a omplir amb un color. Agafa dos arguments: `x` i `y`.

  - Funció: `fillPattern`

    Comença a omplir un patró. Agafa dos arguments: `x` i `y`.

  - Funció: `paintPolyline`

    Aquesta funció dibuixarà una polilínia. Agafa dos arguments: una llista de posicions x i una llista de posicions y.

  - Funció: `paintLine`

    Aquesta funció dibuixarà una línia. Agafa cinc arguments: `x1`, `y1`, `x2`, `y2`, i `pressure`.

  - Funció: `paintBezierCurve`

    Aquesta funció dibuixarà una corba de Bezier. Agafa deu arguments: `x1`, `y1`, `p1`, `cx1`, `cy1`, `cx2`, `cx2`, `x2`, `y2`, `p2`, on (`x1`,`y1`) és la posició d'inici, `p1` és la pressió a l'inici, (`x2`,`y2`) és la posició final, `p2` és la pressió al final. (`cx1`,`cy1`) i (`cx2`,`cy2`) són les posicions dels punts de control.

  - Funció: `paintEllipse`

    Aquesta funció dibuixarà una el·lipsi. Agafa cinc arguments: `x1`, `y1`, `x2`, `y2`, `pressure`, on (`x1`,`y1`) i (`x2`,`y2`) són les posicions dels dos centres.

  - Funció: `paintPolygon`

    Aquesta funció dibuixarà un polígon. Agafa dos arguments: una llista de posicions x i una llista de posicions y.

  - Funció: `paintRect`

    Aquesta funció dibuixarà un rectangle. Agafa cinc arguments: `x`, `y`, `ample` `alçada` i `pressió`.

  - Funció: `paintAt`

    Aquesta funció dibuixarà en una posició donada. Agafa tres arguments: `x`, `y`, `pressió`.

  - Funció: `setPaintColor`

    Aquesta funció arrajna el color de dibuix (també anomenat color de primer pla). Agafa un argument: un `Color`.

  - Funció: `setBackgroundColor`

    Aquesta funció arranja el color de fons. Agafa un argument: un `Color`.

  - Funció: `setPattern`

    Aquesta funció arranja el patró usat per a l'ompliment. Agafa un argument: un objecte de `Pattern`.

  - Funció: `setBrush`

    Aquesta funció arranja el pinzell a usar en un dibuix. Agafa un argument: un objecte de `Brush`.

  - Funció: `setPaintOp`

    Aquesta funció defineix l'operació de dibuix. Agafa un argument: el nom de l'operació de dibuix.

  - Funció: `setDuplicateOffset`

    Aquesta funció defineix la compensació duplicada. Agafa dos arguments: la compensació horitzontal i la compensació vertical.

  - Funció: `setOpacity`

    Aquesta funció arranja l'opacitat del dibuix. Agafa un argument: l'opacitat, en el rang de 0 a 255.

  - Funció: `setStrokeStyle`

    Aquesta funció arranja l'estil del traç. Agafa un argument: 0 per a cap, o 1 per a pinzell.

  - Funció: `setFillStyle`

    Aquesta funció arranja l'estil d'ompliment del `Painter`. Agaf un argument: 0 per a cap, 1 per a ompliment amb el color de primer pla, 2 per a ompliment amb el color de fons, 3 per a ompliment amb un patró.

- Objecte: `Iterator`

  Aquest objecte us permet de canviar valors de píxel un per un. El nom d'algunes funcions depén de l'espai de color, per exemple, si l'espai de color de la capa és RGB, tindreu `setR`, `setG` i `setB`, i per a CMYK: `setC`, `setM`, `setY` i `setK`. A la documentació de sota assumirem que l'espai de color es diu ABC, amb tres canals: A, B i C.

  - Funcions: `setA`, `setB`, `setC`

    Aquestes funcions agafen un argument: el nou valor d'un dels canals d'aquest píxel.

  - Funció: `setABC`

    Arranja el valor de tots els canals. Aquesta funció agafa un argument: una matriu amb els nous valors per a tots els canals.

  - Funcions: `getA`, `getB`, `getC`

    Retornen el valor d'un dels canals d'aquest píxel.

  - Funció: `getABC`

    Retorna una matriu amb els valors de tots els canals.

  - Funció: `darken`

    Obscureix un píxel. Aquesta funció agafa almenys un argument: `shade` (quantitat usada per aobscurir tots els canals de color). Aquesta funció pot agafar el següent argument opcional: `compensation` (per a limitar l'obscuriment).

  - Funció: `invertColor`

    Inverteix el color d'un píxel.

  - Funció: `next`

    Incrementa la posició, va al següent píxel.

  - Funció: `isDone`

    Retorna vertader si l'iterator està al final (no hi ha més píxels disponibles).

## Recursos

Aquí hi ha pistes o llistes parcials de recursos per al &chalk;.

Per a `Brush` i `Pattern`: podeu obtenir el nom i el pinzell o patró associat des del selector de la barra d'eines del &chalk;.

Una llista d'identificadors per a espais de color en el &chalk;: LABA, RGBA, RGBA16, RGBAF32, RGBAF16HALF, LMSAF32, GRAYA, GRAYA16, CMYK, CMYKA16.