path: root/doc/chalk/developers-scripting.docbook

<sect1 id="developers-scripting">
<title>Scripting</title>

<para>
In &chalk;, 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.
</para><para>
Some examples are distributed with &chalk;, and you might find them in
<filename>/usr/share/apps/chalk/scripts</filename> (or
<filename>/opt/kde/share/apps/chalk/scripts</filename>).
</para>

<sect2 id="developers-scripting-variables">
<title>Variables in the <classname>Krosschalkcore</classname> module</title>

<itemizedlist>
<listitem><para><varname>ChalkDocument</varname> returns a
<classname>Document</classname> object</para></listitem>
<listitem><para><varname>ChalkScript</varname> returns a
<classname>ScriptProgress</classname> object</para></listitem>
</itemizedlist>

<para>
You can retrieve an object using the <function>get</function> function of the
<classname>Krosschalkcore</classname> module, in Ruby you will have to write something like that:
<programlisting>
doc = Krosschalkcore::get("ChalkDocument")
script = Krosschalkcore::get("ChalkScript")
</programlisting>
</para>

</sect2>

<sect2 id="developers-scripting-functions">
<title>Functions in the <classname>Krosschalkcore</classname> module</title>

<itemizedlist>
<listitem><para>Function: <function>getBrush</function></para><para>
This function returns a <classname>Brush</classname> taken from the list of
&chalk; resources. It takes one argument: the name of the brush.
For example (in Ruby):
<programlisting>
Krosschalkcore::getBrush("Circle (05)")
</programlisting></para></listitem>

<listitem><para>Function: <function>getFilter</function></para><para>
This function returns a <classname>Filter</classname> taken from the list of
&chalk; resources. It takes one argument: the name of the filter.
For example (in Ruby):
<programlisting>
Krosschalkcore::getFilter("invert")
</programlisting></para></listitem>

<listitem><para>Function: <function>getPattern</function></para><para>
This function returns a <classname>Pattern</classname> taken from the list of
&chalk; resources. It takes one argument: the name of the pattern.
For example (in Ruby):
<programlisting>
Krosschalkcore::getPattern("Bricks")
</programlisting></para></listitem>

<listitem><para>Function: <function>loadBrush</function></para><para>
This function loads a <classname>Brush</classname> and then returns it.
It takes one argument: the filename of the brush.</para></listitem>

<listitem><para>Function: <function>loadPattern</function></para><para>
This function loads a <classname>Pattern</classname> and then returns it.
It takes one argument: the filename of the pattern.</para></listitem>

<listitem><para>Function: <function>newCircleBrush</function></para><para>
This function returns a <classname>Brush</classname> 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):
<programlisting>
Krosschalkcore::newCircleBrush(10,20) # create a plain circle
Krosschalkcore::newCircleBrush(10,20,5,10) # create a gradient
</programlisting></para></listitem>

<listitem><para>Function: <function>newHSVColor</function></para><para>
This function returns a new <classname>Color</classname> 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):
<programlisting>
Krosschalkcore::newHSVColor(255,125,0)
</programlisting></para></listitem>

<listitem><para>Function: <function>newImage</function></para><para>
This function returns a new <classname>Image</classname>. It takes four arguments:
width, height, colorspace id, name of the image. And in return you get an
<classname>Image</classname> object.
For example (in Ruby):
<programlisting>
Krosschalkcore::newImage(10,20, "RGBA", "kikoo")
</programlisting></para></listitem>

<listitem><para>Function: <function>newRectBrush</function></para><para>
This function returns a <classname>Brush</classname> 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):
<programlisting>
 Krosschalkcore::newRectBrush(10,20) # create a plain rectangle
 Krosschalkcore::newRectBrush(10,20,5,10) # create a gradient
</programlisting></para></listitem>

<listitem><para>Function: <function>newRGBColor</function></para><para>
This function returns a new <classname>Color</classname> 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):
<programlisting>
Krosschalkcore::newRGBColor(255,0,0) # create a red color
Krosschalkcore::newRGBColor(255,255,255) # create a white color
</programlisting></para></listitem>
</itemizedlist>
</sect2>

<sect2 id="developers-scripting-objects">
<title>Descriptions and function lists for various objects in
<classname>Krosschalkcore</classname></title>

<itemizedlist>
<listitem><para>Object: PaintLayer</para>

<itemizedlist>
<listitem><para>Function: <function>beginPainting</function></para></listitem>

<listitem><para>Function: <function>convertToColorspace</function></para><para>
Convert the image to a colorspace. This function takes one argument: the name
of the destination colorspace.
For example (in Ruby):
<programlisting>
image.convertToColorspace("CMYK")
</programlisting></para></listitem>

