UrbanWatch

1 An open-access tool for one-meter-resolution urban land cover and land use mapping across the United States © 2021-2025 Laboratory for Remote Sensing and Environmental Change (LRSEC), University of North Carolina at Charlotte Licensed under a Creative Commons license CC BY-NC 4.0 2 1. Introduction UrbanWatch was initially developed in 2021 as a 1.0-meter resolution, open-access land cover and land use (LCLU) database for 22 major cities across the United States with an overall accuracy of 91.52%. It includes nine LCLU classes: building, road, parking lot, tree canopy, grass/shrub, water, agriculture, barren, and others. The database was generated using a novel Fine-resolution, Large-area Urban Thematic information Extraction (FLUTE) framework, which integrates state-of-the-art semisupervised and deep learning architectures. The framework was trained on a benchmark dataset containing 52.43 million labeled pixels, designed to capture diverse LCLU types and spatial patterns. FLUTE effectively addresses several key challenges in large-area, high-resolution urban mapping, including view-angle effects, high intraclass and low interclass variability, and multiscale land cover heterogeneity. We are now making the mapping framework freely available to support flexible, accurate, and cost-effective urban LCLU mapping. To ensure clarity, the shared standalone software package is also referred to as UrbanWatch throughout this document. It has two main features: (i) Ease of use – Provides end-to-end processing with minimal human intervention. (ii) Strong generalization capability – Thoroughly tested across cities throughout the United States, demonstrating robust performance and adaptability. Since the initial release of UrbanWatch, we have continued to refine the model and incorporate additional training samples to enhance overall performance. Please note that UrbanWatch is optimized for urban environments across the United States. If you use UrbanWatch, please cite the following publication: Zhang, Y., Chen, G., Myint, S.W., Zhou, Y., Hay, G.J., Vukomanovic, J., & Meentemeyer, R.K. (2022). UrbanWatch: A 1-meter resolution land cover and land use database for 22 major cities in the United States. Remote Sensing of Environment, 278, 113106. The UrbanWatch software package and/or some UrbanWatch LCLU results are publicly available at the following locations: o UrbanWatch website at the University of North Carolina at Charlotte (software package and LCLU results) o Zenodo open repository (software package) o Google Earth Engine Data Catalog (LCLU results) 3 2. Model Installation Guide The UrbanWatch package includes a pre-configured environment. In most cases, place all files in the shared folder UrbanWatchModel inside your project folder. The tool can be executed directly by following the steps in Section 3: Model Use Guide. If any issue arises, please refer to Section 2: Model Installation Guide for environment setup and troubleshooting. 2.1. System Requirements (Minimum) - Operating System: Ubuntu 20.04 or later - GPU: NVIDIA GPU with CUDA support, Memory ≥8 GB - Python: Version 3.8+ - CUDA Toolkit: Compatible with your GPU and PyTorch version - NVIDIA Driver: Installed and properly configured 2.2. System Requirements (Recommended) - Operating System: Ubuntu 22.04 LTS or later - GPU: NVIDIA GPU with CUDA support, Memory ≥ 12 GB - Python: Version 3.9+ - CUDA Toolkit: Latest stable version supported by PyTorch - NVIDIA Driver: Latest stable version 2.3. Software Dependencies - Python packages (may be required; install via `pip` or `Condi` as needed) o `torch` (PyTorch with CUDA support) o `torchvision` o `numpy` o `pandas` o `opencv-python` o `scikit-learn` o `matplotlib` o `tqdm` 2.4. Installation Steps - Step 1: Update System 4 ```bash sudo apt update && sudo apt upgrade -y ``` - Step 2: Install Python 3.9+ and pip ```bash sudo apt install -y python3.9 python3.9-venv python3.9-dev python3-pip ``` - Step 3: Set Up Virtual Environment (recommended) ```bash python3.9 -m venv urbanwatch_env source urbanwatch_env/bin/activate ``` - Step 4: Install NVIDIA Drivers & CUDA (if not already installed) o Verify GPU is detected: ```bash nvidia-smi ``` o Install drivers and CUDA toolkit following [NVIDIA documentation] (https://developer.nvidia.com/cuda-downloads) - Step 5: Install PyTorch with GPU Support o Check the correct installation command at [PyTorch official site] (https://pytorch.org/get-started/locally/). Example for CUDA 11.8: ```bash pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 ``` - Step 6: o Place all files in the shared folder UrbanWatchModel inside your project folder. 5 3. Model Use Guide 3.1. Activate the Environment ```bash . conda activate urbanwatch ``` 3.2. Change Directory to the Project (where UrbanWatch is also located) Folder ```bash cd 'YOUR_PROJECT_FOLDER' ``` 3.3. Run the Program ```bash ./urbanwatch ``` Figure 1: UrbanWatch Graphic User Interface (GUI). 6 3.4. Process Imagery o In the GUI (Figure 1), click Predict Image to specify the input data folder. You may include multiple image scenes in this folder; the program will automatically process each image sequentially. o In the GUI (Figure 1), click LCLU Result to specify the output data folder. o Click Generate. All results will be saved automatically to the output data folder, using the same filenames as their corresponding input images. The output products are three-band images, which can be directly visualized as color composites without requiring any geospatial software. The legend for interpreting the output is provided below. o Important: Input data must have a 1-meter spatial resolution and contain three bands — near-infrared, red, and green. UrbanWatch is specifically designed to process three-band imagery, and the presence of a near-infrared band is essential for reliable performance. 3.5. Add Projection to the LCLU Images (Optional) o The UrbanWatch output images do not include spatial projection information by default. However, projection can be easily added by following the steps below. o Create three folders:  Folder 1: Place the original optical images.  Folder 2: Place the LCLU images generated by UrbanWatch (without projection).  Folder 3: Create an empty folder where the newly projected images will be saved. o Open and edit the provided Python script GeoTIFF_Projection.py:  Locate INPUT_IMAGE_DIR and set it to the path of Folder 1.  Locate LC_RESULT_DIR and set it to the path of Folder 2.  Locate OUTPUT_DIR and set it to the path of Folder 3. o Run the script GeoTIFF_Projection.py to generate the projected GeoTIFF images. 3.6. Display the LCLU Image Color Scheme Properly in ArcGIS Pro (Optional) o To visualize the UrbanWatch LCLU images properly in ArcGIS Pro, load the images and set the Stretch Type to None in the Symbology settings. This 7 ensures that the displayed colors match the exact color scheme described in Section 3.4. 3.7. Generate Single-Band LCLU Maps from the Three-Band Products (Optional) o The UrbanWatch LCLU results are three-band images. To generate singleband LCLU maps from the three-band products, use the provided Python script RGB2Classify.py within the ArcGIS Pro Python environment. o If you are using ArcGIS Pro on Windows, open the Python environment by navigating to: Start → ArcGIS Pro Folder → Jupyter Notebook → New → Python. o Copy and paste the provided code into the new notebook, then update the input and output directory paths to specify where to read and save your data. o In the generated single-band images, each pixel value corresponds to a specific LCLU class: 0 – Building, 1 – Road, 2 – Parking Lot, 3 – Forest, 4 – Grass/Shrub, 5 – Agriculture, 6 – Water, 7 – Barren, and 8 – Others.