World¶
Simulate the grid-based world, full of robots
The World is where all of the simulation happens. Robots are added to the World, and the Viewer and Logger refer to a World to draw the simulation and save data.
Once the World is created and you have added your robots, you will likely only need to call the
step()
method.
-
class
gridsim.world.
World
(width: int, height: int, robots: List[gridsim.robot.Robot] = [], environment: str = '', allow_collisions: bool = True, observation_stdev: float = 0.0)¶ A simulated 2D grid world for simulated Robots.
- Parameters
width (int) – Width of the world (number of cells)
height (int) – Height of the world (number of cells)
robots (List[Robot], optional) – List of Robots to place in the World to start, by default []. Additional robots can be added after initialization with the
add_robot()
method.environment (str, optional) – Filename of an image to use for a background in the World. Robots will be able to sense the color of this image. If the environment dimensions do not match the World dimensions, the image will be re-scaled (and possibly stretched). I recommend using an image with the same resolution as your grid size. This supports using
~
to indicate the user home directory.allow_collisions (bool, optional) – Whether or not to allow Robots to exist in the same grid cell, by default True.
observation_stdev (float, optional) – If 0 (this is the default), observations will return the exact RGB value of environment image in each cell. If non-zero (should be >= 0), each component of the observations will be drawn from a normal distribution with mean at the image value, and using this standard deviation. If no image is provided as the
environment
, observations will be returned as 0s, regardless of theobservation_std
.
-
add_environment
(img_filename: str)¶ Add an image to the environment for the Robots to sense. This will also be shown by the Viewer.
Because sensing is cell-based, images will be scaled to the size of the World’s grid. If the aspect ratio does not match, images will be stretched. To avoid any surprises from rescaling, I recommend using an image with the same resolution as your grid size. (e.g., if you have a 50x50 grid, use a 50px x 50px image.)
- Parameters
img_filename (str) – Filename of the RGB image to use as a background environment. Any transparency (alpha) is ignored by the robot sensing.
-
add_robot
(robot: gridsim.robot.Robot)¶ Add a single robot to the World. Robots can also be added in bulk (as a list) when the
World
is created, using therobots
keyword.- Parameters
robot (Robot) – Robot to add to the World
Count the total number of tagged cells in the World. This is useful for seeing (for example) how many cells in the World have been observed.
- Returns
Number of cells that have been tagged in the World (using the
tag()
method).- Return type
int
-
get_dimensions
() → Tuple[int, int]¶ Get the dimensions (in grid cells) of the World
- Returns
(width, height) of the World, in grid cells
- Return type
Tuple[int, int]
-
get_robots
() → pygame.sprite.Group¶ Get a list of all the robots in the World
- Returns
All Robots currently in the World
- Return type
pygame.sprite.Group
-
get_time
() → float¶ Get the current time of the World. At the moment, that’s just the number of ticks (time steps) since the simulation started, since this is a discrete-time world.
- Returns
Number of ticks (steps) since simulation started
- Return type
float
-
step
()¶ Run a single step of the simulation. This moves the robots, manages the clock, and runs the robot controllers.
-
tag
(pos: Tuple[int, int], color: Optional[Tuple[int, int, int]] = None)¶ Tag a cell position in the World with an RGB color to display in the viewer. There will be a semi-transparent overlay with the given color in that cell in the World. This is primarily for use with the Viewer, to visualize what has been sampled in the World.
- Parameters
pos (Tuple[int, int]) – (x, y) grid cell position to mark.
color (Tuple[int, int, int] or None, optional) – (R, G, B) color to set as the cell’s overlay color (each in the range [0, 255]). If you use
None
instead of a color, this will clear the tag. (If no tag is set at that position, nothing will happen.)
- Raises
ValueError – If you give an invalid color, or if you try to tag a position outside the World