Tahoma2D

https://github.com/tahoma2d/tahoma2d_docs
Admin
Tahoma2D is an open-source full-featured 2D animation creation software for designing and producing...
Tokens:93,451
Snippets:878
Trust Score:6.9
Update:9 months ago
Show doc for...
Tokens:
Raw
### Example File Data for Interpolation

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/editing_curves_and_numerical_columns.md

This example demonstrates the expected format for a file used in file-based interpolations. The file should contain a series of numbers, potentially on multiple lines. If lines have multiple values, a column number can specify which value to use.

```data
100, 200, 300
101, 201, 301
102, 202, 302
```

--------------------------------

### Start Toonz Farm Server from DOS

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/using_the_toonz_farm.md

This command starts the Toonz Farm server from a DOS shell. It requires navigating to the directory where the Tahoma binaries are installed. No specific inputs are mentioned, and the output is the server running in the console.

```shell
tfarmserver -console
```

--------------------------------

### Install Sphinx and Related Packages (Bash)

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/CONTRIBUTING.md

Installs Sphinx, an automatic documentation generator, along with sphinx-autobuild for live preview and sphinx-intl for internationalization. This is a prerequisite for building and contributing to the Tahoma2D documentation.

```bash
# Install Sphinx and sphinx-autobuild
pip install sphinx sphinx-autobuild

# Install sphinx_rtd_theme theme
pip install sphinx_rtd_theme

# Install internationalization(i18n) package
pip install sphinx-intl
```

--------------------------------

### Build Documentation Locally with Sphinx

Source: https://context7.com/tahoma2d/tahoma2d_docs/llms.txt

Instructions to build the Sphinx documentation locally, generating HTML output. Requires Python and pip for installing dependencies like Sphinx and the Read the Docs theme.

```bash
# Install dependencies
pip install sphinx sphinx-autobuild
pip install sphinx_rtd_theme

# Build HTML documentation
cd /path/to/tahoma2d_docs
make html

# Output will be in build/html/index.html
```

--------------------------------

### Build HTML Documentation (Bash)

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/CONTRIBUTING.md

Generates the HTML version of the Tahoma2D documentation locally. This command should be run from within the root directory of the cloned repository after installing the necessary Python packages and Sphinx.

```bash
# Ensure you are in the tahoma2d_docs folder
# cd tahoma2d_docs

# Build the HTML documentation
make html
```

--------------------------------

### Outline Vectorization Example

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

Demonstrates outline vectorization on a single image. It includes steps for defining directories, loading an image, initializing the vectorizer with specific options (maxThickness, preservePaintedAreas, accuracy, maxColors), and saving the vectorized result.

```default
//Define the input and output folders

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

dir2 = "C:\\Tahoma 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");
```

--------------------------------

### ToonzScript File Management Example

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/index.md

Demonstrates basic file management operations within ToonzScript. This functionality is crucial for organizing and accessing project assets programmatically. It typically involves functions for creating, deleting, copying, and moving files and directories. No external dependencies are usually required for these core operations.

```ToonzScript
// Example: Create a new directory
folder.create("new_folder");

// Example: Copy a file
file.copy("source.txt", "destination.txt");

// Example: Delete a file
file.delete("old_file.txt");
```

--------------------------------

### Scene Management API

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

APIs for managing scenes, including setting and getting cells, manipulating columns, and handling levels.

```APIDOC
## Scene Management API

### Description
Provides methods for interacting with and manipulating scenes in Tahoma2D. This includes cell-level operations, column adjustments, and level management.

### Methods

- **`scene.setCell(row, col, cellObject)`**: Sets a cell at the specified row and column. `cellObject` can be `undefined` to delete the cell, or a JavaScript object with `level` and `fid` attributes.
- **`scene.getCell(row, col)`**: Returns a JavaScript object representing the cell at the specified row and column. The object contains `level` and `fid` attributes.
- **`scene.insertColumn(col)`**: Inserts a new column at the specified index.
- **`scene.deleteColumn(col)`**: Deletes the column at the specified index.
- **`scene.getLevels()`**: Returns an array containing all levels belonging to the scene.
- **`scene.getLevel(name)`**: Returns the level object with the specified name. Returns `undefined` if no level with that name exists.
- **`scene.newLevel(type, name)`**: Adds a new level to the scene. `type` can be 'Raster', 'ToonzRaster', or 'Vector'. `name` must be unique within the scene.
- **`scene.loadLevel(name, path)`**: Loads a level into the scene from the specified absolute `path`. The `name` must be unique. This is used for linking levels.

### Attributes

- **`scene.frameCount`**: (Read-only) The total number of frames in the scene.
- **`scene.columnCount`**: (Read-only) The total number of columns in the scene.

### Examples

```javascript
// Load a scene and manipulate cells
let filename = "test.tnz"; // relative to "+scenes"
let scene = new Scene(filename);

