WEB APPLICATION FOR REFINING LOCAL CLIMATE ZONE CLASSIFICATION USING BUILDING FLOOR DATA

ABSTRACT

This study presents a web-based application designed to refine Local Climate Zone (LCZ) classification using building height data. The tool addresses limitations of satellite-based LCZ mapping by integrating vector information from building datasets. Input data include a GeoTIFF LCZ raster and a Shapefile with building height attributes. Using libraries such as Rasterio, GeoPandas, and Shapely, the system performs spatial overlay, categorizes buildings by height, and applies logical rules to reclassify LCZ cells. The result is a more accurate representation of urban morphology, validated through comparative visualizations. Unlike traditional workflows, this method avoids retraining classifiers, reducing time and resource costs. The application is suitable for urban climate modeling and planning, with potential integration into models like WRF. It supports microclimate research and scenario analysis, offering a practical and efficient tool for updating LCZ maps in response to urban development.

АННОТАЦИЯ

В данном исследовании представлено веб-приложение для уточнения классификации локальных климатических зон (LCZ) с использованием данных о высоте зданий. Разработанный инструмент устраняет ограничения спутниковой классификации LCZ за счёт интеграции векторной информации из слоя зданий. Входные данные включают растровую карту LCZ в формате GeoTIFF и векторный слой в формате Shapefile с атрибутами высотности. С помощью библиотек Rasterio, GeoPandas и Shapely система выполняет пространственное сопоставление, классификацию по этажности и логическую переклассификацию ячеек. Результатом является более точное отображение городской морфологии, подтверждённое сравнительными визуализациями. В отличие от традиционного подхода, метод позволяет избежать повторного обучения моделей, снижая трудозатраты и ресурсоёмкость. Приложение подходит для моделирования городского климата и планирования, с возможной интеграцией в атмосферные модели, такие как WRF. Оно поддерживает микроклиматические исследования и сценарный анализ, обеспечивая эффективное обновление карт LCZ с учётом изменений в городской застройке.

Keywords: local climate zone, application, building height, classification, urban area.

Ключевые слова: локальная климатическая зона, приложение, высота зданий, классификация, городская территория.

Introduction

Local Climate Zones (LCZ) represent a standardized classification system developed to characterize urban and natural environments based on their morphological and thermal properties. Initially proposed by Stewart and Oke [[1]], the LCZ framework has become a foundational tool in urban climate research, particularly for studying the urban heat island effect. Its structured typology supports a unified approach to analyzing urban form and land cover, making it suitable for global applications regardless of geographic context.

LCZ maps are a key component of the WUDAPT (World Urban Database and Access Portal Tools) initiative [[2]], which facilitates large-scale climate modeling, urban planning, and environmental analysis. A systematic review of 115 LCZ-related publications from European cities [[3]] confirms the growing adoption of this method in studies of urban microclimates, especially when paired with numerical models like WRF and ENVI-met. Recent advancements focus on automating classification processes, improving the representation of urban morphology particularly building height and integrating new data sources such as Sentinel imagery and UAV surveys.

Multiple studies have demonstrated the value of incorporating LCZ maps into mesoscale atmospheric models. For example, researchers in Madrid and Szeged [[4]] showed that LCZ-based input data significantly improved the simulation of temperature distribution and urban thermal gradients compared to traditional land use classifications. Similar benefits were observed in Hong Kong [[5]], where LCZ and Building Category (BC) data enhanced estimates of air temperature and cooling energy demand. In Beijing, integrating LCZ into WRF improved the accuracy of daily heat flux simulations [[6]]. Furthermore, in fast-developing regions such as Ahmedabad, India [[7]], the inclusion of LCZ data improved the spatial and temporal modeling of extreme precipitation events.

Despite their advantages, traditional LCZ classification methods primarily based on satellite imagery and training polygons often fail to accurately capture vertical urban structure. While surface parameters such as vegetation or built-up density can be extracted from optical data, building height remains a critical blind spot. This leads to classification errors, particularly in areas where vertical morphology plays a significant role in determining local climatic conditions.

This research addresses the gap by proposing a web-based application that enhances existing LCZ maps through the integration of vector building data enriched with height attributes. By correcting initial classification outputs based on building height distributions, the application produces more reliable and morphologically consistent LCZ maps. This refinement is crucial for improving the input quality of urban climate models and supporting evidence-based decision-making in urban planning.

Materials and methods

Refinement of the Almaty LCZ Map Based on Remote Sensing and Building Height Data

The concept of Local Climate Zones (LCZ) provides a standardized framework for classifying urban and natural landscapes based on their surface characteristics and thermal behavior. Each LCZ represents a spatial unit of relatively homogeneous morphology and land use, typically covering areas from several hundred meters to a few kilometers in extent. The classification is grounded in a set of physical parameters, including building height and density, surface material composition, vegetation fraction, albedo, and permeability.

