Utilities User GuideLegal Notices
Published by Toon Boom Animation Inc.
Corporate Headquarters
7 Laurier Avenue East
Montreal, Quebec
Canada H2T 1E4
Tel: (514) 278-8666
Fax: (514) 278-2666
toonboom.com

Disclaimer
The content of this manual 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). Please refer to the License Agreement and to those special terms and conditions for details.
The content of this manual is the property of Toon Boom Animation Inc. and is copyrighted. Any reproduction in whole
or in part is strictly prohibited.
For additional copies of this manual, please contact Toon Boom Animation Inc. at the Corporate Headquarters
address.
Copyright © 2010 by Toon Boom Animation Inc. All rights reserved.

Trademarks
Toon Boom Animate is a trademark owned by Toon Boom Animation Inc. All other trademarks are the property of
their respective owners.

Credits
Documentation Development: Peter Cawthorne
Content Development: Marie-Eve Chartrand, Anouk Whissell, Shabana Ali
Art Development: Marie-Eve Chartrand, Anouk Whissell, Shabana Ali, Tania Gray, Annie Rodrigue
Product Manager: Sébastien Miglio

Publication Date
March 2010

Contents
Chapter 1: Introduction to Utilities ...................................................................................................................... 3
Running a Utility .......................................................................................................................................................... 4

Chapter 2: Utilities ...................................................................................................................................................... 7
Pdfimport Utility ......................................................................................................................................................... 8
Swf2tvg Utility ............................................................................................................................................................ 9
Swfimport Utility ...................................................................................................................................................... 10
uinfo Utility ............................................................................................................................................................... 10
utransform Utility ..................................................................................................................................................... 11

Index ............................................................................................................................................................................... 15

1

Animate 2 Utilities User Guide

2

Chapter 1
Introduction to Utilities

Toon Boom provides utilities that you can use in Command Prompt and Shells to provide more flexibility and control
over the different command options in Toon Boom Animate.
In this chapter, you will learn about:•

Running a Utility, on page 4

In this guide, you will find the following utilities:

•
•
•
•
•

Pdfimport Utility, on page 8
Swf2tvg Utility, on page 9
Swfimport Utility, on page 10
uinfo Utility, on page 10
utransform Utility, on page 113

Animate 2 Utilities User 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.
For example, for Toon Boom Animate:••

Using Windows, these utilities are located in:\Program Files\Toon Boom Animation\Animate 2\nt\binUsing Mac OS X, these utilities are located in:/Applications/Toon Boom Animate 2/tba/macosx/bin

To run these utilities, use a Command Prompt or a Terminal window. All of these utilities work on input files that areprocessed using options you specify to produce an output.
To run a command line utility:
1.

Open a Command Prompt (Windows) or Terminal (Mac OS X) window.
Using Windows, click on the Start menu and selectPrograms > Accessories > Command Prompt.

Using Mac OS X, open a Finder window and selectApplications > Utilities > Terminal
In the Command Prompt or Terminal window, switch to the directory that contains the image files that you wantto process (element’s folder).


2.

3.

Type the name of the utility that you want to launch, the options and the 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

Here is an example of how to launch utransform using Mac OS X.:
utransform -outformat TGA bg-1.tvg

Note: before launching the utility you need to define an environment variable.

4Chapter 1: Introduction to Utilities
Note: If another version of Animate or Animate Pro is still installed on the system, the utility application should
be launched from the \bin folder. This will make sure that the correct version of the utility is used.
If using Windows:\Program Files\Toon Boom Animation\Toon Boom Animate 2\nt\bin\ utransform -outformat• If using Mac OS X:/Finder/Applications/Toon Boom Animate 2/tba/macosx/bin> ./utransform -outformat
4. For help with the options and syntax of the utilities, open the help. To do this, type
-help after the name of the utility on the command line.
 type: utransform -help•

5

Animate 2 Utilities User Guide

6

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

•
•
•
•
•

Pdfimport Utility, on page 8
Swf2tvg Utility, on page 9
Swfimport Utility, on page 10
uinfo Utility, on page 10
utransform Utility, on page 117

Animate 2 Utilities User Guide

Chapter 2: Utilities Pdfimport Utility

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:

COMMANDACTIONAVAILABLE OPTIONS-outdir output_folder

This option defines the folder where the output files will be saved. 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_LINE_ART_STROKEThis option will set the stroke attribute on contours of line art.

-PDF_BREAK_LINE_ART

This option will break the line art at intersection points.

