svg_path_editor.svg =================== .. py:module:: svg_path_editor.svg Classes ------- .. autoapisummary:: svg_path_editor.svg.Point svg_path_editor.svg.SvgPoint svg_path_editor.svg.SvgControlPoint svg_path_editor.svg.SvgItem svg_path_editor.svg.DummySvgItem svg_path_editor.svg.MoveTo svg_path_editor.svg.LineTo svg_path_editor.svg.CurveTo svg_path_editor.svg.SmoothCurveTo svg_path_editor.svg.QuadraticBezierCurveTo svg_path_editor.svg.SmoothQuadraticBezierCurveTo svg_path_editor.svg.ClosePath svg_path_editor.svg.HorizontalLineTo svg_path_editor.svg.VerticalLineTo svg_path_editor.svg.EllipticalArcTo svg_path_editor.svg.SvgPath Module Contents --------------- .. py:class:: Point(x, y) 2D point with :class:`decimal.Decimal` coordinates. .. py:attribute:: x :type: decimal.Decimal .. py:attribute:: y :type: decimal.Decimal .. py:method:: __iter__() Iterate as ``(x, y)``. .. py:method:: __eq__(other) Compare coordinates for exact equality. :return: ``True`` iff ``other`` is a :class:`Point` with equal ``x`` and ``y``. .. py:property:: vec2 :type: Vec2 Exact conversion to :class:`Vec2`. Coordinates are converted to SymPy rationals via :func:`dec_to_rat`. .. py:method:: __str__() Human-readable representation ``(x, y)`` with decimal formatting. .. py:method:: __repr__() Debug representation ``Point(x, y)`` with decimal formatting. .. py:property:: length :type: decimal.Decimal Euclidean norm :math:`‖v‖_2 = \sqrt{x^2 + y^2}`. .. py:property:: normalized :type: Point Unit vector :math:`v / ‖v‖_2`. The zero vector is returned unchanged. .. py:method:: __neg__() Unary minus :math:`-v`. .. py:method:: __add__(other) Vector addition :math:`v + w`. .. py:method:: __sub__(other) Vector subtraction :math:`v - w`. .. py:method:: __mul__(other) Scalar multiplication :math:`v ⋅ λ`. .. py:method:: __truediv__(other) Scalar division :math:`v / λ`. .. py:class:: SvgPoint(x, y) Bases: :py:obj:`svg_path_editor.geometry.Point` Point used as target or vertex in an SVG path. Instances hold a back-reference to the :class:`SvgItem` that owns them. .. py:attribute:: item_reference :type: SvgItem .. py:class:: SvgControlPoint(point, relations) Bases: :py:obj:`SvgPoint` Control point for Bézier segments with optional relation hints. The :attr:`relations` list can be used to store points that geometrically constrain this control point (e.g. endpoints of the segment). .. py:attribute:: sub_index :type: int :value: 0 .. py:attribute:: relations :type: list[svg_path_editor.geometry.Point] .. py:class:: SvgItem(values, relative) Bases: :py:obj:`abc.ABC` Base class for a single SVG path command and its numeric values. .. py:attribute:: _relative :type: bool .. py:attribute:: values :type: list[decimal.Decimal] .. py:attribute:: previous_point :type: svg_path_editor.geometry.Point .. py:attribute:: absolute_points :type: list[SvgPoint] :value: [] .. py:attribute:: absolute_control_points :type: list[SvgControlPoint] :value: [] .. py:method:: make(raw_item) :staticmethod: Construct the appropriate subclass of :class:`SvgItem` from a parsed command and its parameter strings. :param raw_item: 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. .. py:method:: make_from(origin, previous, new_type) :staticmethod: Create a new :class:`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. :param origin: Existing item whose geometry should be preserved. :param previous: Previous item in the path, used for control point defaults. :param new_type: New SVG command letter (e.g. ``"L"`` or ``"c"``). :raises ValueError: If ``new_type`` is not supported. .. py:method:: refresh_absolute_points(origin, previous) Recalculate absolute points from stored values and the previous item. :param origin: Current subpath origin (last ``M``/``m`` or ``Z``). :param previous: Previous item in the path, or ``None`` for the first item. .. py:property:: relative :type: bool Whether this command is stored in relative coordinates. .. py:method:: refresh_absolute_control_points(origin, previous_target) Recalculate absolute control points. The default implementation assumes there are no control points. :param origin: Current subpath origin. :param previous_target: Previous item in the path, if any. .. py:method:: 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. :param previous_target: Previous item in the path. .. py:method:: refresh(origin, previous) Recompute all absolute points and re-bind back-references. :param origin: Current subpath origin. :param previous: Previous item in the path, or ``None`` for the first item. .. py:method:: clone() Return a shallow clone of this item, retaining its subclass. Values, relativity and :attr:`previous_point` are copied. Absolute points and control points need to be recomputed via :meth:`refresh`, as is done in :meth:`SvgPath.clone`. .. py:method:: translate(x, y, force = False) Translate in place. Relative items are translated only if ``force`` is true; otherwise their stored deltas are left unchanged. :param x: Translation in x direction. :param y: Translation in y direction. :param force: Also adjust relative coordinates. .. py:method:: translated(x, y, force = False) Return a translated copy. See :meth:`translate` for details. :param x: Translation in x direction. :param y: Translation in y direction. :param force: Also adjust relative coordinates. .. py:method:: scale(kx, ky) Scale in place. :param kx: Scale factor for x coordinates. :param ky: Scale factor for y coordinates. .. py:method:: scaled(kx, ky) Return a scaled copy. :param kx: Scale factor for x coordinates. :param ky: Scale factor for y coordinates. .. py:method:: 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. :param ox: Rotation origin x coordinate. :param oy: Rotation origin y coordinate. :param degrees: Rotation angle in degrees. :param force: Rotate relative coordinates around ``(ox, oy)``. .. py:method:: rotated(ox, oy, degrees, force = False) Return a rotated copy around ``(ox, oy)``. See :meth:`rotate` for details. :param ox: Rotation origin x coordinate. :param oy: Rotation origin y coordinate. :param degrees: Rotation angle in degrees. :param force: Rotate relative coordinates around ``(ox, oy)``. .. py:property:: target_location :type: SvgPoint Final absolute point reached by this item. .. py:method:: set_target_location(pt) Move the geometric target of this command to ``pt``. :param pt: New target location in absolute coordinates. .. py:method:: set_control_location(idx, pt) Move control point ``idx`` to ``pt``. Only meaningful for commands storing Bézier handles. :param idx: Index of the control point to move. :param pt: New control point location in absolute coordinates. .. py:property:: control_locations :type: list[SvgControlPoint] Absolute control points associated with this item. .. py:method:: get_type(ignore_is_relative = False) Return the SVG command letter for this item (e.g. ``"M"`` or ``"l"``). :param ignore_is_relative: Always return the uppercase key regardless of :attr:`relative`. .. py:method:: as_standalone_string() Return a standalone path string for this command. The result starts with an ``M`` to this command’s :attr:`previous_point` followed by the command itself. .. py:method:: 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. :param decimals: Number of decimal places, or ``None`` for default. :param minify: Use a more compact numeric representation. :param trailing_items: Additional items of the same type to serialize in the same command group. .. py:method:: __format__(format_spec) Format this item using :meth:`as_string`. The ``format_spec`` can be used to control decimal places and minification: * ``""`` (empty): use :meth:`as_string` defaults * ``".3"``: ``decimals=3`` * ``"m"``: ``minify=True`` * ``".3m"`` or ``"m.3"``: ``decimals=3``, ``minify=True`` Any other characters are currently ignored. :param format_spec: Format specification string (e.g. ``".3m"``). .. py:method:: __str__() Return :meth:`as_string` with default options. .. py:class:: DummySvgItem Bases: :py:obj:`SvgItem` Placeholder item used as a default reference owner for points. .. py:class:: MoveTo(values, relative) Bases: :py:obj:`SvgItem` SVG ``M``/``m`` command (move current point). .. py:attribute:: key :value: 'M' .. py:class:: LineTo(values, relative) Bases: :py:obj:`SvgItem` SVG ``L``/``l`` command (line to point). .. py:attribute:: key :value: 'L' .. py:class:: CurveTo(values, relative) Bases: :py:obj:`SvgItem` SVG ``C``/``c`` command (cubic Bézier curve). .. py:attribute:: key :value: 'C' .. py:method:: refresh_absolute_control_points(origin, previous_target) Recompute absolute control points for a cubic Bézier segment. :param origin: Current subpath origin. :param previous_target: Previous item in the path. :raises ValueError: If there is no previous item. .. py:method:: reset_control_points(previous_target) Reset control points to a smooth cubic curve between previous and target. :param previous_target: Previous item in the path. .. py:class:: SmoothCurveTo(values, relative) Bases: :py:obj:`SvgItem` SVG ``S``/``s`` command (smooth cubic Bézier curve). .. py:attribute:: key :value: 'S' .. py:method:: refresh_absolute_control_points(origin, previous_target) Recompute absolute control points for a smooth cubic Bézier segment. :param origin: Current subpath origin. :param previous_target: Previous item in the path, used for reflection. .. py:method:: as_standalone_string() Standalone SVG path fragment using ``M`` and an explicit ``C``. .. py:method:: reset_control_points(previous_target) Reset the trailing control point for a smooth cubic curve. :param previous_target: Previous item in the path. .. py:method:: set_control_location(idx, pt) Move the effective control point of this smooth cubic to ``pt``. :param idx: Ignored index, the smooth command has a single free control. :param pt: New control point location in absolute coordinates. .. py:class:: QuadraticBezierCurveTo(values, relative) Bases: :py:obj:`SvgItem` SVG ``Q``/``q`` command (quadratic Bézier curve). .. py:attribute:: key :value: 'Q' .. py:method:: refresh_absolute_control_points(origin, previous_target) Recompute absolute control point for a quadratic Bézier segment. :param origin: Current subpath origin. :param previous_target: Previous item in the path. :raises ValueError: If there is no previous item. .. py:method:: reset_control_points(previous_target) Reset the control point to the midpoint of previous and target. :param previous_target: Previous item in the path. .. py:class:: SmoothQuadraticBezierCurveTo(values, relative) Bases: :py:obj:`SvgItem` SVG ``T``/``t`` command (smooth quadratic Bézier curve). .. py:attribute:: key :value: 'T' .. py:method:: refresh_absolute_control_points(origin, previous_target) Recompute absolute control point for a smooth quadratic Bézier segment. :param origin: Current subpath origin. :param previous_target: Previous item in the path, used for reflection. .. py:method:: as_standalone_string() Standalone SVG path fragment using ``M`` and an explicit ``Q``. .. py:class:: ClosePath(values, relative) Bases: :py:obj:`SvgItem` SVG ``Z``/``z`` command (close current subpath). .. py:attribute:: key :value: 'Z' .. py:method:: refresh_absolute_points(origin, previous) Set the target to the current subpath origin. :param origin: Subpath origin point. :param previous: Previous item in the path, if any. .. py:class:: HorizontalLineTo(values, relative) Bases: :py:obj:`SvgItem` SVG ``H``/``h`` command (horizontal line). .. py:attribute:: key :value: 'H' .. py:method:: rotate(ox, oy, degrees, force = False) Rotate in place. Only a rotation by 180 degrees affects pure horizontal segments. Other angles are handled at the path level by type changes. :param ox: Rotation origin x coordinate (ignored here). :param oy: Rotation origin y coordinate (ignored here). :param degrees: Rotation angle in degrees. :param force: Unused for this subclass. .. py:method:: refresh_absolute_points(origin, previous) Recompute absolute point for a horizontal line. :param origin: Current subpath origin. :param previous: Previous item in the path. .. py:method:: set_target_location(pt) Move the target x coordinate to ``pt.x`` (y stays unchanged). :param pt: New target location. .. py:class:: VerticalLineTo(values, relative) Bases: :py:obj:`SvgItem` SVG ``V``/``v`` command (vertical line). .. py:attribute:: key :value: 'V' .. py:method:: rotate(ox, oy, degrees, force = False) Rotate in place. Only a rotation by 180 degrees affects pure vertical segments. Other angles are handled at the path level by type changes. :param ox: Rotation origin x coordinate (ignored here). :param oy: Rotation origin y coordinate (ignored here). :param degrees: Rotation angle in degrees. :param force: Unused for this subclass. .. py:method:: translate(x, y, force = False) Translate in place. For absolute vertical lines, only the y coordinate is translated. :param x: Translation in x direction (ignored). :param y: Translation in y direction. :param force: Unused for this subclass. .. py:method:: scale(kx, ky) Scale in place. For vertical lines only y scaling applies. :param kx: Scale factor for x coordinates (ignored). :param ky: Scale factor for y coordinates. .. py:method:: refresh_absolute_points(origin, previous) Recompute absolute point for a vertical line. :param origin: Current subpath origin. :param previous: Previous item in the path. .. py:method:: set_target_location(pt) Move the target y coordinate to ``pt.y`` (x stays unchanged). :param pt: New target location. .. py:class:: EllipticalArcTo(values, relative) Bases: :py:obj:`SvgItem` SVG ``A``/``a`` command (elliptical arc). .. py:attribute:: key :value: 'A' .. py:method:: translate(x, y, force = False) Translate in place. For absolute arcs, only the arc target coordinates are translated. :param x: Translation in x direction. :param y: Translation in y direction. :param force: Unused for this subclass. .. py:method:: rotate(ox, oy, degrees, force = False) Rotate in place. The arc’s rotation angle and target coordinates are updated accordingly. :param ox: Rotation origin x coordinate. :param oy: Rotation origin y coordinate. :param degrees: Rotation angle in degrees. :param force: Rotate relative coordinates around ``(ox, oy)``. .. py:method:: scale(kx, ky) Scale in place. Radii, rotation angle, target and sweep flag are updated to reflect the scaling factors. :param kx: Scale factor for x coordinates. :param ky: Scale factor for y coordinates. .. py:method:: to_geometry(*, n = None) 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. :param n: Optional precision passed to :func:`evalf` for numeric evaluation. :return: Parametric representation as :class:`ParametricEllipticalArc` or a straight :class:`Line` if the radii are zero. .. py:property:: geometry :type: svg_path_editor.geometry.ParametricEllipticalArc | svg_path_editor.geometry.Line Geometric representation of this arc using :meth:`to_geometry`. .. py:method:: refresh_absolute_points(origin, previous) Recompute the absolute target point for the arc. :param origin: Current subpath origin. :param previous: Previous item in the path. .. py:method:: as_string(decimals = None, minify = False, trailing_items = ()) Serialize this arc (and optionally trailing arcs) to an SVG path fragment. :param decimals: Number of decimal places, or ``None`` for default. :param minify: Use a compact group representation. :param trailing_items: Additional arc items to serialize together. .. py:class:: SvgPath(path) An SVG path as a sequence of :class:`SvgItem`. .. py:method:: clone() Return a deep clone of this path. All contained items are cloned as well, and absolute positions are recomputed. .. py:method:: translate(dx, dy) Translate in place. :param dx: Translation in x direction. :param dy: Translation in y direction. .. py:method:: translated(dx, dy) Return a translated copy of this path. :param dx: Translation in x direction. :param dy: Translation in y direction. .. py:method:: scale(kx, ky) Scale in place. :param kx: Scale factor for x coordinates. :param ky: Scale factor for y coordinates. .. py:method:: scaled(kx, ky) Return a scaled copy of this path. :param kx: Scale factor for x coordinates. :param ky: Scale factor for y coordinates. .. py:method:: rotate(ox, oy, degrees) Rotate in place around ``(ox, oy)``. May also normalize horizontal/vertical segments after rotation. :param ox: Rotation origin x coordinate. :param oy: Rotation origin y coordinate. :param degrees: Rotation angle in degrees. .. py:method:: rotated(ox, oy, degrees) Return a rotated copy of this path. See :meth:`rotate` for details. :param ox: Rotation origin x coordinate. :param oy: Rotation origin y coordinate. :param degrees: Rotation angle in degrees. .. py:property:: relative :type: bool Indicate whether all items are stored as relative commands. Mixed paths (some absolute, some relative) return ``False``. .. py:method:: with_relative(new_relative) Return a new path with all items converted to the requested representation. :param new_relative: Target representation (``True`` for relative). .. py:method:: remove(item) Remove the given item. :param item: Item to remove. :raises ValueError: If the item is not present. .. py:method:: insert(index, item) Insert ``item`` before ``index``. :param index: Index before which to insert. :param item: Item to insert. .. py:method:: change_type(index, new_type) Change the command type of the item at ``index`` in place. :param index: The index of the item whose type should be changed. :param new_type: New SVG command letter (e.g. ``"L"`` or ``"c"``). :return: Newly created :class:`SvgItem` replacing the item at ``index``, or ``None`` if ``index`` is not in the path or is the first item. .. py:method:: as_string(decimals = None, minify = False) Serialize the entire path to an SVG path data string. :param decimals: Number of decimal places, or ``None`` for default. :param minify: Use a compact representation. .. py:property:: target_locations :type: list[SvgPoint] Final absolute points for each item in the path. .. py:property:: control_locations :type: list[SvgControlPoint] Flattened list of all absolute control points for the path. .. py:method:: set_location(pt_reference, to) Move the given point to ``to``. The reference must come from a previously queried point list (e.g. :attr:`target_locations` or :attr:`control_locations`). :param pt_reference: Point (target or control) to be moved. :param to: New absolute location for the point. .. py:method:: refresh_absolute_positions() Recompute absolute positions for all items in the path. This should be called after structural or coordinate changes. .. py:method:: __format__(format_spec) Format this path using :meth:`as_string`. The ``format_spec`` can be used to control decimal places and minification, following the same rules as :meth:`SvgItem.__format__`: * ``""`` (empty): use :meth:`as_string` defaults * ``".3"``: ``decimals=3`` * ``"m"``: ``minify=True`` * ``".3m"`` or ``"m.3"``: ``decimals=3``, ``minify=True`` Any other characters are currently ignored. :param format_spec: Format specification string (e.g. ``".3m"``). .. py:method:: __str__() Return :meth:`as_string` with default options.