irsim.world.map.perlin_map_generator
====================================

.. py:module:: irsim.world.map.perlin_map_generator

.. autoapi-nested-parse::

   Perlin noise based 2D grid map generator for robot navigation.

   Generates procedural occupancy grids using Perlin noise. Parameter semantics
   (complexity, fill, fractal, attenuation) follow the map generation used in
   GCOPTER (https://github.com/ZJU-FAST-Lab/GCOPTER). Pure NumPy implementation.



Attributes
----------

.. autoapisummary::

   irsim.world.map.perlin_map_generator.pmap


Classes
-------

.. autoapisummary::

   irsim.world.map.perlin_map_generator.PerlinGridGenerator


Functions
---------

.. autoapisummary::

   irsim.world.map.perlin_map_generator.generate_perlin_noise


Module Contents
---------------

.. py:function:: generate_perlin_noise(width: int, height: int, complexity: float = 0.142857, fractal: int = 1, attenuation: float = 0.5, seed: int | None = None) -> numpy.ndarray

   Generate 2D Perlin noise array.

   Parameter semantics follow GCOPTER map_gen (see
   https://github.com/ZJU-FAST-Lab/GCOPTER).

   :param width: Output width in grid cells.
   :type width: int
   :param height: Output height in grid cells.
   :type height: int
   :param complexity: Base noise frequency. Default 0.142857.
   :type complexity: float
   :param fractal: Number of octave layers. Default 1. Must be >= 1.
   :type fractal: int
   :param attenuation: Amplitude for layer k is attenuation / (k + 1).
                       Default 0.5. Must be > 0.
   :type attenuation: float
   :param seed: Random seed for reproducibility.
   :type seed: int | None

   :returns: Noise array of shape (width, height), values in [0, 1].
   :rtype: np.ndarray

   :raises ValueError: If fractal < 1 or attenuation <= 0.


.. py:class:: 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: :py:obj:`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
   (https://github.com/ZJU-FAST-Lab/GCOPTER). Output can be saved as PNG
   for use with World.gen_grid_map().

   Initialize map parameters.

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


   .. py:attribute:: name
      :value: 'perlin'



   .. py:attribute:: yaml_param_names
      :value: ('complexity', 'fill', 'fractal', 'attenuation', 'seed')



   .. py:attribute:: width


   .. py:attribute:: height


   .. py:attribute:: complexity
      :value: 0.142857



   .. py:attribute:: fill
      :value: 0.38



   .. py:attribute:: fractal
      :value: 1



   .. py:attribute:: attenuation
      :value: 0.5



   .. py:attribute:: seed
      :value: None



   .. py:method:: preview(title: str = 'Perlin 2D Map', cmap: str = 'gray_r') -> None

      Preview the grid with matplotlib.



.. py:data:: pmap