voxcity.simulator_gpu.solar.mask

Computation Mask Utilities for Solar Irradiance Simulation

This module provides utilities for creating computation masks to limit solar irradiance calculations to specific sub-areas within the domain.

Using a computation mask can significantly speed up calculations when you only need results for a portion of the area.

Functions

create_computation_mask(→ numpy.ndarray)

Create a 2D boolean computation mask for sub-area solar calculations.

draw_computation_mask(voxcity[, zoom])

Interactive map for drawing a computation mask polygon.

get_mask_from_drawing(→ numpy.ndarray)

Create a computation mask from interactively drawn polygon(s).

visualize_computation_mask(→ Optional[numpy.ndarray])

Visualize a computation mask overlaid on the voxcity grid.

get_mask_info(→ dict)

Get information about a computation mask.

Module Contents

voxcity.simulator_gpu.solar.mask.create_computation_mask(voxcity, method: str = 'center', fraction: float = 0.5, i_range: Tuple[int, int] | None = None, j_range: Tuple[int, int] | None = None, polygon_vertices: List[Tuple[float, float]] | None = None, center: Tuple[float, float] | None = None, radius_m: float = 500.0) → numpy.ndarray[source]

Create a 2D boolean computation mask for sub-area solar calculations.

This function creates a mask that specifies which grid cells should be computed. Cells where mask is True will be calculated; cells where mask is False will be set to NaN in the output.

Parameters:

  • voxcity – VoxCity object containing voxel data and metadata

  • method – Method for creating the mask. Options: - ‘center’: Fraction-based center crop (uses fraction parameter) - ‘indices’: Direct grid index specification (uses i_range, j_range) - ‘polygon’: From geographic polygon (uses polygon_vertices) - ‘buffer’: Circular buffer around a point (uses center, radius_m) - ‘full’: No masking, compute entire area

  • fraction – For ‘center’ method, the fraction of the area to include. 0.5 means center 50% of the area. Default: 0.5

  • i_range – For ‘indices’ method, tuple of (start_i, end_i) grid indices. Indices are inclusive. If None, uses full i range.

  • j_range – For ‘indices’ method, tuple of (start_j, end_j) grid indices. Indices are inclusive. If None, uses full j range.

  • polygon_vertices – For ‘polygon’ method, list of (lon, lat) coordinates defining the polygon boundary.

  • center – For ‘buffer’ method, tuple of (lon, lat) for the center point.

  • radius_m – For ‘buffer’ method, radius in meters. Default: 500.0

Returns:

2D numpy boolean array of shape (nx, ny) where True indicates cells to compute and False indicates cells to skip.

Examples

# Center 50% of the area >>> mask = create_computation_mask(voxcity, method=’center’, fraction=0.5)

# Specific grid region >>> mask = create_computation_mask(voxcity, method=’indices’, … i_range=(100, 200), j_range=(100, 200))

# From polygon coordinates >>> mask = create_computation_mask(voxcity, method=’polygon’, … polygon_vertices=[(lon1, lat1), …])

# 500m buffer around a point >>> mask = create_computation_mask(voxcity, method=’buffer’, … center=(lon, lat), radius_m=500)

voxcity.simulator_gpu.solar.mask.draw_computation_mask(voxcity, zoom: int = 17)[source]

Interactive map for drawing a computation mask polygon.

This function displays an interactive map where users can draw a polygon to define the computation area. After drawing, call get_mask_from_drawing() with the returned polygon to create the mask.

Parameters:

  • voxcity – VoxCity object containing voxel data and metadata

  • zoom – Initial zoom level for the map. Default: 17

Returns:

(map_object, drawn_polygons)

  • map_object: ipyleaflet Map instance with drawing controls

  • drawn_polygons: List that will contain drawn polygon vertices after the user draws on the map

Return type:

tuple

Example

# Step 1: Display map and draw polygon >>> m, polygons = draw_computation_mask(voxcity) >>> display(m) # In Jupyter, draw a polygon on the map

# Step 2: After drawing, get the mask >>> mask = get_mask_from_drawing(voxcity, polygons)

# Step 3: Use the mask in solar calculation >>> solar_grid = get_global_solar_irradiance_using_epw( … voxcity, computation_mask=mask, … … )

voxcity.simulator_gpu.solar.mask.get_mask_from_drawing(voxcity, drawn_polygons: List) → numpy.ndarray[source]

Create a computation mask from interactively drawn polygon(s).

Parameters:

  • voxcity – VoxCity object containing voxel data and metadata

  • drawn_polygons – List of polygon vertices from draw_computation_mask()

Returns:

2D numpy boolean array mask

Example

>>> m, polygons = draw_computation_mask(voxcity)
>>> display(m)  # Draw polygon
>>> mask = get_mask_from_drawing(voxcity, polygons)
voxcity.simulator_gpu.solar.mask.visualize_computation_mask(voxcity, mask: numpy.ndarray, show_plot: bool = True) → numpy.ndarray | None[source]

Visualize a computation mask overlaid on the voxcity grid.

Parameters:

  • voxcity – VoxCity object

  • mask – 2D boolean mask array

  • show_plot – Whether to display the plot. Default: True

Returns:

The mask array (for chaining)

voxcity.simulator_gpu.solar.mask.get_mask_info(mask: numpy.ndarray) → dict[source]

Get information about a computation mask.

Parameters:

mask – 2D boolean mask array

Returns:

Dictionary with mask statistics