Toon Boom
Harmony22
Utilities Guide

TOON BOOM ANIMATION INC.

+1 514 278 8666

4200 St.Laurent Blvd, Suite 1020
Montreal, Quebec, Canada
H2W 2R2

contact@toonboom.com
toonboom.com

Harmony 22 Utilities User Guide

Legal Notices
Toon Boom Animation Inc.
4200 Saint-Laurent, Suite 1020
Montreal, Quebec, Canada
H2W 2R2
Tel: +1 514 278 8666
Fax: +1 514 278 2666
toonboom.com

Disclaimer
The content of this document is the property of Toon Boom Animation Inc. and is copyrighted. Any
reproduction in w hole or in part is strictly prohibited.
The content of this document is covered by a specific limited w arranty and exclusions and limit of liability
under the applicable License Agreement as supplemented by the special terms and conditions for
Adobe® Flash® File Format (SW F). For details, refer to the License Agreement and to those special terms andconditions.

Trademarks
Toon Boom® is a registered trademark. Harmony™ and the Toon Boom logo are trademarks of Toon Boom
Animation Inc. All other trademarks of the property of their respective ow ners.

Publication Date
09-23-2022
Copyright © 2022 Toon Boom Animation Inc., a Corus Entertainment Inc. company. All rights reserved.

1

Table of Contents

Table of Contents
Table of Contents

2

Introduction to Utilities

4

Chapter 1: Adding the Path to Harmony Utilities to the System's List of Paths

6

Chapter 2: Running a Command Line Utility

10Chapter 3: Utilities Reference

14

Pdfimport Utility

15

Pix2vec Utility

17

Vectorization

36

How to Vectorize W ith Bubbles

40

Sw f2tvg Utility

44

Sw fimport Utility

46

tvg2xml Utility

47

uinfo Utility

48

utransform Utility

49

About Exporting Layouts as Bitmap Using utransform66

How to Export a Layout as Bitmap Using utransform

70

ConsolidateDb Utility

77

2

Harmony 22 Utilities User Guide

3

Introduction to Utilities

Introduction to Utilities

Toon Boom provides utilities that you can use in a Command Prompt and Shell to provide more flexibility andcontrol over the different command options in Toon Boom Harmony.

4Harmony 22 Utilities User Guide

5

Chapter 1: Adding the Path to Harmony Utilities to the System's List of Paths

Chapter 1: Adding the Path to Harmony Utilities to the System's
List of Paths
By default, to run a Harmony utility, you must type its full path follow ed by its name in the command line. The
full path of the utility includes the path in w hich Harmony w as installed. If you installed Harmony in its default
installation directory, the path w ill be as follow s:l

W indows: C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 22 [Edition]\w in64\binlmacOS:/Applications/Toon Boom Harmony 22 [Edition]/Harmony[Edition].app/Contents/tba/macosx/binl

GNU/Linux:/usr/local/ToonBoomAnimation/harmony[Edition]_22/lnx86_64/bin

So, for example, if you w ish to run utransform on W indow s, you w ould have to type C:\Program Files(x86)\Toon Boom Animation\Toon Boom Harmony 22 [Edition]\win64\bin\utransform into
the command line. This can get tedious and time consuming, especially if you intend to run utilities routinely.
If you prefer, you can add the path to Harmony's command line utilities to your system's list of default paths
for commands. W hen you attempt to run a command w ithout specifying its path, the operating system looks
for an utility that matches the name of the command in every folder in the list of paths, and if it finds it, it runsthat utility. This is w hy most command line utilities bundled w ith your operating system can be launched bysimply typing their name. By adding the path to Harmony's command line utilities to this list, merely typing thename of the utility into a command line w ill be enough to run it.

How to add Harmony to the system path list on W indows
1. Open the Start menu and, in the list of programs, select Harmony 22 [Edition] >Configuration

W izard..
2. In the main menu of the Configuration W izard, select Add Harmony to Path.
3. In the next panel, select the scope to w hich to add the path to:lSingle User: This w ill only add Harmony to your list of paths w hen you're logged in as theuser you are currently logged into.

l

All Users: The path to Harmony w ill alw ays be in the list of system paths, regardless of
w hich user is logged on.

4. Select Next.
5. Click on Finish.
The next time you open a Command Prompt, the path to Harmony w ill be included in the system's
list of paths and you w ill be able to launch Harmony command line utilities by only typing their filename rather than their full file path.

6

Harmony 22 Utilities User Guide

TIPS
You can quickly see w hat is in your list of paths by typing echo %PATH% in the commandl

prompt. Each path in the list w ill be separated by a semicolon.
You can also edit the content of the PATH environment variable, in w hich those paths arelstored, for your logged in user and for the w hole system by using the Environment
Variables panel. To access it, from the Start menu, in the programs list, select W indows
System > Control Panel > System and Security > System > Advanced system settings >Advanced tab > Environment Variables.

IMPORTANT
If you upgraded from a previous version of Harmony, and added the path to that version ofHarmony in the past, both the paths for the old and current version w ill be in the list. Then, it
w ill be difficult to determine if you are running the latest version of Harmony's command line
utilities. It is recommended to remove old versions of Harmony from your paths w hen you
upgrade to a new version.

How to add Harmony to the system path list on macOS
1. In Finder, proceed to Applications >Toon Boom Harmony 22 [Edition] and double-click

Harmony [Edition].
The main Harmony application launches.
2. In the top menu, select Harmony [Edition] > Tools > Configuration Assistant.
3. In the main menu of the Configuration Assistant, check the Register console application in thepath option. Uncheck all other options and select Continue.
4. In the next panel, select the scope to w hich to add the path to:lRegister Path for all users: The path to Harmony w ill alw ays be in the list of system paths,
regardless of w hich user is logged on.

lRegister Path for my user only: This w ill only add Harmony to your list of paths w hen
you're logged in as the user you are currently logged into.

5. Click on Create.
The next time you open a Terminal, the path to Harmony w ill be included in the system's list ofpaths and you w ill be able to launch Harmony command line utilities by only typing their file namerather than their full file path.

7

Chapter 1: Adding the Path to Harmony Utilities to the System's List of Paths

TIPSl

You can quickly see w hat is in your list of paths by typing echo $PATH in the commandprompt. Each path in the list w ill be separated by a colon.

l

If you w ant to remove Harmony from your path, you must manually edit out theconfiguration file in w hich it w as stored:l

If you added Harmony to the path for all users, open /etc/profile in an editor.

l

If you added Harmony to the path for your ow n user, open ~/.profile in an editor.

Then, remove the block betw en # BEGIN HARMONY PATH REGISTRATION and # END
HARMONY PATH REGISTRATION.

How to add Harmony to the system path list on GNU/Linux
1. Locate the installer package that w as used to install Harmony on your machine. If you deleted it,
dow nload it and unpack it again w ith the follow ing command:tar -xvzf <name of package>
2. Sw itch to the directory in w hich the installer package w as unpacked:
cd <path to extracted installer package>
3. Type in the follow ing command:sudo ./install -e
The installer w ill launch.
4. In the installer, read and agree to the End User License Agreement.
5. Confirm that you w ant to add Harmony to the PATH environment variable.
6. Once the operation is done, reboot the machine.
The path to Harmony w ill be included in the system's list of paths.

TIP
You can quickly see w hat is in your list of paths by typing echo $PATH in the commandprompt. Each path in the list w ill be separated by a colon.

TIP
If you w ant to remove Harmony from your path, simply run ./uninstall -e from theinstaller package directory and follow the same procedure.

8Harmony 22 Utilities User Guide

9Chapter 2: Running a Command Line Utility

Chapter 2: Running a Command Line Utility
Toon Boom includes a number of command line utilities that you can use to convert image formats, bitmap or
vector, into other image formats.
To run an utility, you must open your operating system's terminal or command prompt, then type the file pathto the utility follow ed by arguments.
The command line utilities for Harmony are located in the bin directory of its installation folder. Based on thedefault installation path, it should be in the follow ing location:l

W indows: C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 22 [Edition]\w in64\binlmacOS:/Applications/Toon Boom Harmony 22 [Edition]/Harmony[Edition].app/Contents/tba/macosx/binl

GNU/Linux:/usr/local/ToonBoomAnimation/harmony[Edition]_22/lnx86_64/bin

NOTE
By default, to run an utility, you must type its full path follow ed by its name in the command line.
To circumvent this, you can add the path to Harmony's command line utilities to your system's listof default paths for commands—see Adding the Path to Harmony Utilities to the System's List ofPaths on page 6.

How to run a command line utility
1. Open a terminal or command prompt by doing one of the follow ing:l

W indows: Open the Start menu and, in the programs list, select W indows System >Command Prompt.

lmacOS: Open LaunchPad, then select Other > Terminal.

l

GNU/Linux: Open the Applications menu, then select Utilites > Terminal.

2. In the command line, type cd follow ed by the path to the folder containing the file(s) you w ant toprocess, then press ENTER.

10

Harmony 22 Utilities User Guide

TIP
W hen typing paths in a command line:l

You can type the first few characters of the name of a file or folder in the current
directory, then press TAB to make the command line auto-complete the name. If
several files or folders match the characters you typed, you might have to press
TAB repeatedly to cycle through matching files and folders until the right one isselected.

lCommand lines use spaces as a w ay to separate the parameters sent to acommand. If a path contains spaces, you must enter the path betw een quotes, or
add a backslash \ before each space, to indicate that the spaces are part of the path.

l

W indow s uses backslashes \ to separate the name of directories in a path. macOSand GNU/Linux use forw ard slashes /.

lAbsolute file paths on W indow s begin w ith a drive letter follow ed by a colon. Bydefault, the drive on w hich W indow s and your documents are located is C. Hence,
most paths in W indow s w ill start w ith C:\. On macOS and GNU/Linux, absolute filepaths begin w ith a forw ard slash /.

l

You can type file paths that are relative to the current directory by starting the pathw ith the name of the first folder name to navigate to. For example, if you're in theDocuments folder and w ant to go to its MyScene subfolder, simply typing cd
MyScene w ill w ork. You can also navigate to folders that are parent of the current
folder by referring to a folder named w ith tw o consecutive periods ... For example,
to navigate from the MyScene folder back to its Documents parent folder, typing
cd .. w ill w ork.

3. Type the name of the utility you w ish to use, follow ed by its parameters. Each parameter w ill startw ith a dash -. Some parameters take extra information, such as file names or colour values. The
follow ing example launches utransform to convert the file Bg_Camp-Camp.tvg into a Targa(.tga) bitmap image:utransform -outformat TGA Bg_Camp-Camp.tvg

11

Chapter 2: Running a Command Line Utility

The command w ill launch. If no errors are encountered, it w ill simply display its version
information, then exit.
1. Check if the file you expected the command to output is present. On W indow s, you can use the dir
command follow ed by a file name or pattern to query w hich files are in the current directory. On
macOS or GNU/Linux, you can do that w ith the ls command:

2. At any time, you can obtain information on how to use an utility by launching it follow ed w ith the help parameter.

