Skip to content

Commit 8499206

Browse files
ni1o1ni1o1
authored
Merge pull request #2 from ni1o1/0.1.3
0.1.3
2 parents 974b4bc + 21b8eea commit 8499206

20 files changed

+945
-296
lines changed

‎README.md

Lines changed: 61 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,23 @@
22

33
![1649074615552.png](https://github.com/ni1o1/pybdshadow/raw/main/image/README/1649074615552.png)
44

5-
[![Documentation Status](https://readthedocs.org/projects/pybdshadow/badge/?version=latest)](https://pybdshadow.readthedocs.io/en/latest/?badge=latest) [![codecov](https://codecov.io/gh/ni1o1/pybdshadow/branch/main/graph/badge.svg?token=GLAVYYCD9L)](https://codecov.io/gh/ni1o1/pybdshadow) [![Tests](https://github.com/ni1o1/pybdshadow/actions/workflows/tests.yml/badge.svg)](https://github.com/ni1o1/pybdshadow/actions/workflows/tests.yml)
5+
[![Documentation Status](https://readthedocs.org/projects/pybdshadow/badge/?version=latest)](https://pybdshadow.readthedocs.io/en/latest/?badge=latest) [![Downloads](https://pepy.tech/badge/pybdshadow)](https://pepy.tech/project/pybdshadow) [![codecov](https://codecov.io/gh/ni1o1/pybdshadow/branch/main/graph/badge.svg?token=GLAVYYCD9L)](https://codecov.io/gh/ni1o1/pybdshadow) [![Tests](https://github.com/ni1o1/pybdshadow/actions/workflows/tests.yml/badge.svg)](https://github.com/ni1o1/pybdshadow/actions/workflows/tests.yml)
66

77
## Introduction
88

99
`pybdshadow` is a python package to generate building shadow geometry. The latest stable release of the software can be installed via pip and full documentation can be found [here](https://pybdshadow.readthedocs.io/en/latest/).
1010

1111
## Example
1212

13+
### Shadow generated by Sun light
14+
1315
Given a building GeoDataFrame and UTC datetime, `pybdshadow` can calculate the building shadow based on the sun position obtained by `suncalc`
1416

1517
```python
1618
import pybdshadow
1719
#Given UTC datetime
1820
date = pd.to_datetime('2015-01-01 02:45:33.959797119')
19-
#Calculate building shadow
21+
#Calculate building shadow for sun light
2022
shadows = pybdshadow.bdshadow_sunlight(buildings,date)
2123
```
2224

@@ -31,11 +33,61 @@ pybdshadow.show_bdshadow(buildings = buildings,shadows = shadows)
3133

3234
Detail usage can be found in [this example](https://github.com/ni1o1/pybdshadow/blob/main/example/example.ipynb).
3335

36+
### Shadow generated by Point light
37+
38+
`pybdshadow` can also calculate the building shadow generated by point light. Given coordinates and height of the point light:
39+
40+
```python
41+
#Calculate building shadow for point light
42+
shadows = pybdshadow.bdshadow_pointlight(buildings,139.713319,35.552040,200)
43+
#Visualize buildings and shadows
44+
pybdshadow.show_bdshadow(buildings = buildings,shadows = shadows)
45+
```
46+
47+
![1649405838683.png](image/README/1649405838683.png)
48+
49+
### Billboard visual area analyze
50+
51+
To analyze billboard visual area, the parameter `ad_params` for the billboard should be defined. It has two forms:
52+
53+
```python
54+
#1. Given the coordinates of brandCenter, orientation and height
55+
ad_params = {'orientation': 1.2806657381630058,
56+
'height': 10,
57+
'brandCenter': [139.71259, 35.552842999999996]}
58+
#2. Given the coordinates of the two border points and height
59+
ad_params = {'point1': [139.711861, 35.552040],
60+
'point2': [139.713319, 35.553646],#1861,3646
61+
'height': 50,
62+
}
63+
```
64+
65+
We can calculate the visual area of the billboard using `ad_visualArea`.
66+
67+
```python
68+
#calculate the visual area
69+
visualArea,shadows = pybdshadow.ad_visualArea(ad_params,buildings)
70+
```
71+
72+
Then, visualize the billboard and the visual area.
73+
74+
```python
75+
#Generate a GeoDataFrame from ad_params for visualization
76+
billboard_gdf = pybdshadow.ad_to_gdf(ad_params,billboard_height = 100)
77+
#Visualize buildings, shadows, billboard and visual area
78+
pybdshadow.show_bdshadow(buildings=buildings,
79+
shadows=shadows,
80+
ad=billboard_gdf,
81+
ad_visualArea=visualArea)
82+
```
83+
84+
![1649406044109.png](image/README/1649406044109.png)
85+
3486
## Installation
3587

3688
It is recommended to use `Python 3.7, 3.8, 3.9`
3789

38-
### Using pypi [![PyPI version](https://badge.fury.io/py/pybdshadow.svg)](https://badge.fury.io/py/pybdshadow)
90+
### Using pypi [![PyPI version](https://badge.fury.io/py/pybdshadow.svg)](https://badge.fury.io/py/pybdshadow)
3991

4092
`pybdshadow` can be installed by using `pip install`. Before installing `pybdshadow`, make sure that you have installed the available [geopandas package](https://geopandas.org/en/stable/getting_started/install.html). If you already have geopandas installed, run the following code directly from the command prompt to install `pybdshadow`:
4193

@@ -44,6 +96,7 @@ pip install pybdshadow
4496
```
4597

4698
## Dependency
99+
47100
`pybdshadow` depends on the following packages
48101

49102
* `numpy`
@@ -53,8 +106,12 @@ pip install pybdshadow
53106
* `geopandas`
54107
* `matplotlib`
55108
* [`suncalc`](https://github.com/kylebarron/suncalc-py)
56-
* `keplergl` (optional)
109+
* `keplergl`
57110

58111
## Citation information
59112

60113
Citation information can be found at [CITATION.cff](https://github.com/ni1o1/pybdshadow/blob/main/CITATION.cff).
114+
115+
## Contributing to pybdshadow [![GitHub contributors](https://img.shields.io/github/contributors/ni1o1/pybdshadow.svg)](https://github.com/ni1o1/pybdshadow/graphs/contributors) ![GitHub commit activity](https://img.shields.io/github/commit-activity/m/ni1o1/pybdshadow)
116+
117+
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](https://github.com/ni1o1/pybdshadow/blob/master/CONTRIBUTING.md) on GitHub.

‎docs/source/Visualization.rst

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,28 +2,41 @@
22

33

44
*****************************
5-
Building Visualization
5+
Visualization
66
*****************************
77

8+
Visualization Settings in Jupyter
9+
--------------------------------------
10+
11+
| The `pybdshadow`` package provide visualization methods based on the visualization plugin provided by `kepler.gl`.
12+
13+
If you want to display the visualization results in jupyter notebook, you need to check the jupyter-js-widgets (which may need to be installed separately) and keplergl-jupyter plugins
14+
15+
.. image:: _static/jupytersettings.png
16+
817
Visualization
9-
=============================
18+
--------------------------------------
1019

11-
.. function:: pybdshadow.show_bdshadow(buildings=gpd.GeoDataFrame(),shadows=gpd.GeoDataFrame(),height='height',zoom='auto')
20+
.. function:: pybdshadow.show_bdshadow(buildings=gpd.GeoDataFrame(),shadows=gpd.GeoDataFrame(),ad=gpd.GeoDataFrame(),ad_visualArea=gpd.GeoDataFrame(),height='height',zoom='auto')
1221

1322
Visualize the building and shadow with keplergl.
1423

1524
**Parameters**
16-
1725
buildings : GeoDataFrame
1826
Buildings. coordinate system should be WGS84
1927
shadows : GeoDataFrame
2028
Building shadows. coordinate system should be WGS84
29+
ad : GeoDataFrame
30+
Advertisment. coordinate system should be WGS84
31+
ad_visualArea : GeoDataFrame
32+
Visualarea of Advertisment. coordinate system should be WGS84
2133
height : string
2234
Column name of building height
2335
zoom : number
2436
Zoom level of the map
2537

2638
**Return**
27-
2839
vmap : keplergl.keplergl.KeplerGl
2940
Visualizations provided by keplergl
41+
42+

‎docs/source/_static/jupytersettings.png

120 KB
Loading

‎docs/source/advertisment.rst

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
.. _advertisment:
2+
3+
4+
******************************
5+
Billboard visual area
6+
******************************
7+
8+
Advertisment parameters
9+
--------------------------------------
10+
11+
To analyze billboard visual area, the parameter `ad_params` for the billboard should be defined. It has two forms::
12+
13+
#1. Given the coordinates of the two border points and height
14+
ad_params = {'point1': [139.711861, 35.552040],
15+
'point2': [139.713319, 35.553646],#1861,3646
16+
'height': 50,
17+
}
18+
#2. Given the coordinates of brandCenter, orientation and height
19+
ad_params = {'orientation': 1.2806657381630058,
20+
'height': 10,
21+
'brandCenter': [139.71259, 35.552842999999996]}
22+
23+
You can use `ad_to_gdf` to generate the GeoDataFrame for the billboard in order to visualize it.
24+
25+
.. function:: pybdshadow.ad_to_gdf(ad_params,billboard_height = 10)
26+
27+
Generate a GeoDataFrame from ad_params for visualization.
28+
29+
**Parameters**
30+
ad_params : dict
31+
Parameters of advertisement.
32+
billboard_height : number
33+
The height of the billboard
34+
35+
**Return**
36+
ad_gdf : GeoDataFrame
37+
advertisment GeoDataFrame
38+
39+
visual area calculation
40+
--------------------------------------
41+
42+
.. function:: pybdshadow.ad_visualArea(ad_params, buildings=gpd.GeoDataFrame(), height='height')
43+
44+
Calculate visual area for advertisement.
45+
46+
**Parameters**
47+
ad_params : dict
48+
Parameters of advertisement.
49+
buildings : GeoDataFrame
50+
Buildings. coordinate system should be WGS84
51+
height : string
52+
Column name of building height
53+
54+
**Return**
55+
visualArea : GeoDataFrame
56+
Visual Area of the advertisement
57+
shadows : GeoDataFrame
58+
Building shadows

‎docs/source/bdshadow.rst

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Building shadow
77

88

99
Shadow from sunlight
10-
=============================
10+
--------------------------------------
1111

1212
.. function:: pybdshadow.bdshadow_sunlight(buildings, date, merge=False, height='height', ground=0)
1313

@@ -30,3 +30,28 @@ ground : number
3030

3131
shadows : GeoDataFrame
3232
Building shadow
33+
34+
Shadow from pointlight
35+
--------------------------------------
36+
37+
.. function:: pybdshadow.bdshadow_pointlight(buildings, pointlon, pointlat, pointheight, merge=True, height='height', ground=0)
38+
39+
Calculate the sunlight shadow of the buildings.
40+
41+
**Parameters**
42+
buildings : GeoDataFrame
43+
Buildings. coordinate system should be WGS84
44+
pointlon,pointlat,pointheight : float
45+
Point light coordinates and height
46+
date : datetime
47+
Datetime
48+
merge : bool
49+
whether to merge the wall shadows into the building shadows
50+
height : string
51+
Column name of building height
52+
ground : number
53+
Height of the ground
54+
55+
**Return**
56+
shadows : GeoDataFrame
57+
Building shadow

‎docs/source/conf.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,8 @@
2222
author = 'Qing Yu'
2323

2424
# The full version, including alpha/beta/rc tags
25-
release = '0.1.1'
26-
version = '0.1.1'
25+
release = '0.2.0'
26+
version = '0.2.0'
2727
html_logo = "_static/logo-wordmark-light.png"
2828
html_favicon = '_static/logo.ico'
2929
# -- General configuration ---------------------------------------------------

‎docs/source/index.rst

Lines changed: 7 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -35,30 +35,6 @@ Given a building GeoDataFrame and UTC datetime, `pybdshadow` can calculate the b
3535

3636
.. image:: _static/visualize.png
3737

38-
Installation
39-
---------------------------------
40-
41-
42-
| It is recommended to use `Python 3.7, 3.8, 3.9`.
43-
| `pybdshadow` can be installed by using `pip install`. Before installing `pybdshadow`, make sure that you have installed the available `geopandas` package: https://geopandas.org/en/stable/getting_started/install.html.
44-
| If you already have geopandas installed, run the following code directly from the command prompt to install `pybdshadow`:
45-
46-
::
47-
48-
pip install pybdshadow
49-
50-
Dependency
51-
---------------------------------
52-
`pybdshadow` depends on the following packages
53-
54-
* `numpy`
55-
* `pandas`
56-
* `shapely`
57-
* `rtree`
58-
* `geopandas`
59-
* `matplotlib`
60-
* `suncalc`
61-
* `keplergl` (optional)
6238

6339

6440
Citation information
@@ -70,10 +46,17 @@ Citation information can be found at https://github.com/ni1o1/pybdshadow/blob/ma
7046
Method
7147
=========================
7248

49+
.. toctree::
50+
:caption: Installation and dependencies
51+
:maxdepth: 2
52+
53+
install.rst
54+
7355
.. toctree::
7456
:caption: Method
7557
:maxdepth: 2
7658

7759
preprocess.rst
7860
bdshadow.rst
61+
advertisment.rst
7962
Visualization.rst

‎docs/source/install.rst

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
2+
.. _install:
3+
4+
5+
******************************
6+
Installation and dependencies
7+
******************************
8+
9+
10+
Installation
11+
--------------------------------------
12+
13+
14+
| It is recommended to use `Python 3.7, 3.8, 3.9`.
15+
| `pybdshadow` can be installed by using `pip install`. Before installing `pybdshadow`, make sure that you have installed the available `geopandas` package: https://geopandas.org/en/stable/getting_started/install.html.
16+
| If you already have geopandas installed, run the following code directly from the command prompt to install `pybdshadow`:
17+
18+
::
19+
20+
pip install pybdshadow
21+
22+
Dependency
23+
--------------------------------------
24+
`pybdshadow` depends on the following packages
25+
26+
* `numpy`
27+
* `pandas`
28+
* `shapely`
29+
* `rtree`
30+
* `geopandas`
31+
* `matplotlib`
32+
* `suncalc`
33+
* `keplergl`

‎docs/source/preprocess.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@
22

33

44
*********************
5-
Preprocess
5+
Building Preprocess
66
*********************
77

88
Building preprocess
9-
=============================
9+
--------------------------------------
1010

1111
.. function:: pybdshadow.bd_preprocess(buildings)
1212

0 commit comments

Comments
 (0)