Technical Spefication

vectorvision.Converter module

class vectorvision.Converter.Converter(image: <module 'PIL.Image' from '/home/docs/checkouts/readthedocs.org/user_builds/vectorvision/envs/latest/lib/python3.10/site-packages/PIL/Image.py'>, turnpolicy, turdsize, alpha_max, is_long_curve, opttolreance, scale)

Bases: object

A class used to convert an image to an SVG file.

image

The input image to be converted.

Type:: PIL.Image

num_colors

The number of colors in the image.

Type:: int

turnpolicy

The turn policy for bitmap tracing.

Type:: str

turdsize

The minimum turd size for bitmap tracing.

Type:: int

alpha_max

The alpha max value for curve smoothing.

Type:: float

is_long_curve

Whether to use long curve optimization.

Type:: bool

opttolerance

The optimization tolerance for curve optimization.

Type:: float

scale

The scale factor for the output SVG.

Type:: float

convert_single_color(color_table, fh, opacity=1)

Converts a single color layer to SVG paths and writes them to the file.

Parameters:

color_table (np.ndarray) – The color table for the current layer.
fh (TextIO) – The file handle for the SVG file.
opacity (float, optional) – The opacity for the current layer. Defaults to 1.

run(path)

Runs the conversion process and writes the output to an SVG file.

Parameters:: path (str) – The output path for the SVG file.

vectorvision.Converter.create_svg(name: str, width: int, height: int)

A context manager to create an SVG file with the given dimensions. This function opens a file for writing, writes the initial SVG tags with the specified width and height, and ensures that the closing SVG tag is written when the context is exited.

Parameters:

name (str) – The name of the file to create.
width (int) – The width of the SVG canvas.
height (int) – The height of the SVG canvas.

Yields:

TextIO – The file handle for the SVG file.

vectorvision.curve_optimization module

class vectorvision.curve_optimization.OptiT(pen, c, alpha, s)

Bases: tuple

alpha: Alias for field number 2

c: Alias for field number 1

pen: Alias for field number 0

s: Alias for field number 3

vectorvision.curve_optimization.bezier(t: float, p0, p1, p2, p3) → tuple[float, float]

Calculates a point of a bezier curve specified by control points and t param.

Paper: “We restrict ourselves to the case where the straight lines through p0p1 and through p3p2 intersect at a point o (i.e., they are not parallel).”

Parameters:

p0 – Bezier curve control points
p1 – Bezier curve control points
p2 – Bezier curve control points
p3 – Bezier curve control points
t – Curve parameter

Returns:

Point

vectorvision.curve_optimization.calculate_alpha(area: float, p0_o_p3_triangle_area: float) → float

Calculate alpha parameter for curve based on ratio of area under curve and triangle with two sides tangent to the curve

Parameters:

area – area under curve
p0_o_p3_triangle_area – area of triangle

Returns:

Alpha parameter of curve

vectorvision.curve_optimization.calculate_curve_area(curve: _Curve, start_segment_idx: int, end_segment_idx: int) → float

Calculate are under given segments of curve

Parameters:

curve – curve for which subset we want to calculate area
start_segment_idx – index of first segment of curve part for which we want to calculate area
end_segment_idx – index of last segment of curve part for which we want to calculate area

Returns:

Area under given segments of curve

vectorvision.curve_optimization.calculate_distance(p: tuple[float, float], q: tuple[float, float]) → float

Calculates Euclidean distance between two points in 2D space.

Parameters:

p – first point
q – second point

Returns:

Value of the Euclidean distance (float).

vectorvision.curve_optimization.calculate_optimization_penalty(curve: _Curve, start_segment_idx: int, end_segment_idx: int, opttolerance: float) → OptiT

Calculate penalty of optimized curve part between two segments

Parameters:

curve – curve for which subset we want to calculate area
start_segment_idx – index of first segment of curve part for which we want to calculate penalty
end_segment_idx – index of last segment of curve part for which we want to calculate penalty
opttolerance – maximum deviation for which we will still perform replacing

Returns:

Penalty of calculated optimal curve or None if cannot create optimal curve that will fit the requirements

vectorvision.curve_optimization.calculate_penalty_corners(curve: _Curve, start_index: int, end_index: int, opttolerance: float, p0, p1, p2, p3) → float

Calculates part of penalty connected with tangency with corners

Parameters:

curve – curve for which subset we want to calculate penalty
start_index – index of first segment of curve part for which we want to calculate penalty
end_index – index of last segment of curve part for which we want to calculate penalty
opttolerance – maximum deviation for which we will still perform replacing
p0 – control points of new potential curve
p1 – control points of new potential curve
p2 – control points of new potential curve
p3 – control points of new potential curve