12

Harmony 22 Utilities User Guide

utransform -help

13

Chapter 3: Utilities Reference

Chapter 3: Utilities Reference
The follow ing chapter lists the utilities available for processing image and describes all their parameters.
Pdfimport Utility

15

Pix2vec Utility

17

Vectorization

36

How to Vectorize W ith Bubbles

40

Sw f2tvg Utility

44

Sw fimport Utility

46

tvg2xml Utility

47

uinfo Utility

48

utransform Utility

49

About Exporting Layouts as Bitmap Using utransform66

How to Export a Layout as Bitmap Using utransform

70

ConsolidateDb Utility

77

14

Harmony 22 Utilities User Guide

Pdfimport Utility
PDF Import (Pdfimport) allow s you to import a Portable Document File (.pdf) or Adobe Illustrator (.ai) file asa Harmony template w ithout going through the user interface, allow s more control and flexibility over the
results.

NOTE
Since a Harmony template is a folder containing a scene, this command outputs several files insidea folder. If the target folder exists, it w ill not overw rite the w hole folder, but it w ill overw rite thefiles inside it.

SyntaxPdfimport [options] <.pdf or .ai files>

ExamplePdfimport -PDF_GENERATE_COLOUR_ART -outdir "C:\Users\username\Documents\Toon
Boom Harmony [Edition] Library" BG-1.ai BG-2.aiParameters
Parameter

Description

The path to the directory w here to store the template. A new directory w ill becreated in the specified directory, named after the imported .pdf or .ai file
follow ed w ith the extension .tpl. The template filles w ill be stored in that new
directory.
-outdir output_folder

NOTE
You should use this option to specify the output directory if you're
specifying several .ai or .pdf files, as their final output directory w ill
be automatically named based on their original file names.

The path to the template directory in w hich to store the template. The
template files w ill be stored directly inside the specified directory.

-outtemplate output_folder.tpl

NOTE
Since this option does not use the name of the imported file todetermine the output directory, you can only specify a single .ai or.pdf file w hen using this option.

15

Chapter 3: Utilities Reference

NOTE
The -outdir and -outtemplate options are mutually exclusive.

This option w ill automatically convert CMYK colours to RGB. By default CMYK
colours are imported as solid red.

NOTE
-PDF_SUPPORT_CMYK
If this option is not enabled and CMYK colours are in the .pdf or .ai file,they w ill be imported as solid red, and the utility w ill output thefollow ing w arning:
CMYK: Unsupported colorSpace-PDF_SEPARATE_LAYERS

Uses the Illustrator top level groups as separate layer names.

-PDF_FLATTEN

Flattens each draw ing.

-PDF_LINE_ART_STROKE

Makes the contours of vector shapes "strokes". Contrary to a regular contour, astroke w ill remain in the draw ing even if it is unpainted.

Breaks the brush strokes composing the line art at their intersection, making aseparate colour zones for each segment of the line art. This allow s the ink &paint artist to easily paint different parts of the lineart w ith different colours.
-PDF_BREAK_LINE_ART

NOTEThis option implies -PDF_GENERATE_COLOUR_ART.

-PDF_GENERATE_COLOUR_
ART

Creates strokes based on the centrelines of the line art and stores them in thecolour art layer, making empty colour zones that can easily be filled w ith the
Paint tool.

-PDF_ALLOW _UNICODE

Allow s the use of Unicode-exclusive characters in layer names.

-usageDisplays a list of parameters w ith their description.

-?|-h|-help|--help

Displays the help information.

-v|-version|--version n

Displays the version information.

16

Harmony 22 Utilities User Guide

Pix2vec Utility
Pix2vec is an highly flexible and versatile utility for converting scanned draw ings and lineart images to Toon
Boom Vector Graphic (.tvg) files that are ready to be inked and painted. It can be used to vectorize Toon
Boom Scan (.scan) files as w ell as any type of bitmap supported by Toon Boom Harmony.

SyntaxPix2vec -file INPUT_FILE [OPTIONS]

ExampleThe only option that is mandatory for Pix2vec is -file or -infile. It w ill generated a Toon Boom Vector
Graphic (.tvg) draw ing based on the input file, w ith the bitmap draw ing vectorized in the line art layer andcolour zones generated in the colour art layer. The default parameters for vectorization are used for every
unspecified parameter. The filename of the output file w ill be based on the input file, but w ith the extension.tvg.
Pix2vec -file A-1.scan
If the default parameters are not giving the expected results, you can try using Pix2vec w ith its extensive setof options.
Pix2vec -infile A-1.scan -outfile B-1.tvg -register 150 b l -no_texture rmv_holes 10 -rmv_dirt 10 -rmv_hairs 30 3 -rmv_triangles 90
Pix2veccan only process one file at a time. If you w ant to use Pix2vec on a series of file, you can script aloop in your command line. A loop repeats a command w hile counting from one number to another number ina specified increments, and that number is stored in a variable to be used by the command, allow ing you toiterate through several draw ings that have the same base name, but are numbered in a series.
For example, you can iterate through draw ings on to 13, numbered on tw os, w ith the follow ing command:l

On W indow s, in Command Prompt:> FOR /L %I IN (1,2,13) DO Pix2vec -file A-%I.scanl

On macOS and GNU/Linux, in a Bash terminal:$ for I in {1..13..2}; do Pix2vec -file A-$I.scan; done

You can also loop through every file of a given type in a directory using the follow ing syntax:l

On W indow s, in Command Prompt:> FOR %I IN (*.scan) DO Pix2vec -file %Il

On macOS and GNU/Linux, in Bash:$ for I in *.scan; do Pix2vec -file $I; done

17

Chapter 3: Utilities Reference

Parameters
General Options
Parameter

Description-help--help-?

Displays the list of the sections on w hich you can obtain usage
information.

Displays usage information on the specified section. The follow ing
sections are available:-help <section>lall: Displays help on all parameters.

lio: Displays help about the input/output parameters.

lregister: Displays help about the peg registration parameters.

lfilter: Displays help about the filtering parameters.

lrgb: Displays help about the red/green/blue keying parameters.

l4colours: Displays help about four colours vectorization
parameters.

lbubble: Displays help about bubble generation parameters.

lcolor: Displays help about colour vectorization parameters.

-debugUse this option to turn on the debug mode.

-version

This option w ill display the version information.

Input/Output Parameters
Parameter

Description-file <filename> -infile<filename>

Use this option to define the file you w ant to perform Pix2vec on.

Use this option to rename the output file.

-outfile <filename>

NOTE
The filename must include the extension.

18

Harmony 22 Utilities User Guide

Parameter

Description-informat <format>

This option defines the input format. Used if reading from standard input.

-noforce

This option w ill prevent the output image from being forced if the image
is inconsistent.

-force_unamed_palette_for_
textureGenerates textures in the TVG's internal palette.

Sets the version of the output files.
-output_version <version>
Valid versions are 0 or 604. The TVG format version is 604.

Peg Registration Parameters
The follow ing parameters configure how the draw ing is registered. Registration is the process of analyzing theposition of the draw ing's peg holes and aligning it relative to its field.
Parameter

Description

Use this option to perform optical registration.
<dpi>: The resolution of the scan.
<side>: The side of the sheet on w hich the pegs are to be registered.
Can be one of the follow ing:

-register <dpi> <side><strictness>lb or bottomlt or topll or leftlr or right<strictness>: The strictness w ith w hich the registration is evaluated.
Can be one of the follow ing:ll or loosels or strict-registration_center_peg_
holes-rcph

Only uses round (center) peg holes in 16 fields pages.

-registration_looseness_factor <factor> -rlf
<factor>

The registration looseness factor. This is used for optical registration
only.

19

Chapter 3: Utilities Reference

Parameter

Description

By default, the looseness factor is 2.

-rdebug

Outputs debug information about the registration.

The distance betw een peg bars, in inches.
-pegpitch <inches>
By default, this is set to 8.

-threshr <value>

The threshold used for optical registration. This can be set to a decimalvalue ranging from 0 to 1.
By default, this is set to 0.5.

The distance betw een the edge of the paper and its peg holes.
-rmargin <inches>
By default, this is set to 1.

-peg_distance_from_center<inches> -pdfc <inches>

The distance betw een the center of the page and the peg holes.
By default, this is set to 5.25.

Defines the desired side of the pegs on the draw ings. If it is different
from the side of its actual registration (passed w ith the -registerparameter), the draw ing w ill be rotated accordingly.
lsame: The same side as the draw ing's actual registration.

lb or bottomlt or topll or leftlr or right-out_peg_position <side>

By default, this is set to same.

-output_peg_matrix

Outputs the information about the peg matrix to the terminal.

-scanner_calibrate <x scale><y scale>

Sets the horizontal and vertical scale factor to be applied on the scanned
image. The scale factors are 1-based, meaning that 1 represents theimage's original size.
By default, this is set to 1 1.

20

Harmony 22 Utilities User Guide

Filtering Options
The follow ing parameters configure the w ay the line art is converted to vector outlines, and how its centreline
is converted to colour zones.
Parameter

Description

Defines the shape of pixels. The only valid value for this is 4x3.
-pixel <pixel shape>
By default, this is set to 4x3.

Automatically close gaps that are up to a certain size w ith invisible
strokes, to make closed shapes that can be painted.
-gap <length>

The value sets the maximum length of gaps to close, in w orld units.
By default, this is set to 10.

Generate pencil lines for the line art.
-pencilThis should not be used w ith the -no_color_art parameter.

Properly vectorizes line art draw n on a transparent background.
By default, Pix2vec expects line art to be on an opaque background-vectorize_alpha-use_alphaand w ill not properly vectorize line art draw n on a transparent
background. Use this parameter if you are vectorizing draw ings w ith atransparent background.

-keep_dirt

Disables filtering dirt out from the draw ing.

-thresh <value>

The threshold used for vectorization. This can be set to a decimal value
ranging from 0 to 1.
The default threshold is 0.2.

Removes hair, w hich are short useless strokes extending from closed
shapes.

-rmv_hairs <length> <passes>

The length determines the maximum length of hairs to remove, in w orld
units. The passes determines the amount of times to remove hairs fromthe w hole draw ing. Adding extra passes w ill remove hair that branched
into several hairs.
The default length is 1 and the default number of passes is 1.

-rmv_holes <size>

Remove holes that are smaller than the defined area, in w orld units
squared, from the artw ork.

21

Chapter 3: Utilities Reference

Parameter

Description

The default size of holes to remove is 7.

Removes dirt that is smaller than the defined size, in w orld units
squared, from the artw ork.
The default size of dirt to remove is 1.
-rmv_dirt <size>

TIP
Try removing holes and dirt w ith a size ranging from 100 to 500.

Removes triangles at the defined distance from one another, in w orld
units.
By default, the distance of triangles to remove is 30.

-rmv_triangles <size>

NOTE
Triangles are used to break the strokes in line art into different
colour zones to help paint different zones of the line art w ith
different colours. You can use the -no_break parameter toremove all triangles and make all adjacent line art into single
colour zones.

