update doc

Author: ni1o1

docs/source/analysis.rst

@@ -0,0 +1,64 @@
+.. _analysis:
+
+
+*****************************
+Shadow coverage analysis
+*****************************
+
+
+Shadow coverage analysis
+--------------------------------------
+
+.. function:: pybdshadow.cal_sunshadows(buildings, cityname='somecity', dates=['2022-01-01'], gap=3600,roof=True, include_building=True,save_shadows=False,printlog=False)
+
+Calculate the sunlight shadow in different date with given time gap.
+
+**Parameters**
+
+buildings : GeoDataFrame
+    Buildings. coordinate system should be WGS84
+cityname : string
+    Cityname. If save_shadows, this function will create `result/cityname` folder to save the shadows
+dates : list
+    list of dates
+gap : number
+    time gap(s)
+roof : bool
+    whether to calculate roof shadow.
+include_building : bool
+    whether the shadow include building outline
+save_shadows : bool
+    whether to save calculated shadows
+printlog : bool
+    whether to print log
+
+**Return**
+
+allshadow : GeoDataFrame
+    All building shadows calculated
+
+
+.. function:: pybdshadow.cal_shadowcoverage(shadows_input,buildings,roof=True,gap = 3600,accuracy=1)
+
+Calculate the sunlight shadow coverage time for given area.
+
+**Parameters**
+
+shadows_input : GeoDataFrame
+    All building shadows calculated
+buildings : GeoDataFrame
+    Buildings. coordinate system should be WGS84
+roof : bool
+    If true roof shadow, false then ground shadow
+gap : number
+    time gap(s), which is for calculation of coverage time
+accuracy : number
+    size of grids.
+
+**Return**
+
+bdgrids : GeoDataFrame
+    grids generated by TransBigData in study area, each grids have a `time` column store the shadow coverage time
+
+
+

docs/source/conf.py

@@ -22,8 +22,8 @@
 author = 'Qing Yu'
 
 # The full version, including alpha/beta/rc tags
-release = '0.2.4'
-version = '0.2.4'
+release = '0.3.0'
+version = '0.3.0'
 html_logo = "_static/logo-wordmark-light.png"
 html_favicon = '_static/logo.ico'
 # -- General configuration ---------------------------------------------------

docs/source/index.rst

@@ -62,4 +62,5 @@ Citation information can be found at https://github.com/ni1o1/pybdshadow/blob/ma
 
    preprocess.rst
    bdshadow.rst
+   analysis.rst
    Visualization.rst

example/example-analysis.ipynb

