# Scripting

In &krita;, you can write scripts in Ruby or Python (the availability of the interpreters might depend on what your distributions or the administrator of your machine did install). Here you will find a description of the scripting API.

Some examples are distributed with &krita;, and you might find them in `/usr/share/apps/krita/scripts` (or `/opt/kde/share/apps/krita/scripts`).

## Variables in the `Krosskritacore` module

- `KritaDocument` returns a `Document` object

- `KritaScript` returns a `ScriptProgress` object

You can retrieve an object using the `get` function of the `Krosskritacore` module, in Ruby you will have to write something like that:

    doc = Krosskritacore::get("KritaDocument")
    script = Krosskritacore::get("KritaScript")

## Functions in the `Krosskritacore` module

- Function: `getBrush`

  This function returns a `Brush` taken from the list of &krita; resources. It takes one argument: the name of the brush. For example (in Ruby):

      Krosskritacore::getBrush("Circle (05)")

- Function: `getFilter`

  This function returns a `Filter` taken from the list of &krita; resources. It takes one argument: the name of the filter. For example (in Ruby):

      Krosskritacore::getFilter("invert")

- Function: `getPattern`

  This function returns a `Pattern` taken from the list of &krita; resources. It takes one argument: the name of the pattern. For example (in Ruby):

      Krosskritacore::getPattern("Bricks")

- Function: `loadBrush`

  This function loads a `Brush` and then returns it. It takes one argument: the filename of the brush.

- Function: `loadPattern`

  This function loads a `Pattern` and then returns it. It takes one argument: the filename of the pattern.

- Function: `newCircleBrush`

  This function returns a `Brush` with a circular shape. It takes at least two arguments: width and height. It can take two other arguments: width of the shading, and height of the shading. If the shading is not specified, no shading will be used. For example (in Ruby):

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

- Function: `newHSVColor`

  This function returns a new `Color` with the given HSV triplet. It takes three arguments: hue component (0 to 255), saturation component (0 to 255), value component (0 to 255). For example (in Ruby):

      Krosskritacore::newHSVColor(255,125,0)

- Function: `newImage`

  This function returns a new `Image`. It takes four arguments: width, height, colorspace id, name of the image. And in return you get an `Image` object. For example (in Ruby):

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

- Function: `newRectBrush`

  This function returns a `Brush` with a rectangular shape. It takes at least two arguments: width and height. It can take two other arguments: width of the shading and height of the shading. If the shading is not specified, no shading will be used. For example (in Ruby):

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

- Function: `newRGBColor`

  This function returns a new `Color` with the given RGB triplet. It takes three arguments: red component (0 to 255), blue component (0 to 255), green component (0 to 255). For example (in Ruby):

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

## Descriptions and function lists for various objects in `Krosskritacore`

- Object: PaintLayer

  - Function: `beginPainting`

  - Function: `convertToColorspace`

    Convert the image to a colorspace. This function takes one argument: the name of the destination colorspace. For example (in Ruby):

        image.convertToColorspace("CMYK")

  - Function: `createHistogram`

    This function creates a Histogram for this layer. It takes two arguments: the type of the histogram ("RGB8HISTO"), and 0 if the histogram is linear, or 1 if it is logarithmic.

  - Function: `createHLineIterator`

    Create an iterator over a layer, it will iterate on a row. This function takes three arguments: `x` (start in the row), `y` (vertical position of the row), width of the row.

  - Function: `createPainter`

    This function creates a `Painter` which will allow you to paint on the layer.

  - Function: `createRectIterator`

    Create an iterator over a layer, it will iterate on a rectangular area. This function takes four arguments: `x`, `y`, width of the rectangle, height of the rectangle.

  - Function: `createVLineIterator`

    Create an iterator over a layer, it will iterate on a column. This function takes three arguments: `x` (horizontal position of the column), `y` (start in the column), height of the column.

  - Function: `endPainting`

    This function closes the current undo entry and adds it to the history.

  - Function: `fastWaveletTransformation`

    Returns the fast wavelet transformation of the layer.

  - Function: `fastWaveletUntransformation`

    Untransforms a fast wavelet into this layer. It takes one argument: a wavelet object. For example (in Ruby):

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

  - Function: `getHeight`

    Return the height of the layer.

  - Function: `getWidth`

    Return the width of the layer.

