Skip to content

Configuration

USC uses YAML files for all pipeline parameters. The configuration system supports:

  • YAML loading with recursive merging of nested dictionaries.
  • CLI overrides (-o key=value) that take precedence over file values, applied via dot-path notation.
  • Pydantic v2 validation with strict bounds checking, type coercion, and informative error messages on invalid inputs.
  • Manifest schemas for each pipeline stage, enabling re-entry at any stage.

See also: Configuration guide for user-facing parameter reference.

Config loader

urbansolarcarver.load_config

UrbanSolarCarver — Configuration loading and validation

Purpose

Read a YAML config, apply optional overrides from CLI or dicts, validate everything with Pydantic, and hand the pipeline a typed user_config. Also emits a human-readable sample YAML.

Highlights

• Strict schema: fails fast on typos or bad values • Overrides: flat "key=value" pairs or a flat mapping (the schema itself is flat) • Clear errors: aggregates Pydantic messages into one readable string • Sample writer: exports a ready-to-edit template with sane defaults

This module does not touch geometry. It only prepares inputs for the carving and meshing stages.

parse_override_value(raw)

Convert a CLI override scalar into a Python type.

Accepted literals

• "true"/"false" → bool • "null"/"none" → None • ints and floats (simple forms) • everything else stays as a string

Examples:

>>> parse_override_value("true")  # bool
True
>>> parse_override_value("3.5")   # float
3.5
>>> parse_override_value("foofoo")   # str
'foofoo'

load_config(path, overrides=None)

Load a YAML config, apply overrides, and return a validated user_config.

Parameters:

Name Type Description Default
path str

Path to the YAML file.

 required
overrides list[str] | Mapping[str, Any] | None

Optional overrides for top-level config keys (the schema is flat). • list[str]: each item is "key=value"; scalars are type-coerced, JSON lists/objects are parsed (e.g. "tilted_plane_angle_deg=[30,27,...]") • mapping : flat dict of key → value, used as-is

 None

Returns:

Type Description
UserConfig

Raises:

Type Description
FileNotFoundError

If path does not exist.
ValueError

If validation fails. The error message aggregates all Pydantic errors.
Notes

• Scalars in CLI overrides are type-coerced by parse_override_value. • The function does not mutate the YAML on disk.

Schemas

urbansolarcarver.pydantic_schemas

Pydantic schemas for YAML configuration validation and stage manifests.

Defines :class:user_config (the main pipeline configuration model), two stage manifest schemas (:class:PreprocessingManifest, :class:ThresholdingManifest), and the project-specific warning class :class:UrbanSolarCarverWarning.

All schemas use extra='forbid' so that typos in YAML keys are caught at load time rather than silently ignored.

UrbanSolarCarverWarning

Bases: UserWarning

Non-fatal configuration warning.

ThresholdSpec

Bases: BaseModel

Canonical thresholding strategy: how per-voxel scores become a mask.

Every accepted config spelling of threshold (a bare number, a strategy name, or a mapping) is normalized into this one shape at load time, so downstream stages never re-interpret raw user input.

Methods:

Name Description
* ``carve_fraction`` — remove voxels accounting for ``value`` of the

total score mass (0-1).
* ``headtail`` — head/tail breaks
* ``cutoff`` — carve voxels scoring strictly above ``value``; for the

violation-count modes this is the tolerated violation count.

UserConfig

Bases: BaseModel

PreprocessingManifest

Bases: BaseModel

Manifest written by preprocessing, read by thresholding and exporting.

ThresholdingManifest

Bases: BaseModel

Manifest written by thresholding, read by exporting.

schema_from_json(cls, text)

Deserialize a JSON string into a Pydantic model instance.

schema_to_json(model, *, indent=2)

Serialize a Pydantic model to a JSON string.