simetri.extensions.turtle_sg

  1"""Turtle graphics variant, with a twist."""
  2
  3from math import pi, radians
  4from typing import Sequence, List, Tuple, Optional, Any
  5from dataclasses import dataclass
  6
  7from ..graphics.batch import Batch
  8from ..graphics.shape import Shape
  9
 10from ..geometry.geometry import line_by_point_angle_length as get_pos
 11
 12
 13@dataclass
 14class State:
 15    """A state of the turtle.
 16
 17    Attributes:
 18        pos (tuple): The position of the turtle.
 19        angle (float): The angle of the turtle.
 20        pen_is_down (bool): Whether the pen is down.
 21    """
 22
 23    pos: tuple
 24    angle: float
 25    pen_is_down: bool
 26
 27class Turtle(Batch):
 28    """A Turtle graphics variant, with a twist.
 29
 30    This class implements a turtle graphics system that can be used to draw
 31    geometric shapes and patterns.
 32
 33    Args:
 34        *args: Variable length argument list passed to the parent class.
 35        in_degrees (bool, optional): Whether angles are measured in degrees. Defaults to False.
 36        **kwargs: Arbitrary keyword arguments passed to the parent class.
 37    """
 38
 39    def __init__(self, *args: Any, in_degrees: bool = False, **kwargs: Any) -> None:
 40        self.pos = (0, 0)
 41        self.stack = []
 42        self.lists = []
 43        self.current_list = [self.pos]
 44        super().__init__([], *args, **kwargs)
 45        self.pen_is_down = True
 46        self._set_aliasess()
 47        self.in_degrees = in_degrees
 48        if in_degrees:
 49            self.def_angle = 90
 50        else:
 51            self.def_angle = pi / 2
 52        self.def_dist = 20
 53        # start facing north
 54        if in_degrees:
 55            self._angle = 90
 56        else:
 57            self._angle = pi / 2
 58
 59    @property
 60    def angle(self) -> float:
 61        """Return the current angle of the turtle.
 62
 63        The angle is clamped to the appropriate range based on the angle mode.
 64
 65        Returns:
 66            float: The current angle, normalized to 0-360 degrees or 0-2π radians.
 67        """
 68        if self.in_degrees:
 69            res = self._angle % 360
 70        else:
 71            res = self._angle % (2 * pi)
 72
 73        return res
 74
 75    @angle.setter
 76    def angle(self, value: float) -> None:
 77        """Set the angle of the turtle.
 78
 79        Args:
 80            value (float): The new angle value in degrees or radians
 81                based on the turtle's configuration.
 82        """
 83        self._angle = value
 84
 85    def _forward_pos(self, dist: float = None) -> tuple:
 86        """Calculate the position after moving forward by the given distance.
 87
 88        Args:
 89            dist (float, optional): The distance to move. Defaults to self.def_dist.
 90
 91        Returns:
 92            tuple: The new position coordinates.
 93        """
 94        if self.in_degrees:
 95            angle = radians(self._angle)
 96        else:
 97            angle = self._angle
 98
 99        if dist is None:
100            dist = self.def_dist
101
102        return get_pos(self.pos, angle, dist)[1]
103
104    def forward(self, dist: float = None) -> None:
105        """Move the turtle forward by the given distance.
106
107        Moves the turtle and draws a line if the pen is down.
108
109        Args:
110            dist (float, optional): The distance to move forward. Defaults to self.def_dist.
111        """
112        x, y = self._forward_pos(dist)[:2]
113        self.pos = (x, y)
114        if self.pen_is_down:
115            self.current_list.append(self.pos)
116
117    def go(self, dist: float = None) -> None:
118        """Move the turtle forward without drawing.
119
120        Moves the turtle regardless of the pen state, and doesn't draw.
121        Saves the current path and starts a new one.
122
123        Args:
124            dist (float, optional): The distance to move forward. Defaults to self.def_dist.
125        """
126        x, y = self._forward_pos(dist)[:2]
127        self.pos = (x, y)
128        self.lists.append(self.current_list)
129        self.current_list = [self.pos]
130
131    def backward(self, dist: float = None) -> None:
132        """Move the turtle backward by the given distance.
133
134        Args:
135            dist (float, optional): The distance to move backward. Defaults to self.def_dist.
136        """
137        if dist is None:
138            dist = self.def_dist
139        self.forward(-dist)
140
141    def left(self, angle: float = None) -> None:
142        """Turn the turtle left by the given angle.
143
144        Args:
145            angle (float, optional): The angle to turn left. Defaults to self.def_angle.
146        """
147        if angle is None:
148            angle = self.def_angle
149        self._angle += angle
150
151    def right(self, angle: float = None) -> None:
152        """Turn the turtle right by the given angle.
153
154        Args:
155            angle (float, optional): The angle to turn right. Defaults to self.def_angle.
156        """
157        if angle is None:
158            angle = self.def_angle
159        self._angle -= angle
160
161    def turn_around(self) -> None:
162        """Turn the turtle around by 180 degrees.
163
164        Rotates the turtle 180 degrees from its current direction.
165        """
166        if self.in_degrees:
167            self._angle += 180
168        else:
169            self._angle += pi
170
171
172    def pen_up(self) -> None:
173        """Lift the pen.
174
175        Stops drawing and saves the current path when the turtle moves.
176        """
177        self.pen_is_down = False
178        self.lists.append(self.current_list)
179        self.current_list = []
180
181    def pen_down(self) -> None:
182        """Lower the pen.
183
184        Enables drawing when the turtle moves and adds the current position
185        to the current path.
186        """
187        self.pen_is_down = True
188        self.current_list.append(self.pos)
189
190    def move_to(self, pos: tuple) -> None:
191        """Move the turtle to the given position.
192
193        Args:
194            pos (tuple): The target position as (x, y) coordinates.
195        """
196        self.pos = pos
197        if self.pen_is_down:
198            self.current_list.append(self.pos)
199
200
201    def push(self) -> None:
202        """Save the current state of the turtle.
203
204        Stores the current position, angle, and pen state for later retrieval.
205        """
206        state = State(self.pos, self._angle, self.pen_is_down)
207        self.stack.append(state)
208
209    def pop(self) -> None:
210        """Restore the last saved state of the turtle.
211
212        Retrieves the most recently saved state and restores the turtle to it.
213        """
214        state = self.stack.pop()
215        self.pos = state.pos
216        self._angle = state.angle
217        self.pen_is_down = state.pen_is_down
218        self.lists.append(self.current_list)
219        self.current_list = [self.pos]
220
221    def reset(self) -> None:
222        """Reset the turtle to its initial state.
223
224        Appends the current shape to the batch and resets position, angle,
225        and pen state.
226        """
227        self.append(self.current_shape)
228        self.pos = (0, 0)
229        if self.in_degrees:
230            self._angle = 0
231        else:
232            self._angle = pi / 2
233        self.current_list = [self.pos]
234        self.pen_is_down = True
235
236    # aliases
237    def _set_aliasess(self) -> None:
238        """Set up aliases for turtle methods.
239
240        Creates shorthand method names commonly used in turtle graphics.
241        """
242        self.fd = self.forward
243        self.bk = self.backward
244        self.lt = self.left
245        self.rt = self.right
246        self.pu = self.pen_up
247        self.pd = self.pen_down
248        self.goto = self.move_to
249
250
251def add_digits(n: int) -> int:
252    """Return the sum of the digits of n.
253
254    Spirolateral helper function that adds all digits in a number.
255
256    Args:
257        n (int): The number to process.
258
259    Returns:
260        int: The sum of all digits in n.
261
262    Examples:
263        10 -> 1 + 0 -> 1
264        123 -> 1 + 2 + 3 -> 6
265    """
266    return sum((int(x) for x in str(n)))
267
268
269def spirolateral(
270    sequence: Sequence, angle: float, cycles: int = 15, multiplier: float = 50
271) -> Turtle:
272    """Draw a spirolateral with the given sequence and angle.
273
274    Args:
275        sequence (Sequence): Sequence of numbers determining segment lengths.
276        angle (float): Angle in degrees for turns.
277        cycles (int, optional): Number of cycles to draw. Defaults to 15.
278        multiplier (float, optional): Scaling factor for segment lengths. Defaults to 50.
279
280    Returns:
281        Turtle: The turtle object used for drawing.
282    """
283    turtle = Turtle(in_degrees=True)
284    count = 0
285    while count < cycles:
286        for i in sequence:
287            turtle.forward(multiplier * add_digits(i))
288            turtle.right(180 - angle)
289            count += 1
290    return turtle
291
292
293def spiral(turtle: Turtle, side: float, angle: float, delta: float, cycles: int = 15) -> Turtle:
294    """Draw a spiral with the given side, angle, delta, and cycles.
295
296    Args:
297        turtle (Turtle): The turtle object to use for drawing.
298        side (float): Initial length of the side.
299        angle (float): Angle to turn after drawing each side.
300        delta (float): Amount to increase the side length in each step.
301        cycles (int, optional): Number of segments to draw. Defaults to 15.
302
303    Returns:
304        Turtle: The turtle object used for drawing.
305    """
306    t = turtle
307    count = 0
308    while count < cycles:
309        t.forward(side)
310        t.right(angle)
311        side += delta
312        count += 1
313    return t