I/O Functions¶
Raster loading, saving, vector rasterisation, and weather file utilities.
All functions are available via solweig.io or can be imported directly:
load_raster¶
solweig.io.load_raster(path_str, bbox=None, band=0, ensure_float32=True)
¶
Load raster, optionally crop to bbox.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path_str
|
str
|
Path to raster file |
required |
bbox
|
list[int] | None
|
Optional bounding box [minx, miny, maxx, maxy] |
None
|
band
|
int
|
Band index to read (0-based) |
0
|
ensure_float32
|
bool
|
If True, ensure output array is float32 (default: True — converts any non-float32 dtype including integers) |
True
|
Returns:
| Type | Description |
|---|---|
tuple[ndarray, list[float], str | None, float | None]
|
Tuple of (array, transform, crs_wkt, no_data_value) |
save_raster¶
solweig.io.save_raster(out_path_str, data_arr, trf_arr, crs_wkt, no_data_val=-9999, ensure_float32=True, use_cog=True, generate_preview=True)
¶
Save raster to GeoTIFF (Cloud-Optimized by default).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
out_path_str
|
str
|
Output file path |
required |
data_arr
|
ndarray
|
2D numpy array to save |
required |
trf_arr
|
list[float]
|
GDAL-style geotransform [top_left_x, pixel_width, rotation, top_left_y, rotation, pixel_height] |
required |
crs_wkt
|
str | None
|
CRS in WKT format |
required |
no_data_val
|
float
|
No-data value to use |
-9999
|
ensure_float32
|
bool
|
If True, ensure array is float32 before saving (default: True — converts any non-float32 dtype) |
True
|
use_cog
|
bool
|
If True, save as Cloud-Optimized GeoTIFF with built-in overviews (default: True for better OS thumbnail support) |
True
|
generate_preview
|
bool
|
If True, generate a sidecar .preview.png file for OS thumbnails (default: True for float data that can't be previewed directly) |
True
|
rasterise_gdf¶
solweig.io.rasterise_gdf(gdf, geom_col, ht_col, bbox=None, pixel_size=1.0)
¶
download_epw¶
solweig.io.download_epw(latitude, longitude, output_path, *, timeout=60)
¶
Download a Typical Meteorological Year (TMY) EPW file from PVGIS.
Uses the EU Joint Research Centre's PVGIS API (no API key required). Coverage is near-global (all continents except polar regions), using ERA5 reanalysis data.
The downloaded data contains modified Copernicus Climate Change Service information. Neither the European Commission nor ECMWF is responsible for any use that may be made of the Copernicus information or data it contains. See https://cds.climate.copernicus.eu/disclaimer for the full licence terms.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
latitude
|
float
|
Latitude in decimal degrees (-90 to 90). |
required |
longitude
|
float
|
Longitude in decimal degrees (-180 to 180). |
required |
output_path
|
str | Path
|
Path where the EPW file will be saved. |
required |
timeout
|
int
|
HTTP request timeout in seconds (default 60). |
60
|
Returns:
| Type | Description |
|---|---|
Path
|
Path to the saved EPW file. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If coordinates are out of range. |
ConnectionError
|
If the PVGIS server is unreachable. |
RuntimeError
|
If the download fails (e.g. location over ocean). |
Example
from solweig.io import download_epw path = download_epw(37.98, 23.73, "athens.epw") data, metadata = read_epw(path)
read_epw¶
solweig.io.read_epw(path)
¶
Read EnergyPlus Weather (EPW) file and return weather data with metadata.
EPW files have 8 header lines followed by hourly weather data. Uses pure Python parser (no pandas/scipy dependencies).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Path to EPW file (string or Path) |
required |
Returns:
| Type | Description |
|---|---|
tuple
|
Tuple of (data, metadata_dict): |
tuple
|
|
tuple
|
|
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If EPW file doesn't exist |
ValueError
|
If EPW file is malformed |