Skip to content

I/O

Mesh and point-cloud loading, saving, and diagnostic exports. All geometry I/O goes through Trimesh; diagnostic exports produce OBJ line-segment files for visual inspection in Rhino or other 3D viewers.

  • Mesh I/O -- load_mesh reads PLY files and ensures consistent face-normal orientation; save_mesh writes PLY.
  • Point clouds -- save_pointcloud writes Nx3 arrays as PLY point clouds.
  • Diagnostic exports -- sun vectors, arbitrary rays, surface points with normals, and bounding-box meshes, all written as OBJ or PLY for debugging and visual verification.

urbansolarcarver.io

UrbanSolarCarver I/O Module

This module provides all file-based input and output functionality for the UrbanSolarCarver pipeline, abstracting away format specifics and ensuring consistent recording of geometry, point clouds, and diagnostic line sets.

Core Responsibilities

  1. Mesh Loading • load_mesh(path: str) → trimesh.Trimesh

    • Reads a mesh file (PLY, OBJ, etc.) from disk.
    • Repairs normals if the mesh is not watertight.
    • Returns a Trimesh instance ready for downstream processing.

  2. Mesh Saving • save_mesh(mesh: trimesh.Trimesh, path: str) → str

    • Exports a Trimesh object to disk at the given path.
    • Ensures parent directories exist.
    • Returns the absolute path of the written file.

  3. Point Cloud Export • save_pointcloud(points: np.ndarray, path: str) → str

    • Writes an Nx3 NumPy array of 3D points to a PLY point cloud.
    • Validates array shape.
    • Returns the written file path.

  4. Line-Segment Export (OBJ) • export_sun_vectors(vectors: np.ndarray, origin: (x,y,z), scale: float, path: str) → str • export_rays(origins: np.ndarray, directions: np.ndarray, length: float, path: str) → str

    • Convert direction vectors or arbitrary ray sets into 3D line segments.
    • Each segment is two vertices and one line entry in OBJ format.
    • Facilitates visualization of sun directions or raytracing diagnostics.

  5. Combined Point-and-Normal Export • export_points_with_normals(points: np.ndarray, normals: np.ndarray, path: str, normal_length: float) → ExportPaths

    • Writes a PLY point cloud and a matching OBJ of normal vectors.
    • Returns an ExportPaths dataclass with the two output file paths.

  6. Bounding-Box Meshes • export_mesh_bbox_mesh(mesh: trimesh.Trimesh, path: str) → str

    • Computes the axis-aligned bounding box of a mesh.
    • Outputs a PLY box mesh for spatial context. • export_voxel_bbox_mesh(origin: np.ndarray, scale: float, path: str) → str
    • Constructs a cubic bounding box for a voxel grid.
    • Outputs as a PLY box mesh, aiding in debug and visualization.
Key Data Structures

• trimesh.Trimesh - Core mesh representation (vertices, faces, normals). • np.ndarray (Nx3) - Used for both point clouds and line-segment endpoints. • ExportPaths - Simple dataclass grouping point-cloud and normal-OBJ paths.

Usage Context

All functions return the path(s) of files written. This module ensures that geometry and diagnostics are saved reliably and consistently for later analysis or publication.

load_mesh(path)

Load a triangle mesh from file and ensure face normals are consistently oriented (outward-facing). Trimesh’s process=True fixes winding order, merges duplicate vertices, and removes degenerate faces.

save_mesh(mesh, path)

Save a mesh to disk. Creates output directory if needed. Returns the file path.

save_pointcloud(points, path)

Save an Nx3 array of points as a PLY point cloud. Returns the file path.

Raises ValueError if points array is empty.

export_sun_vectors(vectors, origin=(0.0, 0.0, 0.0), scale=30.0, path='sun_vectors.obj')

Export sun direction vectors as OBJ line segments. Returns the file path.

Args: vectors: Nx3 array of sun direction vectors. origin: Common origin point for all vectors. scale: Length of each rendered line segment. path: Output OBJ file path.

export_rays(ray_origins, ray_dirs, length=30.0, path='rays.obj')

Export arbitrary rays as OBJ line segments. Returns the file path.

Args: ray_origins: Nx3 array of ray start points. ray_dirs: Nx3 array of ray direction vectors. length: Length of each rendered line segment. path: Output OBJ file path.

export_points_with_normals(points, normals, path, normal_length=2.0)

Export a point cloud (PLY) and its normals (OBJ). Returns an ExportPaths dataclass with file paths.

Args: points: Nx3 array of 3D point positions. normals: Nx3 array of normal vectors (must match points shape). path: Base output path (must end in .ply). normal_length: Length of each normal line segment.

export_mesh_bbox_mesh(mesh, path)

Export the axis-aligned bounding box of a mesh as a PLY box. Returns the file path.

export_voxel_bbox_mesh(origin, scale, path)

Export a cubic bounding box for the voxel grid as PLY. Returns the file path.

Args: origin: 3-element array, minimum corner of the voxel grid. scale: Side length of the cubic bounding box. path: Output PLY file path.