simetri.graphics.path

  1"""Path module for graphics package."""
  2
  3from dataclasses import dataclass
  4from math import sin, cos, pi
  5from collections import deque
  6from typing_extensions import Self
  7
  8import numpy as np
  9
 10from .core import StyleMixin
 11from .batch import Batch
 12from .shape import Shape
 13from .common import Point, common_properties
 14from ..helpers.validation import validate_args
 15from .all_enums import PathOperation as PathOps
 16from .all_enums import Types
 17from ..canvas.style_map import shape_style_map, ShapeStyle, shape_args
 18from ..geometry.bezier import Bezier
 19from ..geometry.hobby import hobby_shape
 20from ..geometry.geometry import (
 21    homogenize,
 22    positive_angle,
 23    polar_to_cartesian,
 24    sine_points,
 25    close_points2
 26)
 27from ..geometry.ellipse import (
 28    ellipse_point,
 29    ellipse_tangent,
 30    elliptic_arc_points,
 31)
 32from ..geometry.geometry import extended_line, line_angle, line_by_point_angle_length
 33from .affine import translation_matrix, rotation_matrix
 34from ..settings.settings import defaults
 35
 36array = np.array
 37
 38
 39@dataclass
 40class Operation:
 41    """An operation for a Path object.
 42
 43    Attributes:
 44        subtype (Types): The subtype of the operation.
 45        data (tuple): The data associated with the operation.
 46        name (str): The name of the operation.
 47    """
 48
 49    subtype: Types
 50    data: tuple
 51    name: str = ""
 52
 53    def __post_init__(self):
 54        """Post-initialization to set the type and common properties."""
 55        self.type = Types.PATH_OPERATION
 56        common_properties(self, False)
 57
 58
 59class LinPath(Batch, StyleMixin):
 60    """LinerPath.
 61    A LinPath object is a container for various linear elements.
 62    Path objects can be transformed like other Shape and Batch objects.
 63    """
 64
 65    def __init__(self, start: Point = (0, 0), angle: float = pi/2, **kwargs):
 66        """Initialize a Path object.
 67
 68        Args:
 69            start (Point, optional): The starting point of the path. Defaults to (0, 0).
 70            angle (float, optional): The heading angle of the path. Defaults to pi/2.
 71            **kwargs: Additional keyword arguments. Common properties are line_width,
 72            line_color, stroke, etc.
 73        """
 74        if "style" in kwargs:
 75            self.__dict__["style"] = kwargs["style"]
 76            del kwargs["style"]
 77        else:
 78            self.__dict__["style"] = ShapeStyle()
 79        self.__dict__["_style_map"] = shape_style_map
 80        self._set_aliases()
 81        valid_args = shape_args
 82        validate_args(kwargs, valid_args)
 83        self.pos = start
 84        self.start = start
 85        self.angle = angle  # heading angle
 86        self.operations = []
 87        self.objects = []
 88        self.even_odd = True  # False is non-zero winding rule
 89        super().__init__(**kwargs)
 90        self.subtype = Types.LINPATH
 91        self.cur_shape = Shape([start])
 92        self.append(self.cur_shape)
 93        self.rc = self.r_coord  # alias for r_coord
 94        self.rp = self.r_polar  # alias for rel_polar
 95        self.handles = []
 96        self.stack = deque()
 97        for key, value in kwargs.items():
 98            setattr(self, key, value)
 99        common_properties(self)
