# Met scripts werken

In &chalk; kunt u scripts in Ruby of Python schrijven (de beschikbaarheid van de interpreters kan afhankelijk zijn van wat uw distributie of de systeembeheerder geïnstalleerd heeft.). Hier vindt u een beschrijving ven de scripting-API.

Bij &chalk; worden enkele voorbeelden meegeleverd, u kunt ze waarschijnlijk vinden in `/usr/share/apps/chalk/scripts` (of `/opt/kde/share/apps/chalk/scripts`).

## Variabelen in de `Krosschalkcore`-module

- `ChalkDocument` geeft een `Document`-object terug

- `ChalkScript` geeft een `ScriptProgress`-object terug

U kunt een object ophalen door de functie `get` van de `Krosschalkcore`-module te gebruiken, in Ruby moet u iets als dit gebruiken:

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

## Functies in de `Krosschalkcore`-module

- Functie: `getBrush`

  Deze functie geeft een a `Brush` terug uit de bronnenlijst van &chalk; Er moet één argument meegegeven worden: de naam van het penseel. Bijvoorbeeld (in Ruby):

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

- Functie: `getFilter`

  Deze functie geeft een `Filter` terug uit de bronnenlijst van &chalk;. Er moet één argument meegegeven worden: de naam van het filter. Bijvoorbeeld (in Ruby):

      Krosschalkcore::getFilter("invert")

- Functie: `getPattern`

  Deze functie geeft een `Pattern` terug uit de bronnenlijst van &chalk;. Er moet één argument meegegeven worden: de naam van het patroon. Bijvoorbeeld (in Ruby):

      Krosschalkcore::getPattern("Bricks")

- Functie: `loadBrush`

  Deze functie laadt een `Brush` en geeft het vervolgens terug. Er moet één argument meegegeven worden: de bestandsnaam van het penseel.

- Functie: `loadPattern`

  Deze functie laadt een `Pattern` en geeft het vervolgens terug. Er kan één argument meegegeven worden: de bestandsnaam van het patroon.

- Functie: `newCircleBrush`

  Deze functie geeft een `Brush` met een ronde vorm terug. Er moeten ten minste twee argumenten meegegeven worden: breedte en hoogte. Er kunnen twee andere argumenten meegegeven worden: breedte van de schaduw en hoogte van de schaduw. Als de schaduw niet gespecificeerd is, wordt deze niet gebruikt. Bijvoorbeeld (in Ruby):

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

- Functie: `newHSVColor`

  Deze functie geeft een nieuwe `Color` met het gegeven HSV-triplet terug. Er moeten drie argumenten meegegeven worden: hue-component (0 tot 255), saturation-component (0 tot 255) en value-component (0 tot 255). Bijvoorbeeld (in Ruby):

      Krosschalkcore::newHSVColor(255,125,0)

- Functie: `newImage`

  Deze functie geeft een nieuwe `Image` terug. Er moeten vier argumenten meegegeven worden: breedte, hoogte, kleurruimte-id, naam van de afbeelding. Er wordt een `Image`-object teruggegeven. Bijvoorbeeld (in Ruby):

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

- Functie: `newRectBrush`

  Deze functie geeft een `Brush` met een rechthoekige vorm terug. Er moeten ten minste twee argumenten meegegeven worden: breedte en hoogte. Er kunnen twee andere argumenten meegegeven worden: breedte van de schaduw en hoogte van de schaduw. Als de schaduw niet gespecificeerd is, wordt deze niet gebruikt. Bijvoorbeeld (in Ruby):

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

- Functie: `newRGBColor`

  Deze functie geeft een nieuwe `Color` met het gegeven RGB-triplet terug. Er moeten drie argumenten meegegeven worden: red-component (0 tot 255), blue-component (0 tot 255), green-component (0 tot 255). Bijvoorbeeld (in Ruby):

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

## Beschrijvingen en functielijsten voor diverse objecten in `Krosschalkcore`

