TraverseCraft 1.0.3
A Cross-Platform Real-Time Algorithm Simulation Tool
Requires Python: >=3.6
Keywords: algorithms, simulation, real-time, tkinter, education, research, visualization, machine learning, reinforcement learning, artificial intelligence, agent-based modeling, cross-platform, dynamic heatmap, world generation, customizable, interactive, framework, algorithm visualization, graph traversal, tree traversal, grid world

<!-- <picture align="center">
  <img alt="Traverse Craft Logo" src="https://github.com/srajan-kiyotaka/TraverseCraft/blob/main/src/traverseCraft/icons/logo/traverseCraftLandscapeLogo.png">
</picture> -->

[![Traverse Craft Logo](https://github.com/srajan-kiyotaka/TraverseCraft/raw/sracho/src/traverseCraft/icons/logo/traverseCraftLandscapeLogo.png)](https://harrionparrix.github.io/traversecraft/index.html)

<!-- ![Build Status](https://github.com/srajan-kiyotaka/TraverseCraft/blob/main/.github/workflows/python-app.yml/badge.svg) -->
[![Built with Python](https://img.shields.io/badge/Built%20with-Python-blue.svg)](https://www.python.org/)
[![Made with Python](https://img.shields.io/badge/Python->=3.6-blue?logo=python&logoColor=white)](https://python.org "Go to Python homepage")
![Library Version](https://img.shields.io/badge/version-1.0.1-blue.svg)
[![PyPI version](https://badge.fury.io/py/TraverseCraft.svg)](https://badge.fury.io/py/TraverseCraft)
![Supported OS](https://img.shields.io/badge/OS-Windows%20%7C%20MacOS%20%7C%20Linux-0078D6.svg)
![Supported OS: Windows](https://img.shields.io/badge/Windows-%234285F4.svg?logo=windows&logoColor=white)
![Supported OS: macOS](https://img.shields.io/badge/macOS-%23000000.svg?logo=apple&logoColor=white)
![Supported OS: Linux](https://img.shields.io/badge/Linux-%23FCC624.svg?logo=linux&logoColor=black)
[![view - Documentation](https://img.shields.io/badge/view-Documentation-blue)](https://harrionparrix.github.io/traversecraft/references/world/World.html "Go to library documentation")
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/srajan-kiyotaka/TraverseCraft/blob/main/LICENCE)
![Last Commit](https://img.shields.io/github/last-commit/srajan-kiyotaka/TraverseCraft.svg)
[![GitHub Repo Stars](https://img.shields.io/github/stars/srajan-kiyotaka/TraverseCraft.svg?style=social)](https://github.com/srajan-kiyotaka/TraverseCraft)
[![GitHub Forks](https://img.shields.io/github/forks/srajan-kiyotaka/TraverseCraft.svg?style=social)](https://github.com/srajan-kiyotaka/TraverseCraft)
![Algorithm Simulation](https://img.shields.io/badge/Algorithm%20Simulation-%2300aaff.svg)
![AI/ML Simulation](https://img.shields.io/badge/AI/ML%20Simulation-%23ff4081.svg)
![Reinforcement Learning Simulation](https://img.shields.io/badge/Reinforcement%20Learning%20Simulation-%23ffca28.svg)
![Research Work](https://img.shields.io/badge/Research%20Work-%237fbc41.svg)


<center>
  <h1>
    Traverse Craft
  </h1>
</center>

[**TraverseCraft**](https://github.com/srajan-kiyotaka/TraverseCraft) is a ***versatile***, ***cross-platform*** library written in Python for creating *static*, *animated*, and *interactive visualizations*. Designed as a *robust simulation tool*, [**TraverseCraft**](https://github.com/srajan-kiyotaka/TraverseCraft) allows users to build custom virtual worlds, populate them with agents, and observe real-time behaviors of various algorithms, including those in artificial intelligence (AI), reinforcement learning (RL), and machine learning (ML).

Powered by the ***[tkinter](https://docs.python.org/3/library/tkinter.html#module-tkinter)*** library, [**TraverseCraft**](https://github.com/srajan-kiyotaka/TraverseCraft) ensures *fast and responsive simulations*, making it ideal for students, educators, and researchers. Its intuitive framework enables users to easily generate, visualize, and interact with diverse world types and their respective agents, facilitating the study and development of advanced AI, RL, and ML algorithms.

Please visit the our official ***[website](https://harrionparrix.github.io/traversecraft/index.html)*** for more information.

## Features

- **Cross-Platform:** TraverseCraft operates seamlessly on various operating systems, ensuring a consistent experience for all users.
- **High Performance**: Built on the ***[Tkinter](https://docs.python.org/3/library/tkinter.html#module-tkinter)*** library for fast and responsive simulations.
- **Real-Time Algorithm Simulation:** Test and visualize the workings of your algorithms, such as search algorithms, in real time.
- **Dynamic Summaries and Heatmap:** Automatically generate summaries and heatmap to track agent movements and node visits dynamically.
- **Customizable World Generation:** Create and customize diverse worlds to suit your simulation needs.
- **Educational Utility:** Enhance the learning experience for students by providing a visual aid to understand algorithm workings, aiding both instructors and learners.
- **Research Application:** An invaluable tool for researchers in fields such as reinforcement learning, AI, ML, deep learning, and algorithm design.
- **User-Friendly Interface and Framework Flexibility:** Provides extensive customization options while remaining accessible to beginners.


## World Types

TraverseCraft currently supports the creation and simulation of three distinct world types:

| World Type  | Description                                                                           |
|-------------|---------------------------------------------------------------------------------------|
| Grid World  |A customizable simulation of a grid environment for testing algorithms and agent navigation, with options for path, goal, and block states to mimic various grid scenarios.  |
| Tree World  | A visualized tree data structure, perfect for experimenting with various tree-based algorithms. It offers customizable weights, positions, and appearance for flexible and detailed tree like simulations.     |
| Graph World | A visualized graph data structure, perfect for experimenting with various graph-based algorithms. It offers customizable weights, edges, positions, and appearance for flexible and detailed graph like simulations.  |

Each world type is equipped with specialized agents designed to interact within these environments, enabling comprehensive testing and visualization of algorithms. For more information about each class and methods please refer to [API Reference](https://harrionparrix.github.io/traversecraft/references/world/World.html) section.

## Examples

| <center> <a href='https://github.com/srajan-kiyotaka/TraverseCraft/blob/main/tutorials/Graph%20World/dijkstra.py'>Dijkstra Algorithm</a> </center> | <center> <a href='https://github.com/srajan-kiyotaka/TraverseCraft/blob/main/tutorials/Tree%20World/level_order_traversal.py'> Level Order Traversal Algorithm </a> </center> |
|-|-|
| <img src='https://github.com/srajan-kiyotaka/TraverseCraft/raw/main/resources/dijkstra.gif' alt='Dijkstra Algorithm'> |<img src='https://github.com/srajan-kiyotaka/TraverseCraft/raw/main/resources/level_order.gif' alt='Level Order Traversal Algorithm'>|
| <center> <a href='https://github.com/srajan-kiyotaka/TraverseCraft/blob/main/tutorials/Grid%20World/a_star.py'>A Star Algorithm</a> </center> | <center> <a href='https://github.com/srajan-kiyotaka/TraverseCraft/blob/main/tutorials/Grid%20World/unique_path.py'> Unique Path Traversal Algorithm </a> </center> |
| <img src='https://github.com/srajan-kiyotaka/TraverseCraft/raw/main/resources/AStar.gif' alt='A Star Algorithm'> |<img src='https://github.com/srajan-kiyotaka/TraverseCraft/raw/main/resources/unique_paths.gif' alt='Unique Paths Algorithm'>|

Check out more in our [**Example**](https://harrionparrix.github.io/traversecraft/user-guide/examples/index.html) section on our [website](https://harrionparrix.github.io/traversecraft/index.html)!



## Installation

To install Traverse Craft, simply run:

### Using pip

```bash
pip install TraverseCraft
```

For detailed installation instructions, refer to our [installation guide](https://harrionparrix.github.io/traversecraft/getting-started/index.html).

## Getting Started

If you are new to Traverse Craft, start with the [Quick Start](https://harrionparrix.github.io/traversecraft/getting-started/quick-start.html) available in our website. For more detailed information and learning please refer to the [Tutorials](https://harrionparrix.github.io/traversecraft/user-guide/index.html), [API reference](https://harrionparrix.github.io/traversecraft/references/world/World.html), [FAQ](https://harrionparrix.github.io/traversecraft/user-guide/faq/index.html), and view [Release](https://harrionparrix.github.io/traversecraft/releases/release-1.html) for more information.

To build and see the documentation locally, please refer to [docs/ReadMe.md](docs/ReadMe.md).

Explore the source code for deeper insights, or reach out to our [community](https://github.com/srajan-kiyotaka/TraverseCraft/discussions) for help. For further assistance, visit our official [website](https://harrionparrix.github.io/traversecraft/index.html).

## Development

All the details related to contributing to the library are [**Contributor's Toolkit**](https://harrionparrix.github.io/traversecraft/contribute/index.html). Please refer to this section as this section contains information about [Ways to Contribute](https://harrionparrix.github.io/traversecraft/contribute/ways-to-contribute.html), [Development Setup](https://harrionparrix.github.io/traversecraft/contribute/dev-setup.html), [Testing Guidelines](https://harrionparrix.github.io/traversecraft/contribute/testing.html), [Write Documentation](https://harrionparrix.github.io/traversecraft/contribute/documentation.html), [Pull Request Guidelines](https://harrionparrix.github.io/traversecraft/contribute/pull-requests.html), and [Code of Conduct](https://harrionparrix.github.io/traversecraft/contribute/code-of-conduct.html). If you are unable to access the above links you can also refer to the [Contribution Guide](./CONTRIBUTING.md) locally.

Most development discussions take place on GitHub in this library via the [Discussion Page](https://github.com/srajan-kiyotaka/TraverseCraft/discussions).


### Development Setup

#### Manual Installation

You can manually set up the development environment using the following steps:

1. Fork the repository.
2. Clone your repository into your local machine.
3. Change the directory to the cloned repository.
  ```bash
    cd TraverseCraft
  ```
4. Create a virtual environment.
5. Activate the virtual environment.
6. Install the dependencies:
  ```bash
    pip install prettytable
  ```

To set up a development environment using Docker, follow these steps:

1. Pull the Docker image from Docker Hub:

```sh
  docker pull your-username/traversecraf-dev:latest
```

2. Run the Docker container:

```sh
  docker run -it --name traversecraft-dev-container -v $(pwd):/workspace your-username/traversecraf-dev:latest
```

3. Follow step 1 to 5 of manual installation.

> Note: To Access the running container:
> ```sh
> docker exec -it traversecraft-dev-container /bin/bash
> ```

## Contributing to Traverse Craft

We welcome all contributions, including [bug reports](https://github.com/srajan-kiyotaka/TraverseCraft/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%5BBUG%5D), [bug fixes](https://github.com/srajan-kiyotaka/TraverseCraft/issues), [documentation improvements](https://github.com/srajan-kiyotaka/TraverseCraft/issues/new?assignees=&labels=documentation&projects=&template=documentation-template.md&title=%5BDOCUMENTATION%5D), [enhancements](https://github.com/srajan-kiyotaka/TraverseCraft/issues), and [ideas](https://github.com/srajan-kiyotaka/TraverseCraft/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.md&title=%5BFEATURE%5D).

Start by reading our [contributing guide](https://harrionparrix.github.io/traversecraft/contribute/contribution-guide.html).

If you have discovered a bug or have a feature request, please submit an issue on GitHub. For more detailed contribution instructions, visit our [contribution page](https://harrionparrix.github.io/traversecraft/contribute/index.html).

## Citing Traverse Craft

If you use Traverse Craft in your research or publications, please cite our library using the following reference in bibtex:

```bibtex
@misc{traversecrafthq2024,
  author = {Srajan Chourasia, Varun Patrikar},
  title = {Traverse Craft: A Cross-Platform Simulation Tool},
  year = {2024},
  url = {https://github.com/srajan-kiyotaka/TraverseCraft},
  note = {Version 1.0.0},
  publisher = {Traverse Craft Team},
}
```