-no_texture

Disables the generation of textured strokes.

Converts the entire image to a coloured bitmap texture and stores it in avector rectangle.
-color_as_textureThis does not create editable line art nor does it create any colour zones,
but it preserves the image exactly as is.

-noclosegap

Disables closing gaps. All gaps in the artw ork w ill remain open
regardless of how small they are.

-no_break

Disables breaking the line art into triangles, making all adjacent line art
into single colour zones.

-jag_filter <pixels>

This reduces the jaggedness in line art by expanding the lines by the
specified amount of pixels (using the same mechanism as the -expand_bitmap parameter), then contracting the lines by the same amount,
resulting in smoother outlines. It is recommended to use values such as 1

22

Harmony 22 Utilities User Guide

Parameter

Description

or 2.
By default, the jag filter is set to 0.

-expand_bitmap <pixels>

Expands the outlines of the line art by the set amount of pixels, resulting
in thicker outlines.
By default, this is set to 0.

Defines the fit error level for the colour art.

-fit_errorc <value>

The fit error is the process by w hich three points segments, w hich makecorners, are interpreted as curves. This means that instead of draw ing asegment from point 1 to point 2, then from point 2 to point 3, a single
segment is draw n from point 1 to point 3, w ith Bezier curves adjusted forthe line to go over point 2. A higher fit error w ill cause more corners to beinterpreted as curves. A low er fit error w ill cause the artw ork to havemore points. Some fit error is required to avoid having too many control
points.
The default fit error is 1.

Defines the fit error level for the line art.

-fit_errorl <value>

The fit error is the process by w hich three points segments, w hich makecorners, are interpreted as curves. This means that instead of draw ing asegment from point 1 to point 2, then from point 2 to point 3, a single
segment is draw n from point 1 to point 3, w ith Bezier curves adjusted forthe line to go over point 2. A higher fit error w ill cause more corners to beinterpreted as curves. A low er fit error w ill cause the artw ork to havemore points. Some fit error is required to avoid having too many control
points.
The default fit error is 1.

Sets the amount of smoothing passes to perform on the line art.
-smoothl <passes>
By default, this parameter is set to 1.

Sets the amount of smoothing passes to perform on the colour art.
-smoothc <passes>
By default, this parameter is set to 1.

-first_smooth <passes>

Defines the number of smooth passes to perform on the line art before
breaking the triangles.
By default, this parameter is set to 0.

23

Chapter 3: Utilities Reference

Parameter

Description-support_thin_lines

Do not erode thin lines w hen generating colour art.

Using this parameter allow s you to set tw o sets of parameters, one forvectorizing the line art and one for creating the colour art.
W ith this option, you can use the follow ing parameters w ith the suffix lor c ro define its value differently for the line art and for the colour art:

-2passl-treshl and -treshcl-jag_filterl and -jag_filterc

l-expand_bitmapl and -expand_bitmapcl-rmv_holesl and -rmv_holescl-rmv_dirtl and -rmv_dirtcl-first_smoothl and -first_smoothc

The threshold used for vectorization for the line art. This can be set to adecimal value ranging from 0 to 1.
The default threshold is 0.5.
-threshl <value>

NOTE
This threshold is higher than the default value for single-passvectorization, w hich may erode thin or light outlines. If you w ant toobtain results similar to single-pass vectorization, set this to 0.2.

The threshold used for vectorization for the colour art. This can be set toa decimal value ranging from 0 to 1.
The default threshold is 0.5.
-threshc <value>

NOTE
This threshold is higher than the default value for single-passvectorization, w hich may erode thin or light outlines. If you w ant toobtain results similar to single-pass vectorization, set this to 0.2.

-jag_filterl <pixels>

This option expands the pixels in the vectorization bitmap for line art. Tosmooth and straighten jagged lines.

-jag_filterc <pixels>

This option expands the pixels in the vectorization bitmap for colour art.

24

Harmony 22 Utilities User Guide

Parameter

Description

To smooth and straighten jagged lines.

-expand_bitmapl<pixels>

Expands the outlines of the line art by the set amount of pixels, resulting
in thicker outlines for the line art.
By default, this is set to 0.

-expand_bitmapc<pixels>

Expands the outlines of the line art by the set amount of pixels, resulting
in thicker outlines for the colour art.
By default, this is set to 0.

-rmv_holesl <size>

Remove holes that are smaller than the defined area, in w orld units
squared, for the line art.
The default size of holes to remove is 7.

-rmv_holesc <size>

Remove holes that are smaller than the defined area, in w orld units
squared, for the colour art.
The default size of holes to remove is 7.

-rmv_dirtl <size>

Removes dirt that is smaller than the defined size, in w orld units
squared, for the line art.
The default size of dirt to remove is 1.

-rmv_dirtc <size>

Removes dirt that is smaller than the defined size, in w orld units
squared, for the colour art.
The default size of dirt to remove is 1.

-first_smoothl<passes>Defines the number of smooth passes to perform on the line art before
breaking the triangles, for the line art.
By default, this parameter is set to 0.

-first_smoothc<passes>Defines the number of smooth passes to perform on the line art before
breaking the triangles, for the colour art.
By default, this parameter is set to 0.

-margins <inches>

Removes a margin all around the bitmap. The size of the margin must be
specified in inches.

25

Chapter 3: Utilities Reference

Parameter

Description

By default, this parameter is set to 0.25.

-top_margin <inches>

Removes a margin from the top edge of the bitmap. The size of themargin must be specified in inches.
By default, this parameter is set to 0.25.

-bottom_margin <inches>

Removes a margin from the bottom edge of the bitmap. The size of themargin must be specified in inches.
By default, this parameter is set to 0.25.

-left_margin <inches>

Removes a margin from the left edge of the bitmap. The size of themargin must be specified in inches.
By default, this parameter is set to 0.25.

-right_margin <inches>

Removes a margin from the right edge of the bitmap. The size of themargin must be specified in inches.
By default, this parameter is set to 0.25.

-remove_peg_bars

Removes the peg bar holes from the draw ing.

Sets the field size of the output draw ing.
By default, this is set to:l

12 if the input image is a regular bitmap.

l

The internal field size of the scan file, if the input image is a Toon
Boom Scan file.

-field_size <fields>-fs<fields>

NOTE
Scan files have their ow n field size. If the field size of the scan fileis different than the field size of the TVG that is generated from it,its scaling w ill be affected. Regular bitmap files do not have a fieldsize, therefore, their dots per inch (DPI) resolution is automaticallyadjusted to fit the field, unless the -dpi parameter is used.

-peg_bar_size <inches>

Sets the size of the region reserved for the peg bar, from the edge of thedraw ing, in inches.

26

Harmony 22 Utilities User Guide

Parameter

Description-noframe

Disables adding a frame around the colour art.

Adds a frame of the specified size around the colour art. The size must be
specified in fields.

-frame_fields <fields>

If the frame is made to match the draw ing, its element and its scene's
field size, it w ill fit the scene's camera field perfectly. By default, all ofthese are 12 fields in size.
The default value of this parameter is -1, w hich uses the draw ing's fieldsize.

Dow nscales the input image before processing it. This does not affectthe dimensions of the vectorized draw ing in the scene, only its display
quality. In other w ords, this is equivalent to pixelating the draw ing.
-downscale_input <factor>
The scale factor is an integer used as the denominator. For example, thedefault value is 1, w hich does not dow nscale the image, 2 w ould
dow nscale the image by half, etc.

Dow nscales the output texture. This is very similar to -downscale_
input, except that the dow nscaling is performed on the line art's
texture after the original draw ing has been vectorized. This means thatthe contours of the outlines and the strokes in the colour art are notaffected, only the texture in the outline is.
-downscale_texture <factor>

Just like -downscale_input, the dimensions of the vectorized draw ing
are not affected, so this is equivalent to pixelating the vectorizeddraw ing's texture.
The scale factor is an integer used as the denominator. For example, thedefault value is 1, w hich does not dow nscale the texture, 2 w ould
dow nscale the texture by half, etc.

-buildmatte

Generates a filled matte based on the line art and stores it in theunderlay art layer.

Generates a filled matte based on the line art and stores it in the color art
layer.
-buildmatte_colourart

NOTE-buildmatte and -buildmatte_colourart are mutually
exclusive.

27

Chapter 3: Utilities Reference

Parameter

Description-copystrokes

W hen generating a matte, copies the strokes from the line art layer onto
the matte so as to preserve the defined colour zones.

Options for Bitmap with no Registration Information
The follow ing options can be used if you are vectorizing regular bitmaps, rather than Toon Boom Scan (.scan)
files.
Parameter

Description-pixel_margins <pixels>

Removes a margin all around the bitmap. The size of the margin must be
specified in pixels.
By default, this parameter is set to 0.

-top_pixel_margin <pixels>

Removes a margin from the top edge of the bitmap. The size of themargin must be specified in pixels.
By default, this parameter is set to 0.

-bottom_pixel_margin<pixels>

Removes a margin from the bottom edge of the bitmap. The size of themargin must be specified in pixels.
By default, this parameter is set to 0.

-left_pixel_margin <pixels>

Removes a margin from the left edge of the bitmap. The size of themargin must be specified in pixels.
By default, this parameter is set to 0.

-right_pixel_margin <pixels>

Removes a margin from the right edge of the bitmap. The size of themargin must be specified in pixels.
By default, this parameter is set to 0.

Sets the resolution of the input image, in dots per inches.
-dpi <dots per inch>-layer <layer name>

The default value for this parameter is -1, w hich makes Pix2vec
automatically adjust the DPI resolution of the draw ing to make it fit thefield of the draw ing.

W hen vectorizong a multi-layer Photoshop Document (.psd) file, thisparameter allow s you to select w hich layer to vectorize.

28

Harmony 22 Utilities User Guide

Parameter

Description

If the layer is inside one or several groups, its group hierarchy must be
specified w ith the layer name, using colons (:) as separators. For
example, if the layer is named layer1 and is inside group1 at the rootof the layers list, you w ould use this notation:-layer group1:layer
The default value for this parameter is ''.

Red/Green/Blue Keying Options
The follow ing options allow you to vectorize red, green and blue lines as they are coloured, instead of ingreyscale, w hich is the default behaviour. This can be especially useful if you are using certain line colours for
specific purposes. For example, red lines are traditionally used in animation to close colour zones outside of
the camera field or to trace an outline that is meant to match the outline of a background element.
Parameter

Description

Generates separate zones for red, green and blue lines.

NOTE
-rgb
By default, the red, green and blue lines w ill have an alpha of 1.
You can set their alpha to a different value w ith the -rgb_alphaparameter.

-rgb_alpha <value>

Specifies the alpha of the red, green and blue lines generated w ith the rgb parameter.
By default, this parameter is set to 1.

W hen enabled, red, green and blue lines generated w ith the -rgb
parameter w ill also have texture.
-rgb_alpha_texture
Contrary to the -flatten parameter, this w ill still vectorize the colour
line in gray first, then add the coloured vectorized line over it.

