update

docs/source/analysis.rst

@@ -9,6 +9,33 @@ Shadow coverage
 Shadow coverage
 --------------------------------------
 
+.. function:: pybdshadow.cal_sunshine(buildings, day='2022-01-01', roof=False,grids =  gpd.GeoDataFrame(), accuracy=1, precision=3600, padding=0)
+
+Calculate the sunshine time in given date.
+
+**Parameters**
+
+buildings : GeoDataFrame
+    Buildings. coordinate system should be WGS84
+day : str
+    the day to calculate the sunshine
+roof : bool
+    whether to calculate roof shadow.
+grids : GeoDataFrame
+    grids generated by TransBigData in study area
+precision : number
+    time precision(s)
+padding : number
+    padding time before and after sunrise and sunset
+accuracy : number
+    size of grids.
+
+**Return**
+
+grids : GeoDataFrame
+    grids generated by TransBigData in study area, each grids have a `time` column store the sunshine time
+
+
 .. 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.

src/pybdshadow/analysis.py

@@ -9,9 +9,9 @@
 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'], precision=3600, padding=1800):
     # generate timetable
-    def get_timeSeries(day, lon, lat, gap=3600, padding=1800):
+    def get_timeSeries(day, lon, lat, precision=3600, padding=1800):
         date = pd.to_datetime(day+' 12:45:33.959797119')
         times = get_times(date, lon, lat)
         date_sunrise = times['sunrise']
@@ -21,15 +21,15 @@ def get_timeSeries(day, lon, lat, gap=3600, padding=1800):
         times = pd.to_datetime(pd.Series(range(
             timestamp_sunrise.iloc[0]+padding*1000000000,
             timestamp_sunset.iloc[0]-padding*1000000000,
-            gap*1000000000)))
+            precision*1000000000)))
         return times
     dates = pd.DataFrame(pd.concat(
-        [get_timeSeries(date, lon, lat, gap,padding) for date in dates]), columns=['datetime'])
+        [get_timeSeries(date, lon, lat, precision,padding) for date in dates]), columns=['datetime'])
     dates['date'] = dates['datetime'].apply(lambda r: str(r)[:19])
     return dates
 
 
-def cal_sunshine(buildings, day='2022-01-01', roof=False,grids =  gpd.GeoDataFrame(), accuracy=1, gap=3600, padding=0):
+def cal_sunshine(buildings, day='2022-01-01', roof=False,grids =  gpd.GeoDataFrame(), accuracy=1, precision=3600, padding=0):
     '''
     Calculate the sunshine time in given date.
 
@@ -43,8 +43,8 @@ def cal_sunshine(buildings, day='2022-01-01', roof=False,grids =  gpd.GeoDataFra
         whether to calculate roof shadow.
     grids : GeoDataFrame
         grids generated by TransBigData in study area
-    gap : number
-        time gap(s)
+    precision : number
+        time precision(s)
     padding : number
         padding time before and after sunrise and sunset
     accuracy : number
@@ -68,19 +68,19 @@ def cal_sunshine(buildings, day='2022-01-01', roof=False,grids =  gpd.GeoDataFra
         timestamp_sunset.iloc[0]-timestamp_sunrise.iloc[0])/(1000000000*3600)
 
     # Generate shadow every 1800 s
-    shadows = cal_sunshadows(buildings, dates=[day], gap=gap, padding=padding)
+    shadows = cal_sunshadows(buildings, dates=[day], precision=precision, padding=padding)
     # Grid analysis of shadow cover duration(ground).
     grids = cal_shadowcoverage(
-        shadows, buildings, grids = grids,roof=roof, gap=gap, accuracy=accuracy)
+        shadows, buildings, grids = grids,roof=roof, precision=precision, accuracy=accuracy)
 
     grids['Hour'] = sunlighthour-grids['time']/3600
     return grids
 
 
-def cal_sunshadows(buildings, cityname='somecity', dates=['2022-01-01'], gap=3600, padding=0,
+def cal_sunshadows(buildings, cityname='somecity', dates=['2022-01-01'], precision=3600, padding=0,
                    roof=True, include_building=True, save_shadows=False, printlog=False):
     '''
-    Calculate the sunlight shadow in different date with given time gap.
+    Calculate the sunlight shadow in different date with given time precision.
 
     **Parameters**
 
@@ -90,8 +90,8 @@ def cal_sunshadows(buildings, cityname='somecity', dates=['2022-01-01'], gap=360
         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)
+    precision : number
+        time precision(s)
     padding : number
         padding time before and after sunrise and sunset
     roof : bool
@@ -110,7 +110,7 @@ def cal_sunshadows(buildings, cityname='somecity', dates=['2022-01-01'], gap=360
     '''
     # 获取城市位置
     lon, lat = buildings['geometry'].iloc[0].bounds[:2]
-    timetable = get_timetable(lon, lat, dates, gap, padding)
+    timetable = get_timetable(lon, lat, dates, precision, padding)
     import os
     if save_shadows:
         if not os.path.exists('result'):
@@ -143,7 +143,7 @@ def cal_sunshadows(buildings, cityname='somecity', dates=['2022-01-01'], gap=360
     return allshadow
 
 
-def cal_shadowcoverage(shadows_input, buildings, grids = gpd.GeoDataFrame(),roof=True, gap=3600, accuracy=1):
+def cal_shadowcoverage(shadows_input, buildings, grids = gpd.GeoDataFrame(),roof=True, precision=3600, accuracy=1):
     '''
     Calculate the sunlight shadow coverage time for given area.
 
@@ -157,8 +157,8 @@ def cal_shadowcoverage(shadows_input, buildings, grids = gpd.GeoDataFrame(),roof
         grids generated by TransBigData in study area
     roof : bool
         If true roof shadow, false then ground shadow
-    gap : number
-        time gap(s), which is for calculation of coverage time
+    precision : number
+        time precision(s), which is for calculation of coverage time
     accuracy : number
         size of grids.
 
@@ -193,6 +193,6 @@ def cal_shadowcoverage(shadows_input, buildings, grids = gpd.GeoDataFrame(),roof
         drop_duplicates(subset=['LONCOL', 'LATCOL','date']).groupby(['LONCOL', 'LATCOL'])['geometry'].\
             count().rename('count').reset_index()
     grids = pd.merge(grids, gridcount, how='left')
-    grids['time'] = grids['count'].fillna(0)*gap
+    grids['time'] = grids['count'].fillna(0)*precision
 
     return grids

src/pybdshadow/tests/test_analysis.py

@@ -29,6 +29,9 @@ def test_analysis(self):
         buildings = pybdshadow.bd_preprocess(buildings)
         #分析
         date = '2022-01-01'
-        shadows = pybdshadow.cal_sunshadows(buildings,dates = [date],gap=3600)
-        bdgrids = pybdshadow.cal_shadowcoverage(shadows,buildings,gap = 3600,accuracy=2)
-        assert len(bdgrids)==1185
+        shadows = pybdshadow.cal_sunshadows(buildings,dates = [date],precision=3600)
+        bdgrids = pybdshadow.cal_shadowcoverage(shadows,buildings,precision = 3600,accuracy=2)
+        assert len(bdgrids)==1185
+
+        grids = pybdshadow.cal_sunshine(buildings)
+        assert len(grids)==1882