- Object: PaintLayer

  - Functie: `beginPainting`

  - Functie: `convertToColorspace`

    Converteert de afbeelding naar een kleurruimte. Er moet één argument aan deze functie meegegeven worden: de naam van de doelkleurruimte. Bijvoorbeeld (in Ruby):

        image.convertToColorspace("CMYK")

  - Functie: `createHistogram`

    Deze functie creëert een histogram voor deze laag. Er moeten twee argumenten meegegeven worden: het type van het histogram ("RGB8HISTO"), en 0 voor een lineair histogram, of 1 voor een logaritmisch histogram.

  - Functie: `createHLineIterator`

    Creëert een iterator over een laag, de iteratie gebeurt in een rij. Er moeten drie argumenten aan deze functie meegegeven worden: `x` (begin in de rij), `y` (verticale positie van de rij), breedte van de rij.

  - Functie: `createPainter`

    Deze functie creëert een `Painter` waardoor u op de laag kunt tekenen.

  - Functie: `createRectIterator`

    Creëert een iterator over een laag, de iteratie gebeurt in een rechthoekig gebied. Er moeten vier argumenten aan deze functie meegegeven worden: `x`, `y`, breedte van de rechthoek, hoogte van de rechthoek.

  - Functie: `createVLineIterator`

    Creëert een iterator over een laag, de iteratie gebeurt in een kolom. Er moeten drie argumenten aan deze functie meegegeven worden: `x` (horizontale positie van de kolom), `y` (begin in de kolom), hoogte van de kolom.

  - Functie: `endPainting`

    Deze functie sluit het huidige ongedaan-maken-item en voegt het aan de geschiedenis toe.

  - Functie: `fastWaveletTransformation`

    Geeft de "fast wavelet transformed" van de laag terug.

  - Functie: `fastWaveletUntransformation`

    Maakt de "fast wavelet"-transformatie op deze laag ongedaan. Er moet één argument meegegeven worden: een wavelet-object. Bijvoorbeeld (in Ruby):

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

  - Functie: `getHeight`

    Geeft de hoogte van de laag terug.

  - Functie: `getWidth`

    Geeft de breedte van de laag terug.

- Object: `Filter`

  - Functie: `getFilterConfiguration`

    Deze functie geeft de `FilterConfiguration` die bij deze filter hoort terug.

  - Functie: `process`

    Deze functie past de filter toe. Er moet ten minste één argument meegegeven worden: de bronlaag. Er kunnen nog vier andere argumenten meegegeven worden: `x`, `y`, `width`, `height`. (`x`, `y`, `width`, `height`) definieert het rechthoekige gebied waarop de filter berekend wordt. Als de rechthoek niet gedefinieerd is, wordt de filter op de gehele laag toegepast. Bijvoorbeeld (in 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 )

- Object: `FilterConfiguration`

  - Functie: `getProperty`

    Deze functie geeft de waarde van een parameter van de bijbehorende `Filter` terug. Er moet één argument meegegeven worden: de naam van de parameter.

  - Functie: `setProperty`

    Deze functie definieert een parameter van de bijbehorende `Filter`. Er moeten twee argumenten meegegeven worden: de naam van de parameter en de waarde, het type hiervan is afhankelijk van de `Filter`.

