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