svg_path_editor¶

Submodules¶

Classes¶

`Point`	Simple 2D point.
`SvgItem`	Base class for a single SVG path command and its numeric values.
`SvgPath`	An SVG path as a sequence of `SvgItem`.

Functions¶

`change_path_origin`(svg, new_origin_index[, subpath])	Return a new path where the origin of a (sub)path is moved.
`optimize_path`(svg, *[, remove_useless_commands, ...])	Optimize the representation of an SVG path.
`reverse_path`(svg[, subpath_of_item])	Reverse the drawing direction of a path or sub-path.

Package Contents¶

svg_path_editor.change_path_origin(svg, new_origin_index, subpath=None)[source]¶

Return a new path where the origin of a (sub)path is moved.

The command at new_origin_index becomes the first command of the affected subpath segment; all items of that subpath are rotated accordingly. If subpath is True, only the subpath containing new_origin_index is transformed; if False/None, the whole path is treated as a single segment.

Parameters:

svg (SvgPath) – Original path to transform.
new_origin_index (int) – Index of the command that should become the new origin within its subpath.
subpath (bool | None) – If True, restrict the change to the subpath containing new_origin_index; if False or None, treat the full path segment as one subpath.

Returns:

A new SvgPath instance with the origin moved and the path representation optimized.

Return type:

SvgPath

svg_path_editor.optimize_path(svg, *, remove_useless_commands=False, remove_orphan_dots=False, use_shorthands=False, use_horizontal_and_vertical_lines=False, use_relative_absolute=False, use_reverse=False, use_close_path=False)[source]¶

Optimize the representation of an SVG path.

The function can apply several optional passes that can be enabled using the parameters.

Parameters:

svg (SvgPath) – Input path.
remove_useless_commands (bool) – Remove redundant M/Z commands and degenerate L/H/V segments.
remove_orphan_dots (bool) – Remove empty closed subpaths (M immediately followed by Z).
use_shorthands (bool) – Convert eligible C/Q segments to S/T where possible.
use_horizontal_and_vertical_lines (bool) – Replace L with H or V where possible.
use_relative_absolute (bool) – Choose between relative and absolute commands per segment to minimize size.
use_reverse (bool) – Reverse the path direction if that yields a shorter minified representation. This can affect stroked paths.
use_close_path (bool) – Convert final line segments that return to start into Z. This can affect stroked paths.

Returns:

A new, possibly shorter, but geometrically equivalent path.

Return type:

SvgPath

svg_path_editor.reverse_path(svg, subpath_of_item=None)[source]¶

Reverse the drawing direction of a path or sub-path.

Parameters:

svg (SvgPath) – Input path.
subpath_of_item (int | None) – Index of an item within the sub-path to reverse, or None to reverse the entire path.

Returns:

A new path with the selected segment reversed. Geometry is preserved, but command types and relative/absolute representation may change.

Return type:

SvgPath

class svg_path_editor.Point(x, y)[source]¶

Simple 2D point.

Parameters:

x (Number)
y (Number)

x: decimal.Decimal¶

y: decimal.Decimal¶

class svg_path_editor.SvgItem(values, relative)[source]¶

Bases: abc.ABC

Base class for a single SVG path command and its numeric values.

Parameters:

values (list[SvgItem.__init__.T])
relative (bool)

_relative: bool¶

values: list[decimal.Decimal]¶

previous_point: Point¶

absolute_points: list[SvgPoint] = []¶

absolute_control_points: list[SvgControlPoint] = []¶

static make(raw_item)[source]¶

Construct the appropriate subclass of SvgItem from a parsed command and its parameter strings.

Parameters:: raw_item (list[str]) – List starting with the command letter followed by numeric parameters as strings (e.g. ["M", "0", "0"]).
Raises:: ValueError – If the item is empty or the command is invalid.
Return type:: SvgItem

static make_from(origin, previous, new_type)[source]¶

Create a new SvgItem of type new_type from an existing item.

The new item preserves the current target location and, where possible, the original control point geometry.

Parameters:

origin (SvgItem) – Existing item whose geometry should be preserved.
previous (SvgItem) – Previous item in the path, used for control point defaults.
new_type (str) – New SVG command letter (e.g. "L" or "c").

Raises:

ValueError – If new_type is not supported.

Return type:

SvgItem

refresh_absolute_points(origin, previous)[source]¶

Recalculate absolute points from stored values and the previous item.

Parameters:

origin (Point) – Current subpath origin (last M/m or Z).
previous (SvgItem | None) – Previous item in the path, or None for the first item.

Return type:

None

property relative: bool¶

Whether this command is stored in relative coordinates.

Return type:: bool

refresh_absolute_control_points(origin, previous_target)[source]¶

Recalculate absolute control points.

The default implementation assumes there are no control points.

Parameters:

origin (Point) – Current subpath origin.
previous_target (SvgItem | None) – Previous item in the path, if any.

Return type:

None

reset_control_points(previous_target)[source]¶

Reset control points to a default geometry between previous and target.

Subclasses for curve commands override this to compute reasonable defaults.

Parameters:: previous_target (SvgItem) – Previous item in the path.
Return type:: None

refresh(origin, previous)[source]¶

Recompute all absolute points and re-bind back-references.

Parameters:

origin (Point) – Current subpath origin.
previous (SvgItem | None) – Previous item in the path, or None for the first item.

Return type:

None

clone()[source]¶

Return a shallow clone of this item, retaining its subclass.

Values, relativity and previous_point are copied. Absolute points and control points need to be recomputed via refresh(), as is done in SvgPath.clone().

Return type:: Self

translate(x, y, force=False)[source]¶

Translate in place.

Relative items are translated only if force is true; otherwise their stored deltas are left unchanged.

Parameters:

x (Number) – Translation in x direction.
y (Number) – Translation in y direction.
force (bool) – Also adjust relative coordinates.

Return type:

None

translated(x, y, force=False)[source]¶

Return a translated copy. See translate() for details.

Parameters:

x (Number) – Translation in x direction.
y (Number) – Translation in y direction.
force (bool) – Also adjust relative coordinates.

Return type:

SvgItem

scale(kx, ky)[source]¶

Scale in place.

Parameters:

kx (Number) – Scale factor for x coordinates.
ky (Number) – Scale factor for y coordinates.

Return type:

None

scaled(kx, ky)[source]¶

Return a scaled copy.

Parameters:

kx (Number) – Scale factor for x coordinates.
ky (Number) – Scale factor for y coordinates.

Return type:

SvgItem

rotate(ox, oy, degrees, force=False)[source]¶

Rotate the item in place around (ox, oy).

For relative items, rotation is performed around (0, 0) unless force is true.

Parameters:

ox (Number) – Rotation origin x coordinate.
oy (Number) – Rotation origin y coordinate.
degrees (Number) – Rotation angle in degrees.
force (bool) – Rotate relative coordinates around (ox, oy).

Return type:

None

rotated(ox, oy, degrees, force=False)[source]¶

Return a rotated copy around (ox, oy). See rotate() for details.

Parameters:

ox (Number) – Rotation origin x coordinate.
oy (Number) – Rotation origin y coordinate.
degrees (Number) – Rotation angle in degrees.
force (bool) – Rotate relative coordinates around (ox, oy).

Return type:

SvgItem

target_location()[source]¶

Final absolute point reached by this item.

Return type:: SvgPoint

set_target_location(pt)[source]¶

Move the geometric target of this command to pt.

Parameters:: pt (Point) – New target location in absolute coordinates.
Return type:: None

set_control_location(idx, pt)[source]¶

Move control point idx to pt.

Only meaningful for commands storing Bézier handles.

Parameters:

idx (int) – Index of the control point to move.
pt (Point) – New control point location in absolute coordinates.

Return type:

None

property control_locations: list[SvgControlPoint]¶

Absolute control points associated with this item.

Return type:: list[SvgControlPoint]

get_type(ignore_is_relative=False)[source]¶

Return the SVG command letter for this item (e.g. "M" or "l").

Parameters:: ignore_is_relative (bool) – Always return the uppercase key regardless of relative.
Return type:: str

as_standalone_string()[source]¶

Return a standalone path string for this command.

The result starts with an M to this command’s previous_point followed by the command itself.

Return type:: str

as_string(decimals=None, minify=False, trailing_items=())[source]¶

Serialize this command into an SVG path fragment.

Optionally additional same-typed trailing_items can be appended in a compact form.

Parameters:

decimals (int | None) – Number of decimal places, or None for default.
minify (bool) – Use a more compact numeric representation.
trailing_items (collections.abc.Iterable[SvgItem]) – Additional items of the same type to serialize in the same command group.

Return type:

str

__format__(format_spec)[source]¶

Format this item using as_string().

