Quick Links
Beginner Section
Learn how to take your first steps using Traversecraft with this tutorial.
Import required modules¶
Let's start by importing the required module form the main library.
It's always a good idea to check whether the library is installed or not. The below command will install the library if the library is not already installed.
!pip install -i https://test.pypi.org/simple/ TraverseCraft
Looking in indexes: https://test.pypi.org/simple/
Requirement already satisfied: TraverseCraft in /media/srajan/Data/Project/LibraryTests/envs/lib/python3.8/site-packages (0.7.5)
Requirement already satisfied: prettytable in /media/srajan/Data/Project/LibraryTests/envs/lib/python3.8/site-packages (from TraverseCraft) (0.7.3.dev122)
Let's import Grid World and Grid Agent¶
we will import the CreateGridWorld class from the world module and GridAgent class from the agent module.
Note: It is very important to call the right agent for the given world, otherwise the module will through an error. Each world behave differently and each agent is tailored for that world only.
Remark: Don't worry if during the importing the library prints the OS Type. Actually the library uses some internal variables which are OS depended. It is necessary that the os type printed and your OS type matches. If it does't match please report this.
from traverseCraft.world import CreateGridWorld
from traverseCraft.agent import GridAgent
OS Type: Linux
Hello Grid World¶
Let's start with a simple Hello Grid World program to get familiarize with the library.
We will create a simple grid world of dimension (8 x 8) with the default settings on.
# First let's Create a grid world object!
gridWorld = CreateGridWorld(worldName="Hello World", rows=8, cols=8)
Compile our Hello Grid World¶
since, we are just creating a simple grid world with all the default settings, we are ready to compile our world.
Note: It is recommended to do all the changes in the world after compiling the world. Although you can change the world even before the compilation but then the world will show some partial information before compiling the world takes place.
gridWorld.constructWorld()
Warning: Don't worry if the window showed up. Please don't destroy the window. This is due to the fact that the cell in jupyter notebook is running the process and the frame generated will reflect all the changes done after this point. If you destroy the window then it will show error.
Let's see some basic information about our Hello World!¶
you can use a simple print() statement or you can use the builtin function aboutWorld() to get the world information as a string.
print(gridWorld)
+-------------------------+-------------+
| Attribute | Value |
+-------------------------+-------------+
| World Name | Hello World |
| Rows | 8 |
| Columns | 8 |
| Cell Size | 20 |
| Cell Padding | 2 |
| Window Size | 249x204 |
| Path Color | gray |
| Block Color | red |
| Goal Color | green |
| Border Width | 1 |
| Button Background Color | #7FC7D9 |
| Button Foreground Color | #332941 |
| Button Text | Start Agent |
| Text Font | Helvetica |
| Text Size | 24 |
| Text Weight | bold |
+-------------------------+-------------+
print(gridWorld.aboutWorld())
+-------------------------+-------------+
| Attribute | Value |
+-------------------------+-------------+
| World Name | Hello World |
| Rows | 8 |
| Columns | 8 |
| Cell Size | 20 |
| Cell Padding | 2 |
| Window Size | 249x204 |
| Path Color | gray |
| Block Color | red |
| Goal Color | green |
| Border Width | 1 |
| Button Background Color | #7FC7D9 |
| Button Foreground Color | #332941 |
| Button Text | Start Agent |
| Text Font | Helvetica |
| Text Size | 24 |
| Text Weight | bold |
+-------------------------+-------------+
help(gridWorld)
Help on CreateGridWorld in module traverseCraft.world object:
class CreateGridWorld(builtins.object)
| CreateGridWorld(worldName: str, rows: int, cols: int, cellSize: int = 20, pathColor: str = 'gray', blockColor: str = 'red', goalColor: str = 'green', cellPadding: int = 2, borderWidth: int = 1, buttonBgColor: str = '#7FC7D9', buttonFgColor: str = '#332941', textFont: str = 'Helvetica', textSize: int = 24, textWeight: str = 'bold', buttonText: str = 'Start Agent', logoPath: str = None)
|
| Class representing the world created using Grids.
|
| Attributes:
| setOfCoordinates (List[List[int]]): A list of coordinates.
| coordinate (List[int]): A list representing a coordinate.
| worldID (str): The ID of the world.
|
| Args:
| _worldName (str): The name of the world.
| _rows (int): The number of rows in the world. (Between 0 and 50)
| _cols (int): The number of columns in the world. (Between 0 and 50)
| _logoPath (str): The path to the logo image.
| _world (List[List[int]]): A 2D list representing the world.
| _blockCells (setOfCoordinates): A set of coordinates representing the block cells.
| _cellSize (int): The size of each cell in pixels.Defaults to 10. (Between 10 and 60)
| _pathColor (str): The color of the path cells. Defaults to "gray".
| _cellPadding (int): The padding around each cell in pixels. Defaults to 2.
| _blockColor (str): The color of the block cells. Defaults to "red".
| _borderWidth (int): The width of the cell borders in pixels. Defaults to 1.
| _goalColor (str): The color of the goal cells. Defaults to "green".
| _goalCells (setOfCoordinates): A set of coordinates representing the goal cells.
| _buttonBgColor (str): The background color of the button. Defaults to "#7FC7D9".
| _buttonFgColor (str): The foreground color of the button. Defaults to "#332941".
| _textFont (str): The font of the button text. Defaults to "Helvetica".
| _textSize (int): The size of the button text. Defaults to 24.
| _textWeight (str): The weight of the button text. Defaults to "bold".
| _buttonText (str): The text displayed on the button. Defaults to "Start Agent".
| _root (Tk): The root window of the world.
| _agent (Agent): The agent object.
| _logoPath (str): The path to the logo image.
|
| Methods defined here:
|
| __init__(self, worldName: str, rows: int, cols: int, cellSize: int = 20, pathColor: str = 'gray', blockColor: str = 'red', goalColor: str = 'green', cellPadding: int = 2, borderWidth: int = 1, buttonBgColor: str = '#7FC7D9', buttonFgColor: str = '#332941', textFont: str = 'Helvetica', textSize: int = 24, textWeight: str = 'bold', buttonText: str = 'Start Agent', logoPath: str = None)
| Initializes the Grid World.
|
| __str__(self)
| Describes the attributes of the world.
|
| Parameters:
| None
|
| Returns:
| function(): The attributes of the world.
|
| aboutWorld(self)
| Describes the attributes of the world.
|
| Parameters:
| None
|
| Returns:
| str: The attributes of the world.
|
| constructWorld(self)
| Constructs the world by creating and arranging cells in the GUI.
| If the goal cells are not set, it creates a goal cell at the bottom-right corner of the grid.
| It also creates cells for each row and column in the grid, and binds a left-click event to toggle the cells.
| Finally, it creates a "Start Agent" button at the bottom of the grid.
|
| Parameters:
| None
|
| Returns:
| None
|
| setAgent(self, agent)
| Set the agent for the world.
|
| Parameters:
| agent (Agent): The agent object to set.
|
| Returns:
| None
|
| setBlockPath(self, blockCells: List[List[int]])
| Adds block cells to the world grid.
|
| Parameters:
| blockCells (setOfCoordinates): A set of coordinates representing the block cells.
|
| Returns:
| None
|
| setGoalState(self, goalState: List[List[int]])
| Adds the goal state to the world grid.
|
| Parameters:
| goalState (setOfCoordinates): A set of coordinates representing the goal state.
|
| Returns:
| None
|
| showWorld(self)
| Displays the world.
|
| Parameters:
| None
|
| Returns:
| None
|
| summary(self)
| Generates a summary of the world.
|
| Parameters:
| None
|
| Returns:
| str: The summary of the world.
|
| updateWorld(self)
| Updates the world by positioning the cells in a grid layout and updating the root window.
|
| This method iterates over each cell in the world and positions it in a grid layout using the row and column indices.
| It also updates the root window to reflect any changes made to the world.
|
| Note:
| - The cells are positioned using the `grid` method with the specified row and column indices.
| - The `sticky` parameter is set to "nsew" to make the cells stick to all sides of their respective grid cells.
| - The `padx` and `pady` parameters specify the padding around each cell.
|
| Parameters:
| None
| Returns:
| None
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| coordinate = typing.List[int]
| The central part of internal API.
|
| This represents a generic version of type 'origin' with type arguments 'params'.
| There are two kind of these aliases: user defined and special. The special ones
| are wrappers around builtin collections and ABCs in collections.abc. These must
| have 'name' always set. If 'inst' is False, then the alias can't be instantiated,
| this is used by e.g. typing.List and typing.Dict.
|
| setOfCoordinates = typing.List[typing.List[int]]
| The central part of internal API.
|
| This represents a generic version of type 'origin' with type arguments 'params'.
| There are two kind of these aliases: user defined and special. The special ones
| are wrappers around builtin collections and ABCs in collections.abc. These must
| have 'name' always set. If 'inst' is False, then the alias can't be instantiated,
| this is used by e.g. typing.List and typing.Dict.
|
| worldID = 'GRIDWORLD'
Let's create our agent which will interact with the world.¶
here also we will create a simple grid agent with the default settings.
gridAgent = GridAgent(agentName="Grid Agent", world=gridWorld)
Let's see some basic information about our grid Agent.¶
you can use a simple print() statement or you can use the builtin function aboutAgent() to get the agent information as a string.
print(gridAgent)
+----------------+-------------+
| Attribute | Value |
+----------------+-------------+
| Agent Name | Grid Agent |
| Agent Color | blue |
| World Name | Hello World |
| World ID | GRIDWORLD |
| Start Position | (0, 0) |
+----------------+-------------+
print(gridAgent.aboutAgent())
+----------------+-------------+
| Attribute | Value |
+----------------+-------------+
| Agent Name | Grid Agent |
| Agent Color | blue |
| World Name | Hello World |
| World ID | GRIDWORLD |
| Start Position | (0, 0) |
+----------------+-------------+
Connect Our Agent with the World¶
Now, we have our world ready and constructed and we also have our agent ready, but the world doesn't know the agent and the agent does't know the world. We have to connect the agent with the world. We will use the .setAgent() method of the world to connect the agent with the world.
gridWorld.setAgent(gridAgent)
Algorithm¶
Now, we have connected the agent with the world, but we did not told the agent what to do in the world.
The agent have a method setAlgorithmCallBack() which takes a function as a argument.
This function will be run during the simulation.
Note: Make sure that the function you are passing in the
setAlgorithmCallBack()method does not take any argument.
Let's first create our function which will tell the agent what to do.¶
We will start from position (0,0), which is the start position of the agent by default and we will move the agent in the following manner:
(0, 0) -> (0, 1) -> (0, 2) -> (0, 3) -> (0, 4) -> (1, 4) -> (1, 5) -> (2, 5) -> (3, 5) -> (3, 4) -> (3, 3) -> (2, 3) -> (1, 3) -> (0, 3) -> (0, 2) -> (0, 1) -> (0, 2) -> (1, 2)
def whatToDo():
print("I am a Grid Agent and I am going to move around the world!")
gridAgent.moveAgent(0, 1)
gridAgent.moveAgent(0, 2)
gridAgent.moveAgent(0, 3)
gridAgent.moveAgent(0, 4)
gridAgent.moveAgent(1, 4)
gridAgent.moveAgent(1, 5)
gridAgent.moveAgent(2, 5)
gridAgent.moveAgent(3, 5)
gridAgent.moveAgent(3, 4)
gridAgent.moveAgent(3, 3)
gridAgent.moveAgent(2, 3)
gridAgent.moveAgent(1, 3)
gridAgent.moveAgent(0, 3)
gridAgent.moveAgent(0, 2)
gridAgent.moveAgent(0, 1)
gridAgent.moveAgent(0, 2)
gridAgent.moveAgent(1, 2)
print("I am done moving around the world!")
We are ready with our algorithm¶
Lets set the algorithm to tell the agent what to do.
gridAgent.setAlgorithmCallBack(whatToDo)
Display the world and Start the Simulation!¶
Now, we are all set. We will first show the world using the showWorld() method and then on the world there is a button at the bottom to start the simulation.
Warning: Always make sure that the method
showWorld()is called when you are ready to simulate, because after this no change can be made on the world or the agent.
gridWorld.showWorld()
I am a Grid Agent and I am going to move around the world!
I am done moving around the world!
In the window You can see the heatmap forming where the agent is going. This is the default function of the agent, but you can switch off this feature also by simple changing the value of heatMapView to False during the grid agent object creation.
You can also see there is a slight delay in the movement of the agent, this is also a feature of agent, you can control the delay while calling the moveAgent method by the parameter delay.
Let's see the summary¶
The agent and the world keep some records, that we can generate and see.
The Agent have information about the time taken to run the whole simulation.¶
We can see this information using the summary method.
print(gridAgent.summary())
+--------------+---------------------------+
| Attribute | Value |
+--------------+---------------------------+
| Start Time | Wed, 19 Jun 2024 06:44:52 |
| End Time | Wed, 19 Jun 2024 06:45:01 |
| Elapsed Time | 8.533 sec |
+--------------+---------------------------+
The World have information about the visited count after the whole simulation.¶
We can see this information using the summary method.
print(gridWorld.summary())
+------+---+---+---+---+---+---+---+---+
| Cell | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
+------+---+---+---+---+---+---+---+---+
| 0 | 1 | 2 | 3 | 2 | 1 | 0 | 0 | 0 |
| 1 | 0 | 0 | 1 | 1 | 1 | 1 | 0 | 0 |
| 2 | 0 | 0 | 0 | 1 | 0 | 1 | 0 | 0 |
| 3 | 0 | 0 | 0 | 1 | 1 | 1 | 0 | 0 |
| 4 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 5 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 6 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 7 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
+------+---+---+---+---+---+---+---+---+
help(gridAgent)
Help on GridAgent in module traverseCraft.agent object:
class GridAgent(builtins.object)
| GridAgent(world, agentName: str, agentColor: str = 'blue', heatMapView: bool = True, heatMapColor: str = '#FFA732', agentPos: tuple = (0, 0), heatGradient: float = 0.05)
|
| The Grid Agent class.
|
| Parameters:
| - world (CreateGridWorld): The grid world object in which the agent operates.
| - agentName (str): The name of the agent.
| - agentColor (str, optional): The color of the agent. Defaults to "blue".
| - heatMapView (bool, optional): Whether to enable the heat map view. Defaults to True.
| - heatMapColor (str, optional): The color of the heat map. Defaults to "#FFA732".
| - agentPos (tuple, optional): The initial position of the agent. Defaults to (0, 0).
| - heatGradient (float, optional): The gradient value for the heat map. Defaults to 0.05.
|
| Attributes:
| _worldObj (CreateGridWorld): The grid world object.
| _worldID (str): The ID of the world.
| _root (Tk): The root Tkinter object from the grid world.
| _agentName (str): The name of the agent.
| _agentColor (str): The color of the agent.
| _heatMapView (bool): Indicates if the heat map view is enabled.
| _heatMapColor (str): The color of the heat map.
| _heatMapBaseColor (str): The base color of the heat map.
| _heatGradient (float): The gradient value for the heat map.
| _startState (tuple): The initial position of the agent.
| _currentPosition (tuple): The current position of the agent.
| _startTime (float): The start time of the agent.
| _endTime (float): The end time of the agent.
| algorithmCallBack (function): Callback function for the agent's algorithm.
|
| Methods defined here:
|
| __init__(self, world, agentName: str, agentColor: str = 'blue', heatMapView: bool = True, heatMapColor: str = '#FFA732', agentPos: tuple = (0, 0), heatGradient: float = 0.05)
| Initialize self. See help(type(self)) for accurate signature.
|
| __str__(self)
| Describes the attributes of the world.
|
| Parameters:
| None
|
| Returns:
| function(): The attributes of the world.
|
| aboutAgent(self)
| Prints information about the agent.
|
| Parameters:
| None
|
| Returns:
| str: A string containing information about the agent.
|
| checkBlockState(self, i, j)
| Check the state of a block in the world.
|
| Parameters:
| i (int): The row index of the block.
| j (int): The column index of the block.
|
| Returns:
| bool: True if the block is empty (-1), False otherwise.
|
| checkGoalState(self, i, j)
| Check if the given position (i, j) is a goal state.
|
| Parameters:
| i (int): The row index of the position.
| j (int): The column index of the position.
|
| Returns:
| bool: True if the position is a goal state, False otherwise.
|
| getHeatMapColor(self, value: float)
| Maps a value to a color on a heat map.
|
| Args:
| value (float): The value to be mapped.
|
| Returns:
| tuple: The RGB color tuple representing the mapped value on the heat map.
|
| moveAgent(self, i, j, delay: float = 0.5)
| Moves the agent to the specified position (i, j) on the grid.
|
| Args:
| i (int): The row index of the target position.
| j (int): The column index of the target position.
| delay (int, optional): The delay in seconds before moving the agent. Defaults to 1.
|
| Returns:
| bool: True if the agent successfully moves to the target position, False otherwise.
|
| runAlgorithm(self)
| Executes the algorithm callback function.
|
| Raises:
| ValueError: If the algorithm callback function is not set.
|
| setAlgorithmCallBack(self, algorithmCallBack)
| Set the callback function for the algorithm.
|
| Parameters:
| algorithmCallBack (function): The callback function to be set.
|
| Returns:
| None
|
| setStartState(self, i: int, j: int)
| Sets the start state of the agent to the specified position (i, j).
|
| Args:
| i (int): The row index of the start position.
| j (int): The column index of the start position.
|
| Raises:
| ValueError: If the specified start position is invalid.
|
| summary(self)
| Returns a summary of the agent run.
|
| Parameters:
| None
| Returns:
| str: A summary of the agent run.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
This covers the basic of how to create a simple Grid World and Grid Agent. How to connect the created agent with the world and how to run a simple algorithm to simulate the agent on the world.
Next, in the Advance Section we will learn about how to use some advance features and settings to customize the world according to your need.
Thanks!