🌟 Overview

vizods is a powerful, intuitive Python library designed to bridge the gap between abstract code and visual understanding. Whether you're a student learning algorithms, an educator preparing materials, or a developer explaining concepts, vizods turns your data structures and algorithms into beautiful MP4 videos, GIF animations, and PNG snapshots automatically.

💡 "A picture is worth a thousand lines of code."

See It in Action

Bubble Sort in motion (GIF):

(Generate your own with sorter.save_gif("bubble_sort.gif", fps=5))

✨ Key Features

📦 Installation

Install vizods directly from PyPI:

pip install vizods

Prerequisites

• Python: 3.8 or higher
• FFmpeg (optional): Required only for .mp4 rendering. GIF export works without FFmpeg.

Installing FFmpeg (for MP4)

# Using Chocolatey
choco install ffmpeg

# Or download from https://ffmpeg.org/download.html

brew install ffmpeg

sudo apt update && sudo apt install ffmpeg

Dependencies

vizods automatically installs:

• matplotlib >= 3.5.0
• imageio >= 2.20.0
• imageio-ffmpeg >= 0.4.7 (only needed for MP4)
• networkx >= 2.8.0
• numpy >= 1.21.0

🚀 Quick Start

from vizods.bubble_sort import BubbleSort

# Create and visualize a sorting animation in 3 lines
sorter = BubbleSort([64, 25, 12, 22, 11])
sorter.sort()

# Export your animation (choose one or both!)
sorter.save_gif("my_first_animation.gif", fps=5)   # ✅ No FFmpeg needed
sorter.save_video("my_first_animation.mp4", fps=5) # Requires FFmpeg

That's it! 🎉 You now have a fully animated visualization.

📚 Supported Modules

🎯 Examples

1️⃣ Searching Algorithms

Linear Search

from vizods.linear_search import LinearSearch

data = [10, 50, 30, 70, 80, 60, 20, 90, 40]
ls = LinearSearch(data)
ls.search(70)

ls.save_gif("linear_search.gif", fps=2)
ls.save_video("linear_search.mp4", fps=2)

Binary Search

from vizods.binary_search import BinarySearch

# Binary search requires a sorted array
data = [10, 20, 30, 40, 50, 60, 70, 80, 90]
bs = BinarySearch(data)
bs.search(70)

bs.save_gif("binary_search.gif", fps=2)
bs.save_video("binary_search.mp4", fps=2)

2️⃣ Sorting Algorithms

Bubble Sort

from vizods.bubble_sort import BubbleSort

data = [64, 34, 25, 12, 22, 11, 90]
sorter = BubbleSort(data)
sorter.sort(visualize=True)

sorter.save_gif("bubble_sort.gif", fps=5)
sorter.save_video("bubble_sort.mp4", fps=5)

Insertion Sort

from vizods.insertion_sort import InsertionSort

sorter = InsertionSort([12, 11, 13, 5, 6])
sorter.sort()

sorter.save_gif("insertion_sort.gif", fps=4)
sorter.save_video("insertion_sort.mp4", fps=4)

Selection Sort

from vizods.selection_sort import SelectionSort

sorter = SelectionSort([64, 25, 12, 22, 11])
sorter.sort()

sorter.save_gif("selection_sort.gif", fps=3)
sorter.save_video("selection_sort.mp4", fps=3)

Merge Sort

from vizods.merge_sort import MergeSort

sorter = MergeSort([38, 27, 43, 3, 9, 82, 10])
sorter.sort()

sorter.save_gif("merge_sort.gif", fps=3)
sorter.save_video("merge_sort.mp4", fps=3)

Quick Sort

from vizods.quick_sort import QuickSort

sorter = QuickSort([10, 7, 8, 9, 1, 5])
sorter.sort()

sorter.save_gif("quick_sort.gif", fps=5)
sorter.save_video("quick_sort.mp4", fps=5)

3️⃣ Data Structures

Linked List

from vizods.linked_list import LinkedList

ll = LinkedList()
for value in [10, 20, 30, 40, 50]:
    ll.add_node(value)

ll.delete_node(30)

ll.save_gif("linked_list.gif", fps=2)
ll.save_video("linked_list.mp4", fps=2)

Binary Search Tree (BST)

from vizods.bst import BST

