pybdshadow

A python package for generating, analyzing and visualizing building shadows

https://github.com/ni1o1/pybdshadow

Science Score: 44.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
○
DOI references
○
Academic publication links
○
Committers with academic emails
○
Institutional organization owner
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (18.4%) to scientific vocabulary

Keywords

building-outline-data building-shadow geospatial-data gis python sunlight urban-analysis

Last synced: 6 months ago · JSON representation ·

Repository

A python package for generating, analyzing and visualizing building shadows

Basic Info

Host: GitHub
Owner: ni1o1
License: bsd-3-clause
Language: Jupyter Notebook
Default Branch: main
Homepage: https://pybdshadow.readthedocs.io/en/latest/
Size: 22.5 MB

Statistics

Stars: 69
Watchers: 2
Forks: 7
Open Issues: 1
Releases: 14

Topics

building-outline-data building-shadow geospatial-data gis python sunlight urban-analysis

Created almost 4 years ago · Last pushed 11 months ago

Metadata Files

Readme Contributing License Code of conduct Citation

pybdshadow

Introduction

pybdshadow is a python package for generating, analyzing and visualizing building shadows from large scale building geographic data. pybdshadow support generate building shadows from both sun light and point light. pybdshadow provides an efficient and easy-to-use method to generate a new source of geospatial data with great application potential in urban study.

The latest stable release of the software can be installed via pip and full documentation can be found here.

Functionality

Currently, pybdshadow mainly provides the following methods:

Generating building shadow from sun light: With given location and time, the function in pybdshadow uses the properties of sun position obtained from suncalc-py and the building height to generate shadow geometry data.
Generating building shadow from point light: pybdshadow can generate the building shadow with given location and height of the point light, which can be potentially useful for visual area analysis in urban environment.
Analysis: pybdshadow integrated the analysing method based on the properties of sun movement to track the changing position of shadows within a fixed time interval. Based on the grid processing framework provided by TransBigData, pybdshadow is capable of calculating sunshine time on the ground and on the roof.
Visualization: Built-in visualization capabilities leverage the visualization package keplergl to interactively visualize building and shadow data in Jupyter notebooks with simple code.

The target audience of pybdshadow includes data science researchers and data engineers in the field of BIM, GIS, energy, environment, and urban computing.

Installation

It is recommended to use Python 3.7, 3.8, 3.9

Using pypi

pybdshadow can be installed by using pip install. Before installing pybdshadow, make sure that you have installed the available geopandas package. If you already have geopandas installed, run the following code directly from the command prompt to install pybdshadow:

python pip install pybdshadow

Usage

Shadow generated by Sun light

Detail usage can be found in this example. pybdshadow is capable of generating shadows from building geographic data. The buildings are usually store in the data as the form of Polygon object with height information (usually Shapefile or GeoJSON file).

```python import pandas as pd import geopandas as gpd

Read building GeoJSON data

buildings = gpd.readfile(r'data/bddemo_2.json') ```

Given a building GeoDataFrame and UTC datetime, pybdshadow can calculate the building shadow based on the sun position obtained by suncalc-py.

```python import pybdshadow

Given UTC datetime

date = pd.todatetime('2022-01-01 12:45:33.959797119')\ .tzlocalize('Asia/Shanghai')\ .tz_convert('UTC')

Calculate building shadow for sun light

shadows = pybdshadow.bdshadow_sunlight(buildings,date) ```

Visualize buildings and shadows using matplotlib.

```python import matplotlib.pyplot as plt fig = plt.figure(1, (12, 12)) ax = plt.subplot(111)

plot buildings

buildings.plot(ax=ax)

plot shadows

shadows['type'] += ' shadow' shadows.plot(ax=ax, alpha=0.7, column='type', categorical=True, cmap='Set1_r', legend=True) plt.show() ```

pybdshadow also provide visualization method supported by keplergl.

```python

visualize buildings and shadows

pybdshadow.show_bdshadow(buildings = buildings,shadows = shadows) ```

Shadow generated by Point light

pybdshadow can also calculate the building shadow generated by point light. Given coordinates and height of the point light:

```python

Calculate building shadow for point light

shadows = pybdshadow.bdshadow_pointlight(buildings,139.713319,35.552040,200)

Visualize buildings and shadows

pybdshadow.show_bdshadow(buildings = buildings,shadows = shadows) ```

Shadow coverage analysis

pybdshadow provides the functionality to analysis sunshine time on the roof and on the ground.

Result of shadow coverage on the roof:

Result of sunshine time on the ground:

Dependency

pybdshadow depends on the following packages

numpy
pandas
shapely
rtree
geopandas
matplotlib
suncalc
keplergl
TransBigData

Citation information

Citation information can be found at CITATION.cff.

Contributing to pybdshadow

All contributions, bug reports, bug fixes, documentation improvements, enhancements and ideas are welcome. A detailed overview on how to contribute can be found in the contributing guide on GitHub.

Owner

Name: Qing Yu
Login: ni1o1
Kind: user
Location: Shenzhen, China
Company: Southern University of Science and Technology

Website: https://ni1o1.github.io/
Repositories: 37
Profile: https://github.com/ni1o1

Python, JavaScript, Spatio-temporal big data, Data visualization

Citation (CITATION.cff)

