irsim.world.map#

Submodules#

Classes#

`GridMapGenerator`	Abstract base for procedural grid map generators.
`ImageGridGenerator`	Load obstacle grid from an image file (path).
`ObstacleMap`	Base class representing a generic object in the robot simulator.
`PerlinGridGenerator`	Perlin noise based 2D occupancy grid map.
`EnvGridMap`	Structural type accepted by all path planners.
`Map`	Map data container for navigation / path-planning.

Functions#

`resolve_obstacle_map`(→ numpy.ndarray \| None)	Resolve obstacle_map to None or a float64 occupancy grid ndarray.
`build_grid_from_generator`(→ numpy.ndarray)	Build a grid map from a YAML grid_generator spec (name + resolution + params).

Package Contents#

class irsim.world.map.GridMapGenerator(**kwargs: Any)[source]#

Bases: abc.ABC

Abstract base for procedural grid map generators.

Subclasses must implement _build_grid() and set class attributes name (for YAML) and yaml_param_names (allowed constructor params from YAML).

Subclasses accept their own parameters via kwargs.

registry: ClassVar[dict[str, type[GridMapGenerator]]]#

name: str = ''#

yaml_param_names: tuple[str, Ellipsis] = ()#

generate() → GridMapGenerator[source]#: Build the grid and return self. Call _build_grid() and set _grid.

property grid: numpy.ndarray#: Occupancy grid (0-100). Generates on first access if needed.

save_as_image(filepath: str, invert: bool = True) → None[source]#: Save grid as grayscale PNG for use with World.gen_grid_map().

preview(title: str = 'Grid Map', cmap: str = 'gray_r') → None[source]#: Display the occupancy grid with matplotlib.

class irsim.world.map.ImageGridGenerator(path: str, **kwargs: Any)[source]#

Bases: irsim.world.map.grid_map_generator_base.GridMapGenerator

Load obstacle grid from an image file (path).

Subclasses accept their own parameters via kwargs.

name = 'image'#

yaml_param_names = ('path',)#

path#

class irsim.world.map.ObstacleMap(shape: dict | None = None, color: str = 'k', static: bool = True, grid_map: numpy.ndarray | None = None, grid_reso: numpy.ndarray | None = None, world_offset: list[float] | None = None, **kwargs: Any)[source]#

Bases: irsim.world.object_base.ObjectBase

Base class representing a generic object in the robot simulator.

This class encapsulates common attributes and behaviors for all objects, including robots and obstacles, managing their state, velocity, goals, and kinematics.

Parameters:

shape (dict) – Parameters defining the shape of the object for geometry creation. The dictionary should contain keys and values required by the GeometryFactory to create the object’s geometry, such as ‘type’ (e.g., ‘circle’, ‘rectangle’) and associated parameters. Defaults to None.
kinematics (dict) – Parameters defining the kinematics of the object. Includes kinematic model and any necessary parameters. If None, no kinematics model is applied. Defaults to None.
state (list of float) – Initial state vector [x, y, theta, …]. The state can have more dimensions depending on state_dim. Excess dimensions are truncated, and missing dimensions are filled with zeros. Defaults to [0, 0, 0].
velocity (list of float) – Initial velocity vector [vx, vy] or according to the kinematics model. Defaults to [0, 0].
goal (list of float or list of list of float) – Goal state vector [x, y, theta, …] or [[x, y, theta], [x, y, theta], …] for multiple goals Used by behaviors to determine the desired movement. Defaults to [10, 10, 0].
role (str) – Role of the object in the simulation, e.g., “robot” or “obstacle”. Defaults to “obstacle”.
color (str) – Color of the object when plotted. Defaults to “k” (black).
static (bool) – Indicates if the object is static (does not move). Defaults to False.
vel_min (list of float) – Minimum velocity limits for each control dimension. Used to constrain the object’s velocity. Defaults to [-1, -1].
vel_max (list of float) – Maximum velocity limits for each control dimension. Used to constrain the object’s velocity. Defaults to [1, 1].
acce (list of float) – Acceleration limits, specifying the maximum change in velocity per time step. Defaults to [inf, inf].
angle_range (list of float) – Allowed range of orientation angles [min, max] in radians. The object’s orientation will be wrapped within this range. Defaults to [-pi, pi].
behavior (dict or str) – Behavioral mode or configuration of the object. Can be a behavior name (str) or a dictionary with behavior parameters. If None, default behavior is applied. Defaults to {‘name’: ‘dash’}, moving to the goal directly.
group_behavior (dict) – Shared behavior defaults for objects in the same group. When an object’s own behavior configuration is empty or missing, the group behavior will be used as a fallback and exposed via beh_config.
goal_threshold (float) – Threshold distance to determine if the object has reached its goal. When the object is within this distance to the goal, it’s considered to have arrived. Defaults to 0.1.
sensors (list of dict) – List of sensor configurations attached to the object. Each sensor configuration is a dictionary specifying sensor type and parameters. Defaults to None.
arrive_mode (str) – Mode for arrival detection, either “position” or “state”. Determines how arrival at the goal is evaluated. Defaults to “position”.
description (str) – Description or label for the object. Can be used for identification or attaching images in plotting. Defaults to None.
group (int) – Group identifier for organizational purposes, allowing objects to be grouped. Defaults to 0.
state_dim (int) – Dimension of the state vector. If None, it is inferred from the class attribute state_shape. Defaults to None.
vel_dim (int) – Dimension of the velocity vector. If None, it is inferred from the class attribute vel_shape. Defaults to None.
unobstructed (bool) – Indicates if the object should be considered to have an unobstructed path, ignoring obstacles in certain scenarios. Defaults to False.
fov (float) – Field of view angles in radians for the object’s sensors. Defaults to None. If set lidar, the default value is angle range of lidar.
fov_radius (float) – Field of view radius for the object’s sensors. Defaults to None. If set lidar, the default value is range_max of lidar.
**kwargs –
Additional keyword arguments for extended functionality.
- plot (dict): Plotting options for the object. May include ‘show_goal’, ‘show_text’, ‘show_arrow’, ‘show_uncertainty’, ‘show_trajectory’, ‘trail_freq’, etc.

