Skip to main content

lczlite

PyPI Python pipeline License: MIT

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 .qml palette, 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_score and mixed_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.0},
  url     = {https://gitlab.com/geophilo1/lczlite_sdk}
}

License

MIT, see LICENSE.

Metadata

Release files for lczlite 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lczlite 0.1.0
File Size Uploaded Provenance Actions
lczlite-0.1.0.tar.gz 48.1 kB Without provenance Details for lczlite-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lczlite 0.1.0
File Interpreter ABI Platform Actions
lczlite-0.1.0-py3-none-any.whl Python 3 none any Details for lczlite-0.1.0-py3-none-any.whl

Total release size: 86.4 kB

Release files / lczlite-0.1.0.tar.gz

Download URL lczlite-0.1.0.tar.gz
Size 48.1 kB
Tags Source
SHA-256 checksum
How to use checksums
c1b976d91a5ebb51875ec2d93eaa45d8013aa8b5f072878e6a32877cc4bb3d56
BLAKE2b-256 checksum
How to use checksums
6ee6db05cabd6977e118191666503f29aab027fcc62755c87de0a95c6e4ad390
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.0-py3-none-any.whl

Download URL lczlite-0.1.0-py3-none-any.whl
Size 38.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0d70b32b55fdf8951487e479c856f140e22a8a30bd00457514894873a81d5c41
BLAKE2b-256 checksum
How to use checksums
5ded7c49323e7db1fa67a3206f268fb7f1cc0c00453f66e0cea6904788d620ad
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.0

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page