Pix2vec Utility

Pix2vec is an highly flexible and versatile utility for converting scanned drawings and lineart images to Toon Boom Vector Graphic (.tvg) files that are ready to be inked and painted. It can be used to vectorize Toon Boom Scan (.scan) files as well as any type of bitmap supported by Toon Boom Harmony.

Syntax

Pix2vec -file INPUT_FILE [OPTIONS]

Example

The only option that is mandatory for Pix2vec is -file or -infile. It will generated a Toon Boom Vector Graphic (.tvg) drawing based on the input file, with the bitmap drawing vectorized in the line art layer and colour zones generated in the colour art layer. The default parameters for vectorization are used for every unspecified parameter. The filename of the output file will be based on the input file, but with the extension .tvg.

Pix2vec -file A-1.scan

If the default parameters are not giving the expected results, you can try using Pix2vec with its extensive set of options.

Pix2vec -infile A-1.scan -outfile B-1.tvg -register 150 b l -no_texture -rmv_holes 10 -rmv_dirt 10 -rmv_hairs 30 3 -rmv_triangles 90

Pix2veccan only process one file at a time. If you want to use Pix2vec on a series of file, you can script a loop in your command line. A loop repeats a command while counting from one number to another number in a specified increments, and that number is stored in a variable to be used by the command, allowing you to iterate through several drawings that have the same base name, but are numbered in a series.

For example, you can iterate through drawings on to 13, numbered on twos, with the following command:

  • On Windows, in Command Prompt:

    > FOR /L %I IN (1,2,13) DO Pix2vec -file A-%I.scan

  • On macOS and GNU/Linux, in a Bash terminal:

    $ for I in {1..13..2}; do Pix2vec -file A-$I.scan; done

You can also loop through every file of a given type in a directory using the following syntax:

  • On Windows, in Command Prompt:

    > FOR %I IN (*.scan) DO Pix2vec -file %I

  • On macOS and GNU/Linux, in Bash:

    $ for I in *.scan; do Pix2vec -file $I; done

Parameters

General Options

Parameter Description

-help

--help

-?

Displays the list of the sections on which you can obtain usage information.

-help <section>

Displays usage information on the specified section. The following sections are available:

  • all: Displays help on all parameters.
  • io: Displays help about the input/output parameters.
  • register: Displays help about the peg registration parameters.
  • filter: Displays help about the filtering parameters.
  • rgb: Displays help about the red/green/blue keying parameters.
  • 4colours: Displays help about four colours vectorization parameters.
  • bubble: Displays help about bubble generation parameters.
  • color: Displays help about colour vectorization parameters.

-debug

Use this option to turn on the debug mode.

-version

This option will display the version information.

Input/Output Parameters

Parameter Description

-file <filename>

-infile <filename>

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

-outfile <filename>

Use this option to rename the output file.

NOTE: The filename must include the extension.

-informat <format>

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

-noforce

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

-force_unamed_palette_for_texture

Generates textures in the TVG's internal palette.

-output_version <version>

Sets the version of the output files.

Valid versions are 0 or 604. The TVG format version is 604.

Peg Registration Parameters

The following parameters configure how the drawing is registered. Registration is the process of analyzing the position of the drawing's peg holes and aligning it relative to its field.

Parameter Description

-register <dpi> <side> <strictness>

Use this option to perform optical registration.

<dpi>: The resolution of the scan.

<side>: The side of the sheet on which the pegs are to be registered. Can be one of the following:

  • b or bottom
  • t or top
  • l or left
  • r or right

<strictness>: The strictness with which the registration is evaluated. Can be one of the following:

  • l or loose
  • s or strict

-registration_center_peg_holes

-rcph

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

-registration_looseness_factor <factor>

-rlf <factor>

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

By default, the looseness factor is 2.

-rdebug

Outputs debug information about the registration.

-pegpitch <inches>

The distance between peg bars, in inches.

By default, this is set to 8.

-threshr <value>

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

By default, this is set to 0.5.

-rmargin <inches>