According to the LCZ scheme, urban areas are categorized into ten classes (LCZ 1–10), each reflecting distinct morphological configurations, while seven additional classes (LCZ A–G) represent various types of natural terrain. Among these parameters, building height plays a crucial role in determining LCZ type, as it directly affects surface roughness, heat storage, and airflow patterns. Table 1 summarizes the typical building height ranges associated with each LCZ class, as defined in the standardized classification guidelines [1].

Table 1.

Description of LCZ Classes

LCZ maps are generally generated using semi-automated classification techniques applied to satellite imagery. A key step in this process is the preparation of training samples (polygons) that represent each LCZ type. One widely used tool for this purpose is the LCZ Generator, a cloud-based application developed by the WUDAPT initiative in collaboration with Ruhr University Bochum [[8]]. This tool was used to generate the LCZ map for Almaty, shown in Figure 1., which formed the foundation for subsequent environmental modeling studies in the region.

This initial classification has been employed in urban climate modeling to simulate wind patterns and thermal regimes, particularly in studies assessing air pollution dispersion across Almaty [[9], [10]]. However, a comparison between simulated and observed data revealed notable discrepancies, indicating potential classification inaccuracies stemming from the automatic generalization of raster cells.

Subsequent validation using a vector building dataset with detailed height attributes revealed inconsistencies in the LCZ classification. Specifically, there were areas where the assigned LCZ class did not reflect the dominant building height within a given cell.

Figure 1. LCZ map of Almaty region

To address these inconsistencies, this study proposes a methodology for refining the LCZ map by integrating building height data. The developed application identifies mismatches between LCZ classes and actual building characteristics, and automatically adjusts classifications where the height distribution diverges from the class definition. This refinement enhances the morphological accuracy of LCZ maps, thereby improving their reliability for climate modeling, urban heat island analysis, and related urban planning applications.

Building Height Data

Accurate and current information on building heights is a critical component for refining LCZ maps. A widely accessible source of such data is the OpenStreetMap (OSM) project a collaborative, openly editable mapping platform modeled after the principles of Wikipedia. OSM offers detailed spatial information on urban infrastructure, including building footprints and classifications, although the level of data completeness varies by region and depends on the engagement of local contributors.

Of particular relevance to urban morphology studies is the availability of building height attributes. In the case of Almaty, individual buildings in OSM often include metadata such as the number of floors, provided through the building:levels tag. This attribute serves as a practical proxy for estimating the vertical structure of the urban environment and is frequently used in the context of LCZ classification refinement and related geospatial analyses.

System Architecture

The LCZ refinement tool is a modular web-based application built on a modern technology stack and designed following microservice architecture principles. The backend and frontend operate independently, communicating through a RESTful API. The application includes three main components:

1. Frontend – Developed with Next.js [[11]] and React [[12]], it offers a responsive interface for uploading data, configuring analysis settings, and viewing results. The UI adapts well to various screen sizes, ensuring usability across devices.
2. Backend – Powered by FastAPI [[13]], the backend manages requests, asynchronous tasks, and core logic. It is optimized for efficient geospatial processing and resource management.
3. Data Processing Module – Utilizes GeoPandas [[14]], Rasterio [[15]] and Shapely[[16]] for spatial computations and implements the algorithms needed for LCZ analysis and classification correction.

Frontend-backend communication is facilitated via a REST API with an integrated proxy to resolve CORS issues and streamline request handling.

Backend Implementation

The backend is developed using the FastAPI framework, offering high performance, asynchronous request handling, and automatic API documentation. The RESTful API design includes well-structured endpoints with path and query parameters for clear task configuration.

A specialized stack of Python libraries supports geospatial data processing:

• GeoPandas for managing vector data,
• Shapely for geometric operations,
• Rasterio for reading/writing raster files,
• PyProj for spatial reference transformations [[17]].

These tools are integrated into a unified workflow: buildings are spatially linked to LCZ raster cells, analyzed, and reclassified if necessary. Final outputs are exported in GeoJSON/JSON formats for further use and visualization.

The core algorithm refines LCZ classes using building height data. Vector building data is categorized into low-, mid-, and high-rise groups. Each raster cell is evaluated based on the dominant building height within it, and LCZ classes are adjusted accordingly to improve morphological accuracy.

Asynchronous processing allows the backend to remain responsive while handling large computations. FastAPI’s background task system executes long-running operations in separate threads, returning a task ID to the client for status tracking. Robust logging and exception handling ensure system stability and user feedback.

Frontend Implementation

