spyrograph.epitrochoid.epitrochoid module

Model of an epitrochoid. An epitrochoid is a geometric shape drawn from a line attached to a circle rolling around the exterior of a fixed circle

class Epitrochoid(R: Number, r: Number, d: Number, thetas: List[Number] | None = None, theta_start: Number | None = None, theta_stop: Number | None = None, theta_step: Number | None = None, origin: Tuple[Number, Number] = (0, 0), orientation: Number = 0, noise: List[array] | None = None)

Bases: _Trochoid

Model of an epitrochoid, which is a geometric shape drawn by a line attached to a circle as it rolls around the exterior of a fixed circle.

The Epitrochoid class provides methods for calculating the x- and y-values of the epitrochoid at a given theta value using parametrized equations. The class takes in parameters such as the radius of the fixed circle, the radius of the rolling circle, and the distance between their centers, which affect the shape of the curve.

The Epitrochoid class is a useful tool for exploring the properties and behaviors of epitrochoids, and can be used in a variety of applications such as in mechanical engineering and mathematics education. If you need to work with epitrochoids for a project or research, the Epitrochoid class provides a simple and intuitive interface to generate these curves and explore their properties.

__init__(R: Number, r: Number, d: Number, thetas: List[Number] | None = None, theta_start: Number | None = None, theta_stop: Number | None = None, theta_step: Number | None = None, origin: Tuple[Number, Number] = (0, 0), orientation: Number = 0, noise: List[array] | None = None) → None

Model of a trochoid curve from given input parameters. A trochoid is a curve drawn by tracing a point from a circle as it rolls around the inside or outside of a fixed circle

Parameters:

R (Number) – Radius of the fixed circle
r (number) – Radius of the rolling circle
d (Number) – Distance of the trace point from the rolling circle
thetas (List[Number] = None) – Input list of values for theta for inputting into parametric equations. This argument cannot be set at the same time as theta_start, theta_stop, theta_step
theta_start (Number = None) – Starting theta value for creating a list of thetas (similar syntax to built-in range or np.arange). This argument cannot be set at the same time as thetas argument
theta_stop (Number = None) – Stop theta value for creating a list of thetas, stop value is not included in the final array (similar syntax to built-in range or np.arange). This argument cannot be set at the same time as thetas argument
theta_step (Number = None) – Incremental step value for stepping from start to stop (similar syntax to built-in range or np.arange). This argument cannot be set at the same time as thetas argument
origin (Tuple[Number, Number] = (0, 0)) – Custom origin to center the shapes at. Default is (0,0)
orientation (Number = 0) – Angle of rotation for the shape

add_noise(x_scale: Number = 0, y_scale: Number = 0) → _Trochoid | _Cycloid

classmethod animate(R: Number | List[Number], r: Number | List[Number], d: Number | List[Number], thetas: List[Number] | None = None, theta_start: Number | None = None, theta_stop: Number | None = None, theta_step: Number | None = None, origin: Tuple[Number, Number] = (0, 0), screen_size: Tuple[Number, Number] | None = None, screen_color: str = 'white', exit_on_click: bool = False, color: str = 'black', width: Number = 1, frame_pause: Number = 0.1, screen: Screen | None = None, screen_coords=(0, 0), padding: Number = 100, repeat: bool = False, reverse: bool = False, boomerang: bool = False) → List[_Trochoid]

Animate a sequence of _Trochoid shapes with varying input parameters, drawn one after the other.

Parameters:

R (Union[Number, List[Number]]) – Radius of the fixed circle.
r (Union[Number, List[Number]]) – Radius of the rolling circle.
d (Union[Number, List[Number]]) – Distance of the trace point from the rolling circle.
thetas (List[Number], optional) – Input list of values for theta for inputting into parametric equations. This argument cannot be set at the same time as theta_start, theta_stop, theta_step.
theta_start (Number, optional) – Starting theta value for creating a list of thetas (similar syntax to built-in range or np.arange). This argument cannot be set at the same time as thetas argument.
theta_stop (Number, optional) – Stop theta value for creating a list of thetas, stop value is not included in the final array (similar syntax to built-in range or np.arange). This argument cannot be set at the same time as thetas argument.
theta_step (Number, optional) – Incremental step value for stepping from start to stop (similar syntax to built-in range or np.arange). This argument cannot be set at the same time as thetas argument.
origin (Tuple[Number, Number], optional, default (0, 0)) – Custom origin to center the shapes at. Default is (0,0).
screen_size (Tuple[Number, Number], optional, default None) – Length and width of the output screen. Default behavior builds screen just large enough to fit the shape and any extra padding deined by the padding argument
screen_color (str, optional, default "white") – Color of the background screen.
exit_on_click (bool, optional, default False) – Pause the final animation until the user clicks to exit the window.
color (str, optional, default "black") – Color of the primary tracing.
width (Number, optional, default 1) – Width of the turtle tracing.
frame_pause (Number, optional, default 0.1) – Time in seconds to pause between each shape in the animation.
screen (turtle.Screen, optional) – Existing turtle screen.
padding (Number) – Padding on the outside of the image
repeat (bool, optional) – If True, infinitely repeat the animation so it starts over from the beginning, default is False.
reverse (bool, optional, default False) – If True, run the animation from the end to the beginning, default is False
boomerang (bool, optional, default False) – If True, repeat the animation at the end in reverse, default is False