<listitem><para>Function: <function>createHistogram</function></para><para>
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.</para></listitem>

<listitem><para>Function: <function>createHLineIterator</function></para><para>
Create an iterator over a layer, it will iterate on a row. This function takes three arguments:
<varname>x</varname> (start in the row), <varname>y</varname> (vertical
position of the row), width of the row.</para></listitem>

<listitem><para>Function: <function>createPainter</function></para><para>
This function creates a <classname>Painter</classname> which will allow you to
paint on the layer. </para></listitem>

<listitem><para>Function: <function>createRectIterator</function></para><para>
Create an iterator over a layer, it will iterate on a rectangular area. This
function takes four arguments: <varname>x</varname>, <varname>y</varname>,
width of the rectangle, height of the rectangle.</para></listitem>

<listitem><para>Function: <function>createVLineIterator</function></para><para>
Create an iterator over a layer, it will iterate on a column. This function
takes three arguments: <varname>x</varname> (horizontal position of the
column), <varname>y</varname> (start in the column), height of the column.</para></listitem>

<listitem><para>Function: <function>endPainting</function></para><para>
This function closes the current undo entry and adds it to the history.</para></listitem>

<listitem><para>Function: <function>fastWaveletTransformation</function></para><para>
Returns the fast wavelet transformation of the layer.</para></listitem>

<listitem><para>Function: <function>fastWaveletUntransformation</function></para><para>
Untransforms a fast wavelet into this layer. It takes one argument: a wavelet
object.
For example (in Ruby):
<programlisting>
wavelet = layer.fastWaveletTransformation()
layer.fastWaveletUntransformation(wavelet)
</programlisting></para></listitem>

<listitem><para>Function: <function>getHeight</function></para><para>
Return the height of the layer.</para></listitem>

<listitem><para>Function: <function>getWidth</function></para><para>
Return the width of the layer.</para></listitem>
</itemizedlist>
</listitem>

<listitem><para>Object: <classname>Filter</classname></para>
<itemizedlist>

<listitem><para>Function: <function>getFilterConfiguration</function></para><para>
This function returns the <classname>FilterConfiguration</classname>
associated with this filter.</para></listitem>

<listitem><para>Function: <function>process</function></para><para>
This function will apply the filter. It takes at least one argument: the
source layer. You can also use these four aguments: <varname>x</varname>,
<varname>y</varname>, <varname>width</varname>, <varname>height</varname>.
(<varname>x</varname>,<varname>y</varname>,<varname>width</varname>,<varname>height</varname>)
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)
<programlisting>
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 )
</programlisting></para></listitem>
</itemizedlist></listitem>

<listitem><para>Object: <classname>FilterConfiguration</classname></para>
<itemizedlist>

<listitem><para>Function: <function>getProperty</function></para><para>
This function returns the value of a parameter of the associated
<classname>Filter</classname>. It takes one argument: the name of the
parameter.</para></listitem>

<listitem><para>Function: <function>setProperty</function></para><para>
This function defines a parameter of the associated
<classname>Filter</classname>. It takes two arguments: the name of the
parameter and the value, whose type depends on the
<classname>Filter</classname>.</para></listitem>
</itemizedlist>
</listitem>

<listitem><para>Object: <classname>Histogram</classname></para>

<para>This class allows you to access the histogram of a
<classname>PaintLayer</classname>.
Example (in Ruby):
<programlisting>
 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
</programlisting>
</para>

<itemizedlist>
<listitem><para>Function: <function>getChannel</function></para><para>
Return the selected channel.</para></listitem>

<listitem><para>Function: <function>getCount</function></para><para>
This function returns the number of pixels used by the histogram.</para></listitem>

<listitem><para>Function: <function>getHighest</function></para><para>
This function returns the highest value of the histogram.</para></listitem>

<listitem><para>Function: <function>getLowest</function></para><para>
This function returns the lowest value of the histogram.</para></listitem>

<listitem><para>Function: <function>getMax</function></para><para>
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 &ndash; 1.0.</para></listitem>

<listitem><para>Function: <function>getMean</function></para><para>
This function returns the mean of the histogram.</para></listitem>

<listitem><para>Function: <function>getMin</function></para><para>
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 &ndash; 1.0.</para></listitem>

<listitem><para>Function: <function>getNumberOfBins</function></para><para>
Return the number of bins of this histogram. </para></listitem>

<listitem><para>Function: <function>getTotal</function></para><para>
This function returns the sum of all values of the histogram.</para></listitem>