Returns:

Value of the penalty

vectorvision.curve_optimization.calculate_penalty_edges_tangency(curve: _Curve, start_index: int, end_index: int, opttolerance: float, p0, p1, p2, p3) → float

Calculates part of penalty connected with tangency with edges

Parameters:

curve – curve for which subset we want to calculate penalty
start_index – index of first segment of curve part for which we want to calculate penalty
end_index – index of last segment of curve part for which we want to calculate penalty
opttolerance – maximum deviation for which we will still perform replacing
p0 – control points of new potential curve
p1 – control points of new potential curve
p2 – control points of new potential curve
p3 – control points of new potential curve

Returns:

Value of the penalty

vectorvision.curve_optimization.check_if_same_convexity(curve: _Curve, convexity: int, convexity_precalculated: list[int], start_segment_idx: int, end_segment_idx: int) → bool

Checks if condition of the same convexity is satisfied for given segments

Parameters:

curve – curve for which subset we want to perform check
convexity – expected convexity of segment
convexity_precalculated – precalculated convexity to speed up calculations
start_segment_idx – index of first segment of curve part for which we want to perform check
end_segment_idx – index of last segment of curve part for which we want to perform check

Returns:

True if condition is satisfied, False otherwise

vectorvision.curve_optimization.check_if_smaller_than_179(curve: _Curve, start_segment_idx: int, end_segment_idx: int) → bool

Checks if condition of not exceeding 179 degrees in one curve is satisfied for given segments

Parameters:

curve – curve for which subset we want to perform check
start_segment_idx – index of first segment of curve part for which we want to perform check
end_segment_idx – index of last segment of curve part for which we want to perform check

Returns:

True if condition is satisfied, False otherwise

vectorvision.curve_optimization.check_necessary_conditions(curve: _Curve, start_segment_idx: int, end_segment_idx: int) → bool

Checks if all necessary conditions to allow merging curves into one are satisfied

Parameters:

curve – curve for which subset we want to perform checks
start_segment_idx – index of first segment of curve part for which we want to perform checks
end_segment_idx – index of last segment of curve part for which we want to perform checks

Returns:

True if all conditions is satisfied, False otherwise

vectorvision.curve_optimization.cprod(p0, p1, p2, p3) → float

Calculates a cross product of differences between points: (p1-p0)x(p3-p2).

Parameters:

p0 – points
p1 – points
p2 – points
p3 – points

Returns:

Value of cross product (float).

vectorvision.curve_optimization.dpara(p0: tuple[float, float], p1, p2) → float

Calculates the area of the parallelogram in the 2D space. The parallelogram is defined by three points. This function is also used to determine curve convexity.

Parameters:

p0 – first point
p1 – second point
p2 – third point

Returns:

Area = (p1 - p0) x (p2 - p0) Can be also negative.

vectorvision.curve_optimization.iprod(p0, p1, p2, p3=None) → float

Calculates the product: (p1-p0) * (p3-p2) if there are four points given or (p1-p0) * (p2-p0) otherwise.

Parameters:

p0 – points
p1 – points
p2 – points
p3=None – points

Returns:

Value of the product (float).

vectorvision.curve_optimization.optimize_curve(curve: _Curve, opttolerance: float) → _Curve

Optimize the path p, replacing sequences of Bezier segments by a single segment when possible.

Parameters:

curve – curve to optimize
opttolerance – maximum deviation for which we will still perform replacing

Returns:

Optimized curve

vectorvision.curve_optimization.precalculate_areas(curve: _Curve) → list[float]

Precalculate area for curve :param curve: curve to precalculate area

Returns:: Precalculated area for each segment of curve

vectorvision.curve_optimization.precalculate_convexity(curve: _Curve) → list[int]

Precalculate convexity for curve :param curve: curve to precalculate convexity

Returns:: Precalculated convexity for each segment of curve

vectorvision.curve_optimization.tangent(p0, p1, p2, p3, q0, q1) → float

Calculates the point t in [0..1] on the (convex) bezier curve (p0,p1,p2,p3) which is tangent to q1-q0. Return -1 if there is no solution in [0..1].

Parameters:

p0 – control points of Bezier curve
p1 – control points of Bezier curve
p2 – control points of Bezier curve
p3 – control points of Bezier curve
q0
q1

Returns:

Value of t if there is solution in [0..1], otherwise -1.

vectorvision.main module

vectorvision.main.main() → None

vectorvision.main.validate_input(args)