Returns:

shapes – A list of instantiated _Trochoid shapes with varying input parameters.

Return type:

List[_Trochoid]

Examples

>>> from spyrograph import Hypotrochoid
>>> import numpy as np
>>> thetas = np.linspace(0, 2 * np.pi, num=1000)
>>> shapes = Hypotrochoid.animate(R=10, r=[4, 5, 6], d=8, thetas=thetas)

Return a list of instantiated shapes where one of the input parameters (R, r, or d) is a list of increments, and the rest are fixed.

Parameters:

R (Union[Number, List[Number]]) – Radius of the fixed circle.
r (Union[Number, List[Number]]) – Radius of the rolling circle.
d (Union[Number, List[Number]]) – Distance of the trace point from the rolling circle.
thetas (List[Number], optional) – Input list of values for theta for inputting into parametric equations. This argument cannot be set at the same time as theta_start, theta_stop, theta_step.
theta_start (Number, optional) – Starting theta value for creating a list of thetas (similar syntax to built-in range or np.arange). This argument cannot be set at the same time as thetas argument.
theta_stop (Number, optional) – Stop theta value for creating a list of thetas, stop value is not included in the final array (similar syntax to built-in range or np.arange). This argument cannot be set at the same time as thetas argument.
theta_step (Number, optional) – Incremental step value for stepping from start to stop (similar syntax to built-in range or np.arange). This argument cannot be set at the same time as thetas argument.
origin (Tuple[Number, Number], optional, default (0, 0)) – Custom origin to center the shapes at. Default is (0,0).

Returns:

shapes – A list of instantiated _Trochoid shapes with varying input parameters.

Return type:

List[_Trochoid]

Raises:

ValueError – If more than one input variable (R, r, or d) is a list of varying inputs.

Examples

>>> from spyrograph import Hypotrochoid
>>> import numpy as np
>>> thetas = np.linspace(0, 2 * np.pi, num=1000)
>>> shapes = Hypotrochoid.create_range(R=10, r=[4, 5, 6], d=8, thetas=thetas)
>>> len(shapes)
3

property df: DataFrame

Return a pandas DataFrame containing all relevant information pertaining to the parametrized shape.

This property creates a pandas DataFrame with columns for the x and y coordinates, as well as the angular positions (theta) of the parametrized shape.

Raises:: ImportError – If pandas is not installed on the user’s machine.
Returns:: df – A DataFrame with columns ‘x’, ‘y’, and ‘theta’, containing the x and y coordinates and angular positions of the parametrized shape.
Return type:: pd.DataFrame

Examples

>>> from spyrograph import Hypotrochoid
>>> import numpy as np
>>> thetas = np.linspace(0, 2 * np.pi, num=1000)
>>> shape = Hypotrochoid(R=10, r=6, d=8, thetas=thetas)
>>> shape_df = shape.df
>>> shape_df.head()
    x         y     theta
0  12.000  2.000000  0.000000
1  11.998  1.999217  0.006283
2  11.993  1.996869  0.012566
3  11.985  1.993056  0.018849
4  11.974  1.987778  0.025132

is_closed(tolerance: Number = 5) → bool

Return True if the shape is closed (i.e. if it returns to its starting point after a certain number of loops) else False

Parameters:: tolerance (float, optional) – The tolerance to consider the shape as closed, by default 5.
Returns:: True if the shape is closed, False otherwise.
Return type:: bool

plot(**kwargs) → Tuple[matplotlib.matplotlib.Figure, matplotlib.axes._axes.Axes]

Plot the shape and return the associated matplotlib Figure and Axes objects.

This method plots the shape using the x and y attributes of the object, which are defined by the parametric equations from the given input parameters. It returns the Figure and Axes objects of the created plot for further customization if needed.

Parameters:

**kwargs – Keyword arguments passed to the matplotlib.pyplot.plot function. For a full list of available options, refer to: https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.plot.html

Returns:

fig (matplotlib.matplotlib.Figure) – The Figure object associated with the created plot.
ax (matplotlib.axes._axes.Axes) – The Axes object associated with the created plot.

Raises:

ImportError – If matplotlib is not installed on the user’s machine.

Examples

>>> from spyrograph import Hypotrochoid
>>> import numpy as np
>>> shape = Hypotrochoid(R=300, r=200, d=200, thetas=np.arange(0, 2*np.pi, .01))
>>> fig, ax = shape.plot()

rotate(angle: float, degrees: bool = False)

Rotate the shape by the given angle (in radians).

This method creates a new instance of the shape with the updated orientation attribute, keeping the original shape unchanged.

Parameters:

angle (float) – The angle to rotate the shape by, in radians
degrees (bool) – Rotate in degrees

