satsim.clouds package

Cloud generation and composition helpers.

class satsim.clouds.CloudField(layers: tuple, density: ndarray, mask: ndarray, tau: ndarray, transmission: ndarray, metadata: dict)

Bases: object

Combined cloud stack with per-layer arrays and aggregate metadata.

density: ndarray

layers: tuple

mask: ndarray

metadata: dict

tau: ndarray

transmission: ndarray

class satsim.clouds.CloudGeometry(height_px: int, width_px: int, y_fov_deg: float, x_fov_deg: float, cloud_range_m: float = 3000.0, y_center_offset_m: float = 0.0, x_center_offset_m: float = 0.0)

Bases: object

Cloud-plane sampling geometry derived from the sensor FOV.

cloud_range_m: float = 3000.0

property footprint_height_m: Return the cloud-plane footprint height in meters.

property footprint_width_m: Return the cloud-plane footprint width in meters.

height_px: int

property meters_per_pixel: Return the mean cloud-plane meters per image pixel.

width_px: int

x_center_offset_m: float = 0.0

x_fov_deg: float

property x_meters_per_pixel: Return horizontal cloud-plane meters per image pixel.

y_center_offset_m: float = 0.0

y_fov_deg: float

property y_meters_per_pixel: Return vertical cloud-plane meters per image pixel.

class satsim.clouds.CloudLayer(config: CloudLayerConfig, density: ndarray, mask: ndarray, tau: ndarray, transmission: ndarray, metadata: dict)

Bases: object

Generated density, mask, optical, and metadata arrays for one layer.

config: CloudLayerConfig

density: ndarray

mask: ndarray

metadata: dict

tau: ndarray

transmission: ndarray

class satsim.clouds.CloudLayerConfig(name: str, cloud_type: str, seed: int, texture_seed: int, coverage: float, feature_scales_m: tuple, density_edge_width: float, density_floor: float, brightness: float, source_gains: dict, cloud_range: float, altitude: float, wind_speed: float, wind_direction: float, texture_contrast: float, locality_degree: int, tau_min: float, tau_max: float, tau_gamma: float, mask_threshold: float, min_feature_scale_px: float, amplitude_decay: float)

Bases: object

Validated generation and optical settings for one cloud layer.

altitude: float

amplitude_decay: float

brightness: float

cloud_range: float

cloud_type: str

coverage: float

density_edge_width: float

density_floor: float

feature_scales_m: tuple

locality_degree: int

mask_threshold: float

metadata(): Return JSON-serializable layer settings for run metadata.

min_feature_scale_px: float

name: str

seed: int

source_gains: dict

tau_gamma: float

tau_max: float

tau_min: float

texture_contrast: float

texture_seed: int

wind_direction: float

wind_speed: float

satsim.clouds.cloud_brightness_pe_from_field(cloud_field, zeropoint, exposure_s, pixel_area_arcsec2, source_components=None, return_components=False): Return per-pixel cloud glow in photoelectrons for the generated field.

satsim.clouds.cloud_field_from_config(ssp, y_pad_px=0, x_pad_px=0, layer_configs=None, y_pad_after_px=None, x_pad_after_px=None): Generate a combined cloud field from a SatSim configuration.

satsim.clouds.cloud_geometry_from_config(ssp, y_pad_px=0, x_pad_px=0, y_pad_after_px=None, x_pad_after_px=None): Return cloud-plane geometry derived from FPA size, FOV, and padding.

satsim.clouds.cloud_layers_from_config(ssp): Return normalized enabled cloud layer configs from a SatSim config.

satsim.clouds.cloud_source_brightness_pe_from_field(cloud_field, source_components=None): Return source-driven cloud glow from artificial, lunar, and solar PE fields.

satsim.clouds.crop_cloud_field(cloud_field, offset_px, height_px, width_px, pad_px=(0, 0), layer_offsets_px=None): Return an FPA-sized cloud field sampled from a padded source field.

satsim.clouds.generate_cloud_field(layer_configs, geometry): Generate and combine all enabled cloud layers for one geometry.

satsim.clouds.generate_cloud_layer(config, geometry): Generate one cloud layer density, mask, optical depth, and transmission.

satsim.clouds.parse_cloud_layers(clouds, sim_seed=None): Validate raw cloud layer objects and return CloudLayerConfig values.

Submodules

satsim.clouds.config module

Cloud configuration parsing.

satsim.clouds.config.cloud_geometry_from_config(ssp, y_pad_px=0, x_pad_px=0, y_pad_after_px=None, x_pad_after_px=None): Return cloud-plane geometry derived from FPA size, FOV, and padding.

satsim.clouds.config.cloud_layers_from_config(ssp): Return normalized enabled cloud layer configs from a SatSim config.

satsim.clouds.config.parse_cloud_layers(clouds, sim_seed=None): Validate raw cloud layer objects and return CloudLayerConfig values.

satsim.clouds.constants module

Cloud preset constants and public config surface.

satsim.clouds.field module

Cloud field composition, cropping, and brightness helpers.

satsim.clouds.field.array_stats(values): Return JSON-serializable min, max, and mean statistics for an array.

satsim.clouds.field.cloud_brightness_pe_from_field(cloud_field, zeropoint, exposure_s, pixel_area_arcsec2, source_components=None, return_components=False): Return per-pixel cloud glow in photoelectrons for the generated field.