The distance between the edge of the paper and its peg holes.

By default, this is set to 1.

-peg_distance_from_center <inches>

-pdfc <inches>

The distance between the center of the page and the peg holes.

By default, this is set to 5.25.

-out_peg_position <side>

Defines the desired side of the pegs on the drawings. If it is different from the side of its actual registration (passed with the -register parameter), the drawing will be rotated accordingly.

  • same: The same side as the drawing's actual registration.
  • b or bottom
  • t or top
  • l or left
  • r or right

By default, this is set to same.

-output_peg_matrix

Outputs the information about the peg matrix to the terminal.

-scanner_calibrate <x scale> <y scale>

Sets the horizontal and vertical scale factor to be applied on the scanned image. The scale factors are 1-based, meaning that 1 represents the image's original size.

By default, this is set to 1 1.

Filtering Options

The following parameters configure the way the line art is converted to vector outlines, and how its centreline is converted to colour zones.

Parameter Description

-pixel <pixel shape>

Defines the shape of pixels. The only valid value for this is 4x3.

By default, this is set to 4x3.

-gap <length>

Automatically close gaps that are up to a certain size with invisible strokes, to make closed shapes that can be painted.

The value sets the maximum length of gaps to close, in world units.

By default, this is set to 10.

-pencil

Generate pencil lines for the line art.

This should not be used with the -no_color_art parameter.

-vectorize_alpha

-use_alpha

Properly vectorizes line art drawn on a transparent background.

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

-keep_dirt

Disables filtering dirt out from the drawing.

-thresh <value>

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

The default threshold is 0.2.

-rmv_hairs <length> <passes>

Removes hair, which are short useless strokes extending from closed shapes.

The length determines the maximum length of hairs to remove, in world units. The passes determines the amount of times to remove hairs from the whole drawing. Adding extra passes will remove hair that branched into several hairs.

The default length is 1 and the default number of passes is 1.

-rmv_holes <size>

Remove holes that are smaller than the defined area, in world units squared, from the artwork.

The default size of holes to remove is 7.

-rmv_dirt <size>

Removes dirt that is smaller than the defined size, in world units squared, from the artwork.

The default size of dirt to remove is 1.

TIP: Try removing holes and dirt with a size ranging from 100 to 500.

-rmv_triangles <size>

Removes triangles at the defined distance from one another, in world units.

By default, the distance of triangles to remove is 30.

NOTE: Triangles are used to break the strokes in line art into different colour zones to help paint different zones of the line art with different colours. You can use the -no_break parameter to remove all triangles and make all adjacent line art into single colour zones.

-no_texture

Disables the generation of textured strokes.

-color_as_texture

Converts the entire image to a coloured bitmap texture and stores it in a vector rectangle.

This does not create editable line art nor does it create any colour zones, but it preserves the image exactly as is.

-noclosegap

Disables closing gaps. All gaps in the artwork will remain open regardless of how small they are.

-no_break

Disables breaking the line art into triangles, making all adjacent line art into single colour zones.

-jag_filter <pixels>

This reduces the jaggedness in line art by expanding the lines by the specified amount of pixels (using the same mechanism as the -expand_bitmap parameter), then contracting the lines by the same amount, resulting in smoother outlines. It is recommended to use values such as 1 or 2.

By default, the jag filter is set to 0.

-expand_bitmap <pixels>

Expands the outlines of the line art by the set amount of pixels, resulting in thicker outlines.

By default, this is set to 0.

-fit_errorc <value>

Defines the fit error level for the colour art.

The fit error is the process by which three points segments, which make corners, are interpreted as curves. This means that instead of drawing a segment from point 1 to point 2, then from point 2 to point 3, a single segment is drawn from point 1 to point 3, with Bezier curves adjusted for the line to go over point 2. A higher fit error will cause more corners to be interpreted as curves. A lower fit error will cause the artwork to have more points. Some fit error is required to avoid having too many control points.

The default fit error is 1.

-fit_errorl <value>

Defines the fit error level for the line art.

