voxcity.simulator_gpu.solar.mask
================================

.. py:module:: voxcity.simulator_gpu.solar.mask

.. autoapi-nested-parse::

   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
---------

.. autoapisummary::

   voxcity.simulator_gpu.solar.mask.create_computation_mask
   voxcity.simulator_gpu.solar.mask.draw_computation_mask
   voxcity.simulator_gpu.solar.mask.get_mask_from_drawing
   voxcity.simulator_gpu.solar.mask.visualize_computation_mask
   voxcity.simulator_gpu.solar.mask.get_mask_info


Module Contents
---------------

.. py:function:: create_computation_mask(voxcity, method: str = 'center', fraction: float = 0.5, i_range: Optional[Tuple[int, int]] = None, j_range: Optional[Tuple[int, int]] = None, polygon_vertices: Optional[List[Tuple[float, float]]] = None, center: Optional[Tuple[float, float]] = None, radius_m: float = 500.0) -> numpy.ndarray

   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.

   :param voxcity: VoxCity object containing voxel data and metadata
   :param 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
   :param fraction: For 'center' method, the fraction of the area to include.
                    0.5 means center 50% of the area. Default: 0.5
   :param i_range: For 'indices' method, tuple of (start_i, end_i) grid indices.
                   Indices are inclusive. If None, uses full i range.
   :param j_range: For 'indices' method, tuple of (start_j, end_j) grid indices.
                   Indices are inclusive. If None, uses full j range.
   :param polygon_vertices: For 'polygon' method, list of (lon, lat) coordinates
                            defining the polygon boundary.
   :param center: For 'buffer' method, tuple of (lon, lat) for the center point.
   :param 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.

   .. rubric:: 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)


.. py:function:: draw_computation_mask(voxcity, zoom: int = 17)

   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.

   :param voxcity: VoxCity object containing voxel data and metadata
   :param 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
   :rtype: tuple

   .. rubric:: 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, ...
   ... )


.. py:function:: get_mask_from_drawing(voxcity, drawn_polygons: List) -> numpy.ndarray

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

   :param voxcity: VoxCity object containing voxel data and metadata
   :param drawn_polygons: List of polygon vertices from draw_computation_mask()

   :returns: 2D numpy boolean array mask

   .. rubric:: Example

   >>> m, polygons = draw_computation_mask(voxcity)
   >>> display(m)  # Draw polygon
   >>> mask = get_mask_from_drawing(voxcity, polygons)


.. py:function:: visualize_computation_mask(voxcity, mask: numpy.ndarray, show_plot: bool = True) -> Optional[numpy.ndarray]

   Visualize a computation mask overlaid on the voxcity grid.

   :param voxcity: VoxCity object
   :param mask: 2D boolean mask array
   :param show_plot: Whether to display the plot. Default: True

   :returns: The mask array (for chaining)


.. py:function:: get_mask_info(mask: numpy.ndarray) -> dict

   Get information about a computation mask.

   :param mask: 2D boolean mask array

   :returns: Dictionary with mask statistics