svg_path_editor

Submodules

• svg_path_editor.geometry
• svg_path_editor.intersect
• svg_path_editor.math
• svg_path_editor.path_change_origin
• svg_path_editor.path_offset
• svg_path_editor.path_operations
• svg_path_editor.path_parser
• svg_path_editor.path_shade
• svg_path_editor.sub_path_bounds
• svg_path_editor.svg

Attributes

PNG
WEBP

Classes

Point	2D point with decimal.Decimal coordinates.
Precision	Control numerical precision for mixed symbolic/numeric operations.
BevelArced	Planar bevel face containing an elliptical-arc boundary.
BevelPolygon	Planar bevel face bounded by straight segments.
ImageFormat	Abstract image encoder.
PathShading	SVG fragments for shaded bevels.
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.
bevel_path(path, *, d[, prec])	Construct bevel faces for an offset of a simple closed path.
offset_path(path, *, d[, prec])	Offset a simple closed SVG path.
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.
lambert_from_angle(normal)	Lambertian diffuse intensity from a surface normal.
lambert_shading_base64(*, r, phi, locally_convex, ...)	Render a Lambert–shaded elliptical cone, return encoded bytes and base64 URI.
shade_path(svg, *, d, threshold, resolution[, ...])	Per-bevel Lambert shading for an SVG path.

Package Contents

class svg_path_editor.Point(x, y)

2D point with decimal.Decimal coordinates.

Parameters:

• x (Number)

• y (Number)

x: decimal.Decimal

y: decimal.Decimal

__iter__()

Iterate as (x, y).

Return type:

collections.abc.Iterator[decimal.Decimal]

__eq__(other)

Compare coordinates for exact equality.

Returns:

True iff other is a Point with equal x and y.

Parameters:

other (Any)

Return type:

bool

property vec2: Vec2

Exact conversion to Vec2.

Coordinates are converted to SymPy rationals via dec_to_rat().

Return type:

Vec2

__str__()

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

Return type:

str

__repr__()

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__()

Unary minus \(-v\).

Return type:

Point

__add__(other)

Vector addition \(v + w\).

Parameters:

other (Point)

Return type:

Point

__sub__(other)

Vector subtraction \(v - w\).

Parameters:

other (Point)

Return type:

Point

__mul__(other)

Scalar multiplication \(v ⋅ λ\).

Parameters:

other (Number)

Return type:

Point

__truediv__(other)

Scalar division \(v / λ\).

Parameters:

other (Number)

Return type:

Point

class svg_path_editor.Precision

Control numerical precision for mixed symbolic/numeric operations.

baseline defines the primary target precision, while additional can be used to carry extra guard digits during intermediate computations.

Variables:

• baseline – Baseline number of significant digits.

• additional – Additional guard digits to be used internally.

baseline: int

additional: int

property full: int

Full number of significant digits to use.

Returns:

baseline + additional.

Return type:

int

svg_path_editor.change_path_origin(svg, new_origin_index, subpath=None)

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

class svg_path_editor.BevelArced

Bases: NamedTuple

Planar bevel face containing an elliptical-arc boundary.

The path consists of two corresponding arc segments (original and offset) joined by straight segments.

Variables:

• path – Closed SvgPath describing the bevel face.

• c – Center of the supporting ellipse.

• r – Radii vector of the supporting ellipse.

• phi – Rotation of the ellipse in degrees.

• locally_convex – True iff the bevel is convex w.r.t. the interior.

path: SvgPath

c: Point

r: Point

phi: decimal.Decimal

locally_convex: bool

class svg_path_editor.BevelPolygon

Bases: NamedTuple

Planar bevel face bounded by straight segments.

Variables:

• path – Closed SvgPath describing the bevel polygon.

• outward_normal – Unit normal pointing out of the filled region.

path: SvgPath

outward_normal: Point

svg_path_editor.bevel_path(path, *, d, prec=None)

Construct bevel faces for an offset of a simple closed path.

Unlike offset_path(), this yields only the auxiliary faces that fill the bevel region between the original path and its offset.

Parameters:

• path (SvgPath) – Closed SvgPath with exactly one subpath M … Z, using only line and elliptical-arc segments.

• d (Number) – Offset distance. Positive values move edges towards the interior.