Returns:

rotated_shape – A new instance of the shape with the updated orientation.

Return type:

instance of the shape’s class

Examples

>>> from spyrograph import Hypotrochoid
>>> import numpy as np
>>> shape = Hypotrochoid(R=233, r=200, d=233, thetas=np.arange(0, 100*np.pi, .5))
>>> rotated_shape = shape.rotate(np.pi / 4)  # Rotate the shape by 45 degrees

save_png(fpath: str, screen_size: Tuple[Number, Number] | None = None, screen_color: str = 'white', color: str = 'black', width: Number = 1, screen: Screen | None = None, screen_coords=(0, 0), padding=100) → None

Save the shape as a PNG file.

Parameters:

fpath (str) – The file path where the PNG file will be saved.
screen_size (Tuple[Number, Number], optional) – The width and height of the turtle screen. Default is None.
screen_color (str, optional) – The background color of the turtle screen. Default is “white”.
color (str, optional) – The color of the shape. Default is “black”.
width (Number, optional) – The width of the shape lines. Default is 1.
screen ("turtle.Screen", optional) – The turtle screen object to draw the shape on. Default is None.
screen_coords (Tuple[Number, Number], optional) – The x and y coordinates of the top-left corner of the turtle screen. Default is (0, 0).
padding (int, optional) – The padding around the shape in the final PNG image. Default is 100.

Examples

>>> shape = Trochoid(R=250, r=179, d=233, thetas=np.arange(0, 60, .01))
>>> shape.save_png("spirograph.png", width=2)

scale(factor: Number) → _Trochoid | _Cycloid

Return shape with input parameters scaled by a given input factor.

This method creates a new shape by scaling the input parameters R, r, and d (when applicable) by the given factor. The new shape is an instance of the same class as the original shape.

Parameters:: factor (Number) – The factor by which to scale the input parameters (R, r, and d).
Returns:: A new shape instance with the scaled input parameters.
Return type:: Union[“_Trochoid”, “_Cycloid”]

Examples

>>> hypotrochoid = Hypotrochoid(10, 5, 3, thetas=[0, 1, 2])
>>> scaled_hypotrochoid = hypotrochoid.scale(2)
>>> scaled_hypotrochoid.R
20
>>> scaled_hypotrochoid.r
10
>>> scaled_hypotrochoid.d
6

trace(screen_size: Tuple[Number, Number] | None = None, screen_color: str = 'white', exit_on_click: bool = False, color: str = 'black', width: Number = 1, hide_turtle: bool = True, show_circles: bool = False, frame_pause: Number = 0, screen: Screen | None = None, circle_color: str = 'black', show_full_path: bool = False, full_path_color: str = 'grey', repeat: bool = False, screen_coords=(0, 0), padding: Number = 100) → Screen

Trace the shape using the turtle graphics library and return the turtle.Screen object.

This method visually traces the shape using turtle graphics, allowing for various customization options, such as colors, line width, and frame pause time.

Parameters:

screen_size (Tuple[Number, Number], optional) – The length and width of the output screen, default is (1000, 1000).
screen_color (str, optional) – The color of the background screen, default is “white”.
exit_on_click (bool, optional) – If True, pause the final animation until the user clicks to exit the window, default is False.
color (str, optional) – The color of the primary tracing, default is “black”.
width (Number, optional) – The width of the turtle tracing, default is 1.
hide_turtle (bool, optional) – If True, hide the turtle icon while tracing, default is True.
show_circles (bool, optional) – If True, show the inner and outer circles that compose the trace, default is False.
frame_pause (Number, optional) – The time in seconds to pause each individual frame, default is 0.
screen (turtle.Screen, optional) – An existing turtle screen, default is None.
circle_color (str, optional) – The color of the circles, default is “black”.
show_full_path (bool, optional) – If True, show the full path prior to tracing, default is False.
full_path_color (str, optional) – The color of the full path drawing, default is “grey”.
repeat (bool, optional) – If True, infinitely repeat the animation so it starts over from the beginning, default is False.
screen_coords (Tuple[int, int] = (0, 0)) – Location of the screen coordinates
padding (Number) – Padding on the outside of the image

Returns:

screen – The screen that the turtle is drawn on.

Return type:

turtle.Screen

Examples

>>> from spyrograph import Hypotrochoid
>>> import numpy as np
>>> shape = Hypotrochoid(R=300, r=200, d=200, thetas=np.arange(0, 2*np.pi, .01))
>>> screen = shape.trace(show_circles=True, exit_on_click=True)

translate(x: Number = 0, y: Number = 0) → _Trochoid

Return a new shape translated by the given x and y offsets.

Parameters:

x (Number, optional, default=0) – The x-offset to shift the shape by.
y (Number, optional, default=0) – The y-offset to shift the shape by.

Returns:

A new instance of the shape translated by the given x and y offsets.

Return type:

_Trochoid

Examples

>>> shape = Trochoid(R=5, r=2, d=3, thetas=thetas)
>>> transformed_shape = shape.transform(x=10, y=5)