voxcity 0.6.26__py3-none-any.whl → 1.0.2__py3-none-any.whl

voxcity/exporter/obj.py

@@ -23,6 +23,13 @@ Dependencies:
 - numpy: For array operations
 - matplotlib: For colormap handling
 - trimesh: For mesh operations
+
+Orientation contract:
+- Export functions assume input 2D grids are north_up (row 0 = north/top) with
+  columns increasing eastward (col 0 = west/left), and voxel arrays use
+  (row, col, z) = (north→south, west→east, ground→up).
+- Internal flips may be applied to match OBJ coordinate conventions; these do
+  not change the semantic orientation of the data.
 """
 
 import numpy as np
@@ -31,7 +38,7 @@ from numba import njit, prange
 import matplotlib.pyplot as plt
 import trimesh
 import numpy as np
-from ..utils.visualization import get_voxel_color_map
+from ..visualizer import get_voxel_color_map
 
 def convert_colormap_indices(original_map):
     """
@@ -266,7 +273,7 @@ def mesh_faces(mask, layer_index, axis, positive_direction, normal_idx, voxel_si
 
             v += width
 
-def export_obj(array, output_dir, file_name, voxel_size, voxel_color_map=None):
+def export_obj(array, output_dir, file_name, voxel_size=None, voxel_color_map=None):
     """
     Export a voxel array to OBJ format with materials and proper face orientations.
     
@@ -275,14 +282,14 @@ def export_obj(array, output_dir, file_name, voxel_size, voxel_color_map=None):
     both OBJ and MTL files with all necessary components for rendering.
     
     Args:
-        array (ndarray): 3D numpy array containing voxel values.
+        array (ndarray | VoxCity): 3D numpy array of voxel values or a VoxCity instance.
             Non-zero values indicate voxel presence and material type.
         output_dir (str): Directory to save the OBJ and MTL files.
             Will be created if it doesn't exist.
         file_name (str): Base name for the output files.
             Will be used for both .obj and .mtl files.
-        voxel_size (float): Size of each voxel in meters.
-            Used to scale the model to real-world units.
+        voxel_size (float | None): Size of each voxel in meters. If a VoxCity is provided,
+            this is inferred from the object and this parameter is ignored.
         voxel_color_map (dict, optional): Dictionary mapping voxel values to RGB colors.
             If None, uses default color map. Colors should be RGB lists (0-255).
             
@@ -307,6 +314,15 @@ def export_obj(array, output_dir, file_name, voxel_size, voxel_color_map=None):
         - Transparency settings
         - Illumination model definitions
     """
+    # Accept VoxCity instance as first argument
+    try:
+        from ..models import VoxCity as _VoxCity
+        if isinstance(array, _VoxCity):
+            voxel_size = float(array.voxels.meta.meshsize)
+            array = array.voxels.classes
+    except Exception:
+        pass
+
     if voxel_color_map is None:
         voxel_color_map = get_voxel_color_map()
 
@@ -681,6 +697,7 @@ def export_netcdf_to_obj(
     classes_to_show=None,
     voxel_color_scheme="default",
     max_faces_warn=1_000_000,
+    export_vox_base=True,
 ):
     """
     Export two OBJ/MTL files using the same local meter frame:
@@ -718,6 +735,8 @@ def export_netcdf_to_obj(
         classes_to_show (set[int]|None): Optional subset of voxel classes to export; None -> all present (except 0).
         voxel_color_scheme (str): Color scheme name passed to get_voxel_color_map.
         max_faces_warn (int): Warn if a single class exceeds this many faces.
+        export_vox_base (bool): If False, skip exporting VoxCity OBJ/MTL; VoxCity input
+            is still used to define the shared coordinate system for scalar OBJ.
 
     Returns:
         dict: Paths of written files: keys 'vox_obj','vox_mtl','tm_obj','tm_mtl' (values may be None).
@@ -1345,27 +1364,28 @@ def export_netcdf_to_obj(
     vox_meshes = {}
     tm_meshes = {}
 
-    present = set(np.unique(Av_kji))
-    present.discard(0)
-    if classes_to_show is not None:
-        present &= set(classes_to_show)
-    present = sorted(present)
-
-    faces_total = 0
-    voxel_color_map = get_voxel_color_map(color_scheme=voxel_color_scheme)
-    for cls in present:
-        mask = Av_kji == cls
-        if not np.any(mask):
-            continue
-        rgb = voxel_color_map.get(int(cls), [200, 200, 200])
-        if greedy_vox:
-            m_cls, faces = make_voxel_mesh_uniform_color_greedy(mask, Xv_s, Yv_s, Zv_s, rgb=rgb, name=f"class_{int(cls)}")
-        else:
-            m_cls, faces = make_voxel_mesh_uniform_color(mask, Xv_s, Yv_s, Zv_s, rgb=rgb, name=f"class_{int(cls)}")
-        if m_cls is not None:
-            vox_meshes[f"voxclass_{int(cls)}"] = m_cls
-            faces_total += faces
-    print(f"[VoxCity] total voxel faces: {faces_total:,}")
+    if export_vox_base:
+        present = set(np.unique(Av_kji))
+        present.discard(0)
+        if classes_to_show is not None:
+            present &= set(classes_to_show)
+        present = sorted(present)
+
+        faces_total = 0
+        voxel_color_map = get_voxel_color_map(color_scheme=voxel_color_scheme)
+        for cls in present:
+            mask = Av_kji == cls
+            if not np.any(mask):
+                continue
+            rgb = voxel_color_map.get(int(cls), [200, 200, 200])
+            if greedy_vox:
+                m_cls, faces = make_voxel_mesh_uniform_color_greedy(mask, Xv_s, Yv_s, Zv_s, rgb=rgb, name=f"class_{int(cls)}")
+            else:
+                m_cls, faces = make_voxel_mesh_uniform_color(mask, Xv_s, Yv_s, Zv_s, rgb=rgb, name=f"class_{int(cls)}")
+            if m_cls is not None:
+                vox_meshes[f"voxclass_{int(cls)}"] = m_cls
+                faces_total += faces
+        print(f"[VoxCity] total voxel faces: {faces_total:,}")
 
     iso_meshes = build_tm_isosurfaces_regular_grid(
         A_scalar=A_s,
@@ -1390,7 +1410,7 @@ def export_netcdf_to_obj(
 
     os.makedirs(output_dir, exist_ok=True)
     obj_vox = mtl_vox = obj_tm = mtl_tm = None
-    if vox_meshes:
+    if export_vox_base and vox_meshes:
         obj_vox, mtl_vox = save_obj_with_mtl_and_normals(vox_meshes, output_dir, vox_base_filename)
     if tm_meshes:
         obj_tm, mtl_tm = save_obj_with_mtl_and_normals(tm_meshes, output_dir, tm_base_filename)
@@ -1403,4 +1423,59 @@ def export_netcdf_to_obj(
         print(f"Scalar Iso OBJ: {obj_tm}")
         print(f"Scalar Iso MTL: {mtl_tm}")
 
-    return {"vox_obj": obj_vox, "vox_mtl": mtl_vox, "tm_obj": obj_tm, "tm_mtl": mtl_tm}
+    return {"vox_obj": obj_vox, "vox_mtl": mtl_vox, "tm_obj": obj_tm, "tm_mtl": mtl_tm}
+
+
+class OBJExporter:
+    """Exporter that writes mesh collections or trimesh dicts to OBJ/MTL.
+
+    Accepts either a MeshCollection (voxcity.models) or dict[str, trimesh.Trimesh].
+    """
+
+    def export(self, obj, output_directory: str, base_filename: str, **kwargs):
+        os.makedirs(output_directory, exist_ok=True)
+        # VoxCity or MeshCollection path
+        try:
+            from ..models import MeshCollection, VoxCity
+            if isinstance(obj, VoxCity):
+                # Delegate to file-writing path using voxels
+                export_obj(
+                    array=obj.voxels.classes,
+                    output_dir=output_directory,
+                    file_name=base_filename,
+                    voxel_size=float(obj.voxels.meta.meshsize),
+                    voxel_color_map=kwargs.get("voxel_color_map"),
+                )
+                return os.path.join(output_directory, f"{base_filename}.obj")
+            is_collection = isinstance(obj, MeshCollection)
+        except Exception:
+            is_collection = False
+
+        if is_collection:
+            tm = {}
+            for key, mm in obj.items.items():
+                if getattr(mm, "vertices", None) is None or getattr(mm, "faces", None) is None:
+                    continue
+                if mm.vertices.size == 0 or mm.faces.size == 0:
+                    continue
+                tri = trimesh.Trimesh(vertices=mm.vertices, faces=mm.faces, process=False)
+                if getattr(mm, "colors", None) is not None:
+                    tri.visual.face_colors = mm.colors
+                tm[key] = tri
+            if not tm:
+                return None
+            combined = trimesh.util.concatenate(list(tm.values()))
+            out = os.path.join(output_directory, f"{base_filename}.obj")
+            combined.export(out)
+            return out
+
+        # Dict[str, trimesh.Trimesh] path
+        if isinstance(obj, dict) and all(hasattr(m, "vertices") for m in obj.values()):
+            if not obj:
+                return None
+            combined = trimesh.util.concatenate(list(obj.values()))
+            out = os.path.join(output_directory, f"{base_filename}.obj")
+            combined.export(out)
+            return out
+
+        raise TypeError("OBJExporter.export expects MeshCollection or dict[str, trimesh.Trimesh]")

voxcity/generator/__init__.py

@@ -0,0 +1,47 @@
+"""VoxCity generator subpackage.
+
+This package organizes the voxel city generation pipeline into focused modules
+while preserving the original public API under `voxcity.generator`.
+
+Orientation contract:
+- All 2D grids use north_up orientation (row 0 = north/top; columns increase eastward).
+- 3D indexing follows (row, col, z) = (north→south, west→east, ground→up).
+"""
+
+from .api import get_voxcity, get_voxcity_CityGML, auto_select_data_sources
+from .grids import (
+    get_land_cover_grid,
+    get_building_height_grid,
+    get_canopy_height_grid,
+    get_dem_grid,
+)
+from .voxelizer import (
+    Voxelizer,
+    GROUND_CODE,
+    TREE_CODE,
+    BUILDING_CODE,
+)
+from .pipeline import VoxCityPipeline
+from .io import save_voxcity, load_voxcity
+from .update import update_voxcity, regenerate_voxels
+
+__all__ = [
+    "get_voxcity",
+    "auto_select_data_sources",
+    "get_voxcity_CityGML",
+    "get_land_cover_grid",
+    "get_building_height_grid",
+    "get_canopy_height_grid",
+    "get_dem_grid",
+    "Voxelizer",
+    "GROUND_CODE",
+    "TREE_CODE",
+    "BUILDING_CODE",
+    "VoxCityPipeline",
+    "save_voxcity",
+    "load_voxcity",
+    "update_voxcity",
+    "regenerate_voxels",
+]
+
+