ToonzScript

ToonzScript es el lenguaje de scripting usado en OpenToonz. Usar ToonzScript permite a los usuarios crear secuencias de comandos, evitando así la necesidad de realizar tareas repetitivas de forma manual. ToonzScript está basado en QtScript y utiliza el estándar ECMAScript. Es posible encontrar una guía de referencia del estándar ECMAScript en la siguiente URL:

Referencia de ECMAScript (en inglés)

Nota

Muchos lenguajes de scripting conocidos están basados en el estándar ECMAScript como JavaScript, JScript, y ActionScript. La sintaxis de ToonzScript es similar a la de JavaScript, por esta razón, una buena introducción a JavaScript puede resultar muy útil para una mejor comprensión de los fundamentos de ToonzScript.

La página original de ToonzScript conteniendo algunos ejemplos (bastante antiguos) se encuentra disponible en la siguiente URL:

Página de ToonzScript (en inglés)

Es posible ejecutar scripts usando el comando Archivo  →  Scripts  →  Ejecutar script... . Alternativamente, es posible ingresar y ejecutar comandos directamente en la Consola de scripts, que puede ser abierta usando el comando Archivo  →  Scripts  →  Abrir consola de scripts... .

Nota

Cuando un script se encuentra en ejecución, la Consola de scripts se abrirá de forma automática para mostrar los comandos contenidos en el mismo.

Administración de archivos

toonz_script_runscript

La extensión de los archivos de ToonzScript es .js, los scripts deben encontrarse en la carpeta OpenToonz stuff/library/script , para poder ser recuperados automáticamente al abrir el explorador de la función Ejecutar script.

Uso de la Consola de comandos

toonz_script_console

La Consola de comandos permite al usuario ingresar directamente comandos; además de esto también es posible arrastrar y soltar archivos de texto externos en la consola, lo cual insertará automáticamente la ruta de dichos archivos en la misma.

La interfaz de programa no se verá bloqueada mientras se ejecute una serie de comandos ingresados desde la consola.

Convenciones de uso de la consola

Se implementan las siguientes convenciones para el uso de la Consola de scripts:

  • Sólo es posible editar el texto del último párrafo.
  • Las teclas de flechas hacia Arriba y Abajo permiten la navegación del historial de comandos.
  • La ejecución de comandos que demoren no bloqueará la interacción con la interfaz del programa.
  • El atajo Ctrl+Y interrumpirá la ejecución de comandos que estén demorando.
  • Al ingresar una ruta como parte de una cadena de texto, todas las barras invertidas deben ser duplicadas. Siguiendo esa regla, la ruta: C:\tmp\prueba.jpg quedaría como C:\\tmp\\prueba.jpg .
  • Aún trabajando bajo un sistema operativo de la familia Windows, la barra y la barra invertida pueden ser usadas con el mismo efecto, así la ruta C:\tmp\prueba.jpg será equivalente a la ruta C:/tmp/prueba.jpg .
  • Al arrastrar y soltar un archivo externo sobre la consola, se generará una cadena de texto conteniendo la ruta a dicho archivo, cuyas barras invertidas serán automáticamente duplicadas.
  • Si bien es posible copiar varias líneas de texto desde la consola, sólo se permite pegar una línea de texto.

Especificaciones de ToonzScript

Construido sobre las bases de ECMAScript, ToonzScript mantiene un cierto grado de similitud con la sintaxis de JavaScript, sin embargo al mismo tiempo, implementa algunas funciones y varias clases específicamente creadas para hacer más sencilla la interacción con la arquitectura de software de OpenToonz. A continuación se ofrece una lista de las especificaciones de ToonzScript:

Comandos

  • print(arg1, arg2, …): escribe un mensaje en la consola.
    El comando print no devuelve el valor undefined .

Ejemplo:

print(“result=”,12*3);
  • run(nombredearchivo): ejecuta el script guardado en nombredearchivo.
    Las rutas relativas se refieren a la carpeta «<opentoonz library>/scripts/»

Ejemplos:

run(“test.js”)
run(“C:\\Users\\Username\\Tests\\another_test.js”)
  • view(imagen): permite ver una imagen.
    Es posible usar legalmente el comando view en el siguiente contexto: view(new Image(nombredearchivo))
  • view(nivel): permite ver un nivel.

Ejemplo:

view(new Level(“C:\\OpenToonz stuff\\sandbox\\drawings\\A.pli”))
  • La variable ToonzVersion puede ser usada para comprobar la versión actual de OpenToonz.

Clases

Para cada clase se listan, el constructor correspondiente, sus métodos y atributos.

File path

contiene la ruta a un objeto.