The frontend is built with Next.js and React, using a modular architecture with reusable components. State management is handled via React hooks and Zustand, while map rendering is performed with Leaflet and data visualization with ECharts. Styling is done using shadcn/ui and Tailwind CSS for a clean and responsive interface. Communication with the backend occurs via a proxy API in Next.js, which avoids CORS issues and hides backend URLs. Components handle file upload, task tracking, map visualization, and display of classification results. LeafletMapComponent renders the interactive map, while MapSelector allows switching between data layers. MapViewer combines maps with image and analytics tabs, supporting comparison of original and corrected LCZ data. Zustand maintains global state, synchronizing UI components like task status and history. A transition matrix and statistical charts support change analysis.

Deployment & Performance

The application is containerized with Docker, deployed using Coolify and Traefik for automatic HTTPS and traffic compression. Performance optimizations include:

• asynchronous data handling,
• spatial indexing,
• chunked raster processing,
• and multi-core parallel computation.

Security measures include strict input validation, process isolation, file size limits, and per-task sandboxing. This architecture ensures robust, scalable, and secure processing of large geospatial datasets, making the LCZ correction tool accessible and reliable for researchers and planners.

Results and discussion

On the application's start page, the user is prompted to upload the required input data, consisting of two essential components: a raster file representing the initial Local Climate Zone (LCZ) classification and a vector file (Shapefile format) containing information on building heights. These datasets are critical for enabling spatial comparison and subsequent reclassification. In cases where only one of the required files is uploaded—either the raster or the vector layer—the system identifies the incomplete input and issues an error notification, halting further processing until both files are provided.

Following the successful upload, the user is asked to define threshold values for each building height category—low-rise, mid-rise, and high-rise. These thresholds, expressed as percentages of the minimum cell coverage area, determine the influence of each building type on LCZ reclassification. By allowing users to specify these thresholds, the system supports algorithm customization according to the morphological characteristics of the study area and the desired sensitivity of the analysis.

Upon clicking the "Upload and Process" button, the user is redirected to the output page. This section offers access to three result formats: geospatial maps, image previews, and analytical summaries of the transformations performed during the reclassification procedure.

The “Maps” tab allows users to visually compare the original LCZ classification, building height data, and the corrected classification, reflecting the outcomes of the reclassification algorithm based on user-defined coverage thresholds (see Figure 2). The interface presents three synchronized maps: the original LCZ map, the spatial distribution of building heights, and the final reclassified LCZ map. All maps are interactive, supporting zooming, panning, and layer switching, which facilitates visual verification of classification accuracy.

Figure 2. Output the “Maps” tab of LCZ classification API

The “Photographs” tab presents a series of visual outputs illustrating key stages of spatial analysis and data transformation (see Figure 3). These include overlays of building geometries on LCZ raster cells, comparative diagrams of LCZ and building height distributions, final maps highlighting classification changes, and heatmaps of LCZ transitions. These visual materials support inspection and validation of the reclassification logic and enhance interpretability of the results.

Figure 3. The “Photographs” tab

The “Analytics” tab provides a summary of the spatial analysis results (see Figure 4). At the top, key metrics are displayed: the total number of grid cells, the number of modified cells, and the percentage of changes. Below, charts and heatmaps illustrate the distribution of LCZ classes before and after reclassification, as well as the transition dynamics. The analysis highlights the dominant directions and scale of changes in urban morphology.

Additionally, the “Class Data” section contains detailed statistics for each LCZ class, including the total number of cells, number of modified cells, and percentage change. The “Transitions Between Classes” section provides a transition matrix showing how LCZ classes have changed between the original and updated classifications, indicating the stability of initial assignments and the nature of corrections applied.

Figure 4. The “Analytics” tab

Figure 5 demonstrates how the application refines LCZ classification in compact urban areas. In the southeastern part of the map, several cells initially labeled as LCZ 1 (compact high-rise) were reclassified as LCZ 3 (compact low-rise) after analyzing the prevailing building heights within those pixels. This correction is particularly relevant for urban climate modeling, as LCZ 1 and LCZ 3 have significantly different physical and thermal characteristics misclassification between them can lead to substantial inaccuracies in simulated heat fluxes, airflow patterns, and pollutant dispersion.

This example, among others, highlights the application’s ability to resolve both overestimation and underestimation of LCZ classes. By applying a set of logical rules and thresholds to real-world morphological data, the system improves the alignment between classification outputs and actual urban structure. Such refinement is crucial for enhancing the reliability of climate simulations and urban planning decisions.

Figure 5. Comparison of the original (a) and corrected (b) LCZ maps

The application provides a rapid and precise mechanism for adjusting LCZ classifications using building height information. One of its key strengths lies in enabling selective post-classification corrections without requiring full retraining of classification models. This allows for flexible and efficient updates in targeted urban zones based on vector building data.

Conclusion