Separates the colour zones used for red, green and blue lines from thecolour zones used for the black lines instead of overlaying them.
-rgb_separate

NOTE
This parameter also requires the -2pass parameter to w ork.

29

Chapter 3: Utilities Reference

Parameter

Description-no_redIgnores red lines during vectorization.

-no_green

Ignores green lines during vectorization.

-no_blue

Ignores blue lines during vectorization.

-flatten

Instead of adding the vectorized colour lines over the vectorized line art
as separate draw ing strokes, this applies the colour of the colour lines tothe existing texture of the vectorized line art.
This option is useful if you don't w ant black lines to appear behind thecolour lines, should you choose to remove the colour lines later.

-rmv_rgb_dirt <size>

Removes red, green or blue spots smaller than the specified area, inw orld units squared.
The default value for this parameter is 0.

Expands the red, green and blue outlines of the line art by the set
amount of pixels, resulting in thicker coloured outlines.
By default, this is set to 0.
-expand_bitmap_rgb<pixels>

TIP
Using this w ith the -flatten parameter can help overw rite blacklines generated from the coloured lines during regular
vectorization w ith the vectorized coloured lines, as they may nototherw ise overw rite those black lines completely.

-threshrgb <value>

The threshold for RGB vectorization. This can be set to a decimal value
ranging from 0 to 1.
By default, this is set to 0.2.

-threshsv <saturationthreshold> <value
threshold>

The saturation and value threshold required for a pixel to be considered
coloured rather than grey or black. Both can be set to a decimal value
ranging from 0 to 1.
The default saturation threshold is 0.5 and the default value threshold
is 0.5.

30

Harmony 22 Utilities User Guide

Four Colours Vectorization
The follow ing options allow you to vectorize a draw ing w ith red, green, blue and black lines. This is very
similar to the Red/Green/Blue keying vectorization parameters, except that this approach is a mode of its ow n.
Contrary to Red/Green/Blue vectorization, this w ill not generate the black line art and add coloured lines on
top. It w ill generate a single layer of non-textured vector shapes that are either solid red, solid green, solid
blue or solid black, w ithout them overlapping each other. Most of the parameters for this mode are used todetermine how to differentiate red, green, blue, black and w hite in the source draw ing.
Parameter

Description

Performs four colour vectorization using the specified parameters.
You can specify zero or as many parameters as needed. Each parametermust be expressed by its key follow ed by a colon and then its value.
Parameters must be separated by spaces, but there should be no spaces
betw een a key and its value. For example:-4colours rgbdiff:20 dark:20 grey:120 white:250
dirt:200 rt:240 gt:240 bt:240
Here are the available keys:lrgbdiff: The threshold for tolerating mixed colours. A low ervalue means mixed colours are interpreted as their dominantprimary colour. A higher value means mixed colours areinterpreted as either black or w hite, depending on their value.
This parameter can be set to a value betw een 0.0 and 1.0 or
betw een 0 and 255.

ldark: The threshold for differentiating black. A higher valuemeans lighter shades of dark colours and dark greys arevectorized as black. A low er value means only very dark areas
are vectorized as black. Can be set to a value betw een 0.0 and
1.0 or betw een 0 and 255.

lgrey: The threshold for the interpretation of greys. Greys below
this threshold are vectorized as black, and greys above thisthreshold are vectorized as w hite. Can be set to a value betw een
0.0 and 1.0 or betw een 0 and 255.

lwhite: The threshold for differentiating w hite. A low er valuemeans darker shades of light colours and light greys arevectorized as w hite. A higher value means only very light areas
are vectorized as w hite. This parameter can be set to a value
betw een 0.0 and 1.0 or betw een 0 and 255.

l

rt: The threshold differentiating red from black. A low er valuemeans dark red is vectorized as red. A higher value means dark
red is vectorized as black. This parameter can be set to a value
betw een 0.0 and 1.0 or betw een 0 and 255.

-4colours <key:value> ...
<key:value>

31

Chapter 3: Utilities Reference

Parameter

Descriptionlgt: The threshold differentiating green from black. A low ervalue means dark green is vectorized as green. A higher valuemeans dark green is vectorized as black. This parameter can be
set to a value betw een 0.0 and 1.0 or betw een 0 and 255.

l

bt: The threshold differentiating blue from black. A low er valuemeans dark blue is vectorized as blue. A higher value means dark
blue is vectorized as black. This parameter can be set to a value
betw een 0.0 and 1.0 or betw een 0 and 255.

l

dirt: The size of dirt to remove, in w orld units squared. The
suggested value to use is 200.

Bubble options
Bubbles are bumps added along the outlines, giving the impression that the outline w as draw n quickly w ith apressure sensitive marker or fountain pen. They are made of streaks of circles that increase in size as the bumpappears then decrease in size as the bump subsides. The size of bubbles and the distance betw een them canbe configured.

NOTE
To learn more about the Bubble command, see How to Vectorize W ith Bubbles on page 40.

Parameter

Description-create_bubbles

Randomly adds bubble shapes along the line art.

Sets the maximum number of colour art points betw een tw o bubbles.
-bubble_gap <value>
By default, this parameter is set to 3.

Sets the maximum number of circles in a bubble.
-bubble_length <value>

A bubble is a streak of circles draw n along the outline. The more circles,
the bigger the bubbles appear.
By default, this parameter is set to 10.

-min_radius <factor>

Defines the minimum radius of a circle in a bubble. This radius is a factor
relative to the line thickness, w here 1.0 is equal to the original thicknessof the line. Hence, its value must be at least 1.0.
By default, this parameter is set to 1.5.

32

Harmony 22 Utilities User Guide

Parameter

Description-max_radius <factor>

Defines the maximum radius of a circle in a bubble. This radius is a factor
relative to the line thickness, w here 1.0 is equal to the original thicknessof the line. Hence, its value must be at least 1.0.
By default, this parameter is set to 3.5.

-uniform_gap

Lays out the bubbles at an equal distance from each other.

Ensures every circle in bubbles has the same height.

NOTE-uniform_heightThis option is deprecated. Instead, you can accomplish this bysetting -min_radius and -max_radius to the same value.

Colour Vectorization Options
This approach vectorizes each pixel individually, merging pixels of the same colour in the same colour zones.
Hence, it is important to only use it w ith image files that have very few solid colours w ith no antialiasing.

NOTE
Colour vectorization is experimental.

Parameter

Description-color_vectorize

Performs a colour vectorization.

-file2 <color art
filename>

Allow s you to specify a bitmap file for the generation of colour art.

Generates a brush texture for the line art.
-penstyle <center
alpha> <edge alpha><gamma> <centre
pressure effect> <edgepressure effect><texture bitmap
downscaling> <texture
bitmap file>

The parameters are as follow s:l<centre alpha>: The alpha value in the middle of the line.
Can be set to a value betw een 0.0 and 20.0, although thegreatest difference is visible betw een 0.0 and 3.0.

l<edge alpha>: The alpha at the edge of the line. Can be set toa value betw een 0.0 and 1.0. Setting this to 1.0 w ill yield asolid line.

33

Chapter 3: Utilities Reference

Parameter

Descriptionl<gamma>: The gamma of the texture. A higher value w ill makethe edge darker, a low er value w ill make the edge lighter. Thiscan be set to a value betw een 0 and 10.

l<centre pressure effect>: The pressure at the centre of
the line. Can be set to a value betw een 0.0 and 1.0.

l<edge pressure effect>: The pressure at the edge of theline. Can be set to a value betw een 0.0 and 1.0.

l<texture bitmap scaling>: The scaling factor of thebitmap texture. Can be set to a value betw een 0.2 and 20.

l<texture bitmap file>: The path to a bitmap image to use
as the texture. Set this to "" to not use a bitmap texture.

Configures the pressure variation strategy for the centreline.
The parameters are as follow s:-pressure_variation<strategy> <minpressure> <maxpressure> <maxvariation>-blur_radius <pixels>l<strategy>: The strategy to for the distribution of pressure
variation. Can be set to either 0, 1 or 2.

l<min pressure>: The minimum pressure used. Can be set to avalue betw een 0.0 and 1.0.

l<max pressure>: The maximum pressure used. Can be set toa value betw een 0.0 and 1.0.

l<max variation>: The maximum pressure variation. Can be
set to a value betw een 0.0 and 1.0.

Blurs the generated brush texture. The size of the blur must be specified
in pixels.
By default, this parameter is set to 0.

-color_contour_smooth_passes <passes>

Sets the amount of smoothing passes to perform on the contour before
computing the line texture.

-ccsp <passes>

By default, this parameter is set to 3.

-color_rmv_holesl<size>

Removes holes that are smaller than the defined size, in w orld units
squared, from the line art, w hen computing the line texture.
By default, this parameter is set to 0.

-color_fill_holesl<size>

Fills holes that are smaller than the defined size, in w orld units squared,in the coloured line art.

34

Harmony 22 Utilities User Guide

Parameter

Description

By default, this parameter is set to 0.

35

Chapter 3: Utilities Reference

Vectorization
The options that are used during the vectorization process are based on vectorization styles. You can select apreset from a list, or customize your ow n.
Some of the commonly used vectorization styles displayed in the Custom Vectorization Parameters, and theImport Draw ings dialog boxes, use parameters similar to the follow ing examples:•

Black and W hite•

Tones/highlights (B+W notriangles)•

Greyscale Rougher Lines•

Greyscale Soft Edge

Black and W hite
Use this style to vectorize black and w hite (1-bit) SCAN, or any other black and w hite files. Black and w hite 1bit files include no texture information.
options: -no_texture -rmv_holes 7 -rmv_dirt 10 -fit_errorl 2.0 -fit_errorc
2.0
W hen you vectorize black and w hite draw ings w ith these options, the vector files w ill contain no texture (no_texture); all lines w ill be solid.
These options also remove holes, (-rmv_holes 7) and dirt, (-rmv_dirt 10) of specific sizes.
The fit_errorl and fit_errorc options also filter the contours that form ink lines and colour art so thatthey are smoother.

36

Harmony 22 Utilities User Guide

Tones/highlights (B+W notriangles)

This style vectorizes black and w hite 1-bit files that w ill be used as mattes to build tone and highlight effects.
options: -no_texture -rmv_holes 7 -rmv_dirt 10 -fit_errorl 2.0 -fit_errorc
2.0 -no_break
These options prohibit the creation of line textures, remove holes and dirt, and smooth final draw ings. These
options also remove triangles (-no_break) at the intersection of lines in the line art.
Triangles are useful at intersections if the intersecting lines are to be painted using different colours. This is
unnecessary in draw ings, like mattes, that w ill be painted a solid colour.

Greyscale rougher lines
This style vectorizes greyscale draw ings, maintaining the rough textures in the lines.
options: -2pass -threshl 0.1 -threshc 0.2 -rmv_holesl 7 -rmv_holesc 7 -rmv_
dirtl 10 -rmv_dirtc 10 -expand_bitmap 0 -fit_errorc 3.0 -fit_errorl 3.0 jag_filterc 1 -rmv_hairs 30 3 -rmv_triangles 90
As you can see in the example below , the draw ing gets its character from the roughness of its lines. You
w ould not w ant to lose the distinctness of the line during the vectorization process.

