svg_path_editor.svg#

Classes#

`Point`	2D point with `decimal.Decimal` coordinates.
`SvgPoint`	Point used as target or vertex in an SVG path.
`SvgControlPoint`	Control point for Bézier segments with optional relation hints.
`SvgItem`	Base class for a single SVG path command and its numeric values.
`DummySvgItem`	Placeholder item used as a default reference owner for points.
`MoveTo`	SVG `M`/`m` command (move current point).
`LineTo`	SVG `L`/`l` command (line to point).
`CurveTo`	SVG `C`/`c` command (cubic Bézier curve).
`SmoothCurveTo`	SVG `S`/`s` command (smooth cubic Bézier curve).
`QuadraticBezierCurveTo`	SVG `Q`/`q` command (quadratic Bézier curve).
`SmoothQuadraticBezierCurveTo`	SVG `T`/`t` command (smooth quadratic Bézier curve).
`ClosePath`	SVG `Z`/`z` command (close current subpath).
`HorizontalLineTo`	SVG `H`/`h` command (horizontal line).
`VerticalLineTo`	SVG `V`/`v` command (vertical line).
`EllipticalArcTo`	SVG `A`/`a` command (elliptical arc).
`SvgPath`	An SVG path as a sequence of `SvgItem`.

Module Contents#

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

2D point with decimal.Decimal coordinates.

Parameters:

x (Number)
y (Number)

x: decimal.Decimal#

y: decimal.Decimal#

__iter__()[source]#

Iterate as (x, y).

Return type:: collections.abc.Iterator[decimal.Decimal]

__eq__(other)[source]#

Compare coordinates for equality.

Parameters:: other (Any)
Return type:: bool

__ne__(value, /)[source]#

Compare coordinates for inequality.

Parameters:: value (object)
Return type:: bool

property vec2: Vec2#

Exact conversion to Vec2.

Coordinates are converted to SymPy rationals via dec_to_rat().

Return type:: Vec2

__str__()[source]#

Human-readable representation (x, y) with decimal formatting.

Return type:: str

__repr__()[source]#

Debug representation Point(x, y) with decimal formatting.

Return type:: str

property length: decimal.Decimal#

Euclidean norm \(‖v‖_2 = \sqrt{x^2 + y^2}\).

Return type:: decimal.Decimal

property normalized: Point#

Unit vector \(v / ‖v‖_2\).

The zero vector is returned unchanged.

Return type:: Point

__neg__()[source]#

Unary minus \(-v\).

Return type:: Point

__add__(other)[source]#

Vector addition \(v + w\).

Parameters:: other (Point)
Return type:: Point

__sub__(other)[source]#

Vector subtraction \(v - w\).

Parameters:: other (Point)
Return type:: Point

__mul__(other)[source]#

Scalar multiplication \(v ⋅ λ\).

Parameters:: other (Number)
Return type:: Point

__truediv__(other)[source]#

Scalar division \(v / λ\).

Parameters:: other (Number)
Return type:: Point

class svg_path_editor.svg.SvgPoint(x, y)[source]#

Bases: svg_path_editor.geometry.Point

Point used as target or vertex in an SVG path.

Instances hold a back-reference to the SvgItem that owns them.

Parameters:

x (Number)
y (Number)

item_reference: SvgItem#

class svg_path_editor.svg.SvgControlPoint(point, relations)[source]#

Bases: SvgPoint

Control point for Bézier segments with optional relation hints.

The relations list can be used to store points that geometrically constrain this control point (e.g. endpoints of the segment).

Parameters:

point (Point)
relations (list[Point])

sub_index: int = 0#

relations: list[Point]#

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

Bases: abc.ABC

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

Parameters:

values (list[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

property target_location: SvgPoint#

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.svg.DummySvgItem[source]#

Bases: SvgItem

Placeholder item used as a default reference owner for points.

class svg_path_editor.svg.MoveTo(values, relative)[source]#

Bases: SvgItem

SVG M/m command (move current point).

Parameters:

values (list[T])
relative (bool)

key = 'M'#

class svg_path_editor.svg.LineTo(values, relative)[source]#

Bases: SvgItem

SVG L/l command (line to point).

Parameters:

values (list[T])
relative (bool)

key = 'L'#

class svg_path_editor.svg.CurveTo(values, relative)[source]#

Bases: SvgItem

SVG C/c command (cubic Bézier curve).

Parameters:

values (list[T])
relative (bool)

key = 'C'#

refresh_absolute_control_points(origin, previous_target)[source]#

Recompute absolute control points for a cubic Bézier segment.

Parameters:

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

Raises:

ValueError – If there is no previous item.

Return type:

None

reset_control_points(previous_target)[source]#

Reset control points to a smooth cubic curve between previous and target.

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

class svg_path_editor.svg.SmoothCurveTo(values, relative)[source]#

Bases: SvgItem

SVG S/s command (smooth cubic Bézier curve).

Parameters:

values (list[T])
relative (bool)

key = 'S'#

refresh_absolute_control_points(origin, previous_target)[source]#

Recompute absolute control points for a smooth cubic Bézier segment.

Parameters:

origin (Point) – Current subpath origin.
previous_target (SvgItem | None) – Previous item in the path, used for reflection.

Return type:

None

as_standalone_string()[source]#

Standalone SVG path fragment using M and an explicit C.

Return type:: str

reset_control_points(previous_target)[source]#

Reset the trailing control point for a smooth cubic curve.

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

set_control_location(idx, pt)[source]#

Move the effective control point of this smooth cubic to pt.

Parameters:

idx (int) – Ignored index, the smooth command has a single free control.
pt (Point) – New control point location in absolute coordinates.

Return type:

None

class svg_path_editor.svg.QuadraticBezierCurveTo(values, relative)[source]#

Bases: SvgItem

SVG Q/q command (quadratic Bézier curve).

Parameters:

values (list[T])
relative (bool)

key = 'Q'#

refresh_absolute_control_points(origin, previous_target)[source]#

Recompute absolute control point for a quadratic Bézier segment.

Parameters:

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

Raises:

ValueError – If there is no previous item.

Return type:

None

reset_control_points(previous_target)[source]#

Reset the control point to the midpoint of previous and target.

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

class svg_path_editor.svg.SmoothQuadraticBezierCurveTo(values, relative)[source]#

Bases: SvgItem

SVG T/t command (smooth quadratic Bézier curve).

Parameters:

values (list[T])
relative (bool)

key = 'T'#

refresh_absolute_control_points(origin, previous_target)[source]#

Recompute absolute control point for a smooth quadratic Bézier segment.

Parameters:

origin (Point) – Current subpath origin.
previous_target (SvgItem | None) – Previous item in the path, used for reflection.

Return type:

None

as_standalone_string()[source]#

Standalone SVG path fragment using M and an explicit Q.

Return type:: str

class svg_path_editor.svg.ClosePath(values, relative)[source]#

Bases: SvgItem

SVG Z/z command (close current subpath).

Parameters:

values (list[T])
relative (bool)

key = 'Z'#

refresh_absolute_points(origin, previous)[source]#

Set the target to the current subpath origin.

Parameters:

origin (Point) – Subpath origin point.
previous (SvgItem | None) – Previous item in the path, if any.

Return type:

None

class svg_path_editor.svg.HorizontalLineTo(values, relative)[source]#

Bases: SvgItem

SVG H/h command (horizontal line).

Parameters:

values (list[T])
relative (bool)

key = 'H'#

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

Rotate in place.

Only a rotation by 180 degrees affects pure horizontal segments. Other angles are handled at the path level by type changes.

Parameters:

ox (Number) – Rotation origin x coordinate (ignored here).
oy (Number) – Rotation origin y coordinate (ignored here).
degrees (Number) – Rotation angle in degrees.
force (bool) – Unused for this subclass.

Return type:

None

refresh_absolute_points(origin, previous)[source]#

Recompute absolute point for a horizontal line.

Parameters:

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

Return type:

None

set_target_location(pt)[source]#

Move the target x coordinate to pt.x (y stays unchanged).

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

class svg_path_editor.svg.VerticalLineTo(values, relative)[source]#

Bases: SvgItem

SVG V/v command (vertical line).

Parameters:

values (list[T])
relative (bool)

key = 'V'#

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

Rotate in place.

Only a rotation by 180 degrees affects pure vertical segments. Other angles are handled at the path level by type changes.

Parameters:

ox (Number) – Rotation origin x coordinate (ignored here).
oy (Number) – Rotation origin y coordinate (ignored here).
degrees (Number) – Rotation angle in degrees.
force (bool) – Unused for this subclass.

Return type:

None

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

Translate in place.

For absolute vertical lines, only the y coordinate is translated.

Parameters:

x (Number) – Translation in x direction (ignored).
y (Number) – Translation in y direction.
force (bool) – Unused for this subclass.

Return type:

None

scale(kx, ky)[source]#

Scale in place.

For vertical lines only y scaling applies.

Parameters:

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

Return type:

None

refresh_absolute_points(origin, previous)[source]#

Recompute absolute point for a vertical line.

Parameters:

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

Return type:

None

set_target_location(pt)[source]#

Move the target y coordinate to pt.y (x stays unchanged).

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

class svg_path_editor.svg.EllipticalArcTo(values, relative)[source]#

Bases: SvgItem

SVG A/a command (elliptical arc).

Parameters:

values (list[T])
relative (bool)

key = 'A'#

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

Translate in place.

For absolute arcs, only the arc target coordinates are translated.

Parameters:

x (Number) – Translation in x direction.
y (Number) – Translation in y direction.
force (bool) – Unused for this subclass.

Return type:

None

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

Rotate in place.

The arc’s rotation angle and target coordinates are updated accordingly.

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

scale(kx, ky)[source]#

Scale in place.

Radii, rotation angle, target and sweep flag are updated to reflect the scaling factors.

Parameters:

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

Return type:

None

to_geometry(*, n=None)[source]#

Return a parametric representation of this SVG elliptical arc.

The construction follows section B.2.4 of the SVG 2.0 specification (see https://svgwg.org/svg2-draft/implnote.html#ArcImplementationNotes) using SymPy for exact computations.

Parameters:: n (Precision | None) – Optional precision passed to evalf() for numeric evaluation.
Returns:: Parametric representation as ParametricEllipticalArc or a straight Line if the radii are zero.
Return type:: ParametricEllipticalArc | Line

property geometry: ParametricEllipticalArc | Line#

Geometric representation of this arc using to_geometry().

Return type:: ParametricEllipticalArc | Line

refresh_absolute_points(origin, previous)[source]#

Recompute the absolute target point for the arc.

Parameters:

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

Return type:

None

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

Serialize this arc (and optionally trailing arcs) to an SVG path fragment.

Parameters:

decimals (int | None) – Number of decimal places, or None for default.
minify (bool) – Use a compact group representation.
trailing_items (collections.abc.Iterable[SvgItem]) – Additional arc items to serialize together.

Return type:

str

class svg_path_editor.svg.SvgPath(path)[source]#

An SVG path as a sequence of SvgItem.

Parameters:: path (str | 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

svg_path_editor.svg#

Classes#

Module Contents#

This Page