Metadata-Version: 2.4
Name: hypercadaster_es
Version: 1.3.0
Summary: Python library to obtain the Spanish cadaster data joined with external attributes.
Home-page: https://github.com/BeeGroup-cimne
Author: Jose Manuel Broto Vispe
Author-email: jmbrotovispe@gmail.com
License: EUPL-1.2
Keywords: cadastral data,geospatial,spain,gis,real estate
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3.0,>=1.24
Requires-Dist: scipy<2.0,>=1.10
Requires-Dist: pandas<3.0,>=2.1
Requires-Dist: polars<2.0,>=1.0
Requires-Dist: scikit-learn<2.0,>=1.3
Requires-Dist: joblib>=1.3
Requires-Dist: threadpoolctl>=3.3
Requires-Dist: dask>=2024.4
Requires-Dist: cloudpickle>=3.0
Requires-Dist: toolz>=0.12
Requires-Dist: partd>=1.4
Requires-Dist: shapely<3.0,>=2.0
Requires-Dist: pyproj<4.0,>=3.5
Requires-Dist: rasterio<2.0,>=1.3
Requires-Dist: fiona<2.0,>=1.9
Requires-Dist: geopandas<1.1,>=0.13
Requires-Dist: pyogrio<1.0,>=0.8
Requires-Dist: affine>=2.4
Requires-Dist: snuggs>=1.4
Requires-Dist: pygeoif>=0.7
Requires-Dist: osmnx<2.1,>=1.8
Requires-Dist: pyrosm>=0.6
Requires-Dist: networkx>=3.2
Requires-Dist: eppy>=0.5.63
Requires-Dist: geomeppy>=0.12
Requires-Dist: pyarrow>=14.0
Requires-Dist: openpyxl>=3.1
Requires-Dist: et-xmlfile>=1.1
Requires-Dist: arrow>=1.4.0
Requires-Dist: fastkml>=1.4.0
Requires-Dist: lxml>=6.0.2
Requires-Dist: duckdb>=1.5.3
Requires-Dist: requests<3.0,>=2.31
Requires-Dist: urllib3<3,>=2.1
Requires-Dist: charset-normalizer>=3.3
Requires-Dist: idna>=3.6
Requires-Dist: certifi>=2024.2
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: soupsieve>=2.5
Requires-Dist: xmltodict>=0.13
Requires-Dist: matplotlib<4,>=3.8
Requires-Dist: contourpy>=1.2
Requires-Dist: cycler>=0.12
Requires-Dist: kiwisolver>=1.4
Requires-Dist: fonttools>=4.53
Requires-Dist: pillow>=10.2
Requires-Dist: folium>=0.20.0
Requires-Dist: click>=8.1
Requires-Dist: click-plugins>=1.1
Requires-Dist: cligj>=0.7
Requires-Dist: packaging>=23.2
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pytz>=2024.1
Requires-Dist: tzdata>=2024.1
Requires-Dist: regex<2027.0,>=2023.12
Requires-Dist: tqdm>=4.66
Requires-Dist: six>=1.16
Requires-Dist: PyYAML>=6.0
Requires-Dist: social_ES>=1.0.3
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pdoc>=14.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# hypercadaster_ES

A comprehensive Python library for downloading, processing, and analyzing Spanish cadastral data with integration of external geographic datasets and EnergyPlus model generation.