Constructor:

  • new FilePath(ruta)

Métodos:

  • ruta2 = path.withExtension(e)
  • ruta2 = path.withName(nombre)
  • ruta2 = path.withParentDirectory(d)
  • ruta2 = path.concat(f) - donde f puede ser un FilePath o una cadena
  • archivos = path.files() - si archivos es una carpeta, entonces este método devuelve los archivos dentro de esa carpeta.

Atributos:

  • path.extension - atributo de lectura y escritura
  • path.name - atributo de lectura y escritura
  • path.parentDirectory - atributo de lectura y escritura
  • path.lastModified - atributo de sólo lectura
  • path.exists - atributo de sólo lectura
  • path.isDirectory - atributo de sólo lectura

Ejemplos:

myRoot = new FilePath(“C:\\Users\\username\\”);

f = myRoot.concat(“tests”).concat(“name.0001.tif”);

print(f.extension); // => “tif”

print(f.name); // => “name”

print(f.parentDirectory); // => “C:\Users\username\tests”

if(f.exists) print(“the file “,f,”exists”); else print(“the file “,f,”does not exist”);

d = new Date().getTime() - f.lastModified.getTime();

d.setDate(d.getDate()-1);

if(f.lastModified>=d) print(“file modified in the last 24 hours);

files = myRoot.files();

for(k in files) print(files[k]); // print all files in myRoot

Image

contiene una imagen, los tipos soportados son: tlv, pli y fullcolor.

Constructor:

  • new Image() o new Image(nombredearchivo)

Métodos:

  • img.save(nombredearchivo) - la extensión del archivo tiene que ser compatible con el tipo de nivel usado
  • img.load(nombredearchivo)

Atributos:

  • img.width - tendrá valor 0 si la imagen es de tipo pli
  • img.height - tendrá valor 0 si la imagen es de tipo pli
  • img.dpi - tendrá valor 0 si la imagen es de tipo pli
  • img.type - valores aceptados (“Empty”, “Raster”, “ToonzRaster”, “Vector”)

Ejemplos:

img = new Image(“C:/images/basename.0003.tif”);

view(img);

print(img.width,img.height,img.dpi);

img = new Image(“C:/images/name.pli”); // reads only the first frame.

view(img);

img.save(“C:/images/name.pli”);

Level

contiene un nivel, los tipos soportados son: tlv, pli y fullcolor.

Constructor:

  • new Level() o new Level(nombredearchivo)

Métodos:

  • level.load(nombredearchivo)
  • level.save(nombredearchivo) - la extensión del archivo tiene que ser compatible con el tipo de nivel usado
  • level.getFrameIds() - lista los nombres de todos los fotogramas
  • level.getFrame(IDfotograma) - recupera la imagen del fotograma especificado
  • level.getFrameByIndex(índice) - obtiene el fotograma especificado por el valor índice (el primer valor de índice es 0)
  • level.setFrame(IDfotograma, imagen) - define un fotograma (si el nivel no se encuentra vacío, su contenido y el tipo de imagen deben ser compatibles)

Atributos:

  • level.name - atributo de lectura y escritura
  • level.path - atributo de lectura y escritura
  • level.frameCount - atributo de sólo lectura
  • level.type (“Empty”, ”Raster”, ”ToonzRaster”, ”Vector”) - atributo de sólo lectura

Ejemplos:

// This example produces a "renumber"

inputLevel= new Image(“C:/images/name.pli”);

outputLevel = new Level();

for(i=0;i<inputLevel.frameCount;i++)
{
    outputLevel.setFrame(i+1, inputLevel.getFrameByIndex(i));

    outputLevel.save(“C:/images/name.pli”);
}

// instead this keeps the sequence of frames, but reverses the order

outputLevel = new Level();

fids = inputLevel.getFrameIds();

for(i=0;i<fids.length;i++)
{
    img = inputLevel.getFrame(fids[fids.length-1-i]);
    outputLevel.setFrame(fids[i], img);
}

view(outputLevel);

Scene

contiene una escena de OpenToonz.

Constructor:

  • new Scene() o new Scene(nombredearchivo)

Métodos:

  • scene.load(nombredearchivo)

Nota

Si la ruta es relativa, se usarán escenas del proyecto actual.

  • scene.save(nombredearchivo)
  • scene.setCel(fila, columna, celda) , scene.setCell(fila, columna, nivel, IDfotograma)

Nota