print(scene.frameCount, scene.columnCount);

// Move cells from column 0 to other columns
for(let 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 and load a level
scene = new Scene();
let level = scene.load("A", "C:/levels/name.pli");
let fids = level.getFrameIds();
for(let i=0; i<fids.length; i++) scene.setCell(i, 0, level, fids[i]);
scene.save("name.tnz");

// Write details of each level in the scene
scene = new Scene("name.tnz");
let levels = scene.getLevels();
for(let i=0; i<levels.length; i++) {
    let lvl = levels[i];
    print(lvl.name, lvl.path, lvl.frameCount);
}
```
```

--------------------------------

### ToonzScript Mathematical Expressions Example

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/index.md

Shows how to use mathematical expressions within ToonzScript, particularly for animation and parameter control. This enables dynamic and procedural animation by defining relationships between different animation parameters. These expressions can be used in various contexts, such as defining curve values or controlling effect properties.

```ToonzScript
// Example: Define a simple animation curve
var curve = anim.getCurve("my_animation");
curve.setKeyframe(0, 10);
curve.setKeyframe(100, 50);

// Example: Using expressions for parameter control (conceptual)
// var positionX = "sin(frame * 0.1) * 50";
// anim.setParameter("object.x", positionX);
```

--------------------------------

### Translating Strings in .po Files

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/CONTRIBUTING.md

This example shows how to translate a string within a .po file. The 'msgid' is the original string, and 'msgstr' is where the translation should be entered. It's crucial to maintain the reStructuredText syntax in the translated text.

```po
msgid "Tahoma2D User Manual"
msgstr "Tahoma2D ユーザマニュアル"
```

--------------------------------

### ToonzScript Script Console Usage Example

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/index.md

Illustrates how to interact with the ToonzScript environment through its console. The script console allows for interactive execution of ToonzScript commands and debugging. It's essential for testing small script snippets and understanding the immediate effect of commands. Users can typically run single lines or blocks of code.

```ToonzScript
// Example: Print a message to the console
println("Hello, ToonzScript!");

// Example: Get the current scene name
var sceneName = project.currentScene();
println("Current scene: " + sceneName);
```

--------------------------------

### Render Scene or Frame

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

Renders a whole scene or a specific frame of a scene, creating new levels or images. Supports specifying which columns and frames to render. The frameIndex starts from 0.

```default
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"”);
```

--------------------------------

### File Path Conventions in ToonzScript Console

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

When entering file paths in the ToonzScript console, backslashes must be doubled. For example, `C:\tmp\test.jpg` should be entered as `C:\\tmp\\test.jpg`. Slashes can also be used interchangeably with backslashes.

```default
C:\\tmp\\test.jpg
```

```default
C:/tmp/test.jpg
```

--------------------------------

### Rotate Column to Face Another (Expression)

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/example_expressions.md

This expression calculates the angle needed to rotate column 1 (col1) to face column 2 (col2). It uses the atan2 function with the difference in north-south (ns) and east-west (ew) coordinates. This is useful for orienting objects or sprites towards a target.

```Expression
atan2(col2.ns - col1.ns, col2.ew - col1.ew)
```

--------------------------------

### ToonzScript: Mathematical Expressions for Animation

Source: https://context7.com/tahoma2d/tahoma2d_docs/llms.txt

Example of using mathematical expressions within Tahoma2D's Function Editor to create procedural animation. This specific expression rotates one column to face another by calculating the angle between them.

```javascript
// Aim At Expression: Rotate column 1 to face column 2
atan2(col2.ns - col1.ns, col2.ew - col1.ew)

// Usage in Tahoma:
// 1. Open Function Editor
// 2. Select rotation parameter of col1
// 3. Enter expression above
// 4. col1 will automatically rotate to point at col2
```

--------------------------------

### Resolve Merge Conflicts (Bash)

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/CONTRIBUTING.md

Guides through the process of resolving merge conflicts that may arise when pulling updates from the upstream repository. It involves identifying conflicted files, manually editing them to resolve differences, staging the resolved files, and then committing the merge.

```bash
# Pull the latest changes, potentially causing conflicts
git pull upstream master

# Or use rebase for a cleaner history
# git pull --rebase upstream master

# List conflicted files
git status

# Manually edit conflicted files (e.g., path/to/conflicted/file.rst)
# Resolve the <<<<<<< HEAD, =======, >>>>>>> markers

# Stage the resolved files
git add path/to/conflicted/file.rst

# Commit the resolved merge
git commit
```

--------------------------------

### Renderer: Scene and Frame Rendering in ToonzScript

Source: https://context7.com/tahoma2d/tahoma2d_docs/llms.txt

The Renderer class is used to render scenes or specific frames within a ToonzScript environment. It allows rendering the entire scene, specific columns, or selected frames. The output can be viewed directly or saved to a file. Frame indices start from 0.

```javascript
scene = new Scene("testscene.tnz");
r = new Renderer();

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

r.columns = [0, 2];
view(r.renderScene(scene, 0));

r.frames = [0, 2, 4, 6];
output = r.renderScene(scene);
output.save("C:\\Users\\username\\output\\name..tif");

r.columns = [];
r.frames = [0, 2, 4, 6];
output = r.renderScene(scene);
output.save("C:\\Users\\username\\output\\sequence..tif");

image = r.renderFrame(scene, 0);
image.save("C:/output/frame_001.tif");
```

--------------------------------

### Building Translated HTML Locally (Windows Batch)

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/CONTRIBUTING.md

This command sequence builds the HTML documentation locally on Windows, including translations. It first sets the SPHINXOPTS environment variable to specify the target language and then runs the make html command.

```batch
set SPHINXOPTS=-D language=ja
$ make.bat html
```

--------------------------------

### Using Mathematical Expressions for Vertex Linking in Plastic Animation

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/create_animations_using_plastic_tool.md

Demonstrates how to use mathematical expressions in the Function Editor to link vertex parameters, allowing for automatic adjustments and synchronized movements between vertices or other animation elements. This enables creating complex animations with less manual keyframing. The syntax allows referencing vertex angles and distances by their column number and name.

```tahoma2d
vertex(2, "Shoulder_right").angle
```

```tahoma2d
vertex(2, "Shoulder_right").angle*-1
```

--------------------------------

### Building Translated HTML Locally (Linux/macOS)

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/CONTRIBUTING.md

This command builds the HTML documentation locally, incorporating translations for a specific language (e.g., 'ja'). The SPHINXOPTS environment variable is used to set the language for the Sphinx build process.

```bash
$ make SPHINXOPTS="-D language='ja'" html
```

--------------------------------

### Configure Version Control Repositories (XML)

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/using_the_version_control.md

Defines the structure for configuring version control repositories in Tahoma. It specifies the central repository path and the local working copy path. Ensure the XML is well-formed.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Repositories>
    <!-- REMOVE ENTIRELY THIS LINE TO ENABLE SVN 
<repository>
    <name>PutYourRepositoryName</name>
    <localPath>putYourWorkingCopyPath</localPath>
    <repoPath>putYourRepositoryPath</repoPath>
</repository>
REMOVE ENTIRELY THIS LINE TO ENABLE SVN -->
    <svnPath></svnPath>
</Repositories>
```

--------------------------------

### Define Controller Node in controller.txt

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/using_the_toonz_farm.md

This configuration file defines the controller node for the Toonz Farm. It requires the computer name, IP address, and the port number for the controller service, separated by spaces. Ensure the specified port is not blocked by firewalls.

```default
render1 10.10.0.130 10000
```

--------------------------------

### ToonzScript: Running Scripts

Source: https://context7.com/tahoma2d/tahoma2d_docs/llms.txt

Demonstrates how to execute ToonzScript files using the `run` command. Scripts can be run from the library folder or specified with an absolute path. This is useful for automating tasks or chaining script operations.

```javascript
// Run script from library folder
run("test.js");

// Run script from absolute path
run("C:\\Users\\Username\\Tests\\another_test.js");

// Combine with view command
run("vectorize_batch.js");
result = new Level("C:/output/result.pli");
view(result);
```

--------------------------------

### Clone Tahoma2D Docs Repository (Bash)

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/CONTRIBUTING.md

Clones the Tahoma2D documentation repository from GitHub to your local machine. This involves forking the repository, cloning it using Git, and setting up the 'upstream' remote to track the original repository for updates.

```bash
# Navigate to the desired parent folder
cd C:/path/to/the/parent/folder

# Clone the repository from your GitHub account
git clone https://github.com/your_github_account_name/tahoma2d_docs.git

# Move into the cloned repository
cd tahoma2d_docs

# Add the original repository as an upstream remote
git remote add upstream https://github.com/tahoma2d/tahoma2d_docs.git
```

--------------------------------

### Contributing to Documentation: Git Workflow

Source: https://context7.com/tahoma2d/tahoma2d_docs/llms.txt

Instructions for contributing to the Tahoma2D documentation repository using Git. This includes forking, cloning, setting up remotes, creating branches, committing changes, and pushing for a pull request.

```bash
# Fork repository on GitHub first, then clone
git clone https://github.com/your_github_account_name/tahoma2d_docs.git
cd tahoma2d_docs

# Set upstream remote
git remote add upstream https://github.com/tahoma2d/tahoma2d_docs.git

# Create feature branch
git checkout -b feature/my-documentation-update

# Make changes, then commit
git add source/my_changes.md
git commit -m "Add documentation for new feature"

# Push and create pull request
git push origin feature/my-documentation-update
```

--------------------------------

### VSCode Settings for reStructuredText

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/CONTRIBUTING.md

This JSON configuration file for VSCode sets up the esbonio extension for Sphinx, specifying build and configuration directories. It also disables certain linters to prevent unnecessary warnings during development.

```json
{
    "esbonio.sphinx.buildDir": "..\\build",
    "esbonio.sphinx.confDir": "",
    "restructuredtext.linter.disabledLinters": [
        "doc8",
        "rstcheck",
        "rst-lint"
    ]
}
```

--------------------------------

### Project Configuration: Sphinx conf.py

Source: https://context7.com/tahoma2d/tahoma2d_docs/llms.txt

Sphinx configuration file for the Tahoma2D project. It defines project metadata, copyright information, version details, and specifies extensions, HTML theme, and theme options for generating the documentation.

```python
# source/conf.py
project = u'Tahoma'
copyright = u': This page is licensed under a CC-BY-NC 4.0 Int. License'
author = u'Tahoma and OpenToonz Team'
version = u'1.5'
release = u'1.5'

extensions = ['sphinx_rtd_theme']
html_theme = 'sphinx_rtd_theme'
html_logo = "_static/logo.png"
html_favicon = "_static/tahoma.ico"

html_theme_options = {
    'logo_only': True,
}
```

--------------------------------

### Push Branch and Create Pull Request (Bash)

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/CONTRIBUTING.md

Pushes your local feature branch containing your changes to your GitHub fork and then instructs on how to create a pull request through the GitHub interface to merge your changes into the main project.

```bash
# Push your local branch to your GitHub fork
git push origin your-branch-name

# Access https://github.com/tahoma2d/tahoma2d_docs and click the 'Pull Request' button.
```

--------------------------------

### Configure Toonz Farm Server Nodes

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/using_the_toonz_farm.md

Defines the server nodes for the Toonz Farm. Each line specifies a server name, its IP address, and the port number it listens on. Ensure the specified port is not blocked by firewalls and is accessible by all Toonz Farm computers. Changes to this file require restarting the controller node to take effect.

```default
render1 10.10.0.166 8002
render2 10.10.0.195 8002
render3 10.10.0.111 8002
render4 10.10.0.180 8002
```

--------------------------------

### Running Scripts in ToonzScript

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

The `run` command executes another ToonzScript file. Relative paths are resolved from the '<tahoma library>/scripts/' folder. This allows for modular script organization.

```default
run("test.js")
```

```default
run("C:\\Users\\Username\\Tests\\another_test.js")
```

--------------------------------

### Reference Plastic Vertex Transformation in Expressions

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/editing_curves_and_numerical_columns.md

This syntax allows referencing a Plastic vertex transformation within mathematical expressions. It requires the column number and vertex name, optionally with a transformation and a delta value for frame differences. Ensure effect parameter names have no spaces.

```expression
vertex(column_number, "vertex_name").transformation
vertex(column_number, "vertex_name").transformation(delta)
```

--------------------------------

### ToonzScript: Scene Manipulation for Animation Projects

Source: https://context7.com/tahoma2d/tahoma2d_docs/llms.txt

Demonstrates scene manipulation using ToonzScript for creating and modifying animation scenes. Covers loading existing scenes, moving cells between columns and frames, creating new scenes, and listing scene levels with their properties.

```javascript
// Load existing scene (relative to "+scenes" project folder)
filename = "test.tnz";
scene = new Scene(filename);
print(scene.frameCount, scene.columnCount);
// Output: 100 5

// Move cells from first column to first frame of other columns
for(r=1; r<scene.frameCount; r++) {
    scene.setCell(0, r, scene.getCell(r, 0));
    scene.setCell(r, 0, undefined); // delete old cell
}
scene.save("modified.tnz");

// Create new scene and populate with level
scene = new Scene();
level = scene.loadLevel("A", "C:/levels/name.pli");
fids = level.getFrameIds();

for(i=0; i<fids.length; i++) {
    scene.setCell(i, 0, level, fids[i]);
}
scene.save("new_scene.tnz");

// List all levels in scene with properties
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);
}
```

--------------------------------

### Create and Commit Changes to a New Branch (Bash)

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/CONTRIBUTING.md

Creates a new branch for your modifications, allows you to edit files, and then commits those changes with a descriptive message. This is part of the standard Git workflow for contributing code or documentation.

```bash
# Create and checkout a new branch for your changes
git checkout -b your-branch-name