The format_spec can be used to control decimal places and minification:

"" (empty): use as_string() defaults
".3": decimals=3
"m": minify=True
".3m" or "m.3": decimals=3, minify=True

Any other characters are currently ignored.

Parameters:: format_spec (str) – Format specification string (e.g. ".3m").
Return type:: str

__str__()[source]¶

Return as_string() with default options.

Return type:: str

class svg_path_editor.SvgPath(path)[source]¶

An SVG path as a sequence of SvgItem.

Parameters:: path (str)

path: list[SvgItem]¶

clone()[source]¶

Return a deep clone of this path.

All contained items are cloned as well, and absolute positions are recomputed.

Return type:: SvgPath

translate(dx, dy)[source]¶

Translate in place.

Parameters:

dx (Number) – Translation in x direction.
dy (Number) – Translation in y direction.

Return type:

None

translated(dx, dy)[source]¶

Return a translated copy of this path.

Parameters:

dx (Number) – Translation in x direction.
dy (Number) – Translation in y direction.

Return type:

SvgPath

scale(kx, ky)[source]¶

Scale in place.

Parameters:

kx (Number) – Scale factor for x coordinates.
ky (Number) – Scale factor for y coordinates.

Return type:

None

scaled(kx, ky)[source]¶

Return a scaled copy of this path.

Parameters:

kx (Number) – Scale factor for x coordinates.
ky (Number) – Scale factor for y coordinates.

Return type:

SvgPath

rotate(ox, oy, degrees)[source]¶

Rotate in place around (ox, oy).

May also normalize horizontal/vertical segments after rotation.

Parameters:

ox (Number) – Rotation origin x coordinate.
oy (Number) – Rotation origin y coordinate.
degrees (Number) – Rotation angle in degrees.

Return type:

None

rotated(ox, oy, degrees)[source]¶

Return a rotated copy of this path. See rotate() for details.

Parameters:

ox (Number) – Rotation origin x coordinate.
oy (Number) – Rotation origin y coordinate.
degrees (Number) – Rotation angle in degrees.

Return type:

SvgPath

property relative: bool¶

Indicate whether all items are stored as relative commands.

Mixed paths (some absolute, some relative) return False.

Return type:: bool

with_relative(new_relative)[source]¶

Return a new path with all items converted to the requested representation.

Parameters:: new_relative (bool) – Target representation (True for relative).
Return type:: SvgPath

remove(item)[source]¶

Remove the given item.

Parameters:: item (SvgItem) – Item to remove.
Raises:: ValueError – If the item is not present.
Return type:: None

insert(index, item)[source]¶

Insert item before index.

Parameters:

index (int) – Index before which to insert.
item (SvgItem) – Item to insert.

Return type:

None

change_type(index, new_type)[source]¶

Change the command type of the item at index in place.

Parameters:

index (int) – The index of the item whose type should be changed.
new_type (str) – New SVG command letter (e.g. "L" or "c").

Returns:

Newly created SvgItem replacing the item at index, or None if index is not in the path or is the first item.

Return type:

SvgItem | None

as_string(decimals=None, minify=False)[source]¶

Serialize the entire path to an SVG path data string.

Parameters:

decimals (int | None) – Number of decimal places, or None for default.
minify (bool) – Use a compact representation.

Return type:

str

property target_locations: list[SvgPoint]¶

Final absolute points for each item in the path.

Return type:: list[SvgPoint]

property control_locations: list[SvgControlPoint]¶

Flattened list of all absolute control points for the path.

Return type:: list[SvgControlPoint]

set_location(pt_reference, to)[source]¶

Move the given point to to.

The reference must come from a previously queried point list (e.g. target_locations or control_locations).

Parameters:

pt_reference (SvgPoint) – Point (target or control) to be moved.
to (Point) – New absolute location for the point.

Return type:

None

refresh_absolute_positions()[source]¶

Recompute absolute positions for all items in the path.

This should be called after structural or coordinate changes.

Return type:: None

__format__(format_spec)[source]¶

Format this path using as_string().

The format_spec can be used to control decimal places and minification, following the same rules as SvgItem.__format__():

"" (empty): use as_string() defaults
".3": decimals=3
"m": minify=True
".3m" or "m.3": decimals=3, minify=True

Any other characters are currently ignored.

Parameters:: format_spec (str) – Format specification string (e.g. ".3m").
Return type:: str

__str__()[source]¶

Return as_string() with default options.

Return type:: str