Scene Configuration

Top-level configuration classes for defining a scene generation run.

s2gos_generator.core.config.scene.SceneGenConfig pydantic-model

Bases: BaseModel

Comprehensive scene generation configuration.

Provides a validated configuration system for all scene generation parameters. Pass an instance to SceneGenerationPipeline and call run() to produce a SceneDescription.

Optional spatial zones are controlled by BufferConfig and BackgroundConfig. Vegetation placement is configured via VegetationPlacementConfig.

Config:

• default: {'validate_assignment': True, 'arbitrary_types_allowed': True}

Fields:

• config_version (str)
• scene_name (str)
• description (Optional[str])
• location (SceneLocation)
• data_sources (DataSources)
• output_dir (PathRef)
• dem_resolution_m (float)
• landcover_resolution_m (float)
• texture_resolution_m (Optional[float])
• snow (Optional[SnowConfig])
• processing (ProcessingOptions)
• atmosphere (AtmosphereConfig)
• buffer (Optional[BufferConfig])
• background (Optional[BackgroundConfig])
• hamster (Optional[HamsterConfig])
• roads (Optional[RoadsConfig])
• spectral_matching (Optional[SpectralMatchingConfig])
• buildings (Optional[BuildingsConfig])
• mesh_refinement (Optional[MeshRefinementConfig])
• user_assets (list[UserAssets])
• xml_scenes (list[XmlSceneConfig])
• material_regions (list[MaterialRegion])
• region_material_defs (Dict[str, Dict[str, Any]])
• vegetation_placement (Optional[VegetationPlacementConfig])
• vegetation_exclusion_zones (List[VegetationExclusionZone])
• created_at (datetime)

Validators:

• validate_output_dir → output_dir
• validate_scene_config

Attributes

atmosphere pydantic-field

atmosphere: AtmosphereConfig

Atmosphere configuration

background pydantic-field

background: Optional[BackgroundConfig] = None

Background area configuration (None disables background). See BackgroundConfig.

buffer pydantic-field

buffer: Optional[BufferConfig] = None

Buffer area configuration (None disables buffer). See BufferConfig.

buildings pydantic-field

buildings: Optional[BuildingsConfig] = None

Building configuration (None disables buildings). See BuildingsConfig.

config_version pydantic-field

config_version: str

Configuration schema version

created_at pydantic-field

created_at: datetime

Configuration creation time

data_dir property

data_dir: PathRef

Get the data output directory.

data_sources pydantic-field

data_sources: DataSources

Data source configuration

dem_resolution_m pydantic-field

dem_resolution_m: float = 30.0

DEM resolution in meters (controls terrain mesh detail)

description pydantic-field

description: Optional[str] = None

Metadata, only used in case of serialization

hamster pydantic-field

hamster: Optional[HamsterConfig] = None

HAMSTER albedo data configuration for baresoil. See HamsterConfig.

landcover_resolution_m pydantic-field

landcover_resolution_m: float = 30.0

Landcover resolution in meters

location pydantic-field

location: SceneLocation

Geographic location

material_regions pydantic-field

material_regions: list[MaterialRegion] = []

Material regions for spatially-selective material overrides. See MaterialRegion.

mesh_refinement pydantic-field

mesh_refinement: Optional[MeshRefinementConfig] = None

Adaptive mesh refinement configuration (None disables refinement). See MeshRefinementConfig.

meshes_dir property

meshes_dir: PathRef

Get the meshes output directory.

output_dir pydantic-field

output_dir: PathRef

Output directory for generated scene

processing pydantic-field

processing: ProcessingOptions

Processing options

region_material_defs pydantic-field

region_material_defs: Dict[str, Dict[str, Any]]

Material definitions for region materials

roads pydantic-field

roads: Optional[RoadsConfig] = None

Road infrastructure configuration (None disables roads). See RoadsConfig.

scene_name pydantic-field

scene_name: str

Scene name (used for output files)

scene_output_dir property

scene_output_dir: PathRef

Get the specific output directory for this scene.

snow pydantic-field

snow: Optional[SnowConfig] = None

