virtual_knitting_machine.visualizer.visualizer_elements.path_elements module

A module containing SVG Path elements and subclasses for different path types.

class Path_Type(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enumeration of common allowed path types. The value of the enumeration is equal to the expected number of control points for the path type.

Line = 0

Quadratic = 1

Cubic = 2

classmethod __contains__(member)

Return True if member is a member of this enum raises TypeError if member is not an enum member

note: in 3.12 TypeError will no longer be raised, and True will also be returned if member is the value of a member in this enum

classmethod __getitem__(name)

Return the member matching name.

classmethod __iter__()

Return members in definition order.

classmethod __len__()

Return the number of members (no aliases)

class Path_Element(start_x, start_y, end_x, end_y, name, stroke, stroke_width, control_points=None, path_type=Path_Type.Line, **element_kwargs)

Bases: Visualizer_Element

Wrapper class for Path SVG elements, particularly useful for creating curves and splines.

_path_type

Type of path to form with this path element.

Type:

Path_Type

control_points

List of control points for this path element.

Type:

list[ControlPoint]

stroke

The color of the path line.

Type:

str

__init__(start_x, start_y, end_x, end_y, name, stroke, stroke_width, control_points=None, path_type=Path_Type.Line, **element_kwargs)

Initialize the Path SVG element.

Parameters:

• start_x (float) – The x coordinate of the path’s starting point relative to its parent.

• start_y (float) – The y coordinate of the path’s starting point relative to its parent.

• end_x (float) – The x coordinate of the path’s ending point relative to its parent.

• end_y (float) – The y coordinate of the path’s ending point relative to its parent.

• name (str) – The name of the path element used as the element id.

• stroke (str) – The name of the stroke color used for this path.

• stroke_width (int) – The width of the path line.

• control_points (list[tuple[float, float]], optional) – The control points of the path. Defaults to an empty list to form lines.

• path_type (Path_Type) – The type of path element this SVG element represents. This should match the provided number of control points.

• darken_stroke (bool, optional) – If True, the stroke color is automatically darkened (as in a fill color for loops on a yarn). Defaults to True.

• **element_kwargs (Any) – Keyword arguments to configure the Path SVG element. Usually includes “stroke_width”.

property path_data: str

Returns: str: The SVG path data string to form the path’s specific curve.

property start_x: float

Returns: float: The x coordinate of the path’s starting point relative to its parent.

property start_y: float

Returns: float: The y coordinate of the path’s starting point relative to its parent.

property end_x: float

Returns: float: The end x coordinate of the path.

property end_y: float

Returns: float: The end y coordinate of the path.

property x_dist: float

Returns: float: The distance between the x coordinates at the start and end of the path.

property y_dist: float

Returns: float: The distance between the y coordinates at the start and end of the path.

property mid_x: float

Returns: float: The midpoint between the x coordinates at the start and end of the path.

property mid_y: float

Returns: float: The midpoint between the y coordinates at the start and end of the path.

control_x(cp_index=1)

Parameters:

cp_index (int, optional) – Index of the control point. Defaults to first control point.

Returns:

The x coordinate of the specified control point.

Return type:

float

control_y(cp_index=1)

Parameters:

cp_index (int, optional) – Index of the control point. Defaults to first control point.

Returns:

The y coordinate of the specified control point.

Return type:

float

property line_path_data: str

Create a straight line path.

Visual appearance: A direct straight line from start to end point.

Use cases: - Connecting loops on the same needle bed (vertical connections). - Drawing grid lines or reference marks. - Simple direct connections where curves are not needed. - Representing tight yarn segments with no slack.

Returns:

The Path data string used to create a straight line path.

Return type:

str

property quadratic_bezier_path_data: str

Create a quadratic Bézier curve with one control point.

Visual appearance:

A smooth parabolic curve that bends toward the control point. The curve is always tangent to the line from start to control and from control to end. Creates a single, symmetric arc.

Use cases: * Simple yarn floats between adjacent needles (gentle arc) * Connecting parent and child loops in stitch diagrams * Tuck operations where yarn curves around a needle * Any connection requiring a single smooth bend * When you want a simpler, more predictable curve than cubic Bezier

Default behavior:

If control point not specified, places it at the midpoint between start and end, offset perpendicular to create a gentle arc.

Returns:

SVG path data string for the quadratic Bézier curve.

Return type:

str

property cubic_bezier_path_data: str

Create a cubic Bézier curve with two control points.

Visual appearance:

A smooth S-curve or complex curve that can change direction. The curve starts tangent to the line from start to control1 and ends tangent to the line from control2 to end. Can create S-shapes, loops, and complex paths.

Use cases: * Long yarn floats across multiple needles (creates natural drape). * Yarn paths that need to avoid obstacles (can curve around other elements). * Connecting loops on opposite beds with graceful curves. * Split operations where yarn paths diverge smoothly. * Transfer operations showing yarn movement across beds. * Any complex path requiring more control than quadratic Bezier.

This is the most flexible curve type, allowing for sophisticated yarn representations.

Returns:

SVG path data string for the cubic Bézier curve.

Return type:

str

set_cubic_downward_curve(peak_of_curve)

Sets the path type to a downward facing arc set at the midpoint between the start and end position and peaking above the highest end point.

Parameters:

peak_of_curve (float) – The amount for the arc to peak above the highest end point.

set_cubic_upward_curve(peak_of_curve)

Sets the path type to an up facing arc set at the midpoint between the start and end position and peaking below the lowest end point.

Parameters:

peak_of_curve (int) – The amount for the arc to peak below the lowest end point.

set_cubic_crossing_curve()

Sets the path type to form a cube curve between the two points at diagonal positions from each other.

add_to_drawing(drawing)

Adds this element to the given svg drawing. :param drawing: The drawing to add. :type drawing: Drawing

static darken_color(color='none', factor=0.7)

Darken a hex or named color.

Parameters:

• color (str) – The color to darken. Either a named color or a hex representation of the color.

• factor (float, optional) –

  A factor to darken. Defaults to 0.7.

  • 0.0 = No change.

  • 1.0 = black.

Returns:

The color-string of the darkened color. If “none” color is given, this will return “black”.

Return type:

str

static fill_from_stroke(stroke, lighten_factor=0.3)

Parameters:

• stroke (str) – The color string of the stroke to be lightened for infill.

• lighten_factor (float, optional) – The factor to lighten the stroke color by. Defaults to 0.3.

Returns:

The fill color string created by lightening the stroke color.

Return type:

str

property global_x: float

Returns: float: The global x coordinate of this element based on its parent’s coordinates.

global_x_position(x)

Parameters:

x (float) – An X-coordinate position relative to this element’s coordinate system.

Returns:

The x-coordinate adjusted to the global coordinate system.

Return type:

float

property global_y: float

Returns: float: The global y coordinate of this element based on its parent’s coordinates.

global_y_position(y)

Parameters:

y (float) – An Y-coordinate position relative to this element’s coordinate system.

Returns:

The y-coordinate adjusted to the global coordinate system.

Return type:

float

static lighten_color(color='none', factor=0.3)

Lighten a hex or named color.

Parameters:

• color (str, optional) – The color to lighten. Either a named color or a hex representation of the color. Defaults to transparent (“none”).

• factor (float, optional) –

  A factor to lighten (0.0 to 1.0). Defaults to 0.3.

  • 0.0 = no change.

  • 1.0 = white.

Returns:

The color-string of the lightened color. If “none” color is given, this will return “black”.

Return type:

str

property name: str

Returns: str: The unique name of this element. This will match the id of the svg element being wrapped.

static stroke_from_fill(fill, darken_factor=0.7)

Parameters:

• fill (str) – The color string of the fill to be darkened for an outline.

• darken_factor (float, optional) – The factor to darken the fill color by. Defaults to 0.7.

Returns:

The stroke color string created by darkening the fill color.

Return type:

str

property x: float

Returns: float: The x coordinate of this element relative to its parent (or globally).

property y: float

Returns: float: The y coordinate of this element relative to its parent (or globally).