- Object: `Histogram`

  Met behulp van deze class krijgt u toegang tot het histogram van een `PaintLayer`. Bijvoorbeeld (in 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

  - Functie: `getChannel`

    Geeft het geselecteerde kanaal terug.

  - Functie: `getCount`

    Deze functie geeft het aantal pixels dat door het histogram gebruikt wordt terug.

  - Functie: `getHighest`

    Deze functie geeft de hoogste waarde van het histogram terug.

  - Functie: `getLowest`

    Deze functie geeft de laagste waarde van het histogram terug.

  - Functie: `getMax`

    Deze functie geeft de maximumgrens van het histogram (waarden op een positie die hoger is dan het maximum zijn null). De waarde ligt in het bereik 0.0 – 1.0.

  - Functie: `getMean`

    Deze functie geeft het midden van het histogram.

  - Functie: `getMin`

    Deze functie geeft de minimumgrens van het histogram (waarden op posities die lager zijn dan het minimum zijn null). De waarde ligt in het bereik 0.0 – 1.0.

  - Functie: `getNumberOfBins`

    Geeft het aantal bins van het histogram terug.

  - Functie: `getTotal`

    Deze functie geeft de som van alle waarden van het histogram.

  - Functie: `getValue`

    Geeft de waarde van een bin van het histogram terug. Er moet één argument meegegeven worden: index, in het bereik [0..255].

  - Functie: `setChannel`

    Selecteer het kanaal van de laag waarvan het resultaat van het histogram verkregen moet worden. Er moet één argument meegegeven worden: het kanaalnummer.

- Object: `ScriptProgress`

  `ScriptProgress` wordt gebruikt op de voortgangsindicator op de statusbalk in status bar in &chalk; te besturen. Bijvoorbeeld (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)

  - Functie: `incProgress`

    Deze functie verhoogt de voortgang met één stap.

  - Functie: `setProgress`

    Deze functie stelt de waarde van de voortgang in. er moet één argument meegegeven worden: de waarde van de voortgang.

  - Functie: `setProgressStage`

    Deze functie stelt de waarde van de voortgang in en toont de tekst.

  - Functie: `setProgressTotalSteps`

    Deze functie stelt het aantal stappen in dat het script vereist. Er moet één argument meegegeven worden: de maximumwaarde van de voortgang.

- Object: `Wavelet`

  Dit object bevat de coëfficiënten van een wavelet transformatie van een `PaintLayer`.

  - Functie: `getDepth`

    Geeft de diepte van een laag terug.

  - Functie: `getNCoeff`

    Geeft de waarde van de N-de coëfficiënt terug. Er moet één argument aan de functie meegegeven worden: de index van de coëfficiënt.

  - Functie: `getNumCoeffs`

    Geeft het aantal coëfficiënten in deze wavelet (= size * size * depth).

  - Functie: `getSize`

    Geeft de grootte van de wavelet terug (size = width = height).

  - Functie: `getXYCoeff`

    Geeeft de waarde van een coëfficiënt terug. Er moeten twee argumenten aan de functie meegegeven worden: `x` en `y`.

  - Functie: `setNCoeff`

    Stelt de waarde van de N-de coëfficiënt in. Er moeten twee argumenten aan de functie meegegeven worden: de index van de coëfficiënt en de nieuwe waarde van de coëfficiënt.

  - Functie: `setXYCoeff`

    Stelt de waarde in van een coëfficiënt. Er moeten drie argumenten aan de functie meegegeven worden: `x`, `y`, en de nieuwe waarde van de coëfficiënt.

- Object: `Painter`

  - Functie: `convolve`

    Deze functie past een convolutie "kernel" op een afbeelding toe. Er moeten ten minste drie argumenten meegegeven worden: een lijst van een lijst met de "kernel" (alle lijsten moeten even groot zijn), factor, en offset.

    De waarde van een pixel wordt gegeven door de volgende functie: K * P / factor + offset, waar K de kernel is en P de buurpixels zijn.

    De volgende optionele argumenten kunnen meegegeven worden: `borderOp` (bepaalt de convolutue van de pixels aan de rand van een afbeelding: 0 = gebruik de standaardkleur, 1 = gebruik de pixel aan de tegenovergestelde kant van de afbeelding, 2 = gebruik de randpixel, 3 = vermijd randpixels), `channel` (1 voor kleur, 2 voor alpha, 3 voor beide), `x`, `y`, `width`, `height`.

  - Functie: `setFillThreshold`

    Stelt de vuldrempel in. Er moet één argument meegegeven worden: de drempel.

  - Functie: `fillColor`

    Vult met een kleur. Er moeten twee argumenten meegegeven worden: `x` en `y`.

  - Functie: `fillPattern`

    Vult met een patroon. Er moeten twee argumenten meegegeven worden: `x` en `y`.

  - Functie: `paintPolyline`

    Deze functie teken een gebroken lijn. Er moeten twee argumenten meegegeven worden: een lijst met x-posities en een lijst met y-posities.

  - Functie: `paintLine`

    Deze functie tekent een lijn. Er moeten vijf argumenten meegegeven worden: `x1`, `y1`, `x2`, `y2` en `pressure`.

  - Functie: `paintBezierCurve`

    Deze functie tekent een Bezier-curve. Er moeten tien argumenten meegegeven worden: `x1`, `y1`, `p1`, `cx1`, `cy1`, `cx2`, `cx2`, `x2`, `y2`, `p2`, waar (`x1`,`y1`) de beginpositie is, `p1` de druk aan het begin is, (`x2`,`y2`) de eindpositie is, `p2` de druk aan het einde is. (`cx1`,`cy1`) en (`cx2`,`cy2`) zijn de posities van de controlepunten.

  - Functie: `paintEllipse`

    Deze functie tekent een ellips. Er moeten vijf argumenten meegegeven worden: `x1`, `y1`, `x2`, `y2`, `pressure`, waar (`x1`,`y1`) en (`x2`,`y2`) de posities van de twee middelpunten zijn.

  - Functie: `paintPolygon`

    Deze functie tekent een veelhoek. Er moeten twee argumenten meegegeven worden: een lijst met x-posities en een lijst met y-posities.

  - Functie: `paintRect`

    Deze functie tekent een rechthoek. Er moeten vijf argumenten meegegeven worden: `x`, `y`, `width` `height`, `pressure`.

  - Functie: `paintAt`

    Deze functie tekent op een opgegeven positie. Er moeten drie argumenten meegegeven worden: `x`, `y`, `pressure`.

  - Functie: `setPaintColor`

    Deze functie stelt de tekenkleur in (ook voorgrondkleur genoemd). Er moet één argument meegegeven worden: een `Color`.

  - Functie: `setBackgroundColor`

    Deze functie stelt de achtergrondkleur in. Er moet één argument meegegeven worden: een `Color`.

  - Functie: `setPattern`

    Deze functie stelt het patroon in dat voor het vullen gebruikt wordt. Er moet één argument meegegeven worden: een `Pattern`-object.

  - Functie: `setBrush`

    Deze functie stelt het penseel in dat voor het tekenen gebruikt wordt. Er moet één argument meegegeven worden: een `Brush`-object.

  - Functie: `setPaintOp`

    Deze functie definieert tekenactie. Er moet één argument meegegeven worden: de naam van de tekenactie.

  - Functie: `setDuplicateOffset`

    Deze functie definieert de duplicaat-offset. Er moeten twee argumenten meegegeven worden: de horizontale offset en de verticale offset.

  - Functie: `setOpacity`

    Deze functie stelt de dekking voor het tekenen in. Er moet één argument meegegeven worden: de dekking, in het bereik 0 tot 255.

  - Functie: `setStrokeStyle`

    Deze functie stelt de stijl in van de penseelstreek. Er moet één argument meegegeven worden: 0 voor geen of 1 voor penseel.

  - Functie: `setFillStyle`

    Deze functie stelt de vulstijl in van de `Painter`. Er moet één argument meegegeven worden: 0 voor geen, 1 voor vullen met voorgrondkleur, 2 voor vullen met achtergrondkleur, 3 voor vullen met patroon.

- Object: `Iterator`

  Met dit object kunt u pixelwaarden één voor één veranderen. De naam van enkele functies is afhankelijk van de kleurruimte, als de kleurruimte van de laag bijvoorbeeld RGB is, zijn de functies `setR`, `setG` en `setB`, voor CMYK: `setC`, `setM`, `setY` en `setK`. In de documentatie hieronder nemen we aan dat de naam van de kleurruimte ABC is, met drie kanalen: A, B en C.

  - Functies: `setA`, `setB`, `setC`

    Er moet één argument aan deze functies meegegeven worden: de nieuwe waarde van één van de kanalen van deze pixel.

  - Functie: `setABC`

    Stelt de waarde in van alle kanalen. Er moet één argument meegegeven worden: een array met de nieuwe waarden voor alle kanalen.

  - Functies: `getA`, `getB`, `getC`

    Geeft de waarde van één van de kanalen van deze pixel terug.

  - Functie: `getABC`

    Geeft een array terug met de waarden van alle kanalen.

  - Functie: `darken`

    Maakt een pixel donkerder. Er moet ten minste één argument aan deze functie meegegeven worden: `shade` (hoeveelheid die gebruikt wordt om alle kleurkanalen donkerder te maken). Het volgende optionele argument kan meegegeven worden: `compensation` (om het donkerder maken te limiteren).

  - Functie: `invertColor`

    Inverteert de kleur van een pixel.

  - Functie: `next`

    Verhoog de positie, ga naar de volgende pixel.

  - Functie: `isDone`

    Geeft true terug als de iterator het einde bereikt heeft (er zijn geen pixels meer beschikbaar).

## Bronnen

Hier zijn enkele tips en een bronnenlijst voor &chalk;.

Voor `Brush` en `Pattern`: U kunt de naam en het bijbehorende penseel of patroon vinden in het betreffende paletvenster in &chalk;.

Een lijst met ID's voor kleurruimten in &chalk; 1.5: LABA, RGBA, RGBA16, RGBAF32, RGBAF16HALF, LMSAF32, GRAYA, GRAYA16, CMYK, CMYKA16.