tree = BST()
for value in [50, 30, 70, 20, 40, 60, 80]:
    tree.insert(value)

tree.search(40)
tree.delete(20)

tree.save_gif("bst_animation.gif", fps=1)
tree.save_video("bst_animation.mp4", fps=1)

Stack (LIFO)

from vizods.stack import Stack

stack = Stack()
for value in [10, 20, 30]:
    stack.push(value)

stack.pop()

stack.save_gif("stack.gif", fps=2)
stack.save_video("stack.mp4", fps=2)

Queue (FIFO)

from vizods.queue import Queue

queue = Queue()
for value in [10, 20, 30]:
    queue.enqueue(value)

queue.dequeue()

queue.save_gif("queue.gif", fps=2)
queue.save_video("queue.mp4", fps=2)

4️⃣ Graph Algorithms

Dijkstra's Shortest Path

from vizods.dijkstra import Dijkstra

graph = Dijkstra()
edges = [
    ('A', 'B', 4), ('A', 'C', 2),
    ('B', 'C', 1), ('B', 'D', 5),
    ('C', 'D', 8), ('D', 'E', 2)
]
for u, v, w in edges:
    graph.add_edge(u, v, w)

graph.visualize_search(start_node='A', target_node='E')

graph.save_gif("dijkstra_path.gif", fps=1)
graph.save_video("dijkstra_path.mp4", fps=1)

🎨 Visualization Color Standards

vizods uses a consistent color language across all visualizations:

📖 API Documentation

🔹 Searching Classes (LinearSearch, BinarySearch)

🔹 Sorting Classes (BubbleSort, QuickSort, MergeSort, InsertionSort, SelectionSort)

🔹 Stack (LIFO)

🔹 Queue (FIFO)

🔹 BST (Binary Search Tree)

🔹 LinkedList

🔹 Dijkstra

🎓 Use Cases

• 🏫 Education: Teach algorithms in classrooms with engaging visuals (GIFs embed perfectly in slides & LMS pages)
• 📹 Content Creation: Produce YouTube tutorials and online courses
• 📝 Documentation: Embed GIFs in blogs, GitHub READMEs, articles, and books
• 🎤 Presentations: Make technical talks more interactive—no video player needed
• 🧪 Debugging: Visually inspect algorithm behavior frame-by-frame

🛠️ Project Structure

vizods/
├── .github/
│   └── .workflows/
│       └── pypi.yml
├── output/ # Sample outputs (MP4, GIF, PNG)
│   ├── bst_animation.mp4
│   ├── bst_animation.gif
│   ├── bst_snapshot.png
│   ├── bubble_sort.mp4
│   ├── bubble_sort.gif
│   ├── bubble_sort_snapshot.png
│   ├── ...
│   └── stack.gif
├── tests/
│   └── test_all_algorithms.py
├── vizods/
│   ├── __init__.py
│   ├── binary_search.py
│   ├── bst.py
│   ├── bubble_sort.py
│   ├── dijkstra.py
│   ├── insertion_sort.py
│   ├── linear_search.py
│   ├── linked_list.py
│   ├── merge_sort.py
│   ├── queue.py
│   ├── quick_sort.py 
│   ├── selection_sort.py
│   └── stack.py
├── .gitignore
├── LICENSE
├── README.md
├── requirements.txt
└── setup.py

🤝 Contributing

Contributions make the open-source community such an amazing place to learn and grow. Any contributions are greatly appreciated!

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Please make sure to update tests as appropriate and follow the PEP 8 style guide.

🐛 Reporting Bugs

Found a bug? Please open an issue with:

• A clear description
• Steps to reproduce
• Expected vs actual behavior
• Your environment (OS, Python version)

📜 License

Distributed under the MIT License. See LICENSE for more information.

👨‍💻 Author

Abdelrahman Ali (@Mordekai66)

📧 abdelrahman.ali.dev@gmail.com

🌟 Show Your Support

If you find vizods helpful:

• ⭐ Star this repository
• 🍴 Fork it for your projects
• 📢 Share it with fellow developers
• 💬 Tweet about it

🙏 Acknowledgements

• Matplotlib — for plotting
• NetworkX — for graph structures
• ImageIO — for video/GIF encoding
• All contributors and users of this library ❤️