# Skriptid

&chalk; võimaldab kirjutada Ruby või Pythoni skripte (interpretaatorite kättesaadavus sõltub sellest, mida sinu distributsioon või sinu masina administraator on paigaldanud). Alljärgnevalt kirjeldame skriptimise API-t.

Mõned näited on &chalk;ga kaasa pandud, need leiab kataloogist `/usr/share/apps/chalk/scripts` (või `/opt/kde/share/apps/chalk/scripts`).

## Mooduli `Krosschalkcore` muutujad

- `ChalkDocument` tagastab `Document`-objekti

- `ChalkScript` tagastab `ScriptProgress`-objekti

Objekti saab hankida mooduli `Krosschalkcore` funktsiooni `get` kasutades, milleks Ruby korral tuleb kirjutada midagi sellist:

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

## Mooduli `Krosschalkcore` funktsioonid

- Funktsioon: `getBrush`

  See funktsioon tagastab klassi `Brush`, mis võetakse &chalk; ressursside loendist. Kasutada saab üht argumenti: pintsli nimi. Näide (Ruby):

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

- Funktsioon: `getFilter`

  See funktsioon tagastab klassi `Filter`, mis võetakse &chalk; ressursside loendist. Kasutada saab üht argumenti: filtri nimi. Näide (Ruby):

      Krosschalkcore::getFilter("invert")

- Funktsioon: `getPattern`

  See funktsioon tagastab klassi `Pattern`, mis võetakse &chalk; ressursside loendist. Kasutada saab üht argumenti: mustri nimi. Näide (Ruby):

      Krosschalkcore::getPattern("Bricks")

- Funktsioon: `loadBrush`

  See funktsioon laadib klassi `Brush` ja tagastab siis selle. Kasutada saab üht argumenti: pintsli failinimi.

- Funktsioon: `loadPattern`

  See funktsioon laadib klassi `Pattern` ja tagastab siis selle. Kasutada saab üht argumenti: mustri failinimi.

- Funktsioon: `newCircleBrush`

  See funktsioon tagastab klassi `Brush` ringikujulisena. Kasutada tuleb vähemalt kaht argumenti: laius ja kõrgus. Kasutada saab veel kaht argumenti: varju laius ja varju kõrgus. Kui varju pole määratud, seda ei kasutata. Näide (Ruby):

      Krosschalkcore::newCircleBrush(10,20) # loob puhta ringi
      Krosschalkcore::newCircleBrush(10,20,5,10) # loob ülemineku

- Funktsioon: `newHSVColor`

  See funktsioon tagastab uue klassi `Color` määratud HSV-tripletiga. Kasutada saab kolme argumenti: toon (0 kuni 255), küllastus (0 kuni 255), väärtus (0 kuni 255). Näide (Ruby):

      Krosschalkcore::newHSVColor(255,125,0)

- Funktsioon: `newImage`

  See funktsioon tagastab uue klassi `Image`. Kasutada saab nelja argumenti: laius, kõrgus, värviruumi ID, pildi nimi. Tagastatakse `Image`-objekt. Näide (Ruby):

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

- Funktsioon: `newRectBrush`

  See funktsioon tagastab klassi `Brush` ristkülikukujulisena. Kasutada tuleb vähemalt kaht argumenti: laius ja kõrgus. Kasutada saab veel kaht argumenti: varju laius ja varju kõrgus. Kui varju pole määratud, seda ei kasutata. Näide (Ruby):

      Krosschalkcore::newRectBrush(10,20) # loob puhta ristküliku
       Krosschalkcore::newRectBrush(10,20,5,10) # loob ülemineku

- Funktsioon: `newRGBColor`

  See funktsioon tagastab uue klassi `Color` määratud RGB-tripletiga. Kasutada saab kolme argumenti: punane (0 kuni 255), sinine (0 kuni 255), roheline (0 kuni 255). Näide (Ruby):

      Krosschalkcore::newRGBColor(255,0,0) # loob punase värvi
      Krosschalkcore::newRGBColor(255,255,255) # loob valge värvi

## `Krosschalkcore` objektide kirjeldused ja funktsioonide loendid

