Toon Boom
Harmony V15.0

Utilities Guide

TOON BOOM ANIMATION INC.

+1 514 278 8666

4200 Saint-Laurent, Suite 1020
Montreal, Quebec, Canada
H2W 2R2

contact@toonboom.com
toonboom.com

Harmony 15.0 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 guide is covered by a specific limited warranty and exclusions and limit of liability under theapplicable License Agreement as supplemented by the special terms and conditions for Adobe®Flash ® File
Format (SWF). For details, refer to the License Agreement and to those special terms and conditions.
The content of this guide is the property of Toon Boom Animation Inc. and is copyrighted.
Any reproduction in whole or in part is strictly prohibited.
Trademarks
Harmony is a trademark of Toon Boom Animation Inc.
Publication Date
01-15-2020
Copyright © 2018 Toon Boom Animation Inc., a Corus Entertainment Inc. company. All rights reserved.

1

Table of Contents

Table of Contents
Table of Contents

2

Chapter 1: Introduction to Utilities

4

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

6

Chapter 2: Running a Utility

10Chapter 3: Utilities Reference

14

Pdfimport Utility

15

Pix2vec Utility

17

Vectorization

36

How to Vectorize With Bubbles

40

Swf2tvg Utility

44

Swfimport Utility

46

tvg2xml Utility

47

uinfo Utility

48

utransform Utility

49

About Exporting Layouts as Bitmap Using utransform65

How to Export a Layout as Bitmap Using utransform

69

ConsolidateDb Utility

762

Harmony 15.0 Utilities User Guide

3

Chapter 1: Introduction to Utilities

Chapter 1: 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 15.0 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 followed by its name in the command line. The
full path of the utility includes the path in which Harmony was installed. If you installed Harmony in its default
installation directory, the path will be as follows:lWindows: C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 15.0 [Edition]\win64\binlmacOS (Stand Alone):/Applications/Toon Boom Harmony 15.0 [Edition]/tba/macosx/bin

lmacOS (Server): /Applications/Toon Boom Harmony 15.0 [Edition] Network/tba/macosx/binl

GNU/Linux:/usr/local/ToonBoomAnimation/harmony[Edition]_15.0/lnx86_64/bin

