Skip to content

I/O Functions

Raster loading, saving, vector rasterisation, and weather file utilities.

All functions are available via solweig.io or can be imported directly:

import solweig

data, transform, crs, nodata = solweig.io.load_raster("dsm.tif")

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[float] | 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 (v5.3, no API key required). Coverage is near-global (all continents except polar regions), using ERA5 reanalysis data.

Important: TMY files are not observations for a specific year. A TMY is a statistical composite — each calendar month is selected from the most "typical" month across a multi-year reference period (2005–2023 for PVGIS v5.3). The resulting file represents long-term average climate conditions, not a recent or continuously updated dataset. Because each month is taken from a real historical year, the row timestamps in the returned file will legitimately span multiple years within the reference window (e.g. a January from 2022 alongside a February from 2014). This is the defining property of a TMY and not an artefact. The reference period is fixed per PVGIS release; data freshness depends on the upstream PVGIS version, not on SOLWEIG.

See the PVGIS TMY documentation for full methodology and data sources: https://joint-research-centre.ec.europa.eu/photovoltaic-geographical-information-system-pvgis/pvgis-tools/pvgis-typical-meteorological-year-tmy-generator_en

Ref: UMEP-dev/solweig#8

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
  • data: DataFrame-like object with datetime index and weather columns:
  • temp_air: Dry bulb temperature (°C)
  • relative_humidity: Relative humidity (%)
  • atmospheric_pressure: Atmospheric pressure (Pa)
  • ghi: Global horizontal irradiance (W/m²)
  • dni: Direct normal irradiance (W/m²)
  • dhi: Diffuse horizontal irradiance (W/m²)
  • wind_speed: Wind speed (m/s)
  • wind_direction: Wind direction (degrees)
tuple
  • metadata_dict: Dictionary with keys:
  • city: Location city name
  • latitude: Latitude (degrees)
  • longitude: Longitude (degrees)
  • elevation: Elevation (m)
  • tz_offset: Timezone offset (hours)

Raises:

Type Description
FileNotFoundError

If EPW file doesn't exist
ValueError

If EPW file is malformed