@@ -152,7 +152,7 @@
    ],
    "source": [
     "#Grid analysis of shadow cover duration(roof).\n",
-    "bdgrids = pybdshadow.cal_shadowduration(shadows,buildings,gap = 1800,accuracy=2)\n",
+    "bdgrids = pybdshadow.cal_shadowcoverage(shadows,buildings,gap = 1800,accuracy=2)\n",
     "\n",
     "#Visualize buildings and shadows using matplotlib\n",
     "import matplotlib.pyplot as plt\n",
@@ -196,7 +196,7 @@
    ],
    "source": [
     "#Grid analysis of shadow cover duration(ground).\n",
-    "bdgrids = pybdshadow.cal_shadowduration(shadows,buildings,roof=False,gap = 900,accuracy=2)\n",
+    "bdgrids = pybdshadow.cal_shadowcoverage(shadows,buildings,roof=False,gap = 900,accuracy=2)\n",
     "\n",
     "#Visualize buildings and shadows using matplotlib\n",
     "import matplotlib.pyplot as plt\n",

setup.py

@@ -5,7 +5,7 @@
 
 setuptools.setup(
     name="pybdshadow",
-    version="0.2.4",
+    version="0.3.0",
     author="Qing Yu",
     author_email="qingyu0815@foxmail.com",
     description="Python package to generate building shadow geometry",

src/pybdshadow/__init__.py

@@ -32,7 +32,7 @@
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 """
 
-__version__ = '0.2.4'
+__version__ = '0.3.0'
 __author__ = 'Qing Yu <qingyu0815@foxmail.com>'
 
 # module level doc-string
@@ -52,11 +52,13 @@
 )
 from .analysis import (
     cal_sunshadows,
-    cal_shadowduration
+    cal_shadowcoverage
 )
 
 __all__ = ['bdshadow_sunlight',
            'bdshadow_pointlight',
            'bd_preprocess',
            'show_bdshadow',
+           'cal_sunshadows',
+           'cal_shadowcoverage',
            ]

src/pybdshadow/analysis.py

@@ -1,12 +1,16 @@
 import pandas as pd
 from suncalc import get_times
+from shapely.geometry import MultiPolygon
+import transbigdata as tbd
+import geopandas as gpd
 from .pybdshadow import (
     bdshadow_sunlight,
 )
 from .preprocess import bd_preprocess
-# 生成时间表
-def get_timetable(lon, lat, dates=['2022-01-01'], gap=3600, padding=1800):
 
+
+def get_timetable(lon, lat, dates=['2022-01-01'], gap=3600, padding=1800):
+    # generate timetable
     def get_timeSeries(day, lon, lat, gap=3600, padding=1800):
         date = pd.to_datetime(day+' 12:45:33.959797119')
         times = get_times(date, lon, lat)
@@ -27,6 +31,33 @@ def get_timeSeries(day, lon, lat, gap=3600, padding=1800):
 
 def cal_sunshadows(buildings, cityname='somecity', dates=['2022-01-01'], gap=3600,
               roof=True, include_building=True,save_shadows=False,printlog=False):
+    '''
+    Calculate the sunlight shadow in different date with given time gap.
+
+    **Parameters**
+
+    buildings : GeoDataFrame
+        Buildings. coordinate system should be WGS84
+    cityname : string
+        Cityname. If save_shadows, this function will create `result/cityname` folder to save the shadows
+    dates : list
+        list of dates
+    gap : number
+        time gap(s)
+    roof : bool
+        whether to calculate roof shadow.
+    include_building : bool
+        whether the shadow include building outline
+    save_shadows : bool
+        whether to save calculated shadows
+    printlog : bool
+        whether to print log
+
+    **Return**
+
+    allshadow : GeoDataFrame
+        All building shadows calculated
+    '''
     # 获取城市位置
     lon, lat = buildings['geometry'].iloc[0].bounds[:2]
     timetable = get_timetable(lon, lat, dates, gap)
@@ -61,10 +92,30 @@ def cal_sunshadows(buildings, cityname='somecity', dates=['2022-01-01'], gap=360
     allshadow = pd.concat(allshadow)
     return allshadow
 
-from shapely.geometry import MultiPolygon
-import transbigdata as tbd
-import geopandas as gpd
-def cal_shadowduration(shadows_input,buildings,roof=True,gap = 3600,accuracy=1):
+
+def cal_shadowcoverage(shadows_input,buildings,roof=True,gap = 3600,accuracy=1):
+    '''
+    Calculate the sunlight shadow coverage time for given area.
+
+    **Parameters**
+
+    shadows_input : GeoDataFrame
+        All building shadows calculated
+    buildings : GeoDataFrame
+        Buildings. coordinate system should be WGS84
+    roof : bool
+        If true roof shadow, false then ground shadow
+    gap : number
+        time gap(s), which is for calculation of coverage time
+    accuracy : number
+        size of grids.
+
+    **Return**
+    
+    bdgrids : GeoDataFrame
+        grids generated by TransBigData in study area, each grids have a `time` column store the shadow coverage time
+
+    '''
     shadows = bd_preprocess(shadows_input)
     if roof:
         ground_shadows = shadows[shadows['type']=='roof'].groupby(['date'])['geometry'].apply(

src/pybdshadow/tests/test_analysis.py

@@ -30,5 +30,5 @@ def test_analysis(self):
         #分析
         date = '2022-01-01'
         shadows = pybdshadow.cal_sunshadows(buildings,dates = [date],gap=3600)
-        bdgrids = pybdshadow.cal_shadowduration(shadows,buildings,gap = 3600,accuracy=2)
+        bdgrids = pybdshadow.cal_shadowcoverage(shadows,buildings,gap = 3600,accuracy=2)
         assert len(bdgrids)==1185