So, for example, if you wish to run utransform on Windows, you would have to type C:\Program Files(x86)\Toon Boom Animation\Toon Boom Harmony 15.0 [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 forcommands. When you attempt to run a command without specifying its path, the operating system looks for anutility that matches the name of the command in every folder in the list of paths, and if it finds it, it runs thatutility. This is why most command line utilities bundled with your operating system can be launched by simply
typing their name. By adding the path to Harmony's command line utilities to this list, merely typing the nameof the utility into a command line will be enough to run it.

How to add Harmony to the system path list on Windows
1. From the Start menu, in the programs list, select Toon BoomToon BoomHarmony 15.0 [Edition]and launch the Configuration Wizard.
2. In the main menu of the Configuration Wizard, select Add Harmony to Path.
3. In the next panel, select the scope to which to add the path to:lSingle User: This will only add Harmony to your list of paths when you're logged in as theuser you are currently logged into.

l

All Users: The path to Harmony will always be in the list of system paths, regardless of whichuser is logged on.

4. Select Next.
5. Click on Finish.

6Harmony 15.0 Utilities User Guide

The next time you open a Command Prompt, the path to Harmony will be included in the system's
list of paths and you will be able to launch Harmony command line utilities by only typing their filename rather than their full file path.
TIP
You can quickly see what is in your list of paths by typing echo %PATH% in the commandprompt. Each path in the list will be separated by a semicolon.

TIP
You can also edit the content of the PATH environment variable, in which those paths are
stored, for your logged in user and for the whole system by using the Environment Variables
panel. To access it, from the Start menu, in the programs list, select Windows 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 will be in the list. Then, it
will 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 when you
upgrade to a new version.

How to add Harmony to the system path list on macOS
1. Open Finder, then select Applications > Toon Boom Harmony 15.0 [Edition] > Tools> Configuration Assistant.
2. In the main menu of the Configuration Assistant, check the Register console application in the path
option. Uncheck all other options and select Continue.
3. In the next panel, select the scope to which to add the path to:lRegister Path for all users: The path to Harmony will always be in the list of system paths,
regardless of which user is logged on.

lRegister Path for my user only: This will only add Harmony to your list of paths when you'relogged in as the user you are currently logged into.

4. Click on Create.

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

The next time you open a Terminal, the path to Harmony will be included in the system's list ofpaths and you will be able to launch Harmony command line utilities by only typing their file namerather than their full file path.
TIP
You can quickly see what is in your list of paths by typing echo $PATH in the commandprompt. Each path in the list will be separated by a colon.

TIP
If you want to remove Harmony from your path, you must manually edit out the configuration
file in which it was 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 own user, open ~/.profile in an editor.

Then, remove the block betwen # 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 was used to install Harmony on your machine. If you deleted it,
download it and unpack it again with the following command:tar -xvzf <name of package>
2. Switch to the directory in which the installer package was unpacked:
cd <path to extracted installer package>
3. Type in the following command:sudo ./install -e
The installer will launch.
4. In the installer, read and agree to the End User License Agreement.
5. Confirm that you want to add Harmony to the PATH environment variable.
6. Once the operation is done, reboot the machine.
The path to Harmony will be included in the system's list of paths.

8

Harmony 15.0 Utilities User Guide

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

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

9

Chapter 2: Running a Utility

Chapter 2: Running a 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 followed 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 following location:lWindows: C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 15.0 [Edition]\win64\binlmacOS (Stand Alone):/Applications/Toon Boom Harmony 15.0 [Edition]/tba/macosx/bin

lmacOS (Server): /Applications/Toon Boom Harmony 15.0 [Edition] Network/tba/macosx/binl

GNU/Linux:/usr/local/ToonBoomAnimation/harmony[Edition]_15.0/lnx86_64/bin
NOTE
By default, to run an utility, you must type its full path followed 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 list ofdefault 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 following:lWindows: Open the Start menu and, in the programs list, select Windows System> Command Prompt.

lmacOS: Open LaunchPad, then select Other > Terminal.

l

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

10Harmony 15.0 Utilities User Guide

2. In the command line, type cd followed by the path to the folder containing the file(s) you want toprocess, then press ENTER.

TIP
When 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 is selected.

lCommand lines use spaces as a way to separate the parameters sent to a command.
If a path contains spaces, you must enter the path between quotes, or add abackslash \ before each space, to indicate that the spaces are part of the path.

lWindows uses backslashes \ to separate the name of directories in a path. macOSand GNU/Linux use forward slashes /.

lAbsolute file paths on Windows begin with a drive letter followed by a colon. Bydefault, the drive on which Windows and your documents are located is C. Hence,
most paths in Windows will start with C:\. On macOS and GNU/Linux, absolute filepaths begin with a forward slash /.

l

You can type file paths that are relative to the current directory by starting the pathwith the name of the first folder name to navigate to. For example, if you're in theDocuments folder and want to go to its MyScene subfolder, simply typing cd
MyScene will work. You can also navigate to folders that are parent of the current
folder by referring to a folder named with two consecutive periods ... For example,
to navigate from the MyScene folder back to its Documents parent folder, typing cd.. will work.

3. Type the name of the utility you wish to use, followed by its parameters. Each parameter will startwith a dash -. Some parameters take extra information, such as file names or colour values. The
following 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 Utility

The command will launch. If no errors are encountered, it will simply display its version information,then exit.
1. Check if the file you expected the command to output is present. On Windows, you can use the dir
command followed by a file name or pattern to query which files are in the current directory. On
macOS or GNU/Linux, you can do that with the ls command:

2. At any time, you can obtain information on how to use an utility by launching it followed with the help parameter.

12

Harmony 15.0 Utilities User Guide

utransform -help

13

Chapter 3: Utilities Reference

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

15

Pix2vec Utility

17

Vectorization

36

How to Vectorize With Bubbles

40

Swf2tvg Utility

44

Swfimport Utility

46

tvg2xml Utility

47

uinfo Utility

48

utransform Utility

49

About Exporting Layouts as Bitmap Using utransform65

How to Export a Layout as Bitmap Using utransform

69

ConsolidateDb Utility

76

14

Harmony 15.0 Utilities User Guide

Pdfimport Utility
PDF Import (Pdfimport) allows you to import a Portable Document File (.pdf) or Adobe Illustrator (.ai) file as aHarmony template without going through the user interface, allows more control and flexibility over the results.
NOTE
Since a Harmony template is a folder containing a scene, this command outputs several files inside afolder. If the target folder exists, it will not overwrite the whole folder, but it will overwrite the files
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 where to store the template. A new directory will becreated in the specified directory, named after the imported .pdf or .ai file
followed with the extension .tpl. The template filles will 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
will be automatically named based on their original file names.

The path to the template directory in which to store the template. The templatefiles will 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 when using this option.

15

Chapter 3: Utilities Reference

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

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

-PDF_SUPPORT_CMYKNOTE
If this option is not enabled and CMYK colours are in the .pdf or .ai file,they will be imported as solid red, and the utility will output thefollowing warning:

CMYK: Unsupported colorSpace-PDF_SEPARATE_LAYERS

Uses the Illustrator top level groups as separate layer names.

-PDF_FLATTEN

Flattens each drawing.

-PDF_LINE_ART_STROKE

Makes the contours of vector shapes "strokes". Contrary to a regular contour,
a stroke will remain in the drawing 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 allows the ink &paint artist to easily paint different parts of the lineart with 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 with the
Paint tool.

-PDF_ALLOW_UNICODE

Allows the use of Unicode-exclusive characters in layer names.

-usageDisplays a list of parameters with their description.

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

Displays the help information.

-v|-version|--version n

Displays the version information.

16

Harmony 15.0 Utilities User Guide

Pix2vec Utility
Pix2vec is an highly flexible and versatile utility for converting scanned drawings 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 well 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 will generated a Toon Boom Vector
Graphic (.tvg) drawing based on the input file, with the bitmap drawing 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 will be based on the input file, but with the extension.tvg.
Pix2vec -file A-1.scan
If the default parameters are not giving the expected results, you can try using Pix2vec with 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 want to use Pix2vec on a series of file, you can script a loop
in your command line. A loop repeats a command while counting from one number to another number in a
specified increments, and that number is stored in a variable to be used by the command, allowing you toiterate through several drawings that have the same base name, but are numbered in a series.
For example, you can iterate through drawings on to 13, numbered on twos, with the following command:l

On Windows, 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 following syntax:l

On Windows, 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 which you can obtain usage
information.

-?

Displays usage information on the specified section. The following
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 will display the version information.

Input/Output Parameters
Parameter-file <filename>-infile <filename>-outfile <filename>

Description

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

Use this option to rename the output file.

18Harmony 15.0 Utilities User Guide

Parameter

Description

NOTE
The filename must include the extension.

-informat <format>

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

-noforce

This option will 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 following parameters configure how the drawing is registered. Registration is the process of analyzing theposition of the drawing'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 which the pegs are to be registered.
Can be one of the following:-register<dpi> <side> <strictness>lb or bottomlt or topll or leftlr or right<strictness>: The strictness with which the registration is evaluated.
Can be one of the following:ll or loosels or strict

19

Chapter 3: Utilities Reference

Parameter-registration_center_peg_
holes

Description

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

-rcph-registration_looseness_factor <factor>

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

-rlf <factor>

By default, the looseness factor is 2.

-rdebug

Outputs debug information about the registration.
The distance between peg bars, in inches.

-pegpitch <inches>-threshr <value>

By default, this is set to 8.
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 between the edge of the paper and its peg holes.

-rmargin <inches>-peg_distance_from_center<inches>-pdfc <inches>

By default, this is set to 1.

The distance between 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 drawings. If it is different
from the side of its actual registration (passed with the -registerparameter), the drawing will be rotated accordingly.

-out_peg_position <side>lsame: The same side as the drawing's actual registration.

lb or bottomlt or topll or leftlr or right

By default, this is set to same.

-output_peg_matrix

Outputs the information about the peg matrix to the terminal.

20

Harmony 15.0 Utilities User Guide

Parameter

Description-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.

Filtering Options
The following parameters configure the way 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 with invisible
strokes, to make closed shapes that can be painted.

-gap <length>

The value sets the maximum length of gaps to close, in world units.
By default, this is set to 10.
Generate pencil lines for the line art.

-pencilThis should not be used with the -no_color_art parameter.
Properly vectorizes line art drawn on a transparent background.

-use_alpha

By default, Pix2vec expects line art to be on an opaque background andwill not properly vectorize line art drawn on a transparent background.
Use this parameter if you are vectorizing drawings with a transparent
background.

-keep_dirt

Disables filtering dirt out from the drawing.

-thresh <value>

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

-vectorize_alphaThe default threshold is 0.2.

-rmv_hairs <length> <passes>

Removes hair, which are short useless strokes extending from closed

21

Chapter 3: Utilities Reference

Parameter

Description

shapes.
The length determines the maximum length of hairs to remove, in world
units. The passes determines the amount of times to remove hairs fromthe whole drawing. Adding extra passes will 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 world units
squared, from the artwork.
The default size of holes to remove is 7.
Removes dirt that is smaller than the defined size, in world units
squared, from the artwork.
The default size of dirt to remove is 1.

-rmv_dirt <size>

TIP
Try removing holes and dirt with a size ranging from 100 to500.

Removes triangles at the defined distance from one another, in world
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 withdifferent 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.

22Harmony 15.0 Utilities User Guide

Parameter

Description-noclosegap

Disables closing gaps. All gaps in the artwork will 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.
This reduces the jaggedness in line art by expanding the lines by the-jag_filter <pixels>

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 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 which three points segments, which makecorners, are interpreted as curves. This means that instead of drawing asegment from point 1 to point 2, then from point 2 to point 3, a single
segment is drawn from point 1 to point 3, with Bezier curves adjusted
for the line to go over point 2. A higher fit error will cause more corners
to be interpreted as curves. A lower fit error will cause the artwork tohave more 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 which three points segments, which makecorners, are interpreted as curves. This means that instead of drawing asegment from point 1 to point 2, then from point 2 to point 3, a single
segment is drawn from point 1 to point 3, with Bezier curves adjusted
for the line to go over point 2. A higher fit error will cause more corners
to be interpreted as curves. A lower fit error will cause the artwork tohave more points. Some fit error is required to avoid having too many
control points.
The default fit error is 1.

23

Chapter 3: Utilities Reference

Parameter

Description

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>-first_smooth <passes>

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

-support_thin_lines

Do not erode thin lines when generating colour art.
Using this parameter allows you to set two sets of parameters, one forvectorizing the line art and one for creating the colour art.
With this option, you can use the following parameters with 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, which may erode thin or light outlines. If you wantto obtain results similar to single-pass vectorization, set this to
0.2.

-threshc <value>

The threshold used for vectorization for the colour art. This can be set toa decimal value ranging from 0 to 1.

24

Harmony 15.0 Utilities User Guide

Parameter

Description

The default threshold is 0.5.

NOTEThis threshold is higher than the default value for single-passvectorization, which may erode thin or light outlines. If you wantto obtain results similar to single-pass vectorization, set this to0.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.
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 world 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 world 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 world 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 world units
squared, for the colour art.
The default size of dirt to remove is 1.

25

Chapter 3: Utilities Reference

Parameter-first_smoothl <passes>

Description

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.
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 drawing.
Sets the field size of the output drawing.

-field_size <fields>-fs <fields>

By default, this is set to:ll

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

26

Harmony 15.0 Utilities User Guide

Parameter

Description

NOTE
Scan files have their own field size. If the field size of the scan
file is different than the field size of the TVG that is generated
from it, its scaling will be affected. Regular bitmap files do nothave a field size, therefore, their dots per inch (DPI) resolution is
automatically adjusted 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 thedrawing, in inches.

-noframe

Disables adding a frame around the colour art.
Adds a frame of the specified size around the colour art. The size mustbe specified in fields.

-frame_fields <fields>

If the frame is made to match the drawing, its element and its scene's
field size, it will fit the scene's camera field perfectly. By default, all ofthese are 12 fields in size.
The default value of this parameter is -1, which uses the drawing's fieldsize.
Downscales the input image before processing it. This does not affectthe dimensions of the vectorized drawing in the scene, only its display
quality. In other words, this is equivalent to pixelating the drawing.

-downscale_input <factor>

The scale factor is an integer used as the denominator. For example, thedefault value is 1, which does not downscale the image, 2 would
downscale the image by half, etc.
Downscales the output texture. This is very similar to -downscale_
input, except that the downscaling is performed on the line art's texture
after the original drawing has been vectorized. This means that thecontours of the outlines and the strokes in the colour art are not affected,
only the texture in the outline is.

-downscale_texture <factor>

Just like -downscale_input, the dimensions of the vectorized drawing
are not affected, so this is equivalent to pixelating the vectorizeddrawing's texture.
The scale factor is an integer used as the denominator. For example, thedefault value is 1, which does not downscale the texture, 2 would
downscale the texture by half, etc.

27

Chapter 3: Utilities Reference

Parameter

Description-buildmatte

Generates a filled matte based on the line art and stores it in the underlay
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.

-copystrokes

When 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 following 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.

28

Harmony 15.0 Utilities User Guide

Parameter

Description-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>

The default value for this parameter is -1, which makes Pix2vec
automatically adjust the DPI resolution of the drawing to make it fit thefield of the drawing.
When vectorizong a multi-layer Photoshop Document (.psd) file, thisparameter allows you to select which layer to vectorize.

-layer <layer name>

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

Red/Green/Blue Keying Options
The following options allow you to vectorize red, green and blue lines as they are coloured, instead of ingreyscale, which 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 thecamera 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 will have an alpha of 1.
You can set their alpha to a different value with the -rgb_
alpha parameter.

-rgb_alpha <value>

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

29

Chapter 3: Utilities Reference

Parameter

Description

When enabled, red, green and blue lines generated with the -rgb
parameter will also have texture.
-rgb_alpha_texture

Contrary to the -flatten parameter, this will 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 work.

-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 drawing 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 want 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, inworld units squared.
The default value for this parameter is 0.
Expands the red, green and blue outlines of the line art by the set amountof pixels, resulting in thicker coloured outlines.
By default, this is set to 0.

-expand_bitmap_rgb<pixels>

TIP
Using this with the -flatten parameter can help overwrite
black lines generated from the coloured lines during regular
vectorization with the vectorized coloured lines, as they may nototherwise overwrite those black lines completely.

30

Harmony 15.0 Utilities User Guide

Parameter-threshrgb <value>

Description

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<saturation threshold><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.

Four Colours Vectorization
The following options allow you to vectorize a drawing with 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 own.
Contrary to Red/Green/Blue vectorization, this will not generate the black line art and add coloured lines on
top. It will generate a single layer of non-textured vector shapes that are either solid red, solid green, solid blue
or solid black, without them overlapping each other. Most of the parameters for this mode are used todetermine how to differentiate red, green, blue, black and white in the source drawing.
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 followed by a colon and then its value.
Parameters must be separated by spaces, but there should be no spaces
between 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:-4colours <key:value> ...
<key:value>llrgbdiff: The threshold for tolerating mixed colours. A lower
value means mixed colours are interpreted as their dominantprimary colour. A higher value means mixed colours areinterpreted as either black or white, depending on their value.
This parameter can be set to a value between 0.0 and 1.0 or
between 0 and 255.
dark: The threshold for differentiating black. A higher valuemeans lighter shades of dark colours and dark greys arevectorized as black. A lower value means only very dark areas arevectorized as black. Can be set to a value between 0.0 and 1.0

31Chapter 3: Utilities Reference

Parameter

Description

or between 0 and 255.
ll

grey: The threshold for the interpretation of greys. Greys below
this threshold are vectorized as black, and greys above thisthreshold are vectorized as white. Can be set to a value between
0.0 and 1.0 or between 0 and 255.
white: The threshold for differentiating white. A lower valuemeans darker shades of light colours and light greys arevectorized as white. A higher value means only very light areas
are vectorized as white. This parameter can be set to a value
between 0.0 and 1.0 or between 0 and 255.

l

l

l

rt: The threshold differentiating red from black. A lower 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
between 0.0 and 1.0 or between 0 and 255.
gt: The threshold differentiating green from black. A lower valuemeans dark green is vectorized as green. A higher value means
dark green is vectorized as black. This parameter can be set to avalue between 0.0 and 1.0 or between 0 and 255.
bt: The threshold differentiating blue from black. A lower 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
between 0.0 and 1.0 or between 0 and 255.

l

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

Bubble options
Bubbles are bumps added along the outlines, giving the impression that the outline was drawn quickly with 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 between them canbe configured.
NOTE
To learn more about the Bubble command, see How to Vectorize With Bubbles on page 40.

32

Harmony 15.0 Utilities User Guide

Parameter

Description-create_bubbles

Randomly adds bubble shapes along the line art.
Sets the maximum number of colour art points between two 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 drawn 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, where 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.

-max_radius <factor>

Defines the maximum radius of a circle in a bubble. This radius is a factor
relative to the line thickness, where 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.

-uniform_height

NOTE
This 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 with image files that have very few solid colours with no antialiasing.
NOTE
Colour vectorization is experimental.

33

Chapter 3: Utilities Reference

Parameter

Description-color_vectorize

Performs a colour vectorization.

-file2 <color art filename>Allows you to specify a bitmap file for the generation of colour art.
Generates a brush texture for the line art.
The parameters are as follows:ll-penstyle <center alpha><edge alpha> <gamma><centre pressure effect><edge pressure effect><texture bitmap downscaling><texture bitmap file>

l

l

l

<centre alpha>: The alpha value in the middle of theline. Can be set to a value between 0.0 and 20.0, although
the greatest difference is visible between 0.0 and 3.0.
<edge alpha>: The alpha at the edge of the line. Can be
set to a value between 0.0 and 1.0. Setting this to 1.0 will
yield a solid line.
<gamma>: The gamma of the texture. A higher value will
make the edge darker, a lower value will make the edge
lighter. This can be set to a value between 0 and 10.
<centre pressure effect>: The pressure at the centreof the line. Can be set to a value between 0.0 and 1.0.
<edge pressure effect>: The pressure at the edge ofthe line. Can be set to a value between 0.0 and 1.0.

ll<texture bitmap scaling>: The scaling factor of thebitmap texture. Can be set to a value between 0.2 and 20.
<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 follows:l-pressure_variation<strategy> <min pressure><max pressure><max variation>

l

l

l

-blur_radius <pixels><strategy>: The strategy to for the distribution ofpressure variation. Can be set to either 0, 1 or 2.
<min pressure>: The minimum pressure used. Can be
set to a value between 0.0 and 1.0.
<max pressure>: The maximum pressure used. Can be
set to a value between 0.0 and 1.0.
<max variation>: The maximum pressure variation. Can
be set to a value between 0.0 and 1.0.

Blurs the generated brush texture. The size of the blur must be

34

Harmony 15.0 Utilities User Guide

Parameter

Description

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 world
units squared, from the line art, when 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 world units
squared, in the coloured line art.
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 own.
Some of the commonly used vectorization styles displayed in the Custom Vectorization Parameters, and theImport Drawings dialog boxes, use parameters similar to the following examples:• Black and White• Tones/highlights (B+W notriangles)• Greyscale Rougher Lines• Greyscale Soft Edge

Black and White
Use this style to vectorize black and white (1-bit) SCAN, or any other black and white files. Black and white 1bit files include no texture information.
options: -no_texture -rmv_holes 7 -rmv_dirt 10 -fit_errorl 2.0 -fit_errorc
2.0
When you vectorize black and white drawings with these options, the vector files will contain no texture (-no_texture); all lines will 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 15.0 Utilities User Guide

Tones/highlights (B+W notriangles)

This style vectorizes black and white 1-bit files that will 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 drawings. 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 drawings, like mattes, that will be painted a solid colour.

Greyscale rougher lines
This style vectorizes greyscale drawings, 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 drawing gets its character from the roughness of its lines. You would
not want to lose the distinctness of the line during the vectorization process.

37

Chapter 3: Utilities Reference

The options in this style force two 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 when you use this option.
For drawings with specific vector-style lines or mattes, you only need one pass. For greyscale drawings, you
may want to pass through the vectorization process twice to apply different values to the line art and colourart.
The colour art (-threshc) and line art (-threshl) thresholds determine what values in the scanned image
will be considered as part of the drawing, and what will be ignored and eliminated in the vectorized drawing.
Zero (0) is white and one (1) is black. The threshold is between these two values.
The expand_bitmap and jag_filter options work 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. When used with jag_filter, the bitmap is shrunk down by the value of the option. You use these
two 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 when you want to create a vector image with 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 will notice that the-thresh values are smaller; therefore, fewer pixels will be filtered out.This contributes to the fluffier38

Harmony 15.0 Utilities User Guide

appearance of the lines. You will 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.

39

Chapter 3: Utilities Reference

How to Vectorize With Bubbles
Vectorizing with bubbles allows the user to modify the original LineArt of a drawing by randomly inserting
bubble shapes.
The command inserts bubbles starts from the circle with the smallest radius (min_radius), with 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
between bubbles. The bubble_gap specifies the maximum number of such points, with the minimum beingzero.

ExamplesDrawing With Uniform Line Thickness
The initial drawing has a uniform thickness. Use it to view and compare the results of the following bubbles
options.

40

Harmony 15.0 Utilities User Guide• Example 1
The drawing has been vectorized using the command options:-create_bubbles -bubble_gap 3 -bubble_length 16 -max_radius• Example 2
The drawing 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 drawing has been vectorized using the command options:-create_bubbles -bubble_gap 3 -bubble_length 16 -max_radius 3.5• Example 4
The drawing has been vectorized using the options:-create_bubbles -bubble_gap 3 -bubble_length 4 -max_radius 3.0 -uniform_gap-uniform_height42

Harmony 15.0 Utilities User Guide

43

Chapter 3: Utilities Reference

Swf2tvg Utility
The Swf2tvg utility is used to import an SWF file into your scene without using the interface. This will create a.tvg file for each frame. Use the different commands to control the options.
Here is the format you must follow when using Swf2tvg:
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 Swf2tvg options:
COMMANDACTIONDESCRIPTION OF SWITCHES-palette <palette_file>

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

-use_different_palettes

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

-base_name <name>

Use this option to automatically rename all generated
drawings name-x.tvg where x is an increasing index.

-start_index <index>

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

-outdir <dir>-use_place_objects

Use this option to define the output directory for all
generated drawings.
This option will transform and position the imported
drawings following the position on the stage in the Flashproject. This option uses the information that is contained in
the SWF 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 15.0 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 drawings according to their boundingbox.
This option implies -ignore_position.

-ignore_position

Use this option to ignore all sceneplanning information.

-usageThis option will display the usage.

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

This option will display the help information.

-v|-version|--version

This option will display the version information.

NOTE• If -outdir is not specified, the files will be written in the SWF file current directory.
• You can specify any SWF file or PLT file. The PLT files will be read and used to match colours
but will not be modified. The only palette modified is the palette specified by the -paletteswitch.

45

Chapter 3: Utilities Reference

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

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

This option will apply colour transforms from SWF onto
the drawings.

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

DESCRIPTION OF SWITCHES-outdir dir

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

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

This option will display the help information.

-v|-version|--version

This option will display the version information.

WARNING
Swfimport does not overwrite templates.

46

Harmony 15.0 Utilities User Guide

tvg2xml Utility
The tvg2xml utility is used for debugging purposes; it will convert your TVG files to an XML file format that you
can read.
Here is the format you must follow when 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 where each pixel of an image
is converted into the black foreground or the whitebackground. The colours and grays of the original image arelost. By controlling discretizing, unwanted parts of theoriginal image can be removed. This process of converting
colour images into black foreground and white backgroundis called discretizing.

-no_bitmap_data

This option will prevent the output of bitmap data. This willproduce a smaller XML files if the bitmap data is not needed.

-flattenThis option will perform a flatten on the layers.

-v|-version|--version

This option will display the version information.

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

This option will display the help information.

47

Chapter 3: Utilities Reference

uinfo Utility
The uinfo utility is used to display the following information about a specified bitmap file.
• Name• Resolution• Format• Channels• Bites per Channels
Here is the format you must follow when using uinfo:
uinfo program input_files
COMMANDACTIONAVAILABLE OPTIONS-?|-h|-help|--help

This option will display the help information.

-v|-version|--version

This option will display the version information.

48

Harmony 15.0 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 50

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

General Parameters
Parameter

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

-?
-h
-help

This option will display the help information.

--help-v-version

This option will display the version information.

--version

49

Chapter 3: Utilities ReferenceFile Output Parameters
The following parameters are used to set the file name and file type of the output files.
Parameter

Description

This is the image format that you want to output with utransform. The
following output image formats are supported:-outformat <format>l

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 which iscomposed of:lll

Their file extension. For example, the format PSDDP4 will output a
Photoshop Document (.psd) file.
Their colour depth, if applicable. The format PSDDP4 specifies"DP", which 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.
If they support different amounts of channels, the amount ofchannels they use. For example:lll

1 means 1 colour channel, which renders in greyscale.
3 means 3 colour channels, which renders in solid
colours.
4 means 3 colour channels + 1 alpha channel, meaning
the format supports transparency values.

50Harmony 15.0 Utilities User Guide

Parameter

Description

NOTES
l

l

l

It is important to specify the output format. If no output
format is specified, utransform will not use the output
format specified in the extension of the output file.
Instead, it will either output in TGA or TVG format,
depending on the parameters.
For formats that have variants, merely specifying the fileextension will also work. It will output images withstandard colour depth (8 bits per channel) in solid
colour (3 channels).
Some of these formats are Toon Boom formats:
l

l

l

l

VAR is a legacy Toon Boom format for exporting
greyscale (matte) images.
OPT is a legacy Toon Boom format for exporting
images in various channel configurations.
SCAN is the format in which the Scan application
records image data from a scanner. It is a greyscale
bitmap format that also contains metadata for theregistration and resolution of the drawing within ascene.
TVG is the standard image format used by Toon
Boom applications for vector drawings as well as
Toon Boom bitmap drawings.

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

Image Processing Parameters
The following options can perform routine transformations on images.

51

Chapter 3: Utilities Reference

Parameter

Description

The dimensions of the output image, in pixels.
-resolution <width> <height>

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

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

NOTE
This option only works 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 will move the image towards the right, and a positive y offset will
move the image towards the top.
The scale factor to apply to the input image. The default value is 1 (noscaling).

-scale <factor>

NOTE
This will not affect the dimensions of the output image. Hence,
when scaling up, the image is liable to be cropped, and when
scaling down, 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.

-turn <angle>

Rotates the input image by the specified angle in degrees. A positive
value will rotate the image counterclockwise, and a negative value will
rotate it clockwise.

52

Harmony 15.0 Utilities User Guide

Parameter

Description

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

Converts the shape of the pixels in the image for use with analog
television formats. The pixel shape of the input image and of the output-ps <input format> <output
format>image must be specified to make the conversion. The following 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 will be laid on solid
white.

-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 works 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 will 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 works if the output file is a regular bitmap andits format supports alpha.

The way the colour values of pixels is encoded relative to their alphavalue. This parameter has two possibles uses:l-premultiply <mode>l

To indicate the premultiplication type of the source image whenconverting a regular bitmap image to a Toon Boom bitmap(.tvg).
To set the premultiplication type of the output image when53

Chapter 3: Utilities Reference

Parameter

Description

converting a Toon Boom Bitmap (.tvg) to a regular bitmap
image (with the -bitmapartonly option).
This parameter supports the following premultiplication modes:llstraight: The colour values are not encoded raw regardless of
their opacity ratio.
black: 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
When exporting Portable Network Graphics (.png) files, theimage is always encoded with no premultiplication (straight).

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

Description

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

lmedium-low: Renders vector artwork with basic antialiasing.

l-antialiasing <quality><exponent>lmedium: Renders vector shapes with improved antialiasing.
Bitmap texture fills will appear blurred.
high: Renders vector shapes with improved antialiasing,
without blurring bitmap texture fills.

The exponent determines how much the image is scaled up before
antialiasing is applied onto it, to then be scaled down. The higher thevalue, the sharper the edges will come out. This value can range between
0 and 3. This value is only applied with medium or high quality
antialiasing.

54Harmony 15.0 Utilities User Guide

Parameter

Description

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

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 when 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 artwork is converted as-is, with its output resolution
matching its canvas size.
If the input file has multiple art layers of the Toon Boom bitmap type, theart layers are merged together before the final conversion. The resolutionof the output image will be based on either one of the following:-bitmapartonlyll

The canvas size of the line art layer in the input file, if there is one
and if it is a bitmap art layer.
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 following parameters can be used to render invisible strokes, the contour of brush strokes and thecentrelines of pencil lines with a colour to make them visible.

-showstrokes

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

-thickness

If unspecified, the default thickness is 1.

55

Chapter 3: Utilities Reference-lineartstrokescolor<red> <green> <blue><alpha>-colorartstrokescolor<red> <green> <blue><alpha>Sets the colour in which to render the strokes in the line art. The colour isdefined 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 which 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 following parameters affect how a Toon Boom Vector Graphic (.tvg) file is aligned and proportioned whenrendered into a bitmap canvas.
Parameter

Description

Determines how the vector artwork is laid out within its canvas.
The following rules are available:
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-align <rule>

The bitmap will be made to fit inside a Harmony scene in a drawing layer
with this alignment rule in its properties.
While most of these options will align the drawing relative to theirinternal canvas, AUTO_ALIGN will automatically centre the artwork 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.

56

Harmony 15.0 Utilities User Guide

Parameter

Description

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 Boomdrawing (.tvg) file. If unspecified, this is set to 8.

-margin <fields>

NOTE
This parameter only affects the output when used with the align parameter set to AUTO_ALIGN.

The field size of the element.

-element_size <fields>

NOTE
This parameter only affects the output when used with the align parameter set to AUTO_ALIGN.

The aspect ratio of the scene to use for processing drawings.
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 when used with the align parameter set to CENTER_FIRST_PAGE_
HORIZONTAL, CENTER_FIRST_PAGE_VERTICAL or AUTO_
ALIGN.

Outputs the coordinates of the input drawing's bounding box to theterminal, in the following format:-printboxx1 y1 x2 y2
Where x1 and y1 are the x and y coordinates of the bottom-left cornerof the box, and x2 and y2 are the x and y coordinates of the top-rightcorner of the box.

57

Chapter 3: Utilities Reference

Parameter

Description

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 verticalfield is equal to 156.25 units.

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

The bounding box to use when aligning the drawing before rendering it,
instead of its normal bounding box. The box is drawn using the x and ycoordinates of its bottom-left corner followed by the x and y coordinatesof its top-right corner.
Adjusts the canvas of the output image to include all of the artwork in
the input drawing 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 well as in an .xml
file named after the output file with the suffix .xml.

PDF Output Parameters
The following parameter is the only parameter that will affect the output when outputting Portable Document
Files (.pdf).
Parameter-fieldsize <field size>

Description

Sets the amount of fields to render PDF files in. This will 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 following parameters are for extracting the centerline from a drawing's line art layer and storing it as
strokes in the colour art layer.

58

Harmony 15.0 Utilities User Guide

Parameter

Description-centerline

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

-keepcolorart-nofitcolorart

When extracting the centreline from the line art, preserve the artwork 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 will 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 artwork. The default
value is 20.

Colour Art Generation Parameters
Like -centerline, the following options will extract the centreline from an art layer and store it in anotherlayer. This option has more flexibility on which 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 artwork inthat layer prior.
-arttoart <source art>
<destination art>
<max resolution> <threshold><fitting error>

To reproduce the effect of the Create Colour Art from Line Art commandin Harmony, simply use it with the following 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 Art

59

Chapter 3: Utilities Reference

Parameter

Descriptionl2: Colour Art

l

4: Line Artl

8: Overlay Art<destination art>: The art layer in which 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 will either be ignored or cut up along their length. Thissetting should be at least as high as the width at which the drawing 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 will be. The lower it is,
the more details will 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 following parameters can be used to generate a matte. A matte is a shape that matches the outlines of theartwork and is filled with a solid colour. Contrary to typical colour art, a matte does not have different colour
zones for a single drawing, and does not require the line art to have a closed shape, so it is useful to fill sketches.
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 lower
radius means the matte will be generated with 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 verticalfield is equal to 156.25 units.

60Harmony 15.0 Utilities User Guide

Parameter

Description

The source and destination art layers can be specified with the following
keywords:loverlayartllineartlcolorartlunderlayart

NOTE
The matte will be filled with a non-indexed colour. You will
hence be prompted to perform colour recovery when viewing thedrawing in Harmony.

-copystrokes

When 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 following parameters can be used to manipulate the different art layers in a Toon Boom Vector Graphic(.tvg) file.
Adds the specified drawing to the output file's overlay art layer.
-addoverlay <drawing>-useoverlayayer <art layer>

If the drawing is a Toon Boom Vector Graphic (.tvg) file, it will use thatdrawing's line art layer by default.
When using the -addoverlay option to add a Toon Boom Vector
Graphic (.tvg) file to a drawing's overlay art layer, this parameter can beused to specify which art layer in the specified drawing to add to theoverlay art layer. Otherwise, the specified drawing's line art layer will be
used.
The following values are supported:-addunderlay <drawing>loverlayartllineartlcolorartlunderlayart

Adds the specified drawing to the output file's underlay art layer.

61

Chapter 3: Utilities Reference

If the drawing is a Toon Boom Vector Graphic (.tvg) file, it will use thatdrawing's line art layer by default.
When using the -addunderlay option to add a Toon Boom Vector
Graphic (.tvg) file to a drawing's overlay art layer, this parameter can beused to specify which art layer in the specified drawing to add to theoverlay art layer. Otherwise, the specified drawing's line art layer will beused.
-userunderlaylayer <artlayer>

The following values are supported:loverlayartllineartlcolorartlunderlayart

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

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

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

Description

Replaces colour IDs in the source file with the specified colour IDs.
This parameter must be specified with the path to a .json file thatspecifies the ID of each colour you want to change, followed by the ID
you want to replace it with, in the following format:-change_color_ids <json file>[{"from" : "source ID",
"to" : "destination ID"},

62

Harmony 15.0 Utilities User Guide

Parameter

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

Reduces the internal resolution of textures in Toon Boom drawing(.tvg) files.
l-reduce_tvg_texture_
resolution <dots per field><max size>l<dots per field>: The maximum resolution of textures indots per field, based on horizontal fields. By default, this is set to72.
<max size>: The maximum size (horizontal or verticaldimension) of textures, in pixels. You can set this to -1 if you do
not want to set a maximum size for textures.

-adjustpencil <multiple><addition>

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

-flatten

Flattens the artwork, making superposed drawing strokes into single
drawing objects, and merging superposed textures together.
Scales the artwork up by the specified scale factor, flattens it, then scales
it back to its original size.

-flatten_scale <scale factor>

This can be useful when attempting to flatten artwork withsuperimposed textured brush strokes. If the pixels in their bitmap
textures are not aligned properly, flattening them may cause some loss of
texture quality. Scaling them up before flattening them can circumvent
this problem.
If using the -flatten option on your artwork causes your bitmap
textures to become blurry, it is recommended to use this parameter withat scale factor of at least 4.
Changes the internal field size of the input drawing.

-setfieldsize <field>

Typically, a drawing's field size should match the field size of the63Chapter 3: Utilities Reference

Parameter

Description

element that contains it in order to appear the right size in the scene. Bydefault, both drawings and elements have a field size of 12. If the fieldsize of the element is bigger than the field size of the drawing, thedrawing will appear bigger. If the field size of the drawing is bigger than
the field size of the element, the drawing will appear smaller.
Normalizes the size of the drawing relative to its field size. This scales-normalize-bboxtvgincrease <percentage>

the artwork up or down so that it fits an element that is 12 fields in size,
then sets the internal scaling of the drawing to 1. If the drawing's fieldsize is bigger than 12, it will be scaled up. If the drawing's field size issmaller than 12, it will be scaled down.
A legacy option that would increase the bounding box of vector artwork.
It is only left in to preserve for compatibility with legacy scripts.

64Harmony 15.0 Utilities User Guide

About Exporting Layouts as Bitmap Using utransformIf you wish 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 within the software, or export them to a third-party bitmap software to paint.
There are two techniques for exporting vector black and white backgrounds:• Render Network• utransform and Exporting a Panoramic Background

Render Network
To export your background image, you can add a Write node to your network and use the Render Write Nodeoption to export the frame where your background is. The background image will 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 will convert the strokes and colour zones that are within the 12 field chart. If
you have extra artwork outside of the 12 field, you will have to scale down the drawing using the utransform
utility in order to fit it in the 12 field zone, and enlarge the bitmap export resolution.
The panoramic background export will work with the alignment rule of your background drawing in your Toon
Boom software.
There are several alignment rules to consider:• Centre Top and Bottom

65

Chapter 3: Utilities Reference• Centre Left and Right• 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 where the default scene’s 12 field isplaced at the centre of the drawing.
Centre Left and Right

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

66

Harmony 15.0 Utilities User Guide

The Centre First Page Horizontal rule is used for a horizontal pan background where the default scene’s 12
field is placed at the far left of the drawing.
Centre First Page Vertical

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

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

The Right rule aligns the drawings with the right side of the alignment rectangle. Harmony scales thedrawings to match their heights to the alignment rectangle of the scene.

67

Chapter 3: Utilities Reference

Top

The Top rule aligns with drawings with the top of the alignment rectangle. Toon Boom Animate scales thedrawings to match their widths to the width of the alignment rectangle of the scene.
BottomThe Bottom rule aligns the drawings with the bottom of the alignment rectangle. Toon Boom Animate scales
the drawings to match the drawings' width to the width of the alignment rectangle of the scene.

68Harmony 15.0 Utilities User Guide

How to Export a Layout as Bitmap Using utransform
The As Is alignment rule is used when you have artwork 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 with the exact resolution that you want the file to be, since you are passing from a vector
based image to a bitmap image.
There are a few rules that will help you understand the calculation that you must perform:• 1 field width equals one inch.
• A 12 field chart has a twelve inch width.
• If you scale your drawing down to fit in the 12 field, you will have to enlarge the output resolution so thatthe final image has the same size as the original drawing (which is not problematic since the source is
vector-based).
• When you re-import your painted background, the bitmap file will be fitted in the 12 field size. You will
have increased the field size so that it fits the original image size.
To find the scale and DPI that you will need to export your image, you will need the following information:• The field size of the drawing.
• The scene resolution.
NOTE
Note that this process will work with a 12x12 scene alignment and when 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 drawing that you want to export.

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

3. In the Drawing view, select all of your drawing strokes. Select Edit > Select All. TheCtrl + A(Windows/Linux) or ⌘ + A (macOS).
4. In the Drawing view, place your mouse cursor over the top, right corner.

69

Chapter 3: Utilities Reference

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

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

70Harmony 15.0 Utilities User Guide

7. Once you have all of your field information, select the greatest X and Y values. These will give you thetotal field size of your drawing. This also tells you the width of your drawing, in inches (1 field width isequal 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 drawing is than the 12 field
Y/12 = How much bigger your drawing is than the 12 field

9. Once you have both scaling values, calculate your official scaling value by dividing 1 by the greater of thetwo values. This will 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 will have to give a precise amount of DPI. In this case, divide yourscene resolution width (Rx) by 12 (fields) to know how many pixels per inch you have.
Rx/12 = Pixels per inch.

71

Chapter 3: Utilities Reference

11. Once you have your scene’s DPI, you need to enlarge it to re-scale your output to the correct size, since
we scaled down the drawing strokes. To do so, multiply the scene’s DPI by how much larger thedrawing is than the 12 field (X/12) or (Y/12).
(Rx/12) x (X/12) or (Y/12) = Amount of DPI needed for the drawing 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 drawing that you
want to convert.

72

Harmony 15.0 Utilities User Guide‣

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 Windows/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 what your command line should look like:‣

For Windows/Linux: utransform -outformat PNG4 -scale 0.75 -dpi 227.55 -bgalpha0 bg-1.tvg‣

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

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

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

The Import Drawings dialog box opens.

73Chapter 3: Utilities Reference

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.

74Harmony 15.0 Utilities User Guide

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 what it should look like: 1.5 x 12 = 18
13. Click on the OK button.

75

Chapter 3: Utilities Reference

ConsolidateDb Utility
The ConsolidateDb command line utility allows you to reduce the amount of drawings in your scene by merging
the elements that have the same drawings together.
ConsolidateDb works by going through the target scene's elements to detect any pair of elements that containthe same drawings, which typically occurs when importing a template several times or when duplicating layers.
If it finds two elements that have the same drawings, it will 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 was originally linked to the duplicate element to the original element. If the duplicate element has
any extra drawings that are not in the original element, those drawings are moved to the original element sothat they do not get removed from the scene.
By default, ConsolidateDb will not merge two elements that appear to match if they have at least one drawing
with the same name, but different artwork, as it would require renaming one of the drawings to keep both ofthem in the same element. With the -renameTiming option, ConsolidateDb will merge elements even if it has
to rename some drawings to keep all of the drawings in both elements. It will also update the Xsheet columns
with the new names of the renamed drawings to avoid affecting the rendered image.
NOTElThis utility only works 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 Parameters tablebelow for a list of available options.

IMPORTANTl

It is possible to add palettes to individual elements, which makes it possible to make twoelements with the same drawings use different colours. If two elements have the samedrawings but have different palettes, ConsolidateDb will merge them together regardless,which will cause them to use the same palette and may affect the colours of the merged elementin the rendered image.

lConsolidateDb will 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.

SyntaxWhen using Harmony Server:

76

Harmony 15.0 Utilities User Guide

ConsolidateDb [options] -env <environment> -job <job> -scene <scene> -user<username>
When 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 which the target scene is located.

-job <job>

The job in which the target scene is located.

-scene <scene>

The name of the target scene.

-user <username>

The Harmony user who will perform the consolidation.

Consolidation Options
By default, ConsolidateDb will not merge two elements ifthey contain drawings with the same name, but not thesame artwork. With this option enabled, ConsolidateDb
will merge elements as long as they have at least one
drawing in common.
-renameTiming

When two drawings have the same name but not the same
artwork, one of the drawings is renamed before it is moved
to the merged element. This allows ConsolidateDb to keep
all the drawings in the both elements without causing any
naming conflict.
The Xsheet columns will be updated to preserve theexposure of drawings getting renamed. Hence, therendered image will not be affected.

77

Chapter 3: Utilities Reference

Parameter

Description-removeEmptyElements

By default, even if ConsolidateDb removes all the drawings
from an element to merge it into another element, it will not
remove the element's directory. Use this option to delete
element directories emptied by ConsolidateDb.
Increases the amount of information reported to theterminal while the scene is being consolidated.
Verbose mode 1 will output the following information:ll

Each drawing file it deletes.

lWhether it deletes each element and why.

-verbose 1-verbose 2

The origin of each drawing in duplicate elements
followed by their destination in the original
element.

Verbose mode 2 will output the following information:ll

The origin and destination of each drawing in boththe original element and its duplicate elements.
Each drawing it removes from or adds to eachcolumn.

lEach drawing files it deletes.

lWhether it deletes each element and why.

Miscellaneous
-?
-h
-help

Displays the usage information in the terminal.

--help-v-version

Displays the version information in the terminal.

--version78