# (Modify files here...)

# Stage all modified files for commit
git add .

# Commit the staged changes with a message
git commit -m "Your descriptive commit message"

# Alternatively, to commit all modified files directly:
git commit -a -m "Your descriptive commit message"
```

--------------------------------

### ToonzScript: Print Command for Debugging

Source: https://context7.com/tahoma2d/tahoma2d_docs/llms.txt

Demonstrates the use of the 'print' command in ToonzScript to output messages to the Script Console. Useful for debugging and monitoring script execution by displaying variable values and execution status.

```javascript
// Basic printing
print("result=", 12*3);
// Output: result=36

// Print multiple variables
var width = 1920;
var height = 1080;
var fps = 24;
print("Resolution:", width, "x", height, "at", fps, "fps");
// Output: Resolution: 1920 x 1080 at 24 fps

// Check Tahoma version
print("Running Tahoma version:", ToonzVersion);
```

--------------------------------

### Project Configuration: .readthedocs.yaml

Source: https://context7.com/tahoma2d/tahoma2d_docs/llms.txt

Configuration file for Read the Docs to set up the build environment for the project. It specifies the operating system, Python version, and tools to be used during the documentation build process.

```yaml
# .readthedocs.yaml
version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"

sphinx:
  configuration: source/conf.py

python:
  install:
  - requirements: requirements.txt
