# Guiones

En &chalk;, puede escribir guiones en Ruby o en Python (la disponibilidad de los intérpretes puede depender de la distribución o del administrador de la máquina en la que se instale). Aquí va a encontrar una descripción de la API para guiones.

Con &chalk; se distribuyen algunos ejemplo, y los puede encontrar en `/usr/share/apps/chalk/scripts` (o `/opt/kde/share/apps/chalk/scripts`).

## Variables del módulo `Krosschalkcore`

- `ChalkDocument` devuelve un objeto `Document`

- `ChalkScript` devuelve un objeto `ScriptProgress`

Puede recuperar un objeto usando la función `get` del módulo `Krosschalkcore`, en Ruby tiene que escribir algo parecido a esto:

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

## Funciones del módulo `Krosschalkcore`

- Función: `getBrush`

  Esta función devuelve un objeto `Brush` de la lista de recursos de &chalk;. Recibe un argumento: el nombre de la brocha. Por ejemplo (en Ruby):

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

- Función: `getFilter`

  Esta función devuelve un objeto `Filter` de la lista de recursos de &chalk;. Recibe un argumento: el nombre del filtro. Por ejemplo (en Ruby):

      Krosschalkcore::getFilter("invert")

- Función: `getPattern`

  Esta función devuelve un objeto `Pattern` de la lista de recursos de &chalk;. Recibe un argumento: el nombre del patrón. Por ejemplo (en Ruby):

      Krosschalkcore::getPattern("Bricks")

- Función: `loadBrush`

  Esta función carga un objeto `Brush` y luego lo devuelve. Recibe un argumento: el nombre del archivo de la brocha.

- Función: `loadPattern`

  Esta función carga un objeto `Pattern` y luego lo devuelve. Recibe un argumento: el nombre del archivo del patrón.

- Función: `newCircleBrush`

  Esta función devuelve un objeto `Brush` con una forma circular. Recibe al menos dos argumentos: la anchura y la altura. Puede recibir otros dos argumentos: la anchura de la sombra y la altura de la sombra. Si no se especifica la sombra, no se utiliza. Por ejemplo (en Ruby):

      Krosschalkcore::newCircleBrush(10,20) # crea un círculo plano
      Krosschalkcore::newCircleBrush(10,20,5,10) # crea un degradado

- Función: `newHSVColor`

  Esta función devuelve un objeto `Color` nuevo con la tripleta HSV dada. Recibe tres argumentos: el componente de tono (de 0 a 255), el componente de saturación (de 0 a 255) y el componente de valor (de 0 a 255). Por ejemplo (en Ruby):

      Krosschalkcore::newRGBColor(255,125,0)

- Función: `newImage`

  Esta función devuelve un objeto `Image` nuevo. Recibe cuatro argumentos: anchura, altura, id. del espacio de colores y nombre de la imagen. Y como resultado se obtiene un objeto `Image`. Por ejemplo (en Ruby):

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

- Función: `newRectBrush`

  Esta función devuelve un objeto `Brush` con una forma rectangular. Recibe al menos dos argumentos: anchura y altura. Puede recibir otros dos argumentos: anchura de la sombra y altura de la sombra. Si no se especifica la sombra, no se usa. Por ejemplo (en Ruby):

      Krosschalkcore::newRectBrush(10,20) # crea un rectángulo plano
       Krosschalkcore::newRectBrush(10,20,5,10) # crea un degradado

- Función: `newRGBColor`

  Esta función devuelve un objeto `Color` nuevo con la tripleta RGB dada. Recibe tres argumentos: componente de rojo (de 0 a 255), componente de azul (de 0 a 255) y componente de verde (de 0 a 255). Por ejemplo (en Ruby):

      Krosschalkcore::newRGBColor(255,0,0) # crea un color rojo
      Krosschalkcore::newRGBColor(255,255,255) # crea un color blanco

## Descripciones y lista de funciones para varios objetos de `Krosschalkcore`

