Vegetation

Configuration classes for vegetation placement.

s2gos_generator.core.config.vegetation.VegetationPlacementConfig pydantic-model

Bases: BaseModel

Configuration for multi-species vegetation placement system.

Controls how vegetation instances are distributed across the scene based on landcover classifications. Supports multiple species per landcover class.

Configuration levels: - Per-species parameters: density, scale, asset (in VegetationSpecies) - Global parameters: spacing, variation, limits (this class)

Config:

• default: {'validate_assignment': True}

Fields:

• enabled (bool)
• landcover_species_mapping (Dict[int, List[VegetationSpecies]])
• min_spacing (float)
• density_variation (float)
• max_instances_per_pixel (int)
• rotation_range (float)
• tilt_range (float)
• spillover_max_distance_m (float)
• spillover_compatibility (Dict[int, float])
• random_seed (Optional[int])
• road_exclusion (RoadExclusionConfig)

Attributes

density_variation pydantic-field

density_variation: float = 0.3

Random variation in density (±30% by default)

enabled pydantic-field

enabled: bool = True

Enable vegetation placement based on landcover data

landcover_species_mapping pydantic-field

landcover_species_mapping: Dict[
    int, List[VegetationSpecies]
]

Mapping from landcover class to list of vegetation species

max_instances_per_pixel pydantic-field

max_instances_per_pixel: int = 50

Performance limit per pixel across all species

min_spacing pydantic-field

min_spacing: float = 2.0

Global minimum spacing between any vegetation instances (meters)

random_seed pydantic-field

random_seed: Optional[int] = None

Random seed for reproducible scene generation. If None, uses system entropy.

rotation_range pydantic-field

rotation_range: float = 360.0

Random rotation range in degrees (azimuth around vertical axis)

spillover_compatibility pydantic-field

spillover_compatibility: Dict[int, float]

Default spillover compatibility map. Maps landcover class to probability 0.0-1.0. Can be overridden per species.

spillover_max_distance_m pydantic-field

spillover_max_distance_m: float = 30.0

Maximum distance (meters) for spillover from primary landcover class

tilt_range pydantic-field

tilt_range: float = 6.0

Random tilt range in degrees (±deviation from vertical for natural variation)

s2gos_generator.core.config.vegetation.VegetationSpecies pydantic-model

Bases: BaseModel

Configuration for a single vegetation species.

Defines placement parameters for a vegetation type (e.g., oak trees, shrubs). Multiple species can be assigned to the same landcover class for mixed vegetation. Instances are placed within pixels of the matched landcover class in the target area.

Config:

• default: {'validate_assignment': True}

Fields:

• name (str)
• asset_xml_paths (Union[List[PathRef], Dict[PathRef, float]])
• density_per_hectare (float)
• scale_min (float)
• scale_max (float)
• spillover_enabled (bool)
• spillover_compatibility (Optional[Dict[int, float]])

Validators:

• validate_scale_range → scale_max
• validate_asset_paths → asset_xml_paths
• resolve_asset_paths

Attributes

asset_xml_paths pydantic-field

asset_xml_paths: Union[List[PathRef], Dict[PathRef, float]]

Asset XML file path(s). Use list for uniform distribution or dict for weighted distribution

density_per_hectare pydantic-field

density_per_hectare: float

Density for this species

name pydantic-field

name: str

Species identifier (e.g., 'oak_trees', 'berry_bushes')

scale_max pydantic-field

scale_max: float

Maximum scale factor

scale_min pydantic-field

scale_min: float

Minimum scale factor

spillover_compatibility pydantic-field

spillover_compatibility: Optional[Dict[int, float]] = None

Per-species spillover compatibility map (overrides global). Maps landcover class to probability 0.0-1.0

spillover_enabled pydantic-field

spillover_enabled: bool = False

Enable spillover into adjacent compatible landcover classes

Functions

get_asset_paths_and_weights

get_asset_paths_and_weights() -> Tuple[
    List[str], List[float]
]

Get asset paths and normalized weights for selection.

Returns:

Type	Description
Tuple[List[str], List[float]]	(paths, weights) tuple ready for random.choices()

resolve_asset_paths pydantic-validator

resolve_asset_paths()

Resolve all asset XML paths using configured search paths.

This ensures all vegetation assets can be found before scene generation, providing fail-fast behavior with clear error messages.

validate_asset_paths pydantic-validator

validate_asset_paths(v)

Validate asset paths and weights.

validate_scale_range pydantic-validator

validate_scale_range(v, info)

Ensure scale_max > scale_min.

s2gos_generator.core.config.vegetation.VegetationExclusionZone pydantic-model

Bases: BaseModel

Standalone vegetation exclusion zone not tied to objects.

Defines a geographic area where vegetation placement is disabled. Geometry can be a circle, box, or arbitrary polygon.

Fields:

• zone_id (str)
• geometry (Union[CircleGeometry, BoxGeometry, PolygonGeometry])

Attributes

geometry pydantic-field

geometry: Union[
    CircleGeometry, BoxGeometry, PolygonGeometry
]

Zone geometry

zone_id pydantic-field

zone_id: str

Unique identifier for this exclusion zone

s2gos_generator.core.config.vegetation.CircleGeometry pydantic-model

Bases: BaseModel

Circular geometry definition for vegetation exclusion zones.

Coordinates can be specified in either: - Geographic coordinates (WGS84): center=(lon, lat) with coord_type="geographic" - Scene coordinates (meters from scene center): center=(x, y) with coord_type="scene"

Fields:

• type (Literal['circle'])
• center (Tuple[float, float])
• coord_type (Literal['geographic', 'scene'])
• radius (float)

Validators:

• validate_coordinate_format

Attributes

center pydantic-field

center: Tuple[float, float]

Center: (lon, lat) if geographic, (x, y) if scene

coord_type pydantic-field

coord_type: Literal['geographic', 'scene']

Coordinate system type

radius pydantic-field

radius: float

Radius in meters

Functions

validate_coordinate_format pydantic-validator

validate_coordinate_format()

Ensure coordinate format matches coord_type.

s2gos_generator.core.config.vegetation.BoxGeometry pydantic-model

Bases: BaseModel

Rectangular box geometry definition for vegetation exclusion zones.

Coordinates can be specified in either: - Geographic coordinates (WGS84): center=(lon, lat) with coord_type="geographic" - Scene coordinates (meters from scene center): center=(x, y) with coord_type="scene"

Fields:

• type (Literal['box'])
• center (Tuple[float, float])
• coord_type (Literal['geographic', 'scene'])
• width (float)
• height (float)

Validators:

• validate_coordinate_format

Attributes

center pydantic-field

center: Tuple[float, float]

Center: (lon, lat) if geographic, (x, y) if scene

coord_type pydantic-field

coord_type: Literal['geographic', 'scene']

Coordinate system type

height pydantic-field

height: float

Height in meters (north-south)

width pydantic-field

width: float

Width in meters (east-west)

Functions

validate_coordinate_format pydantic-validator

validate_coordinate_format()

Ensure coordinate format matches coord_type.

s2gos_generator.core.config.vegetation.PolygonGeometry pydantic-model

Bases: BaseModel

Polygon geometry definition for vegetation exclusion zones.

Coordinates can be specified in either: - Geographic coordinates (WGS84): coordinates=[(lon, lat), ...] with coord_type="geographic" - Scene coordinates (meters from scene center): coordinates=[(x, y), ...] with coord_type="scene"

Fields:

• type (Literal['polygon'])
• coordinates (List[Tuple[float, float]])
• coord_type (Literal['geographic', 'scene'])

Validators:

• validate_coordinate_format

Attributes

coord_type pydantic-field

coord_type: Literal['geographic', 'scene']

Coordinate system type

coordinates pydantic-field

coordinates: List[Tuple[float, float]]

Vertices: [(lon, lat), ...] if geographic, [(x, y), ...] if scene. Min 3 vertices.

Functions

validate_coordinate_format pydantic-validator

validate_coordinate_format()

Ensure coordinate format matches coord_type and vertex count.