37

Chapter 3: Utilities Reference

The options in this style force tw o passes of the vectorization process to apply different values to the line art
and colour art (-2pass). You must specify values for the line art and colour art w hen you use this option.
For draw ings w ith specific vector-style lines or mattes, you only need one pass. For greyscale draw ings, you
may w ant to pass through the vectorization process tw ice to apply different values to the line art and colourart.
The colour art (-threshc) and line art (-threshl) thresholds determine w hat values in the scanned image
w ill be considered as part of the draw ing, and w hat w ill be ignored and eliminated in the vectorized draw ing.
Zero (0) is w hite and one (1) is black. The threshold is betw een these tw o values.
The expand_bitmap and jag_filter options w ork together so that you can pick up noise, or small pencil
lines and marks, during the vectorization process. The expand_bitmap option expands the bitmap to pick up
the noise. W hen used w ith jag_filter, the bitmap is shrunk dow n by the value of the option. You use thesetw o options together to maintain the size of your line art.
The fit_error options smooth ink lines and colour art strokes.
The rmv_holes and rmv_dirt options remove hair and dirt of a specific size from the line art and colour art.
The rmv_hairs option removes tiny strokes that extend from main colour art strokes. And, rmv_triangles
option removes triangles and intersections that are less than the specified distance apart.

Greyscale soft edge
Use this vectorize style w hen you w ant to create a vector image w ith fine, textured strokes. Unlike theGrayscale rougher lines style, this style is meant for more subtle line variations.
style_name: Grayscale soft edge
options: -2pass -threshl 0.05 -threshc 0.05 -rmv_holesl 7 -rmv_holesc 7 rmv_dirtl 10 -rmv_dirtc 10 -fit_errorl 2.0 -fit_errorc 2.0 -expand_bitmapl 1
Compare these options to the Grayscale rougher lines style. You w ill notice that the-thresh values are smaller; therefore, few er pixels w ill be filtered out.This contributes to the fluffierappearance of the lines. You w ill also notice that the fit_error value is smaller and the -expand_bitmap
value is larger. All of these options contribute to the smoother appearance of the final line.

38Harmony 22 Utilities User Guide

39

Chapter 3: Utilities Reference

How to Vectorize W ith Bubbles
Vectorizing w ith bubbles allow s the user to modify the original LineArt of a draw ing by randomly inserting
bubble shapes.
The command inserts bubbles starts from the circle w ith the smallest radius (min_radius), w ith the centre on
one colour art point. The command then adds subsequent circles on the remaining colour art points, increasing
their radius each time. The command adds new circles in ascending order of radius until the bubbles reach the
maximum size specified by the max_radius parameter.
The command inserts the first and last circle at the minimum radius (specified by the min_radius parameter)
and randomly assigns the height of the middle circle based on the bubble_length parameter.
For each bubble that appears, the command selects a random number of colour art points to set the distance
betw een bubbles. The bubble_gap specifies the maximum number of such points, w ith the minimum beingzero.

ExamplesDrawing W ith Uniform Line Thickness
The initial draw ing has a uniform thickness. Use it to view and compare the results of the follow ing bubbles
options.

40

Harmony 22 Utilities User Guide•

Example 1
The draw ing has been vectorized using the command options:-create_bubbles -bubble_gap 3 -bubble_length 16 -max_radius•

Example 2
The draw ing has been vectorized using the command options:-create_bubbles -bubble_gap 3 -bubble_length 4 -max_radius 3.5

41

Chapter 3: Utilities Reference•

Example 3
The draw ing has been vectorized using the command options:-create_bubbles -bubble_gap 3 -bubble_length 16 -max_radius 3.5•

Example 4
The draw ing has been vectorized using the options:-create_bubbles -bubble_gap 3 -bubble_length 4 -max_radius 3.0 -uniform_gap-uniform_height42

Harmony 22 Utilities User Guide

43

Chapter 3: Utilities Reference

Swf2tvg Utility
The Sw f2tvg utility is used to import an SW F file into your scene w ithout using the interface. This w ill create a.tvg file for each frame. Use the different commands to control the options.
Here is the format you must follow w hen using Sw f2tvg:
Swf2Tvg -palette <palette_file> -usage -help -use_different_palettes-base_name <base_out_name> -outdir <output directory> -bbox_recenter-ignore_position -start_index <number> file1 [file2] [file3]
Here are the available Sw f2tvg options:
COMMANDACTIONDESCRIPTION OF SW ITCHES-palette <palette_file>

This option is used to add the colours of the SW F file to thepalette file and save it.

-use_different_palettes

This option is used to create a new palette for each SW F fileand DOES NOT save any palette.

-base_name <name>

Use this option to automatically rename all generated
draw ings name-x.tvg w here x is an increasing index.

-start_index <index>

Use this option to define the starting index to name thedraw ings.
The default value is 1.

-outdir <dir>-use_place_objects

Use this option to define the output directory for all
generated draw ings.

This option w ill transform and position the imported
draw ings follow ing the position on the stage in the Flashproject. This option uses the information that is contained in
the SW F PLACE_OBJECT record.
Note: this option does not use -start_index.

-frame_alias <list>

This option uses the comma separated list of names togenerate timing information.
This is mainly to convert models.

44

Harmony 22 Utilities User Guide

COMMANDACTIONe.g. -frame_alias FR_%.2d,3Q_%.2d,BK_%.2d"-base_color_index <index>

Use this option to base the colour index in higher 32 bits.

-bbox_recenter

This option centres draw ings according to their boundingbox.
This option implies -ignore_position.

-ignore_position

Use this option to ignore all sceneplanning information.

-usageThis option w ill display the usage.

-?|-h|-help|--help

This option w ill display the help information.

-v|-version|--version

This option w ill display the version information.

NOTE•

If -outdir is not specified, the files w ill be w ritten in the SW F file current directory.

•

You can specify any SW F file or PLT file. The PLT files w ill be read and used to matchcolours but w ill not be modified. The only palette modified is the palette specified by the palette sw itch.

45

Chapter 3: Utilities Reference

Swfimport Utility
The Sw fimport utility is used to create a template from a SW F file.
Here is the format you must follow w hen using Sw fimport:
SwfImport [options] swf_files
Here are the available Sw fimport options:
COMMANDACTIONAVAILABLE OPTIONS-outdir output_folder

This option specifies the output folder for the generated
templates-applycolourtransform

This option w ill apply colour transforms from SW F onto
the draw ings.

-paletteName name_of_paletteUse this option to specify the name of the palette file touse w ith colour recovery.

DESCRIPTION OF SW ITCHES-outdir dir

This option specifies the output folder for the templates(The specified folder must already exist.)-usageThis option w ill display the usage.

-?|-h|-help|--help

This option w ill display the help information.

-v|-version|--version

This option w ill display the version information.

W ARNING
Sw fimport does not overw rite templates.

46

Harmony 22 Utilities User Guide

tvg2xml Utility
The tvg2xml utility is used for debugging purposes; it w ill convert your TVG files to an XML file format thatyou can read.
Here is the format you must follow w hen using tvg2xml:
tvg2xml -file <filename (including extension)> [ options ]Here are the available tvg2xml options:
COMMANDACTIONOPTIONS-infile <filename (including extension)>

Use this option to define the file to perform tvg2xml on.

-outfile <filename>

This option is used to define an alternate output file. Use for output to standard output.

This option discretizes the Bezier path using scale. Scaletypically range from 0.025 to 4. A larger number means ahigher resolution.
-discretize [optional scale default =0.1]

NOTE: Discretize is a process w here each pixel of an image
is converted into the black foreground or the w hitebackground. The colours and grays of the original image arelost. By controlling discretizing, unw anted parts of theoriginal image can be removed. This process of converting
colour images into black foreground and w hite backgroundis called discretizing.

-no_bitmap_data

This option w ill prevent the output of bitmap data. This w ill
produce a smaller XML files if the bitmap data is notneeded.

-flattenThis option w ill perform a flatten on the layers.

-v|-version|--version

This option w ill display the version information.

-?|-h|-help|--help

This option w ill display the help information.

47

Chapter 3: Utilities Reference

uinfo Utility
The uinfo utility is used to display the follow ing information about a specified bitmap file.
•

Name

•

Resolution•

Format•Channels•

Bites per Channels

Here is the format you must follow w hen using uinfo:
uinfo program input_files
COMMANDACTIONAVAILABLE OPTIONS-?|-h|-help|--help

This option w ill display the help information.

-v|-version|--version

This option w ill display the version information.

48

Harmony 22 Utilities User Guide

utransform Utility
The utransform utility can convert regular bitmap images to Toon Boom Vector Graphic (.tvg) images andvice-versa, and perform certain image processing routines at the same time.

Syntaxutransform [OPTIONS] INPUT_FILES

Exampleutransform -outformat PNG4 -outfile layout.png -scale 0.5 -bgalpha 0 BG1.tvg
utransform -outformat SCAN -bgcolor 255 255 255 A-1.tvg A-2.tvg A-3.tvg

ParameterslGeneral Parameters on page 49lFile Output Parameters on page 49

lImage Processing Parameters on page 51lVector to Bitmap Parameters on page 54lVector to Vector Options on page 58

General Parameters
Parameter

Description-debugThis option w ill display information on the different steps of the process
as w ell as the messages related to errors that might have occurred.

-?-h-help--help

This option w ill display the help information.

-v-version--version

This option w ill display the version information.

File Output Parameters
The follow ing parameters are used to set the file name and file type of the output files.
Parameter

Description-outformat <format>

This is the image format that you w ant to output w ith utransform. The
follow ing output image formats are supported:49

Chapter 3: Utilities Reference

Parameter

Descriptionl

TGA (TGA1, TGA3 and TGA4)l

SGI (SGI1, SGI3, SGI4, SGIDP3 and SGIDP4)l

OPT (OPT1, OPT3 and OPT4)l

PSD (PSD1, PSD3, PSD4, PSDDP3 and PSDDP4)

l

YUV

l

PAL

l

SCAN

l

TVG

l

PDF

l

PNG (PNG4)Some of these image formats have variants, the notation of w hich iscomposed of:lTheir file extension. For example, the format PSDDP4 w ill output
a Photoshop Document (.psd) file.

l

Their colour depth, if applicable. The format PSDDP4 specifies"DP", w hich means double- precision. This means each channel
has a colour depth of 16 bits. Formats that do not have thisnotation use the standard depth of 8 bits per channel.

l

If they support different amounts of channels, the amount ofchannels they use. For example:l1 means 1 colour channel, w hich renders in greyscale.

l

3 means 3 colour channels, w hich renders in solid
colours.

l

4 means 3 colour channels + 1 alpha channel, meaning
the format supports transparency values.

50Harmony 22 Utilities User Guide

Parameter

Description