<listitem><para>Function: <function>getValue</function></para><para>
Return the value of a bin of the histogram. This function takes one argument:
index, in the range [0..255].</para></listitem>

<listitem><para>Function: <function>setChannel</function></para><para>
Select the channel of the layer on which to get the result of the histogram.
This function takes one argument: the channel number.</para></listitem>
</itemizedlist>
</listitem>

<listitem><para>Object: <classname>ScriptProgress</classname></para>
<para><classname>ScriptProgress</classname> is used to manage the progress bar
of the status bar in &chalk;.
For example (in Ruby):
<programlisting>
script = Krosschalkcore::get("ChalkScript")
script.setProgressTotalSteps(1000)
script.setProgressStage("progressive", 0)
for i in 1..900
  script.incProgress()
end
script.setProgressStage("brutal", 1000)
</programlisting></para>

<itemizedlist>
<listitem><para>Function: <function>incProgress</function></para><para>
This function increments the progress by one step.</para></listitem>

<listitem><para>Function: <function>setProgress</function></para><para>
This function sets the value of the progress. It takes one argument:
the value of the progress.</para></listitem>

<listitem><para>Function: <function>setProgressStage</function></para><para>
This function sets the value of the progress and displays the text.</para></listitem>

<listitem><para>Function: <function>setProgressTotalSteps</function></para><para>
This function set the number of steps that the script will require. It takes
one argument: the maximum value of the progress</para></listitem>
</itemizedlist>
</listitem>

<listitem><para>Object: <classname>Wavelet</classname></para><para>
This object holds the coefficients of a wavelet transformation of a
<classname>PaintLayer</classname>.</para>
<itemizedlist>

<listitem><para>Function: <function>getDepth</function></para><para>
Returns the depth of the layer.</para></listitem>

<listitem><para>Function: <function>getNCoeff</function></para><para>
Returns the value of the Nth coefficient. The function takes one argument: the
index of the coefficient.</para></listitem>

<listitem><para>Function: <function>getNumCoeffs</function></para><para>
Returns the number of coefficients in this wavelet (= size * size * depth).</para></listitem>

<listitem><para>Function: <function>getSize</function></para><para>
Returns the size of the wavelet (size = width = height).</para></listitem>

<listitem><para>Function: <function>getXYCoeff</function></para><para>
Returns the value of a coefficient. The function takes two arguments:
<varname>x</varname> and <varname>y</varname>.</para></listitem>

<listitem><para>Function: <function>setNCoeff</function></para><para>
Set the value of the Nth coefficient. The function takes two arguments: the
index of the coefficient and the new value of the coefficient.</para></listitem>

<listitem><para>Function: <function>setXYCoeff</function></para><para>
Set the value of a coefficient. The function takes three arguments:
<varname>x</varname>, <varname>y</varname>, and the new value of the
coefficient.</para></listitem>
</itemizedlist>
</listitem>

<listitem><para>Object: <classname>Painter</classname></para>
<itemizedlist>

<listitem><para>Function: <function>convolve</function></para><para>
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.
</para><para>
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.
</para><para>
It can take the following optional arguments: <varname>borderOp</varname>
(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), <varname>channel</varname> (1 for
color, 2 for alpha, 3 for both), <varname>x</varname>, <varname>y</varname>,
<varname>width</varname>, <varname>height</varname>.</para></listitem>

<listitem><para>Function: <function>setFillThreshold</function></para><para>
Sets the fill threshold. It takes one argument: the threshold.</para></listitem>

<listitem><para>Function: <function>fillColor</function></para><para>
Starts filling with a color. It takes two arguments: <varname>x</varname> and
<varname>y</varname>.</para></listitem>

<listitem><para>Function: <function>fillPattern</function></para><para>
Starts filling with a pattern. It takes two arguments: <varname>x</varname>
and <varname>y</varname>.</para></listitem>

<listitem><para>Function: <function>paintPolyline</function></para><para>
This function will paint a polyline. It takes two arguments: a list of x
positions, and a list of y positions.</para></listitem>

<listitem><para>Function: <function>paintLine</function></para><para>
This function will paint a line. It takes five arguments:
<varname>x1</varname>, <varname>y1</varname>, <varname>x2</varname>,
<varname>y2</varname>, and <varname>pressure</varname>. 
</para></listitem>

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

<listitem><para>Function: <function>paintEllipse</function></para><para>
This function will paint an ellipse. It takes five arguments:
<varname>x1</varname>, <varname>y1</varname>, <varname>x2</varname>,
<varname>y2</varname>, <varname>pressure</varname>, where
(<varname>x1</varname>,<varname>y1</varname>) and
(<varname>x2</varname>,<varname>y2</varname>) are the positions of the two
centers.</para></listitem>

