Merge pull request #2 from ni1o1/0.1.3

0.1.3
ni1o1 · Apr 8, 2022 · 8499206 · 8499206
2 parents 974b4bc + 21b8eea
commit 8499206
Show file tree

Hide file tree

Showing 20 changed files with 945 additions and 296 deletions.
diff --git a/README.md b/README.md
@@ -2,21 +2,23 @@
 
 ![1649074615552.png](https://github.com/ni1o1/pybdshadow/raw/main/image/README/1649074615552.png)
 
-[![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)
+[![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)
 
 ## Introduction
 
 `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/).
 
 ## Example
 
+### Shadow generated by Sun light
+
 Given a building GeoDataFrame and UTC datetime, `pybdshadow` can calculate the building shadow based on the sun position obtained by `suncalc`
 
 ```python
 import pybdshadow
 #Given UTC datetime
 date = pd.to_datetime('2015-01-01 02:45:33.959797119')
-#Calculate building shadow
+#Calculate building shadow for sun light
 shadows = pybdshadow.bdshadow_sunlight(buildings,date)
 ```
 
@@ -31,11 +33,61 @@ pybdshadow.show_bdshadow(buildings = buildings,shadows = shadows)
 
 Detail usage can be found in [this example](https://github.com/ni1o1/pybdshadow/blob/main/example/example.ipynb).
 
+### 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)
+```
+
+![1649405838683.png](image/README/1649405838683.png)
+
+### Billboard visual area analyze
+
+To analyze billboard visual area, the parameter `ad_params` for the billboard should be defined. It has two forms:
+
+```python
+#1. Given the coordinates of brandCenter, orientation and height
+ad_params = {'orientation': 1.2806657381630058,
+            'height': 10,
+            'brandCenter': [139.71259, 35.552842999999996]} 
+#2. Given the coordinates of the two border points and height
+ad_params = {'point1': [139.711861, 35.552040],
+            'point2': [139.713319, 35.553646],#1861,3646
+            'height': 50,
+            }
+```
+
+We can calculate the visual area of the billboard using `ad_visualArea`.
+
+```python
+#calculate the visual area
+visualArea,shadows = pybdshadow.ad_visualArea(ad_params,buildings)
+```
+
+Then, visualize the billboard and the visual area.
+
+```python
+#Generate a GeoDataFrame from ad_params for visualization
+billboard_gdf = pybdshadow.ad_to_gdf(ad_params,billboard_height = 100)
+#Visualize buildings, shadows, billboard and visual area
+pybdshadow.show_bdshadow(buildings=buildings,
+                         shadows=shadows,
+                         ad=billboard_gdf,
+                         ad_visualArea=visualArea)
+```
+
+![1649406044109.png](image/README/1649406044109.png)
+
 ## Installation
 
 It is recommended to use `Python 3.7, 3.8, 3.9`
 
-### Using pypi [![PyPI version](https://badge.fury.io/py/pybdshadow.svg)](https://badge.fury.io/py/pybdshadow) 
+### Using pypi [![PyPI version](https://badge.fury.io/py/pybdshadow.svg)](https://badge.fury.io/py/pybdshadow)
 
 `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`:
 
@@ -44,6 +96,7 @@ pip install pybdshadow
 ```
 
 ## Dependency
+
 `pybdshadow` depends on the following packages
 
 * `numpy`
@@ -53,8 +106,12 @@ pip install pybdshadow
 * `geopandas`
 * `matplotlib`
 * [`suncalc`](https://github.com/kylebarron/suncalc-py)
-* `keplergl` (optional)
+* `keplergl`
 
 ## Citation information
 
 Citation information can be found at [CITATION.cff](https://github.com/ni1o1/pybdshadow/blob/main/CITATION.cff).
+
+## 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)
+
+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.
diff --git a/docs/source/Visualization.rst b/docs/source/Visualization.rst
@@ -2,28 +2,41 @@
 
 
 *****************************
-Building Visualization
+Visualization
 *****************************
 
+Visualization Settings in Jupyter
+--------------------------------------
+
+| The `pybdshadow`` package provide visualization methods based on the visualization plugin provided by `kepler.gl`.
+
+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
+
+.. image:: _static/jupytersettings.png
+
 Visualization
-=============================
+--------------------------------------
 
-.. function:: pybdshadow.show_bdshadow(buildings=gpd.GeoDataFrame(),shadows=gpd.GeoDataFrame(),height='height',zoom='auto')
+.. function:: pybdshadow.show_bdshadow(buildings=gpd.GeoDataFrame(),shadows=gpd.GeoDataFrame(),ad=gpd.GeoDataFrame(),ad_visualArea=gpd.GeoDataFrame(),height='height',zoom='auto')
 
 Visualize the building and shadow with keplergl.
 
 **Parameters**
-
 buildings : GeoDataFrame
     Buildings. coordinate system should be WGS84
 shadows : GeoDataFrame
     Building shadows. coordinate system should be WGS84
+ad : GeoDataFrame
+    Advertisment. coordinate system should be WGS84
+ad_visualArea : GeoDataFrame
+    Visualarea of Advertisment. coordinate system should be WGS84
 height : string
     Column name of building height
 zoom : number
     Zoom level of the map
 
 **Return**
-
 vmap : keplergl.keplergl.KeplerGl
     Visualizations provided by keplergl
+
+
diff --git a/docs/source/_static/jupytersettings.png b/docs/source/_static/jupytersettings.png
diff --git a/docs/source/advertisment.rst b/docs/source/advertisment.rst
@@ -0,0 +1,58 @@
+.. _advertisment:
+
+
+******************************
+Billboard visual area
+******************************
+
+Advertisment parameters
+--------------------------------------
+
+To analyze billboard visual area, the parameter `ad_params` for the billboard should be defined. It has two forms::
+
+    #1. Given the coordinates of the two border points and height
+    ad_params = {'point1': [139.711861, 35.552040],
+                'point2': [139.713319, 35.553646],#1861,3646
+                'height': 50,
+                }
+    #2. Given the coordinates of brandCenter, orientation and height
+    ad_params = {'orientation': 1.2806657381630058,
+                'height': 10,
+                'brandCenter': [139.71259, 35.552842999999996]} 
+
+You can use `ad_to_gdf` to generate the GeoDataFrame for the billboard in order to visualize it.
+
+.. function:: pybdshadow.ad_to_gdf(ad_params,billboard_height = 10)
+
+Generate a GeoDataFrame from ad_params for visualization.
+
+**Parameters**
+ad_params : dict
+    Parameters of advertisement.
+billboard_height : number
+    The height of the billboard
+
+**Return**
+ad_gdf : GeoDataFrame
+    advertisment GeoDataFrame
+
+visual area calculation
+--------------------------------------
+
+.. function:: pybdshadow.ad_visualArea(ad_params, buildings=gpd.GeoDataFrame(), height='height')
+
+Calculate visual area for advertisement.
+
+**Parameters**
+ad_params : dict
+    Parameters of advertisement.
+buildings : GeoDataFrame
+    Buildings. coordinate system should be WGS84
+height : string
+    Column name of building height
+
+**Return**
+visualArea : GeoDataFrame
+    Visual Area of the advertisement
+shadows : GeoDataFrame
+    Building shadows
diff --git a/docs/source/bdshadow.rst b/docs/source/bdshadow.rst
@@ -7,7 +7,7 @@ Building shadow
 
 
 Shadow from sunlight
-=============================
+--------------------------------------
 
 .. function:: pybdshadow.bdshadow_sunlight(buildings, date, merge=False, height='height', ground=0)
 
@@ -30,3 +30,28 @@ ground : number
 
 shadows : GeoDataFrame
     Building shadow
+
+Shadow from pointlight
+--------------------------------------
+
+.. function:: pybdshadow.bdshadow_pointlight(buildings, pointlon, pointlat, pointheight, merge=True, height='height', ground=0)
+
+Calculate the sunlight shadow of the buildings.
+
+**Parameters**
+buildings : GeoDataFrame
+    Buildings. coordinate system should be WGS84
+pointlon,pointlat,pointheight : float
+    Point light coordinates and height
+date : datetime
+    Datetime
+merge : bool
+    whether to merge the wall shadows into the building shadows
+height : string
+    Column name of building height
+ground : number
+    Height of the ground
+
+**Return**
+shadows : GeoDataFrame
+    Building shadow
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -22,8 +22,8 @@
 author = 'Qing Yu'
 
 # The full version, including alpha/beta/rc tags
-release = '0.1.1'
-version = '0.1.1'
+release = '0.2.0'
+version = '0.2.0'
 html_logo = "_static/logo-wordmark-light.png"
 html_favicon = '_static/logo.ico'
 # -- General configuration ---------------------------------------------------

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -35,30 +35,6 @@ Given a building GeoDataFrame and UTC datetime, `pybdshadow` can calculate the b
 
 .. image:: _static/visualize.png
 
-Installation
----------------------------------
-
-
-| It is recommended to use `Python 3.7, 3.8, 3.9`.   
-| `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`:
-
-::
-
-    pip install pybdshadow
-
-Dependency
----------------------------------
-`pybdshadow` depends on the following packages
-
-* `numpy`
-* `pandas`
-* `shapely`
-* `rtree`
-* `geopandas`
-* `matplotlib`
-* `suncalc`
-* `keplergl` (optional)
 
 
 Citation information
@@ -70,10 +46,17 @@ Citation information can be found at https://github.com/ni1o1/pybdshadow/blob/ma
 Method
 =========================
 
+.. toctree::
+   :caption: Installation and dependencies
+   :maxdepth: 2
+
+   install.rst
+
 .. toctree::
    :caption: Method
    :maxdepth: 2
 
    preprocess.rst
    bdshadow.rst
+   advertisment.rst
    Visualization.rst
diff --git a/docs/source/install.rst b/docs/source/install.rst
@@ -0,0 +1,33 @@
+
+.. _install:
+
+
+******************************
+Installation and dependencies
+******************************
+
+
+Installation
+--------------------------------------
+
+
+| It is recommended to use `Python 3.7, 3.8, 3.9`.   
+| `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`:
+
+::
+
+    pip install pybdshadow
+
+Dependency
+--------------------------------------
+`pybdshadow` depends on the following packages
+
+* `numpy`
+* `pandas`
+* `shapely`
+* `rtree`
+* `geopandas`
+* `matplotlib`
+* `suncalc`
+* `keplergl`
diff --git a/docs/source/preprocess.rst b/docs/source/preprocess.rst
@@ -2,11 +2,11 @@
 
 
 *********************
-Preprocess
+Building Preprocess
 *********************
 
 Building preprocess
-=============================
+--------------------------------------
 
 .. function:: pybdshadow.bd_preprocess(buildings)