Coverage for pyguymer3/geo/bufferSrc/buffer_Point.py: 75%

1#!/usr/bin/env python3 

2 

3# Define function ... 

4def buffer_Point( 

5 point, 

6 dist, 

7 /, 

8 *, 

9 debug = __debug__, 

10 eps = 1.0e-12, 

11 fill = 1.0, 

12 fillSpace = "EuclideanSpace", 

13 nAng = 9, 

14 nIter = 100, 

15 prefix = ".", 

16 ramLimit = 1073741824, 

17 simp = 0.1, 

18 tol = 1.0e-10, 

19): 

20 """Buffer a Point 

21 

22 This function reads in a Point that exists on the surface of the Earth and 

23 returns a [Multi]Polygon of the same Point buffered by a constant distance 

24 (in metres). 

25 

26 Parameters 

27 ---------- 

28 point : shapely.geometry.point.Point 

29 the Point 

30 dist : float 

31 the distance to buffer the Point by (in metres) 

32 debug : bool, optional 

33 print debug messages 

34 eps : float, optional 

35 the tolerance of the Vincenty formula iterations 

36 fill : float, optional 

37 the Euclidean or Geodesic distance to fill in between each point within 

38 the shapes by (in degrees or metres) 

39 fillSpace : str, optional 

40 the geometric space to perform the filling in (either "EuclideanSpace" 

41 or "GeodesicSpace") 

42 nAng : int, optional 

43 the number of angles around the Point that are calculated when buffering 

44 nIter : int, optional 

45 the maximum number of iterations (particularly the Vincenty formula) 

46 prefix : str, optional 

47 change the name of the output debugging CSVs 

48 ramLimit : int, optional 

49 the maximum RAM usage of each "large" array (in bytes) 

50 simp : float, optional 

51 how much intermediary [Multi]Polygons are simplified by; negative values 

52 disable simplification (in degrees) 

53 tol : float, optional 

54 the Euclidean distance that defines two points as being the same (in 

55 degrees) 

56 

57 Returns 

58 ------- 

59 buffs : shapely.geometry.polygon.Polygon, shapely.geometry.multipolygon.MultiPolygon 

60 the buffered Point 

61 

62 Notes 

63 ----- 

64 According to the `Shapely documentation for the method object.buffer() 

65 <https://shapely.readthedocs.io/en/stable/manual.html#object.buffer>`_ : 

66 

67 "Passed a distance of 0, buffer() can sometimes be used to "clean" 

68 self-touching or self-crossing polygons such as the classic "bowtie". 

69 Users have reported that very small distance values sometimes produce 

70 cleaner results than 0. Your mileage may vary when cleaning surfaces." 

71 

72 According to the `Shapely documentation for the function 

73 shapely.geometry.polygon.orient() 

74 <https://shapely.readthedocs.io/en/stable/manual.html#shapely.geometry.polygon.orient>`_ : 

75 

76 "A sign of 1.0 means that the coordinates of the product's exterior ring 

77 will be oriented counter-clockwise." 

78 

79 Copyright 2017 Thomas Guymer [1]_ 

80 

81 References 

82 ---------- 

83 .. [1] PyGuymer3, https://github.com/Guymer/PyGuymer3 

84 """ 

85 

86 # Import special modules ... 

87 try: 

88 import shapely 

89 import shapely.geometry 

90 except: 

91 raise Exception("\"shapely\" is not installed; run \"pip install --user Shapely\"") from None 

92 

93 # Import sub-functions ... 

94 from ..check import check 

95 from .buffer_CoordinateSequence import buffer_CoordinateSequence 

96 

97 # ************************************************************************** 

98 

99 # Check argument ... 

100 assert isinstance(point, shapely.geometry.point.Point), "\"point\" is not a Point" 

101 if debug: 

102 check(point, prefix = prefix) 

103 

104 # Return buffered Point ... 

105 return buffer_CoordinateSequence( 

106 point.coords, 

107 dist, 

108 debug = debug, 

109 eps = eps, 

110 fill = fill, 

111 fillSpace = fillSpace, 

112 nAng = nAng, 

113 nIter = nIter, 

114 prefix = prefix, 

115 ramLimit = ramLimit, 

116 simp = simp, 

117 tol = tol, 

118 )