voxcity.io¶

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 - migrate_h5 – one-shot converter from pre-v3 HDF5 files to the strict v3 format

Attributes¶

FORMAT_V3

Functions¶

`load_voxcity`(input_path, *[, trusted])	Load a VoxCity instance from a file.
`save_voxcity`(output_path, city)	Save a VoxCity instance to disk.
`save_h5`(output_path, city)	Save a VoxCity model to an HDF5 file (no simulation results).
`load_h5`(input_path)	Load a VoxCity model from an HDF5 file.
`migrate_h5`(src, dst)	Convert a pre-v3 VoxCity HDF5 file to the v3 format, one shot.
`save_results_h5`(output_path, city[, ground_results, ...])	Save a VoxCity model and simulation results to an HDF5 file.
`load_results_h5`(input_path)	Load a VoxCity model and simulation results from an HDF5 file.

Module Contents¶

voxcity.io.FORMAT_V3 = 'voxcity_results.v3'¶

voxcity.io.load_voxcity(input_path, *, trusted: bool = False)[source]¶

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.

Parameters:

input_path (str or Path) – Path to the file.
trusted (bool, default False) – (Pickle only) Set to True to acknowledge the security implications of loading a pickle file and suppress the warning.

Return type:

VoxCity

voxcity.io.save_voxcity(output_path, city)[source]¶

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.

Parameters:

output_path (str or Path) – Destination file path.
city (VoxCity) – The model to save.

voxcity.io.save_h5(output_path, city)[source]¶

Save a VoxCity model to an HDF5 file (no simulation results).

This is the recommended alternative to save_voxcity() (pickle-based) because HDF5 files cannot execute arbitrary code on load.

Parameters:

output_path (str or Path) – Destination file path (e.g. "model.h5").
city (VoxCity) – The VoxCity model instance.

See also

save_h5: Save a VoxCity model to an HDF5 file.
load_results_h5: Load a VoxCity model together with simulation results.

voxcity.io.migrate_h5(src, dst)[source]¶

Convert a pre-v3 VoxCity HDF5 file to the v3 format, one shot.

Copies src to dst, then stamps the v3 contract on the copy: the axes attribute (root, voxcity group, voxcity/voxel_grid dataset), a derived rotation_angle, and a structured root rectangle_vertices dataset. Geometry comes from extras_json['rectangle_vertices'] when present, else an axis-aligned rectangle is constructed from the bounds attribute (pre-v3 files without stored vertices were produced axis-aligned).

Provenance attrs are recorded on dst so inferred geometry stays auditable: migrated_from (the source’s original __format__, or "unknown") and geometry_source ("extras" or "bounds").

src is fully validated read-only before dst is written, so a failed migration never overwrites an existing dst.

Raises:: ValueError – If src and dst are the same file (the converter never works in place), src is already v3, or src has no usable geometry.

voxcity.io.save_results_h5(output_path, city, ground_results=None, building_results=None, simulation_results=None)[source]¶

Save a VoxCity model and simulation results to an HDF5 file.

Parameters:

output_path (str) – Destination file path (e.g. "results.h5").
city (VoxCity) – The VoxCity model instance.
ground_results (dict, optional) –
Ground-level simulation results. Keys whose values are 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.
building_results (dict, optional) –
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.

simulation_results (dict, optional) –

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': {...}},
    },
    'network': {
        'solar': edge_geodataframe,  # LineString edges + value columns
    },
}

Supported simulation types are 'ground', 'building_surface' and 'network'. The legacy ground_results and building_results arguments remain supported for saving one unnamed/default result of each type.

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.
Files are written in the voxcity_results.v3 format: root attrs axes, rotation_angle and root dataset rectangle_vertices declare the coordinate contract (see voxcity.utils.orientation).

voxcity.io.load_results_h5(input_path)[source]¶

Load a VoxCity model and simulation results from an HDF5 file.

Parameters:

input_path (str) – Path to the HDF5 file created by save_results_h5().

Returns:

A dictionary with the following keys:

'voxcity': The reconstructed 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']. Network results appear as data['simulations']['network'][name], a dict with an 'edges' GeoDataFrame plus scalar metadata. Legacy top-level 'ground' and 'building' groups are also exposed as 'default' entries in this nested structure.
'meta': dict with 'crs', 'meshsize', 'bounds', 'rotation_angle' and 'rectangle_vertices'.

Return type:

dict

Raises:

ValueError – If the file does not declare the voxcity_results.v3 format (via the root __format__ attribute) or otherwise fails the v3 axis contract (see voxcity.utils.orientation.check_axes()). This loader is strict: pre-v3 (e.g. voxcity_results.v2) and foreign HDF5 files are rejected outright, with the error message pointing to migrate_h5() to convert the file once.

Notes

The returned 'voxcity' object is a fully reconstructed VoxCity dataclass – it can be passed directly to any simulator or visualizer function. Its .extras dict also carries 'rectangle_vertices' and 'rotation_angle', taken from the file’s structured v3 geometry (these override any stale copies that may exist in extras_json).