The fit error is the process by which three points segments, which make corners, are interpreted as curves. This means that instead of drawing a segment from point 1 to point 2, then from point 2 to point 3, a single segment is drawn from point 1 to point 3, with Bezier curves adjusted for the line to go over point 2. A higher fit error will cause more corners to be interpreted as curves. A lower fit error will cause the artwork to have more points. Some fit error is required to avoid having too many control points.

The default fit error is 1.

-smoothl <passes>

Sets the amount of smoothing passes to perform on the line art.

By default, this parameter is set to 1.

-smoothc <passes>

Sets the amount of smoothing passes to perform on the colour art.

By default, this parameter is set to 1.

-first_smooth <passes>

Defines the number of smooth passes to perform on the line art before breaking the triangles.

By default, this parameter is set to 0.

-support_thin_lines

Do not erode thin lines when generating colour art.

-2pass

Using this parameter allows you to set two sets of parameters, one for vectorizing the line art and one for creating the colour art.

With this option, you can use the following parameters with the suffix l or c ro define its value differently for the line art and for the colour art:

  • -treshl and -treshc
  • -jag_filterl and -jag_filterc
  • -expand_bitmapl and -expand_bitmapc
  • -rmv_holesl and -rmv_holesc
  • -rmv_dirtl and -rmv_dirtc
  • -first_smoothl and -first_smoothc

-threshl <value>

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

The default threshold is 0.5.

NOTE: This threshold is higher than the default value for single-pass vectorization, which may erode thin or light outlines. If you want to obtain results similar to single-pass vectorization, set this to 0.2.

-threshc <value>

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

The default threshold is 0.5.

NOTE: This threshold is higher than the default value for single-pass vectorization, which may erode thin or light outlines. If you want to obtain results similar to single-pass vectorization, set this to 0.2.

-jag_filterl <pixels>

This option expands the pixels in the vectorization bitmap for line art. To smooth and straighten jagged lines.

-jag_filterc <pixels>

This option expands the pixels in the vectorization bitmap for colour art. To smooth and straighten jagged lines.

-expand_bitmapl <pixels>

Expands the outlines of the line art by the set amount of pixels, resulting in thicker outlines for the line art.

By default, this is set to 0.

-expand_bitmapc <pixels>

Expands the outlines of the line art by the set amount of pixels, resulting in thicker outlines for the colour art.

By default, this is set to 0.

-rmv_holesl <size>

Remove holes that are smaller than the defined area, in world units squared, for the line art.

The default size of holes to remove is 7.

-rmv_holesc <size>

Remove holes that are smaller than the defined area, in world units squared, for the colour art.

The default size of holes to remove is 7.

-rmv_dirtl <size>

Removes dirt that is smaller than the defined size, in world units squared, for the line art.

The default size of dirt to remove is 1.

-rmv_dirtc <size>

Removes dirt that is smaller than the defined size, in world units squared, for the colour art.

The default size of dirt to remove is 1.

-first_smoothl <passes>

Defines the number of smooth passes to perform on the line art before breaking the triangles, for the line art.

By default, this parameter is set to 0.

-first_smoothc <passes>

Defines the number of smooth passes to perform on the line art before breaking the triangles, for the colour art.

By default, this parameter is set to 0.

-margins <inches>

Removes a margin all around the bitmap. The size of the margin must be specified in inches.

By default, this parameter is set to 0.25.

-top_margin <inches>

Removes a margin from the top edge of the bitmap. The size of the margin must be specified in inches.

By default, this parameter is set to 0.25.

-bottom_margin <inches>

Removes a margin from the bottom edge of the bitmap. The size of the margin must be specified in inches.

By default, this parameter is set to 0.25.

-left_margin <inches>

Removes a margin from the left edge of the bitmap. The size of the margin must be specified in inches.

By default, this parameter is set to 0.25.

-right_margin <inches>

Removes a margin from the right edge of the bitmap. The size of the margin must be specified in inches.

By default, this parameter is set to 0.25.