```

--------------------------------

### Reference Object Transformation

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/editing_curves_and_numerical_columns.md

Enables referencing transformations of objects (cameras, columns, pegbars, table) within expressions. This allows creating relationships between different transformations.

```expression
object.transformation
object.transformation(delta)
```

--------------------------------

### Viewing Levels in ToonzScript

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

The `view` command can also be used to display a level file. This is done by creating a `Level` object with the path to the level file.

```default
view(new Level("C:\\Tahoma stuff\\sandbox\\drawings\\A.pli"))
```

--------------------------------

### Generating Message Catalog (.pot)

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/CONTRIBUTING.md

This command generates a message catalog (.pot file) from the reStructuredText source files. This file is essential for internationalization as it contains all translatable strings. It is typically run from the project's root directory.

```bash
$ make gettext
```

--------------------------------

### OutlineVectorizer API

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

API for vectorizing raster images using an outline algorithm.

```APIDOC
## OutlineVectorizer API

### Description
Vectorizes raster images using an outline algorithm. This tool is useful for converting scanned drawings or bitmap images into scalable vector graphics.

### Constructor

- **`new OutlineVectorizer()`**: Creates a new instance of the OutlineVectorizer.

### Methods

- **`v.vectorize(level or image)`**: Vectorizes the input `level` or `image`. Supports Raster or Smart Raster images and levels as input. Returns the new vectorized level or image.