- Objeto: PaintLayer

  - Función: `beginPainting`

  - Función: `convertToColorspace`

    Convierte la imagen a un espacio de colores. Esta función recibe un argumento: el nombre del espacio de colores destino. Por ejemplo (en Ruby):

        image.convertToColorspace("CMYK")

  - Función: `createHistogram`

    Esta función crea un histograma para esta capa. Recibe dos argumentos: el tipo del histograma ("RGB8HISTO"), y 0 si el histograma es lineal, o 1 si es logarítmico.

  - Función: `createHLineIterator`

    Crea un iterador sobre una capa, que itera sobre una fila. Esta función recibe tres argumentos: `x` (empezar en la fila), `y` (posición vertical de la fila) y anchura de la fila.

  - Función: `createPainter`

    Esta función crea un objeto `Painter` que le permite dibujar sobre la capa.

  - Función: `createRectIterator`

    Crea un iterador sobre una capa que itera sobre un área rectangular. Esta función recibe cuatro argumentos: `x`, `y`, anchura del rectángulo y altura del rectángulo.

  - Función: `createVLineIterator`

    Crea un iterador sobre una capa, que itera sobre una columna. Esta función recibe tres argumentos: `x` (posición horizontal de la columna), `y` (empezar en la columna) y altura de la columna.

  - Función: `endPainting`

    Use esta función para cerrar la entrada de rehacer actual y para añadirla al historial.

  - Función: `fastWaveletTransformation`

    Devuelve la transformada rápida de onda de la capa.

  - Función: `fastWaveletUntransformation`

    Deja de realizar la transformada rápida de onda de la capa. Recibe un argumento: un objeto wavelet. Por ejemplo (en Ruby):

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

  - Función: `getHeight`

    Devuelve la altura de la capa.

  - Función: `getWidth`

    Devuelve la anchura de la capa.

- Objecto: `Filter`

  - Función: `getFilterConfiguration`

    Esta función devuelve el objeto `FilterConfiguration` asociado con este filtro.

  - Función: `process`

    Esta función aplica el filtro. Recibe al menos un argumento: la capa origen. También puede usar estos cuatro argumentos: `x`, `y`, `anchura` y `altura`. (`x`,`y`,`anchura` y `altura`) define el área rectangular en la que se debe aplicar el filtro. Si el rectángulo no se ha definido, el filltro se aplica a la capa origen por completo. Por ejemplo (en 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 )

- Objeto: `FilterConfiguration`

  - Función: `getProperty`

    Esta función devuelve el valor de un parámetro del objeto `Filter` asociado. Recibe un argumento: el nombre del parámetro.

  - Función: `setProperty`

    Esta función define un parámetro para el objeto `Filter` asociado. Recibe dos argumentos: el nombre del parámetro y el valor, cuyo tipo depende del objeto `Filter`.