-remove_peg_bars

Removes the peg bar holes from the drawing.

-field_size <fields>

-fs <fields>

Sets the field size of the output drawing.

By default, this is set to:

  • 12 if the input image is a regular bitmap.
  • The internal field size of the scan file, if the input image is a Toon Boom Scan file.
NOTE: Scan files have their own field size. If the field size of the scan file is different than the field size of the TVG that is generated from it, its scaling will be affected. Regular bitmap files do not have a field size, therefore, their dots per inch (DPI) resolution is automatically adjusted to fit the field, unless the -dpi parameter is used.

-peg_bar_size <inches>

Sets the size of the region reserved for the peg bar, from the edge of the drawing, in inches.

-noframe

Disables adding a frame around the colour art.

-frame_fields <fields>

Adds a frame of the specified size around the colour art. The size must be specified in fields.

If the frame is made to match the drawing, its element and its scene's field size, it will fit the scene's camera field perfectly. By default, all of these are 12 fields in size.

The default value of this parameter is -1, which uses the drawing's field size.

-downscale_input <factor>

Downscales the input image before processing it. This does not affect the dimensions of the vectorized drawing in the scene, only its display quality. In other words, this is equivalent to pixelating the drawing.

The scale factor is an integer used as the denominator. For example, the default value is 1, which does not downscale the image, 2 would downscale the image by half, etc.

-downscale_texture <factor>

Downscales the output texture. This is very similar to -downscale_input, except that the downscaling is performed on the line art's texture after the original drawing has been vectorized. This means that the contours of the outlines and the strokes in the colour art are not affected, only the texture in the outline is.

Just like -downscale_input, the dimensions of the vectorized drawing are not affected, so this is equivalent to pixelating the vectorized drawing's texture.

The scale factor is an integer used as the denominator. For example, the default value is 1, which does not downscale the texture, 2 would downscale the texture by half, etc.

-buildmatte

Generates a filled matte based on the line art and stores it in the underlay art layer.

-buildmatte_colourart

Generates a filled matte based on the line art and stores it in the color art layer.

NOTE: -buildmatte and -buildmatte_colourart are mutually exclusive.

-copystrokes

When generating a matte, copies the strokes from the line art layer onto the matte so as to preserve the defined colour zones.

Options for Bitmap with no Registration Information

The following options can be used if you are vectorizing regular bitmaps, rather than Toon Boom Scan (.scan) files.

Parameter Description

-pixel_margins <pixels>

Removes a margin all around the bitmap. The size of the margin must be specified in pixels.

By default, this parameter is set to 0.

-top_pixel_margin <pixels>

Removes a margin from the top edge of the bitmap. The size of the margin must be specified in pixels.

By default, this parameter is set to 0.

-bottom_pixel_margin <pixels>

Removes a margin from the bottom edge of the bitmap. The size of the margin must be specified in pixels.

By default, this parameter is set to 0.

-left_pixel_margin <pixels>

Removes a margin from the left edge of the bitmap. The size of the margin must be specified in pixels.

By default, this parameter is set to 0.

-right_pixel_margin <pixels>

Removes a margin from the right edge of the bitmap. The size of the margin must be specified in pixels.

By default, this parameter is set to 0.

-dpi <dots per inch>

Sets the resolution of the input image, in dots per inches.

The default value for this parameter is -1, which makes Pix2vec automatically adjust the DPI resolution of the drawing to make it fit the field of the drawing.

-layer <layer name>

When vectorizong a multi-layer Photoshop Document (.psd) file, this parameter allows you to select which layer to vectorize.

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

-layer group1:layer

The default value for this parameter is ''.

Red/Green/Blue Keying Options

The following options allow you to vectorize red, green and blue lines as they are coloured, instead of in greyscale, which is the default behaviour. This can be especially useful if you are using certain line colours for specific purposes. For example, red lines are traditionally used in animation to close colour zones outside of the camera field or to trace an outline that is meant to match the outline of a background element.

Parameter Description

-rgb