### Attributes

- **`v.accuracy`**: Controls the accuracy of the vectorization.
- **`v.despeckling`**: Enables or disables despeckling to remove small noise artifacts.
- **`v.preservePaintedAreas`**: If true, attempts to preserve areas that are already painted.
- **`v.cornerAdherence`**: Controls how sharp corners are handled during vectorization.
- **`v.cornerCurveRadius`**: Specifies the radius for corner smoothing.
- **`v.maxColors`**: Sets the maximum number of colors to use in the vectorized output.
- **`v.transparentColor`**: Defines the color to be treated as transparent.
- **`v.toneThreshold`**: Threshold for tone detection during vectorization.

### Examples

```javascript
// Vectorize a raster image with specific settings
let v = new OutlineVectorizer();
v.preservePaintedAreas = true;
let a = new Image("C:/Users/username/name.tif");
let b = v.vectorize(a);
view(b);
```
```

--------------------------------

### Synchronize Local Repository with Upstream (Bash)

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/CONTRIBUTING.md

Updates your local repository with the latest changes from the 'tahoma2d/tahoma2d_docs' repository. This involves checking out the master branch, pulling changes from upstream, and then pushing these updates to your GitHub fork.

```bash
# Ensure you are in the tahoma2d_docs folder

# Change to the master branch
git checkout master

# Pull the latest changes from the upstream repository
git pull upstream master

# Push the synchronized changes to your fork on GitHub
git push origin master
```

--------------------------------

### ToonzScript: Level Class for Animation Sequences

Source: https://context7.com/tahoma2d/tahoma2d_docs/llms.txt

Explains the Level class in ToonzScript for managing animation levels, which consist of multiple frames. Shows how to renumber frames, reverse their order, and access level properties like name, path, and frame count.

```javascript
// Renumber frames in a level
inputLevel = new Level("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/renumbered.pli");

// Reverse frame order while keeping frame IDs
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);