• prec (Precision | Literal['auto', 'auto-intersections'] | None) – Same semantics as in offset_path().

Returns:

Closed paths covering the bevel surface between original and offset.

Raises:

AssertionError – If path is not a single closed subpath of the expected form, or if an offset intersection cannot be computed.

Return type:

collections.abc.Iterable[BevelPolygon | BevelArced]

svg_path_editor.offset_path(path, *, d, prec=None)

Offset a simple closed SVG path.

The input must be a single closed subpath M … Z of straight lines and elliptical arcs. Every segment is offset by distance d (inwards for d > 0), and consecutive offset segments are intersected to form the output path.

Parameters:

• path (SvgPath) – Closed SvgPath with exactly one subpath M … Z, using only line and elliptical-arc segments.

• d (Number) – Offset distance. Positive values move edges towards the interior.

• prec (Precision | Literal['auto', 'auto-intersections'] | None) –

  Intersection and offsetting precision:

  • "auto": decimal precision + additional_digits for both offset geometry and intersections.

  • "auto-intersections": same automatic precision for intersections only; offsets remain symbolic.

  • Precision: use this precision everywhere.

  • None: purely symbolic where supported.

Returns:

The offset closed path.

Raises:

AssertionError – If path is not a single closed subpath of the expected form, or if an offset intersection cannot be computed.

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)

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)

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

svg_path_editor.PNG

svg_path_editor.WEBP

class svg_path_editor.ImageFormat

Bases: Protocol

Abstract image encoder.

Variables:

• media_type – MIME type of the encoded image.

• extension – File extension (without dot).

media_type: ClassVar[str]

extension: ClassVar[str]

encode(data)

Encode an RGBA image.

Parameters:

data (numpy.ndarray) – (H, W, 4) uint8 array in RGBA order.

Returns:

Encoded image bytes.

Return type:

bytes | bytearray

class svg_path_editor.PathShading

SVG fragments for shaded bevels.

Variables:

• defs_body – Elements for a document-wide <defs> (e.g. shared <image> or <clipPath> definitions).

• body – Per-path drawing elements (e.g. <path>, <g>, <use>) that reference defs_body.

defs_body: list[str]

body: list[str]

svg_path_editor.lambert_from_angle(normal)

Lambertian diffuse intensity from a surface normal.

The light direction is fixed to \((0, -1, 1)\) in world space. The result is

\[I = \max(0, \hat{\mathbf{n}}\cdot\hat{\mathbf{L}}),\]

evaluated via the signed angle of normal in the \(xy\)-plane.

Parameters:

normal (Point) – Surface normal.

Returns:

Lambertian intensity in \([0, 1]\).

Return type:

decimal.Decimal

svg_path_editor.lambert_shading_base64(*, r, phi, locally_convex, resolution, t=0.25, format=WEBP, seed=None)

Render a Lambert–shaded elliptical cone, return encoded bytes and base64 URI.

The cone radii are \(r = (r_x, r_y)\) in image space. For a point \((x, y)\) on the grid

\[(x, y) \in \left[-\frac{1}{r_x}, \frac{1}{r_x}\right] \times \left[-\frac{1}{r_y}, \frac{1}{r_y}\right],\]

the unnormalized normal is

\[\mathbf{n}(x, y) = \left(\frac{x}{r_x^2}, \frac{y}{r_y^2}, 1\right).\]

The Lambert term is

\[I(x, y) = \max\left(0, \hat{\mathbf{n}}(x, y)\cdot\hat{\mathbf{L}}\right),\]

where \(\hat{\mathbf{L}}\) is the unit vector from \((0, s, 1)\), with \(s = -1\) if locally_convex else \(+1\), rotated in the \(xy\)-plane by \(-\varphi\) degrees.

Grayscale is binary (0 or 255) according to \(I > t\). Alpha is a symmetric remap of \(I\) around \(t\):

\[\begin{split}\alpha(I) = \begin{cases} \dfrac{I - t}{1 - t}, & I \geq t,\\ \dfrac{t - I}{t}, & I < t. \end{cases}\end{split}\]

Before 8-bit quantization, uniform noise in \([0, 1]\) is added to alpha for dithering.

The final RGBA image is encoded with format and returned both as raw bytes and as a data:...;base64,... URI.

Parameters:

• r (Point) – Ellipse radii in \(x\) and \(y\).

