Toon Boom Harmony 12.1
Utilities 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
2015-08-07
Copyright © 2015 Toon Boom Animation Inc. All rights reserved.

2

Harmony 12.1 Utilities Guide

Contents
Toon Boom Harmony 12.1 Utilities Guide

1

Contents

3

Chapter 1: Introduction to Utilities

5

Running a Utility

7

Chapter 3: Utilities

9

Pdfimport Utility

9

Pix2vec Utility

10Vectorization

17Black and White

17

Tones/highlights (B+W notriangles)

18

Greyscale rougher lines

18

Greyscale soft edge

19

How to Vectorize With Bubbles

20

Examples20

Swf2tvg Utility

23

Swfimport Utility

24

tvg2xml Utility

25

uinfo Utility

26

utransform Utility

26

Output a Layout to a Bitmap Format

30

Render Network

30

utransform and Exporting a Panoramic Background

30

As Is

33

3

Harmony 12.1 Utilities Guide

4

Harmony 12.1 Utilities Guide

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.
This guide is divided as follows:•

Running a Utility on page 7•

Pdfimport Utility on page 9•

Pix2vec Utility on page 10•

Swf2tvg Utility on page 23•

Swfimport Utility on page 24•

tvg2xml Utility on page 25•

uinfo Utility on page 26•

utransform Utility on page 26

5

Harmony 12.1 Utilities Guide

6

Harmony 12.1 Utilities Guide

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.
These command line utilities are found in your Toon Boom application folder.
lWindows: \Program Files(x86)\Toon Boom Animation\Toon Boom Harmony 12.1 [edition]\win[x]\binl

Mac OS X: /Applications/Toon Boom Harmony 12.1 [edition]/tba/macosx/binlLinux: /usr/local/ToonBoomAnimation/harmony_12.1/lnx86_64/bin

To run these utilities, use a Command Prompt or Terminal window. All of these utilities work on input files thatare processed using options you specify to produce an output.
How to run a command line utility
1. Open a Command Prompt (Windows) or Terminal (Mac OS X) window or a Console (Linux) window.
‣

Windows: From the Start menu, select Programs > Accessories > Command Prompt.

‣

Linux: Select Menu > System Tools > Terminal.

‣

Mac OS X: Open a Finder window and select Applications > Utilities > Terminal

2. In the Command Prompt or Terminal window, switch to the directory that contains the image files you
want to process (elements folder).

3. Type the name of the utility you want to launch, and the options and name of the file you want to process.
The options must be preceded by a dash (-).
Here is an example of how to launch utransform using Windows:‣

utransform -outformat TGA bg-1.tvg

7

Here is an example of how to launch utransform using Mac OS X:‣

utransform -outformat TGA bg-1.tvg

NOTE: If another version of Toon Boom Harmony is still installed on the system, start the utility application fromthe \bin folder. This will ensure that the correct version of the utility is used.

‣

Windows: \Program Files\Toon Boom Harmony 12.1[edition]\nt\bin>./utransform -outformat‣

Mac OS X: Applications/Toon Boom Harmony 12.1[edition]/tba/macosx/bin>./utransform -outformat‣

Linux: /usr/local/ToonBoomAnimation/harmony_12.1/lnx86/bin>./utransform outformat

4. For help with the options and syntax of the utilities, open the help. To do this, type -help after thename of the utility on the command line.
‣

Type: utransform -help8

Harmony 12.1 Utilities Guide

Chapter 3: Utilities
This chapter describes all of the utilities, options and their uses:•

Pdfimport Utility on page 9•

Pix2vec Utility on page 10•

Swf2tvg Utility on page 23•

Swfimport Utility on page 24•

tvg2xml Utility on page 25•

uinfo Utility on page 26•

utransform Utility on page 26

