Krita Scripting

Pages
1. index
Objects

index

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.

Handbook

Krita offers a complete handbook which includes detailed informations about the scripting API, examples and more.

http://www.koffice.org/krita

http://docs.kde.org/development/en/koffice/krita/

Objects

The Scripting::Module is the Krita scripting module which provides access to the scripting functionality.

Examples

Some examples are distributed with Krita, and you might find them in /usr/share/apps/krita/scripts (or /opt/kde/share/apps/krita/scripts depending on your used distribution).

Also you are able to get or even provide your own new scripts online at

http://www.kde-files.org/index.php?xcontentmode=616

Objects

Scripting::Brush

A brush object.

Scripting::Color

The color class represents a single color.

Scripting::ConstIterator

Scripting::ConstIteratorBase

This object allow to read the value of pixel one by one.

bool next() [slot]

Increment the position, and go to the next pixel. The returned value is true if the iterator reached the end (so, it's like calling next() and after that asking what isDone() returns).
bool isDone() [slot]

Return true if the iterator is at the end, what means, that there are no more pixels available.
int x() [slot]

Return the current column the iterator is on. The value will be always smaller then the width of the image/layer.
int y() [slot]

Return the current row the iterator is on. The value will be always smaller then the height of the image/layer.
QVariant channel(uint channelnr) [slot]

Return the value the current pixel has in the channel number channelnr . If the channelnr is out of range (as in >= what channelCount() returns) a invalid QVariant is returned.
uint channelCount() [slot]

Return the number of channels the current pixmap has. As example for RGBA-images 4 is returned cause R is one channel, while G, B and A are other channels what makes 4 total.
QVariantList pixel() [slot]

Return the current pixel. The pixel itself may have depending on the used colorspace n colors where each color has it's own channel. So, as example if the colorspace is RGBA, the returned list has exact 4 items. The first one is a value 0-255 for the color red, the second for green and the theird for blue while the forth is the alpha-channel.
void invalidateIterator() [slot]

Scripting::ConstPaintDevice

A PaintDevice is a layer within a Image where you are able to perform paint-operations on.

int width() [slot]

Return the width of the layer.
int height() [slot]

Return the height of the layer.
QString colorSpaceId() [slot]

Return the id of the colorspace of this image (e.g. "RGBA" or "CMYK").
QObject createRectConstIterator(uint x, uint y, uint width, uint height) [slot]

Create an iterator over a layer, it will iterate on a rectangle area. This function takes four arguments :
x
y
width of the rectangle
height of the rectangle
QObject createHLineConstIterator(uint x, uint y, uint width) [slot]

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
QObject createVLineConstIterator(uint x, uint y, uint height) [slot]

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
QObject createHistogram(QString histoname, uint typenr) [slot]

This function creates an Histogram for this layer. It takes two arguments :
the type of the histogram ("RGB8HISTO")
0 if the histogram is linear, or 1 if it is logarithmic
QObject fastWaveletTransformation() [slot]

Return the fast Wavelet transformed of the layer.
QObject clone() [slot]

clone this paint layer, making a deep copy.

Scripting::Filter

This class enables access to the filters Krita provides.

For example (in Ruby)

 require "Krita"

 # fetch the image.
 image = Krita.image()

 # we like to operate on the active painting layer.
 layer = image.activePaintLayer()

 # get the height and the width the layer has.
 width = layer.width()
 height = layer.height()

 # we like to use the progressbar
 progress = Krita.progress()
 progress.setProgressTotalSteps( (width / 20) * (height / 20) )

 # apply the invert filter each 20x20 pixels at a 10x10 rect.
 invertfilter = Krita.filter("invert")
 0.step(width - 10, 20) do |x|
     0.step(height - 10, 20) do |y|
         invertfilter.process(layer, x, y, x + 10, y + 10)
         progress.incProgress()
     end
 end

QString name() [slot]

Return the unique name the filter has.

QVariant property(QString name) [slot]

This function return the value of a parameter of the associated Filter. The properties define the filters-configuration and you are able to use property and setProperty to manipulate them.
It takes one argument :
the name of the parameter It returns the properties value.
void setProperty(QString name, QVariant value) [slot]

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

QVariantMap properties() [slot]

This function returns all properties the filter has as name=value dictonary.
For example (in Python)
 require "Krita"
 filter = Krita.filter("invert")
 for propname in filter.properties().keys():
     propvalue = filter.property(propname)
     filter.setProperty(propname, propvalue)

void fromXML(QString xml) [slot]

Deserialize the filter-configuration from XML.
QString toXML() [slot]

Serialize filter-configuration to XML.
bool process(QObject layer) [slot]
This function will apply the filter. It takes one argument :
the source layer

For example (in Ruby)
```
 require "Krita"
 layer = Krita.image().activePaintLayer()
 filter = Krita.filter("invert")
 filter.process(layer)
```
bool process(QObject layer, int x, int y, int width, int height) [slot]
This function will apply the filter. It takes five argument :
the source layer
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 apply on alll the source layer.
For example (in Ruby)
```
 require "Krita"
 layer = Krita.image().activePaintLayer()
 filter = Krita.filter("invert")
 filter.process(layer, 10, 10, 20, 20)
```

Scripting::Histogram

This class allow to access the histogram of a PaintDevice object.

Example (in Ruby) :

 require "Krita"
 image = Krita.image()
 layer = image.activePaintDevice()
 histo = layer.createHistogram("RGB8HISTO",0)
 min = histo.min() * 255
 max = histo.max() * 255
 for i in min..max
     print layer.getValue(i), "\n"
 end

uint channel() [slot]

Return the selected channel.
void setChannel(uint channelnr) [slot]

Select the channel of the layer on which to get the result of the histogram. This function takes one argument :
channel number
double max() [slot]

This function return 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.
double min() [slot]

This function return 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.
uint highest() [slot]

This function return the highest value of the histogram.
uint lowest() [slot]

This function return the lowest value of the histogram.
double mean() [slot]

This function return the mean of the histogram.
uint count() [slot]

This function return the number of pixels used by the histogram.
double total() [slot]

This function return the sum of all values of the histogram.
uint value(int index) [slot]

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

Return the number of bins of this histogram.

Scripting::Image

An image object.

int width() [slot]

Return the width of the image.

int height() [slot]

Return the height of the image.

QString colorSpaceId() [slot]

Return the id of the colorspace of this image (e.g. "RGBA" or "CMYK").

bool convertToColorspace(QString colorspacename) [slot]

Convert the image to a colorspace. This function takes one argument :
the name of the destination colorspace This function returns true if convert to the colorspace was successfully else (e.g. if the colorspace is not available, please check your installation in that case) false is returned.

For example (in Ruby) :
 # set the colorspace to "CMYK"
 image.convertToColorspace("CMYK")
 # following line will print "CMYK" now.
 image.colorSpaceId()

void resize(int width, int height, int x, int y) [slot]

Resize the image. This function takes four arguments :
the new width of the image.
the new height of the image.
x-position (if you don't need this, set it to 0).
y-position (if you don't need this, set it to 0).

void scale(double widthfactor, double heightfactor) [slot]

Scale an image. This function takes two arguments :
the width scalefactor.
the height scalefactor.

void rotate(double angle) [slot]

Rotate the image. This function takes one argument :
the angle.

void shear(double xangle, double yangle) [slot]

Shear the image. This function takes two arguments :
the X-angle.
the Y-angle.

QObject createPaintLayer(QString name, int opacity) [slot]

Create a new PaintLayer for this image, and return it. This function takes two arguments :
the name of the layer
the opacity of the layer (between 0 and 255) The new PaintLayer will have the same colorspace as the image. Use the method bellow to define the colorspace.
QObject createPaintLayer(QString name, int opacity, QString colorspacename) [slot]

Create a new PaintLayer for this image, and return it. This function takes three arguments :
the name of the layer
the opacity of the layer (between 0 and 255)
the id of the colorSpace

Scripting::Iterator

Scripting::IteratorBase

This object allow to change the value of pixel one by one.

bool next() [slot]

Increment the position, and go to the next pixel. The returned value is true if the iterator reached the end (so, it's like calling next() and after that asking what isDone() returns).
bool isDone() [slot]

Return true if the iterator is at the end, what means, that there are no more pixels available.
int x() [slot]

Return the current column the iterator is on. The value will be always smaller then the width of the image/layer.
int y() [slot]

Return the current row the iterator is on. The value will be always smaller then the height of the image/layer.
QVariant channel(uint channelnr) [slot]

Return the value the current pixel has in the channel number channelnr . If the channelnr is out of range (as in >= what channelCount() returns) a invalid QVariant is returned.
void setChannel(uint channelnr, QVariant value) [slot]

Set the value the current pixel has in the channel number channelnr.
uint channelCount() [slot]

Return the number of channels the current pixmap has. As example for RGBA-images 4 is returned cause R is one channel, while G, B and A are other channels what makes 4 total.
QVariantList pixel() [slot]

Return the current pixel. The pixel itself may have depending on the used colorspace n colors where each color has it's own channel. So, as example if the colorspace is RGBA, the returned list has exact 4 items. The first one is a value 0-255 for the color red, the second for green and the theird for blue while the forth is the alpha-channel.
void setPixel(QVariantList pixel) [slot]

Set the current pixel.
void copyFrom(QObject obj) [slot]
void invertColor() [slot]

Invert the color of the current pixel.
void darken(int shade, bool compensate, double compensation) [slot]

Darken a pixel. This functions takes three arguments:
shade amount use to darken all color channels.
compensate defines if compensation should be used to limit the darkening.
compensation to limit the darkening
void invalidateIterator() [slot]

Returns the Progress object which could be used to display a progressbar in Krita to visualize the progress your script makes.
Example (in Python) :
 import Krita
 progress = Krita.progress()
 progress.setProgressTotalSteps(100)
 for i in range(100):
     progress.incProgress()
Example (in Ruby) :
 require 'Krita'
 progress = Krita.progress()
 progress.setProgressTotalSteps(100)
 for i in 0..100
   progress.incProgress()
 end

QObject image() [slot]
This function returns the Image associated with the currently loaded document.
Example (in Ruby) :
```
 require 'Krita'
 image = Krita.image()
```
QObject activeLayer() [slot]
This function returns the current active layer.
Example (in Ruby) :
```
 require 'Krita'
 layer = Krita.activeLayer()
```
QObject createImage(int width, int height, QString colorspace, QString name) [slot]
This function returns a new Image object. It takes four arguments :
width of the new image
height of the new image
colorspace id (e.g. "RGBA" or "CMYK")
the name of the new image

For example (in Ruby) :
```
 require 'Krita'
 Krita.createImage(10, 20, "RGBA", "kikoo")
```
QObject createRGBColor(int r, int g, int b) [slot]
This function return a new Color object with the given RGB triplet. It takes three arguments :
red color (0 to 255)
blue color (0 to 255)
green color (0 to 255)

For example (in Ruby) :
```
 require "Krita"
 redcolor = Krita.createRGBColor(255,0,0)
 whitecolor = Krita.createRGBColor(255,255,255)
```
QObject createHSVColor(int hue, int saturation, int value) [slot]
This function return a new Color object with the given HSV triplet. It takes three arguments :
hue color (0 to 255)
saturation color (0 to 255)
value color (0 to 255)

For example (in Ruby) :
```
 require "Krita"
 color = Krita.createHSVColor(255,125,0)
```
QObject pattern(QString patternname) [slot]
This function return a Pattern taken from the list of resources of Krita. It takes one argument :
the name of the pattern

For example (in Ruby) :
```
 require "Krita"
 brickspattern = Krita.pattern("Bricks")
```
QObject brush(QString brushname) [slot]
This function return a Brush taken from the list of resources of Krita. It takes one argument :
the name of the brush

For example (in Ruby) :
```
 require "Krita"
 circlebrush = Krita.brush("Circle (05)")
```
QObject createCircleBrush(uint w, uint h, uint hf, uint vf) [slot]
This function return a Brush with a circular shape It takes four arguments :
width
height
width of the shading
height of the shading

If the shading isn't specified, no shading will be used.
For example (in Ruby) :
```
 require "Krita"
 plaincircle = Krita.createCircleBrush(10,20,0,0)
 gradientcircle = Krita.createCircleBrush(10,20,5,10)
```
QObject createRectBrush(uint w, uint h, uint hf, uint vf) [slot]
This function return a Brush with a rectangular shape It takes four arguments :
width of the brush
height of the brush
width of the shading
height of the shading

If the shading isn't specified, no shading will be used.
For example (in Ruby) :
```
 require "Krita"
 plainrectangle = Krita.createRectBrush(10,20,0,0)
 gradientrectangle = Krita.createRectBrush(10,20,5,10)
```
QObject filter(QString filtername) [slot]
This function return a Filter object taken from the list of resources of Krita. It takes one argument :
the name of the filter

For example (in Ruby) :
```
 require "Krita"
 invertfilter = Krita.getFilter("invert")
```
QObject loadBrush(QString filename) [slot]

This function loads a Brush and then returns it. It takes one argument: the filename of the brush.
QObject loadPattern(QString filename) [slot]

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

Scripting::Module::Private

Scripting::Monitor

void signalExecutionStarted() [signal]
void signalExecutionFinished() [signal]

Scripting::PaintDevice

A PaintDevice is a layer within a Image where you are able to perform paint-operations on.

bool convertToColorspace(QString colorspacename) [slot]
Convert the image to a colorspace. This function takes one argument :
the name of the destination colorspace This function returns true if convert to the colorspace was successfully else (e.g. if the colorspace is not available, please check your installation in that case) false is returned.

For example (in Ruby) :
```
 # set the colorspace to "CMYK"
 image.convertToColorspace("CMYK")
 # following line will print "CMYK" now.
 image.colorSpaceId()
```
QObject createRectIterator(uint x, uint y, uint width, uint height) [slot]

Create an iterator over a layer, it will iterate on a rectangle area. This function takes four arguments :
x
y
width of the rectangle
height of the rectangle
QObject createHLineIterator(uint x, uint y, uint width) [slot]

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
QObject createVLineIterator(uint x, uint y, uint height) [slot]

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
QObject createPainter() [slot]

This function create a Painter which will allow you to some painting on the layer.

void beginPainting(QString name) [slot]

Uses this function to create a new undo entry. The name is the displayed undo-name. You should always close the paint-operation with endPainting() .
For example (in Ruby) :
 require "Krita"
 layer = Krita.image().activePaintDevice()
 layer.beginPainting("invert")
 iterator = layer.createRectIterator(0, 0, layer.width(), layer.height())
 while (not iterator.isDone())
     iterator.invertColor()
     iterator.next()
 end
 layer.endPainting()

void endPainting() [slot]

Uses this function to close the current undo entry and add it to the history. This function closes the with beginPainting() started painting-operation.
bool fastWaveletUntransformation(QObject wavelet) [slot]
Untransform a fast Wavelet into this layer. It takes one argument :
a wavelet object It returns true on success else (e.g. cause no valid Wavelet object was passed as argument) false is returned.

For example (in Ruby) :
```
 wavelet = layer.fastWaveletTransformation()
 layer.fastWaveletUntransformation(wavelet)
```

Scripting::Painter

The painter enables drawing to a PaintDevice object.

void setFillThreshold(int threshold) [slot]

Set the threshold the fill threshold. It takes one argument :
threshold
void fillColor(uint x, uint y, uint w, uint h) [slot]

Start filling color. It takes four arguments :
x
y
void fillPattern(uint x, uint y, uint w, uint h) [slot]

Start filling a pattern. It takes four arguments :
x
y
void setFillStyle(uint style) [slot]

This function set 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 a pattern.
void setOpacity(uint opacity) [slot]

This function set the opacity of the painting. It takes one argument :
opacity in the range 0 to 255
void setStrokeStyle(uint style) [slot]

This function set the style of the stroke. It takes one argument :
0 for none 1 for brush
void composeWith(qint32 dx, qint32 dy, QString compositeOp, QObject source, qint32 opacity, qint32 sx, qint32 sy, qint32 sw, qint32 sh) [slot]
void paintPolyline(QVariantList pointsX, QVariantList pointsY) [slot]

This function will paint a polyline. It takes two arguments :
a list of x position
a list of y position
void paintLine(double x1, double y1, double p1, double x2, double y2, double p2) [slot]

This function will paint a line. It takes six arguments :
x1
y1
pressure1
x2
y2
pressure2
void paintBezierCurve(double x1, double y1, double p1, double cx1, double cy1, double cx2, double cy2, double x2, double y2, double p2) [slot]

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 ending position, p2 is the pressure at the end. (cx1,cy1) and (cx2,cy2) are the position of the control points.
void paintEllipse(double x, double y, double w, double h, double pressure) [slot]

This function will paint an ellipse. It takes five arguments :
x
y
w
h
pressure

Where x, y, w, and h define the rectangle containing the ellipse.
void paintPolygon(QVariantList pointsX, QVariantList pointsY) [slot]

This function will paint a polygon. It takes two arguments :
a list of x position
a list of y position
void paintRect(double x, double y, double width, double height, double pressure) [slot]

This function will paint a rectangle. It takes five arguments :
x
y
width of the rectangle
height of the rectangle
pressure
void paintAt(double x, double y, double pressure) [slot]

This function will paint at a given position. It takes three arguments :
x
y
pressure
void setPaintColor(QObject color) [slot]

This functions set the paint color (also called foreground color). It takes one argument :
a Color object e.g. create with Module::createRGBColor .
void setBackgroundColor(QObject color) [slot]

This functions set the background color. It takes one argument :
a Color object e.g. create with Module::createRGBColor .
void setPattern(QObject pattern) [slot]

This function sets the pattern used for filling. It takes one argument :
a Pattern object
void setBrush(QObject brush) [slot]

This function sets the brush used for painting. It takes one argument :
a Brush object
void setPaintOp(QString paintopname) [slot]

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

Scripting::PaintLayer

A paintlayer is a layer within a Image where you are able to perform paint-operations on.

QObject paintDevice() [slot]

Scripting::Pattern

Pattern object.

Scripting::Progress

The Progress object enables displaying of a progressbar in Krita to visualize the progress your script makes.

void setProgressTotalSteps(uint totalSteps) [slot]

Set the total steps the progressbar should have. This could be as example the width * height of an image and if you iterate over the images, just call incProgress() to increase the current stage. If this function got called, Krita starts to display the progressbar.
void incProgress() [slot]

Increment the progress by one step.
void setProgress(uint progress) [slot]

Set the current stage to progress . The value should be always <= as the with setProgressTotalSteps() defined maximal number of steps.
void setProgressStage(QString stage, uint progress) [slot]

Set the current stage to progress and provide with stage a in the progressbar displayed string.
void progressDone() [slot]

If called, the progressbar will be disabled again do indicate, that the operation is done. Please note, that it's not needed to call this explicit since once the script finished, it's called automatically.

Scripting::Wavelet

Fast Wavelet object.

double getNCoeff(uint index) [slot]

Return the value of the Nth coefficient. The function takes one argument :
the index of the coefficient
void setNCoeff(uint index, double value) [slot]

Set the value of the Nth coefficient. The function takes two arguments :
the index of the coefficient
the new value of the coefficient
double getXYCoeff(uint x, uint y) [slot]

Return the value of a coefficient The function takes two arguments :
x
y
void setXYCoeff(uint x, uint y, double value) [slot]

Set the value of a coefficient. The function takes three arguments :
x
y
the new value of the coefficient
uint getDepth() [slot]

Return the depth of the layer.
uint getSize() [slot]

Return the size of the wavelet (size = width = height).
uint getNumCoeffs() [slot]

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

Krita Scripting

index

Handbook

Objects

Examples

Objects

Scripting::Brush

Scripting::Color

Scripting::ConstIterator

Scripting::ConstIteratorBase

Scripting::ConstPaintDevice

Scripting::Filter

Scripting::Histogram

Scripting::Image

Scripting::Iterator

Scripting::IteratorBase

KisProgressSubject

KoScriptingModule

Scripting::Module

Scripting::Module::Private

Scripting::Monitor

Scripting::PaintDevice

Scripting::Painter

Scripting::PaintLayer

Scripting::Pattern

Scripting::Progress

Scripting::Wavelet