voxcity.io ========== .. py:module:: voxcity.io .. autoapi-nested-parse:: Persistence functions for VoxCity models and simulation results. Provides: - ``save_voxcity`` / ``load_voxcity`` – pickle-based VoxCity model I/O - ``save_h5`` / ``load_h5`` – HDF5-based VoxCity model I/O (recommended) - ``save_results_h5`` / ``load_results_h5`` – HDF5-based combined model + results I/O Functions --------- .. autoapisummary:: voxcity.io.load_voxcity voxcity.io.save_voxcity voxcity.io.save_h5 voxcity.io.load_h5 voxcity.io.save_results_h5 voxcity.io.load_results_h5 Module Contents --------------- .. py:function:: load_voxcity(input_path, *, trusted: bool = False) Load a VoxCity instance from a file. The format is detected automatically based on the file extension: * ``.h5`` / ``.hdf5`` → safe HDF5 format (no warning). * Anything else (e.g. ``.pkl``) → legacy pickle format. .. warning:: Pickle files can execute arbitrary code on load. Only load files you created yourself or received from a trusted source. Pass ``trusted=True`` to suppress this warning. :param input_path: Path to the file. :type input_path: str or Path :param trusted: (Pickle only) Set to ``True`` to acknowledge the security implications of loading a pickle file and suppress the warning. :type trusted: bool, default False :rtype: VoxCity .. py:function:: save_voxcity(output_path, city) Save a VoxCity instance to disk. The format is chosen automatically based on the file extension: * ``.h5`` / ``.hdf5`` → safe HDF5 format (recommended). * Anything else (e.g. ``.pkl``) → legacy pickle format. :param output_path: Destination file path. :type output_path: str or Path :param city: The model to save. :type city: VoxCity .. py:function:: save_h5(output_path, city) Save a VoxCity model to an HDF5 file (no simulation results). This is the recommended alternative to :func:`save_voxcity` (pickle-based) because HDF5 files cannot execute arbitrary code on load. :param output_path: Destination file path (e.g. ``"model.h5"``). :type output_path: str or Path :param city: The VoxCity model instance. :type city: VoxCity .. seealso:: :py:obj:`load_h5` Load a VoxCity model from an HDF5 file. :py:obj:`save_results_h5` Save a VoxCity model together with simulation results. .. py:function:: load_h5(input_path) Load a VoxCity model from an HDF5 file. This is the safe counterpart to :func:`load_voxcity` (pickle-based). Works with files written by either :func:`save_h5` or :func:`save_results_h5` — simulation result groups are simply ignored. :param input_path: Path to the HDF5 file. :type input_path: str or Path :returns: The reconstructed VoxCity model. :rtype: VoxCity .. seealso:: :py:obj:`save_h5` Save a VoxCity model to an HDF5 file. :py:obj:`load_results_h5` Load a VoxCity model together with simulation results. .. py:function:: save_results_h5(output_path, city, ground_results=None, building_results=None, simulation_results=None) Save a VoxCity model and simulation results to an HDF5 file. :param output_path: Destination file path (e.g. ``"results.h5"``). :type output_path: str :param city: The VoxCity model instance. :type city: VoxCity :param ground_results: Ground-level simulation results. Keys whose values are :class:`numpy.ndarray` are stored as HDF5 datasets (with gzip compression); all other JSON-serializable values are stored as group attributes. Typical keys produced by the GPU solar integration module:: { 'sunlight_hours': np.ndarray (ny, nx), 'cumulative_global': np.ndarray (ny, nx), 'svf': np.ndarray (ny, nx), 'potential_sunlight_hours': float, 'mode': str, ... } If the input numpy array carries a ``.metadata`` dict (e.g. ``ArrayWithMetadata``), those metadata entries are also persisted as sub-attributes. :type ground_results: dict, optional :param building_results: Building-surface simulation results. The dict **must** contain a ``'mesh'`` key whose value is a Trimesh object. Per-face data arrays are taken either from the ``'metadata'`` sub-dict or directly from the Trimesh's ``.metadata`` attribute. Typical keys produced by the GPU solar integration module:: { 'mesh': trimesh.Trimesh, 'metadata': { 'irradiance_direct': np.ndarray (n_faces,), 'irradiance_diffuse': np.ndarray (n_faces,), 'sunlight_hours': np.ndarray (n_faces,), 'potential_sunlight_hours': float, ... }, } If ``'metadata'`` is *not* provided explicitly, the function falls back to ``mesh.metadata``. :type building_results: dict, optional :param simulation_results: Multiple named simulation results grouped by simulation type. The recommended structure is:: { 'ground': { 'solar_cumulative': {'cumulative_global': array, ...}, 'sunlight_hours_dsh': {'sunlight_hours': array, ...}, }, 'building_surface': { 'solar_cumulative': trimesh_obj, 'sky_view_factor': {'mesh': trimesh_obj, 'metadata': {...}}, }, } Supported simulation types are ``'ground'`` and ``'building_surface'``. The legacy ``ground_results`` and ``building_results`` arguments remain supported for saving one unnamed/default result of each type. :type simulation_results: dict, optional .. rubric:: Notes * Requires the ``h5py`` package (``pip install h5py``). * The file is self-contained – no pickle dependency at load time. * Datasets use ``compression='gzip'`` by default for compact files. .. py:function:: load_results_h5(input_path) Load a VoxCity model and simulation results from an HDF5 file. :param input_path: Path to the HDF5 file created by :func:`save_results_h5`. :type input_path: str :returns: A dictionary with the following keys: ``'voxcity'`` The reconstructed :class:`~voxcity.models.VoxCity` instance. ``'ground'`` *(if present)* dict mapping dataset names to numpy arrays, plus scalar metadata entries. ``'building'`` *(if present)* dict with ``'mesh_vertices'``, ``'mesh_faces'``, ``'mesh_face_normals'`` (numpy arrays) and per-face data arrays / scalar metadata. ``'simulations'`` *(if present)* nested dict of named simulation results grouped by simulation type, e.g. ``data['simulations']['ground']['solar_cumulative']`` or ``data['simulations']['building_surface']['sky_view_factor']``. Legacy top-level ``'ground'`` and ``'building'`` groups are also exposed as ``'default'`` entries in this nested structure. ``'meta'`` dict with ``'crs'``, ``'meshsize'``, ``'bounds'``. :rtype: dict .. rubric:: Notes The returned ``'voxcity'`` object is a fully reconstructed :class:`VoxCity` dataclass – it can be passed directly to any simulator or visualizer function.