Generates separate zones for red, green and blue lines.

NOTE: By default, the red, green and blue lines will have an alpha of 1. You can set their alpha to a different value with the -rgb_alpha parameter.

-rgb_alpha <value>

Specifies the alpha of the red, green and blue lines generated with the -rgb parameter.

By default, this parameter is set to 1.

-rgb_alpha_texture

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

Contrary to the -flatten parameter, this will still vectorize the colour line in gray first, then add the coloured vectorized line over it.

-rgb_separate

Separates the colour zones used for red, green and blue lines from the colour zones used for the black lines instead of overlaying them.

NOTE: This parameter also requires the -2pass parameter to work.

-no_red

Ignores red lines during vectorization.

-no_green

Ignores green lines during vectorization.

-no_blue

Ignores blue lines during vectorization.

-flatten

Instead of adding the vectorized colour lines over the vectorized line art as separate drawing strokes, this applies the colour of the colour lines to the existing texture of the vectorized line art.

This option is useful if you don't want black lines to appear behind the colour lines, should you choose to remove the colour lines later.

-rmv_rgb_dirt <size>

Removes red, green or blue spots smaller than the specified area, in world units squared.

The default value for this parameter is 0.

-expand_bitmap_rgb <pixels>

Expands the red, green and blue outlines of the line art by the set amount of pixels, resulting in thicker coloured outlines.

By default, this is set to 0.

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

-threshrgb <value>

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

By default, this is set to 0.2.

-threshsv <saturation threshold> <value threshold>

The saturation and value threshold required for a pixel to be considered coloured rather than grey or black. Both can be set to a decimal value ranging from 0 to 1.

The default saturation threshold is 0.5 and the default value threshold is 0.5.

Four Colours Vectorization

The following options allow you to vectorize a drawing with red, green, blue and black lines. This is very similar to the Red/Green/Blue keying vectorization parameters, except that this approach is a mode of its own. Contrary to Red/Green/Blue vectorization, this will not generate the black line art and add coloured lines on top. It will generate a single layer of non-textured vector shapes that are either solid red, solid green, solid blue or solid black, without them overlapping each other. Most of the parameters for this mode are used to determine how to differentiate red, green, blue, black and white in the source drawing.

Parameter Description

-4colours <key:value> ... <key:value>

Performs four colour vectorization using the specified parameters.

You can specify zero or as many parameters as needed. Each parameter must be expressed by its key followed by a colon and then its value. Parameters must be separated by spaces, but there should be no spaces between a key and its value. For example:

-4colours rgbdiff:20 dark:20 grey:120 white:250 dirt:200 rt:240 gt:240 bt:240

Here are the available keys:

  • rgbdiff: The threshold for tolerating mixed colours. A lower value means mixed colours are interpreted as their dominant primary colour. A higher value means mixed colours are interpreted as either black or white, depending on their value. This parameter can be set to a value between 0.0 and 1.0 or between 0 and 255.
  • dark: The threshold for differentiating black. A higher value means lighter shades of dark colours and dark greys are vectorized as black. A lower value means only very dark areas are vectorized as black. Can be set to a value between 0.0 and 1.0 or between 0 and 255.
  • grey: The threshold for the interpretation of greys. Greys below this threshold are vectorized as black, and greys above this threshold are vectorized as white. Can be set to a value between 0.0 and 1.0 or between 0 and 255.
  • white: The threshold for differentiating white. A lower value means darker shades of light colours and light greys are vectorized as white. A higher value means only very light areas are vectorized as white. This parameter can be set to a value between 0.0 and 1.0 or between 0 and 255.
  • rt: The threshold differentiating red from black. A lower value means dark red is vectorized as red. A higher value means dark red is vectorized as black. This parameter can be set to a value between 0.0 and 1.0 or between 0 and 255.
  • gt: The threshold differentiating green from black. A lower value means dark green is vectorized as green. A higher value means dark green is vectorized as black. This parameter can be set to a value between 0.0 and 1.0 or between 0 and 255.
  • bt: The threshold differentiating blue from black. A lower value means dark blue is vectorized as blue. A higher value means dark blue is vectorized as black. This parameter can be set to a value between 0.0 and 1.0 or between 0 and 255.
  • dirt: The size of dirt to remove, in world units squared. The suggested value to use is 200.