Seasonal snow configuration (None disables snow). See SnowConfig.

spectral_matching pydantic-field

spectral_matching: Optional[SpectralMatchingConfig] = None

Spectral matching configuration (None disables). See SpectralMatchingConfig.

texture_resolution_m pydantic-field

texture_resolution_m: Optional[float] = None

Texture resolution in meters per pixel. When set finer than landcover_resolution_m, roads and landcover are rasterized at higher pixel density, reducing road blockiness. Defaults to native landcover resolution when None.

textures_dir property

textures_dir: PathRef

Get the textures output directory.

user_assets pydantic-field

user_assets: list[UserAssets] = []

User assets to be placed in generated scene. See UserAssets.

vegetation_exclusion_zones pydantic-field

vegetation_exclusion_zones: List[VegetationExclusionZone]

Standalone vegetation exclusion zones

vegetation_placement pydantic-field

vegetation_placement: Optional[
    VegetationPlacementConfig
] = None

Vegetation placement configuration (None disables vegetation). See VegetationPlacementConfig.

xml_scenes pydantic-field

xml_scenes: list[XmlSceneConfig] = []

XML scene files to import for additional assets and materials. See XmlSceneConfig.

Functions

disable_hamster_albedo

disable_hamster_albedo()

Disable HAMSTER albedo system.

enable_hamster_albedo

enable_hamster_albedo(
    data_path: PathRef,
    variable_name: str = "albedo",
    fallback_on_error: bool = True,
)

Enable HAMSTER albedo data for baresoil material replacement.

Parameters:

Name	Type	Description	Default
data_path	PathRef	Path to HAMSTER NetCDF data file	required
variable_name	str	Variable name in NetCDF file (default: "albedo")	'albedo'
fallback_on_error	bool	Fall back to standard baresoil material on errors	True

from_json classmethod

from_json(path: PathRef) -> SceneGenConfig

Load from JSON file.

set_atmosphere_heterogeneous

set_atmosphere_heterogeneous(
    molecular_config=None, particle_layers=None
)

Set atmosphere using heterogeneous configuration with molecular and particle layers.

set_atmosphere_homogeneous

set_atmosphere_homogeneous(
    aerosol_dataset,
    optical_thickness: float = 0.1,
    scale_height: float = 1000.0,
)

Set atmosphere using homogeneous configuration.

set_atmosphere_molecular

set_atmosphere_molecular(molecular_config)

Set atmosphere using molecular configuration.

to_dict

to_dict() -> Dict[str, Any]

Convert to dictionary for serialization.

to_json

to_json(
    path: Optional[PathRef] = None, indent: int = 2
) -> str

Export to JSON format.

validate_output_dir pydantic-validator

validate_output_dir(v)

Validate and create output directory if needed.

validate_scene_config pydantic-validator

validate_scene_config()

Validate complete scene configuration.

s2gos_generator.core.config.scene.SceneLocation pydantic-model

Bases: BaseModel

Geographic location configuration.

Fields:

• center_lat (float)
• center_lon (float)
• aoi_size_km (float)

Attributes

aoi_size_km pydantic-field

aoi_size_km: float

Area of interest size in kilometers

center_lat pydantic-field

center_lat: float

Center latitude in degrees

center_lon pydantic-field

center_lon: float

Center longitude in degrees

s2gos_generator.core.config.scene.BufferConfig pydantic-model

Bases: BaseModel

Buffer area configuration. Presence (non-None) enables buffer processing.

Fields:

• size_km (float)
• resolution_m (float)

Attributes

resolution_m pydantic-field

resolution_m: float = 100.0

Buffer resolution in meters

size_km pydantic-field

size_km: float = 60.0

Buffer size in kilometers

s2gos_generator.core.config.scene.BackgroundConfig pydantic-model

Bases: BaseModel

Background area configuration. Presence (non-None) enables background processing.

Fields:

• size_km (float)
• resolution_m (float)
• elevation (float)

Attributes

elevation pydantic-field

elevation: float = 0.0

Background elevation in meters

resolution_m pydantic-field

