vizods 2.3.0

The ultimate Python toolkit for animating Data Structures and Algorithms.

🎨 vizods

Visualize Data Structures & Algorithms with Python

Transform abstract algorithms into stunning animated visualizations with a single line of code.

Installation • Quick Start • Documentation • Examples • Contributing

---

🌟 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 animations and PNG snapshots automatically.

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

---

✨ Key Features

Feature	Description
🎬 Auto Animation	Generate .mp4 videos of algorithm execution step-by-step
📸 Snapshot Export	Save final or intermediate states as .png images
🌳 Tree Visualization	Hierarchical layouts for Binary Search Trees
📊 Sorting Animations	Bar chart visualizations with color-coded states
🔍 Search Animations	Dynamic highlighting of search ranges and target matching
🗺️ Graph Pathfinding	Step-by-step Dijkstra's algorithm tracing with weights
🔗 Linked Lists	Pointer-based node visualization
🎨 Color-Coded States	Universal color scheme for clarity
⚡ Zero Configuration	Works out of the box — just pip install and run

---

📦 Installation

Install vizods directly from PyPI:

pip install vizods

Prerequisites

• Python: 3.8 or higher
• FFmpeg: Required for .mp4 rendering

Installing FFmpeg

🪟 Windows

# Using Chocolatey
choco install ffmpeg

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

🍎 macOS

brew install ffmpeg

🐧 Linux (Ubuntu/Debian)

sudo apt update && sudo apt install ffmpeg

Dependencies

vizods automatically installs:

• matplotlib >= 3.5.0
• imageio >= 2.20.0
• imageio-ffmpeg >= 0.4.7
• 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()
sorter.save_video("my_first_animation.mp4")

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

---

📚 Supported Modules

Category	Module	Class	Visual Style
Searching	linear_search	LinearSearch	🔍 Highlighted Bars
	binary_search	BinarySearch	📉 Range Reduction
Sorting	bubble_sort	BubbleSort	📊 Bar Chart
	insertion_sort	InsertionSort	📊 Bar Chart
	selection_sort	SelectionSort	📊 Bar Chart
	merge_sort	MergeSort	📊 Bar Chart
	quick_sort	QuickSort	📊 Bar Chart
Data Structures	linked_list	LinkedList	🔗 Nodes & Pointers
	bst	BST	🌳 Hierarchical Tree
	stack	Stack	📚 Vertical Bar Stack
	queue	Queue	➡️ Horizontal Bar Queue
Graph Algorithms	dijkstra	Dijkstra	🗺️ Weighted Graph

---

🎯 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_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_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_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_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_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_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_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_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_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_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_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_video("dijkstra_path.mp4", fps=1)

---

🎨 Visualization Color Standards

vizods uses a consistent color language across all visualizations:

Color	Meaning
🟢 Green	Sorted / Visited / Completed
🟠 Orange	Active / Currently Processing
🔴 Red	Critical / Deleting / Shortest Path
🔵 Skyblue	Standard / Unprocessed
🟣 Purple	Pivot (Quick Sort)
⚪ Lightgray	Inactive / Waiting

---

📖 API Documentation

🔹 Searching Classes (LinearSearch, BinarySearch)

Method	Parameters	Description
__init__(data)	data: list	Initialize with a list of numbers
search(target)	target: int/float	Start the search process and capture frames
save_video(output_name, fps)	output_name: str, fps: int	Export search animation as MP4

---

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

Method	Parameters	Description
__init__(data)	data: list	Initialize with a list of numbers
sort(visualize=True)	visualize: bool	Run the sorting algorithm & capture frames
save_video(output_name, fps)	output_name: str, fps: int	Export sorting animation as MP4
save_snapshot(filename)	filename: str	Save the final sorted state as PNG

---

🔹 Stack (LIFO - Last In First Out)

Method	Parameters	Description
push(value)	value	Add an element to the top of the stack
pop()	-	Remove and return the top element
peek()	-	View the top element without removing it
is_empty()	-	Check if the stack is empty
save_video(output_name, fps)	output_name: str, fps: int	Export stack operations as MP4
save_snapshot(filename)	filename: str	Save a snapshot of the current stack state

---

🔹 Queue (FIFO - First In First Out)

Method	Parameters	Description
enqueue(value)	value	Add an element to the end of the queue
dequeue()	-	Remove and return the front element
front()	-	View the first element in the queue
rear()	-	View the last element in the queue
save_video(output_name, fps)	output_name: str, fps: int	Export queue operations as MP4
save_snapshot(filename)	filename: str	Save a snapshot of the current queue state

---

🔹 BST (Binary Search Tree)

Method	Description
insert(value)	Insert a new node into the tree
search(value)	Search for a value, animating the traversal path
delete(value)	Delete a node (currently supports leaf nodes)
save_video(output_name, fps)	Export full tree operations as MP4
save_snapshot(filename)	Save the current tree structure as PNG

---

🔹 LinkedList

Method	Description
add_node(value)	Append a new node to the end of the list
delete_node(value)	Remove a specific node from the list
save_video(output_name, fps)	Export pointer/node operations as MP4

---

🔹 Dijkstra

Method	Parameters	Description
add_edge(u, v, weight)	u, v: nodes, weight: int	Add a weighted edge between two nodes
visualize_search(start, target)	start, target: nodes	Run and animate the shortest pathfinding process
save_video(output_name, fps)	output_name: str, fps: int	Export pathfinding animation as MP4

---

🎓 Use Cases

• 🏫 Education: Teach algorithms in classrooms with engaging visuals
• 📹 Content Creation: Produce YouTube tutorials and online courses
• 📝 Documentation: Embed animations in blogs, articles, and books
• 🎤 Presentations: Make technical talks more interactive
• 🧪 Debugging: Visually inspect algorithm behavior

---

🛠️ Project Structure

vizods/
├── .github/
│   └── .workflows/
│       └── pypi.yml
├── output/ # Samples
│   ├── bst_animation.mp4
│   ├── bst_snapshot.png
│   ├── bubble_sort_snapshot.png
│   ├── bubble_sort.mp4
│   ├── ...
│   ├── ...
│   ├── ...
│   └── stack.mp4
├── 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)

📧 [e-mail]

---

🌟 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 encoding
• All contributors and users of this library ❤️

---

Developed with ❤️ by Mordekai66

If this project helped you, consider giving it a ⭐ on GitHub!