- Objekt: PaintLayer

  - Funktsioon: `beginPainting`

  - Funktsioon: `convertToColorspace`

    Teisendab pildi värviruumi. See funktsioon kasutab üht argumenti: sihtvärviruumi nimi. Näide (Ruby):

        image.convertToColorspace("CMYK")

  - Funktsioon: `createHistogram`

    See funktsioon loob antud kihi histogrammi. Kasutada saab kaht argumenti: histogrammi tüüp ("RGB8HISTO") ja 0, kui histogramm on lineaarne, või 1, kui histogramm on logaritmiline.

  - Funktsioon: `createHLineIterator`

    Loob iteraatori üle kihi, itereerib reas. Funktsioon kasutab kolme argumenti: `x` (algus reas), `y` (rea vertikaalne positsioon), rea laius.

  - Funktsioon: `createPainter`

    See funktsioon loob klassi `Painter`, mis võimaldab kihil joonistada.

  - Funktsioon: `createRectIterator`

    Loob iteraatori üle kihi, itereerib ristkülikulises piirkonnas. Funktsioon kasutab nelja argumenti: `x`, `y`, ristküliku laius, ristküliku kõrgus.

  - Funktsioon: `createVLineIterator`

    Loob iteraatori üle kihi, itereerib veerus. Funktsioon kasutab kolme argumenti: `x` (veeru horisontaalne positsioon), `y` (algus veerus), veeru kõrgus.

  - Funktsioon: `endPainting`

    Selle funktsiooniga saab sulgeda aktiivse tagasivõtmise kirje ja lisada selle ajalukku.

  - Funktsioon: `fastWaveletTransformation`

    Tagastab kihist teisendatud kiirlainiku.

  - Funktsioon: `fastWaveletUntransformation`

    Teisendab kiirlainiku tagasi kihti. Kasutada saab üht argumenti: lainikuobjekt. Näide (Ruby):

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

  - Funktsioon: `getHeight`

    Tagastab kihi kõrguse.

  - Funktsioon: `getWidth`

    Tagastab kihi laiuse.

- Objekt: `Filter`

  - Funktsioon: `getFilterConfiguration`

    Tagastab antud filtriga seotud klassi `FilterConfiguration`.

  - Funktsioon: `process`

    See funktsioon rakendab filtri. Kasutada tuleb vähemalt üht argumenti: lähtekiht. Kasutada saab veel nelja argumenti: `x`, `y`, `width`, `height`. (`x`,`y`,`width`,`height`) määravad ristkülikulise ala, millele filter rakendatakse. Kui ristkülik pole määratud, rakendatakse filter tervele lähtekihile. Näide (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 )

- Objekt: `FilterConfiguration`

  - Funktsioon: `getProperty`

    See funktsioon tagastab seonduva klassi `Filter` parameetri väärtuse. Kasutada saab üht argumenti: parameetri nimi.

  - Funktsioon: `setProperty`

    See funktsioon defineerib seonduva klassi `Filter` parameetri. Kasutada saab kaht argumenti: parameetri nimi ja väärtus, mille tüüp sõltub klassist `Filter`.