Pdfimport Utility
The Pdfimport utility is used to import a .PDF or an .AI file as a template without going through the interface. It
allows more control and option flexibility over the imported file.
Here is the format you must follow when using Pdfimport:
Pdfimport [options] pdf or ai files
The available Pdfimport options are:Command

Action-outdir output_folder

This option defines the folder where the output files will besaved. The defined path is not relative.

-outtemplate output_folder.tpl

This option defines the template name for the converted
pages. The defined path can be relative.

-PDF_SUPPORT_CMYKThis option will automatically convert CMYK colours to
RGB. Otherwise, CMYK colours would import as a red
colour.

-PDF_SEPARATE_LAYERS

This option will use the Illustrator top level groups as
separate drawing names.

-PDF_FLATTEN

Use this option to perform a flatten on each drawings while
importing.

Description of Switches-outtemplate output_folder.tpl

Output template name for converted pages.

-outdir dir

This option defines the output folder for the templates (thedefined folder must already exists.)-usageThis option will display the usage.

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

This option will display the help information.

-v|-version|--version nThis option will display the version information.

9

Chapter 3: Utilities

NOTE:• The -outdir and -outtemplate options are exclusive; they cannot be used together.
•

You can only specify one file with the outtemplate option.

•

If the CMYK colours option is not enabled, the application will output the following error message:
CMYK: Unsupported colorSpace•

Pdfimport does not overwrite existing templates, but will overwrite files in outdir.

Pix2vec Utility
The Pix2vec program converts bitmap files, which can be generated during the scanning process, toToonboom Vector Graphic (TVG) files. TVG is the vector file format for Toon Boom professional software.
You can vectorize SCAN and other bitmap files by running Pix2vec from the command line. There are a numberof options you can use. To see a list of the vectorization options, type pix2vec --help or pix2vec -? .
Here is the format you must follow when using Pix2vec:$ Pix2vec -file [file name, including extension] [options]
Here are the available Pix2vec options:
COMMANDACTIONFILE IO OPTIONS
Use this option to define the file you want toperform Pix2vec on.

-file <filename (including extension)> [options ]This option is the same as -file.
-infile <filename (including extension)>

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

-outfile <filename>

Use this option to rename the output file.

-informat <format>

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

-debugUse this option to turn on the debug mode.

-version

This option will display the version information.

-output_version [version]

This option defines the output files of thisversion. Valid versions can be: 0 or 604. The
TVG format version is 604.

-noforce

This option will prevent the output image frombeing forced if the image is inconsistent.

REGISTRATION OPTIONS
Use this option to perform optical registration.
Follow this format:-register<dpi side strictness>;

10Harmony 12.1 Utilities Guide

COMMANDACTIONThe Side position can be left, right, top, bottom
or l, r, t, b.
The Strictness can be either loose, strict or l, s.

-registration_looseness_factor <factor>

Registration looseness factor (by default thelooseness factor is 2.0). This is used for opticalregistration only and is calculated
mathematically by the system.

-rlfThis option is the short hand equivalent of theregistration_looseness_factor function.

-rdebug

This option output registration debug
messages-pegpitch <inch (default 8.000000)>

Use this option to customize the value of the
distance between the registration marks.

-threshr < (default 0.500000)>

Use this option to set the threshold value for
optical registration.
You can set the value in the range of 0.0 to 1.0.

-rmargin <inch (default 1)>

Use this option to define the size of the region
where registration marks can be detected.

Use this option to determine the distance-peg_distance_from_center <inch (default 5.25)
between the centre of your page to the peg>
registration marks.
This function is the short equivalent of peg_
distance_from_centre.
-pdfc

Use this option to determine the distance
between the centre of your page to the peg
registration marks.
This option defines the wanted position of thepeg on the drawing.

-out_peg_position <side (default same)>

The position can be right, left, top, bottom, r, l,t, b or same.
A rotation will be performed if this position isdifferent from the side passed to -register.

-output_peg_matrix

This option outputs the peg transformation
matrix on standard output.

