Assets & Regions

Configuration classes for scene assets including user-defined objects, material regions, and material mappings.

s2gos_generator.core.config.assets.UserAssets pydantic-model

Bases: BaseModel

User assets to be placed on scene.

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

Config:

• default: {'validate_assignment': True}

Fields:

• object_id (str)
• ply_path (PathRef)
• coordinate (list[float])
• coord_type (Literal['geographic', 'scene'])
• material (Union[str, Dict[str, Any]])
• elevation_offset (float)
• scale (float)
• rotation_x (float)
• rotation_y (float)
• rotation_z (float)
• blender_fix (bool)
• face_normals (Optional[bool])
• exclusion_zone (Optional[Union[float, Tuple[float, float]]])

Validators:

• validate_coordinate → coordinate
• validate_ply_path → ply_path
• validate_material → material
• validate_scale → scale
• validate_coordinate_format

Attributes

blender_fix pydantic-field

blender_fix: bool = False

Informs as to whether a 90 degree around x was added to adjust from blender, useful to know what the actual rotation intended was

coord_type pydantic-field

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

Coordinate system type

coordinate pydantic-field

coordinate: list[float]

Coordinates: [lon, lat] if geographic, [x, y] if scene

elevation_offset pydantic-field

elevation_offset: float = 0.0

Height offset above terrain surface in meters

exclusion_zone pydantic-field

exclusion_zone: Optional[
    Union[float, Tuple[float, float]]
] = None

Vegetation exclusion zone centered on this object. Can be: - float: Circular radius in meters - (width, height): Rectangular box in meters

face_normals pydantic-field

face_normals: Optional[bool] = None

Mitsuba PLY face normals setting: True=smooth normals, False=per-face normals, None=use PLY file defaults

material pydantic-field

material: Union[str, Dict[str, Any]]

Material reference (string ID) or inline material definition dict

object_id pydantic-field

object_id: str

Unique identifier for the object

ply_path pydantic-field

ply_path: PathRef

Path to PLY file containing 3D object geometry

rotation_x pydantic-field

rotation_x: float = 0.0

Rotation around X-axis in degrees

rotation_y pydantic-field

rotation_y: float = 0.0

Rotation around Y-axis in degrees

rotation_z pydantic-field

rotation_z: float = 0.0

Rotation around Z-axis in degrees

scale pydantic-field

scale: float = 1.0

Uniform scaling factor for the object

Functions

get_inline_material_dict

get_inline_material_dict() -> Optional[Dict[str, Any]]

Return inline material definition if present, else None.

get_inline_material_id

get_inline_material_id() -> Optional[str]

Return generated material ID for inline materials, None otherwise.

validate_coordinate pydantic-validator

validate_coordinate(v)

Validate coordinate format.

validate_coordinate_format pydantic-validator

validate_coordinate_format()

Ensure coordinate format matches coord_type.

validate_material pydantic-validator

validate_material(v)

Validate material is either a non-empty string reference or a valid dict definition.

validate_ply_path pydantic-validator

validate_ply_path(v)

Validate and resolve PLY file path using configured search paths.

validate_scale pydantic-validator

validate_scale(v)

Validate scale is positive.

s2gos_generator.core.config.assets.HamsterConfig pydantic-model

Bases: BaseModel

HAMSTER albedo data configuration for baresoil material replacement.

Config:

• default: {'arbitrary_types_allowed': True}

Fields:

• enabled (bool)
• data_path (PathRef)
• variable_name (str)
• fallback_on_error (bool)

Validators:

• validate_data_path → data_path

Attributes

data_path pydantic-field

data_path: PathRef

Path to HAMSTER NetCDF data file

enabled pydantic-field

enabled: bool = True

Enable HAMSTER albedo for baresoil

fallback_on_error pydantic-field

fallback_on_error: bool = True

Fall back to standard baresoil material on errors

variable_name pydantic-field

variable_name: str = 'albedo'

Variable name in NetCDF file

Functions

validate_data_path pydantic-validator

validate_data_path(v)

Validate HAMSTER data file exists.

s2gos_generator.core.config.assets.XmlSceneConfig pydantic-model

Bases: BaseModel

Configuration for importing assets and materials from XML scene files.

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

Config:

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

Fields:

• xml_path (PathRef)
• base_coordinate (Tuple[float, float])
• coord_type (Literal['geographic', 'scene'])
• object_id_prefix (Optional[str])
• elevation_offset (float)
• scale (float)
• fix_blender_coords (bool)
• rotation_x (float)
• rotation_y (float)
• rotation_z (float)
• material_mappings (list[MaterialMapping])
• validate_materials (bool)
• exclusion_zone (Optional[Union[float, Tuple[float, float]]])

Validators:

• validate_xml_path → xml_path
• validate_base_coordinate → base_coordinate
• validate_coordinate_format

Attributes

base_coordinate pydantic-field

base_coordinate: Tuple[float, float]

Base coordinates: (lon, lat) if geographic, (x, y) if scene

