utransform Utility

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

Syntax

utransform [OPTIONS] INPUT_FILES

Example

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

utransform -outformat SCAN -bgcolor 255 255 255 A-1.tvg A-2.tvg A-3.tvg

Parameters

General Parameters

Parameter Description
-debug

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

File Output Parameters

The following parameters are used to set the file name and file type of the output files.

Parameter Description
-outformat <format>

This is the image format that you 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 use the standard depth of 8 bits per channel.
  • If they support different amounts of channels, the amount of channels they use. For example:
    • 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.
NOTES
  • 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 file extension will also work. It will output images with standard colour depth (8 bits per channel) in solid colour (3 channels).
  • Some of these formats are Toon Boom formats:
    • VAR is a legacy Toon Boom format for greyscale bitmap images.
    • OPT is a legacy Toon Boom format for bitmap images with 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 scanning metadata such as the registration, resolution and field chart of the drawing.
    • TVG is the standard image format used by Toon Boom applications for vector drawings as well as Toon Boom bitmap drawings.
-outfile <file 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.

Image Processing Parameters

The following options can perform routine transformations on images.

Parameter Description
-resolution <width> <height>

The dimensions of the output image, in pixels.

NOTE This option only works if the output file is a regular bitmap.
-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.

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.

-scale <factor>

The scale factor to apply to the input image. 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 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.

NOTE This option only works if the output file is a regular bitmap.
-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.

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

NOTE This option only works if the output file is a regular bitmap.
-bgalpha <alpha>

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 or a decimal ranging from 0.0 to 1.0.

NOTE This option only works if the output file is a regular bitmap and its format supports alpha.
-premultiply <mode>

The way the colour values of pixels is encoded relative to their alpha value. This parameter has two possibles uses:

  • To indicate the premultiplication type of the source image when converting a regular bitmap image to a Toon Boom bitmap (.tvg).
  • To set the premultiplication type of the output image when converting a Toon Boom Bitmap (.tvg) to a regular bitmap image (with the -bitmapartonly option).

This parameter supports the following premultiplication modes:

  • straight: 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.
  • white: 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, the image 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
-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.

-nolinetexture

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

NOTE This does not affect textured pencil lines.
-nolineart

Does not render the line art layer.

-nocolorart

Does not render the colour art layer.

-bitmapartonly

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, the art layers are merged together before the final conversion. The resolution of the output image will be based on either one of the following:

  • 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 no line 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 the centrelines of pencil lines with a colour to make them visible.

Parameter Description
-showstrokes

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

-thickness

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

If unspecified, the default thickness is 1.

-lineartstrokescolor <red> <green> <blue> <alpha>

Sets the colour in which to render the strokes in the line art. The colour is defined in red, green, blue and alpha values.

If unspecified, the default colour of line art strokes is green (0 255 0 255).

-colorartstrokescolor <red> <green> <blue> <alpha>

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 when rendered into a bitmap canvas.

Parameter Description
-align <rule>

Determines how the vector artwork is laid out within its canvas.

The following rules are available:

  • AS_IS
  • CENTER_TB
  • CENTER_LR
  • CENTER_FIRST_PAGE_HORIZONTAL
  • CENTER_FIRST_PAGE_VERTICAL
  • TOP
  • BOTTOM
  • LEFT
  • RIGHT
  • AUTO_ALIGN

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 their internal 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 in dots per inch.

The default resolution is 75 DPI.

-paper_size <inches>

The size of the paper in inches.

The default size is 12.

-margin <fields>

The number of fields to add as margin around the output Toon Boom drawing (.tvg) file. If unspecified, this is set to 8.

NOTE This parameter only affects the output when used with the -align parameter set to AUTO_ALIGN.
-element_size <fields>

The field size of the element.

NOTE This parameter only affects the output when used with the -align parameter set to AUTO_ALIGN.
-sar <scene aspect ratio>

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.

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

Outputs the coordinates of the input drawing's bounding box to the terminal, in the following format:

x1 y1 x2 y2

Where x1 and y1 are the x and y coordinates of the bottom-left corner of the box, and x2 and y2 are the x and y coordinates of the top-right corner of the box.

NOTE These coordinates are in model coordinates. In a 4:3 12 fields grid, a horizontal field is equal to 208.333 units and a vertical field 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 y coordinates of its bottom-left corner followed by the x and y coordinates of its top-right corner.

-crop

Adjusts the canvas of the output image to include all of the artwork in the input drawing and to trim out the negative space.

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 Description
-fieldsize <field size>

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.

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

When extracting the centreline from the line art, preserve the artwork in the colour art layer and put the extracted centreline over it.

