# Arbeiten mit Skripten

In &chalk; können Sie Skripte in Ruby oder Python schreiben (Welche Sprache Sie verwenden können, hängt davon ab, welche Interpreter auf Ihrem Computer installiert wurden). Hier finden Sie eine Beschreibung der Prgrammierschnittstellen.

Einige Beispiele erhalten Sie zusammen mit &chalk;, Sie finden sie in `/usr/share/apps/chalk/scripts` (oder `/opt/kde/share/apps/chalk/scripts`).

## Variablen im Modul `Krosschalkcore`

- `ChalkDocument` gibt ein `Document`-Objekt zurück

- `ChalkScript` gibt ein `ScriptProgress`-Objekt zurück

Sie können ein Objekt mit der `get`-Funktion des `Krosschalkcore`-Moduls beziehen. In Ruby geht das z. B. so:

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

## Funktionen im Modul `Krosschalkcore`

- Funktion: `getBrush`

  Diese Funktion gibt ein `Brush`-Objekt aus der Liste der &chalk;-Ressourcen zurück. Sie akzeptiert ein Argument: den Namen des Pinsels. Ein Beispiel in Ruby:

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

- Funktion: `getFilter`

  Diese Funktion gibt ein `Filter`-Objekt aus der Liste der &chalk;-Ressourcen zurück. Sie akzeptiert ein Argument: den Namen des Filters. Ein Beispiel in Ruby:

      Krosschalkcore::getFilter("invert")

- Funktion: `getPattern`

  Diese Funktion gibt ein `Pattern`-Objekt aus der Liste der &chalk;-Ressourcen zurück. Sie akzeptiert ein Argument: den Namen des Musters. Ein Beispiel in Ruby:

      Krosschalkcore::getPattern("Bricks")

- Funktion: `loadBrush`

  Diese Funktion lädt ein `Brush`-Objekt und gibt es zurück. Sie akzeptiert ein Argument: den Dateinamen des Pinsels.

- Funktion: `loadPattern`

  Diese Funktion lädt ein `Pattern`-Objekt und gibt es zurück. Sie akzeptiert ein Argument: den Dateinamen des Musters.

- Funktion: `newCircleBrush`

  Diese Funktion gibt ein `Brush`-Objekt in Kreisform zurück. Sie akzeptiert mindestens zwei Argumente: Breite und Höhe. Zusätzlich akzeptiert sie zwei weitere Argumente: Ausblendbreite und Ausblendhöhe. Ist keine Ausblendung angegeben, besitzt der Pinsel keine Ausblendkanten. Ein Beispiel in Ruby:

      Krosschalkcore::newCircleBrush(10,20) # erzeugt einen Kreis
      Krosschalkcore::newCircleBrush(10,20,5,10) # erzeugt einen Verlauf

- Funktion: `newHSVColor`

  Diese Funktion gibt ein `Color`-Objekt in Form eines HSV-Satzes zurück. Sie akzeptiert drei Argumente: Farbton (0 bis 255), Sättigung (0 bis 255), Farbwert (0 bis 255). Ein Beispiel in Ruby:

      Krosschalkcore::newHSVColor(255,125,0)

- Funktion: `newImage`

  Diese Funktion gibt ein `Image`-Objekt zurück. Sie akzeptiert vier Argumente: Breite, Höhe, Farbraum-ID, Name des Bildes. Als Rückgabewert erhalten Sie ein `Image`-Objekt. Ein Beispiel in Ruby:

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

- Funktion: `newRectBrush`

  Diese Funktion gibt ein `Brush`-Objekt rechteckiger Form zurück. Sie akzeptiert mindestens zwei Argumente: Breite und Höhe. Zusätzlich akzeptiert Sie zwei weitere Argumente: Ausblendbreite und Ausblendhöhe. Ist keine Ausblendung angegeben, besitzt der Pinsel keine Ausblendkanten: Ein Beispiel in Ruby:

      Krosschalkcore::newRectBrush(10,20) # erzeugt ein Rechteck
       Krosschalkcore::newRectBrush(10,20,5,10) # erzeugt einen Verlauf