-PDF_GENERATE_COLOUR_ART

This option will extract the centreline of the line art and put it in the colour
art.

-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 (the defined 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.

•
•
•
•

8

The -outdir and -outtemplate options are exclusive, they can not 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.

Chapter 2: Utilities Swf2tvg Utility

Swf2tvg Utility
The Swf2tvg utility is used to import an SWF file into your scene without using the interface. This will create a .tvg filefor 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 the palette fileand save it.

-use_different_palettes

This option is used to create a new palette for each SWF file and 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 the drawings.
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 Flash project. This option uses theinformation 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 to generate timing
information.
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 bounding box.
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.

9

Animate 2 Utilities User Guide

Chapter 2: Utilities Swfimport Utility

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 to use 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.

NOTE:
Swfimport does not overwrite templates.

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

•
•
•
•
•

Name
Resolution
FormatChannels
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.

10Chapter 2: Utilities utransform Utility

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 -file [file name, including extension] [options]
Here are the available utransform options:

COMMANDACTIONOPTIONS-outformat <format>

This is the file type you want to output with utransform.
The following are the file formats supported by utransform: TGA, TGA1,
TGA3, TGA4, SGI, SGI1, SGI3, SGI4, SGIDP3, SGIDP4, OMFJPEG, OPT,
OPT1, OPT3, OPT4, PSD, PSD1, PSD3, PSD4, PSDDP3, PSDDP4, TVG,
PDF, PNG, PNG4, YUV, PAL, and SCAN.

-outfile <name>

This option is for the file name of the output file.
If you are processing multiple files, you will not be able to control their
final name. If not specified, the files created by utransform will have thesame file name as the original. The only difference will be the fileextension.

-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|--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 the drawing resolution
when unvectorizing from the Control Centre.

-scale 


Use this option to scale the height and the width of the output file by thevalue you enter.
The resolution of the image must be able to accommodate the new image
size.

-xscale 


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

-yscale 


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

-turn <degrees>

Use this option to rotate the output file by the amount of degree entered.

-ps <in> <out>

Use this option to convert the shape of the pixel.
This option inputs and outputs pixel shapes for formats other than YUV
and PAL.
The possible values are: square, NTSC and PAL.

-bgcolor <r> <g> <b>This option defines the background colour for TVG images.
The range is either 0-1 (a percentage of 255) or 0 - 255. The default value
is white.

11

Animate 2 Utilities User Guide

Chapter 2: Utilities utransform Utility

COMMANDACTION-bgalpha <a>This is the alpha value of the background.
The range is either 0-1 or 0 - 255. The default value is opaque (255).

-arttoart

Will perform the same function as lineArtToColourart from the UI exceptthat it can use any source art combination and output the result in any
other art, clearing it before adding.
1 = underlay, 2 = colourArt, 4 = lineArt, 8 = overlay-addoverlay

Specify an overlay file to add in composition-addunderlay

Specify an underlay file to add in composition-useoverlaylayer

Specify art from drawing to use in overlay,(lineart,colorart,overlayart,underlayart)-useunderlaylayer

Specify art from drawing to use in underlay,(lineart,colorart,overlayart,underlayart)-clearlayers

Clear specific art layers,(lineart,colorart,overlayart,underlayart)-automatte

Computes the auto matte of art src and put it in art dst. (src and dst must
be different and must be one of lineart, colorart, overlayart, underlayart).
Radius is expressed in model coordinates, 1 field of a 12 fields drawing isroughly 200 model units.

-copystrokes

Copy original strokes in destination when doing an auto-matte.

VECTOR OPTIONS-antialiasing <quality><exponent>

quality = low, medium-low, medium or high exponent = between 0-3
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.

-move <x> <y>Use this option to recentre the output file, output pixels or world units for
TVG output
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).

-normalize

This option normalizes the TVG. This implies that the outformat is TVG.
If the TVG has a different scaling than 1, it will scale the coordinates andset the scaling to 1.0.

-setfieldsize <f>

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

VECTOR TO VECTOR OPTIONS-centreline

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

-closegap

Use this option to perform Close gap.

12

Chapter 2: Utilities utransform Utility

COMMANDACTION-gaplength

Use this option to define a Close gap length value.
The default value is 10.

-hairpasses

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

-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 and extract the centreline
over it.

-showstrokes

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

-thickness

Use this option to define the thickness in pixels of the strokes to show.

-fieldsize <fs>

Use this option to set the field size for PDF output.
The default field size is 12.