-scanner_calibrate < (default 1.0000 1.0000) >This option sets the x and y scale factors to be
applied to scanner image.

FILTERING OPTIONS-pixel <pixel_shape (default '4x3')>

The valid value is: 4x3.

-gap <worldUnits (default 10)>

Use this option to set the size of gaps that will

11

Chapter 3: Utilities

COMMANDACTIONbe automatically closed.

-pencil

Use this option to generate line art only.

-keep_dirt

Use this option to not filter dirt.

-thresh <threshold (default 0.2)>

Use this option to set the threshold value.

-rmv_hairs <worldUnits (default 1)> <passes(default 1)>

Use this option to remove hair smaller than thedefined size in a specific number of passes.

-rmv_holes <area (default 7)>

Use this option to remove holes smaller thanthe defined area size.

-rmv_dirt <area (default 1)>

This option will remove dirt smaller than thedefined size. You can set values in the range of
100 to 500. The size, or area, is in world units
squared.

-rmv_triangles <worldUnits (default 30.000000)>

Use this option to remove triangles at thedefined pixel distance from each other.
You can use -no_break to remove all triangles.

-no_textureThis option prevents textured strokes to begenerated.

-color_as_textureThis option will vectorize the alpha channel andput the RGB colour in a textured colour.

-noclosegap

This option will prevent gaps from being
automatically closed.

-no_breakThis option disables the breaking of line art.
This option will expand the pixels in thevectorization bitmap to give a jagged line amore straight and smooth result.

