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)[源代码]#

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, ...] = ()#

generate() → GridMapGenerator[源代码]#: 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[源代码]#: Save grid as grayscale PNG for use with World.gen_grid_map().

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

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

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)[源代码]#

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.

参数:

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[源代码]#

Check collision using grid array lookup.

参数:: geometry -- Shapely geometry object to check collision for.
返回:: True if collision detected, False otherwise.
返回类型:: bool

is_collision(geometry) → bool[源代码]#: 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)[源代码]#

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.

参数:

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[源代码]#: Preview the grid with matplotlib.

class irsim.world.map.EnvGridMap[源代码]#

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[源代码]#: Check if any grid cell within the bounding box is occupied.

is_collision(geometry) → bool[源代码]#: 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.

返回:: 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[源代码]#

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.

参数:

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

返回:

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)[源代码]#

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.

参数:

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[源代码]#

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.

返回:: 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[源代码]#

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)[源代码]#

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.

参数:

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.

抛出:

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[源代码]#: 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[源代码]#

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

参数:

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[源代码]#

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.

参数:

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[源代码]#

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[源代码]#: Remove the fog overlay artist.