The developed software application is a tool for post-classification refinement of Local Climate Zone (LCZ) maps based on attribute data from a vector layer containing information on building heights.

The primary objective of this solution is to improve the accuracy of LCZ classification by incorporating the vertical structure of urban development—a parameter often inadequately captured by conventional satellite image-based classification.

By integrating vector data, the application enables selective refinement of specific urban areas without the need to re-run the entire traditional mapping workflow, which typically includes image preprocessing, training polygon generation, and classifier training. This approach significantly reduces computational costs and supports timely updates of LCZ maps in response to evolving urban morphology.

An additional advantage is the application’s potential for use in scenario modeling, particularly for evaluating the impact of alternative development strategies on the urban microclimate. This functionality makes the tool especially valuable for urban planning professionals, providing a basis for evidence-based design and assessment of different urban development scenarios.

In the future, the system may be extended to incorporate additional building attributes such as construction materials or vegetation density—and integrated with atmospheric models (e.g., WRF), enabling more comprehensive analyses of climate processes in urbanized environments.

References:

1. Stewart I.D., Oke T.R. Local climate zones for urban temperature studies // Bulletin of the American Meteorological Society. – 2012. – Vol. 93, № 12. – P. 1879–1900. – DOI: 10.1175/BAMS-D-11-00019.1.
2. WUDAPT. World Urban Database and Access Portal Tools Available at: http://www.wudapt.org/ (accessed 20.04.2025).
3.  Lehnert M., Savić S., Milošević D., Dunjić J., Geletič J. Mapping Local Climate Zones and Their Applications in European Urban Environments: A Systematic Literature Review and Future Development Trends // ISPRS International Journal of Geo-Information. – 2021. – Vol. 10, № 4. – Article 260. – DOI: 10.3390/ijgi10040260.
4. Molnár G., Gyöngyösi A.Z., Gál T. Integration of an LCZ-based classification into WRF to assess the intra-urban temperature pattern under a heatwave period in Szeged, Hungary // Theoretical and Applied Climatology. – 2019. – Vol. 138. – P. 1139–1158. – DOI: 10.1007/s00704-019-02881-1.
5.  Du R., et al. Effect of local climate zone (LCZ) and building category (BC) classification on the simulation of urban climate and air-conditioning load in Hong Kong // Energy. – 2023. – Vol. 271. – Article 127004. – DOI: 10.1016/j.energy.2023.127004.
6. Mu Q., Miao S., Wang Y., et al. Evaluation of employing local climate zone classification for mesoscale modelling over Beijing metropolitan area // Meteorology and Atmospheric Physics. – 2020. – Vol. 132. – P. 315–326. – DOI: 10.1007/s00703-019-00692-7.
7. Patel P., et al. Improved simulation of very heavy rainfall events by incorporating WUDAPT urban land use/land cover in WRF // Urban Climate. – 2020. – Vol. 32. – Article 100616. – DOI: 10.1016/j.uclim.2020.100616.
8. Demuzere M., Kittner J., Bechtel B. LCZ Generator: a web application to create Local Climate Zone maps // Frontiers in Environmental Science. – 2021. – Vol. 9. – Article 637455. – DOI: 10.3389/fenvs.2021.637455.
9. Dedova T., Balakay L., Zakarin E., Bostanbekov K., Abdimanap G. Investigating Stagnant Air Conditions in Almaty: A WRF Modeling Approach // Atmosphere. – 2024. – Vol. 15, № 6. – Article 633. – DOI: 10.3390/atmos15060633.
10. Dedova T., Balakay L., Zakarin E., Bostanbekov K., Abdimanap G. High-Resolution WRF Modeling of Wind and Thermal Regimes with LCZ in Almaty, Kazakhstan // Atmosphere. – 2024. – Vol. 15, № 8. – Article 966. – DOI: 10.3390/atmos15080966.
11. The React Framework for the Web. Available at: https://nextjs.org (accessed 20.04.2025).
12. React. The library for web and native user interfaces. Available at:  https://react.dev/ (accessed 20.04.2025).
13.  FastAPI framework, high performance, easy to learn, fast to code, ready for production Available at: https://fastapi.tiangolo.com/ (accessed 20.04.2025).
14. GeoPandas 1.0.1. Available at: https://geopandas.org/en/stable/ (accessed 20.04.2025).
15. Rasterio 1.3.11: Fast and direct raster I/O for use with Numpy and SciPy Available at:https://pypi.org/project/rasterio/ (accessed 20.04.2025).
16.  The Shapely User Manual. Available at: https://shapely.readthedocs.io/en/stable/manual.html (accessed 20.04.2025).
17. Python interface to PROJ (cartographic projections and coordinate transformations library). Available at: https://pyproj4.github.io/pyproj/stable/ (accessed 20.04.2025).