100        self.closed = False
101
102    def __getattr__(self, name):
103        """Retrieve an attribute of the shape.
104
105        Args:
106            name (str): The attribute name to return.
107
108        Returns:
109            Any: The value of the attribute.
110
111        Raises:
112            AttributeError: If the attribute cannot be found.
113        """
114        try:
115            res = super().__getattr__(name)
116        except AttributeError:
117            res = self.__dict__[name]
118        return res
119
120    def __bool__(self):
121        """Return True if the path has operations.
122        Batch may have no elements yet still be True.
123
124        Returns:
125            bool: True if the path has operations.
126        """
127        return bool(self.operations)
128
129    def _create_object(self):
130        """Create an object using the last operation."""
131        PO = PathOps
132        op = self.operations[-1]
133        op_type = op.subtype
134        data = op.data
135        if op_type in [PO.MOVE_TO, PO.R_MOVE]:
136            self.cur_shape = Shape([data])
137            self.append(self.cur_shape)
138            self.objects.append(None)
139        elif op_type in [PO.LINE_TO, PO.R_LINE, PO.H_LINE, PO.V_LINE, PO.FORWARD]:
140            self.objects.append(Shape(data))
141            self.cur_shape.append(data[1])
142        elif op_type in [PO.SEGMENTS]:
143            self.objects.append(Shape(data[1]))
144            self.cur_shape.extend(data[1])
145        elif op_type in [PO.SINE, PO.BLEND_SINE]:
146            self.objects.append(Shape(data[0]))
147            self.cur_shape.extend(data[0])
148        elif op_type in [PO.CUBIC_TO, PO.QUAD_TO]:
149            n_points = defaults["n_bezier_points"]
150            curve = Bezier(data, n_points=n_points)
151            self.objects.append(curve)
152            self.cur_shape.extend(curve.vertices[1:])
153            if op_type == PO.CUBIC_TO:
154                self.handles.extend([(data[0], data[1]), (data[2], data[3])])
155            else:
156                self.handles.append((data[0], data[1]))
157                self.handles.append((data[1], data[2]))
158        elif op_type in [PO.HOBBY_TO]:
159            n_points = defaults['n_hobby_points']
160            curve = hobby_shape(data[1], n_points=n_points)
161            self.objects.append(Shape(curve.vertices))
162        elif op_type in [PO.ARC, PO.BLEND_ARC]:
163            self.objects.append(Shape(data[-1]))
164            self.cur_shape.extend(data[-1][1:])
165        elif op_type in [PO.CLOSE]:
166            self.cur_shape.closed = True
167            self.cur_shape = Shape([self.pos])
168            self.objects.append(None)
169            self.append(self.cur_shape)
170        else:
171            raise ValueError(f"Invalid operation type: {op_type}")
172
173    def copy(self) -> "LinPath":
174        """Return a copy of the path.
175
176        Returns:
177            LinPath: The copied path object.
178        """
179
180        new_path = LinPath(start=self.start)
181        new_path.pos = self.pos
182        new_path.angle = self.angle
183        new_path.operations = self.operations.copy()
184        new_path.objects = []
185        for obj in self.objects:
186            if obj is not None:
187                new_path.objects.append(obj.copy())
188        new_path.even_odd = self.even_odd
189        new_path.cur_shape = self.cur_shape.copy()
190        new_path.handles = self.handles.copy()
191        new_path.stack = deque(self.stack)
192        for attrib in shape_style_map:
193            setattr(new_path, attrib, getattr(self, attrib))
194
195        return new_path
196
197    def _add(self, pos, op, data, pnt2=None, **kwargs):
198        """Add an operation to the path.
199
200        Args:
201            pos (Point): The position of the operation.
202            op (PathOps): The operation type.
203            data (tuple): The data for the operation.
204            pnt2 (Point, optional): An optional second point for the operation. Defaults to None.
205            **kwargs: Additional keyword arguments.
206        """
207        self.operations.append(Operation(op, data))
208        if op in [PathOps.ARC, PathOps.BLEND_ARC, PathOps.SINE, PathOps.BLEND_SINE]:
209            self.angle = data[1]
210        else:
211            if pnt2 is not None:
212                self.angle = line_angle(pnt2, pos)
213            else:
214                self.angle = line_angle(self.pos, pos)
215        self._create_object()
216        if "name" in kwargs:
217            setattr(self, kwargs["name"], self.operations[-1])
218        list(pos)[:2]
219        self.pos = pos
220
221    def push(self):
222        """Push the current position onto the stack."""
223        self.stack.append((self.pos, self.angle))
224
225    def pop(self):
226        """Pop the last position from the stack."""
227        if self.stack:
228            self.pos, self.angle = self.stack.pop()
229
230    def r_coord(self, dx: float, dy: float) -> Point:
231        """Return the relative coordinates of a point in a
232        coordinate system with the path's midpoint and y-axis aligned
233        with the path.angle.
234
235        Args:
236            dx (float): The x offset.
237            dy (float): The y offset.
238
239        Returns:
240            tuple: The relative coordinates.
241        """
242        x, y = self.pos[:2]
243        theta = self.angle - pi / 2
244        x1 = dx * cos(theta) - dy * sin(theta) + x
245        y1 = dx * sin(theta) + dy * cos(theta) + y
246
247        return x1, y1
248
249    def r_polar(self, r: float, angle: float) -> Point:
250        """Return the relative coordinates of a point in a polar
251        coordinate system with the path's midpoint and 0 degree axis aligned
252        with the path.angle.
253
254        Args:
255            r (float): The radius.
256            angle (float): The angle in radians.
257
258        Returns:
259            tuple: The relative coordinates.
260        """
261        x, y = polar_to_cartesian(r, angle + self.angle - pi / 2)[:2]
262        x1, y1 = self.pos[:2]
263
264        return x1 + x, y1 + y
265
266    def line_to(self, point: Point, **kwargs) -> Self:
267        """Add a line to the path.
268
269        Args:
270            point (Point): The end point of the line.
271            **kwargs: Additional keyword arguments.
272
273        Returns:
274            Path: The path object.
275        """
276        self._add(point, PathOps.LINE_TO, (self.pos, point))
277
278        return self
279
280    def forward(self, length: float, **kwargs) -> Self:
281        """Extend the path by the given length.
282
283        Args:
284            length (float): The length to extend.
285            **kwargs: Additional keyword arguments.
286
287        Returns:
288            Path: The path object.
289
290        Raises:
291            ValueError: If the path angle is not set.
292        """
293        if self.angle is None:
294            raise ValueError("Path angle is not set.")
295        else:
296            x, y = line_by_point_angle_length(self.pos, self.angle, length)[1][:2]
297        self._add((x, y), PathOps.FORWARD, (self.pos, (x, y)))
298
299        return self
300
301    def move_to(self, point: Point, **kwargs) -> Self:
302        """Move the path to a new point.
303
304        Args:
305            point (Point): The new point.
306            **kwargs: Additional keyword arguments.
307
308        Returns:
309            Path: The path object.
310        """
311        self._add(point, PathOps.MOVE_TO, point)
312
313        return self
314
315    def r_line(self, dx: float, dy: float, **kwargs) -> Self:
316        """Add a relative line to the path.
317
318        Args:
319            dx (float): The x offset.
320            dy (float): The y offset.
321            **kwargs: Additional keyword arguments.
322
323        Returns:
324            Path: The path object.
325        """
326        point = self.pos[0] + dx, self.pos[1] + dy
327        self._add(point, PathOps.R_LINE, (self.pos, point))
328
329        return self
330
331    def r_move(self, dx: float = 0, dy: float = 0, **kwargs) -> Self:
332        """Move the path to a new relative point.
333
334        Args:
335            dx (float): The x offset.
336            dy (float): The y offset.
337            **kwargs: Additional keyword arguments.
338
339        Returns:
340            Path: The path object.
341        """
342        x, y = self.pos[:2]
343        point = (x + dx, y + dy)
344        self._add(point, PathOps.R_MOVE, point)
345        return self
346
347    def h_line(self, length: float, **kwargs) -> Self:
348        """Add a horizontal line to the path.
349
350        Args:
351            length (float): The length of the line.
352            **kwargs: Additional keyword arguments.
353
354        Returns:
355            Path: The path object.
356        """
357        x, y = self.pos[0] + length, self.pos[1]
358        self._add((x, y), PathOps.H_LINE, (self.pos, (x, y)))
359        return self
360
361    def v_line(self, length: float, **kwargs) -> Self:
362        """Add a vertical line to the path.
363
364        Args:
365            length (float): The length of the line.
366            **kwargs: Additional keyword arguments.
367
368        Returns:
369            Path: The path object.
370        """
371        x, y = self.pos[0], self.pos[1] + length
372        self._add((x, y), PathOps.V_LINE, (self.pos, (x, y)))
373        return self
374
375    def segments(self, points, **kwargs) -> Self:
376        """Add a series of line segments to the path.
377
378        Args:
379            points (list): The points of the segments.
380            **kwargs: Additional keyword arguments.
381
382        Returns:
383            Path: The path object.
384        """
385
386        self._add(points[-1], PathOps.SEGMENTS, (self.pos, points), pnt2=points[-2], **kwargs)
387        return self
388
389    def cubic_to(self, control1: Point, control2: Point, end: Point, *args, **kwargs) -> Self:
390        """Add a Bézier curve with two control points to the path. Multiple blended curves can be added
391        by providing additional arguments.
392
393        Args:
394            control1 (Point): The first control point.
395            control2 (Point): The second control point.
396            end (Point): The end point of the curve.
397            *args: Additional arguments for blended curves.
398            **kwargs: Additional keyword arguments.
399
400        Returns:
401            Path: The path object.
402        """
403        self._add(
404            end,
405            PathOps.CUBIC_TO,
406            (self.pos, control1, control2, end),
407            pnt2=control2,
408            **kwargs,
409        )
410        return self
411
412    def hobby_to(self, points, **kwargs) -> Self:
413        """Add a Hobby curve to the path.
414
415        Args:
416            points (list): The points of the Hobby curve.
417            **kwargs: Additional keyword arguments.
418
419        Returns:
420            Path: The path object.
421        """
422        self._add(points[-1], PathOps.HOBBY_TO, (self.pos, points))
423        return self
424
425
426    def quad_to(self, control: Point, end: Point, *args, **kwargs) -> Self:
427        """Add a quadratic Bézier curve to the path. Multiple blended curves can be added by providing
428        additional arguments.
429
430        Args:
431            control (Point): The control point.
432            end (Point): The end point of the curve.
433            *args: Additional arguments for blended curves.
434            **kwargs: Additional keyword arguments.
435
436        Returns:
437            Path: The path object.
438
439        Raises:
440            ValueError: If an argument does not have exactly two elements.
441        """
442        self._add(
443            end, PathOps.QUAD_TO, (self.pos[:2], control, end[:2]), pnt2=control, **kwargs
444        )
445        pos = end
446        for arg in args:
447            if len(arg) != 2:
448                raise ValueError("Invalid number of arguments for curve.")
449            if isinstance(arg[0], (int, float)):
450                # (length, end)
451                length = arg[0]
452                control = extended_line(length, control, pos)
453                end = arg[1]
454                self._add(end, PathOps.QUAD_TO, (pos, control, end), pnt2=control)
455                pos = end
456            elif isinstance(arg[0], (list, tuple)):
457                # (control, end)
458                control = arg[0]
459                end = arg[1]
460                self._add(end, PathOps.QUAD_TO, (pos, control, end), pnt2=control)
461                pos = end
462        return self
463
464    def blend_cubic(self, control1_length, control2: Point, end: Point, **kwargs) -> Self:
465        """Add a cubic Bézier curve to the path where the first control point is computed based on a length.
466
467        Args:
468            control1_length (float): The length to the first control point.
469            control2 (Point): The second control point.
470            end (Point): The end point of the curve.
471            **kwargs: Additional keyword arguments.
472
473        Returns:
474            Path: The path object.
475        """
476        c1 = line_by_point_angle_length(self.pos, self.angle, control1_length)[1]
477        self._add(
478            end,
479            PathOps.CUBIC_TO,
480            (self.pos, c1, control2, end),
481            pnt2=control2,
482            **kwargs,
483        )
484        return self
485
486    def blend_quad(self, control_length, end: Point, **kwargs) -> Self:
487        """Add a quadratic Bézier curve to the path where the control point is computed based on a length.
488
489        Args:
490            control_length (float): The length to the control point.
491            end (Point): The end point of the curve.
492            **kwargs: Additional keyword arguments.
493
494        Returns:
495            Path: The path object.
496        """
497        pos = list(self.pos[:2])
498        c1 = line_by_point_angle_length(pos, self.angle, control_length)[1]
499        self._add(end, PathOps.QUAD_TO, (pos, c1, end), pnt2=c1, **kwargs)
500        return self
501
502    def arc(
503        self,
504        radius_x: float,
505        radius_y: float,
506        start_angle: float,
507        span_angle: float,
508        rot_angle: float = 0,
509        n_points=None,
510        **kwargs,
511    ) -> Self:
512        """Add an arc to the path. The arc is defined by an ellipse (with rx as half-width and ry as half-height).
513        The sign of the span angle determines the drawing direction.
514
515        Args:
516            radius_x (float): The x radius of the arc.
517            radius_y (float): The y radius of the arc.
518            start_angle (float): The starting angle of the arc.
519            span_angle (float): The span angle of the arc.
520            rot_angle (float, optional): The rotation angle of the arc. Defaults to 0.
521            n_points (int, optional): The number of points to use for the arc. Defaults to None.
522            **kwargs: Additional keyword arguments.
523
524        Returns:
525            Path: The path object.
526        """
527        rx = radius_x
528        ry = radius_y
529        start_angle = positive_angle(start_angle)
530        clockwise = span_angle < 0
531        if n_points is None:
532            n_points = defaults["n_arc_points"]
533        points = elliptic_arc_points((0, 0), rx, ry, start_angle, span_angle, n_points)
534        start = points[0]
535        end = points[-1]
536        # Translate the start to the current position and rotate by the rotation angle.
537        dx = self.pos[0] - start[0]
538        dy = self.pos[1] - start[1]
539        rotocenter = start
540        if rot_angle != 0:
541            points = (
542                homogenize(points)
543                @ rotation_matrix(rot_angle, rotocenter)
544                @ translation_matrix(dx, dy)
545            )
546        else:
547            points = homogenize(points) @ translation_matrix(dx, dy)
548        tangent_angle = ellipse_tangent(rx, ry, *end) + rot_angle
549        if clockwise:
550            tangent_angle += pi
551        pos = points[-1]
552        self._add(
553            pos,
554            PathOps.ARC,
555            (pos, tangent_angle, rx, ry, start_angle, span_angle, rot_angle, points),
556        )
557        return self
558
559    def blend_arc(
560        self,
561        radius_x: float,
562        radius_y: float,
563        start_angle: float,
564        span_angle: float,
565        sharp=False,
566        n_points=None,
567        **kwargs,
568    ) -> Self:
569        """Add a blended elliptic arc to the path.
570
571        Args:
572            radius_x (float): The x radius of the arc.
573            radius_y (float): The y radius of the arc.
574            start_angle (float): The starting angle of the arc.
575            span_angle (float): The span angle of the arc.
576            sharp (bool, optional): Whether the arc is sharp. Defaults to False.
577            n_points (int, optional): The number of points to use for the arc. Defaults to None.
578            **kwargs: Additional keyword arguments.
579
580        Returns:
581            Path: The path object.
582        """
583        rx = radius_x
584        ry = radius_y
585        start_angle = positive_angle(start_angle)
586        clockwise = span_angle < 0
587        if n_points is None:
588            n_points = defaults["n_arc_points"]
589        points = elliptic_arc_points((0, 0), rx, ry, start_angle, span_angle, n_points)
590        start = points[0]
591        end = points[-1]
592        # Translate the start to the current position and rotate by the computed rotation angle.
593        dx = self.pos[0] - start[0]
594        dy = self.pos[1] - start[1]
595        rotocenter = start
596        tangent = ellipse_tangent(rx, ry, *start)
597        rot_angle = self.angle - tangent
598        if clockwise:
599            rot_angle += pi
600        if sharp:
601            rot_angle += pi
602        points = (
603            homogenize(points)
604            @ rotation_matrix(rot_angle, rotocenter)
605            @ translation_matrix(dx, dy)
606        )
607        tangent_angle = ellipse_tangent(rx, ry, *end) + rot_angle
608        if clockwise:
609            tangent_angle += pi
610        pos = points[-1][:2]
611        self._add(
612            pos,
613            PathOps.ARC,
614            (pos, tangent_angle, rx, ry, start_angle, span_angle, rot_angle, points),
615        )
616        return self
617
618    def sine(
619        self,
620        period: float = 40,
621        amplitude: float = 20,
622        duration: float = 40,
623        phase_angle: float = 0,
624        rot_angle: float = 0,
625        damping: float = 0,
626        n_points: int = 100,
627        **kwargs,
628    ) -> Self:
629        """Add a sine wave to the path.
630
631        Args:
632            period (float, optional): _description_. Defaults to 40.
633            amplitude (float, optional): _description_. Defaults to 20.
634            duration (float, optional): _description_. Defaults to 1.
635            n_points (int, optional): _description_. Defaults to 100.
636            phase_angle (float, optional): _description_. Defaults to 0.
637            damping (float, optional): _description_. Defaults to 0.
638            rot_angle (float, optional): _description_. Defaults to 0.
639
640        Returns:
641            Path: The path object.
642        """
643
644        points = sine_points(
645            period, amplitude, duration, n_points, phase_angle, damping
646        )
647        if rot_angle != 0:
648            points = homogenize(points) @ rotation_matrix(rot_angle, points[0])
649        points = homogenize(points) @ translation_matrix(*self.pos[:2])
650        angle = line_angle(points[-2], points[-1])
651        self._add(points[-1], PathOps.SINE, (points, angle))
652        return self
653
654    def blend_sine(
655        self,
656        period: float = 40,
657        amplitude: float = 20,
658        duration: float = 40,
659        phase_angle: float = 0,
660        damping: float = 0,
661        n_points: int = 100,
662        **kwargs,
663    ) -> Self:
664        """Add a blended sine wave to the path.
665
666        Args:
667            amplitude (float): The amplitude of the wave.
668            frequency (float): The frequency of the wave.
669            length (float): The length of the wave.
670            **kwargs: Additional keyword arguments.
671
672        Returns:
673            Path: The path object.
674        """
675
676        points = sine_points(
677            period, amplitude, duration, n_points, phase_angle, damping
678        )
679        start_angle = line_angle(points[0], points[1])
680        rot_angle = self.angle - start_angle
681        points = homogenize(points) @ rotation_matrix(rot_angle, points[0])
682        points = homogenize(points) @ translation_matrix(*self.pos[:2])
683        angle = line_angle(points[-2], points[-1])
684        self._add(points[-1], PathOps.SINE, (points, angle))
685        return self
686
687    def close(self, **kwargs) -> Self:
688        """Close the path.
689
690        Args:
691            **kwargs: Additional keyword arguments.
692
693        Returns:
694            Path: The path object.
695        """
696        self._add(self.pos, PathOps.CLOSE, None, **kwargs)
697        return self
698
699    @property
700    def vertices(self):
701        """Return the vertices of the path.
702
703        Returns:
704            list: The vertices of the path.
705        """
706        vertices = []
707        last_vert = None
708        dist_tol2 = defaults["dist_tol"] ** 2
709        for obj in self.objects:
710            if obj is not None and obj.vertices:
711                obj_verts = obj.vertices
712                if last_vert:
713                    if close_points2(last_vert,  obj_verts[0], dist_tol2):
714                        vertices.extend(obj_verts[1:])
715                    else:
716                        vertices.extend(obj_verts)
717                else:
718                    vertices.extend(obj_verts)
719                last_vert = obj_verts[-1]
720
721        return vertices
722
723    def set_style(self, name, value, **kwargs) -> Self:
724        """Set the style of the path.
725
726        Args:
727            name (str): The name of the style.
728            value (Any): The value of the style.
729            **kwargs: Additional keyword arguments.
730
731        Returns:
732            Path: The path object.
733        """
734        self.operations.append((PathOps.STYLE, (name, value, kwargs)))
735        return self
736
737    def _update(self, xform_matrix: array, reps: int = 0) -> Batch:
738        """Used internally. Update the shape with a transformation matrix.
739
740        Args:
741            xform_matrix (array): The transformation matrix.
742            reps (int, optional): The number of repetitions, defaults to 0.
743
744        Returns:
745            Batch: The updated shape or a batch of shapes.
746        """
747        if reps == 0:
748            for obj in self.objects:
749                if obj is not None:
750                    obj._update(xform_matrix)
751            res = self
752        else:
753            paths = [self]
754            path = self
755            for _ in range(reps):
756                path = path.copy()
757                path._update(xform_matrix)
758                paths.append(path)
759            res = Batch(paths)
760
761        return res