NOTES
l

It is important to specify the output format. If no output format
is specified, utransform w ill not use the output format
specified in the extension of the output file. Instead, it w illeither output in TGA or TVG format, depending on theparameters.

l

For formats that have variants, merely specifying the fileextension w ill also w ork. It w ill output images w ith standard
colour depth (8 bits per channel) in solid colour (3 channels).

lSome of these formats are Toon Boom formats:l

VAR is a legacy Toon Boom format for greyscale bitmap
images.

l

OPT is a legacy Toon Boom format for bitmap images
w ith various channel configurations.

l

SCAN is the format in w hich the Scan application records
image data from a scanner. It is a greyscale bitmap format
that also contains scanning metadata such as theregistration, resolution and field chart of the draw ing.

l

TVG is the standard image format used by Toon Boomapplications for vector draw ings as w ell as Toon Boom
bitmap draw ings.

The path and name of the file to output. By default, output files w ill havethe same name as their input files and w ill be output in the same
directory, w ith the only difference being their file extension.
-outfile <file name>NOTE
If processing multiple files, this option w ill be ignored.

Image Processing Parameters
The follow ing options can perform routine transformations on images.
Parameter

Description-resolution <width><height>

The dimensions of the output image, in pixels.

51

Chapter 3: Utilities Reference

Parameter

Description

NOTE
This option only w orks if the output file is a regular bitmap.

Determines the dimensions of the output image based on its scan
metadata. This is useful w hen unvectorizing images that w ere initiallyvectorized after being scanned, as Harmony records the dimensions ofscanned images in the draw ing's metadata.
-resolution scan

NOTE
This option only w orks if the input file is a Toon Boom Vector
Graphic (.tvg) file and the output file is a regular bitmap.

-move <x> <y>Offsets the input image from the centre of the frame. x is the horizontal
offset and y is the vertical offset. Both values are in pixels. A positive x
offset w ill move the image tow ards the right, and a positive y offset w ill
move the image tow ards the top.

The scale factor to apply to the input image. The default value is 1 (noscaling).

-scale <factor>

NOTE
This w ill not affect the dimensions of the output image. Hence,w hen scaling up, the image is liable to be cropped, and w hen
scaling dow n, the image may have padding around it.

-xscale <factor>

The horizontal scale factor to apply to the input image.

-yscale <factor>

The vertical scale factor to apply to the input image.

Rotates the input image by the specified angle in degrees. A positive
value w ill rotate the image counterclockw ise, and a negative value w illrotate it clockw ise.
-turn <angle>

NOTE
This option only w orks if the output file is a regular bitmap.

52

Harmony 22 Utilities User Guide

Parameter-ps <input format> <output
format>Description

Converts the shape of the pixels in the image for use w ith analog
television formats. The pixel shape of the input image and of the output
image must be specified to make the conversion. The follow ing formats
are supported:lsquare

l

NTSC

l

PAL

The background colour to apply to the background if the input image hastransparent pixels. By default, the output image w ill be laid on solid
w hite.
-bgcolor <red> <green><blue>

The colour values can be expressed in integers ranging from 0 to 255 or
in decimals ranging from 0.0 to 1.0.

NOTEThis option only w orks if the output file is a regular bitmap.

The alpha value of the background if the input image has transparent
pixels. By default, the background w ill be fully opaque.
The alpha value can be expressed in an integer ranging from 0 to 255 ora decimal ranging from 0.0 to 1.0.
-bgalpha <alpha>NOTE
This option only w orks if the output file is a regular bitmap and its
format supports alpha.

The w ay the colour values of pixels is encoded relative to their alphavalue. This parameter has tw o possibles uses:l

To indicate the premultiplication type of the source image w hen
converting a regular bitmap image to a Toon Boom bitmap(.tvg).

l

To set the premultiplication type of the output image w hen
converting a Toon Boom Bitmap (.tvg) to a regular bitmap
image (w ith the -bitmapartonly option).

-premultiply <mode>This parameter supports the follow ing premultiplication modes:lstraight: The colour values are not encoded raw regardless of53

Chapter 3: Utilities Reference

Parameter

Description

their opacity ratio.
lblack: The colour values are multiplied by their opacity ratio,
meaning they are encoded as darker if they are semi-transparent.

lwhite: The colour values are divided by their opacity ratio,
meaning they are encoded as lighter if they are semi-transparent.

NOTE
W hen exporting Portable Netw ork Graphics (.png) files, theimage is alw ays encoded w ith no premultiplication (straight).

Vector to Bitmap Parameters
Rendering Parameters
The follow ing parameters affect how a Toon Boom Vector Graphic (.tvg) image is rendered into a bitmap.
Parameter

Description

Specify the antialiasing quality and exponent w hen converting vector
images to bitmaps.
The quality determines the method used to apply antialiasing:llow: Disables antialiasing, but renders transparency.

lmedium-low: Renders vector artw ork w ith basic antialiasing.

lmedium: Renders vector shapes w ith improved antialiasing.
Bitmap texture fills w ill appear blurred.

lhigh: Renders vector shapes w ith improved antialiasing,w ithout blurring bitmap texture fills.

-antialiasing <quality><exponent>

The exponent determines how much the image is scaled up before
antialiasing is applied onto it, to then be scaled dow n. The higher thevalue, the sharper the edges w ill come out. This value can range
betw een 0 and 3. This value is only applied w ith medium or high quality
antialiasing.

-nolinetexture

Ignores the bitmap texture in brush strokes and vectorized line art,
rendering them solid.

54

Harmony 22 Utilities User Guide

Parameter

Description

NOTE
This does not affect textured pencil lines.

-nolineart

Does not render the line art layer.

-nocolorart

Does not render the colour art layer.

Only renders bitmap art layers. This can be used w hen converting from a
Toon Boom Bitmap to a regular bitmap.
If the input file only has one art layer and this art layer is of Toon Boom
bitmap type, the artw ork is converted as-is, w ith its output resolution
matching its canvas size.

-bitmapartonly

If the input file has multiple art layers of the Toon Boom bitmap type, theart layers are merged together before the final conversion. The
resolution of the output image w ill be based on either one of thefollow ing:l

The canvas size of the line art layer in the input file, if there is one
and if it is a bitmap art layer.

l

The bottom most bitmap art layer in the input file, if there is noline art layer of if the line art layer is not bitmap.

NOTE
This parameter ignores the -resolution parameter.

Show Strokes Parameters
The follow ing parameters can be used to render invisible strokes, the contour of brush strokes and thecentrelines of pencil lines w ith a colour to make them visible.
Parameter

Description-showstrokes

Renders the contour of line art and centrelines in colour so that it'svisible in the output image.

-thickness

Sets the thickness of the contours of line art and centerlines.

55

Chapter 3: Utilities Reference

Parameter

Description

If unspecified, the default thickness is 1.

-lineartstrokescolor<red> <green> <blue><alpha>-colorartstrokescolor<red> <green> <blue><alpha>Sets the colour in w hich to render the strokes in the line art. The colour
is defined in red, green, blue and alpha values.
If unspecified, the default colour of line art strokes is green (0 255 0
255).

Sets the colour in w hich to render the strokes in the colour art. The
colour is defined in red, green, blue and alpha values.
If unspecified, the default colour for colour art strokes is cyan (0 255
255 255).

Alignment Parameters
The follow ing parameters affect how a Toon Boom Vector Graphic (.tvg) file is aligned and proportioned
w hen rendered into a bitmap canvas.
Parameter

Description

Determines how the vector artw ork is laid out w ithin its canvas.
The follow ing rules are available:-align <rule>

l

AS_IS

l

CENTER_TBl

CENTER_LRl

CENTER_FIRST_PAGE_HORIZONTALl

CENTER_FIRST_PAGE_VERTICAL

l

TOP

l

BOTTOM

l

LEFT

l

RIGHT

l

AUTO_ALIGN

The bitmap w ill be made to fit inside a Harmony scene in a draw ing layer
w ith this alignment rule in its properties.
W hile most of these options w ill align the draw ing relative to theirinternal canvas, AUTO_ALIGN w ill automatically centre the artw ork

56

Harmony 22 Utilities User Guide

Parameter

Description

inside a canvas that is adjusted to its size and add a margin around it.

-dpi <dpi>

Use this option to define the output resolution for the bitmap image indots per inch.
The default resolution is 75 DPI.

The size of the paper in inches.
-paper_size <inches>
The default size is 12.

The number of fields to add as margin around the output Toon Boomdraw ing (.tvg) file. If unspecified, this is set to 8.
-margin <fields>

NOTE
This parameter only affects the output w hen used w ith the align parameter set to AUTO_ALIGN.

The field size of the element.

-element_size <fields>

NOTE
This parameter only affects the output w hen used w ith the align parameter set to AUTO_ALIGN.

The aspect ratio of the scene to use for processing draw ings.
The default aspect ratio is 1.33333. You should use 1.77777 for 16:9
scenes.
-sar <scene aspect ratio>

NOTE
This parameter only affects the output w hen used w ith the align parameter set to CENTER_FIRST_PAGE_HORIZONTAL,CENTER_FIRST_PAGE_VERTICAL or AUTO_ALIGN.

Outputs the coordinates of the input draw ing's bounding box to theterminal, in the follow ing format:-printboxx1 y1 x2 y2
W here x1 and y1 are the x and y coordinates of the bottom-left corner57

Chapter 3: Utilities Reference

Parameter

Descriptionof the box, and x2 and y2 are the x and y coordinates of the top-rightcorner of the box.

NOTE
These coordinates are in model coordinates. In a 4:3 12 fields grid,a horizontal field is equal to 208.333 units and a vertical field isequal to 156.25 units.

-box <x1> <y1> <x2> <y2>

The bounding box to use w hen aligning the draw ing before rendering it,
instead of its normal bounding box. The box is draw n using the x and ycoordinates of its bottom-left corner follow ed by the x and y coordinatesof its top-right corner.

Adjusts the canvas of the output image to include all of the artw ork in
the input draw ing and to trim out the negative space.
-crop

Also outputs the information about the cropping of the image in XML
format. The information is output to the terminal, as w ell as in an .xml
file named after the output file w ith the suffix .xml.

PDF Output Parameters
The follow ing parameter is the only parameter that w ill affect the output w hen outputting Portable Document
Files (.pdf).
Parameter

Description-fieldsize <field size>

Sets the amount of fields to render PDF files in. This w ill crop or extend
the canvas of the image inside the PDF document if the value is different
than the source image's field size.
The default field size is 12.

Vector to Vector Options
Centerline Parameters
The follow ing parameters are for extracting the centerline from a draw ing's line art layer and storing it as
strokes in the colour art layer.

58

Harmony 22 Utilities User Guide

Parameter

Description-centerline

Extracts the centreline of the draw ing’s line art and store it as strokes in
the colour art, so that they can be painted.

-keepcolorart-nofitcolorart

W hen extracting the centreline from the line art, preserve the artw ork in
the colour art layer and put the extracted centreline over it.