// Access level properties
print(outputLevel.name);        // Level name
print(outputLevel.path);        // File path
print(outputLevel.frameCount);  // Number of frames
print(outputLevel.type);        // "Empty", "Raster", "ToonzRaster", "Vector"
```

--------------------------------

### Rotate Image and Create Animation Level

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

Loads an image and creates an animation level by rotating each frame. It uses Transform and ImageBuilder to apply rotation and set frames in a new level. The final animated level is saved and displayed.

```default
\\Define the input and output folders

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

dir2 = "C:\\Tahoma 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 panel

view(b);
```

--------------------------------

### Viewing Images in ToonzScript

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

The `view` command with an `Image` object allows displaying an image file within Tahoma. It requires creating an `Image` object with the file path.

```default
view(new Image(filename))
```

--------------------------------

### ImageBuilder Class: Composing Images and Filling Backgrounds

Source: https://context7.com/tahoma2d/tahoma2d_docs/llms.txt

The ImageBuilder class enables the composition of multiple images with transformations. It can also be used to fill the background with a specified color. Images are added with or without transformations, defaulting to the origin if no transform is provided.

```javascript
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);

ib2 = new ImageBuilder(1920, 1080);
ib2.fill("#FF0000");

ib3 = new ImageBuilder();
ib3.add(img);
```

--------------------------------

### Generate Wave Curve

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/editing_curves_and_numerical_columns.md

Generates a wave curve, equivalent to sin(f * 2 * pi / length). This function implicitly uses a frame-independent variable.

```mathematical
wave(length)
```

--------------------------------

### ToonzScript: FilePath Class for File Operations

Source: https://context7.com/tahoma2d/tahoma2d_docs/llms.txt

Utilizes the FilePath class in ToonzScript for cross-platform file path management and operations. Allows creating, manipulating, and inspecting file paths, checking existence, and listing directory contents.

```javascript
// Create and manipulate file paths
myRoot = new FilePath("C:\\Users\\username\\");
f = myRoot.concat("tests").concat("name.0001.tif");

// Access path properties
print(f.extension);        // => "tif"
print(f.name);            // => "name"
print(f.parentDirectory);  // => "C:\\Users\\username\\tests"

// Check file existence
if(f.exists) {
    print("the file", f, "exists");
} else {
    print("the file", f, "does not exist");
}

// Check last modified time
d = new Date().getTime() - f.lastModified.getTime();
d.setDate(d.getDate()-1);
if(f.lastModified >= d) {
    print("file modified in the last 24 hours");
}

// List all files in directory
files = myRoot.files();
for(k in files) {
    print(files[k]);
}
```

--------------------------------

### ToonzScript: Image Class for Frame Manipulation

Source: https://context7.com/tahoma2d/tahoma2d_docs/llms.txt

Demonstrates the Image class in ToonzScript for loading, viewing, and saving individual image frames. Supports both raster and vector image formats and provides access to image properties like dimensions and DPI.

```javascript
// Load and view a raster image
img = new Image("C:/images/basename.0003.tif");
view(img);
print(img.width, img.height, img.dpi);
// Output: 1920 1080 72

// Load vector image (PLI format reads first frame)
img = new Image("C:/images/name.pli");
view(img);

// Save image
img.save("C:/images/output.pli");

// Check image type
print(img.type);
// Output: "Empty", "Raster", "ToonzRaster", or "Vector"
```

--------------------------------

### Transform API

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

API for creating and manipulating geometric transformations (translation, rotation, scale).

```APIDOC
## Transform API

### Description
Represents a geometric transformation composed of rotation, translation, and scale. Used primarily by the `ImageBuilder`.

### Constructor

- **`new Transform()`**: Creates a new Transform object with default values.

### Methods

- **`transform.translate(dx, dy)`**: Applies a translation to the transform. `dx` is the horizontal shift, `dy` is the vertical shift.
- **`transform.rotate(degrees)`**: Applies a rotation to the transform in degrees. Positive values correspond to counterclockwise rotation.
- **`transform.scale(s)`**: Applies a uniform scale to the transform.
- **`transform.scale(sx, sy)`**: Applies non-uniform scaling to the transform, with `sx` for horizontal scale and `sy` for vertical scale.

### Examples

```javascript
// Create a transform with rotation and translation
let transform = new Transform().rotate(45).translate(10, 2);
print(transform);
```
```

--------------------------------

### ImageBuilder API

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

API for modifying images and creating compositions of images.

```APIDOC
## ImageBuilder API

### Description
Allows modification of images (rotate, scale, crop) or creating compositions (over) between multiple images.

### Constructor

- **`new ImageBuilder()`**: Creates a new ImageBuilder with default resolution.
- **`new ImageBuilder(xres, yres)`**: Creates a new ImageBuilder with specified X and Y resolution.

