voxcity.geoprocessor.surface_meta

Pure helpers for building surface face classification and metadata.

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

Attributes

SELECTABLE_KINDS

Functions

make_surface_face_key(→ str)	Create a unique identifier for a surface face.
classify_surface_kind(→ str)	Classify surface kind based on normal vector.
wall_orientation(→ Optional[str])	Determine wall orientation (N/E/S/W) from normal vector.
classify_surface_faces(→ list[dict])	Classify each face of a mesh and return metadata dicts for each face.
attach_surface_face_meta(→ Any)	Attach surface face metadata to a mesh in-place.
surface_zone_mask(→ numpy.ndarray)	Return a boolean mask of faces selected by the given selectors.
resolve_target_face_mask(→ numpy.ndarray)	Resolve target_selectors to a boolean face mask over mesh.faces.
compute_face_areas(→ numpy.ndarray)	Return the area of each triangular face of mesh as a float32 array.

Module Contents

voxcity.geoprocessor.surface_meta.SELECTABLE_KINDS

voxcity.geoprocessor.surface_meta.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.

voxcity.geoprocessor.surface_meta.classify_surface_kind(normal: Sequence[float]) → str

Classify surface kind based on normal vector.

voxcity.geoprocessor.surface_meta.wall_orientation(normal: Sequence[float]) → str | None

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

voxcity.geoprocessor.surface_meta.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.

voxcity.geoprocessor.surface_meta.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.

voxcity.geoprocessor.surface_meta.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.

voxcity.geoprocessor.surface_meta.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.

voxcity.geoprocessor.surface_meta.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.