irsim.world.map#

Submodules#

Classes#

`GridMapGenerator`	Abstract base for procedural grid map generators.
`ImageGridGenerator`	Load obstacle grid from an image file (path).
`ObstacleMap`	Static obstacle object backed by map line segments and optional grid data.
`PerlinGridGenerator`	Perlin noise based 2D occupancy grid map.
`EnvGridMap`	Structural type accepted by all path planners.
`Map`	Map data container for navigation / path-planning.
`FogMap`	Fog-of-map overlay grid, built on `Map`.

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

Static obstacle object backed by map line segments and optional grid data.

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#

world_offset#

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.

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

Bases: irsim.world.map.Map

Fog-of-map overlay grid, built on Map.

Every cell starts unexplored (covered by fog). A robot’s lidar reveals cells along each beam’s line of sight, so the explored region grows as the robot navigates. The overlay is rendered as a grey layer that is opaque where unexplored and transparent where explored, so the underlying obstacle map shows through only once an area has been seen (free space appears white, obstacles black, the unknown stays grey).

The explored mask is updated regardless of whether a display is active, so it is also usable headless as an exploration observation or coverage metric.

Initialize the fog grid.

Parameters:

width – Width of the world (metres) — matches the world it covers.
height – Height of the world (metres).
resolution – Fog cell size (metres/cell). Finer is smoother but heavier; coarser is faster.
world_offset – World origin (x, y) for cell indexing.

Raises:

ValueError – If resolution is not positive and finite (it is user-configurable via fog_map_resolution).

explored#

property shape: tuple[int, int]#: Grid shape (nx, ny) (cells along x and y).

property explored_ratio: float#: Fraction of the world revealed so far, in [0, 1].

reset() → None[source]#: Re-cover the whole world with fog.

reveal_from_lidar(origin: numpy.ndarray | list[float], angles: numpy.ndarray | list[float], ranges: numpy.ndarray | list[float]) → None[source]#

Reveal cells along each lidar beam’s line of sight.

Parameters:

origin – Lidar world pose [x, y, theta] (theta optional).
angles – Per-beam angles in the lidar’s local frame (radians).
ranges – Per-beam measured ranges (metres), aligned with angles.

reveal_fov(origin: numpy.ndarray | list[float], fov: float, fov_radius: float) → None[source]#

Reveal every cell within a field-of-view sector (no occlusion).

Used when a sensing object has no lidar: each cell within fov_radius of the origin and within ±fov/2 of the object’s heading is revealed.

Parameters:

origin – Object world pose [x, y, theta] (theta optional).
fov – Full field-of-view angle in radians (2*pi is a full circle).
fov_radius – View range in metres.

to_rgba(color: tuple[float, float, float] = (0.78, 0.78, 0.8), alpha: float = 1.0) → numpy.ndarray[source]#

RGBA image of the fog for rendering.

Unexplored cells get color at alpha (a soft light grey, opaque by default so the fog still fully hides the map until seen); explored cells are fully transparent so the underlying map shows through. Shape is (nx, ny, 4) (transpose the first two axes for imshow).

The buffer is allocated once and reused: the constant RGB channels are filled on the first call, and only the alpha channel is recomputed (the only thing that changes as cells are revealed).

plot_clear() → None[source]#: Remove the fog overlay artist.