### Methods

- **`builder.add(img)`**: Adds an image to the builder without a specific transform.
- **`builder.add(img, transform)`**: Adds an image to the builder with a specified `Transform` object. The translation component of the transform is expressed in pixels for Raster and Smart Raster levels, and in Camera Stand units for Vector levels.
- **`builder.fill(color)`**: Fills the entire image area with the specified color.

### Attributes

- **`builder.image`**: (Read-only) Returns the resulting image after operations are applied.

### Examples

```javascript
// Create an image composition with scaling and rotation
let ib = new ImageBuilder(800, 800);
let img = new Image("C:/levels/name.0001.tif");

let scale = 1;
let phi = 0;

for(let i=0; i<20; i++) {
    let tr = new Transform().scale(scale).translate(0, -200).rotate(phi);
    ib.add(img, tr);
    phi -= scale * 30;
    scale *= 0.9;
}

view(ib.image);
```
```

--------------------------------

### XML Structure for HTML Xsheet Header and Table Size

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/working_in_xsheet.md

Defines the structure for customizing the HTML Xsheet header and table dimensions. This XML file allows users to set the number of rows and columns for the Xsheet tables and add custom information to the HTML header. Editing these values controls how the Xsheet is rendered and printed.

```xml
<xsheet_html>
   <page rows="50">
   <page columns="10">
   <info name="Company" value="Company name"/>
   <info name="Name" value="Value"/>
</xsheet_html>
```

--------------------------------

### Scene Object Loading and Saving

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

The Scene object represents a Toonz scene file. It can be loaded from and saved to a specified filename. If a relative path is provided, it defaults to using the scenes of the current project. The Scene object also provides methods to set individual cells within the scene.

```default
// Example usage would typically involve loading and then manipulating scene data.
// Specific examples for scene.setCel and scene.setCell are not provided in the source text.
```

--------------------------------

### Explicitly Define Variable in Functions

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/editing_curves_and_numerical_columns.md

Allows explicit definition of the variable used in predefined functions like 'saw', 'wave', and 'pulse'. This provides more control over the function's behavior relative to specific variables.

```mathematical
fun (var; argument...)
```

--------------------------------

### Printing to Console in ToonzScript

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

The `print` command in ToonzScript writes messages to the console. It accepts multiple arguments and does not return `undefined`. This is useful for debugging and displaying output.

```default
print("result=",12*3);
```

--------------------------------

### Reference Effect Parameter

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/editing_curves_and_numerical_columns.md

Allows referencing parameters of effects within expressions. This is useful for creating dynamic relationships between effect properties.

```expression
fx.name.parameter
fx.name.parameter(delta)
fx.name.parameter.subparameter
fx.name.parameter.subparameter(delta)
```

--------------------------------

### Vectorizing Raster Images with OutlineVectorizer

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

Converts raster images (Raster or Smart Raster) into vector formats using an outline algorithm. Allows customization of vectorization parameters.

```javascript
v = new OutlineVectorizer();

v.preservePaintedAreas = true;

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

b = v.vectorize(a);

view(b);
```

--------------------------------

### Rasterizer: Converting Vector to Raster Formats

Source: https://context7.com/tahoma2d/tahoma2d_docs/llms.txt

The Rasterizer class converts vector images (like PLI) into raster formats (TIF) or ToonzRaster (TLV). It allows customization of resolution (xres, yres), DPI, and whether to use color mapping for TLV output. It can process individual images or entire levels.

```javascript
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\\output.tlv");

r2 = new Rasterizer();
r2.xres = 3840;
r2.yres = 2160;
r2.dpi = 150;
r2.colorMapped = false;
hires = r2.rasterize(new Image("C:/vector/image.pli"));
hires.save("C:/raster/hires.tif");
```

--------------------------------

### CenterlineVectorizer: Vectorizing for Line-Art Animation

Source: https://context7.com/tahoma2d/tahoma2d_docs/llms.txt

The CenterlineVectorizer class is designed to vectorize raster images for line-art animation using a centerline-based algorithm. It provides parameters for thresholding, accuracy, despeckling, maximum thickness, thickness calibration, preserving painted areas, and adding borders. The output can be viewed and saved.

```javascript
v = new CenterlineVectorizer();
v.threshold = 128;
v.accuracy = 5;
v.despeckling = 2;
v.maxThickness = 10;
v.thicknessCalibration = 1.0;
v.preservePaintedAreas = true;
v.addBorder = false;