-jag_filter <pixels (default 0>This makes use of the -expand_bitmap option
to expand the line by 1 or 2 pixels and thencontract it by the same amount, removing any
jaggedness from the line in the process.
This option expand the pixels in thevectorization bitmap.

-expand_bitmap <pixels (default 0>This is used to thicken the line.
This option defines the fit error for the colourart.
A fit error occurs when there are three points
on a curved or angled line and the system
misses the middle point. For example, insteadof a the line going from point 1 up to point 2
and then down to point 3, to form a curve or-fit_errorc <error (default 1.000000>

12

Harmony 12.1 Utilities Guide

COMMANDACTION
angled line, it goes from point 1 to point 3
missing point 2 and creating a straight line.
Using the -fit_error option eliminates this error.
This option defines the fit error for the line art.

-fit_errorl <error (default 1.000000>

A fit error occurs when there are three points
on a curved or angled line and the system
misses the middle point. For example, insteadof a the line going from point 1 up to point 2
and then down to point 3, to form a curve or
angled line, it goes from point 1 to point 3
missing point 2 and creating a straight line.
Using the -fit_error option eliminates this error.

-smoothl <passes (default 1>

This option defines the number of smooth
passes for the line art.

-smoothc <passes (default 1>

This option defines the number of smooth
passes for the colour art.

-first_smooth <passes (default 0>This option defines the number of smooth
passes on the line art before breaking triangles.

-first_smoothl <passes (default 0>This option defines the number of smooth
passes for line art before breaking triangles.

-first_smoothc <passes (default 0>This option defines the number of smooth
passes to perform. For line art in colour art
pass (needs -2pass).

-2passThis option specify 2 sets of parameters; onefor line art "l", one for colour art "c"(-thresh, rmv_holes and -rmv_dirt will be overridden by threshl, -threshc, -rmv_holesl, -rmv_holesc, rmv_dirtl and -rmv_dirtc).

-threshl <threshold for line art (default 0.5)>

This option sets the threshold value for the line
art.
Range can be from 0.0 to 1.0.

-threshc <threshold for color art (default 0.5)>

This option sets the threshold value for thecolour art.
Range can be from 0.0 to 1.0.

-jag_filterl <pixels (default 0>This option expands the pixels in thevectorization bitmap for line art. To smoothand straighten jagged lines.

-jag_filterc <pixels (default 0>This option expands the pixels in thevectorization bitmap for colour art. To smoothand straighten jagged lines.

-expand_bitmapl <pixels (default 0>This option expands the pixels in the13Chapter 3: Utilities

COMMANDACTION
vectorization bitmap for line art.

-expand_bitmapc <pixels (default 0>This option expands the pixels in thevectorization bitmap for colour art.

-rmv_holesl <area (default 7)>

This option removes line art holes smaller than
the specified area.

-rmv_holesc <area (default 7)>

This option removes colour art holes smaller
than the specified area.
This option will remove dirt on the line art thatis smaller than the defined size.

-rmv_dirtl <area (default 1)>
You can set values in the range of 100 to 500.
The size, or area, is in world units squared.
This option removes dirt on the colour art thatis smaller than the defined size.
-rmv_dirtc <area (default 1)>
You can set values in the range of 100 to 500.
The size, or area, is in world units squared.
-margins <inch (default 0.25)>

This option removes the margin aroundbitmap.You must define the size of the margin
in inches.

-top_margin <inch (default 0.25)>

This option removes the top margin of bitmap.
You must define the size of the margin in inches.

-bottom_margin <inch (default 0.25)>

This option removes the bottom margin ofbitmap. You must define the size of the margin
in inches.

-left_margin <inch (default 0.25)>

This option removes the left margin of bitmap.
You must define the size of the margin in inches.

-right_margin <inch (default 0.25)>

This option removes the right margin ofbitmap. You must define the size of the margin
in inches.

-remove_peg_bars

This option removes the registration marks.

-field_size <fields (default 12 or use value in scanThis option sets the drawing to this field size.
file)>
This is the abbreviated version of -field_size
function.

-fs

Use this option to set the drawing field size.
-peg_bar_size <inch (default 1)>

This option sets the size of the peg bar region.

-noframe

This option prevents a frame being added
around the colour art.

-frame_fields <default -1.000000>

This option will put a frame of the specified
dimension around the colour art.

14

Harmony 12.1 Utilities Guide

COMMANDACTION-downscale_input <default 1> t

This option downscales the raw input by thisinteger factor.

-downscale_texture <default 1>

This option downscales the output texture bythis integer factor.

-buildmatteThis option will automatically generate a matteon the underlay layer for quick line test.

-buildmatte_colourart

This option will automatically generate a matteon the colour art layer for quick line test.
This option will copy the original strokes whenbuilding the matte.

-copystrokes
Note that -buildmatte and -buildmatte_colourart are mutually exclusive.
Options for bitmap that have no registration
information-pixel_margins <inch (default 0)>

This option sets the size in inches for the bitmap
margin.

-top_pixel_margin <inch (default 0)>

This option sets the size value in inches for thebitmap top margin.

-bottom_pixel_margin <inch (default 0)>

This option sets the size value in inches for thebitmap bottom margin.

-left_pixel_margin <inch (default 0)>

This option sets the size value in inches for thebitmap left margin.

-right_pixel_margin <inch (default 0)>

This option sets the size value in inches for thebitmap right margin.

-dpi <(default -1)>

This option defines the dpi information of input
bitmap.

RGB KEYING OPTIONS-rgb

Use this option to generate separate zones forred green and blue lines.

-rgb_alpha <value (default 255)>

Use this option to set an alpha value for red,green and blue colours.

-no_redUse this option to ignore the colour red duringvectorization.

-no_green

Use this option to ignore the colour green
during vectorization.

-no_blue

Use this option to ignore the colour blue duringvectorization.

-flatten

Use this option to perform a flatten on thedrawing after generating the colours.

15

Chapter 3: Utilities

COMMANDACTION-rmv_rgb_dirt <threshold area default 0.0>

Use this option to remove red, green and blue
regions smaller than the specified area.

-expand_bitmap_rgb <pixels (default 0>This option expands the pixels in thevectorization bitmap for rgb.

-threshrgb <value> <threshold for rgb
vectorization default 0.200000>

This option defines the thresholds on rgb
vectorization and value to consider a pixel to begray.

-threshsv <saturation threshold default
0.500000> <value threshold default 0.500000>

This option defines the thresholds on saturationand value to consider a pixel to be gray.

COLOUR VECTORIZATION OPTIONSNote that the following colour vectorization
options are experimental.

-color_vectorize

Use this option to perform a colour
vectorization.

-file2 <color art filename>

This option specifies the colour art bitmap file
to perform vectorization on.

-penstyle <center alpha (0.0-20.0)> <edge alpha(0.0-20.0)> <gamma (0-10)> <centre pressure
effect (0.0-1.0)> <edge pressure effect (0.0-1.0) Use this option to generate and set a brush><texture bitmap downscaling (0.2-20)>
texture for the line art.
<texture bitmap file (valid filename or "" if nofile)>-pressure_variation <strategy (0, 1 or 2)> <minpressure (0.0-1.0)> <max pressure (0.0-1.0)><max variation (0.0-1.0)>

This option specifies a pressure strategy for thecentre line.

-blur_radius <pixels (default 0)>

This option blurs the generated brush texture.

This option sets the performed number of-color_contour_smooth_passes <times (default
smooth passed on contour before computing
3)>
texture.
This is the abbreviated version of the -color_
contour_smooth_passes function.
-ccsp <times (default 3)>

This option sets the performed number ofsmooth passed on contour before computing
texture.

-color_rmv_holesl <world units (default
0.000000)>

This option sets the size of holes to be removed
when computing texture.

-color_fill_holesl <world units (default 0.000000) This option will automatically fill holes of the>selected size on the colour art layer.
BUBBLE USAGE

To learn more about the Bubble command,(implemented only for colour vectorization's line refer to the How to Vectorize With Bubbles
section.
art)

16Harmony 12.1 Utilities Guide

COMMANDACTION-create_bubbles

This option modifies the original line art of adrawing by randomly inserting bubble shapes init.

-bubble_gap <value (default 3)>

This option defines the maximum number ofcolour art points between two consecutive
bubbles.

-bubble_length <value (default 10)>

This option defines the maximum number ofdifferent radius circles in a single bubble.

-min_radius <value (default 1.5000)>

This option defines the minimum radius of acircle in a bubble relative to the line thickness(must be >= 1.0).

-max_radius <value (default 3.5000)>

This option defines the maximum radius of acircle in a bubble relative to the line thickness(must be >= 1.0).

-uniform_gap

This option specifies that the bubbles should beplaced at equal distance from each other.

-uniform_heightThis option forces the height of the bubbles tobe the same for all bubbles.

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 1-bit
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 that they
are smoother.

17

Chapter 3: Utilities

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.

18

Harmony 12.1 Utilities Guide

The options in this style force two passes of the vectorization process to apply different values to the line art andcolour 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 colour art.
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 the Grayscalerougher 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 fluffier appearanceof the lines. You will also notice that the fit_error value is smaller and the -expand_bitmap value is larger. Allof these options contribute to the smoother appearance of the final line.

19Chapter 3: Utilities

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.

20

Harmony 12.1 Utilities 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

21Chapter 3: Utilities•

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_height22Harmony 12.1 Utilities Guide

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 this option to define the output directory for all
generated drawings.

-use_place_objects

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
23

Chapter 3: Utilities

COMMANDACTIONthe SWF PLACE_OBJECT record.
Note: this option does not use -start_index.
This option uses the comma separated list of names togenerate timing information.

-frame_alias <list>

This is mainly to convert models.
e.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 -palette switch.

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.

24Harmony 12.1 Utilities Guide

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.

Swfimport does not overwrite templates.

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.

NOTE: Discretize is a process where each pixel of an image-discretize [optional scale default = 0.1] is converted into the black foreground or the whitebackground. The colours and grays of the original image
are lost. By controlling discretizing, unwanted parts of theoriginal image can be removed. This process of converting
colour images into black foreground and whitebackground is 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 notneeded.

-flattenThis option will perform a flatten on the layers.

25

Chapter 3: Utilities-v|-version|--version

This option will display the version information.

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

This option will display the help information.

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.

utransform Utility
The utransform program converts vector images to pixmaps, and between different pixmap file formats. For
example, you can use utransform to convert a TGA to an SGI file. Or, you can convert a TVG file to a
Photoshop PSD file.
Here is the format you must follow when using utransform:
utransform -outformat [options] [file name, including extension]
Here are the available utransform options:

COMMANDACTIONOPTIONSThis is the file type you want to output with utransform.

-outformat <format>

The following are the file formats supported byutransform: TGA, TGA1, TGA3, TGA4, SGI, SGI1, SGI3,
SGI4, SGIDP3, SGIDP4, OMFJPEG, OPT, OPT1, OPT3,
OPT4, PSD, PSD1, PSD3, PSD4, PSDDP3, PSDDP4,
YUV, PAL, and SCAN.
This option is for the file name of the output file.

-outfile <name>

If you are processing multiple files, you will not be able

26

Harmony 12.1 Utilities Guide

COMMANDACTION
to control their final name. If not specified, the files
created by utransform will have the same file name as
the original. The only difference will be the file extension.

-crop

Outputs part of a tvg where the lines are. A bitmap of
the bounding box around those lines is output as well as
an XML file with the position of that bitmap in relation to
the Camera view.

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

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

This option will display the help information.

-v|-version|--version

This option will display the version information.

IMAGE OPTIONS-resolution <w> <h>This option manages vector and pixmap input files. It
indicates the height and width of the output file.

-resolution scanThis option will use the.scan info to determine thedrawing resolution when unvectorizing from the Control
Centre.
Use this option to scale the height and the width of theoutput file by the value you enter.

-scale 

The resolution of the image must be able toaccommodate the new image size.
Use this option to scale the width of the output file.
-xscale 


The resolution of the image must be able toaccommodate the new image size.
Use this option to scale the height of the output file.

-yscale 
-turn <degrees>

The resolution of the image must be able toaccommodate the new image size.
Use this option to rotate the output file by the amountof degree entered.
Use this option to convert the shape of the pixel.

-ps <in> <out>This option inputs and outputs pixel shapes for formats
other than YUV and PAL.
The possible values are: square, NTSC and PAL.
This option defines the background colour for TVG
images.

-bgcolor <r> <g> <b>
The range is either 0-1 (a percentage of 255) or 0 - 255.
The default value is white.

27

Chapter 3: Utilities

COMMANDACTION
This is the alpha value of the background.

-bgalpha <a>

The range is either 0-1 or 0 - 255. The default value isopaque (255).

VECTOR OPTIONS
quality = low, medium-low, medium or high exponent =between 0-3-antialiasing <quality><exponent>

This option is for converting vector images to pixmaps.
You can specify the quality of the anti-aliasing process(low, medium-low, medium or high) or the exponent(between 0-3).

-nolinetextureThis disables the generation of line textures from TVG
files.

-nolineart

Use this option to exclude line art from the output file.

-nocolorart

Use this option to exclude colour art from output file.
Use this option to recentre the output file, output pixels
or world units for TVG output-move <x> <y>Note: Useful values for TVG output might be714.285000 in x or 535.713750 in y-flatten

Use this option to flatten the drawing and merge its
textures.
By default the output file format is TVG.

-bboxtvgincrease

This option will increase the .tvg bonding box size. The
default value is 5 (percent).
This option normalizes the TVG. This implies that theoutformat is TVG.

-normalize
If the TVG has a different scaling than 1, it will scale thecoordinates and set the scaling to 1.0.
-setfieldsize <f>

Use this option to set the internal scaling of the TVG toan exact field size.

VECTOR TO VECTOR OPTIONS-centreline

Use this option to extract the centreline of the drawing’sline art.

-closegap

Use this option to perform Close gap.
Use this option to define a Close gap length value.

-gaplength
The default value is 10.
-hairpasses

Use this option to set the number of pass to perform forthe remove hair option. The default value is 2.

28

Harmony 12.1 Utilities Guide

COMMANDACTION-hairlength

Use this option to define the value for the hair length.
The default is 20.

-keepcolorart

Use this option to keep the existing colour art andextract the centreline over it.

-showstrokes

Use this option to show the contour of line art andcentrelines in special colours.

-thickness

Use this option to define the thickness in pixels of thestrokes to show.
Use this option to set the field size for PDF output.

-fieldsize <fs>
The default field size is 12.
-lineartstrokescolor <r> <g> <b> <a>

Use this option to define the red, green, blue, alphavalues for the line art stroke colour.

-colorartstrokescolor <r> <g> <b><a>

Use this option to define the red, green, blue, alphavalues for the colour art stroke colour.

-nofitcolorart

Use this option if you do NOT want to generate Bezier
curves for colour art.
This option will convert to older/supported vector
format product version:
v720 = 1005

-tvgversion [version]

v710 = 1005
v702 = 1004 (Early version of 7.0.2 were using1003.)
v700 = 1003

ALIGNMENT OPTIONS
Use this option to generate a bitmap that will fit inside
Harmony with a read node aligned with a defined rule.
-align <RULE>-dpi <dpi>

RULE can be: AS_IS, CENTER_TB, CENTER_LR,
CENTER_FIRST_PAGE_HORIZONTAL, CENTER_FIRST_
PAGE_VERTICAL, TOP, BOTTOM, LEFT, RIGHT.
Use this option to define the output resolution for thebitmap image in dots per inch.
The default resolution is 75 dpi.

-sar <scene_aspect_ratio>

This option sets the scene aspect ratio, the default is
1.33333. Use 1.7777777 for 16/9 scenes. The scene
aspect ratio can be read from the scene alignment
dialog. Beware, that this is not the ratio of the scene
resolution.

29

Chapter 3: Utilities

Output a Layout to a 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
to the scene resolution.
If you have a panoramic background, use the utransform utility to export your image.

NOTE: Refer to the Toon Boom Harmony User Guide to learn how to render your background from your network.

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•

Centre Left and Right

30

Harmony 12.1 Utilities Guide•

Centre First Page Horizontal•

Centre First Page Vertical

•

Left

•

Right

•

Top

•

BottomCentre Top and Bottom

The Centre Top and Bottom rule is used for a vertical pan background where the default scene’s 12 field is placedat 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

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

31

Chapter 3: Utilities

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 the drawings
to match their heights to the alignment rectangle of the scene.

32Harmony 12.1 Utilities GuideTop

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 thedrawings to match the drawings' width to the width of the alignment rectangle of the scene.

As Is
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 to provide
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.

33

Chapter 3: Utilities

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 (Mac OS X).
4. In the Drawing view, place your mouse cursor over the top, right corner.

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

34

Harmony 12.1 Utilities Guide

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

7. Once you have all of your field information, select the greatest X and Y values. These will give you the total
field size of your drawing. This also tells you the width of your drawing, in inches (1 field width is equal to
one inch).

8. Divide the X and Y field values by 12 to know how much to scale the image to fit it in the 12 field.
X/12 = how much bigger your 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

35

Chapter 3: Utilities

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.

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 the drawing 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.

36

Harmony 12.1 Utilities Guide

13. In the Command Prompt, go to the scene’s element directory that contains the *.tvg drawing that you
want to convert.

‣

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 Mac OS X: ./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 Mac OS X: ./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.

37Chapter 3: Utilities

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.

38Harmony 12.1 Utilities 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.

39

Harmony 12.1 Utilities Guide

40