Developer's information
Prev
Next

Chapter 11. Developer's information

This chapter contains information for developers or other enthousiasts who want to get more out of chalk.

Scripting

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.

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

Variables in the Krosschalkcore module

  • ChalkDocument returns a Document object

  • ChalkScript returns a ScriptProgress object

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

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

Functions in the Krosschalkcore module

  • Function: getBrush

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

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

  • Function: getFilter

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

    Krosschalkcore::getFilter("invert")
    

  • Function: getPattern

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

    Krosschalkcore::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):

    Krosschalkcore::newCircleBrush(10,20) # create a plain circle
    Krosschalkcore::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):

    Krosschalkcore::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):

    Krosschalkcore::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):

     Krosschalkcore::newRectBrush(10,20) # create a plain rectangle
     Krosschalkcore::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):

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

Descriptions and function lists for various objects in Krosschalkcore

  • 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 = 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

    • 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 = 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
    

    • 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 chalk. For example (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)
    

    • 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 chalk.

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

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

Prev
Next
Home


Would you like to comment or contribute an update to this page?
Send feedback to the TDE Development Team