Shapely从1.7.1升级到1.8时parallel_offset功能异常问题

我维护一个依赖Shapely的大型项目，将Shapely从1.7.1版本升级到1.8版本后，遇到parallel_offset功能的异常：部分LineString偏移后，原本预期返回LineString，实际却生成了MultiLineString，导致下游代码大量报错。部分相似几何对象不会触发该问题，原因不明。查看Shapely源码后怀疑和GEOS版本有关，但尚未确认不同Shapely版本打包的GEOS是否存在差异。希望得到解决思路，先完成1.7.1到1.8的升级，再过渡到2.0版本。

最小复现代码 #

import numpy as np
from shapely.geometry import LinearRing, LineString, MultiLineString
import matplotlib.pyplot as plt
from shapely import __version__

print(__version__)


pts = np.asarray([[809.29025038, -1.22445615],
                  [796.0907264, -1.6687565],
                  [783.00450305, -2.3655554],
                  [770.01539453, -3.28167197],
                  [757.11530794, -4.39201819],
                  [744.31233618, -5.66988749],
                  [731.59838634, -7.09504763],
                  [718.95727263, -8.64726633],
                  [706.39708795, -10.3095485],
                  [693.90973938, -12.06489905],
                  [681.48713404, -13.89146715],
                  [669.12927192, -15.77468556],
                  [656.82806011, -17.69674991],
                  [644.58349862, -19.64228367],
                  [632.37940165, -21.59348246],
                  [620.22386209, -23.53416048],
                  [608.10878704, -25.44651334],
                  [596.0260836, -27.31597382],
                  [583.97575177, -29.12554682],
                  [571.94969865, -30.8622837],
                  [559.93983134, -32.51323581],
                  [559.93983134, 32.51323581],
                  [571.94969865, 30.8622837],
                  [583.97575177, 29.12554682],
                  [596.0260836, 27.31597382],
                  [608.10878704, 25.44651334],
                  [620.22386209, 23.53416048],
                  [632.37940165, 21.59348246],
                  [644.58349862, 19.64228367],
                  [656.82806011, 17.69674991],
                  [669.12927192, 15.77468556],
                  [681.48713404, 13.89146715],
                  [693.90973938, 12.06489905],
                  [706.39708795, 10.3095485],
                  [718.95727263, 8.64726633],
                  [731.59838634, 7.09504763],
                  [744.31233618, 5.66988749],
                  [757.11530794, 4.39201819],
                  [770.01539453, 3.28167197],
                  [783.00450305, 2.3655554],
                  [796.0907264, 1.6687565],
                  [809.29025038, 1.22445615],
                  [809.29025038, -1.22445615]])

line = LineString(pts)

plt.plot(*line.xy, '+-', color='blue')

inside = line.parallel_offset(distance=2.6, side="right", resolution=0, join_style=3)
print(f"Inside offset is type {type(inside)}")

if isinstance(inside, LineString):
    plt.plot(*inside.xy, '+-', color='orange')
elif isinstance(inside, MultiLineString):
    plt.plot(*inside[0].xy, '+-', color='orange')
    plt.plot(*inside[1].xy, '+-', color='green')

plt.show()

版本输出对比 #

Shapely 1.7.1预期输出 #

1.7.1 
Inside offset is type <class 'shapely.geometry.linestring.LineString'>

Shapely 1.8.5实际输出 #

1.8.5
Inside offset is type <class 'shapely.geometry.multilinestring.MultiLineString'>

解决思路 #

• 确认GEOS版本差异：Shapely的parallel_offset依赖GEOS实现，Shapely 1.7.1通常打包GEOS 3.8.x，而1.8.x版本打包GEOS 3.9.x，GEOS在3.9版本中对偏移算法做了优化，可能导致返回类型变化。可以通过shapely.geos_version查看当前GEOS版本，对比两个版本的GEOS差异。
• 兼容返回类型：修改下游代码，统一处理LineString和MultiLineString的情况。比如封装一个工具函数，将返回结果转换为统一类型：如果是MultiLineString，可根据需求合并为LineString（确保线段连续）或保留多段，避免类型判断报错。

  def safe_parallel_offset(line, distance, **kwargs):
      result = line.parallel_offset(distance, **kwargs)
      if isinstance(result, MultiLineString):
          # 尝试合并连续线段
          merged = None
          for part in result.geoms:
              if merged is None:
                  merged = part
              else:
                  merged = merged.union(part)
          return merged if isinstance(merged, LineString) else result
      return result
  

• 调整offset参数：尝试调整join_style、resolution等参数。比如将join_style从3改为其他值，或者设置resolution为默认的16，观察是否能稳定返回LineString。注意resolution=0在新版本中可能行为有变化。
• 几何预处理：对输入的LineString进行预处理，比如简化几何（使用line.simplify()），去除重复点或接近重合的点，避免因几何精度问题导致偏移时生成多段线。
• 过渡到Shapely 2.0的准备：Shapely 2.0对GEOS的依赖和API有更多调整，建议先在测试环境验证1.8版本的修改是否能平滑过渡到2.0，提前处理类型兼容逻辑。

内容的提问来源于stack exchange，提问作者gohu