More > Utilities > 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.


utransform [options] <input files>


utransform -outformat PNG4 -outfile layout.png -scale 0.5 -bgalpha 0 BG-1.tvg




General Options

-outformat <format>

This is the image format that you want to output with utransform. The following output image formats are supported:

  • TGA ( TGA1, TGA3 and TGA4)
  • SGI ( SGI1, SGI3, SGI4, SGIDP3 and SGIDP4)
  • OPT (OPT1, OPT3 and OPT4)
  • PSD (PSD1, PSD3, PSD4, PSDDP3 and PSDDP4)
  • YUV
  • PAL
  • SCAN
  • TVG
  • PDF
  • PNG (PNG4)

Some of these image formats have variants, the notation of which is composed of:

  • 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 this notation have a standard depth of 8 bits per channel.
  • If they support different amounts of channels, the amount of channels they preserve. For example:
    • 1 means 1 colour channel, which outputs greyscale.
    • 3 means 3 colour channels, which is solid colours.
    • 4 means 3 colour channels + 1 alpha channel, meaning the format supports transparency values.
NOTE: For formats that have variants, merely specifying the file extension will also work. It will output images with standard colour depth (8 bits per channel) in true colour (3 channels).
NOTE: Some of these formats are Toon Boom proprietary formats:
  • 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 the registration and resolution of the drawing within a scene.
  • TVG is the standard image format used by Toon Boom applications for vector drawings as well as Toon Boom bitmap drawings.

-outfile <name>

The path and name of the file to output. By default, output files will have the same name as their input files and will be output in the same directory, with the only difference being their file extension.

NOTE: If processing multiple files, this option will be ignored.


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


This option will display the help information.


This option will display the version information.

Image Options

-resolution <width> <height>

The intended dimensions of the output image, in pixels.

-resolution scan

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

-scale <factor>

The scale factor to apply to the input image before processing it. The default value is 1 (no scaling).

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 is liable to have padding around it.

-xscale <factor>

The horizontal scale factor to apply to the input image before processing it.

-yscale <factor>

The vertical scale factor to apply to the input image before processing it.

-turn <angle>

Rotates the input image by the specified angle in degrees. A positive value will rotate the image counter-clockwise.

-ps <input format> <output format>

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 image must be specified to make the conversion. The following formats are supported:

  • square
  • NTSC
  • PAL

-bgcolor <red> <green> <blue>

The background colour to apply to the background if the input image has transparent pixels. By default, the output image will be laid on solid white. To choose a colour, values for red, green and blue ranging from 0 to 255 must be specified.

-bgalpha <a>

The alpha value of the background if the input image has transparent pixels. By default, the background will be fully opaque. To choose the background's transparency, specify a value between 0 (fully transparent) and 255 (fully opaque.

Vector Options

-antialiasing <quality> <exponent>

Specify the antialiasing quality and exponent when converting vector images to bitmaps.

The quality determines the method used to apply antialiasing:

  • low: Disables antialiasing, but renders transparency.
  • medium-low: Renders vector artwork with basic antialiasing.
  • medium: 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 the value, 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.


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

NOTE: This does not affect textured pencil lines.


Ignores the line art layer.


Ignores the colour art layer.

-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 pixel. A positive x offset will move the image towards the right, and a positive y offset will move the image towards the top.


Increases the bounding box of the vector artwork.

-setfieldsize <f>

Sets the internal field size of the output image, when outputting in TVG format.

NOTE: This field size is used in relation to the field size of the element to determine the size in which the drawing is displayed. By default, elements have a field size of 12, and drawings have a field size of 12, making them display at 100% their size. If, for example, a drawing has a field size of 6 in an element that has a field size of 12, it will appear to be scaled up to 200%.

Vector to Vector Options


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

-arttoart <source art> <destination art> <max resolution> <threshold> <fitting error>

Creates colour art based on the selected source art layer, and outputs it to the selected destination art layer, removing any existing artwork in that layer prior.

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:

  • 1: Underlay Art
  • 2: Colour Art
  • 3: Line Art
  • 4: 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 dimension of 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. This setting 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 in account to create the colour art. The higher this setting is, the less detailed 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, this parameter is set to 0.25 by default.

Fitting Error: Reduces the amount of detail in the colour art by converting sequences of points fit curvilinear shapes into curved segments. In Harmony, this parameter is set to 0.01 by default.


Use this option to perform Close gap.


Flattens the artwork, making superposed drawing strokes into single drawing objects, and merging superposed textures together.


Use this option to define a Close gap length value.

The default value is 10.


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


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


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


This option normalizes the input image. If the TVG has a different scaling than 1, it will scale the coordinates and set the scaling to 1.0.


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


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.


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

Toon Boom Bitmap Options
-premultiply <straight | black | white>  

Alignment Options

-align <RULE>

Use this option to generate a bitmap that will fit inside Harmony with a read node aligned with a defined rule.


-dpi <dpi>

Use this option to define the output resolution for the bitmap 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.


Outputs information about the way the input image was framed to produce the output image, in XML format.

If no outfile is specified, the information will be stored in an XML file named after the output image, with the .xml extension added after the output image's extension. If an outfile is specified, the information will be sent to standard output.