Skip to main content

lczlite

PyPI Python pipeline License: MIT DOI

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.1},
  doi     = {10.5281/zenodo.24235562},
  url     = {https://gitlab.com/geophilo1/lczlite_sdk}
}

License

MIT, see LICENSE.

Metadata

Release files for lczlite 0.1.1

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.1
File Size Uploaded Provenance Actions
lczlite-0.1.1.tar.gz 48.5 kB Without provenance Details for lczlite-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 86.8 kB

Release files / lczlite-0.1.1.tar.gz

Download URL lczlite-0.1.1.tar.gz
Size 48.5 kB
Tags Source
SHA-256 checksum
How to use checksums
71453ef535add64ec403a31f49fcb0c2016c348676fe5f3bcf3eb76a539e188b
BLAKE2b-256 checksum
How to use checksums
3b678f1e451092fe1534970a08008efc0ab9603639bff8f5feb224d89cb46176
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.1-py3-none-any.whl

Download URL lczlite-0.1.1-py3-none-any.whl
Size 38.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3246aa7d5af2013a0c8ed4e325ddc6f1e6f5d40ce07f23031955ba706c4ca5b4
BLAKE2b-256 checksum
How to use checksums
305b425bbf2329bf6532be4ba26d66c8fc401ae873adfafa3daca7e934a76ea5
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.1

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