celda es la clase de objeto devuelto por getCell() .

  • La siguiente sintaxis es permitida scene.setCell(1, 0, scene.getCell(0,0))
  • Para borrar una celda: scene.setCell(fila, columna, nodefinido)
  • celda es un objeto estándar de JavaScript que incluye los atributos:nivel y idf , se permite el siguiente uso: scene.setCell(fila, columna, {nivel:a, idf:1})
  • nivel puede ser tanto Level como el nombre de un nivel. El nivel ya tiene que existir en la escena.
  • idf soporta valores numéricos o cadenas como “2” o “2a”.
  • celda = scene.getCell(fila, columna) - devuelve un objeto de JavaScript con los atributos nivel e idf
  • scene.insertColumn(columna)
  • scene.deleteColumn(columna)
  • scene.getLevels() - devuelve un array que contiene todos los niveles pertenecientes a la escena
  • scene.getLevel(nombre) - devuelve un nivel basándose en su nombre. Si no existiera un nivel con el nombre especificado el valor undefined será devuelto.
  • nivel = scene.newLevel(tpo, nombre) - Agrega una capa a la escena. Tipo puede ser «Raster», «ToonzRaster» o «Vector». El nombre no debe estar ya en uso en la escena.
  • level = scene.loadLevel(nombre, ruta) - Carga un nivel (en modo “«enlace») a la escena. La ruta debe existir y ser absoluta. El nombre no debe estar siendo usado por ningún otro nivel de la escena.

Atributos:

  • scene.frameCount - valor de sólo lectura
  • scene.columnCount - valor de sólo lectura

Ejemplos:

filename = “test.tnz”; // relative to “+scenes”

scene = new Scene(filename);

print(scene.frameCount, scene.columnCount);

// Move the cells of the first column on the first frame of the other columns.

for(r=1;r<scene.frameCount;r++)
{
    scene.setCell(0,r, scene.getCell(r,0));

    scene.setCell(r,0,undefined); // delete the old cell.
}

scene.save(“name.tnz”);

//Create a new scene.

scene = new Scene();

level = scene.load(“A”,”C:/levels/name.pli”);

fids = level.getFrameIds();

for(i=0;i<fids.length;i++) scene.setCell(i,0,level,fids[i]);

scene.save(“name.tnz”);

// writes name, path and number of frames of each level in the scene.

scene = new Scene(“name.tnz”);

levels = scene.getLevels();

for(i=0;i<levels.length;i++)
{
    level = levels[i];

    print(level.name, level.path, level.frameCount);
}

Transform

representa una transformación geométrica (compuesta por rotación, traslación y escala). Usada por ImageBuilder.

Constructor:

  • new Transform()

Métodos:

  • transform.translate(dx, dy)
  • transform.rotate(grados)

Nota

Valores positivos corresponden a una rotación en sentido antihorario.

  • transform.scale(e)
  • transform.scale(ex, ey)

Ejemplos:

transform = new Transform().rotate(45).translate(10,2);

print(transform);

ImageBuilder

permite modificar una imagen (rotarla, escalarla, recortarla) o componer una o más imágenes sobre otras.

Constructor:

  • new ImageBuilder() o new ImageBuilder(resx, resy)

Métodos:

  • builder.add(imagen)
  • builder.add(imagen, transformación)

Nota

El componente de traslación de la transformación se encuentra expresado en píxeles para niveles de Imagen de Toonz o Imagen, y en unidades de cámara para niveles Vectorial de Toonz.

  • builder.fill(color)

Atributos:

  • builder.image - devuelve el resultado actual.

Ejemplos:

ib = new ImageBuilder(800,800);

img = new Image(“C:/levels/name.0001.tif”);

scale = 1;

phi = 0;

for(i=0;i<20;i++)
{
    tr = new Transform().scale(scale).translate(0,-200).rotate(phi);

    ib.add(img, tr);

    phi -= scale*30;

    scale *= 0.9;
}

view(ib.image);

OutlineVectorizer

vectoriza imágenes usando el algoritmo de contornos.

Constructor:

  • new OutlineVectorizer()

Métodos:

  • v.vectorize(nivel o imagen) - devuelve el nuevo nivel vectorizado, soporta como entrada: niveles de Imagen de Toonz o Imagen.

Atributos:

  • v.accuracy
  • v.despeckling
  • v.preservePaintedAreas
  • v.cornerAdherence
  • v.cornerAngle
  • v.cornerCurveRadius
  • v.maxColors
  • v.transparentColor
  • v.toneThreshold

Ejemplos:

v = new OutlineVectorizer();

v.preservePaintedAreas = true;

a = new Image("C:/Users/username/name.tif");

b = v.vectorize(a);

view(b);

CenterlineVectorizer

vectoriza imágenes usando el algoritmo de líneas.

Constructor:

  • new CenterlineVectorizer()