Does not generate Bezier curves for the colour art. The resulting colour
art w ill be made of straight line segments.

-closegap

Automatically adds strokes to close small gaps in the colour art.

-gaplength

Defines the maximum size of gaps to close. The default value is 10.

-hairpasses

The amount of passes to perform on the colour art to remove its hair.
Hairs are useless strokes extending fromclosed shapes. The default
value is 2.

-hairlength

The maximum length of hair to remove from the artw ork. The default
value is 20.

Colour Art Generation Parameters
Like -centerline, the follow ing options w ill extract the centreline from an art layer and store it in anotherlayer. This option has more flexibility on w hich art layers are used and how the centreline is generated.
Parameter

Description

Creates colour art based on the selected source art layer, and outputs itto the selected destination art layer, removing any existing artw ork inthat layer prior.

-arttoart <source art>
<destination art> <maxresolution> <threshold><fitting error>

To reproduce the effect of the Create Colour Art from Line Art commandin Harmony, simply use it w ith the follow ing parameters:-arttoart 4 2 2500 0.25 1<source art>: The art layer containing the line art to base the colour
art on. The value is one of the numbers used in the back-end to identify
art layers:l

1: Underlay Artl

2: Colour Art

59

Chapter 3: Utilities Reference

Parameter

Descriptionl

4: Line Artl

8: Overlay Art<destination art>: The art layer in w hich to remove existing line art
and output the generated colour art. Uses the same numbering system
as the one for the source art parameter.
<max resolution>: The maximum size in pixels, of either dimensionof the rasterized image that is created to generate the colour art. If too
low , thin lines w ill either be ignored or cut up along their length. Thissetting should be at least as high as the w idth at w hich the draw ing is
intended to be rendered. In Harmony, this parameter is set to 2500 by
default.
<threshold>: The factor that determines the level of detail to take inaccount to create the colour art. The higher this setting is, the lessdetailed but the more manageable the colour art w ill be. The low er it is,
the more details w ill be included in the colour art. In Harmony, thisparameter is set to 0.25 by default.
<fitting error>: Reduces the amount of detail in the colour art byconverting sequences of points fit curvilinear shapes into curved
segments. In Harmony, this parameter is set to 1 by default.

Matte Generation Parameters
The follow ing parameters can be used to generate a matte. A matte is a shape that matches the outlines of theartw ork and is filled w ith a solid colour. Contrary to typical colour art, a matte does not have different colour
zones for a single draw ing, and does not require the line art to have a closed shape, so it is useful to fillsketches.
Parameter

Description

Generates a matte based on the source art layer and puts it in thedestination art layer.
The radius is the size of the sample used to generate the matte. A low er
radius means the matte w ill be generated w ith higher precision.
-automatte <source art>
<destination art> <radius>

NOTE
The radius is expressed in model coordinates. On a 4:3 12 fields
grid, a horizontal field is equal to 208.333 units and a vertical field
is equal to 156.25 units.

60Harmony 22 Utilities User Guide

Parameter

Description

The source and destination art layers can be specified w ith the follow ing
keyw ords:loverlayartllineartlcolorartlunderlayart

NOTE
The matte w ill be filled w ith a non-indexed colour. You w ill hence
be prompted to perform colour recovery w hen view ing thedraw ing in Harmony.

-copystrokes

W hen generating a matte, copy the strokes from the source layer onto
the matte in the destination layer, preserving the defined colour zones.

Art Layer Parameters
The follow ing parameters can be used to manipulate the different art layers in a Toon Boom Vector Graphic(.tvg) file.
Parameter

Description

Adds the specified draw ing to the output file's line art layer.
-addlineart <drawing>

If the draw ing is a Toon Boom Vector Graphic (.tvg) file, it w ill use thatdraw ing's line art layer by default.

W hen using the -addlineart option to add a Toon Boom Vector
Graphic (.tvg) file to a draw ing's line art layer, this parameter can beused to specify w hich art layer in the source draw ing to add to the target
draw ing's line art layer. Otherw ise, the source draw ing's line art layer
w ill be used.
-uselineartlayer <art layer>

The follow ing values are supported:loverlayartllineartlcolorartlunderlayart

61

Chapter 3: Utilities Reference

Parameter

Description

Adds the specified draw ing to the output file's colour art layer.
-addcolorart <drawing>

If the draw ing is a Toon Boom Vector Graphic (.tvg) file, it w ill use thatdraw ing's line art layer by default.

W hen using the -addcolorart option to add a Toon Boom Vector
Graphic (.tvg) file to a draw ing's colour art layer, this parameter can beused to specify w hich art layer in the source draw ing to add to the target-usecolorartlayer <artlayer>

draw ing's colour art layer. Otherw ise, the source draw ing's line art layer
w ill be used.
The follow ing values are supported:loverlayartllineartlcolorartlunderlayart

Adds the specified draw ing to the output file's overlay art layer.
-addoverlay <drawing>

If the draw ing is a Toon Boom Vector Graphic (.tvg) file, it w ill use thatdraw ing's line art layer by default.

W hen using the -addoverlay option to add a Toon Boom Vector
Graphic (.tvg) file to a draw ing's overlay art layer, this parameter can beused to specify w hich art layer in the source draw ing to add to the target
draw ing's overlay art layer. Otherw ise, the source draw ing's line art
layer w ill be used.
-useoverlaylayer <art layer>

The follow ing values are supported:loverlayartllineartlcolorartlunderlayart

Adds the specified draw ing to the output file's underlay art layer.
-addunderlay <drawing>

If the draw ing is a Toon Boom Vector Graphic (.tvg) file, it w ill use thatdraw ing's line art layer by default.

-userunderlaylayer <artlayer>

W hen using the -addunderlay option to add a Toon Boom Vector
Graphic (.tvg) file to a draw ing's overlay art layer, this parameter can be62Harmony 22 Utilities User Guide

Parameter

Description

used to specify w hich art layer in the source draw ing to add to the target
draw ing's underlay art layer. Otherw ise, the source draw ing's line art
layer w ill be used.
The follow ing values are supported:-keep_birmap_transformloverlayartllineartlcolorartlunderlayart

W hen replacing the artw ork in a bitmap art layer, this option preserves
the geometric transformations that w ere done on this bitmap art layer
w ith theSelect tool.

Removes the artw ork from the specified art layer.
loverlayartllineartlcolorartlunderlayart-clearlayers <art layers>

More than one art layer can be specified by separating them w ith
commas, like so:-clearlayers overlayart,underlayart

Vector Transformation Parameters
The follow ing parameters can make specific types of transformations to Toon Boom Vector Graphic (.tvg)
files.
Parameter

Description

Replaces colour IDs in the source file w ith the specified colour IDs.

-change_color_ids <jsonfile>This parameter must be specified w ith the path to a .json file thatspecifies the ID of each colour you w ant to change, follow ed by the ID
you w ant to replace it w ith, in the follow ing format:[

63

Chapter 3: Utilities Reference

Parameter

Description{"from" : "source ID",
"to" : "destination ID"},{"from" : "source ID",
"to" : "destination ID"},{"from" : "source ID",
"to" : "destination ID"}]

Reduces the internal resolution of textures in Toon Boom draw ing(.tvg) files.
l<dots per field>: The maximum resolution of textures indots per field, based on horizontal fields. By default, this is set to72.

l<max size>: The maximum size (horizontal or verticaldimension) of textures, in pixels. You can set this to -1 if you do
not w ant to set a maximum size for textures.

-reduce_tvg_texture_
resolution <dots per field><max size>-adjustpencil <multiple><addition>

Multiplies the w idth of pencil lines by <multiple>, then adds
<addition> to their w idth.

-flatten

Flattens the artw ork, making superposed draw ing strokes into single
draw ing objects, and merging superposed textures together.

Scales the artw ork up by the specified scale factor, flattens it, thenscales it back to its original size.

-flatten_scale <scale
factor>This can be useful w hen attempting to flatten artw ork w ith
superimposed textured brush strokes. If the pixels in their bitmap
textures are not aligned properly, flattening them may cause some lossof texture quality. Scaling them up before flattening them can circumvent
this problem.
If using the -flatten option on your artw ork causes your bitmap
textures to become blurry, it is recommended to use this parameter w ith
at scale factor of at least 4.

64

Harmony 22 Utilities User Guide

Parameter

Description

Changes the internal field size of the input draw ing.

-setfieldsize <field>

Typically, a draw ing's field size should match the field size of theelement that contains it in order to appear the right size in the scene. Bydefault, both draw ings and elements have a field size of 12. If the fieldsize of the element is bigger than the field size of the draw ing, thedraw ing w ill appear bigger. If the field size of the draw ing is bigger than
the field size of the element, the draw ing w ill appear smaller.

-normalize

Normalizes the size of the draw ing relative to its field size. This scales
the artw ork up or dow n so that it fits an element that is 12 fields in size,
then sets the internal scaling of the draw ing to 1. If the draw ing's fieldsize is bigger than 12, it w ill be scaled up. If the draw ing's field size issmaller than 12, it w ill be scaled dow n.

-bboxtvgincrease<percentage>

A legacy option that w ould increase the bounding box of vector artw ork.
It is only left in to preserve for compatibility w ith legacy scripts.

65Chapter 3: Utilities Reference

About Exporting Layouts as Bitmap Using utransformIf you w ish to export a layout in bitmap format
Once your backgrounds are done in a Toon Boom application, you are ready to paint them. You can paint yourbackgrounds w ithin the softw are, or export them to a third-party bitmap softw are to paint.
There are tw o techniques for exporting vector black and w hite backgrounds:•

Render Netw ork•

utransform and Exporting a Panoramic Background

Render Network
To export your background image, you can add a W rite node to your netw ork and use the Render W rite Nodeoption to export the frame w here your background is. The background image w ill be exported and cropped tothe scene resolution.
If you have a panoramic background, use the utransform utility to export your image.

utransform and Exporting a Panoramic BackgroundThe utransform utility is able to do some format conversions and limited image processing.
By default, the utransform utility w ill convert the strokes and colour zones that are w ithin the 12 field chart. If
you have extra artw ork outside of the 12 field, you w ill have to scale dow n the draw ing using the utransform
utility in order to fit it in the 12 field zone, and enlarge the bitmap export resolution.
The panoramic background export w ill w ork w ith the alignment rule of your background draw ing in your Toon
Boom softw are.
There are several alignment rules to consider:•

Centre Top and Bottom•

Centre Left and Right

66

Harmony 22 Utilities User Guide•

Centre First Page Horizontal•

Centre First Page Vertical

•

Left

•

Right

•

Top

•

BottomCentre Top and Bottom

The Centre Top and Bottom rule is used for a vertical pan background w here the default scene’s 12 field isplaced at the centre of the draw ing.
Centre Left and Right

The Centre Left and Right rule is used for a horizontal pan background w here the default scene’s 12 field isplaced at the centre of the draw ing.
Centre First Page Horizontal

The Centre First Page Horizontal rule is used for a horizontal pan background w here the default scene’s 12
field is placed at the far left of the draw ing.