- Funktion: `newRGBColor`

  Diese Funktion gibt ein `Color`-Objekt in Form eines RGB-Satzes zurück. Sie akzeptiert drei Argumente: Rot (0 bis 255), Blau (0 bis 255), Grün (0 bis 255). Ein Beispiel in Ruby:

      Krosschalkcore::newRGBColor(255,0,0) # erzeugt eine rote Farbe
      Krosschalkcore::newRGBColor(255,255,255) # erzeugt eine weiße Farbe

## Beschreibung und Liste verschiedener Funktionen in `Krosschalkcore`

- Objekt: PaintLayer

  - Funktion: `beginPainting`

  - Funktion: `convertToColorspace`

    Wandelt ein Bild in einen Farbraum um. Diese Funktion akzeptiert ein Argument: den Namen des Farbraums. Ein Beispiel in Ruby:

        image.convertToColorspace("CMYK")

  - Funktion: `createHistogram`

    Diese Funktion erzeugt ein Histogramm für diese Ebene. Sie akzeptiert zwei Argumente: den Typ des Histogramms ( ("RGB8HISTO"), und 0 für ein lineares und 1 für ein logarithmisches Histogramm.

  - Funktion: `createHLineIterator`

    Erstellt einen Iterator über die Ebene, der eine Zeile durchläuft. Sie akzeptiert drei Argumente: `x` (Anfangspunkt in der Zeile), `y` (vertikale Position der Zeile), Breite der Zeile.

  - Funktion: `createPainter`

    Diese Funktion erzeugt ein `Painter`-Objekt, mit dem Sie auf einer Ebene zeichnen können.

  - Funktion: `createRectIterator`

    Erzeugt einen Iterator über eine Ebene, der über eine rechteckige Fläche läuft. Diese Funktion akzeptiert vier Argumente: `x`, `y`, Breite des Rechtecks, Höhe des Rechtecks.

  - Funktion: `createVLineIterator`

    Erstellt einen Iterator über eine Ebene, der eine Spalte durchläuft. Diese Funktion akzeptiert drei Argumente: `x` (horizontale Position der Spalte), `y` (Anfangspunkt in der Spalte), Höhe der Spalte.

  - Funktion: `endPainting`

    Diese Funktion schließt den aktuellen Eintrag für die Liste der Rückgängig-Funktion und fügt ihn dem Verlauf hinzu.

  - Funktion: `fastWaveletTransformation`

    Gibt ein Objekt der schnellen Wavelet-Transformation der Ebene zurück.

  - Funktion: `fastWaveletUntransformation`

    Macht eine schnelle Wavelet-Transformation auf dieser Ebene rückgängig. Akzeptiert ein Argument: ein Wavelet-Objekt. Ein Beispiel in Ruby:

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

  - Funktion: `getHeight`

    Gibt die Höhe der Ebene zurück.

  - Funktion: `getWidth`

    Gibt die Breite der Ebene zurück.

- Objekt: `Filter`

  - Funktion: `getFilterConfiguration`

    Diese Funktion gibt ein `FilterConfiguration`-Objekt zurück, das zu diesem Filter gehört.

  - Funktion: `process`

    Diese Funktion wendet den Filter an. Sie akzeptiert mindestens ein Argument: die Quellebene. Sie können zusätzlich diese vier Argumente übergeben: `x`, `y`, `width`, `height`. (`x`,`y`,`width`,`height`) definieren die rechteckige Ebene, auf die der Filter angewandt wird. Ist kein Rechteck definiert, wird der Filter auf die gesamte Quellebene angewandt. Ein Beispiel 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 )