-nofitcolorart

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 another layer. This option has more flexibility on which art layers are used and how the centreline is generated.

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

To reproduce the effect of the Create Colour Art from Line Art command in 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:

  • 1: Underlay Art
  • 2: Colour Art
  • 4: Line Art
  • 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 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 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 the artwork 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
-automatte <source art> <destination art> <radius>

Generates a matte based on the source art layer and puts it in the destination 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.

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

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

  • overlayart
  • lineart
  • colorart
  • underlayart
NOTE The matte will be filled with a non-indexed colour. You will hence be prompted to perform colour recovery when viewing the drawing 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.

Parameter Description
-addlineart <drawing>

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

If the drawing is a Toon Boom Vector Graphic (.tvg) file, it will use that drawing's line art layer by default.

-uselineartlayer <art layer>

 

When using the -addlineart option to add a Toon Boom Vector Graphic (.tvg) file to a drawing's line art layer, this parameter can be used to specify which art layer in the source drawing to add to the target drawing's line art layer. Otherwise, the source drawing's line art layer will be used.

The following values are supported:

  • overlayart
  • lineart
  • colorart
  • underlayart
-addcolorart <drawing>

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

If the drawing is a Toon Boom Vector Graphic (.tvg) file, it will use that drawing's line art layer by default.

-usecolorartlayer <art layer>

When using the -addcolorart option to add a Toon Boom Vector Graphic (.tvg) file to a drawing's colour art layer, this parameter can be used to specify which art layer in the source drawing to add to the target drawing's colour art layer. Otherwise, the source drawing's line art layer will be used.

The following values are supported:

  • overlayart
  • lineart
  • colorart
  • underlayart
-addoverlay <drawing>

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

If the drawing is a Toon Boom Vector Graphic (.tvg) file, it will use that drawing's line art layer by default.

-useoverlaylayer <art layer>

When using the -addoverlay option to add a Toon Boom Vector Graphic (.tvg) file to a drawing's overlay art layer, this parameter can be used to specify which art layer in the source drawing to add to the target drawing's overlay art layer. Otherwise, the source drawing's line art layer will be used.

The following values are supported:

  • overlayart
  • lineart
  • colorart
  • underlayart
-addunderlay <drawing>

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

If the drawing is a Toon Boom Vector Graphic (.tvg) file, it will use that drawing's line art layer by default.

-userunderlaylayer <art layer>

When using the -addunderlay option to add a Toon Boom Vector Graphic (.tvg) file to a drawing's overlay art layer, this parameter can be used to specify which art layer in the source drawing to add to the target drawing's underlay art layer. Otherwise, the source drawing's line art layer will be used.

The following values are supported:

  • overlayart
  • lineart
  • colorart
  • underlayart
-keep_birmap_transform When replacing the artwork in a bitmap art layer, this option preserves the geometric transformations that were done on this bitmap art layer with the Select tool.
-clearlayers <art layers>

Removes the artwork from the specified art layer.

  • overlayart
  • lineart
  • colorart
  • underlayart

More than one art layer can be specified by separating them with commas, 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
-change_color_ids <json file>

Replaces colour IDs in the source file with the specified colour IDs.

This parameter must be specified with the path to a .json file that specifies the ID of each colour you want to change, followed by the ID you want to replace it with, in the following format:

[ { "from" : "source ID", "to" : "destination ID" }, { "from" : "source ID", "to" : "destination ID" }, { "from" : "source ID", "to" : "destination ID" } ]
-reduce_tvg_texture_resolution <dots per field> <max size>

Reduces the internal resolution of textures in Toon Boom drawing (.tvg) files.

  • <dots per field>: The maximum resolution of textures in dots per field, based on horizontal fields. By default, this is set to 72.

  • <max size>: The maximum size (horizontal or vertical dimension) 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.

-flatten_scale <scale factor>

Scales the artwork up by the specified scale factor, flattens it, then scales it back to its original size.

This can be useful when attempting to flatten artwork with superimposed 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 with at scale factor of at least 4.

-setfieldsize <field>

Changes the internal field size of the input drawing.

Typically, a drawing's field size should match the field size of the element that contains it in order to appear the right size in the scene. By default, both drawings and elements have a field size of 12. If the field size of the element is bigger than the field size of the drawing, the drawing will appear bigger. If the field size of the drawing is bigger than the field size of the element, the drawing will appear smaller.

-normalize

Normalizes the size of the drawing relative to its field size. This scales 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 field size is bigger than 12, it will be scaled up. If the drawing's field size is smaller than 12, it will be scaled down.

-bboxtvgincrease <percentage>

A legacy option that would increase the bounding box of vector artwork. It is only left in to preserve for compatibility with legacy scripts.