67

Chapter 3: Utilities ReferenceCentre First Page Vertical

The Centre First Page Vertical rule is used for a vertical pan background w here the default scene’s 12 field isplaced at the very bottom of the draw ing.
Left

The Left rule is the default alignment for draw ings. It aligns the draw ings w ith the left side of the scene’salignment rectangle. Harmony scales the draw ings to match their heights to the alignment rectangle of thescene.
Right

The Right rule aligns the draw ings w ith the right side of the alignment rectangle. Harmony scales thedraw ings to match their heights to the alignment rectangle of the scene.

68Harmony 22 Utilities User GuideTop

The Top rule aligns w ith draw ings w ith the top of the alignment rectangle. Toon Boom Animate scales thedraw ings to match their w idths to the w idth of the alignment rectangle of the scene.
BottomThe Bottom rule aligns the draw ings w ith the bottom of the alignment rectangle. Toon Boom Animate scales
the draw ings to match the draw ings' w idth to the w idth of the alignment rectangle of the scene.

69

Chapter 3: Utilities Reference

How to Export a Layout as Bitmap Using utransform
The As Is alignment rule is used w hen you have artw ork outside every edge of the 12 field size, such as a
Safety Paint edge.
To properly export your background and re-import it so that it fits precisely into your scene, you have toprovide utransform w ith the exact resolution that you w ant the file to be, since you are passing from a vector
based image to a bitmap image.
There are a few rules that w ill help you understand the calculation that you must perform:•

1 field w idth equals one inch.

•

A 12 field chart has a tw elve inch w idth.

•

If you scale your draw ing dow n to fit in the 12 field, you w ill have to enlarge the output resolution sothat the final image has the same size as the original draw ing (w hich is not problematic since the sourceis vector-based).

•

W hen you re-import your painted background, the bitmap file w ill be fitted in the 12 field size. You w ill
have increased the field size so that it fits the original image size.

To find the scale and DPI that you w ill need to export your image, you w ill need the follow ing information:•

The field size of the draw ing.

•

The scene resolution.

NOTE
Note that this process w ill w ork w ith a 12x12 scene alignment and w hen using Harmony.

To export a .tvg file to bitmap using the As Is alignment:
1. In the Timeline or Xsheet view , select the cell that contains the draw ing that you w ant to export.

2. In the Tools toolbar, choose the Selecttool. The default keyboard shortcut is [Alt]+[V].

3. In the Draw ing view , select all of your draw ing strokes. Select Edit > Select All. TheCtrl + A(W indow s/Linux) or ⌘ + A (macOS).
4. In the Draw ing view , place your mouse cursor over the top, right corner.

70Harmony 22 Utilities User Guide

5. From the Draw ing view ’s bottom toolbar, note the X and Y field chart information.

6. Repeat steps 4 and 5 for the bottom, left corner.

7. Once you have all of your field information, select the greatest X and Y values. These w ill give you thetotal field size of your draw ing. This also tells you the w idth of your draw ing, in inches (1 field w idth is71

Chapter 3: Utilities Reference

equal to one inch).

8. Divide the X and Y field values by 12 to know how much to scale the image to fit it in the 12 field.
X/12 = how much bigger your draw ing is than the 12 field
Y/12 = How much bigger your draw ing is than the 12 field

9. Once you have both scaling values, calculate your official scaling value by dividing 1 by the greater of
the tw o values. This w ill give you the official scaling value to enter into your utransform command line.
1/(X/12) or 1/(Y/12) = Scaling Value

10. To enlarge the output resolution, you w ill have to give a precise amount of DPI. In this case, divide yourscene resolution w idth (Rx) by 12 (fields) to know how many pixels per inch you have.
Rx/12 = Pixels per inch.

72

Harmony 22 Utilities User Guide

11. Once you have your scene’s DPI, you need to enlarge it to re-scale your output to the correct size, sincew e scaled dow n the draw ing strokes. To do so, multiply the scene’s DPI by how much larger the
draw ing is than the 12 field (X/12) or (Y/12).
(Rx/12) x (X/12) or (Y/12) = Amount of DPI needed for the draw ing output

12. Once the values are calculated, open the command prompt to launch utransform.

13. In the Command Prompt, go to the scene’s element directory that contains the *.tvg draw ing that you
w ant to convert.

73

Chapter 3: Utilities Reference‣

Use the cd command to go back up one directory.

‣

Use the cd \directory name command to enter a new directory.

‣

Use the dir command to see the directories available.

14. Once in your scene’s element directory, type:‣

For W indow s/Linux: utransform -outformat file_format_you_need -scale scale_value -dpi dpi_value -bgalpha 0 file_name.tvg‣

For macOS: ./utransform -outformat file_format_you_need -scale scale_value dpi dpi_value -bgalpha 0 file_name.tvg

Here is an example of w hat your command line should look like:‣

For W indow s/Linux: utransform -outformat PNG4 -scale 0.75 -dpi 227.55 bgalpha 0 bg-1.tvg‣

For macOS: ./utransform -outformat PNG4 -scale 0.75 -dpi 227.55 -bgalpha 0bg-1.tvg

15. In the operating system, brow se to the scene’s element folder and open the new bitmap file to paint inthird-party softw are.
To import a utransform bitmap background back in Toon Boom Harmony:
1. Open the Toon Boom Harmony scene w here the background needs to be imported.
2. To import a bitmap:‣

In the top menu, select File > Import > Images.

The Import Draw ings dialog box opens.

74Harmony 22 Utilities User Guide

3. Click on the Browse button and select your bitmap background file.
4. Click on the Open button.
5. You can import the image into an existing element or create a new element.
‣

To import the image into an existing layer, select Add to Existing Layer and select the appropriateelement from the list.

‣

To import the image into a new element, selectCreate Layer(s) > Create Single Layer Named and type a name for the element in the Name field.
6. Disable the Vectorize Imported Items option.
7. Click on the OK button.
8. Open the background’s layer properties:‣

In the Timeline view , double-click on the background’s node.

‣In the Network view , click on the background node’s yellow square.

The Layer Properties dialog box opens.
9. In the Advanced tab, set the alignment rule to As Is.

75

Chapter 3: Utilities Reference

10. Click on the OK button.
11. Open the column editor:‣

In the Timeline view , select the background’s layer, right-click and select Column Properties.

‣

In the Xsheet view , double-click on the background column’s header

12. Take your previous (X/12) or (Y/12) value and multiply it by the scene’s field to find the correct field size.
Enter this into the Field Chart field.
‣(X/12) or (Y/12) x Scene’s field‣

To see the Field Chart field, you must enable the Advanced Element Mode preference found in the
Advanced section of the Preferences panel.

Here is an example of w hat it should look like: 1.5 x 12 = 18
13. Click on the OK button.

76

Harmony 22 Utilities User Guide

ConsolidateDb Utility
The ConsolidateDb command line utility allow s you to reduce the amount of draw ings in your scene bymerging the elements that have the same draw ings together.
ConsolidateDb w orks by going through the target scene's elements to detect any pair of elements that containthe same draw ings, w hich typically occurs w hen importing a template several times or w hen duplicating
layers. If it finds tw o elements that have the same draw ings, it w ill merge both elements together into a single
element.
Merging elements is done by keeping the original element, deleting the duplicate element, and linking thecolumn that w as originally linked to the duplicate element to the original element. If the duplicate element has
any extra draw ings that are not in the original element, those draw ings are moved to the original element sothat they do not get removed from the scene.
By default, ConsolidateDb w ill not merge tw o elements that appear to match if they have at least one draw ing
w ith the same name, but different artw ork, as it w ould require renaming one of the draw ings to keep both ofthem in the same element. W ith the -renameTiming option, ConsolidateDb w ill merge elements even if it
has to rename some draw ings to keep all of the draw ings in both elements. It w ill also update the Xsheet
columns w ith the new names of the renamed draw ings to avoid affecting the rendered image.

NOTElThis utility only w orks on one scene at a time. Shell scripts must be used to run ConsolidateDb
on an entire job, environment or database.

lConsolidateDb can also be used on Harmony Stand Alone scenes.

lThis utility can also clean up unused elements in the target scene. Refer to the Parameterstable below for a list of available options.

IMPORTANTl

It is possible to add palettes to individual elements, w hich makes it possible to make tw oelements w ith the same draw ings use different colours. If tw o elements have the samedraw ings but have different palettes, ConsolidateDb w ill merge them together regardless,w hich w ill cause them to use the same palette and may affect the colours of the merged
element in the rendered image.

lConsolidateDb w ill delete files permanently from the target scene. Although it is designed to
avoid affecting the rendered image and to only remove files that are unnecessary, it is highly
recommended to make a backup of a scene before running ConsolidateDb on it.

SyntaxW hen using Harmony Server:
ConsolidateDb [options] -env <environment> -job <job> -scene <scene> -user<username>77Chapter 3: Utilities Reference

W hen using Harmony Stand Alone:
ConsolidateDb [options] <path to scene folder>

ExamplesConsolidateDb -renameTiming -removeEmptyElements -env myProject -job S03E05-scene SC0015 -user jdoe
ConsolidateDb -removeUnusedElements -verbose 2
C:\Users\jdoe\Documents\MyScene

Parameters
Parameter

Description

Database Scene Location-env <environment>

The environment in w hich the target scene is located.

-job <job>

The job in w hich the target scene is located.

-scene <scene>

The name of the target scene.

-user <username>

The Harmony user w ho w ill perform the consolidation.

Consolidation Options

By default, ConsolidateDb w ill not merge tw o elements ifthey contain draw ings w ith the same name, but not thesame artw ork. W ith this option enabled, ConsolidateDb
w ill merge elements as long as they have at least one
draw ing in common.

-renameTiming

W hen tw o draw ings have the same name but not thesame artw ork, one of the draw ings is renamed before it is
moved to the merged element. This allow s ConsolidateDb
to keep all the draw ings in the both elements w ithoutcausing any naming conflict.
The Xsheet columns w ill be updated to preserve theexposure of draw ings getting renamed. Hence, therendered image w ill not be affected.

-removeEmptyElements

By default, even if ConsolidateDb removes all thedraw ings from an element to merge it into another78Harmony 22 Utilities User Guide

Parameter

Description

element, it w ill not remove the element's directory. Use
this option to delete element directories emptied byConsolidateDb.

Increases the amount of information reported to theterminal w hile the scene is being consolidated.
Verbose mode 1 w ill output the follow ing information:-verbose 1-verbose 2l

The origin of each draw ing in duplicate elements
follow ed by their destination in the original
element.

lEach draw ing file it deletes.

l

W hether it deletes each element and w hy.

Verbose mode 2 w ill output the follow ing information:l

The origin and destination of each draw ing in boththe original element and its duplicate elements.

lEach draw ing it removes from or adds to eachcolumn.

lEach draw ing files it deletes.

l

W hether it deletes each element and w hy.

Miscellaneous-?
-hDisplays the usage information in the terminal.
-help--help-v-version

Displays the version information in the terminal.

--version79