satsim.clouds.field.cloud_layer_from_density(config, density): Build a cloud layer from normalized density and optical config.

satsim.clouds.field.cloud_source_brightness_pe_from_field(cloud_field, source_components=None): Return source-driven cloud glow from artificial, lunar, and solar PE fields.

satsim.clouds.field.combine_cloud_layers(layers): Combine cloud layers into one stacked transmission and density field.

satsim.clouds.field.crop_cloud_field(cloud_field, offset_px, height_px, width_px, pad_px=(0, 0), layer_offsets_px=None): Return an FPA-sized cloud field sampled from a padded source field.

satsim.clouds.field.normalize_unit(values): Normalize an array to the closed interval [0, 1].

satsim.clouds.field.optical_fields(density, config): Return optical depth and transmission arrays for a cloud density field.

satsim.clouds.field.sample_bilinear(values, start_y, start_x, height, width): Sample a rectangular view from values using bilinear interpolation.

satsim.clouds.field.smoothstep(values, edge0, edge1): Apply cubic Hermite interpolation between two scalar edges.

satsim.clouds.generation module

Cloud texture generation.

satsim.clouds.generation.active_feature_scales_m(config, geometry): Return texture scales that are resolvable for the current pixel size.

satsim.clouds.generation.cloud_density_from_noise(noise, coverage, edge_width, density_floor, mask_threshold=0.02)

Map normalized procedural noise into normalized cloud density.

coverage targets the realized mask fraction after edge softening. For floored layers, it targets the above-floor support while baseline attenuation keeps the mask full-frame. mask_threshold is the density cutoff used when building the layer mask.

satsim.clouds.generation.cloud_field_from_config(ssp, y_pad_px=0, x_pad_px=0, layer_configs=None, y_pad_after_px=None, x_pad_after_px=None): Generate a combined cloud field from a SatSim configuration.

satsim.clouds.generation.cloud_texture(config, geometry): Return a normalized procedural texture for one cloud layer.

satsim.clouds.generation.generate_cloud_field(layer_configs, geometry): Generate and combine all enabled cloud layers for one geometry.

satsim.clouds.generation.generate_cloud_layer(config, geometry): Generate one cloud layer density, mask, optical depth, and transmission.

satsim.clouds.generation.layer_geometry(config, geometry): Return geometry rescaled for a layer-specific cloud range.

satsim.clouds.generation.noise_grid(seed, xs, ys): Return an OpenSimplex noise grid with SatSim row/column orientation.

satsim.clouds.generation.open_simplex_fractal(geometry, feature_scales_m, seed, amplitude_decay): Generate a multi-scale OpenSimplex texture over the cloud plane.

satsim.clouds.models module

Cloud data models.

class satsim.clouds.models.CloudField(layers: tuple, density: ndarray, mask: ndarray, tau: ndarray, transmission: ndarray, metadata: dict)

Bases: object

Combined cloud stack with per-layer arrays and aggregate metadata.

density: ndarray

layers: tuple

mask: ndarray

metadata: dict

tau: ndarray

transmission: ndarray

class satsim.clouds.models.CloudGeometry(height_px: int, width_px: int, y_fov_deg: float, x_fov_deg: float, cloud_range_m: float = 3000.0, y_center_offset_m: float = 0.0, x_center_offset_m: float = 0.0)

Bases: object

Cloud-plane sampling geometry derived from the sensor FOV.

cloud_range_m: float = 3000.0

property footprint_height_m: Return the cloud-plane footprint height in meters.

property footprint_width_m: Return the cloud-plane footprint width in meters.

height_px: int

property meters_per_pixel: Return the mean cloud-plane meters per image pixel.

width_px: int

x_center_offset_m: float = 0.0

x_fov_deg: float

property x_meters_per_pixel: Return horizontal cloud-plane meters per image pixel.

y_center_offset_m: float = 0.0

y_fov_deg: float

property y_meters_per_pixel: Return vertical cloud-plane meters per image pixel.

class satsim.clouds.models.CloudLayer(config: CloudLayerConfig, density: ndarray, mask: ndarray, tau: ndarray, transmission: ndarray, metadata: dict)

Bases: object

Generated density, mask, optical, and metadata arrays for one layer.

config: CloudLayerConfig

density: ndarray

mask: ndarray

metadata: dict

tau: ndarray

transmission: ndarray

class satsim.clouds.models.CloudLayerConfig(name: str, cloud_type: str, seed: int, texture_seed: int, coverage: float, feature_scales_m: tuple, density_edge_width: float, density_floor: float, brightness: float, source_gains: dict, cloud_range: float, altitude: float, wind_speed: float, wind_direction: float, texture_contrast: float, locality_degree: int, tau_min: float, tau_max: float, tau_gamma: float, mask_threshold: float, min_feature_scale_px: float, amplitude_decay: float)

Bases: object

Validated generation and optical settings for one cloud layer.

altitude: float

amplitude_decay: float

brightness: float

cloud_range: float

cloud_type: str

coverage: float

density_edge_width: float

density_floor: float

feature_scales_m: tuple

locality_degree: int

mask_threshold: float

metadata(): Return JSON-serializable layer settings for run metadata.

min_feature_scale_px: float

name: str

seed: int

source_gains: dict

tau_gamma: float

tau_max: float

tau_min: float

texture_contrast: float

texture_seed: int

wind_direction: float

wind_speed: float