[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-EUPL%20v1.2-blue.svg)](https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12)
[![Version](https://img.shields.io/badge/version-1.1.0-green.svg)](https://github.com/BeeGroup-cimne/hypercadaster_ES)

## 🎯 Overview

**hypercadaster_ES** is a powerful Python library designed for comprehensive analysis of Spanish cadastral data. It provides tools for downloading official cadastral information, integrating it with external geographic datasets, performing advanced building analysis including geometric inference, orientation analysis, and exporting building models for energy simulation (EnergyPlus IDF).

### Key Features

- 🏘️ **Comprehensive Cadastral Data Access**: Download building and parcel data from the Spanish Cadastre, and nationwide address points from CartoCiudad (CNIG)
- 🗺️ **Multi-source Data Integration**: Merge with census tracts, postal codes, elevation models, and OpenStreetMap data
- 🧮 **Socioeconomic Enrichment**: INE indicators via `social_ES` (income atlas, population, education, dwelling stock & tenure, empty & secondary dwellings, rental & housing prices, electricity) joined per building, plus per-building Essential-Characteristics downscaling
- 🌦️ **Weather Enrichment**: Annual ERA5-Land climate indicators per building (heating/cooling degree days, precipitation, solar irradiation, temperature, humidity, wind) via `merge(weather_layer=True)`, gathered from the Copernicus analysis-ready (ARCO) Zarr stores
- 🏗️ **Advanced Building Analysis**: Geometric inference, floor footprint calculation, building space classification, shadow analysis
- 📊 **Orientation & Environmental Analysis**: Building orientation analysis, street relationships, shadow calculations, terrain analysis
- 🔌 **External Tool Integration**: Export capabilities for building energy simulation tools (EnergyPlus via eppy+geomeppy)
- 📈 **Scalable Processing**: Optimized for large-scale municipal and provincial analysis with DuckDB persistence
- ⚡ **Memory Efficient**: Central DuckDB database reduces memory footprint; heavy BLOB columns loaded on demand

## 📚 Documentation

### Getting Started
- [**Installation & Quick Start**](docs/installation-quickstart.md) - Installation methods, basic usage, and first steps
- [**Configuration & Examples**](docs/configuration-examples.md) - Advanced configuration and example workflows

### Library Reference
- [**Energy Model & Scenarios**](docs/energy-model.md) - How the EnergyPlus model is built, the occupant-behaviour model, and the scenarios
- [**Library Structure**](docs/library-structure.md) - Module overview and key entry points
- [**Data Sources & Coverage**](docs/data-sources-coverage.md) - Available datasets and geographic coverage
- [**Output Data Schema**](docs/output-schema.md) - Complete data structure and column reference
- **API Reference** - Generated from docstrings with [pdoc](https://pdoc.dev): run `./scripts/build_api_docs.sh` and open `docs/api/index.html`

### Development
- [**Contributing**](docs/contributing.md) - How to contribute to the project
- [**Changelog**](docs/changelog.md) - Version history and changes

## 🚀 Quick Start

### Library installation
```bash
pip install hypercadaster-ES
```

### Basic Usage
```python
import hypercadaster_ES as hc

# Download data for Barcelona municipality
hc.download("./data", cadaster_codes=["08900"])

# Merge all data into a unified GeoDataFrame (persisted to building_results.duckdb internally)
gdf = hc.merge("./data", cadaster_codes=["08900"])

# Optional: save the GeoDataFrame for later use (e.g., as Parquet or pickle)
gdf.to_parquet("./data/barcelona_data.parquet")  # or to_pickle(..., compression="gzip")
```

### Accessing Results via DuckDB
The central `building_results.duckdb` is the canonical artifact. Query
directly instead of materialising full GeoDataFrames:

```python
# Read inferred indicators from DB (returns pandas DataFrame)
br = hc.utils.read_br_inferred_indicators("08900", "./data")

# Fetch heavy shadow/terrain columns for one building (on demand)
heavy = hc.utils.get_heavy_columns_for_building(
    "./data", "08900", "8341105DF2884A"
)

# Access other tables via ResultsHandle (advanced)
from hypercadaster_ES import _db
handle = hc.ResultsHandle("./data/results/building_results.duckdb", "08900")
spaces_df = handle.sbr_to_pandas()  # space-level results
```

For detailed installation instructions and advanced examples, see [Installation & Quick Start](docs/installation-quickstart.md).

## 🎯 Key Applications

- **Urban Planning & Municipal Management**: Building stock analysis, zoning compliance, infrastructure planning
- **Energy & Environmental Analysis**: Building energy modeling, carbon footprint analysis
- **Real Estate & Economic Analysis**: Property valuation, market analysis, location intelligence
- **Academic Research**: Urban geography, transportation research, social sciences applications

## 📊 Geographic Coverage

- **National Coverage**: Complete coverage of peninsular Spain, Balearic Islands, Canary Islands (except Basque Country and Navarre)
- **Enhanced Coverage**: Additional Barcelona open data layers
- **Scale Range**: Individual buildings to entire autonomous communities

## 🏗️ Advanced Features

- **Building Inference Engine**: Advanced geometric analysis, floor footprint calculation, orientation analysis, shadow and terrain analysis
- **Multi-source Integration**: Cadastral, census, elevation, postal, and OpenStreetMap data
- **CAT Files Support**: Detailed building space classification from official cadastral CAT format
- **Energy Simulation Ready**: Export formats compatible with building energy simulation tools (EnergyPlus IDF via hc.energy.build_energy_model)
- **POI Proximity Analysis**: Points of interest from OpenStreetMap with distance-based indicators
- **Socioeconomic Layer**: INE indicators via `social_ES` joined at the finest geographic level (`merge(social_ES_layer=True)`), each figure taken from a single source dataset, with `ec__*` Essential-Characteristics downscaling when CAT files are used
- **Weather Layer**: Annual ERA5-Land climate indicators per building (`merge(weather_layer=True)`) — degree days, precipitation, irradiation, temperature, humidity, wind — via the Copernicus analysis-ready (ARCO) Zarr stores with `cdsapi` fallback
- **Commercial Premises Analysis**: Barcelona-specific ground floor commercial data

## 👥 Authors & Contributors

**Primary Authors:**
- **Jose Manuel Broto Vispe** - jmbrotovispe@gmail.com
- **Gerard Mor** - gmor@cimne.upc.edu

**Institutional Affiliations:**
- **CIMNE** - Centre Internacional de Mètodes Numèrics en Enginyeria, Building Energy and Environment (BEE) group
- **Universitat Politècnica de Catalunya (UPC)** - Technical University of Catalonia

## 📄 License

This project is licensed under the **EUPL v1.2**. See the [license](https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12) for details.

---

*hypercadaster_ES - Built with ❤️ for the Spanish urban analysis and building research community*

*Last updated: July 2026 | Version 1.1.0*