• phi (decimal.Decimal) – Rotation in degrees of the light direction in image space (clockwise in screen coordinates).

• locally_convex (bool) – If true, the base light direction is \((0, -1, 1)\), otherwise \((0, 1, 1)\).

• resolution (float) – Pixels per SVG unit. Image size is \(\lceil 2 r_x \, \mathrm{resolution} \rceil \times \lceil 2 r_y \, \mathrm{resolution} \rceil\).

• t (float) – Neutral Lambert intensity in \([0, 1]\) (threshold).

• format (ImageFormat) – Image format to use.

• seed (int | None) – RNG seed for alpha dithering; None is non-deterministic.

Returns:

(img_bytes, img_data_uri) with img_data_uri suitable for SVG href.

Return type:

tuple[bytes, str]

svg_path_editor.shade_path(svg, *, d, threshold, resolution, max_opacity=1, format=WEBP, seed=None, prec=None)

Per-bevel Lambert shading for an SVG path.

The path is decomposed into bevel regions via svg_path_editor.path_offset.bevel_path(). Flat bevel polygons are shaded analytically with lambert_from_angle(). Curved bevel arcs use a small Lambert RGBA texture from lambert_shading_base64(), referenced by <image> / <use> and clipped to the arc geometry.

For each bevel polygon:

• One <path> is emitted with fill="white" or fill="black" depending on whether the intensity is above or below threshold.

• Opacity is a symmetric remap of the intensity around threshold in \([0, 1]\), scaled by max_opacity.

For each bevel arc:

• A Lambert cone texture is generated (or reused from a cache) for (r.x, r.y, phi, locally_convex).

• A base <image> at the origin with size \(2 r_x \times 2 r_y\) is placed in PathShading.defs_body once per unique key.

• For each occurrence, a <clipPath> with the bevel geometry and a <use> of the base image are emitted into PathShading.body, translated so the image origin matches the lower-left corner of the ellipse bounding box, and rotated by phi around the ellipse center if non-zero.

• <use> carries opacity max_opacity when it is less than 1.

To integrate into an SVG, place all defs_body entries inside a single document-level <defs> and insert body where the path should render.

Parameters:

• svg (SvgPath) – Input path to bevel and shade.

• d (Number) – Offset distance for bevel_path().

• threshold (Number) – Neutral Lambert intensity in \([0, 1]\), shared between flat bevels and textures.

• resolution (float) – Pixels per SVG unit for generated textures; image dimensions follow lambert_shading_base64().

• max_opacity (Number) – Global opacity scale in \([0, 1]\).

• format (ImageFormat) – Texture format, e.g. WEBP or PNG.

• seed (int | None) – RNG seed for alpha dithering in lambert_shading_base64(); None for non-deterministic.

• prec (Precision | Literal['auto', 'auto-intersections'] | None) – Precision/geometry mode passed to bevel_path(). "auto" and "auto-intersections" select automatic strategies; None uses the default.

Return type:

PathShading

class svg_path_editor.SvgItem(values, relative)

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)

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)

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)

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)

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)

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)

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()

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)

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)

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)

Scale in place.

Parameters:

• kx (Number) – Scale factor for x coordinates.

• ky (Number) – Scale factor for y coordinates.

Return type:

None

scaled(kx, ky)

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)

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)

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)

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)

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)

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()

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=())

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)

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__()

Return as_string() with default options.

Return type:

str

class svg_path_editor.SvgPath(path)

An SVG path as a sequence of SvgItem.

Parameters:

path (str | list[SvgItem])

clone()

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)

Translate in place.

Parameters:

• dx (Number) – Translation in x direction.

• dy (Number) – Translation in y direction.

Return type:

None

translated(dx, dy)

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)

Scale in place.

Parameters:

• kx (Number) – Scale factor for x coordinates.

• ky (Number) – Scale factor for y coordinates.

Return type:

None

scaled(kx, ky)

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)

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)

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)

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)

Remove the given item.

Parameters:

item (SvgItem) – Item to remove.

Raises:

ValueError – If the item is not present.

Return type:

None

insert(index, item)

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)

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)

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)

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()

Recompute absolute positions for all items in the path.

This should be called after structural or coordinate changes.

Return type:

None

__format__(format_spec)

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__()

Return as_string() with default options.

Return type:

str