Scoring

Handles the conversion from raw per-voxel obstruction counts to a binary carving decision:

• Weight dispatch (get_weights) -- routes to the correct sky-patch weighting function based on the selected mode (Perez irradiance, heating benefit, CIE daylight luminance, or radiative cooling).
• Normalization (normalize_scores) -- rescales raw scores to [0, 1] using min-max or other strategies.
• Thresholding -- three automatic methods:
  • otsu_threshold -- minimizes intra-class variance (good general default).
  • headtail_threshold -- iterative head-tail breaks for heavy-tailed score distributions.
  • carve_fraction -- removes a fixed percentage of the scored volume.

urbansolarcarver.scoring

UrbanSolarCarver Scoring Module

Provides sky-patch weight computation and threshold selection for voxel carving.

1. get_weights(mode, device, epw_file, hoys, …) → torch.Tensor Per-patch weight vector for the specified mode. Delegates to compute_EPW_based_weights (sky_patches.py) for climate-based modes and compute_radiative_cooling_weights for radiative_cooling.

2. headtail_threshold(scores) → float Head/tail breaks (Jiang 2013): iteratively partitions right-skewed score distributions at the arithmetic mean. Well-suited for solar obstruction scores which are typically heavy-tailed.

get_weights(mode, device=torch.device('cuda'), epw_file=None, hoys=None, dew_point_celsius=10.0, bliss_k=1.8, ground_reflectance=0.2, balance_temperature=15.0, balance_offset=2.0, north_deg=0.0)

Build a vector of weights for each sky patch, according to a chosen analysis mode.

Explanation: - We represent the sky as discrete patches. This function assigns a numeric weight to each patch. - Modes include simple uniform weighting, solar irradiance, passive solar benefit, daylighting and radiative cooling. - Solar irradiance uses EPW data, Passive solar benefit uses Ladybug's method that employs a balance temp and offset. - Daylight uses CIE overcast approximation. Radiative cooling uses dew point temperature to estimate cooling potential of a night sky. Args: mode: Analysis type (e.g., 'time-based', 'irradiance', 'benefit', 'daylight', 'radiative_cooling'). device: Compute device identifier (e.g., 'cuda' or 'cpu'). epw_file: Path to weather data file; required for certain modes. hoys : Hour-of-year indices for EPW sampling. dew_point_celsius: Parameter for radiative cooling estimation. bliss_k: Angular-attenuation constant for radiative cooling. ground_reflectance: Reflectivity coefficient of ground surface. balance_temperature: Indoor-outdoor temperature threshold for comfort benefit. balance_offset: Temperature offset for comfort benefit.

Returns: Tensor of length V (number of sky patches) with the computed weight for each patch.

headtail_threshold(scores, max_iterations=10)

Head-tail breaks (Jiang, 2013): iteratively partition scores into 'head' (above mean) and 'tail' (below mean). Each iteration re-computes the mean of the head subset. The process stops when the head mean drops below the overall mean, indicating the distribution's heavy tail has been isolated. This is well-suited for right-skewed score distributions typical of solar exposure data.

Parameters:

Name	Type	Description	Default
scores	ndarray	1-D array of non-negative voxel scores.	required
max_iterations	int	Safety cap on recursion depth.	10

Returns:

Type	Description
float	Threshold value (the last computed mean).