resolution_m: float = 200.0

Background resolution in meters

size_km pydantic-field

size_km: float = 200.0

Background area size in kilometers

s2gos_generator.core.config.scene.SnowConfig pydantic-model

Bases: BaseModel

Seasonal snow configuration. Presence (non-None) enables snow.

Fields:

• season_month (Month)
• material_index (int)
• thermoprops (Optional[ThermophysicalConfig])
• random_seed (Optional[int])

Attributes

material_index pydantic-field

material_index: int = 6

Material index to use for snow coverage

random_seed pydantic-field

random_seed: Optional[int] = None

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

season_month pydantic-field

season_month: Month

Month for seasonal snow calculation (JUNE or DECEMBER)

thermoprops pydantic-field

thermoprops: Optional[ThermophysicalConfig] = None

Optional CAMS thermoprops for snow temperature calculation. If None, uses synthetic temperature model.

s2gos_generator.core.config.scene.DataSources pydantic-model

Bases: BaseModel

Data source configuration using FileResolver.

Fields:

• dem (IndexedGeoTiff | Zarr)
• landcover (IndexedGeoTiff | Zarr)
• material_config_path (PathRef)
• building_tiles (Optional[PathRef])

Validators:

• _load_defaults_and_merge_overrides
• validate_path_exists → material_config_path, building_tiles

Attributes

building_tiles pydantic-field

building_tiles: Optional[PathRef] = None

Directory of quadkey-indexed OpenBuildingMap tiles (plus index CSV).

dem pydantic-field

dem: IndexedGeoTiff | Zarr

DEM Dataset

landcover pydantic-field

landcover: IndexedGeoTiff | Zarr

Landcover Dataset

material_config_path pydantic-field

material_config_path: PathRef

Path to custom material configuration JSON

Functions

validate_path_exists pydantic-validator

validate_path_exists(v)

Validate that local files or directories exist (optional fields skip None).

s2gos_generator.core.config.scene.ProcessingOptions pydantic-model

Bases: BaseModel

Processing options for scene generation.

Fields:

• generate_texture_preview (bool)
• handle_dem_nans (bool)
• dem_fillna_value (float)
• flatten_dem (bool)

Attributes

dem_fillna_value pydantic-field

dem_fillna_value: float = 0.0

Fill value for DEM NaN values

flatten_dem pydantic-field

flatten_dem: bool = False

Flatten DEM to zero elevation for testing

generate_texture_preview pydantic-field

generate_texture_preview: bool = True

Generate texture preview images

handle_dem_nans pydantic-field

handle_dem_nans: bool = True

Handle NaN values in DEM data

s2gos_generator.core.config.scene.Month

Bases: str, Enum

Month selection for seasonal adjustments.

s2gos_generator.core.config.scene.create_scene_config

create_scene_config(
    scene_name: str,
    center_lat: float,
    center_lon: float,
    aoi_size_km: float,
    output_dir: PathRef,
    dem_resolution_m: float = 30.0,
    landcover_resolution_m: float = 10.0,
    description: Optional[str] = None,
    data_overrides: Optional[dict] = None,
    atmosphere: Optional[AtmosphereConfig] = None,
    **kwargs,
) -> SceneGenConfig

Scene generation configuration using PathResolver.

Parameters:

Name	Type	Description	Default
scene_name	str	Scene name (used for output files)	required
center_lat	float	Center latitude in degrees	required
center_lon	float	Center longitude in degrees	required
aoi_size_km	float	Area of interest size in kilometers	required
output_dir	PathRef	Output directory for generated scene	required
dem_resolution_m	float	DEM resolution in meters (default: 30.0)	30.0
landcover_resolution_m	float	Landcover resolution in meters (default: 30.0)	10.0
description	Optional[str]	Optional scene description	None
data_overrides	Optional[dict]	Optional dict with user data overrides: - dem_index: Custom DEM index file - landcover_index: Custom landcover index file - materials_config: Custom materials config file	None
atmosphere	Optional[AtmosphereConfig]	Optional atmosphere configuration	None
**kwargs		Additional configuration options	{}