Métodos:

  • v.vectorize(nivel o imagen) - devuelve el nuevo nivel vectorizado, soporta como entrada: niveles de Imagen de Toonz o Imagen.

Atributos:

  • v.threshold
  • v.accuracy
  • v.despeckling
  • v.maxThickness
  • v.thicknessCalibration
  • v.preservePaintedAreas
  • v.addBorder

Ejemplos:

v = new OutlineVectorizer();

v.preservePaintedAreas = true;

a = new Image("C:/Users/username/name.tif");

b = v.vectorize(a);

view(b);

Rasterizer

convierte imágenes vectoriales en Imágenes de Toonz o Imágenes.

Constructor:

  • new Rasterizer()

Métodos:

  • out = r.rasterize(imagenvect) - convierte en imagen un nivel vectorial

Atributos:

  • r.colorMapped - si su valor está definido como True la imagen generada será de tipo Imagen de Toonz
  • r.xres
  • r.yres
  • r.dpi

Ejemplos:

a = new Level("C:\\Users\\username\\PLI\\name.pli");

r= new Rasterizer();

r.xres=768; r.yres=576; r.dpi=40;

b = r.rasterize(a);

b.save(“C:\\Users\\username\\PLI\\name.tif”);

r.colorMapped = true

c = r.rasterize(new Level("C:\\Users\\username\\PLI\\name.pli"))

c.save(“C:\\Users\\username\\PLI\\bimba.tlv”);

Renderer

procesa una escena completa o una parte de ella, creando niveles o imágenes.

Constructor:

  • new Renderer()

Métodos:

  • level = c.renderScene(escena)
  • image = c.renderFrame(escena, IDfotograma)

Nota

IDfotograma comienza desde 0

Atributos:

  • r.columns (lista de índices de las columnas a procesar. p.ej: r.columns = [0,3])
  • r.frames (lista de índices de los fotogramas a procesar. p.ej: r.frames = [0,1,2,3])

Ejemplos:

scene = new Scene("testscene.tnz”);

r= new Rasterizer();

view(r.renderScene(scene ,0));

r.columns = [0,2];

view(r.renderScene(a,0)); // frame 1; columns 1 and 3

r.frames = [0,2,4,6];

output = r.renderScene(scene ); // frames 1,3,5,7; columns 1 and 3

output.save(“C:\\Users\\username\\output\\name..tif”);

r.columns = [];

output = r.renderScene(scene ); // frames 1,3,5,7; all columns

output.save(““C:\\Users\\username\\output\\name..tif””);

Ejemplos de código

A continuación se presentan algunos ejemplos de código de scripts:

Vectorización de contornos

Este breve script es un ejemplo de cómo usar OutlineVectorizer en una única imagen. El script se encuentra comentado, explicando lo que hace cada sección:

//Define the input and output folders

dir = "C:\\OpenToonz stuff\\SCRIPT IMAGES IN\\";

dir2 = "C:\\OpenToonz stuff\\SCRIPT IMAGES OUT\\";


//Load image toad3.0001.tif from disk

a = new Image(dir+"toad3.0001.tif");

print("loaded",a);


//Initialize a vectorizer and specify any relevant options

v = new OutlineVectorizer();

v.maxThickness = 1;

v.preservePaintedAreas = false;

v.accuracy = 10;

v.maxColors = 10;


//Run the vectorization process and save the result

v.vectorize(a).save(dir2 + "vec.pli");

print("vectorized");

Rotación de una imagen

Este ejemplo explica cómo cargar una imagen y luego crear una animación en un nivel, rotando dicha imagen:

\\Define the input and output folders

dir = "C:\\OpenToonz stuff\\SCRIPT IMAGES IN\\";

dir2 = "C:\\OpenToonz stuff\\SCRIPT IMAGES OUT\\";


//Load the toad3.tif image

a = new Level(dir+"toad3..tif");

print("loaded\n",a);


//Initialization of the new objects and creation of a list containing the IDs of all the frames

t = new Transform();

b=new Level();

ll=a.getFrameIds();


//For loop that builds the new level. At each step a new frame is added to the level b using the
setFrame method that adds the myimage frame rotated of a step degrees value using the ib ImageBuilder

for(i=0; i<a.frameCount;i++)
{
    ib = new ImageBuilder();

    step=360/a.frameCount;

    myimage=a.getFrame(ll[i]);

    b.setFrame(ll[i], ib.add(myimage, t.rotate(step)).image);

    print("building frame " + ll[i] + "\n");
}


//Save the result prompting a status message

b.save(dir2+"rottoad3..tif")

print("saved\n",b);


//Shows the resulting level in a flipbook window

view(b);