-lineartstrokescolor <r> <g> <b> <a>

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

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

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

-nofitcolorart

Use this option if you do NOT want to generate Bezier curves for colour
art.

-tvgversion <version>

This option will convert to older/supported vector format product version:
v720 = 1005
v710 = 1005
v702 = 1004 (Early version of 7.0.2 were using1003.)
v700 = 1003

ALIGNMENT OPTIONS-align <RULE>

Use this option to generate a bitmap that will fit inside Animate with aread module aligned with a defined rule.
RULE can be: AS_IS, CENTER_TB, CENTER_LR,
CENTER_FIRST_PAGE_HORIZONTAL, CENTER_FIRST_PAGE_VERTICAL,
TOP, BOTTOM, LEFT, RIGHT.

-dpi <dpi>

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

-paper_size

Size of paper in inches default is 12.

-margin

Number of fields to keep around the TVG.-elementId <fields> ; Field sizeof element.-sar <scene_aspect_ratio> ; Scene aspect ratio default is
1.33333. Use 1.7777777 for 16/9 scenes.

-box

Use this box to render.

13

Animate 2 Utilities User Guide

14

Chapter 2: Utilities utransform UtilityIndexIndex-PDF_SEPARATE_LAYERS 8-PDF_SUPPORT_CMYK 8
switches 8-?|-h|-help|--help 8-outdir dir 8-outtemplate output_folder.tpl 8-usage 8-v|-version|--versio 8
utility 8Aabout
utilities 3alignment
options
utransform 13

pixmapconversion 11

BR

bitmap conversion 4, 11

Ccommand line
utility 4
command line utilities
location
Animate 4
run 4
MacOSX 4
Windows 4
convertimage formats 11

FformatPdfimport 8
Swf2tvg 9
Swfimport 10
unifo 10
utransform 11

I

image
options
utransform 11
image format
conversion 4, 11O

optionsalignmentutransform 13
image
utransform 11
Pdfimport 8
Swfimport 10
unifo 10
utransform 11
vectorutransform 12
vector to vector
utransform 12

P

Pdfimport
format 8
options 8-outdir output_folder 8-outtemplate output_folder.tp 8-PDF_BREAK_LINE_ART 8-PDF_FLATTEN 8-PDF_GENERATE_COLOUR_ART 8-PDF_LINE_ART_STROKE 8

runutility 4S

Swf2tvg
format 9
switches 9-?|-h|-help|--help 9-base_color_index 9-base_name 9-bbox_recenter 9-frame_alias 9-ignore_position 9-outdir 9-palette 9-start_index 9-usage 9-use_different_palettes 9-use_place_objects 9-v|-version|--version 9
utility 9
Swfimport
format 10
options 10-applycolourtransform 10-outdir output_folde 10-paletteName name_of_palette 10
switches 10-?|-h|-help|--help 10-outdir dir 10-usage 10-v|-version|--version 10
utility 10
switches
Pdfimport 8
Swf2tvg 9
Swfimport 10

U

uinfo
format 10
options 10-?|-h|-help|--help 10-v|-version|--version 10
utility 10
utilities
about 3Pdfimport 8
Swf2tvg 9
Swfimport 10
uinfo 10
utransform 11
utilityrunning 415

Animate 2 Utilities User Guide
utransformalignment options-align 13-dpi 13
format 11
help
MacOSX
example of 5
Windows
example of 5
Image options
11-addoverlay 12-addunderlay 12-arttoart 12-automatte 12-bgalpha 12-bgcolor 11-box 13-clearlayers 12-copystrokes 12-margin 13-paper_size 13-ps 11-resolution scan 11-scale 11-turn 11
-useoverlaylayer 12-useunderlaylayer 12-xscale 11-yscale 11
launchWindows
example of 4
options 11-?|-h|-help|--help 11alignment 13-debug 11
image 11
-outfile 11-outformat 11-v|-version|--version 11
vector 12
vector to vector 12
utility 11
vector options-antialiasing 12-bboxtvgincrease 12-flatten 12-move 12
nocolorart 12-nolineart 12-nolinetexture 12-normalize 12-setfieldsize 12vector to vector options-centreline 12-closegap 12-colorartstrokescolor 13-fieldsize 13-gaplength 13-hairlength 13-hairpasses 13-keepcolorart 13-lineartstrokescolor 13-nofitcolorart 13-showstrokes 13

16-thickness 13-tvgversion 13

V

vectoroptions
utransform 12
vector conversion 4, 11
vector to vector
options
utransform 12