coord_type pydantic-field

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

Coordinate system type

elevation_offset pydantic-field

elevation_offset: float = 0.0

Global elevation offset for all assets in meters

exclusion_zone pydantic-field

exclusion_zone: Optional[
    Union[float, Tuple[float, float]]
] = None

Vegetation exclusion zone centered on base_coordinate for this XML scene. Can be: - float: Circular radius in meters - (width, height): Rectangular box in meters

fix_blender_coords pydantic-field

fix_blender_coords: bool = True

Apply Blender coordinate system correction (90° rotation around X-axis)

material_mappings pydantic-field

material_mappings: list[MaterialMapping]

List of material mappings for mesh filename patterns

object_id_prefix pydantic-field

object_id_prefix: Optional[str] = None

Prefix for asset object IDs

rotation_x pydantic-field

rotation_x: float = 0.0

Global rotation around X-axis in degrees (applied after fix_blender_coords)

rotation_y pydantic-field

rotation_y: float = 0.0

Global rotation around Y-axis in degrees (applied after fix_blender_coords)

rotation_z pydantic-field

rotation_z: float = 0.0

Global rotation around Z-axis in degrees (applied after fix_blender_coords)

scale pydantic-field

scale: float = 1.0

Global scaling factor for all assets

validate_materials pydantic-field

validate_materials: bool = True

Validate that all materials are properly defined

xml_path pydantic-field

xml_path: PathRef

Path to XML scene file

Functions

validate_base_coordinate pydantic-validator

validate_base_coordinate(v)

Validate coordinate format.

validate_coordinate_format pydantic-validator

validate_coordinate_format()

Ensure coordinate format matches coord_type.

validate_xml_path pydantic-validator

validate_xml_path(v)

Validate and resolve XML file path using configured search paths.

s2gos_generator.core.config.assets.MaterialRegion pydantic-model

Bases: BaseModel

Material region for spatially-selective material overrides.

Defines a spatial region where the terrain material will be overridden with a specified material. Supports rectangle and polygon geometry types in both geographic (WGS84) and scene coordinate systems.

Used in SceneGenConfig via the material_regions field. The material_name must reference a Material known to the scene.

Fields:

• region_id (str)
• geometry (Dict[str, Any])
• material_name (str)
• priority (int)
• applies_to (List[Literal['target', 'buffer', 'background']])
• landcover_filter (Optional[List[int]])

Validators:

• validate_region_id → region_id
• validate_material_name → material_name
• validate_applies_to → applies_to
• validate_landcover_filter → landcover_filter

Attributes

applies_to pydantic-field

applies_to: List[
    Literal["target", "buffer", "background"]
] = ["target"]

Which scene areas this region applies to (target/buffer/background)

geometry pydantic-field

geometry: Dict[str, Any]

Region geometry specification. Supported types: rectangle and polygon.

landcover_filter pydantic-field

landcover_filter: Optional[List[int]] = None

Optional ESA WorldCover class filter. If specified, only override pixels matching these landcover classes. If None, override all pixels. Example: [60, 80] = only bare/sparse vegetation

material_name pydantic-field

material_name: str

Material reference to apply in this region (must exist in materials)

priority pydantic-field

priority: int = 0

Priority for overlapping regions (higher priority wins). Default is 0.

region_id pydantic-field

region_id: str

Unique identifier for this region

Functions

validate_applies_to pydantic-validator

validate_applies_to(v)

Ensure at least one area is specified.

validate_landcover_filter pydantic-validator

validate_landcover_filter(v)

Validate landcover class codes.

validate_material_name pydantic-validator

validate_material_name(v)

Validate material reference.

validate_region_id pydantic-validator

validate_region_id(v)

Validate region ID is non-empty and valid for filenames.

s2gos_generator.core.config.assets.MaterialMapping pydantic-model

Bases: BaseModel

Material mapping for XML assets.

Maps mesh filenames to material IDs using pattern matching.

Attributes:

Name	Type	Description
pattern	str	Filename pattern to match (without .ply extension)
material	str	Material ID to assign to matching meshes
mode	Literal['glob', 'regex']	Pattern matching mode ('glob' or 'regex')

Config:

• default: {'validate_assignment': True}

Fields:

• pattern (str)
• material (str)
• mode (Literal['glob', 'regex'])

Validators:

• validate_pattern → pattern
• validate_material → material

Attributes

material pydantic-field

material: str

Material ID to assign to matching meshes

mode pydantic-field

mode: Literal['glob', 'regex'] = 'glob'

Pattern matching mode: 'glob' for wildcards (* and ?), 'regex' for regular expressions

pattern pydantic-field

pattern: str

Filename pattern to match (e.g., 'vegetation_' or 'tree_.')

Functions

validate_material pydantic-validator

validate_material(v: str) -> str

Validate material reference is non-empty.

validate_pattern pydantic-validator

validate_pattern(v: str) -> str

Validate pattern is non-empty.