- Objekt: `FilterConfiguration`

  - Funktion: `getProperty`

    Diese Funktion gibt den Wert eines Parameters des zugehörigen `Filter`-Objektes zurück. Sie akzeptiert ein Argument: den Namen des Parameters.

  - Funktion: `setProperty`

    Diese Funktion definiert einen Parameter des zugehörigen `Filter`-Objekts. Sie übernimmt zwei Argumente: den Namen des Parameters und den Wert, dessen Typ vom `Filter`-Objekt abhängt.

- Objekt: `Histogramm`

  Diese Klasse gibt Ihnen Zugriff auf das Histogramm eines `PaintLayer`-Objekts. Ein Beispiel 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

  - Funktion: `getChannel`

    Gibt den ausgewählten Kanal zurück.

  - Funktion: `getCount`

    Diese Funktion gibt die Anzahl der im Histogramm verwendeten Pixel zurück.

  - Funktion: `getHighest`

    Diese Funktion gibt den größten Wert im Histogramm zurück.

  - Funktion: `getLowest`

    Diese Funktion gibt den kleinsten Wert im Histogramm zurück.

  - Funktion: `getMax`

    Diese Funktion gibt die Maximalbegrenzung des Histogramms zurück (Werte über dem Maximum sind Null). Der Wert liegt im Bereich 0.0 – 1.0.

  - Funktion: `getMean`

    Diese Funktion gibt den Mittelwert im Histogramm zurück.

  - Funktion: `getMin`

    Diese Funktion gibt die Minimalbegrenzung des Histogramms zurück (Werte unter dem Minimum sind Null). Der Wert liegt im Bereich 0.0 – 1.0.

  - Funktion: `getNumberOfBins`

    Gibt die Anzahl der Behälter eines Histogramms zurück.

  - Funktion: `getTotal`

    Diese Funktion gibt die Summe aller Werte im Histogramm zurück.

  - Funktion: `getValue`

    Gibt den Wert eines Behälters eines Histogramms zurück. Diese Funktion akzeptiert ein Argument: den Index im Bereich 0..255.

  - Funktion: `setChannel`

    Wählt den Kanal der Ebene, von dem das Ergebnis des Histogramms bezogen wird. Diese Funktion akzeptiert ein Argument: die Kanalnummer.

- Objekt: `ScriptProgress`

  Mit `ScriptProgress` können Sie die Fortschrittsanzeige in der Statusleiste von &chalk; steuern. Ein Beispiel 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)

  - Funktion: `incProgress`

    Diese Funktion erhöht den Wert des Fortschritts um eine Schrittweite.

  - Funktion: `setProgress`

    Diese Funktion stellt den Wert des Fortschritts ein. Sie akzeptiert ein Argument: den Wert des Fortschritts.

  - Funktion: `setProgressStage`

    Diese Funktion stellt den Wert des Fortschritts ein, und zeigt den Text an.

  - Funktion: `setProgressTotalSteps`

    Diese Funktion stellt die Anzahl der Schritte ein, die das Skript benötigt. Sie akzeptiert ein Argument: den Maximalwert des Fortschritts.

- Objekt: `Wavelet`

  Dieses Objekt enthält den Koeffizienten der Wavelet-Transformation eines `PaintLayer`-Objekts.

  - Funktion: `getDepth`

    Gibt die Tiefe einer Ebene zurück.

  - Funktion: `getNCoeff`

    Gibt den Wert des n-ten Koeffizienten zurück. Die Funktion akzeptiert ein Argument: den Index des Koeffizienten.

  - Funktion: `getNumCoeffs`

    Gibt die Anzahl der Koeffizienten dieses Wavelets zurück (= Größe * Größe * Tiefe).

  - Funktion: `getSize`

    Gibt die Größe des Wavelets zurück (= Breite * Höhe).

  - Funktion: `getXYCoeff`

    Gibt den Wert eines Koeffizienten zurück. Diese Funktion akzeptiert zwei Argumente: `x` und `y`.

  - Funktion: `setNCoeff`

    Stellt den Wert des n-ten Koeffizienten ein. Die Funktion akzeptiert zwei Argumente: den Index des Koeffizienten und den neuen Wert den neuen Wert des Koeffizienten.

  - Funktion: `setXYCoeff`

    Stellt den Wert eines Koeffizienten ein. Diese Funktion akzeptiert drei Argumente: `x`, `y`, und den neuen Wert des Koeffizienten.