- Object: `Filter`

  - Function: `getFilterConfiguration`

    This function returns the `FilterConfiguration` associated with this filter.

  - Function: `process`

    This function will apply the filter. It takes at least one argument: the source layer. You can also use these four aguments: `x`, `y`, `width`, `height`. (`x`,`y`,`width`,`height`) defines the rectangular area on which the filter will be computed. If the rectangle is not defined, then the filter will be applied on the entire source layer. For example (in Ruby)

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

- Object: `FilterConfiguration`

  - Function: `getProperty`

    This function returns the value of a parameter of the associated `Filter`. It takes one argument: the name of the parameter.

  - Function: `setProperty`

    This function defines a parameter of the associated `Filter`. It takes two arguments: the name of the parameter and the value, whose type depends on the `Filter`.

- Object: `Histogram`

  This class allows you to access the histogram of a `PaintLayer`. Example (in Ruby):

       doc = krosskritacore::get("KritaDocument")
       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

  - Function: `getChannel`

    Return the selected channel.

  - Function: `getCount`

    This function returns the number of pixels used by the histogram.

  - Function: `getHighest`

    This function returns the highest value of the histogram.

  - Function: `getLowest`

    This function returns the lowest value of the histogram.

  - Function: `getMax`

    This function returns the maximum bound of the histogram (values at greater position than the maximum are null). The value is in the range 0.0 – 1.0.

  - Function: `getMean`

    This function returns the mean of the histogram.

  - Function: `getMin`

    This function returns the minimum bound of the histogram (values at smaller position than the minimum are null). The value is in the range 0.0 – 1.0.

  - Function: `getNumberOfBins`

    Return the number of bins of this histogram.

  - Function: `getTotal`

    This function returns the sum of all values of the histogram.

  - Function: `getValue`

    Return the value of a bin of the histogram. This function takes one argument: index, in the range [0..255].

  - Function: `setChannel`

    Select the channel of the layer on which to get the result of the histogram. This function takes one argument: the channel number.

- Object: `ScriptProgress`

  `ScriptProgress` is used to manage the progress bar of the status bar in &krita;. For example (in Ruby):

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

  - Function: `incProgress`

    This function increments the progress by one step.

  - Function: `setProgress`

    This function sets the value of the progress. It takes one argument: the value of the progress.

  - Function: `setProgressStage`

    This function sets the value of the progress and displays the text.

  - Function: `setProgressTotalSteps`

    This function set the number of steps that the script will require. It takes one argument: the maximum value of the progress

- Object: `Wavelet`

  This object holds the coefficients of a wavelet transformation of a `PaintLayer`.

  - Function: `getDepth`

    Returns the depth of the layer.

  - Function: `getNCoeff`

    Returns the value of the Nth coefficient. The function takes one argument: the index of the coefficient.

  - Function: `getNumCoeffs`

    Returns the number of coefficients in this wavelet (= size * size * depth).

  - Function: `getSize`

    Returns the size of the wavelet (size = width = height).

  - Function: `getXYCoeff`

    Returns the value of a coefficient. The function takes two arguments: `x` and `y`.

  - Function: `setNCoeff`

    Set the value of the Nth coefficient. The function takes two arguments: the index of the coefficient and the new value of the coefficient.

  - Function: `setXYCoeff`

    Set the value of a coefficient. The function takes three arguments: `x`, `y`, and the new value of the coefficient.