<listitem><para>Function: <function>paintPolygon</function></para><para>
This function will paint a polygon. It takes two arguments: a list of x
positions and a list of y positions.</para></listitem>

<listitem><para>Function: <function>paintRect</function></para><para>
This function will paint a rectangle. It takes five arguments:
<varname>x</varname>, <varname>y</varname>, <varname>width</varname>
<varname>height</varname>, <varname>pressure</varname>.</para></listitem>

<listitem><para>Function: <function>paintAt</function></para><para>
This function will paint at a given position.
It takes three arguments: <varname>x</varname>, <varname>y</varname>,
<varname>pressure</varname>.</para></listitem>

<listitem><para>Function: <function>setPaintColor</function></para><para>
This function sets the paint color (also called foreground color). It takes
one argument: a <classname>Color</classname>.</para></listitem>

<listitem><para>Function: <function>setBackgroundColor</function></para><para>
This function sets the background color. It takes one argument: a
<classname>Color</classname>.</para></listitem>

<listitem><para>Function: <function>setPattern</function></para><para>
This function sets the pattern used for filling. It takes one argument: a
<classname>Pattern</classname> object.</para></listitem>

<listitem><para>Function: <function>setBrush</function></para><para>
This function sets the brush used for painting. It takes one argument: a
<classname>Brush</classname> object.</para></listitem>

<listitem><para>Function: <function>setPaintOp</function></para><para>
This function defines the paint operation. It takes one argument: the name of
the paint operation.</para></listitem>

<listitem><para>Function: <function>setDuplicateOffset</function></para><para>
This function defines the duplicate offset. It takes two arguments: the
horizontal offset and the vertical offset.</para></listitem>

<listitem><para>Function: <function>setOpacity</function></para><para>
This function set the opacity of the painting. It takes one argument: the
opacity, in the range 0 to 255.</para></listitem>

<listitem><para>Function: <function>setStrokeStyle</function></para><para>
This function sets the style of the stroke. It takes one argument: 0 for none,
or 1 for brush.</para></listitem>

<listitem><para>Function: <function>setFillStyle</function></para><para>
This function sets the fill style of the <classname>Painter</classname>.
It takes one argument: 0 for none, 1 for fill with foreground color, 2 for
fill with background color, 3 for fill with pattern.</para></listitem>
</itemizedlist>
</listitem>

<listitem><para>Object: <classname>Iterator</classname></para><para>
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 <function>setR</function>,
<function>setG</function> and <function>setB</function>, and for
CMYK: <function>setC</function>, <function>setM</function>,
<function>setY</function> and <function>setK</function>. In the documentation
below we will assume that the colorspace is called ABC, with three channels:
A, B and C.</para>

<itemizedlist>
<listitem><para>Functions: <function>setA</function>,
<function>setB</function>, <function>setC</function></para><para>
Those functions take one argument: the new value of one of the channels of
this pixel.</para></listitem>

<listitem><para>Function: <function>setABC</function></para><para>
Set the value of all channels. This function takes one argument: an array with
the new values for all channels.</para></listitem>

<listitem><para>Functions: <function>getA</function>,
<function>getB</function>, <function>getC</function></para><para>
Return the value of one of the channels of this pixel.</para></listitem>

<listitem><para>Function: <function>getABC</function></para><para>
Return an array with the values of all channels.</para></listitem>

<listitem><para>Function: <function>darken</function></para><para>
Darken a pixel. This function takes at least one argument:
<varname>shade</varname> (amount used to darken all color channels). This
function can take the following optional argument:
<varname>compensation</varname> (to limit the darkening).</para></listitem>

<listitem><para>Function: <function>invertColor</function></para><para>
Invert the color of a pixel.</para></listitem>

<listitem><para>Function: <function>next</function></para><para>
Increment the position, go to the next pixel.</para></listitem>

<listitem><para>Function: <function>isDone</function></para><para>
Return true if the iterator is at the end (no more pixels are
available).</para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>

</sect2>

<sect2 id="developers-scripting-resources">
<title>Resources</title>

<para>
Here are hints or partial lists of resources for &chalk;.
</para><para>
For <classname>Brush</classname> and <classname>Pattern</classname>: You can get
the name and the associated brush or pattern from the selector in &chalk;'s
toolbar.
</para><para>
A list of ids for colorspaces in &chalk;: LABA, RGBA, RGBA16, RGBAF32,
RGBAF16HALF, LMSAF32, GRAYA, GRAYA16, CMYK, CMYKA16.
</para>
</sect2>

</sect1>