- Objekt: `Painter`

  - Funktion: `convolve`

    Diese Funktion wendet eine Faltung auf das Bild an. Sie akzeptiert mindestens drei Argumente: eine Liste von Kernen (alle Listen müssen die gleiche Länge haben), den Faktor, und den Versatz.

    Der Wert eines Pixels wird über die folgende Funktion ermittelt: K * P / Faktor + Versatz, wobei K der Kern, und P die direkte Umgebung ist.

    Zusätzlich akzeptiert die Funktion die folgenden Argumente: `borderOp` (bestimmt, wie Pixel am Rand eines Bildes gefaltet werden: 0 = Standardfarbe verwenden, 1 = benutze das Pixel von der gegenüber liegenden Seite des Bildes, 2 = benutze das Rahmenpixel, 3 = vermeide Rahmenpixel), `channel` (1 für Farbe, 2 für Alpha, 3 für beides), `x`, `y`, `width`, `height`.

  - Funktion: `setFillThreshold`

    Stellt den Schwellenwert beim Füllen ein. Akzeptiert ein Argument: den Schwellenwert.

  - Funktion: `fillColor`

    Beginnt mit einer Farbe zu füllen. Akzeptiert zwei Argumente: `x` und `y`.

  - Funktion: `fillPattern`

    Beginnt mit einem Muster zu füllen. Akzeptiert zwei Argumente: `x` und `y`.

  - Funktion: `paintPolyline`

    Diese Funktion zeichnet eine Linienkette. Sie akzeptiert zwei Argumente: eine Liste der x-Koordinaten und eine Liste der y-Koordinaten.

  - Funktion: `paintLine`

    Diese Funktion zeichnet eine Linie. Sie akzeptiert fünf Argumente: `x1`, `y1`, `x2`, `y2`, und `pressure`.

  - Funktion: `paintBezierCurve`

    Diese Funktion zeichnet eine Bézier-Kurve. Sie akzeptiert zehn Argumente: `x1`, `y1`, `p1`, `cx1`, `cy1`, `cx2`, `cx2`, `x2`, `y2`, `p2`, wobei (`x1`,`y1`) die Anfangsposition ist, `p1` der Druck zu Beginn, (`x2`,`y2`) ist die Endposition, `p2` ist der Druck am Ende. (`cx1`,`cy1`) und (`cx2`,`cy2`) sind die Positionen der Kontrollpunkte.

  - Funktion: `paintEllipse`

    Diese Funktion zeichnet eine Ellipse. Sie akzeptiert fünf Argumente: `x1`, `y1`, `x2`, `y2`, `pressure`, wobei (`x1`,`y1`) und (`x2`,`y2`) die Position der beiden Zentren angeben.

  - Funktion: `paintPolygon`

    Diese Funktion zeichnet ein Vieleck. Sie akzeptiert zwei Argumente: eine Liste der x-Koordinaten und eine Liste der y-Koordinaten.

  - Funktion: `paintRect`

    Diese Funktion zeichnet ein Rechteck. Sie akzeptiert fünf Argumente: `x`, `y`, `width`, `height`, `pressure`.

  - Funktion: `paintAt`

    Diese Funktion malt an der gegebenen Position. Sie akzeptiert drei Argumente > `x`, `y`, `pressure`.

  - Funktion: `setPaintColor`

    Diese Funktion stellt die Zeichenfarbe (Vordergrundfarbe) ein. Sie akzeptiert ein Argument: ein `Color`-Objekt.

  - Funktion: `setBackgroundColor`

    Diese Funktion stellt die Hintergrundgrundfarbe ein. Sie akzeptiert ein Argument: ein `Color`-Objekt.

  - Funktion: `setPattern`

    Diese Funktion stellt das Muster für Füllung ein. Sie akzeptiert ein Argument: ein `Pattern`-Objekt.

  - Funktion: `setBrush`

    Diese Funktion stellt den Pinsel zum Zeichnen ein. Sie akzeptiert ein Argument: ein `Brush`-Objekt.

  - Funktion: `setPaintOp`

    Diese Funktion definiert die Malverfahren. Sie akzeptiert ein Argument: den Namen der Malverfahren.

  - Funktion: `setDuplicateOffset`

    Diese Funktion definiert den Versatz beim Duplizieren. Sie akzeptiert zwei Argumente: den waagerechten Versatz und den senkrechten Versatz.

  - Funktion: `setOpacity`

    Diese Funktion stellt die Deckkraft beim Malen ein. Sie akzeptiert ein Argument: die Deckkraft im Bereich von 0 bis 255.

  - Funktion: `setStrokeStyle`

    Diese Funktion stellt den Stil des Strichs ein. Sie akzeptiert ein Argument: 0 für keinen Strich, 1 für einen Pinsel.

  - Funktion: `setFillStyle`

    Diese Funktion stellt den Füllstil des `Painter`-Objekts ein. Sie akzeptiert ein Argument: 0 für keine Füllung, 1 für Füllung mit der Vordergrundfarbe, 2 für Füllung mit der Hintergrundfarbe und 3 für Füllung mit Muster.