Bubble options

Bubbles are bumps added along the outlines, giving the impression that the outline was drawn quickly with a pressure sensitive marker or fountain pen. They are made of streaks of circles that increase in size as the bump appears then decrease in size as the bump subsides. The size of bubbles and the distance between them can be configured.

NOTE: To learn more about the Bubble command, see How to Vectorize With Bubbles .
Parameter Description

-create_bubbles

Randomly adds bubble shapes along the line art.

-bubble_gap <value>

Sets the maximum number of colour art points between two bubbles.

By default, this parameter is set to 3.

-bubble_length <value>

Sets the maximum number of circles in a bubble.

A bubble is a streak of circles drawn along the outline. The more circles, the bigger the bubbles appear.

By default, this parameter is set to 10.

-min_radius <factor>

Defines the minimum radius of a circle in a bubble. This radius is a factor relative to the line thickness, where 1.0 is equal to the original thickness of the line. Hence, its value must be at least 1.0.

By default, this parameter is set to 1.5.

-max_radius <factor>

Defines the maximum radius of a circle in a bubble. This radius is a factor relative to the line thickness, where 1.0 is equal to the original thickness of the line. Hence, its value must be at least 1.0.

By default, this parameter is set to 3.5.

-uniform_gap

Lays out the bubbles at an equal distance from each other.

-uniform_height

Ensures every circle in bubbles has the same height.

NOTE: This option is deprecated. Instead, you can accomplish this by setting -min_radius and -max_radius to the same value.

Colour Vectorization Options

This approach vectorizes each pixel individually, merging pixels of the same colour in the same colour zones. Hence, it is important to only use it with image files that have very few solid colours with no antialiasing.

NOTE: Colour vectorization is experimental.
Parameter Description

-color_vectorize

Performs a colour vectorization.

-file2 <color art filename>

Allows you to specify a bitmap file for the generation of colour art.

-penstyle <center alpha> <edge alpha> <gamma> <centre pressure effect> <edge pressure effect> <texture bitmap downscaling> <texture bitmap file>

Generates a brush texture for the line art.

The parameters are as follows:

  • <centre alpha>: The alpha value in the middle of the line. Can be set to a value between 0.0 and 20.0, although the greatest difference is visible between 0.0 and 3.0.
  • <edge alpha>: The alpha at the edge of the line. Can be set to a value between 0.0 and 1.0. Setting this to 1.0 will yield a solid line.
  • <gamma>: The gamma of the texture. A higher value will make the edge darker, a lower value will make the edge lighter. This can be set to a value between 0 and 10.
  • <centre pressure effect>: The pressure at the centre of the line. Can be set to a value between 0.0 and 1.0.
  • <edge pressure effect>: The pressure at the edge of the line. Can be set to a value between 0.0 and 1.0.
  • <texture bitmap scaling>: The scaling factor of the bitmap texture. Can be set to a value between 0.2 and 20.
  • <texture bitmap file>: The path to a bitmap image to use as the texture. Set this to "" to not use a bitmap texture.

-pressure_variation <strategy> <min pressure> <max pressure> <max variation>

Configures the pressure variation strategy for the centreline.

The parameters are as follows:

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

-blur_radius <pixels>

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

By default, this parameter is set to 0.

-color_contour_smooth_passes <passes>

-ccsp <passes>

Sets the amount of smoothing passes to perform on the contour before computing the line texture.

By default, this parameter is set to 3.

-color_rmv_holesl <size>

Removes holes that are smaller than the defined size, in world units squared, from the line art, when computing the line texture.

By default, this parameter is set to 0.

-color_fill_holesl <size>

Fills holes that are smaller than the defined size, in world units squared, in the coloured line art.

By default, this parameter is set to 0.