Validates the input arguments for the vectorvision CLI tool. This function checks if the input file exists and if its format is supported. It also validates the output file format if an output path is specified.

Parameters:: args (Namespace) – The arguments parsed from the command line.
Returns:: True if all validations pass, False otherwise.
Return type:: bool

vectorvision.path_decomposition module

class vectorvision.path_decomposition.Bitmap(array: ndarray)

Bases: object

Represents one of the image bitmaps (color).

This class has methods that do produce the paths from the bitmap, and is used as the first stage in the potrace algorithm.

bitmap

array representing the bitmap.

Type:: np.ndarray

classmethod from_pil_image(image)

Bitmap class constructor.

Parameters:: image – PIL Image object
Returns:: The object of type Bitmap, created from PIL Image.

generate_paths_list(turdsize: int = 2, turnpolicy=Turnpolicy.RIGHT) → list[list[tuple[int, int]]]

Generate a list of paths from the bitmap.

Parameters:

turdsize – minimal area of the paths that will be produced
turnpolicy – the turnpolicy enum value

Returns:

List of paths.

class vectorvision.path_decomposition.Turnpolicy(value)

Bases: Enum

An enumeration.

BLACK = 0

LEFT = 2

MAJORITY = 5

MINORITY = 4

RIGHT = 3

WHITE = 1

vectorvision.polygons module

class vectorvision.polygons.Sums(x, y, xy, x2, y2)

Bases: tuple

x: Alias for field number 0

x2: Alias for field number 3

xy: Alias for field number 2

y: Alias for field number 1

y2: Alias for field number 4

vectorvision.polygons.calc_sums(path: list) → namedtuple

Calculate cumulative sums for the given path.

Parameters:: path (list) – A list of tuples, where each tuple represents a point (x, y).
Returns:: A list of Sums namedtuples, each containing cumulative sums of x, y, xy, x^2, and y^2 coordinates.
Return type:: sums (Sums)

vectorvision.polygons.clip_path_backward(forward_clips: list, path_len: int) → list

Calculate the backward clipping path, non-cyclic.

Parameters:

forward_clips (list) – Forward clipping path.
path_len (int) – Length of the path.

Returns:

Backward clipping path.

Return type:

list

vectorvision.polygons.clip_path_forward(longest_straight_subpaths: list, path_len: int) → list

Calculate the forward clipping path.

Parameters:

longest_straight_subpaths (list) – List of point indexes forming the longest straight subpaths.
path_len (int) – Length of the path.

Returns:

Forward clipping path.

Return type:

list

vectorvision.polygons.compute_direction(point1: tuple, point2: tuple) → int

Compute the path direction between two points.

Parameters:

point1 (tuple) – The coordinates of the first point (x, y).
point2 (tuple) – The coordinates of the second point (x, y).

Returns:

The index representing the direction:: (0, 1)[N] == 2, (1, 0)[E] == 3, (0, -1)[S] == 1, (-1, 0)[W] == 0.

Return type:

int

vectorvision.polygons.compute_vector(point1: tuple, point2: tuple) → tuple

Compute the vector between two points.

Parameters:

point1 (tuple) – The coordinates of the first point (x, y).
point2 (tuple) – The coordinates of the second point (x, y).

Returns:

A tuple representing the vector (dx, dy) between the points.

Return type:

tuple

vectorvision.polygons.cyclic(a: int, b: int, c: int) → bool

Determine if the value ‘b’ is between ‘a’ and ‘c’ in a cyclic sense.

Parameters:

a (int) – The start value.
b (int) – The value to check.
c (int) – The end value.

Returns:

True if a <= b < c in a cyclic sense (mod n), False otherwise.

Return type:

bool

vectorvision.polygons.get_best_polygon(path: list) → list

Find the optimal polygon for the given path. This function fills in the m and po components and returns the optimal polygon. Assumes i=0 is in the polygon. This is a non-cyclic version.

Parameters:: path (list) – List of points representing the path.
Returns:: Optimal polygon as a list of point indices.
Return type:: list

vectorvision.polygons.get_longest_straight_subpaths(path: list) → list

Return a list of indexes forming the longest straight subpaths in the given path.

Parameters:: path (list) – A list of points representing the path.
Returns:: A list of point indexes forming the longest straight subpaths.
Return type:: list

vectorvision.polygons.get_next_corners(path: list, path_len: int) → list

Return the list of indices of the next corner for each point in the path. A corner is defined as a point where the direction changes.

Parameters:

path (list) – A list of tuples representing points in the path.
path_len (int) – The length of the path.

Returns:

A list of indices of the next corner for each point in the path.

Return type:

list

vectorvision.polygons.get_pivot_points(path: list, next_corner: list, path_len: int) → list

Calculate the pivot points for each point in the path.

For each index i, the pivot point k is the furthest point forming a straight path between them, such that: all of the points j within i < j < k lie on a line connecting i, k.

Parameters:

path (list) – The list of points representing the path.
next_corner (list) – The list of indices of the next corner for each point in the path.
path_len (int) – The length of the path.

Returns:

A list of indexes of pivot points for each point of the path.

Return type:

list

vectorvision.polygons.get_segment_bounds_backward(backward_clips: list, segment_num: int, path_len: int) → list

Calculate the backward segment bounds.

Parameters:

backward_clips (list) – Backward clipping path.
segment_num (int) – Number of segments.
path_len (int) – Length of the path.

Returns:

Backward segment bounds.

Return type:

list

vectorvision.polygons.get_segment_bounds_forward(forward_clips: list, path_len: int) → tuple

Calculate the forward segment bounds.

Parameters:

forward_clips (list) – Forward clipping path.
path_len (int) – Length of the path.

Returns:

A tuple containing the number of segments and the forward segment bounds.

Return type:

tuple

vectorvision.polygons.penalty3(path: list, sums: list, i: int, j: int) → float

Calculate the penalty of an edge from point i to point j in the given path.

Parameters:

path (list) – List of points representing the path.
sums (list) – List of precomputed sums used for penalty calculations.
i (int) – Starting point index.
j (int) – Ending point index.

Returns:

Penalty value.

Return type:

float

vectorvision.polygons.vector_is_not_between(vector: list, right_constraint: list, left_constraint: list) → bool

Check if the vector is kept between two constraining vectors.

Parameters:

vector (list) – The vector to be checked.
right_constraint (list) – The right constraint vector.
left_constraint (list) – The left constraint vector.

Returns:

True if the vector is not between the two constraints, False otherwise.

Return type:

bool

vectorvision.smoothing module

vectorvision.smoothing.calculate_alpha(point0: tuple[float, float], point1: tuple[float, float], point2: tuple[float, float]) → float

Calculate the parameter alpha of Bezier curve necessary for corner detection and smoothing

Parameters:

point0 – starting point
point1 – vertex point
point2 – end point

Returns:

value of alpha parameter

vectorvision.smoothing.smooth(curve: _Curve, alphamax: float) → None

Calculate the point which is splitting section into two parts in given proportion

Parameters:

proportion – in which proportion segment should be splitted, ratio ax/ab
a – first point
b – second point

Returns:

point splitting segment ab in given proportion

vectorvision.utils module

vectorvision.utils.interval(proportion: float, a: tuple[float, float], b: tuple[float, float]) → tuple[float, float]

Calculate the point which is splitting section into two parts in given proportion

Parameters:

proportion – in which proportion segment should be splitted, ratio ax/ab
a – first point
b – second point

Returns:

point splitting segment ab in given proportion

vectorvision.vertex_adjustment module

vectorvision.vertex_adjustment.adjust_vertices(path: list[tuple[float, float]], polygon_points_idxs: list[int]) → _Curve

Adjust vertices of optimal polygon: calculate the intersection of

the two “optimal” line segments, then move it into the unit square if it lies outside.

Args:
path: list of points forming path polygon_points_idxs: list of points indexes in path contained in optimal polygon

Returns:
Curve representation of path

vectorvision.vertex_adjustment.calculate_intersection_point(first_parameters: tuple[float, float], second_parameters: tuple[float, float]) → tuple[float, float] | None

Calculate point of intersection for two linear functions

Parameters:

first_parameters – Tuple (a, b), parameters of first straight in format ax+b
second_parameters – Tuple (c, d), parameters of second straight in format cx+d

Returns:

Tuple (x, y) with point of intersection or None if straights are parallel

vectorvision.vertex_adjustment.find_closest_point_in_boundary(original_point: tuple[float, float], boundary_center: tuple[float, float], boundary_manhatan_range: float) → Point

Find point closest to original point but lying inside the square boundary around another point

Parameters:

original_point – location of original point
boundary_center – center of boundary
boundary_manhatan_range – distance along all main directions designating boundary location

Returns:

Point in boundary closest to original point

vectorvision.vertex_adjustment.fit_least_squares(points: list[tuple[float, float]]) → tuple[float, float]

Fit linear function to given points in 2D with least squares method

Parameters:: points – list of points to which straight should be fitted
Returns:: Tuple (a, b) with parameters of fitted straight in format y=ax+b