- Objekt: `Iterator`

  Dieses Objekt ermöglicht es, Pixelwerte nacheinander zu verändern. Der Name einiger Funktionen hängen von ihrem Farbraum ab. Ist der Farbraum einer Ebene z. B. RGB, stehen `setR`, `setG` und `setB` zur Verfügung. Für CMYK: `setC`, `setM`, `setY` und `setK`. Im weiteren Verlauf gehen wir davon aus, dass der Farbraum "ABC" heißt und die drei Kanäle A, B und C enthält.

  - Funktionen: `setA`, `setB`, `setC`

    Diese Funktionen akzeptieren ein Argument: den neuen Wert für einen der Kanäle des Pixels.

  - Funktion: `setABC`

    Stellt den Wert aller Kanäle ein. Diese Funktion akzeptiert ein Argument: ein Array mit den neuen Werten für alle Kanäle.

  - Funktionen: `getA`, `getB`, `getC`

    Gibt den Wert eines der Kanäle des Pixels zurück.

  - Funktion: `getABC`

    Gibt ein Array mit den Werten aller Kanäle zurück.

  - Funktion: `darken`

    Ein Pixel abdunkeln. Diese Funktion akzeptiert mindestens ein Argument: `shade` (Betrag, um alle Kanäle abzudunkeln). Zusätzlich akzeptiert sie das folgende Argument: `compensation` (um die Abdunklung zu begrenzen).

  - Funktion: `invertColor`

    Invertiert die Farbe eines Pixels.

  - Funktion: `next`

    Positionswert wird inkrementiert und zum nächsten Pixel gesprungen.

  - Funktion: `isDone`

    Gibt "true" zurück, wenn der Iterator am Ende angekommen ist (keine weiteren Pixel vorhanden sind).

## Ressourcen

Hier ein paar Hinweise oder Listen mit Informationen für &chalk;.

Für `Brush` und `Pattern`: Sie finden die Namen und die zugehörigen Pinsel oder Muster in der Auswahlpalette in der Werkzeugleiste in &chalk;.

Eine Liste mit IDs für Farbräume in &chalk;: LABA, RGBA, RGBA16, RGBAF32, RGBAF16HALF, LMSAF32, GRAYA, GRAYA16, CMYK, CMYKA16.