SymPy 几何实体基类解析：GeometryEntity 与 GeometrySet 的完整 API 指南

SymPy 几何实体基类解析GeometryEntity 与 GeometrySet 的完整 API 指南【免费下载链接】sympyA computer algebra system written in pure Python项目地址: https://gitcode.com/GitHub_Trending/sy/sympy几何实体GeometryEntity是 SymPy 几何模块sympy.geometry的根抽象层。本文基于模块 API 文档 entities.rst 所指向的类定义结合 entity.py 源码与其测试用例 test_entity.py系统讲解 GeometryEntity / GeometrySet 的继承关系、通用成员方法与属性、集合运算适配机制、几何变换能力以及参数化求值等核心内容帮助读者理解点、线、圆、多边形等所有几何对象的公共行为并能直接用这些底层 API 完成几何运算与二次开发。一、文档定位与类概览entities.rst 是几何模块 API 文档的入口之一在 index.rst 的 Submodules 目录中被引用它通过 Sphinx 的autoclass指令将sympy.geometry.entity.GeometryEntity的完整 docstring 渲染成文档。虽然该文件正文只有两条指令但它指向的类承载了全部几何实体共享的核心实现。在 entity.py 的模块 docstring 中明确了类的定位The definition of the base geometrical entity with attributes common to all derived geometrical entities.所有派生几何实体公共属性的基类定义该模块包含两个类类作用GeometryEntity一切具有几何性质对象的基类GeometrySet同时可被看作sympy.sets.Set的几何实体的父类关键设计点Point 是唯一不属于 Set 的 GeometryEntity而其余实体线段、直线、圆、多边形、平面等都同时是集合可与sympy.sets体系互操作。模块还引入了Rnn 维欧氏空间的概念目前仅实现了R2与R3两种环境空间。类的继承结构见 entity.pyclass GeometryEntity(Basic, EvalfMixin): The base class for all geometrical entities. class GeometrySet(GeometryEntity, Set): Parent class of all GeometryEntity that are also Sets (compatible with sympy.sets)即GeometryEntity继承自 SymPy 的表达式基类Basic获得符号表达式、参数替换subs、遍历等能力与EvalfMixin获得数值求值n()/evalf()能力GeometrySet再混入Set使几何实体能参与集合运算。二、实体构造与序列化__new__、__repr__、__str__2.1 构造时的参数归一化GeometryEntity.__new__entity.py在创建实例时对参数做归一化将序列参数转换为Tuple其他参数通过sympify转为 SymPy 对象。特别地它用is_Point属性检测避免把Point误转成Tuple——因为点本身是序列sequence但不能被当作坐标元组处理def is_seq_and_not_point(a): if hasattr(a, is_Point) and a.is_Point: return False return is_sequence(a) args [Tuple(*a) if is_seq_and_not_point(a) else sympify(a) for a in args] return Basic.__new__(cls, *args)同时__getnewargs__返回self.args元组保证实体可被正常 pickle 序列化/反序列化。2.2 字符串表示__str__返回可读形式__repr__返回可被 eval 重建同一实体的形式def __repr__(self): return type(self).__name__ repr(self.args) def __str__(self): return type(self).__name__ sstr(self.args)例如Triangle(Point2D(1, 0), Point2D(-1/2, sqrt(3)/2), ...)这样的输出即由此产生__repr__形式可直接粘贴回 Python 重新求值。2.3 反向运算协议__radd__、__rmul__、__rsub__、__rtruediv__使几何实体能安全地出现在算术运算的右侧如2 * segment统一转发给左操作数。三、通用几何属性ambient_dimension与bounds两个只读属性由基类声明由子类具体实现未实现时抛NotImplementedErrorambient_dimensionentity.py对象所在空间的维度。Point2D返回 2Point3D、Plane返回 3圆、多边形等二维实体返回 2。boundsentity.py返回包围矩形(xmin, ymin, xmax, ymax)是绘制 SVG、计算包围盒的基础。bounds也是_repr_svg_能否工作的前提如果bounds抛异常或包含非有限数值如符号或无穷大_repr_svg_返回None让 Jupyter/IPython 回退到其他表示形式。这一点在测试 test_entity.py 中有明确验证符号半径的Circle(Point(a, b), d)与半径为S.Infinity的圆其_repr_svg_()均为None。四、成员测试与包含关系__contains__、encloses4.1 相等与成员测试__contains__entity.py的默认行为同类型实体比较是否相等否则抛NotImplementedError由子类实现更复杂的语义如点是否在线段上、是否在圆内。测试 test_entity.py 验证assert GeometryEntity(x, y) in GeometryEntity(x, y) raises(NotImplementedError, lambda: Point(0, 0) in GeometryEntity(x, y)) assert GeometryEntity(x, y) GeometryEntity(x, y) assert GeometryEntity(x, y).equals(GeometryEntity(x, y))注意equalsentity.py在基类中即等价于子类可以重写为更严格的数学等价判断。4.2encloses判断是否包含另一个实体encloses(o)entity.py是通用包含判定返回True表示o位于 self 内部不含边界。它会将对象分解为点各实体只需实现各自的encloses_point即可Point直接调用self.encloses_point(o)Segment要求两个端点都被包含Ray / Line无限延伸恒返回FalseEllipse中心与右端点在内部且两者不相交Polygon / RegularPolygon所有顶点都在内部正多边形额外要求中心在内部内置示例entity.py from sympy import RegularPolygon, Point, Polygon t Polygon(*RegularPolygon(Point(0, 0), 1, 3).vertices) t2 Polygon(*RegularPolygon(Point(0, 0), 2, 3).vertices) t2.encloses(t) True t.encloses(t2) False测试 test_entity.py 覆盖了圆对点、线段、直线、内切圆、三角形、外接正多边形的包含判定c Circle((0, 0), 5) assert GeometryEntity.encloses(c, Point(0, 0)) assert GeometryEntity.encloses(c, Segment((0, 0), (1, 1))) assert GeometryEntity.encloses(c, Line((0, 0), (1, 1))) is False assert GeometryEntity.encloses(c, Circle((0, 0), 4)) assert GeometryEntity.encloses(c, Polygon(Point(0, 0), Point(1, 0), Point(0, 1))) assert GeometryEntity.encloses(c, RegularPolygon(Point(8, 8), 1, 3)) is Falseencloses_point的实际实现在各子类中例如 ellipse.py椭圆/圆内部、polygon.py多边形内部。五、集合运算适配GeometrySet与union_sets/intersection_setsGeometrySet是GeometryEntity与sympy.sets.Set的双重子类因此天然支持集合运算。为使Union、Intersection等集合操作正确处理几何实体模块通过multipledispatch注册了两个分发函数entity.pyunion_sets(self, o)——几何实体与任意Set求并集若o是FiniteSet剔除其中已被 self 包含的点剩余的并入FiniteSet形成Union(self, FiniteSet(*other_points))若 self 不包含其中任何点返回None表示无法化简。若 self 完全包含o直接返回self。intersection_sets(self, o)——求交集o为FiniteSet时直接筛选出self.contains(p)的点构造FiniteSet避免无限递归否则调用self.intersection(o)捕获NotImplementedError并返回None最后把交点归入FiniteSet、非点部分保留整体合并为Union返回。GeometrySet._contains兼容sympy.sets的接口约定对FiniteSet逐个元素判定否则转发给__contains__。这套机制意味着可以写出如Circle((0, 0), 1) | FiniteSet(Point(2, 2))之类的表达式并得到语义正确的集合结果。六、实体间关系判定intersection与is_similar6.1intersection(o)求 self 与o的所有交点返回交点列表entity.py。基类仅声明协议不要求所有实体实现。模块内存在一个分工约定docstring 原文If two different types of entities can intersect, the item with higher index in ordering_of_classes should implement intersections with anything having a lower index.若两类实体可能相交ordering_of_classes中序号较大者应实现与所有序号较小者的求交全局求交入口是 util.py 中的intersection(*entities)函数通常调用entity1.intersection(entity2)即可。6.2 相似判定is_similar与are_similaris_similar(other)entity.py判断两个实体是否相似——即其中一个经过均匀缩放enlarge/shrink能否得到另一个。docstring 特别说明该方法不建议直接调用应通过 util.py 的are_similar函数使用实体不强制实现该方法若两类实体可能相似只要求其中一方能判断即可。七、几何变换rotate、scale、translate、reflect基类为所有实体提供四种仿射变换均返回变换后的新实体不可变风格并给出了大量 doctest 示例。7.1rotate(angle, ptNone)绕点pt逆时针旋转angle弧度默认绕原点Point(0, 0)旋转entity.py。实现是对每个args递归调用自身的rotate非几何参数原样保留。 from sympy import Point, RegularPolygon, Polygon, pi t Polygon(*RegularPolygon(Point(0, 0), 1, 3).vertices) t # vertex on x axis Triangle(Point2D(1, 0), Point2D(-1/2, sqrt(3)/2), Point2D(-1/2, -sqrt(3)/2)) t.rotate(pi/2) # vertex on y axis now Triangle(Point2D(0, 1), Point2D(-sqrt(3)/2, -1/2), Point2D(sqrt(3)/2, -1/2))7.2scale(x1, y1, ptNone)按x、y因子缩放坐标若给出pt则先平移到该点再缩放再平移回来相对该点缩放见 entity.py t.scale(2) Triangle(Point2D(2, 0), Point2D(-1, sqrt(3)/2), Point2D(-1, -sqrt(3)/2)) t.scale(2, 2) Triangle(Point2D(2, 0), Point2D(-1, sqrt(3)), Point2D(-1, -sqrt(3)))7.3translate(x0, y0)对坐标整体加上偏移量entity.py t.translate(2) Triangle(Point2D(3, 0), Point2D(3/2, sqrt(3)/2), Point2D(3/2, -sqrt(3)/2)) t.translate(2, 2) Triangle(Point2D(3, 2), Point2D(3/2, sqrt(3)/2 2), Point2D(3/2, 2 - sqrt(3)/2))7.4reflect(line)沿直线line反射对象entity.py。实现按直线斜率分三种情况水平线直接scale(y-1)、竖直线scale(x-1)、一般直线通过平移 → 旋转到水平 → 翻转 → 旋转回来 → 平移的复合变换作用于每个原子Point。内置示例 from sympy import pi, sqrt, Line, RegularPolygon l Line((0, pi), slopesqrt(2)) pent RegularPolygon((1, 2), 1, 5) rpent pent.reflect(l) rpent RegularPolygon(Point2D(-2*sqrt(2)*pi/3 - 1/3 4*sqrt(2)/3, 2/3 2*sqrt(2)/3 2*pi/3), -1, 5, -atan(2*sqrt(2)) 3*pi/5) circ Circle(Point(0, 0), 5) rcirc circ.reflect(Line((0, pi), slope1)) rcirc Circle(Point2D(-pi, pi), -5)注意反射后半径取负Circle(Point2D(-pi, pi), -5)在测试 test_entity.py 中则体现为c.area -cr.area反射翻转了定向面积。八、参数化与求值arbitrary_point、parameter_value、subs8.1arbitrary_point(parametert)由子类实现返回实体上的参数化点。各实体的具体行为Lineline.pyp1 (p2 - p1)*tt0时返回第一个定义点t1时返回第二个若参数名已存在于对象中则抛ValueError。Polygonpolygon.py参数从 0 到 1 对应沿周长的位置。Ellipseellipse.py标准三角函数参数化。Curvecurve.py按曲线的定义表达式。Planeplane.py支持 1 或 2 个参数。8.2parameter_value(other, t)反查参数给定实体上的一个点求解该点对应的参数值entity.py。内部通过解方程self.arbitrary_point(T) - other 0实现若点不在实体上则抛ValueError from sympy import Line, Point from sympy.abc import t Line(Point(0, 0), Point(2, 2)).parameter_value((1, 1), t) {t: 1/2} Line(Point(0, 0), Point(2, 2)).arbitrary_point(t).subs(_) Point2D(1, 1)8.3subs与_eval_subs实体支持Basic的符号替换。_eval_subsentity.py专门处理用点替换点/元组的情况当old/new是序列或Point时把坐标元组包装成Point/Point3D后再替换。测试 test_entity.py 覆盖了各种替换形式例如assert Point(1, 2).subs({x: 1}) Point(1, 2) # 符号替换 assert Point(1, 2).subs(Point(1, 2), Point(3, 4)) Point(3, 4) # 点换点 assert Point(1, 2).subs((1, 2), Point(3, 4)) Point(3, 4) # 元组换点同时_sympy_返回自身使实体可被sympify幂等处理。九、数值求值与 SVG 渲染9.1EvalfMixin数值求值由于GeometryEntity混入了EvalfMixin所有实体可直接调用.n(dps)/.evalf(dps)获得数值近似。测试 test_entity.py 对 12 种实体点、平面、曲线、椭圆、圆、直线、线段、射线、抛物线、多边形、正多边形、三角形逐一验证str(g).replace(pi, 3.1) str(g.n(2))。9.2_repr_svg_IPython 内联 SVG_repr_svg_entity.py为 Jupyter 等富文本环境生成 SVG。实现细节获取bounds若无法获取或含非有限值则返回None回退建立 SVG 画布按数据范围加 10% 边距保持箭头可见点对象特殊处理为 0.5 单位缓冲通过_svg(scale_factor)子类方法生成路径元素默认填充色#66cc99宽度上下限 100–300用matrix(1,0,0,-1,0,ymaxymin)翻转 Y 轴使坐标与数学约定一致。_svg在基类抛NotImplementedErrorentity.py由各实体实现具体的 SVG 路径绘制。十、实体排序约定ordering_of_classesentity.py 定义了模块级的类排序列表它是求交、相似判定等跨类型操作由谁来主导实现的依据ordering_of_classes [ Point2D, Point3D, Point, Segment2D, Ray2D, Line2D, Segment3D, Line3D, Ray3D, Segment, Ray, Line, Plane, Triangle, RegularPolygon, Polygon, Circle, Ellipse, Curve, Parabola ]从源码结构可以推断该顺序大致反映了维度从低到高、结构从简到繁的层次点 → 线 → 平面/多边形 → 圆锥曲线/曲线序号大的类负责实现与序号小的类之间的交互运算从而避免双向实现造成重复与冲突。十一、仿射变换矩阵辅助函数模块底部还提供了三个构造 3×3 仿射变换矩阵的模块级函数作用于齐次坐标(x, y, 1)供Point.transform等使用translate(x, y)entity.py平移矩阵第三行存(x, y)。scale(x, y, ptNone)entity.py缩放矩阵给出pt时等价于translate(-pt) · scale · translate(pt)。rotate(th)entity.py绕原点旋转th弧度。矩阵可以左乘复合例如绕(1,1)旋转 90° from sympy.geometry.entity import rotate, translate from sympy import Point, pi rot_about_11 translate(-1, -1)*rotate(pi/2)*translate(1, 1) Point(1, 1).transform(rot_about_11) Point2D(1, 1) Point(0, 0).transform(rot_about_11) Point2D(2, 0)测试 test_entity.py 验证了scale(1, 2, (3, 4))的矩阵形式为[[1, 0, 0], [0, 2, 0], [0, -4, 1]]——注意左下角-4正是先平移再缩放再平移复合的结果。十二、在真实场景中使用综合以上 API一个典型的几何分析流程如下 from sympy import Point, Triangle, Circle, Line, intersection t Triangle(Point(0, 0), Point(2, 0), Point(0, 2)) t.area # 面积有符号顺时针为负 2 abs(t.area) # 取绝对值得到普通面积 2 t.encloses(Point(1, 1)) True c Circle(Point(1, 1), 1) t.encloses(c) # 圆是否整体落在三角形内 False intersection(Line(Point(0, 0), Point(1, 1)), c) [Point2D(0, 0), Point2D(2, 2)]若要开发自定义几何实体只需继承GeometryEntity至少实现ambient_dimension、bounds、arbitrary_point等抽象成员若希望新实体参与Union/Intersection集合运算则应继承GeometrySet并复用 entity.py 注册的分发逻辑。小结GeometryEntity 与 GeometrySet 构成了 SymPy 几何模块的统一抽象层前者借助Basic与EvalfMixin提供符号替换、数值求值与仿射变换后者打通了与sympy.sets集合体系的互操作。理解这两个基类即可掌握 Point、Line、Polygon、Ellipse 等全部几何实体背后共享的成员语义、跨实体运算分工约定ordering_of_classes以及二次开发所需的扩展点。更完整的实体清单、全局工具函数intersection、convex_hull、are_similar等与使用示例可进一步阅读 index.rst 及其指向的 utils.rst 等子模块文档。【免费下载链接】sympyA computer algebra system written in pure Python项目地址: https://gitcode.com/GitHub_Trending/sy/sympy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考