- Objekt: `Histogram`

  See klass võimaldab ligipääsu klassi `PaintLayer` histogrammile. Näide (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

  - Funktsioon: `getChannel`

    Tagastab valitud kanali.

  - Funktsioon: `getCount`

    See funktsioon kasutab histogrammi kasutatud pikslite arvu.

  - Funktsioon: `getHighest`

    See funktsioon tagastab histogrammi suurima väärtuse.

  - Funktsioon: `getLowest`

    See funktsioon tagastab histogrammi väikseima väärtuse.

  - Funktsioon: `getMax`

    See funktsioon tagastab histogrammi maksimaalse raja (väärtused maksimumist suuremas positsioonis on null). Väärtus on vahemikus 0,0 – 1,0.

  - Funktsioon: `getMean`

    See funktsioon tagastab histogrammi keskmise.

  - Funktsioon: `getMin`

    See funktsioon tagastab histogrammi minimaalse raja (väärtused miinimumist väiksemas positsioonis on null). Väärtus on vahemikus 0,0 – 1,0.

  - Funktsioon: `getNumberOfBins`

    Tagastab kastide arvu histogrammis.

  - Funktsioon: `getTotal`

    See funktsioon tagastab histogrammi kõigi väärtuste summa.

  - Funktsioon: `getValue`

    Tagastab histogrammi kasti väärtuse. See funktsioon kasutab üht argumenti: indeks vahemikus 0 kuni 255.

  - Funktsioon: `setChannel`

    Valib kihi kanali, mille kohta hankida histogrammi tulemus. See funktsioon kasutab üht argumenti: kanali number.

- Objekt: `ScriptProgress`

  `ScriptProgress`'i kasutatakse &chalk; olekuriba edenemisriba haldamiseks. Näide (Ruby):

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

  - Funktsioon: `incProgress`

    See funktsioon kasvatab edenemist ühe sammu võrra.

  - Funktsioon: `setProgress`

    See funktsioon määrab edenemise väärtuse. See kasutab üht argumenti: edenemise väärtus.

  - Funktsioon: `setProgressStage`

    See funktsioon määrab edenemise väärtuse ja näitab teksti.

  - Funktsioon: `setProgressTotalSteps`

    See funktsioon määrab sammude arvu, mida skript nõuab. See kasutab üht argumenti: edenemise maksimumväärtus.

- Objekt: `Wavelet`

  See objekt sisaldab klassi `PaintLayer` lainikteisenduse koefitsiente.

  - Funktsioon: `getDepth`

    Tagastab kihi sügavuse.

  - Funktsioon: `getNCoeff`

    Tagastab N-nda koefitsiendi väärtuse. Funktsioon kasutab üht argumenti: koefitsiendi indeks,

  - Funktsioon: `getNumCoeffs`

    Tagastab koefitsientide arvu antud lainikus (= suurus * suurus * sügavus).

  - Funktsioon: `getSize`

    Tagastab lainiku suuruse (suurus = laius = kõrgus).

  - Funktsioon: `getXYCoeff`

    Tagastab koefitsiendi väärtuse. Funktsioon kasutab kaht argumenti: `x` ja `y`.

  - Funktsioon: `setNCoeff`

    Määrab N-nda koefitsiendi väärtuse. Funktsioon kasutab kaht argumenti: koefitsiendi indeks ja koefitsiendi uus väärtus.

  - Funktsioon: `setXYCoeff`

    Määrab koefitsiendi väärtuse. Funktsioon kasutab kolme argumenti: `x`, `y` ja koefitsiendi uus väärtus.

- Objekt: `Painter`

  - Funktsioon: `convolve`

    See funktsioon rakendab pildile konvolutsioonituuma. Kasutada tuleb vähemalt kolme argumenti: loend tuuma loenditega (kõik loendid peavad olema ühesuguse suurusega), tegur ja nihe.

    Piksli väärtus määratakse järgmise funktsiooniga: K * P / tegur + nihe, kus K on tuum ja P naabruskond.

    Kasutada võib järgmisi lisaargumente: `borderOp` (määrab, kuidas konvolveerida piksleid pildi piiril: 0 = kasutatakse vaikevärvi, 1 = kasutatakse pildi vastaskülje pikslit, 2 = kasutatakse piiri pikslit, 3 = välditakse piiri piksleid), `channel` (1 tähendab värvi, 2 alfat, 3 mõlemat), `x`, `y`, `width`, `height`.

  - Funktsioon: `setFillThreshold`

    Määrab täitmise läve. Kasutada saab üht argument: lävi.

  - Funktsioon: `fillColor`

    Alustab täitmist värviga. Kasutada saab kaht argumenti: `x` ja `y`.

  - Funktsioon: `fillPattern`

    Alustab täitmist mustriga. Kasutada saab kaht argumenti: `x` ja `y`.

  - Funktsioon: `paintPolyline`

    See funktsioon joonistab kompleksjoone. Kasutada saab kaht argumenti: X-positsioonide loend ja Y-positsioonide loend.

  - Funktsioon: `paintLine`

    See funktsioon joonistab sirge. Kasutada saab viit argumenti: `x1`, `y1`, `x2`, `y2` ja `pressure` (surve).

  - Funktsioon: `paintBezierCurve`

    See funktsioon joonistab Bezier' kõvera. Kasutada saab kümmet argumenti: `x1`, `y1`, `p1`, `cx1`, `cy1`, `cx2`, `cx2`, `x2`, `y2`, `p2`, kus (`x1`,`y1`) on alguspositsioon, `p1` surve alguses, (`x2`,`y2`) lõpp-positsioon, `p2` surve lõpus. (`cx1`,`cy1`) ja (`cx2`,`cy2`) on kontrollpunktide positsioonid.

  - Funktsioon: `paintEllipse`

    See funktsioon joonistab ellipsi. Kasutada saab viit argumenti: `x1`, `y1`, `x2`, `y2`, `pressure`, kus (`x1`,`y1`) ja (`x2`,`y2`) on fookuste positsioonid.

  - Funktsioon: `paintPolygon`

    See funktsioon joonistab hulknurga. Kasutada saab kaht argumenti: X-positsioonide loend ja Y-positsioonide loend.

  - Funktsioon: `paintRect`

    See funktsioon joonistab ristküliku. Kasutada saab viit argumenti: `x`, `y`, `width` (laius), `height` (kõrgus), `pressure` (surve).

  - Funktsioon: `paintAt`

    See funktsioon joonistab määratud positsioonis. Kasutada saab kolme argumenti: `x`, `y`, `pressure` (surve).

  - Funktsioon: `setPaintColor`

    See funktsioon määrab joonistamise värvi (nimetatakse ka esiplaani värviks). Kasutada saab üht argumenti: `Color` (värv).

  - Funktsioon: `setBackgroundColor`

    See funktsioon määrab taustavärvi. Kasutada saab üht argumenti: `Color` (värv).

  - Funktsioon: `setPattern`

    See funktsioon määrab täitmisel kasutatava mustri. Kasutada saab üht argumenti: `Pattern`-objekt.

  - Funktsioon: `setBrush`

    See funktsioon määrab joonistamisel kasutatava pintsli. Kasutada saab üht argumenti: `Brush`-objekt.

  - Funktsioon: `setPaintOp`

    See funktsioon määratleb joonistamisoperatsiooni. Kasutada saab üht argumenti: joonistamisoperatsiooni nimi.

  - Funktsioon: `setDuplicateOffset`

    See funktsioon määrab klooni nihke. Kasutada saab kaht argumenti: horisontaalne nihe ja vertikaalne nihe.

  - Funktsioon: `setOpacity`

    See funktsioon määrab joonistamise läbipaistmatuse. Kasutada saab üht argumenti: läbipaistmatus vahemikus 0 kuni 255.

  - Funktsioon: `setStrokeStyle`

    see funktsioon määrab joone stiili. Kasutada saab üht argumenti: 0 tähendab puudumist ja 1 pintslit.

  - Funktsioon: `setFillStyle`

    See funktsioon määrab klassi `Painter` täitmise stiili. Kasutada saab üht argumenti: 0 tähendab puudumist, 1 täitmist esiplaani värviga, 2 täitmist taustavärviga, 3 täitmist mustriga.

- Objekt: `Iterator`

  See objekt võimaldab muuta piksliväärtusi ükshaaval. Osade funktsioonide nimi sõltub värviruumist: kui näiteks kihi värviruumiks on RGB, siis on funktsioonideks `setR`, `setG` ja `setB`, kui aga CMYK, siis `setC`, `setM`, `setY` ja `setK`. Alljärgnevas dokumentatsioonis eeldame, et värviruumi nimi on ABC, millel on kolm kanalit: A, B ja C.

  - Funktsioonid: `setA`, `setB`, `setC`

    Need funktsioonid kasutavad üht argumenti: antud piksli ühe kanali uus väärtus.

  - Funktsioon: `setABC`

    Määrab kõigi kanalite väärtuse. Funktsioon kasutab üht argumenti: massiiv kõigi kanalite uute väärtustega.

  - Funktsioonid: `getA`, `getB`, `getC`

    Tagastab piksli ühe kanali väärtuse.

  - Funktsioon: `getABC`

    Tagastab massiivi kõigi kanalite väärtustega.

  - Funktsioon: `darken`

    Tumendab pikslit. See funktsioon kasutab vähemalt üht argumenti: `shade` (kogus, mille võrra kõiki värvikanaleid tumendatakse). Funktsioon võib kasutada veel üht lisaargumenti: `compensation` (piirab tumendamist).

  - Funktsioon: `invertColor`

    Inverteerib piksli värvi.

  - Funktsioon: `next`

    Kasvatab positsiooni, liigub järgmisele pikslile.

  - Funktsioon: `isDone`

    Tagastab 'tõene', kui iteraator asub lõpus (rohkem piksleid enam pole).

## Ressursid

Toome siin mõningad vihjed ja &chalk; ressursside osalise loendi:

Klassid `Brush` ja `Pattern`: nime ja seonduva pintsli või mustri leiab &chalk; tööriistariba valijast.

&chalk; 1.5 värviruumide ID-de loend: LABA, RGBA, RGBA16, RGBAF32, RGBAF16HALF, LMSAF32, GRAYA, GRAYA16, CMYK, CMYKA16.