Coverage for pyguymer3/geo/bufferSrc/buffer_LineString.py: 8%

1#!/usr/bin/env python3 

2 

3# Define function ... 

4def buffer_LineString( 

5 line, 

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 LineString 

21 

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

23 and returns a [Multi]Polygon of the same LineString buffered by a constant 

24 distance (in metres). 

25 

26 Parameters 

27 ---------- 

28 line : shapely.geometry.linestring.LineString 

29 the LineString 

30 dist : float 

31 the Geodesic distance to buffer each point within the LineString by (in 

32 metres) 

33 debug : bool, optional 

34 print debug messages 

35 eps : float, optional 

36 the tolerance of the Vincenty formula iterations 

37 fill : float, optional 

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

39 the shapes by (in degrees or metres) 

40 fillSpace : str, optional 

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

42 or "GeodesicSpace") 

43 nAng : int, optional 

44 the number of angles around each point within the LineString that are 

45 calculated when buffering 

46 nIter : int, optional 

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

48 prefix : str, optional 

49 change the name of the output debugging CSVs 

50 ramLimit : int, optional 

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

52 simp : float, optional 

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

54 disable simplification (in degrees) 

55 tol : float, optional 

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

57 degrees) 

58 

59 Returns 

60 ------- 

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

62 the buffered LineString 

63 

64 Notes 

65 ----- 

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

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

68 

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

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

71 Users have reported that very small distance values sometimes produce 

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

73 

74 According to the `Shapely documentation for the function 

75 shapely.geometry.polygon.orient() 

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

77 

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

79 will be oriented counter-clockwise." 

80 

81 Copyright 2017 Thomas Guymer [1]_ 

82 

83 References 

84 ---------- 

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

86 """ 

87 

88 # Import special modules ... 

89 try: 

90 import shapely 

91 import shapely.geometry 

92 except: 

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

94 

95 # Import sub-functions ... 

96 from ..check import check 

97 from .buffer_CoordinateSequence import buffer_CoordinateSequence 

98 

99 # ************************************************************************** 

100 

101 # Check argument ... 

102 assert isinstance(line, shapely.geometry.linestring.LineString), "\"line\" is not a LineString" 

103 if debug: 

104 check(line, prefix = prefix) 

105 

106 # Return buffered LineString ... 

107 return buffer_CoordinateSequence( 

108 line.coords, 

109 dist, 

110 debug = debug, 

111 eps = eps, 

112 fill = fill, 

113 fillSpace = fillSpace, 

114 nAng = nAng, 

115 nIter = nIter, 

116 prefix = prefix, 

117 ramLimit = ramLimit, 

118 simp = simp, 

119 tol = tol, 

120 )