- Object: `Painter`

  - Function: `convolve`

    This function applies a convolution kernel to an image. It takes at least three arguments: a list of kernels (all lists need to have the same size), factor, and offset.

    The value of a pixel will be given by the following function: K * P / factor + offset, where K is the kernel and P is the neighbourhood.

    It can take the following optional arguments: `borderOp` (control how to convolve the pixels on the border of an image: 0 = use the default color, 1 = use the pixel on the opposite side of the image, 2 = use the border pixel, 3 = avoid border pixels), `channel` (1 for color, 2 for alpha, 3 for both), `x`, `y`, `width`, `height`.

  - Function: `setFillThreshold`

    Sets the fill threshold. It takes one argument: the threshold.

  - Function: `fillColor`

    Starts filling with a color. It takes two arguments: `x` and `y`.

  - Function: `fillPattern`

    Starts filling with a pattern. It takes two arguments: `x` and `y`.

  - Function: `paintPolyline`

    This function will paint a polyline. It takes two arguments: a list of x positions, and a list of y positions.

  - Function: `paintLine`

    This function will paint a line. It takes five arguments: `x1`, `y1`, `x2`, `y2`, and `pressure`.

  - Function: `paintBezierCurve`

    This function will paint a Bezier curve. It takes ten arguments: `x1`, `y1`, `p1`, `cx1`, `cy1`, `cx2`, `cx2`, `x2`, `y2`, `p2`, where (`x1`,`y1`) is the start position, `p1` is the pressure at the start, (`x2`,`y2`) is the end position, `p2` is the pressure at the end. (`cx1`,`cy1`) and (`cx2`,`cy2`) are the positions of the control points.

  - Function: `paintEllipse`

    This function will paint an ellipse. It takes five arguments: `x1`, `y1`, `x2`, `y2`, `pressure`, where (`x1`,`y1`) and (`x2`,`y2`) are the positions of the two centers.

  - Function: `paintPolygon`

    This function will paint a polygon. It takes two arguments: a list of x positions and a list of y positions.

  - Function: `paintRect`

    This function will paint a rectangle. It takes five arguments: `x`, `y`, `width` `height`, `pressure`.

  - Function: `paintAt`

    This function will paint at a given position. It takes three arguments: `x`, `y`, `pressure`.

  - Function: `setPaintColor`

    This function sets the paint color (also called foreground color). It takes one argument: a `Color`.

  - Function: `setBackgroundColor`

    This function sets the background color. It takes one argument: a `Color`.

  - Function: `setPattern`

    This function sets the pattern used for filling. It takes one argument: a `Pattern` object.

  - Function: `setBrush`

    This function sets the brush used for painting. It takes one argument: a `Brush` object.

  - Function: `setPaintOp`

    This function defines the paint operation. It takes one argument: the name of the paint operation.

  - Function: `setDuplicateOffset`

    This function defines the duplicate offset. It takes two arguments: the horizontal offset and the vertical offset.

  - Function: `setOpacity`

    This function set the opacity of the painting. It takes one argument: the opacity, in the range 0 to 255.

  - Function: `setStrokeStyle`

    This function sets the style of the stroke. It takes one argument: 0 for none, or 1 for brush.

  - Function: `setFillStyle`

    This function sets the fill style of the `Painter`. It takes one argument: 0 for none, 1 for fill with foreground color, 2 for fill with background color, 3 for fill with pattern.

- Object: `Iterator`

  This object allows you to change pixel values one by one. The name of some functions depends on the colorspace, for instance, if the colorspace of the layer is RGB, you will have `setR`, `setG` and `setB`, and for CMYK: `setC`, `setM`, `setY` and `setK`. In the documentation below we will assume that the colorspace is called ABC, with three channels: A, B and C.

  - Functions: `setA`, `setB`, `setC`

    Those functions take one argument: the new value of one of the channels of this pixel.

  - Function: `setABC`

    Set the value of all channels. This function takes one argument: an array with the new values for all channels.

  - Functions: `getA`, `getB`, `getC`

    Return the value of one of the channels of this pixel.

  - Function: `getABC`

    Return an array with the values of all channels.

  - Function: `darken`

    Darken a pixel. This function takes at least one argument: `shade` (amount used to darken all color channels). This function can take the following optional argument: `compensation` (to limit the darkening).

  - Function: `invertColor`

    Invert the color of a pixel.

  - Function: `next`

    Increment the position, go to the next pixel.

  - Function: `isDone`

    Return true if the iterator is at the end (no more pixels are available).

## Resources

Here are hints or partial lists of resources for &krita;.

For `Brush` and `Pattern`: You can get the name and the associated brush or pattern from the selector in &krita;'s toolbar.

A list of ids for colorspaces in &krita;: LABA, RGBA, RGBA16, RGBAF32, RGBAF16HALF, LMSAF32, GRAYA, GRAYA16, CMYK, CMYKA16.