urban-imageable 0.1.0__tar.gz

urban_imageable-0.1.0/.gitignore

@@ -0,0 +1,54 @@
+# Python
+cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+.coverage.*

urban_imageable-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2025, Scalable Design Participation Lab
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

urban_imageable-0.1.0/PKG-INFO

@@ -0,0 +1,319 @@
+Metadata-Version: 2.4
+Name: urban-imageable
+Version: 0.1.0
+Summary: Computer vision library for extracting 43+ building properties from street view images and footprints
+Project-URL: Homepage, https://github.com/scalable-design-participation-lab/imageable
+Project-URL: Bug Tracker, https://github.com/scalable-design-participation-lab/imageable/issues
+Project-URL: Documentation, https://github.com/scalable-design-participation-lab/imageable#readme
+Author-email: Khoi Ngo <ngo.kho@northeastern.edu>, Uriel Legaria <fill@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: building-analysis,computer-vision,geospatial,gis,height-estimation,segmentation,street-view,urban-planning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.13
+Requires-Dist: cmcrameri>=1.9
+Requires-Dist: geopandas>=1.1.1
+Requires-Dist: libpysal>=4.13.0
+Requires-Dist: lu-vp-detect>=1.0.4
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: numpy>=2.2.6
+Requires-Dist: osmnx>=2.0.6
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: pillow>=11.2.1
+Requires-Dist: pydeck>=0.9.1
+Requires-Dist: scikit-image>=0.19.0
+Requires-Dist: scikit-learn>=1.7.2
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: shapely>=2.1.1
+Requires-Dist: spopt>=0.7.0
+Requires-Dist: tensorboardx>=2.6.4
+Requires-Dist: timm>=1.0.21
+Requires-Dist: torch>=2.7.1
+Requires-Dist: transformers>=4.52.4
+Requires-Dist: ultralytics>=8.4.0
+Description-Content-Type: text/markdown
+
+# imageable
+
+[![Tests](https://github.com/scalable-design-participation-lab/imageable/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/scalable-design-participation-lab/imageable/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/imageable.svg)](https://badge.fury.io/py/imageable)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+An open-source Python library for extracting **43+ building properties** from street view images and building footprints. Designed for urban planners, architects, climate resilience researchers, and GIS professionals.
+
+![Imageable](./imageable.png)
+
+## Features
+
+- **Height Estimation**: Estimate building heights from single street-level images using vanishing point detection and semantic segmentation
+- **Material Analysis**: Segment and quantify façade materials (brick, glass, concrete, etc.)
+- **Footprint Properties**: Extract 21 geometric, engineered, and contextual features from building polygons
+- **Image Features**: Analyze color, shape, and façade characteristics from street view images
+- **Batch Processing**: Process entire neighborhoods via GeoDataFrames or GeoJSON files
+
+## Installation
+
+```bash
+pip install urban-imageable
+```
+
+### For Development
+
+```bash
+# Clone the repository
+git clone https://github.com/scalable-design-participation-lab/imageable.git
+cd imageable
+
+# Install with uv (recommended)
+uv sync --group dev
+```
+
+## Quick Start
+
+### Single Building Analysis
+
+```python
+import imageable
+from shapely.geometry import Polygon
+
+# Define building footprint (WGS84 coordinates)
+footprint = Polygon([
+    (-71.0589, 42.3601),
+    (-71.0585, 42.3601),
+    (-71.0585, 42.3605),
+    (-71.0589, 42.3605),
+])
+
+# Get street view image
+image, metadata = imageable.get_image(api_key, footprint)
+
+# Extract all 43+ properties
+props = imageable.get_dataset(api_key, footprint)
+print(f"Estimated height: {props.building_height}m")
+print(f"Projected area: {props.projected_area}m²")
+print(f"Shape complexity: {props.complexity}")
+```
+
+### Batch Processing from GeoDataFrame
+
+```python
+import geopandas as gpd
+import imageable
+
+# Load building footprints
+gdf = gpd.read_file("buildings.geojson")
+
+# Extract properties for all buildings
+result = imageable.get_building_data_from_gdf(
+    gdf,
+    api_key,
+    id_column="building_id",
+    neighbor_radius=100.0,  # meters
+    verbose=True,
+)
+
+# Result is a GeoDataFrame with 43+ new columns
+print(result.columns)
+```
+
+### From GeoJSON File
+
+```python
+import imageable
+
+# Process directly from GeoJSON
+result = imageable.get_building_data_from_geojson(
+    "buildings.geojson",
+    api_key,
+    output_format="gdf",  # or "geojson", "dict"
+)
+```
+
+### With Pre-downloaded Images
+
+```python
+import imageable
+
+# Process from local footprints and images
+result = imageable.get_building_data_from_file(
+    "footprints.geojson",
+    "images/",  # Directory containing images named by building ID
+    id_column="building_id",
+)
+```
+
+## Extracted Properties
+
+### Footprint Properties (21 features)
+
+**Geometric (6):**
+- `unprojected_area`, `projected_area`: Area in original and projected CRS
+- `longitude_difference`, `latitude_difference`: Bounding box dimensions
+- `n_vertices`: Number of polygon vertices
+- `shape_length`: Perimeter length
+
+**Engineered (5):**
+- `complexity`: Perimeter/area ratio
+- `inverse_average_segment_length`: Edge length metric
+- `vertices_per_area`: Vertex density
+- `average_complexity_per_segment`: Segment-level complexity
+- `isoperimetric_quotient`: Circularity measure (4πA/P²)
+
+**Contextual (10):**
+- `neighbor_count`: Number of buildings within radius
+- `mean_distance_to_neighbors`: Average centroid distance
+- `nearest_neighbor_distance`: Distance to closest building
+- `n_size_mean/std/min/max/cv`: Neighbor area statistics
+- `expected_nearest_neighbor_distance`: Random distribution expectation
+- `nni`: Nearest neighbor index
+
+### Height Estimation
+
+- `building_height`: Estimated height in meters using CV pipeline (vanishing points + segmentation)
+
+### Image Features (16 features)
+
+**Color (5):**
+- `average_red/green/blue_channel_value`: RGB means
+- `average_brightness`: HSV brightness percentage
+- `average_vividness`: HSV saturation percentage
+
+**Shape (5):**
+- `mask_area`: Segmented building pixels
+- `mask_length`: Boundary perimeter
+- `mask_complexity`: Length/area ratio
+- `number_of_edges`, `number_of_vertices`: Polygon complexity
+
+**Façade (6):**
+- `average_window_x/y`: Window centroid location
+- `average_door_x/y`: Door centroid location
+- `number_of_windows`, `number_of_doors`: Element counts
+
+### Material Percentages
+
+- `material_percentages`: Dictionary of façade material coverage (brick, glass, concrete, metal, etc.)
+
+## API Reference
+
+### Main Functions
+
+```python
+# Batch processing
+imageable.get_building_data_from_gdf(gdf, api_key, ...)
+imageable.get_building_data_from_geojson(source, api_key, ...)
+imageable.get_building_data_from_file(footprints, images_dir, ...)
+
+# Single building
+imageable.get_dataset(api_key, footprint, ...)
+imageable.get_image(api_key, footprint, ...)
+
+# Data class
+imageable.BuildingProperties
+```
+
+### BuildingProperties
+
+```python
+from imageable import BuildingProperties
+
+# Create and populate
+props = BuildingProperties(building_id="b001")
+props.update_footprint_features(footprint_dict)
+props.update_height(25.5)
+props.update_material_percentages({"brick": 60.0, "glass": 40.0})
+
+# Export
+props.to_dict()  # Dictionary
+props.to_json("output.json")  # JSON file
+props.get_feature_vector()  # NumPy array for ML
+
+# Import
+props = BuildingProperties.from_dict(data)
+props = BuildingProperties.from_json("input.json")
+```
+
+## Requirements
+
+- Python 3.13+
+- Google Street View API key (for image acquisition and height estimation)
+- See `pyproject.toml` for full dependency list
+
+## Development
+
+```bash
+# Run tests
+uv run pytest
+
+# Run tests with coverage
+uv run pytest --cov-report=html
+open htmlcov/index.html
+
+# Lint and format
+uv run pre-commit run --all-files
+
+# Build package
+uv build
+```
+
+## Project Structure
+
+```
+imageable/
+├── src/imageable/
+│   ├── core/              # Public API
+│   │   ├── building_data.py   # Batch processing
+│   │   ├── dataset.py         # Single building extraction
+│   │   └── image.py           # Image acquisition
+│   ├── _extraction/       # Property extraction
+│   │   ├── building.py        # BuildingProperties dataclass
+│   │   ├── extract.py         # Main orchestrator
+│   │   ├── footprint.py       # Footprint features
+│   │   └── image.py           # Image features
+│   ├── _features/         # Feature pipelines
+│   │   ├── height/            # Height estimation
+│   │   └── materials/         # Material segmentation
+│   ├── _images/           # Image acquisition
+│   │   ├── camera/            # Camera parameters
+│   │   └── download.py        # Street View API
+│   └── _models/           # ML models
+│       ├── huggingface/       # SegFormer segmentation
+│       ├── lcnn/              # Line detection
+│       └── vpts/              # Vanishing points
+└── tests/                 # Test suite
+```
+
+## Citation
+
+If you use imageable in your research, please cite:
+
+```bibtex
+@software{imageable2025,
+  author = {Ngo, Khoi and Legaria, Uriel and Sandoval Olascoaga, Carlos},
+  title = {imageable: Computer Vision Library for Urban Building Analysis},
+  year = {2025},
+  url = {https://github.com/scalable-design-participation-lab/imageable}
+}
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Authors
+
+- Khoi Ngo ([Khoi Ngo](https://github.com/billnqk)) - ngo.kho@northeastern.edu
+- Uriel Legaria
+- Carlos Sandoval Olascoaga
+
+
+Developed at the [Scalable Design Participation Lab](https://github.com/scalable-design-participation-lab), Northeastern University.

urban_imageable-0.1.0/README.md

@@ -0,0 +1,275 @@
+# imageable
+
+[![Tests](https://github.com/scalable-design-participation-lab/imageable/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/scalable-design-participation-lab/imageable/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/imageable.svg)](https://badge.fury.io/py/imageable)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+An open-source Python library for extracting **43+ building properties** from street view images and building footprints. Designed for urban planners, architects, climate resilience researchers, and GIS professionals.
+
+![Imageable](./imageable.png)
+
+## Features
+
+- **Height Estimation**: Estimate building heights from single street-level images using vanishing point detection and semantic segmentation
+- **Material Analysis**: Segment and quantify façade materials (brick, glass, concrete, etc.)
+- **Footprint Properties**: Extract 21 geometric, engineered, and contextual features from building polygons
+- **Image Features**: Analyze color, shape, and façade characteristics from street view images
+- **Batch Processing**: Process entire neighborhoods via GeoDataFrames or GeoJSON files
+
+## Installation
+
+```bash
+pip install urban-imageable
+```
+
+### For Development
+
+```bash
+# Clone the repository
+git clone https://github.com/scalable-design-participation-lab/imageable.git
+cd imageable
+
+# Install with uv (recommended)
+uv sync --group dev
+```
+
+## Quick Start
+
+### Single Building Analysis
+
+```python
+import imageable
+from shapely.geometry import Polygon
+
+# Define building footprint (WGS84 coordinates)
+footprint = Polygon([
+    (-71.0589, 42.3601),
+    (-71.0585, 42.3601),
+    (-71.0585, 42.3605),
+    (-71.0589, 42.3605),
+])
+
+# Get street view image
+image, metadata = imageable.get_image(api_key, footprint)
+
+# Extract all 43+ properties
+props = imageable.get_dataset(api_key, footprint)
+print(f"Estimated height: {props.building_height}m")
+print(f"Projected area: {props.projected_area}m²")
+print(f"Shape complexity: {props.complexity}")
+```
+
+### Batch Processing from GeoDataFrame
+
+```python
+import geopandas as gpd
+import imageable
+
+# Load building footprints
+gdf = gpd.read_file("buildings.geojson")
+
+# Extract properties for all buildings
+result = imageable.get_building_data_from_gdf(
+    gdf,
+    api_key,
+    id_column="building_id",
+    neighbor_radius=100.0,  # meters
+    verbose=True,
+)
+
+# Result is a GeoDataFrame with 43+ new columns
+print(result.columns)
+```
+
+### From GeoJSON File
+
+```python
+import imageable
+
+# Process directly from GeoJSON
+result = imageable.get_building_data_from_geojson(
+    "buildings.geojson",
+    api_key,
+    output_format="gdf",  # or "geojson", "dict"
+)
+```
+
+### With Pre-downloaded Images
+
+```python
+import imageable
+
+# Process from local footprints and images
+result = imageable.get_building_data_from_file(
+    "footprints.geojson",
+    "images/",  # Directory containing images named by building ID
+    id_column="building_id",
+)
+```
+
+## Extracted Properties
+
+### Footprint Properties (21 features)
+
+**Geometric (6):**
+- `unprojected_area`, `projected_area`: Area in original and projected CRS
+- `longitude_difference`, `latitude_difference`: Bounding box dimensions
+- `n_vertices`: Number of polygon vertices
+- `shape_length`: Perimeter length
+
+**Engineered (5):**
+- `complexity`: Perimeter/area ratio
+- `inverse_average_segment_length`: Edge length metric
+- `vertices_per_area`: Vertex density
+- `average_complexity_per_segment`: Segment-level complexity
+- `isoperimetric_quotient`: Circularity measure (4πA/P²)
+
+**Contextual (10):**
+- `neighbor_count`: Number of buildings within radius
+- `mean_distance_to_neighbors`: Average centroid distance
+- `nearest_neighbor_distance`: Distance to closest building
+- `n_size_mean/std/min/max/cv`: Neighbor area statistics
+- `expected_nearest_neighbor_distance`: Random distribution expectation
+- `nni`: Nearest neighbor index
+
+### Height Estimation
+
+- `building_height`: Estimated height in meters using CV pipeline (vanishing points + segmentation)
+
+### Image Features (16 features)
+
+**Color (5):**
+- `average_red/green/blue_channel_value`: RGB means
+- `average_brightness`: HSV brightness percentage
+- `average_vividness`: HSV saturation percentage
+
+**Shape (5):**
+- `mask_area`: Segmented building pixels
+- `mask_length`: Boundary perimeter
+- `mask_complexity`: Length/area ratio
+- `number_of_edges`, `number_of_vertices`: Polygon complexity
+
+**Façade (6):**
+- `average_window_x/y`: Window centroid location
+- `average_door_x/y`: Door centroid location
+- `number_of_windows`, `number_of_doors`: Element counts
+
+### Material Percentages
+
+- `material_percentages`: Dictionary of façade material coverage (brick, glass, concrete, metal, etc.)
+
+## API Reference
+
+### Main Functions
+
+```python
+# Batch processing
+imageable.get_building_data_from_gdf(gdf, api_key, ...)
+imageable.get_building_data_from_geojson(source, api_key, ...)
+imageable.get_building_data_from_file(footprints, images_dir, ...)
+
+# Single building
+imageable.get_dataset(api_key, footprint, ...)
+imageable.get_image(api_key, footprint, ...)
+
+# Data class
+imageable.BuildingProperties
+```
+
+### BuildingProperties
+
+```python
+from imageable import BuildingProperties
+
+# Create and populate
+props = BuildingProperties(building_id="b001")
+props.update_footprint_features(footprint_dict)
+props.update_height(25.5)
+props.update_material_percentages({"brick": 60.0, "glass": 40.0})
+
+# Export
+props.to_dict()  # Dictionary
+props.to_json("output.json")  # JSON file
+props.get_feature_vector()  # NumPy array for ML
+
+# Import
+props = BuildingProperties.from_dict(data)
+props = BuildingProperties.from_json("input.json")
+```
+
+## Requirements
+
+- Python 3.13+
+- Google Street View API key (for image acquisition and height estimation)
+- See `pyproject.toml` for full dependency list
+
+## Development
+
+```bash
+# Run tests
+uv run pytest
+
+# Run tests with coverage
+uv run pytest --cov-report=html
+open htmlcov/index.html
+
+# Lint and format
+uv run pre-commit run --all-files
+
+# Build package
+uv build
+```
+
+## Project Structure
+
+```
+imageable/
+├── src/imageable/
+│   ├── core/              # Public API
+│   │   ├── building_data.py   # Batch processing
+│   │   ├── dataset.py         # Single building extraction
+│   │   └── image.py           # Image acquisition
+│   ├── _extraction/       # Property extraction
+│   │   ├── building.py        # BuildingProperties dataclass
+│   │   ├── extract.py         # Main orchestrator
+│   │   ├── footprint.py       # Footprint features
+│   │   └── image.py           # Image features
+│   ├── _features/         # Feature pipelines
+│   │   ├── height/            # Height estimation
+│   │   └── materials/         # Material segmentation
+│   ├── _images/           # Image acquisition
+│   │   ├── camera/            # Camera parameters
+│   │   └── download.py        # Street View API
+│   └── _models/           # ML models
+│       ├── huggingface/       # SegFormer segmentation
+│       ├── lcnn/              # Line detection
+│       └── vpts/              # Vanishing points
+└── tests/                 # Test suite
+```
+
+## Citation
+
+If you use imageable in your research, please cite:
+
+```bibtex
+@software{imageable2025,
+  author = {Ngo, Khoi and Legaria, Uriel and Sandoval Olascoaga, Carlos},
+  title = {imageable: Computer Vision Library for Urban Building Analysis},
+  year = {2025},
+  url = {https://github.com/scalable-design-participation-lab/imageable}
+}
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Authors
+
+- Khoi Ngo ([Khoi Ngo](https://github.com/billnqk)) - ngo.kho@northeastern.edu
+- Uriel Legaria
+- Carlos Sandoval Olascoaga
+
+
+Developed at the [Scalable Design Participation Lab](https://github.com/scalable-design-participation-lab), Northeastern University.