fimama.configuration

  1"""
  2Configuration classes and extensions to Pydantic BaseModel.
  3"""
  4
  5import logging
  6
  7from pydantic import BaseModel, ConfigDict, model_validator
  8
  9_logger = logging.getLogger('patkit.base_model_extensions')
 10
 11
 12class FimamaModel(BaseModel):
 13    """
 14    The extended Pydantic BaseModel for fimama.
 15
 16    This BaseModel which accepts empty strings for any field as None.
 17
 18    This BaseModel which can be updated with new data. The update will trigger
 19    validation again.
 20
 21    Additionally, trying to parse undefined fields will raise an exception.
 22    """
 23
 24    model_config = ConfigDict(extra="forbid")
 25
 26    @model_validator(mode="before")
 27    @classmethod
 28    def empty_str_to_none(cls, input_string: str) -> str | None:
 29        """
 30        Validate empty strings to None, but non-empties to themselves.
 31
 32        Parameters
 33        ----------
 34        input_string : str
 35            String to be validated.
 36
 37        Returns
 38        -------
 39        Optional[str]
 40            None for empty string, otherwise the string itself.
 41        """
 42        if input_string == '':
 43            input_string = None
 44        return input_string
 45
 46    def update(self, data: dict) -> 'FimamaModel':
 47        """
 48        Update the BaseModel with the contents of data and validate.
 49
 50        The update does not happen in place but rather a new updated object is
 51        returned and updating triggers validation.
 52
 53        Parameters
 54        ----------
 55        data : dict
 56            Only valid key, value pairs are accepted.
 57
 58        Returns
 59        -------
 60        UpdatableBaseModel
 61            The updated BaseModel.
 62        """
 63        update = self.model_dump()
 64        update.update(data)
 65        new_dict = self.model_validate(
 66            update).model_dump(exclude_defaults=True)
 67        for key, value in new_dict.items():
 68            _logger.debug(
 69                "Updating value of '%s' from '%s' to '%s'.",
 70                str(key), str(getattr(self, key, None)), str(value))
 71            setattr(self, key, value)
 72        return self
 73
 74
 75class PerlinParameters(FimamaModel):
 76    """
 77    Parameters for generating a heightmap with Perlin noise.
 78
 79    Apart from `scale` these are parameters of the `noise.pnoise2` function.
 80
 81    Parameters
 82    ----------
 83        scale : float
 84            Factor to zoom into the noise field by. Small values will produce a
 85            very densely noisy map, by default 100.0.
 86        octaves: int
 87            The number of passes for generating fractional Brownian motion
 88            (fBm) noise, by default 6.
 89        persistence: float
 90            The amplitude of each successive octave relative to the one below
 91            it. Note the amplitude of the first pass is always 1.0. Defaults to
 92            0.5 (each higher octave's amplitude is halved).
 93        lacunarity: float
 94            The frequency of each successive octave relative to the one below
 95            it, similar to persistence. Defaults to 2.0.
 96        base: int
 97            Fixed offset for the input coordinates. Useful for generating
 98            different noise textures with the same repeat interval, by default
 99            42.
100    """
101    scale: float = 100.0
102    octaves: int = 6
103    persistence: float = 0.5
104    lacunarity: float = 2.0
105    base: int = 42
106
107
108class VoronoiConfiguration(FimamaModel):
109    """
110    Configuration for plotting elements of the Voronoi grid.
111
112    Note that these parameters do not affect drawing the Voronoi cell polygons.
113    Their plotting is controlled by configuration for drawing the heightmap.
114
115    Parameters
116    ----------
117        plot_voronoi_grid: bool
118            Should any part of the grid be plotted, if set to False, none of
119            the elements get plotted regardless of the parameter values, by
120            default False.
121        show_ridges: bool
122            Should the perimeter of the polygons - the Voronoi ridges - be
123            plotted, by default True.
124        show_vertices: bool
125            Should the vertices, or intersections of the ridges, be plotted, by
126            default False.
127        show_points: bool
128            Should the points that the Voronoi grid is based on be plotted, by
129            default False.
130    """
131    plot_voronoi_grid: bool = False
132    show_ridges: bool = True
133    show_vertices: bool = False
134    show_points: bool = False
135
136
137class MapConfiguration(FimamaModel):
138    """
139    Map generation configuration.
140
141    Parameters
142    ----------
143        height: int
144            Height of the map in cells, by default 125.
145        width: int
146            Width of the map in cells, by default 200.
147        generator: str
148            Which generator to use for the heightmap, by default "perlin".
149        colormap_name: str
150            Name of the colormap to use for displaying the heightmap, by
151            default "dark-atlas".
152        perlin_parameters: `PerlinParameters` | None
153            Parameters for generating a heightmap with Perlin noise, by default
154            None.
155        voronoi_configuration: `VoronoiConfiguration` | None
156            Parameters for plotting the Voronoi grid (not the voronoi polygons,
157            but rather associated edges and points), by default None.
158    """
159    height: int = 125
160    width: int = 200
161    generator: str = "perlin"
162    colormap_name: str = "dark-atlas"
163    perlin_parameters: PerlinParameters | None = None
164    voronoi_configuration: VoronoiConfiguration | None = None