lczlite
Local Climate Zone classification from urban canopy parameters.
lczlite assigns sites or grid cells to the Local Climate Zones of Stewart & Oke (2012)
by comparing their urban canopy parameters with the property ranges of each zone:
- Range scoring: trapezoidal (fuzzy) membership of each parameter in each class's
range, weighted class scores, best class, confidence, runner-up, margin and mixed-class
flags; crisp in/out tests with
softness=0. - Parameters from simple inputs: building, impervious and pervious surface fractions; aspect ratio; canyon sky view factor; frontal area index; displacement height and roughness length (Macdonald et al. 1998); Davenport terrain roughness class.
- Building grids: footprint areas and heights (with x, y) summed into grid cells with area-weighted, geometric and maximum heights and frontal areas.
- Outputs: WUDAPT integer codes (1-17, 0 = unclassified), LCZ colour table, RGB
images, QGIS
.qmlpalette, class summaries, mixed-pair counts, agreement between two maps, majority filter. - Published range table bundled: the property ranges of all 17 classes from Stewart &
Oke (2012), Tables 3 and 4 (
stewart_oke_table()); local tables load from CSV or JSON, with an empty 17-class template.
It needs only NumPy. A command-line tool is included.
The default range table holds the values of Stewart & Oke (2012), Table 3 (sky view
factor, aspect ratio, building / impervious / pervious surface fraction, height of
roughness elements, terrain roughness class) and Table 4 (surface admittance, albedo,
anthropogenic heat), read from the published article and shipped as
lczlite/data/stewart_oke_2012.json. Surface fractions are converted from percent to
0-1. Two cells are blank in the paper and stay blank: the admittance of LCZ A ("unknown")
and the height of roughness elements of LCZ G.
Installation
pip install lczlite
Requires Python 3.9 or newer.
Quickstart
import numpy as np
import lczlite as lz
table = lz.stewart_oke_table() # Stewart & Oke (2012), Tables 3-4
# or a local adaptation: lz.read_range_table("my_ranges.csv", percent=True)
# Parameters per site (any shape; NaN = unknown)
params = {
"svf": [0.45, 0.75, 0.95],
"aspect_ratio": [1.2, 0.5, 0.05],
"bsf": [0.50, 0.30, 0.03],
"isf": [0.40, 0.30, 0.02],
"psf": [0.10, 0.40, 0.95],
"height": [15.0, 6.0, 0.5],
}
res = lz.classify(params, table, mixed_margin=0.1)
res.labels # best LCZ key per site, '' = unclassified
res.codes # WUDAPT codes 1-17, 0 = unclassified
res.confidence # best score (0-1)
res.margin # gap to the runner-up
res.mixed # True where the two best classes are close
res.explain(0) # per-parameter memberships of site 0
lz.class_summary(res)
From building footprints to classified cells:
spec = lz.GridSpec(x0=500000, y0=4300000, cell_size=200, shape=(50, 50))
grid = lz.buildings_to_grid(x, y, footprint_area, height, spec)
params = grid.parameters(impervious_area, height="mean",
admittance=adm, albedo=alb, anthropogenic_heat=qf)
res = lz.classify(params, table)
rgb = res.to_rgb() # (rows, cols, 3) uint8
lz.write_qml("lcz.qml") # palette for a WUDAPT-coded GeoTIFF in QGIS
A complete synthetic run is in examples/quickstart.py.
Feature overview
| Area | Functions / classes |
|---|---|
| Classes | LCZ_CLASSES, LCZ_KEYS, normalize_key, wudapt_code, key_from_code, lcz_class |
| Colours | colour_table, to_rgb, hex_to_rgb, write_qml, write_colour_csv |
| Range tables | RangeTable, Range, parse_range, stewart_oke_table, read_range_table, write_template, PARAMETERS |
| Parameters | surface_fractions, street_width_regular, aspect_ratio, svf_canyon, frontal_area_index, macdonald, roughness_class, albedo_plan_weighted, canopy_parameters, DAVENPORT_Z0 |
| Grids | GridSpec, buildings_to_grid -> BuildingGrid (parameters()) |
| Classification | membership, classify -> LCZResult (labels, codes, confidence, margin, mixed, explain, records, to_rgb) |
| Summaries | class_summary, mixed_pairs, compare_maps, majority_filter |
| I/O | read_sites_csv, result_rows, write_results_csv, write_csv |
Parameter names: svf, aspect_ratio, bsf (building surface fraction), isf
(impervious), psf (pervious), height (height of roughness elements), roughness_class,
admittance, albedo, anthropogenic_heat; common long names are accepted as aliases.
Surface fractions are 0-1 inside the package; use percent=True for tables or site files
in percent.
Methods and sources
Local Climate Zones. Seventeen classes (built types 1-10, land-cover types A-G) defined by ranges of geometric, surface-cover, thermal, radiative and metabolic properties (Stewart & Oke 2012). WUDAPT products store them as integers 1-17 with A-G as 11-17 (Demuzere et al. 2021); the default colours follow the palette commonly used for WUDAPT maps and can be overridden.
Scoring. For a range [lo, hi] the membership is 1 inside and falls linearly to 0 at
a distance w outside; w = softness · (hi − lo) for two-sided ranges,
softness · |bound| for one-sided ones, or an absolute tolerance per parameter. A class
score is the weighted mean membership over the parameters the class constrains and the
site has. The best class gives the confidence; the margin to the second class drives the
mixed flag. The membership shape and the defaults (softness=0.5, mixed_margin=0.1,
min_score=0) are design choices of this package, not values from the paper.
Parameters.
| Parameter | Computation | Source |
|---|---|---|
| BSF, ISF, PSF | plan-area shares of the cell; PSF = remainder unless given | definition |
| Street width | W = L (1/√λp − 1), L = √(mean footprint) |
regular array of square blocks (assumption of this package) |
| Aspect ratio | H / W |
definition |
| SVF, floor-averaged | √(1 + (H/W)²) − H/W |
infinite canyon, Hottel's crossed-strings rule |
| SVF, floor centre | cos(arctan(2H/W)) |
Oke (1987) |
| λf | frontal area / cell area; default frontal width √footprint |
definition |
| zd, z0 | zd/H = 1 + A^(−λp)(λp − 1), z0/H = (1 − zd/H) exp(−(0.5 β C_D/κ² (1 − zd/H) λf)^(−1/2)), A = 4.43, β = 1.0, C_D = 1.2, κ = 0.4 (staggered arrays) |
Macdonald, Griffiths & Hall (1998) |
| Roughness class | Davenport class whose nominal z0 (0.0002, 0.005, 0.03, 0.10, 0.25, 0.5, 1.0, ≥2 m) is nearest on a log scale | Davenport et al. (2000); nearest-class rule is this package's convention. Stewart & Oke (2012, Table 5) print 0.0005 m for class 2; 0.005 m is the Davenport-Wieringa value |
| Albedo (optional) | plan-area-weighted component albedos | approximation, ignores canyon trapping |
| Admittance, anthropogenic heat | passed through | user data |
Buildings are assigned whole to the cell containing their reference point.
Values left to the user
- Local adaptations of the LCZ property ranges (the published ranges are bundled).
- Impervious and pervious areas, surface admittance, albedo and anthropogenic heat.
- Membership softness, tolerances, weights,
min_scoreandmixed_margin.
Command line
lczlite ranges -o so2012.csv # bundled Stewart & Oke ranges as CSV
lczlite template lcz_ranges.csv # empty 17-class table for local ranges
lczlite grid buildings.csv --cell-size 200 -o cells.csv # x,y,area,height -> cells
# add impervious_area (and optional albedo, admittance, ...) to cells.csv, then:
lczlite params cells.csv --height-col height_geometric -o params.csv
lczlite classify params.csv \
--weights svf=2 --mixed-margin 0.1 --scores -o lcz.csv --summary summary.json
lczlite colours --qml lcz.qml --csv lcz_colours.csv
params expects cell_area, building_area, impervious_area and a height column, and
uses mean_footprint, street_width, frontal_area, svf, pervious_area,
admittance, albedo, anthropogenic_heat when present.
Limitations
- Range scoring is a rule-based approach on known parameters, not the WUDAPT remote-sensing workflow; it does not use training areas or satellite imagery.
- Canyon formulas assume long symmetric canyons and regular arrays; real urban fabric differs, so measured SVF and street widths are preferable where available.
- The result depends on the range table, which should be cited with the classification.
Stewart & Oke present their ranges as generic values; local fabric may need adapted
ranges (
--ranges my_ranges.csv --table-percent).
References
- Davenport, A. G., Grimmond, C. S. B., Oke, T. R. & Wieringa, J. (2000). Estimating the roughness of cities and sheltered country. 12th Conference on Applied Climatology, American Meteorological Society, 96-99.
- Demuzere, M., Kittner, J. & Bechtel, B. (2021). LCZ Generator: a web application to create Local Climate Zone maps. Frontiers in Environmental Science 9, 637455.
- Macdonald, R. W., Griffiths, R. F. & Hall, D. J. (1998). An improved method for the estimation of surface roughness of obstacle arrays. Atmospheric Environment 32(11), 1857-1864.
- Oke, T. R. (1987). Boundary Layer Climates, 2nd ed. Routledge, London.
- Stewart, I. D. & Oke, T. R. (2012). Local Climate Zones for urban temperature studies. Bulletin of the American Meteorological Society 93(12), 1879-1900. https://doi.org/10.1175/BAMS-D-11-00019.1
Academic citation
@software{eminoglu_lczlite,
author = {Eminoğlu, Yusuf},
title = {lczlite},
year = {2026},
version = {0.1.2},
doi = {10.5281/zenodo.24235562},
url = {https://gitlab.com/geophilo1/lczlite_sdk}
}
Related Geophilo SDKs
- skyview: sky view factor, topographic openness and street-canyon H/W metrics from DSMs or building footprints.
- lstcalc: land surface temperature and urban heat island metrics from Landsat 8/9 and Sentinel-2.
- spacematrix: Spacematrix urban density indicators (FSI, GSI, OSR, L).
- heatstress: heat stress indices such as the heat index, WBGT, UTCI and humidex.
License
MIT, see LICENSE.
Metadata
Release files for lczlite 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| lczlite-0.1.2.tar.gz | 49.5 kB | Without provenance | Details for lczlite-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| lczlite-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for lczlite-0.1.2-py3-none-any.whl |
Total release size: 88.3 kB
Release files / lczlite-0.1.2.tar.gz
| Download URL | lczlite-0.1.2.tar.gz |
|---|---|
| Size | 49.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
45418140f993be941b1a4f5e7e00dd8462c9c88bad339743a5472e81957a9c6f
|
|
BLAKE2b-256 checksum How to use checksums |
a81d93c221926de7761eee236d89d297fd86ca918891f82280c78cec3d465392
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Release files / lczlite-0.1.2-py3-none-any.whl
| Download URL | lczlite-0.1.2-py3-none-any.whl |
|---|---|
| Size | 38.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e7803074a116deb7f78f4b3aec7c2995af5dc68775dbb9776a024d09336a5255
|
|
BLAKE2b-256 checksum How to use checksums |
556e2843917373089eaae3da7451995c62b4c5b3ed1ce99199d027a6a55f83ea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Security for lczlite 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.