✦ where mathematics becomes art ✦

◦ ─ ∿ ─ ◦ ─ ∿ ─ ◦

Generative art & geometric animations : built entirely with Python's turtle library

"The universe is written in the language of mathematics,and its characters are triangles, circles, and geometric figures." — Galileo Galilei

⭐ If this project sparks your imagination, please star the repo! ⭐

---

✦ What Is TurtleAnimations?

TurtleAnimations is a curated gallery of generative art and geometric animations — crafted entirely with Python's built-in turtle library. No game engine, no GPU renderer, no external dependencies. Just math, code, and curiosity.

Every script is a standalone mathematical poem that draws itself on screen.

---

📦 Project Structure

TurtleAnimations/
│
├── 📄 README.md
├── 🐍 main.py ← Interactive launcher menu
├── 🐍 setup_structure.py ← Repo scaffolding script
│
├── ⚙️ core/ ← Shared engine
│ ├── config.py ← Canvas settings + Config class
│ ├── fractal_engine.py ← mandelbrot(), julia(), L-systems
│ └── renderer.py ← Turtle setup + Renderer class
│
├── 🌿 fractals/
│ ├── mandelbrot_visualizer.py ← Vivid gradient Mandelbrot set
│ └── julia_set_explorer.py ← Neon cyan-pink Julia set
│
├── 🎮 interactive/
│ ├── keyboard_fireworks.py ← Press keys → fireworks
│ ├── lissajous_controller.py ← Real-time Lissajous figures
│ └── mouse_painter.py ← Draw with your cursor
│
├── 📦 legacy/
│ ├── parametric_heart.py
│ ├── arc_weave.py
│ ├── aurora_dots.py
│ ├── colorburst_sunflower.py
│ ├── crazy_dancing_arcs.py
│ ├── crescent_cardioid.py
│ ├── geometricRainbow_wheel.py
│ ├── golden_spirograph.py
│ ├── orbital_flower_pattern.py
│ ├── oscillator.py
│ ├── oscillator2.py
│ ├── star_tetrahedron.py
│ ├── starburst_orbit.py
│ └── sunburst_spiral.py
|
├── 🌀 Torus/
│ ├── lotusOf_life.py
│ └── torus_vortex.py
|
├── 🌊 physics/
│ ├── engine.py ← Simulation loop
│ ├── forces.py ← Gravity + wind
│ ├── galaxy.py ← N-body galaxy sim
│ ├── interactions.py ← Mouse gravity well
│ ├── neon.py ← Glow renderer
│ ├── particles.py ← Particle base class
│ ├── presets.py ← Firework scene
│ ├── vectors.py ← Vector field
│ └── [vectors.py](http://vectors.py)
│
├── 🧊 projections/
│ ├── camera.py ← Rotating 3D wireframe cube
│ ├── perspective.py ← 3D star field
│ ├── transform.py ← Spinning octahedron
│ └── viewport.py ← Pulsing isometric grid
│
└── 🗂️ assets/
├── fonts/ ← Font demo scripts
├── palettes/ ← JSON colour palettes
├── previews/ ← Screenshots
└── exports/ ← Canvas exports

---

🎨 Legacy Animations — Where It All Started

Animation	File	Description	Complexity
💖 Parametric Heart	parametric_heart.py	Heart from parametric equations	⭐⭐
🌀 Arc Weave	arc_weave.py	Interlocking circular arc patterns	⭐⭐⭐
🌌 Aurora Dots	aurora_dots.py	Flowing aurora-style particle waves	⭐⭐⭐
🌻 Colorburst Sunflower	colorburst_sunflower.py	Golden angle spiral with vibrant coloring	⭐⭐⭐⭐
💃 Crazy Dancing Arcs	crazy_dancing_arcs.py	Dynamic rotating arc animations	⭐⭐⭐
🌙 Crescent Cardioid	crescent_cardioid.py	Cardioid-based crescent geometry	⭐⭐⭐
🌈 Rainbow Wheel	geometricRainbow_wheel.py	Full-spectrum rotating color wheel	⭐⭐⭐
🧿 Golden Spirograph	golden_spirograph.py	Harmonic circular interference patterns	⭐⭐⭐⭐
🌸 Orbital Flower	orbital_flower_pattern.py	Rotating petal interference pattern	⭐⭐⭐
〰️ Oscillator	oscillator.py	Simple harmonic motion visualization	⭐⭐
〰️ Oscillator II	oscillator2.py	Multi-frequency oscillation patterns	⭐⭐⭐
✡️ Star Tetrahedron	star_tetrahedron.py	Sacred geometry projection	⭐⭐⭐⭐
✨ Starburst Orbit	starburst_orbit.py	Radial orbiting burst animation	⭐⭐⭐
☀️ Sunburst Spiral	sunburst_spiral.py	Fermat spiral using golden angle	⭐⭐⭐⭐

---

🌀 Torus Explorations

Animation	File	Description
🌸 Lotus of Life	lotusOf_life.py	Layered circular symmetry forming lotus-like sacred geometry
🌪️ Torus Vortex	torus_vortex.py	Rotating toroidal flow illusion using layered arcs

---

🌿 Fractals

Mathematical infinity made visible — recursive boundary structures with vivid gradient colouring.

Animation	What you see on screen
🌑 Mandelbrot Visualizer	The classic Mandelbrot set rendered in a 4-stop gradient: black interior → electric blue → vivid purple → hot orange → white-yellow at the fastest-escaping edges. The iconic seahorse valleys and bulb spirals appear in deep blue-purple.
🔵 Julia Set Explorer	A Julia set for seed c = -0.7 + 0.27015i — the classic spiral variant. Coloured in a cyan → purple → hot-pink → white neon gradient. The interior is near-black, with bright neon tendrils radiating outward. Change c in the script to explore completely different shapes.

💡 Both fractals take ~1–2 minutes to render — this is normal. Watch the rows fill in progressively in the terminal.

---

🌊 Physics Simulations

A full physics engine built on turtle — each file is both a reusable module and a standalone visual demo.

File	What you see when you run it
⚙️ engine.py	Neon particle fountain — 8 streams of coloured particles spray outward from the bottom centre, arc under gravity, and fade out. Demonstrates the Engine loop.
💨 forces.py	Neon snowstorm — hundreds of white/cyan snowflakes fall from the top, drifting sideways as wind direction randomly shifts every few seconds.
🧲 interactions.py	Mouse gravity well — 60 orbiting coloured particles circle the screen. Move your mouse to pull them toward your cursor like a gravity well.
🌟 neon.py	Neon Lissajous ribbon — a glowing trail traces a Lissajous figure (3:2 frequency ratio) in cycling neon colours, fading as it moves.
🌌 galaxy.py	N-body galaxy — 300 stars orbit a central mass. Stars are pulled toward the centre by gravity, creating spiral arm patterns over time.
🎆 presets.py	Firework show — coloured firework bursts launch from random positions, expand outward, and fade under gravity in a continuous loop.
📐 vectors.py	Animated curl vector field — a grid of arrows across the whole canvas points in directions defined by sin/cos functions that evolve over time, creating a flowing field effect.

---

🧊 3D Projections

A hand-rolled 3D pipeline — no libraries, just math turning 3D coordinates into 2D turtle drawings.

File	What you see when you run it
📷 camera.py	Rotating wireframe cube — a 3D cube with 12 rainbow-coloured edges rotates continuously around both X and Y axes using perspective projection. Each edge is a different colour.
🔭 perspective.py	3D star field — 200 stars at random 3D depths rotate slowly. Stars closer to you appear larger and brighter; distant ones are tiny. Creates a galaxy flythrough effect.
🔄 transform.py	Spinning octahedron — a 3D octahedron (6 vertices, 12 edges) rotates with slightly different X and Y angular speeds, giving it a tumbling motion. Edges cycle through 6 colours.
🖥️ viewport.py	Pulsing isometric grid — a 7×7 grid of diamond shapes pulses in and out using a sin wave, with each diamond a different colour from the palette.

---

🚀 Getting Started

# Clone
git clone https://github.com/Aaricacoding/TurtleAnimations.git
cd TurtleAnimations
# Launch the menu (recommended)
python main.py
# Or run any file directly
python fractals/mandelbrot_visualizer.py
python physics/galaxy.py
python projections/camera.py

💡 turtle is built into Python — no pip install needed. Python 3.6+ required.

---

🧮 The Math Behind the Magic

Animation	Core Formula
💖 Parametric Heart	x = 16sin³t · y = 13cos(t) − 5cos(2t) − 2cos(3t) − cos(4t)
☀️ Sunburst Spiral	Fermat's spiral r = a√θ · golden angle φ = 137.508°
🌑 Mandelbrot	zₙ₊₁ = zₙ² + c, z₀ = 0 — iterate until |z| > 2
🔵 Julia Set	zₙ₊₁ = zₙ² + c, fixed c, varying z₀
〰️ Lissajous	x = A·sin(aτ + δ) · y = B·sin(bτ)
🌌 Galaxy	F = Gm₁m₂ / r² · velocity-Verlet integration
📐 Vector Field	vx = sin(y·k + t) · vy = cos(x·k + t)
🧊 3D Cube	Rotation matrices + perspective divide f = FOV / depth

---

📅 Status

30+ scripts and growing. New animations added regularly — watch the repo to get notified.

---

🔭 Coming Soon

Category	Upcoming
🌿 Fractals	Dragon Curve · Koch Snowflake · Barnsley Fern · Sierpiński Triangle
🧊 3D	Platonic solids · Torus wireframe · Morphing polyhedra
🎮 Interactive	Real-time kaleidoscope · Gravity well painter
🌊 Physics	Double pendulum · Wave interference · Lorenz attractor

---

🤝 Contributing

1. Fork the repo
2. Place your script in the correct category folder
3. Add a docstring with the math concept used
4. Submit a pull request

Rules: turtle only · one .py file · if __name__ == "__main__" block required.

---

💫 Show Your Support

If this project inspired you, made you smile, or taught you something —

⭐ Please Star the Repo ⭐

---

📜 License

MIT — free to use, modify, and share. Just spread the beauty. 🎨

---

Made with 🐢 Python Turtle · Math · Love

✦ more animations loading... ✦