a = new Image("C:/Users/username/lineart.tif");
b = v.vectorize(a);
view(b);
b.save("C:/Users/username/vectorized_lineart.pli");
```

--------------------------------

### Scene Manipulation in JavaScript

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

API for managing cells, columns, and levels within a Tahoma2D scene. Supports creating, loading, saving, and modifying scene elements.

```javascript
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);
}
```

--------------------------------

### Image Manipulation with ImageBuilder

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

Enables image modifications like rotation, scaling, cropping, and layering multiple images. Supports different transformations based on level types.

```javascript
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: Vectorizing Raster Images with Custom Settings

Source: https://context7.com/tahoma2d/tahoma2d_docs/llms.txt

The OutlineVectorizer class converts raster images into vector format using an outline-based algorithm. It offers parameters for controlling maximum thickness, preserving painted areas, accuracy, color mapping, despeckling, corner adherence, and tone threshold. It can vectorize single images or entire levels.

```javascript
dir = "C:\\Tahoma stuff\\SCRIPT IMAGES IN\\";
dir2 = "C:\\Tahoma stuff\\SCRIPT IMAGES OUT\\";

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

v = new OutlineVectorizer();
v.maxThickness = 1;
v.preservePaintedAreas = false;
v.accuracy = 10;
v.maxColors = 10;
v.despeckling = 2;
v.cornerAdherence = 0.5;
v.cornerAngle = 45;
v.cornerCurveRadius = 0.1;
v.toneThreshold = 128;
v.transparentColor = "#FFFFFF";

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

level = new Level("C:/images/sequence..tif");
v2 = new OutlineVectorizer();
v2.accuracy = 5;
v2.preservePaintedAreas = true;
vectorizedLevel = v2.vectorize(level);
vectorizedLevel.save("C:/output/vector_sequence.pli");
```

--------------------------------

### FilePath Object Manipulation

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

The FilePath object represents a file system path and provides methods to manipulate it, such as changing extensions, names, parent directories, and concatenating paths. It also allows access to file attributes like existence, modification time, and directory status. This is useful for file management within scripts.

```default
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
```

--------------------------------

### Updating Language Translations

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/CONTRIBUTING.md

This command updates the language-specific message files (.po) using the generated message catalog. It creates or updates the .po files in the specified locale directory for the target language (e.g., 'ja' for Japanese).

```bash
$ sphinx-intl update -p build/gettext -l ja
```

--------------------------------

### Image Object Loading and Saving

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

The Image object represents an image file and supports loading from and saving to various formats like tlv, pli, and fullcolor. It provides attributes for width, height, and DPI, and can be displayed using the 'view' function. Supported image types include Raster, ToonzRaster, and Vector.

```default
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");
```

--------------------------------

### Generate Sawtooth Curve

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/editing_curves_and_numerical_columns.md

Generates a periodic sawtooth-shaped curve. The height defaults to the length if not specified. This function is implicitly tied to a frame-independent variable.

```mathematical
sawtooth(length)
sawtooth(length, height)
```

--------------------------------

### ToonzScript: Rotating Animation Frames

Source: https://context7.com/tahoma2d/tahoma2d_docs/llms.txt

This script processes each frame of an animation level, applies a rotation transformation, and saves the result as a new animation level. It utilizes ToonzScript's Level, Transform, and ImageBuilder classes to manipulate animation frames programmatically.

```javascript
// Define input/output directories
dir = "C:\\Tahoma stuff\\SCRIPT IMAGES IN\\";
dir2 = "C:\\Tahoma stuff\\SCRIPT IMAGES OUT\\";

// Load the image level
a = new Level(dir + "toad3..tif");
print("loaded\n", a);

// Initialize transformation and new level
t = new Transform();
b = new Level();
ll = a.getFrameIds();

// Build rotated animation
for(i=0; i<a.frameCount; i++) {
    ib = new ImageBuilder();
    step = 360 / a.frameCount;
    myimage = a.getFrame(ll[i]);

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

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

// Save and display result
b.save(dir2 + "rottoad3..tif");
print("saved\n", b);
view(b);
```

--------------------------------

### Geometric Transformation with Transform Class

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

Defines a geometric transformation comprising rotation, translation, and scaling. Used in conjunction with ImageBuilder.

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

print(transform);
```

--------------------------------

### Convert Vector to Raster Images

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

Converts vector images into Raster or ToonzRaster images. Allows setting output resolution (xres, yres) and DPI. Can produce color-mapped ToonzRaster images by setting the colorMapped attribute to true.

```default
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");
```

--------------------------------

### Level Object Frame Manipulation

Source: https://github.com/tahoma2d/tahoma2d_docs/blob/master/source/toonzscript.md

The Level object manages sequences of images, supporting formats like tlv, pli, and fullcolor. It allows loading, saving, and retrieving individual frames by ID or index. Frames can also be set using an Image object. The level has attributes for name, path, frame count, and type.

```default
// 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);
```
Tokens:
Raw