- Objeto: `Histogram`

  Esta clase le permite acceder al histograma de un objeto `PaintLayer`. Ejemplo (en 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

  - Función: `getChannel`

    Devuelve el canal seleccionado.

  - Función: `getCount`

    Esta función devuelve el número de píxeles utilizados por el histograma.

  - Función: `getHighest`

    Esta función devuelve el valor más alto del histograma.

  - Función: `getLowest`

    Esta función devuelve el valor más bajo del histograma.

  - Función: `getMax`

    Esta función devuelve el límite máximo del histograma (se descartan los valores superiores al máximo). El valor está en el rango 0.0 – 1.0.

  - Función: `getMean`

    Esta función devuelve la media del histograma.

  - Función: `getMin`

    Esta función devuelve el límite mínimo del histograma (se descartan los valores inferiores al mínimo). El valor está en el rango 0.0 – 1.0.

  - Función: `getNumberOfBins`

    Devuelve el número de cubos del histograma.

  - Función: `getTotal`

    Esta función devuelve la suma de todos los valores del histograma.

  - Función: `getValue`

    Devuelve el valor de un cubo del histograma. Esta función recibe un argumento: índice, en el rango [0..255].

  - Función: `setChannel`

    Selecciona el canal de la capa en la que se obtiene el resultado del histograma. Esta función recibe un argumento: el número del canal.

- Objeto: `ScriptProgress`

  `ScriptProgress` se utiliza para gestionar la barra de progreso de la barar de estado de &chalk;. Por ejemplo (en Ruby):

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

  - Función: `incProgress`

    Esta función incremente el progreso en un paso.

  - Función: `setProgress`

    Esta función define el valor del progreso. Recibe un argumento: el valor del progreso.

  - Función: `setProgressStage`

    Esta función define el valor del progreso y muestra el texto.

  - Función: `setProgressTotalSteps`

    Esta función define el número de pasos que necesita el guión. Recibe un argumento: el valor máximo del progreso.

- Objeto: `Wavelet`

  Este objeto mantiene el coeficiente de una transformación de onda en un objeto `PaintLayer`.

  - Función: `getDepth`

    Devuelve la profundidad de la capa.

  - Función: `getNCoeff`

    Devuelve el valor del enésimo coeficiente. La función recibe un argumento: el índice del coeficiente.

  - Función: `getNumCoeffs`

    Devuelve el número de coeficientes de la onda (= tamaño * tamaño * profundidad).

  - Función: `getSize`

    Devuelve el tamaño de la onda (tamaño = anchura = altura).

  - Función: `getXYCoeff`

    Devuelve el valor de un coeficiente. El coeficiente recibe dos argumentos: `x` e `y`.

  - Función: `setNCoeff`

    Define el valor de coeficiente enésimo. La función recibe dos argumentos: el índice del coeficiente y el valor nuevo del coeficiente.

  - Función: `setXYCoeff`

    Define el valor de un coeficiente. La función recibe tres argumentos: `x`, `y` y el valor nuevo del coeficiente.

- Objeto: `Painter`

  - Función: `convolve`

    Esta función aplica un núcleo de convolución a una imagen. Recibe al menos tres argumentos: una lista con una lista del núcleo (todas las listas deben tener el mismo tamaño), factor y desplazamiento.

    El valor de un píxel se consigue con la siguiente función: K * P / factor + desplazamiento, donde K es el núcleo y P es la vecindad.

    Puede recibir los siguientes parámetros opcionales: `borderOp` (contrar cómo se hace la convolución de los píxeles del borde de una imagen: 0 = usar el color predefinido, 1 = usar el píxel del aldo opuesto de la imagen, 2 = usar el píxel del borde, 3 = evitar los píxeles del borde), `canal` (1 para color, 2 para alfa, 3 para ambos), `x`, `y`, `anchura` y `altura`.

  - Función: `setFillThreshold`

    Define el umbral de relleno. Recibe un argumento: el umbral.

  - Función: `fillColor`

    Comienza a rellenar con un color. Recibe dos argumentos: `x` e `y`.

  - Función: `fillPattern`

    Comienza a rellenar con un patrón. Recibe dos argumentos: `x` e `y`.

  - Función: `paintPolyline`

    Esta función pinta un polígono con líneas. Recibe dos argumentos: una lista de posiciones x y una lista de posiciones y.

  - Función: `paintLine`

    Esta función pinta una línea. Recibe cinco argumentos: `x1`, `y1`, `x2`, `y2` y `presión`.

  - Función: `paintBezierCurve`

    Esta función pinta una curva Bézier. Recibe diez argumentos: `x1`, `y1`, `p1`, `cx1`, `cy1`, `cx2`, `cx2`, `x2`, `y2` y `p2`, donde (`x1`,`y1`) es la posición inicial, `p1` es la presión inicial, (`x2`,`y2`) es la posición final, `p2` es la presión final. (`cx1`,`cy1`) y (`cx2`,`cy2`) son las posiciones de los puntos de control.

  - Función: `paintEllipse`

    Esta función pinta una elipse. Recibe cinco argumentos: `x1`, `y1`, `x2`, `y2` y `presión`, donde (`x1`,`y1`) y (`x2`,`y2`) son las posiciones de los dos centros.

  - Función: `paintPolygon`

    Esta función pinta un polígono. Recibe dos argumentos: una lista de posiciones x y una lista de posiciones y.

  - Función: `paintRect`

    Esta función dibuja un rectángulo. Recibe cinco argumentos: `x`, `y`, `anchura` `altura` y `presión`.

  - Función: `paintAt`

    Esta función dibuja en una posición dada. Recibe tres argumentos: `x`, `y` y `presión`.

  - Función: `setPaintColor`

    Esta función define el color de la pintura (también llamado color de primer plano). Recibe un argumento: un objeto `Color`.

  - Función: `setBackgroundColor`

    Esta función define el color de fondo. Recibe un argumento: un objeto `Color`.

  - Función: `setPattern`

    Esta función define el patrón usado para rellenar. Recibe un argumento: un objeto `Pattern`.

  - Función: `setBrush`

    Esta función define la brocha que se utiliza para pintar. Recibe un argumento: un objeto `Brush`.

  - Función: `setPaintOp`

    Esta función define la operación de pintura. Recibe un argumento: el nombre de la operación de pintura.

  - Función: `setDuplicateOffset`

    Esta función define el desplazamiento duplicado. Recibe dos argumentos: el desplazamiento horizontal y el desplazamiento vertical.

  - Función: `setOpacity`

    Esta función define la opacidad de la pintura. Recibe un argumento: la opacidad, en el rango de 0 a 255.

  - Función: `setStrokeStyle`

    Esta función define el estilo del trazo. Recibe un argumento: 0 para ninguno o 1 para brocha.

  - Función: `setFillStyle`

    Esta función define el estilo de relleno del objeto `Painter`. Recibe un argumento: 0 para ninguno, 1 para relleno con color de primer plano, 2 para relleno con color de fondo y 3 para relleno con patrón.

- Objeto: `Iterator`

  Este objeto le permite cambiar los valores de píxel uno a uno. El nombre de algunas funciones depende del espacio de colores, de hecho, si el espacio de colores de la capa es RGB, debe tener `setR`, `setG` y `setB`, y para CMYK: `setC`, `setM`, `setY` y `setK`. En la documentación siguiente, asumiremos que el espacio de colores se llama ABC, con tres canales: A, B y C.

  - Funciones: `setA`, `setB`, `setC`

    Estas funciones reciben un argumento: el valor nuevo de uno de los canales para este píxel.

  - Función: `setABC`

    Define el valor de todos los canales. Esta función recibe un argumento: un vector con los valores nuevos para todos los canales.

  - Función `getA`, `getB`, `getC`

    Devuelve el valor de uno de los canales de este píxel.

  - Función: `getABC`

    Devuelve un vector con los valores de todos los canales.

  - Función: `darken`

    Oscurece un píxel. Esta función recibe al menos un argumento: `sombra` (cantidad utilizada para oscurecer todos los canales de color). Esta función puede recibir los siguientes argumentos opcionales: `compensación` (para limitar el oscurecimiento).

  - Función: `invertColor`

    Invierte el color de un píxel.

  - Función: `next`

    Incrementa la posición y va al siguiente píxel.

  - Función: `isDone`

    Devuelve cierto si el iterador está al final (no hay más píxeles disponibles).

## Recursos

Aquí hay consejos o listas parciales de recursos para &chalk;.

Para los objetos `Brush` y `Pattern`: Puede obtener el nombre de la brocha o del patrón asociado con el selector en la barra de herramientas de &chalk;.

Una lista de ids. con todos los espacios de color en &chalk; 1.5: LABA, RGBA, RGBA16, RGBAF32, RGBAF16HALF, LMSAF32, GRAYA, GRAYA16, CMYK, CMYKA16.