cff-version: 1.2.0
title: "Global Estimation of Building-Integrated Facade and Rooftop Photovoltaic Potential by Integrating 3D Building Footprint and Spatio-Temporal Datasets"
authors:
  - family-names: Yu
    given-names: Qing
    affiliation: "School of Urban Planning and Design, Peking University Shenzhen Graduate School"
  - family-names: Dong
    given-names: Kechuan
    affiliation: "Center for Spatial Information Science, University of Tokyo"
  - family-names: Guo
    given-names: Zhiling
    affiliation: "Department of Building Environment and Energy Engineering, The Hong Kong Polytechnic University"
  - family-names: Xu
    given-names: Jian
    affiliation: "Department of Building Environment and Energy Engineering, The Hong Kong Polytechnic University"
  - family-names: Li
    given-names: Jiaxing
    affiliation: "School of Urban Planning and Design, Peking University Shenzhen Graduate School"
  - family-names: Tan
    given-names: Hongjun
    affiliation: "Department of Building Environment and Energy Engineering, The Hong Kong Polytechnic University"
  - family-names: Jin
    given-names: Yanxiu
    affiliation: "Center for Spatial Information Science, University of Tokyo"
  - family-names: Yuan
    given-names: Jian
    affiliation: "School of Urban Planning and Design, Peking University Shenzhen Graduate School"
  - family-names: Zhang
    given-names: Haoran
    affiliation: "Department of Building Environment and Energy Engineering, The Hong Kong Polytechnic University"
  - family-names: Liu
    given-names: Junwei
    affiliation: "Department of Building Environment and Energy Engineering, The Hong Kong Polytechnic University"
  - family-names: Chen
    given-names: Qi
    affiliation: "School of Geography and Information Engineering, China University of Geosciences (Wuhan)"
  - family-names: Yan
    given-names: Jinyue
    affiliation: "Department of Building Environment and Energy Engineering, The Hong Kong Polytechnic University"
repository-code: "https://github.com/ni1o1/pybdshadow"
date-published: "2025"
doi: "10.1016/j.ynexs.2025.100060."
year: "2025"

GitHub Events

Total

Watch event: 17
Push event: 1
Fork event: 1

Last Year

Watch event: 17
Push event: 1
Fork event: 1

Committers

Last synced: about 2 years ago

All Time

Total Commits: 177
Total Committers: 4
Avg Commits per committer: 44.25
Development Distribution Score (DDS): 0.062

Past Year

Commits: 7
Committers: 1
Avg Commits per committer: 7.0
Development Distribution Score (DDS): 0.0

Top Committers

Name	Email	Commits
ni1o1	5****1	166
Console99	r**9@1**m	9
Console99	1****9	1
ImgBotApp	I**p@g**m	1

Committer Domains (Top 20 + Academic)

163.com: 1

Issues and Pull Requests

Last synced: 7 months ago

All Time

Total issues: 8
Total pull requests: 15
Average time to close issues: 7 months
Average time to close pull requests: about 2 hours
Total issue authors: 7
Total pull request authors: 3
Average comments per issue: 1.5
Average comments per pull request: 0.4
Merged pull requests: 15
Bot issues: 0
Bot pull requests: 1

Past Year

Issues: 1
Pull requests: 0
Average time to close issues: N/A
Average time to close pull requests: N/A
Issue authors: 1
Pull request authors: 0
Average comments per issue: 0.0
Average comments per pull request: 0
Merged pull requests: 0
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

lenasophia711 (2)
WanliQianKolmostar (1)
gcaria (1)
Csaooo (1)
amaccarini (1)
Shreyayadav21 (1)
Pradeesh-K (1)

Pull Request Authors

ni1o1 (14)
imgbot[bot] (1)
Console99 (1)

Top Labels

Issue Labels

bug (1) enhancement (1)

Pull Request Labels

Packages

Total packages: 1
Total downloads:
- pypi 678 last-month

Total dependent packages: 0
Total dependent repositories: 2
Total versions: 13
Total maintainers: 1

pypi.org: pybdshadow

Python package to generate building shadow geometry

Homepage: https://github.com/ni1o1/pybdshadow
Documentation: https://pybdshadow.readthedocs.io/
License: BSD
Latest release: 0.3.5
published about 2 years ago

Versions: 13
Dependent Packages: 0
Dependent Repositories: 2
Downloads: 678 Last month

Rankings

Dependent packages count: 10.1%

Dependent repos count: 11.5%

Stargazers count: 11.8%

Average: 14.1%

Downloads: 17.9%

Forks count: 19.1%

Maintainers (1)

ni1o1

Last synced: 7 months ago

Dependencies

.github/workflows/python-publish.yml actions

actions/checkout v3 composite
actions/setup-python v3 composite
pypa/gh-action-pypi-publish 27b31702a0e7fc50959f5ad993c78deac1bdfc29 composite

.github/workflows/tests.yml actions

actions/checkout v2 composite
actions/setup-python v2 composite
codecov/codecov-action v2 composite

requirements.txt pypi

geopandas *
keplergl *
mapbox_vector_tile *
matplotlib *
requests *
retrying *
rtree *
scikit-opt *
suncalc *
tqdm *
transbigdata *
vt2geojson *

setup.py pypi

numpy *

pybdshadow

Science Score: 44.0%

Keywords

Repository

Basic Info

Statistics

Topics

Metadata Files

README.md

pybdshadow

Introduction

Functionality

Installation

Using pypi

Usage

Shadow generated by Sun light

Read building GeoJSON data

Given UTC datetime

Calculate building shadow for sun light

plot buildings

plot shadows

visualize buildings and shadows

Shadow generated by Point light

Calculate building shadow for point light

Visualize buildings and shadows

Shadow coverage analysis

Dependency

Citation information

Contributing to pybdshadow

Owner

Citation (CITATION.cff)

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

pypi.org: pybdshadow

Rankings

Maintainers (1)

Dependencies