voxcity.geoprocessor.surface_meta
=================================

.. py:module:: voxcity.geoprocessor.surface_meta

.. autoapi-nested-parse::

   Pure helpers for building surface face classification and metadata.

   No Pydantic or app imports — keeps this module portable for subprocess use.



Attributes
----------

.. autoapisummary::

   voxcity.geoprocessor.surface_meta.SELECTABLE_KINDS


Functions
---------

.. autoapisummary::

   voxcity.geoprocessor.surface_meta.make_surface_face_key
   voxcity.geoprocessor.surface_meta.classify_surface_kind
   voxcity.geoprocessor.surface_meta.wall_orientation
   voxcity.geoprocessor.surface_meta.classify_surface_faces
   voxcity.geoprocessor.surface_meta.attach_surface_face_meta
   voxcity.geoprocessor.surface_meta.surface_zone_mask
   voxcity.geoprocessor.surface_meta.resolve_target_face_mask
   voxcity.geoprocessor.surface_meta.compute_face_areas


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

.. py:data:: SELECTABLE_KINDS

.. py:function:: make_surface_face_key(building_id: int, centroid: Sequence[float], normal: Sequence[float], face_index: int) -> str

   Create a unique identifier for a surface face.


.. py:function:: classify_surface_kind(normal: Sequence[float]) -> str

   Classify surface kind based on normal vector.


.. py:function:: wall_orientation(normal: Sequence[float]) -> Optional[str]

   Determine wall orientation (N/E/S/W) from normal vector.


.. py:function:: classify_surface_faces(mesh: Any) -> list[dict]

   Classify each face of a mesh and return metadata dicts for each face.

   Returns a list of dicts with keys: face_key, building_id, surface_kind, orientation.


.. py:function:: attach_surface_face_meta(mesh: Any, reference_mesh: Any = None) -> Any

   Attach surface face metadata to a mesh in-place.

   Idempotent — safe to call multiple times.
   If reference_mesh is provided and has matching face topology, copy its keys directly.

   Stores mesh.metadata["surface_face_meta"] as list of dicts and version 1.


.. py:function:: surface_zone_mask(face_meta: Sequence[Any], selectors: Sequence[Any]) -> numpy.ndarray

   Return a boolean mask of faces selected by the given selectors.

   Accepts both dict and object selectors, handles both snake_case and camelCase keys.
   Skips selectors with unknown/missing building_id gracefully.


.. py:function:: resolve_target_face_mask(mesh: Any, target_selectors: Sequence, reference_mesh: Any = None) -> numpy.ndarray

   Resolve target_selectors to a boolean face mask over mesh.faces.

   Ensures surface_face_meta is attached first (classifying if needed). When
   *reference_mesh* is provided and its face count matches *mesh*, the
   attach uses its fast-path copy of the reference's classified meta --
   avoiding the per-face Python classify loop.

   Returns an (n_faces,) bool array.


.. py:function:: compute_face_areas(mesh: Any) -> numpy.ndarray

   Return the area of each triangular face of mesh as a float32 array.

   Assumes triangular faces (mesh.faces shape (n_faces, 3)). Voxcity's
   create_voxel_mesh produces triangulated output, so this fits the
   existing pipeline. If a future mesh source produces quads, triangulate
   first.