Raises:

ValueError – If dimension parameters do not match the provided shapes or if input parameters are invalid.

state_dim#

Dimension of the state vector.

Type:: int

state_shape#

Shape of the state array.

Type:: tuple

vel_dim#

Dimension of the velocity vector.

Type:: int

vel_shape#

Shape of the velocity array.

Type:: tuple

state#

Current state of the object.

Type:: np.ndarray

_init_state#

Initial state of the object.

Type:: np.ndarray

_velocity#

Current velocity of the object.

Type:: np.ndarray

_init_velocity#

Initial velocity of the object.

Type:: np.ndarray

_goal#

Goal state of the object.

Type:: np.ndarray

_init_goal#

Initial goal state of the object.

Type:: np.ndarray

_geometry#

Geometry representation of the object.

Type:: any

group#

Group identifier for the object.

Type:: int

stop_flag#

Flag indicating if the object should stop.

Type:: bool

arrive_flag#

Flag indicating if the object has arrived at the goal.

Type:: bool

collision_flag#

Flag indicating a collision has occurred.

Type:: bool

unobstructed#

Indicates if the object has an unobstructed path.

Type:: bool

static#

Indicates if the object is static.

Type:: bool

vel_min#

Minimum velocity limits.

Type:: np.ndarray

vel_max#

Maximum velocity limits.

Type:: np.ndarray

color#

Color of the object.

Type:: str

role#

Role of the object (e.g., “robot”, “obstacle”).

Type:: str

info#

Information container for the object.

Type:: ObjectInfo

wheelbase#

Distance between the front and rear wheels. Specified for ackermann robots.

Type:: float

fov#

Field of view angles in radians.

Type:: float

fov_radius#

Field of view radius.

Type:: float

Create an obstacle map object from a set of line segments.

Parameters:

shape (dict | None) – Map shape configuration with keys like {"name": "map", "reso": float, "points": array}.
color (str) – Display color. Default “k”.
static (bool) – Whether the object is static. Default True.
grid_map (np.ndarray | None) – Grid map array for fast collision detection.
grid_reso (np.ndarray | None) – Resolution [x_reso, y_reso] of the grid.
world_offset (list | None) – World offset [x, y].
**kwargs – Forwarded to ObjectBase constructor.

linestrings#

geometry_tree#

grid_map = None#

grid_reso = None#

world_offset = None#

check_grid_collision(geometry) → bool[source]#

Check collision using grid array lookup.

Uses a two-phase approach: 1. Quick bounding box check for early rejection 2. Precise check: verify if geometry actually intersects occupied cells

Parameters:: geometry – Shapely geometry object to check collision for.
Returns:: True if collision detected, False otherwise.
Return type:: bool

is_collision(geometry) → bool[source]#: Check collision against grid (if present) and map geometry.

class irsim.world.map.PerlinGridGenerator(width: int, height: int, complexity: float = 0.142857, fill: float = 0.38, fractal: int = 1, attenuation: float = 0.5, seed: int | None = None)[source]#

Bases: irsim.world.map.grid_map_generator_base.GridMapGenerator

Perlin noise based 2D occupancy grid map.

Holds width, height, and a grid of occupancy values (0-100; values > 50 are obstacles). Parameter semantics follow GCOPTER map_gen (ZJU-FAST-Lab/GCOPTER). Output can be saved as PNG for use with World.gen_grid_map().

Initialize map parameters.

Parameters:

width (int) – Map width in grid cells.
height (int) – Map height in grid cells.
complexity (float) – Base noise frequency. Default 0.142857.
fill (float) – Obstacle ratio in [0, 1]. Default 0.38.
fractal (int) – Number of octave layers. Default 1. Must be >= 1.
attenuation (float) – Amplitude decay per octave. Default 0.5. Must be > 0.
seed (int | None) – Random seed for reproducibility.

name = 'perlin'#

yaml_param_names = ('complexity', 'fill', 'fractal', 'attenuation', 'seed')#

width#

height#

complexity = 0.142857#

fill = 0.38#

fractal = 1#

attenuation = 0.5#

seed = None#

preview(title: str = 'Perlin 2D Map', cmap: str = 'gray_r') → None[source]#: Preview the grid with matplotlib.

class irsim.world.map.EnvGridMap[source]#

Bases: Protocol

Structural type accepted by all path planners.

Any object that exposes the attributes below (including Map) is a valid EnvGridMap. Planners should annotate their env_map parameter with this protocol instead of the concrete Map class to support duck-typed map objects.

Collision precedence (adopted by every planner):

Grid lookup (O(1) per cell) when grid is not None; if the grid reports occupied, the point is in collision.
When the grid reports free or is unavailable, Shapely geometry intersection with obstacle_list is used. Planners therefore combine grid and obstacle_list when both are present.

width: float#

height: float#

resolution: float#

obstacle_list: list#

grid: numpy.ndarray | None#

world_offset: tuple[float, float]#

property grid_resolution: tuple[float, float] | None#: Actual cell size (x_reso, y_reso) derived from grid shape and world size.

grid_occupied(x: float, y: float, margin_x: float = 0.0, margin_y: float = 0.0, threshold: float = 50.0) → bool | None[source]#: Check if any grid cell within the bounding box is occupied.

is_collision(geometry) → bool[source]#: Check collision for a Shapely geometry against the map.

Resolve obstacle_map to None or a float64 occupancy grid ndarray.

Accepted types: None, ndarray, or a generator spec dict with name (e.g. "image" or "perlin"). For backward compatibility, a str is treated as {"name": "image", "path": obstacle_map}.

name == "image": only path is required; grid size comes from the image.
Other names (e.g. "perlin"): require resolution and world size (world_width / world_height); grid size = world size / resolution.

Returns:: None, or ndarray (0-100 grid, dtype float64).

irsim.world.map.build_grid_from_generator(spec: dict[str, Any], world_width: float, world_height: float) → numpy.ndarray[source]#

Build a grid map from a YAML grid_generator spec (name + resolution + params).

Grid size is always computed from world size and resolution (meters per cell): (world_width / resolution, world_height / resolution) cells.

Parameters:

spec – Dict from YAML, e.g. {name: perlin, resolution: 0.1, ...}.
world_width – World width in meters.
world_height – World height in meters.

Returns:

Occupancy grid (0-100) as float64 ndarray.

class irsim.world.map.Map(width: float = 10, height: float = 10, resolution: float = 0.1, obstacle_list: list | None = None, grid: numpy.ndarray | None = None, world_offset: tuple[float, float] | list[float] | None = None)[source]#

Map data container for navigation / path-planning.

Satisfies the EnvGridMap protocol so that it can be passed to any planner that expects EnvGridMap.

Collision precedence (shared by all planners):

Grid lookup (O(1) per cell) when grid is not None.
Shapely geometry intersection when grid is unavailable.

Initialize the Map.

Parameters:

width – Width of the world (metres).
height – Height of the world (metres).
resolution – Planner discretisation cell size (metres/cell).
obstacle_list – Obstacle objects for Shapely collision detection.
grid – Occupancy grid (0-100) for grid-based collision detection.
world_offset – World origin (x, y) for grid indexing. When non-zero, geometry and positions are interpreted in world coordinates so grid lookups align with ObstacleMap. Default (0, 0).

width = 10#

height = 10#

resolution = 0.1#

obstacle_list = None#

grid = None#

world_offset#

property grid_resolution: tuple[float, float] | None#

Actual cell size (x_reso, y_reso) derived from grid shape and world size.

Returns None when no grid is present.

grid_occupied(x: float, y: float, margin_x: float = 0.0, margin_y: float = 0.0, threshold: float = 50.0) → bool | None[source]#

Check if any grid cell within the bounding box around (x, y) is occupied.

The bounding box extends margin_x / margin_y (in world metres) in each direction. Grid cells whose occupancy exceeds threshold are considered occupied.

Returns:: None when no grid is present (caller should fall back to Shapely or another collision method). True / False otherwise. Points outside the world bounds are treated as occupied so planners cannot escape the map.

is_collision(geometry) → bool[source]#

Check collision for a Shapely geometry against grid + obstacles.

Collision precedence:

Grid lookup when grid is not None; if occupied, collision.
When the grid reports free or is unavailable, Shapely geometry intersection with obstacle_list.

irsim.world.map#

Submodules#

Classes#

Functions#

Package Contents#

This Page