svg_path_editor =============== .. py:module:: svg_path_editor Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/svg_path_editor/path_change_origin/index /autoapi/svg_path_editor/path_operations/index /autoapi/svg_path_editor/path_parser/index /autoapi/svg_path_editor/sub_path_bounds/index /autoapi/svg_path_editor/svg/index Classes ------- .. autoapisummary:: svg_path_editor.Point svg_path_editor.SvgItem svg_path_editor.SvgPath Functions --------- .. autoapisummary:: svg_path_editor.change_path_origin svg_path_editor.optimize_path svg_path_editor.reverse_path Package Contents ---------------- .. py:function:: 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. :param svg: Original path to transform. :param new_origin_index: Index of the command that should become the new origin within its subpath. :param subpath: 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 :class:`~svg_path_editor.SvgPath` instance with the origin moved and the path representation optimized. .. py:function:: 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. :param svg: Input path. :param remove_useless_commands: Remove redundant ``M``/``Z`` commands and degenerate ``L``/``H``/``V`` segments. :param remove_orphan_dots: Remove empty closed subpaths (``M`` immediately followed by ``Z``). :param use_shorthands: Convert eligible ``C``/``Q`` segments to ``S``/``T`` where possible. :param use_horizontal_and_vertical_lines: Replace ``L`` with ``H`` or ``V`` where possible. :param use_relative_absolute: Choose between relative and absolute commands per segment to minimize size. :param use_reverse: Reverse the path direction if that yields a shorter minified representation. This can affect stroked paths. :param use_close_path: Convert final line segments that return to start into ``Z``. This can affect stroked paths. :returns: A new, possibly shorter, but geometrically equivalent path. .. py:function:: reverse_path(svg, subpath_of_item = None) Reverse the drawing direction of a path or sub-path. :param svg: Input path. :param subpath_of_item: 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. .. py:class:: Point(x, y) Simple 2D point. .. py:attribute:: x :type: decimal.Decimal .. py:attribute:: y :type: decimal.Decimal .. 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: 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:method:: target_location() 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:: SvgPath(path) An SVG path as a sequence of :class:`SvgItem`. .. py:attribute:: path :type: list[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.