spyrograph.hypotrochoid.hypocycloid module

Model of a hypocycloid. Specific case of a hypotrochoid where the distance from the rolling circle is equal to the radius of the rolling circle

class Hypocycloid(R: Number, r: 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: Number | None = None)

Bases: _Cycloid, Hypotrochoid

Model of a hypocycloid, which is a mathematical curve traced by a point on a circle as it rolls around the inside of another fixed circle. This class represents a special case of a hypotrochoid, where the distance from the point to the rolling circle is equal to the radius of the rolling circle.

The Hypocycloid class allows you to generate points along the curve using mathematical equations and visualize the curve in a plot. It also provides properties and methods for plotting and animating the curve.

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

__init__(R: Number, r: 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: Number | 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], 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.
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 (1000, 1000)) – Length and width of the output screen.
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 is a list of increments i.e. R, r 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
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)

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

classmethod n_cusps(R: Number, n: int, thetas: List[Number] = None, theta_start: Number = None, theta_stop: Number = None, theta_step: Number = None, origin: Tuple[Number, Number] = (0, 0), orientation: Number = 0) → Cycloid

Create and return a cycloid with a specified number of cusps

Parameters:

R (Number) – Radius of the fixed circle.
n (int) – Number of cusps to create in the cycloid.
thetas (List[Number], optional) – List of theta values for inputting into parametric equations.
theta_start (Number, optional) – Starting theta value for creating a list of thetas (similar syntax to built-in range or np.arange).
theta_stop (Number, optional) – Stop theta value for creating a list of thetas; the stop value is not included in the final array (similar syntax to built-in range or np.arange).
theta_step (Number, optional) – Incremental step value for stepping from start to stop (similar syntax to built-in range or np.arange).
origin (Tuple[Number, Number], optional, default: (0, 0)) – Custom origin to center the shapes at. Default is (0, 0).
orientation (Number = 0) – Angle of rotation for the shape

Returns:

A Cycloid object with the specified number of cusps.

Return type:

Cycloid

Examples

>>> from spyrograph import Cycloid
>>> cycloid = Cycloid.n_cusps(R=10, n=5)
>>> cycloid.trace(exit_on_click=True)

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)