735 lines
26 KiB
Markdown
735 lines
26 KiB
Markdown
PySSMath 模块提供了丰富的数学计算功能，专为 GIS 和测绘应用设计。该模块通过 SWIG 封装底层 C++ 实现，提供高性能的几何计算、坐标转换、空间关系判断等核心算法库。本文档面向高级开发者，详细说明各类数学计算工具的 API 接口与应用场景。
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L1-L20)
|
||
|
||
## 模块架构概览
|
||
|
||
PySSMath 模块采用分层架构设计，将数学计算功能划分为多个功能域。底层通过 `_PySSMath.pyd` C++ 扩展模块实现高效计算，上层 Python 接口提供类型安全的函数调用。
|
||
|
||
```mermaid
|
||
graph TB
|
||
A[PySSMath 模块] --> B[坐标系统转换]
|
||
A --> C[距离与长度计算]
|
||
A --> D[面积计算]
|
||
A --> E[角度与方位角]
|
||
A --> F[几何变换]
|
||
A --> G[空间关系判断]
|
||
A --> H[弧线与圆操作]
|
||
A --> I[点与线操作]
|
||
|
||
B --> B1[deg/radian/dms转换]
|
||
C --> C1[点距离/线长度]
|
||
D --> D1[多边形面积/三角形面积]
|
||
E --> E1[方位角/夹角/方向]
|
||
F --> F1[旋转/偏移/缩放/镜像]
|
||
G --> G1[相交/包含/共线]
|
||
H --> H1[弧长/中点/打断]
|
||
I --> I1[插入/延伸/修剪]
|
||
|
||
A --> J[基础数据结构]
|
||
J --> J1[Point3D]
|
||
J --> J2[Vec3d]
|
||
J --> J3[POINT3DLIST]
|
||
J --> J4[LINE3DLIST]
|
||
```
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L1-L120)
|
||
|
||
## 基础数据结构
|
||
|
||
### Point3D - 三维点类
|
||
|
||
Point3D 是模块的核心数据结构，表示三维空间中的点，支持 x、y、z 坐标访问和丰富的运算符重载。
|
||
|
||
**构造方法**：
|
||
- `Point3D()` - 默认构造函数
|
||
- `Point3D(x, y, z)` - 使用坐标构造
|
||
- `Point3D(other)` - 拷贝构造
|
||
|
||
**核心属性与方法**：
|
||
- `x()`, `y()`, `z()` - 获取坐标分量
|
||
- `set(x_arg, y_arg, z_arg)` - 设置坐标
|
||
- `__getitem__(i)` / `__setitem__(i, value)` - 索引访问坐标（0=x, 1=y, 2=z）
|
||
- `__add__`, `__sub__`, `__neg__` - 向量运算
|
||
- `epsilonEqual(other, epsilon)` - 带容差的相等判断
|
||
- `getName()`, `setName(name)` - 点名称管理
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L710-L775)
|
||
|
||
### Vec3d - 三维向量类
|
||
|
||
Vec3d 提供完整的向量运算功能，包括点积、叉积、缩放等操作。
|
||
|
||
**构造方法**：
|
||
- `Vec3d()` - 默认构造
|
||
- `Vec3d(x, y, z)` - 使用分量构造
|
||
- `Vec3d(other)` - 拷贝构造
|
||
|
||
**核心方法**：
|
||
- `dot(rhs)` - 点积运算
|
||
- `cross(rhs)` - 叉积运算
|
||
- `__mul__`, `__truediv__` - 标量乘除
|
||
- `set(x_arg, y_arg, z_arg)` - 设置分量
|
||
- `epsilonEqual(other, epsilon)` - 带容差的相等判断
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L5345-L5400)
|
||
|
||
### 容器类
|
||
|
||
模块提供多种容器类用于管理点的集合：
|
||
- `POINT3DLIST` - 点列表容器
|
||
- `LINE3DLIST` - 线列表容器
|
||
- `LOOP3DLIST` - 环列表容器（支持带岛复杂面）
|
||
- `StringArray` - 字符串数组容器
|
||
|
||
这些容器均支持迭代器模式，提供 `size()`, `empty()`, `clear()`, `push_back()` 等标准容器操作。
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L122-L200)
|
||
|
||
## 坐标系统转换
|
||
|
||
### 角度格式转换
|
||
|
||
PySSMath 提供多种角度表示形式之间的转换功能，支持弧度制、十进制度数、度分秒（DMS）格式互转。
|
||
|
||
| 函数名 | 功能描述 | 参数 | 返回值 |
|
||
|--------|----------|------|--------|
|
||
| `degToRadian(deg)` | 十进制度数转弧度 | deg: float | 弧度值 |
|
||
| `radianToDeg(dRadian)` | 弧度转十进制度数 | dRadian: float | 度数值 |
|
||
| `degToDms(deg)` | 十进制度数转度分秒 | deg: float | DMS 值 |
|
||
| `dmsToDeg(dms)` | 度分秒转十进制度数 | dms: float | 度数值 |
|
||
| `dmsToRadian(dDms)` | 度分秒转弧度 | dDms: float | 弧度值 |
|
||
| `radianToDms(dRadian)` | 弧度转度分秒 | dRadian: float | DMS 值 |
|
||
| `dmsToSec(dms)` | 度分秒转秒数 | dms: float | 秒数 |
|
||
| `secToDms(sec)` | 秒数转度分秒 | sec: float | DMS 值 |
|
||
|
||
**角度调整函数**：
|
||
- `adjustAngle(dRadian)` - 调整弧度值到 [-π, π] 范围
|
||
- `adjustDmsAngle(dAngle)` - 调整 DMS 角度值
|
||
- `adjustDegAngle(dAngle)` - 调整度数值到 [0, 360] 范围
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2772-L2787)
|
||
|
||
### 极坐标与直角坐标转换
|
||
|
||
| 函数名 | 功能描述 |
|
||
|--------|----------|
|
||
| `rightToPolar(x, y)` | 直角坐标转极坐标 |
|
||
| `polarToRight(r, angle)` | 极坐标转直角坐标 |
|
||
| `getPolar(p1, p2, dist, dRadian)` | 从点 p1 按给定距离和方位角获取极坐标点 |
|
||
| `getPoint(p1, p2, dist, dRadian)` - 同 `getPolar` |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2808-L2815)
|
||
|
||
## 距离与长度计算
|
||
|
||
### 点与点距离
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `distance(p1, p2)` | 两点间二维距离（仅 xy） | float |
|
||
| `distance3d(p1, p2)` | 两点间三维距离 | float |
|
||
| `getDistSquare(p1, p2)` | 两点间距离的平方 | float |
|
||
| `get3dDistSquare(p1, p2)` | 两点间三维距离的平方 | float |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2680-L2690)
|
||
|
||
### 点到线距离
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `getDistPtToLine(p, p1, p2)` | 点到线段的距离 | float |
|
||
| `distPerpend(p0, p1, p2, pResPerpend, pResRelation)` | 点到线的垂距 | float |
|
||
| `distParallel(p0, p1, p2)` | 点到线的平行距 | float |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2710-L2720)
|
||
|
||
### 线段长度
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `getLinesSumlen(pList)` | 点列表构成线段的总长度（2D） | float |
|
||
| `getLinesSumlen3d(pList)` | 点列表构成线段的总长度（3D） | float |
|
||
| `getSumlen(pList, nLineType, mapScale)` | 获取长度（支持线型类型和比例尺） | float |
|
||
| `get3DLength(*args)` | 获取三维长度 | float |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2692-L2700)
|
||
|
||
### 高级距离查询
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `getNearDist(p0, pList, nOrder)` | 获取第 nOrder 近的距离 | float |
|
||
| `getNearstDistSquare(sp, Points, pNodeIndex, pSideIndex, pDirFlag, ptNearstOnline)` | 获取最近距离平方（附带详细信息） | float |
|
||
| `getDistForPoint(p, pList)` | 点到点列表中某点的距离 | float |
|
||
| `getDistDir(p, pList, irec, flag)` | 获取距离和方向 | float |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2702-L2710)
|
||
|
||
## 面积计算
|
||
|
||
### 多边形面积
|
||
|
||
| 函数名 | 功能描述 | 参数说明 |
|
||
|--------|----------|----------|
|
||
| `getPolyArea(points, bHaveSgin)` | 计算多边形面积 | points: 点列表；bHaveSgin: 是否保留符号（正为逆时针） |
|
||
| `calTriHeight(a, b, c)` | 计算三角形高 | a, b, c: 三角形三边长 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2698-L2700)
|
||
|
||
### 三角形面积
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `get3DArea(sp0, sp1, sp2)` | 计算三点构成的三角形面积 | float |
|
||
| `get3DAreaInDirection(direP, sp0, sp1, sp2)` | 计算指定方向下的三角形面积 | float |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2793-L2796)
|
||
|
||
## 角度与方位角计算
|
||
|
||
### 方位角计算
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `bearing(x1, y1, x0, y0)` | 计算从 (x0, y0) 到 (x1, y1) 的方位角 | 弧度值 |
|
||
| `bearing(p0, p1)` - 重载形式，使用 Point3D 对象 |
|
||
| `jiaoPingfenFangWei(x1, y1, x0, y0, x2, y2)` | 计算两线段的夹角平分方位角 | 弧度值 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2789-L2792)
|
||
|
||
### 夹角计算
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `openAngle(p1, p0, p2)` | 计算 ∠p1p0p2 的夹角 | 弧度值 |
|
||
| `openAngleDeg(p1, p0, p2)` | 计算 ∠p1p0p2 的夹角（度数） | 度数 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2791-L2794)
|
||
|
||
### 方向计算
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `get3Direction(p0, p1)` | 获取三维空间方向向量 | Vec3d |
|
||
| `getDirection(sp, sp1, sp2)` | 获取方向 | int |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2794-L2797)
|
||
|
||
## 几何变换操作
|
||
|
||
### 二维/三维变换
|
||
|
||
| 函数名 | 功能描述 | 参数说明 |
|
||
|--------|----------|----------|
|
||
| `rotate2DList(Points, angle, basePoint)` | 二维点集旋转 | angle: 旋转角；basePoint: 旋转基点 |
|
||
| `rotate3DList(*args)` | 三维点集旋转 | 支持多种参数形式 |
|
||
| `offset2DList(Points, dx, dy)` | 二维点集平移 | dx, dy: 平移量 |
|
||
| `offset3DList(*args)` | 三维点集偏移 | 支持多种参数形式 |
|
||
| `zoom3DList(*args)` | 三维点集缩放 | 支持缩放中心 |
|
||
| `mirror3DList(baseP0, baseP1, Ps)` | 三维点集镜像 | baseP0, baseP1: 镜像轴上的两点；Ps: 点集 |
|
||
| `extend3DList(Points, dist, bTail)` | 点集延伸 | dist: 延伸距离；bTail: true=尾部延伸，false=头部延伸 |
|
||
| `smooth3DList(Ps0, fScale, nFlag)` | 点集平滑 | fScale: 平滑系数；nFlag: 平滑方式 |
|
||
| `mapping3DList(Points, ctrlPoints_old, ctrlPoints_new)` | 点集映射变换 | 基于控制点的仿射变换 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2819-L2840)
|
||
|
||
### 系统坐标旋转
|
||
|
||
| 函数名 | 功能描述 | 参数说明 |
|
||
|--------|----------|----------|
|
||
| `sysRotate(Xold, Yold, Xnew, Ynew, X0, Y0, dRadian)` | 系统旋转 | 将旧坐标系旋转至新坐标系 |
|
||
| `grdbodyRotate(*args)` | 网格体旋转 | 支持多种参数形式 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2816-L2820)
|
||
|
||
## 几何关系判断
|
||
|
||
### 点与点关系
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `isSamePoint(p0, p1, epsilon)` | 判断两点是否相同（仅 xy） | boolean |
|
||
| `isSame3dPoint(p0, p1, epsilon)` | 判断两点是否相同（xyz） | boolean |
|
||
| `isSameCoord(*args)` | 判断坐标是否相同 | boolean |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2867-L2877)
|
||
|
||
### 点与线关系
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `isPointOnLine(sp, sp1, sp2, dbLimit)` | 判断点是否在线段上 | boolean |
|
||
| `pointOnLine(*args)` | 点在线上判断（重载） | boolean |
|
||
| `getOnLinePosition(sp, sp1, sp2, dbLimit)` | 获取点在线段上的位置 | float |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2879-L2885)
|
||
|
||
### 点与多边形关系
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `ptInPoly(x, y, pPolygon, limit)` | 判断点是否在多边形内 | boolean |
|
||
| `ptInTriangle(x, y, x1, y1, x2, y2, x3, y3)` | 判断点是否在三角形内 | boolean |
|
||
| `isPointListInPoly(*args)` | 判断点集是否在多边形内 | boolean |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2901-L2905)
|
||
|
||
### 线与线关系
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `isLineCrossLine(sp1, sp2, sp3, sp4)` | 判断两线段是否相交 | boolean |
|
||
| `isLineCrossLines(sp1, sp2, Ps)` | 判断线段与多段线是否相交 | boolean |
|
||
| `getCrossPoint(*args)` | 获取线段交点 | Point3D |
|
||
| `lineCrossLine(Line, Line1, newLine, pattr)` - 线段相交处理 |
|
||
| `lineCrossLines(*args)` - 线段与多段线相交处理 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L5222-L5230)
|
||
|
||
### 多边形与多边形关系
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `isPolygonInPolygon(rl, line, limit)` | 判断多边形是否在另一多边形内 | boolean |
|
||
| `isPolygonInPolygonComplex(polygon1, polygon2, limit)` | 判断复杂多边形关系（支持带岛） | int |
|
||
|
||
**复杂多边形关系返回值**：
|
||
- `0` - 不相关
|
||
- `1` - polygon1 包含 polygon2
|
||
- `2` - polygon2 包含 polygon1
|
||
- `3` - 相交
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2893-L2903)
|
||
|
||
### 其他几何关系
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `isClose(Ps)` | 判断点列是否闭合 | boolean |
|
||
| `isClockwise(Rgn)` | 判断多边形是否为顺时针 | boolean |
|
||
| `isCross(P0, P1, Ps, nAvoidPoint)` | 判断线段与点列是否相交 | boolean |
|
||
| `isSamePointList(Ps1, Ps2, dbLimit, bCompareName, bCompateType, bCompareZ)` | 判断两点集是否相同 | boolean |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2862-L2892)
|
||
|
||
## 弧线与圆操作
|
||
|
||
### 弧长计算
|
||
|
||
| 函数名 | 功能描述 | 参数说明 |
|
||
|--------|----------|----------|
|
||
| `arc3pLength(spCenter, dbRadius, PsArc)` | 计算三点圆弧长度 | spCenter: 圆心；dbRadius: 半径；PsArc: 弧上三点 |
|
||
| `getArcLength(spCenter, dbRadius, bClockwise, sp1, sp2)` | 计算弧长 | sp1, sp2: 弧的起点和终点；bClockwise: 是否顺时针 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L5233-L5240)
|
||
|
||
### 弧线属性判断
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `isArcClockwise(PsArc, pCenter, pRadius)` | 判断弧线是否为顺时针 | boolean |
|
||
| `isPointOnArc(sp, PsArc, miniDist, pCenter, pRadius, nArc1, nArc2, bAdjustCoord)` | 判断点是否在弧上 | boolean |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L5242-L5250)
|
||
|
||
### 弧线中点
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `getArcMidPoint(spCenter, dbRadius, bClockwise, sp1, sp2)` | 获取弧线中点 | Point3D |
|
||
| `getSupplementaryArc(PsArcIn, PsArcOut)` | 获取补弧 | boolean |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L5256-L5260)
|
||
|
||
### 弧线打断与插入
|
||
|
||
| 函数名 | 功能描述 | 参数说明 |
|
||
|--------|----------|----------|
|
||
| `arcBreakByPoint(PsArc, PsBreak, newArcList)` | 用点集打断弧线 | newArcList: 输出的弧线列表 |
|
||
| `circleBreakByPoint(PsCir, PsCross, newArcList)` | 用点集打断圆 | newArcList: 输出的弧线列表 |
|
||
| `insertPointToArc(sp, ArcPoints, miniDist)` | 在弧线上插入点 | miniDist: 最小距离限差 |
|
||
| `insertPointToPLineArc(sp, nLineType, PsLine, miniDist)` - 在折线弧上插入点 |
|
||
| `adjustPointToPLineArc(sp, nLineType, PsLine, pRefPoint)` - 调整点到折线弧上 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L5252-L5258)
|
||
|
||
### 极坐标弧生成
|
||
|
||
| 函数名 | 功能描述 | 参数说明 |
|
||
|--------|----------|----------|
|
||
| `xysa_Arc(spCenter, dbRadius, bClockwise, sp1, sp2, dbArcLen, nFlag, pAngle)` | 极坐标法生成弧点 | dbArcLen: 弧长；nFlag: 标志；pAngle: 输出角度 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L5231-L5232)
|
||
|
||
## 点与线操作
|
||
|
||
### 点插入与延伸
|
||
|
||
| 函数名 | 功能描述 | 参数说明 |
|
||
|--------|----------|----------|
|
||
| `innerInsertPoint(sp1, sp2, dbDist, Ps)` | 在两点之间插入点 | dbDist: 距离；Ps: 输出点集 |
|
||
| `getInsertPoint(Ps, dbInterv)` | 按间隔插入点 | dbInterv: 间隔距离 |
|
||
| `getIntervPoint(Ps, dbInterv, pIndexs)` - 获取间隔点（附带索引） |
|
||
| `getlinesIntervP(pList, ResList, dInterv, dZongChang)` - 按总长和间隔获取点 |
|
||
| `innerInsertCor(Begin, End, nCount, PointList)` - 在两点间插入 nCount 个点 |
|
||
| `extend3DList_Done(Points, dbDist, bTail)` - 延伸点集 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L5325-L5335)
|
||
|
||
### 点修剪与去重
|
||
|
||
| 函数名 | 功能描述 | 参数说明 |
|
||
|--------|----------|----------|
|
||
| `removeSameCoordPoint(*args)` - 移除相同坐标点 |
|
||
| `removeRepeatPoint(Ps, dbLimit)` - 移除重复点 | dbLimit: 限差 |
|
||
| `getRepeatPoint(Ps, nRepeats, dbLimit)` - 获取重复点 | nRepeats: 重复次数 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L5315-L5320)
|
||
|
||
### 线段打断
|
||
|
||
| 函数名 | 功能描述 | 参数说明 |
|
||
|--------|----------|----------|
|
||
| `lineBreakByPoint(Lines, nAttrs, CrossList, newLines, bIsPLine)` - 用点集打断线段 |
|
||
| `plineSplit(PsPLine, nLineType, LineList, nAttrs, bClearPointType)` - 拆分多段线 |
|
||
| `plineMerge(*args)` - 合并多段线 |
|
||
| `arcSplit(PsArc, LineList, nAttrs)` - 打断弧线 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L5267-L5275)
|
||
|
||
### 中点与垂足
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `midPoint(*args)` - 获取中点 | Point3D |
|
||
| `calPoint(*args)` - 计算点位置 | Point3D |
|
||
| `getLineMidPoint(sp, Ps, pInsertAt)` - 获取线段中点 | Point3D |
|
||
| `perpend(p, p1, p2)` - 计算垂足 | Point3D |
|
||
| `perpendLize(p0, p1, p2)` - 垂直化操作 | Point3D |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2841-L2849)
|
||
|
||
### 高程插值
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `altitudeInterpolation(sp, sp1, sp2)` - 高程插值 | float |
|
||
| `interpolationPoint(sp1, sp2, dbZ, sp)` - 按高程插值点 | Point3D |
|
||
| `insertZValue(sp, sp0, sp1)` - 插入 Z 值 | Point3D |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2850-L2854)
|
||
|
||
## 高级几何操作
|
||
|
||
### 平行线生成
|
||
|
||
| 函数名 | 功能描述 | 参数说明 |
|
||
|--------|----------|----------|
|
||
| `parallel(PListFrom, PListTo, dWidth, nDir, nLineType, nSharpAngleTrimType, truncations)` - 生成平行线 | dWidth: 宽度；nDir: 方向；nSharpAngleTrimType: 尖角处理方式（0=不处理，1=平头，2=圆头）；truncations: 是否截断 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2920-L2935)
|
||
|
||
### 曲线生成
|
||
|
||
| 函数名 | 功能描述 | 参数说明 |
|
||
|--------|----------|----------|
|
||
| `arcToPoints(pListFrom, pl, gscale)` - 弧线转点集 | gscale: 缩放比例 |
|
||
| `circleToPoints(pListFrom, pl, gscale)` - 圆转点集 | gscale: 缩放比例 |
|
||
| `freeCurve(pList, pListRes, gscale)` - 自由曲线生成 | gscale: 缩放比例 |
|
||
| `dzlyt(pList, pListRes, gscale)` - 等值线生成 | gscale: 缩放比例 |
|
||
| `zlyt(Points, sgm, scale)` - 张力样条曲线 | sgm: 张力系数 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2942-L2950)
|
||
|
||
### 椭圆操作
|
||
|
||
| 函数名 | 功能描述 | 参数说明 |
|
||
|--------|----------|----------|
|
||
| `createEllipse(*args)` - 创建椭圆点集 |
|
||
| `createEllipseArc(*args)` - 创建椭圆弧点集 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2951-L2952)
|
||
|
||
### 线型重建
|
||
|
||
| 函数名 | 功能描述 | 参数说明 |
|
||
|--------|----------|----------|
|
||
| `gotoBeeline(srcPoints, nLineType, ArcInfoList, pResPoints)` - 转为直线 | ArcInfoList: 弧信息列表 |
|
||
| `polylineRebuild(srcPoints, nLineType, ArcInfoList, pResPoints)` - 重建多段线 |
|
||
| `gotoPoints(pList, lin_sty, pListRes, gscale, bMarkType, bForCalArea)` - 线型转换点集生成 | lin_sty: 线型；bForCalArea: 是否用于计算面积 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L3023-L3030)
|
||
|
||
### 矩形与边界操作
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `getLineRect(sp1, sp2, rect)` - 获取线段包围盒 | boolean |
|
||
| `getPolyRectFromPointList(points)` - 获取点集的多边形包围盒 | POINT3DLIST |
|
||
| `getPolyRectFromStructList(points)` - 获取结构点集的多边形包围盒 | POINT3DLIST |
|
||
| `getMinimumRectangle(Polygon, PsRect)` - 获取最小外接矩形 | boolean |
|
||
| `isLineOutOfRect(rect, sp1, sp2)` - 判断线段是否在矩形外 | boolean |
|
||
| `isRectCrossLine(rect, sp1, sp2)` - 判断矩形与线段是否相交 | boolean |
|
||
| `isRectCrossPolygon(rect, rgnPoints)` - 判断矩形与多边形是否相交 | boolean |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L5285-L5295)
|
||
|
||
### 点集排序
|
||
|
||
| 函数名 | 功能描述 | 参数说明 |
|
||
|--------|----------|----------|
|
||
| `sortByValue(Ps, arKeys, bAscending)` - 按键值排序点集 | arKeys: 键值数组；bAscending: 是否升序 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L5290-L5291)
|
||
|
||
## 辅助计算工具
|
||
|
||
### 数值精度处理
|
||
|
||
| 函数名 | 功能描述 | 参数说明 |
|
||
|--------|----------|----------|
|
||
| `fRounding(dbData, nDecimal)` - 数值四舍五入 | nDecimal: 小数位数 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L5275-L5276)
|
||
|
||
### 法向量计算
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `calculateNormal(*args)` - 计算法向量 | Vec3d |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2798-L2799)
|
||
|
||
### 线段交点
|
||
|
||
| 函数名 | 功能描述 | 参数说明 |
|
||
|--------|----------|----------|
|
||
| `getLineIntersect(p1, p2, pList, resP)` - 获取线段与点列表的交点 | resP: 输出交点 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2936-L2937)
|
||
|
||
### 三角形计算
|
||
|
||
| 函数名 | 功能描述 | 返回值 |
|
||
|--------|----------|--------|
|
||
| `calTriHeight(a, b, c)` - 计算三角形边 a 对应的高 | float |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2677-L2678)
|
||
|
||
### 多边形焦点
|
||
|
||
| 函数名 | 功能描述 | 参数说明 |
|
||
|--------|----------|----------|
|
||
| `getPolygonFocus(_Point, rlPolygon, pClipRgn, bWidthPreference)` - 获取多边形内焦点 | _Point: 输出焦点；rlPolygon: 多边形点列；pClipRgn: 裁剪区域；bWidthPreference: 宽度优先标志 | float: 返回值 |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2906-L2918)
|
||
|
||
## 常用常量
|
||
|
||
模块定义了多个数学常量和枚举常量：
|
||
|
||
**数学常量**：
|
||
- `PI` - 圆周率 π
|
||
- `PI_2` - π/2
|
||
- `PI_4` - π/4
|
||
- `ZERO_FLOAT` - 零浮点数阈值
|
||
- `MIN_FLOAT` / `MAX_FLOAT` - 最小/最大浮点数
|
||
- `MINI_COORDINATE` - 最小坐标限差
|
||
- `MINI_FLOAT` / `MINI_DOUBLE` - 最小浮点数/双精度限差
|
||
|
||
**方向常量**：
|
||
- `_LEFT` / `_RIGHT` / `_TOP` / `_BOTTOM` - 方向标识
|
||
- `e_East` / `e_North` / `e_West` / `e_South` - 东西北南
|
||
- `_CLOCKWISE` / `_ANTICLOCK` - 顺时针/逆时针
|
||
|
||
**点在多边形关系**：
|
||
- `_IN_POLY` - 点在多边形内
|
||
- `_OUT_POLY` - 点在多边形外
|
||
- `_CLIP_POLY` - 点在裁剪多边形边界
|
||
|
||
**线型标识**：
|
||
- `e_LS_Null` / `e_LS_Polyline` / `e_LS_PWline` / `e_LS_PolyArea`
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L680-L720)
|
||
|
||
## 应用示例
|
||
|
||
### 基础距离与面积计算
|
||
|
||
```python
|
||
import PySSMath
|
||
|
||
# 创建三维点
|
||
p1 = PySSMath.Point3D(100, 200, 0)
|
||
p2 = PySSMath.Point3D(150, 250, 50)
|
||
|
||
# 计算距离
|
||
dist_2d = PySSMath.distance(p1, p2)
|
||
dist_3d = PySSMath.distance3d(p1, p2)
|
||
|
||
# 创建多边形点集
|
||
polygon = PySSMath.POINT3DLIST()
|
||
polygon.push_back(PySSMath.Point3D(0, 0, 0))
|
||
polygon.push_back(PySSMath.Point3D(100, 0, 0))
|
||
polygon.push_back(PySSMath.Point3D(100, 100, 0))
|
||
polygon.push_back(PySSMath.Point3D(0, 100, 0))
|
||
|
||
# 计算面积
|
||
area = PySSMath.getPolyArea(polygon)
|
||
```
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2680-L2698)
|
||
|
||
### 坐标转换与角度计算
|
||
|
||
```python
|
||
import PySSMath
|
||
|
||
# 角度格式转换
|
||
deg = 45.5
|
||
rad = PySSMath.degToRadian(deg)
|
||
dms = PySSMath.degToDms(deg)
|
||
|
||
# 计算方位角
|
||
azimuth = PySSMath.bearing(100, 200, 0, 0)
|
||
|
||
# 计算夹角
|
||
p_center = PySSMath.Point3D(100, 100, 0)
|
||
p1 = PySSMath.Point3D(150, 100, 0)
|
||
p2 = PySSMath.Point3D(100, 150, 0)
|
||
angle_rad = PySSMath.openAngle(p1, p_center, p2)
|
||
angle_deg = PySSMath.openAngleDeg(p1, p_center, p2)
|
||
```
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2772-L2794)
|
||
|
||
### 几何变换操作
|
||
|
||
```python
|
||
import PySSMath
|
||
|
||
# 创建点集
|
||
points = PySSMath.POINT3DLIST()
|
||
for i in range(5):
|
||
points.push_back(PySSMath.Point3D(i * 10, i * 20, 0))
|
||
|
||
# 旋转 30 度
|
||
base_point = PySSMath.Point3D(0, 0, 0)
|
||
angle = PySSMath.degToRadian(30)
|
||
rotated = PySSMath.rotate2DList(points, angle, base_point)
|
||
|
||
# 平移
|
||
offset_x, offset_y = 50, 50
|
||
offset_points = PySSMath.offset2DList(points, offset_x, offset_y)
|
||
|
||
# 镜像
|
||
mirror_p0 = PySSMath.Point3D(0, 0, 0)
|
||
mirror_p1 = PySSMath.Point3D(100, 100, 0)
|
||
mirrored = PySSMath.mirror3DList(mirror_p0, mirror_p1, points)
|
||
```
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2819-L2838)
|
||
|
||
### 空间关系判断
|
||
|
||
```python
|
||
import PySSMath
|
||
|
||
# 判断点是否在多边形内
|
||
test_point = PySSMath.Point3D(50, 50, 0)
|
||
is_inside = PySSMath.ptInPoly(test_point.x(), test_point.y(), polygon, 0.001)
|
||
|
||
# 判断线段是否相交
|
||
line1_p1 = PySSMath.Point3D(0, 0, 0)
|
||
line1_p2 = PySSMath.Point3D(100, 100, 0)
|
||
line2_p1 = PySSMath.Point3D(0, 100, 0)
|
||
line2_p2 = PySSMath.Point3D(100, 0, 0)
|
||
is_cross = PySSMath.isLineCrossLine(line1_p1, line1_p2, line2_p1, line2_p2)
|
||
|
||
# 获取交点
|
||
cross_point = PySSMath.Point3D()
|
||
has_cross = PySSMath.getCrossPoint(line1_p1, line1_p2, line2_p1, line2_p2, cross_point)
|
||
```
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2893-L2918)
|
||
|
||
### 点线操作
|
||
|
||
```python
|
||
import PySSMath
|
||
|
||
# 在两点之间插入点
|
||
p_start = PySSMath.Point3D(0, 0, 0)
|
||
p_end = PySSMath.Point3D(100, 100, 0)
|
||
inserted_points = PySSMath.POINT3DLIST()
|
||
distance = 25 # 每 25 个单位插入一个点
|
||
PySSMath.innerInsertPoint(p_start, p_end, distance, inserted_points)
|
||
|
||
# 延伸线段
|
||
points_to_extend = PySSMath.POINT3DLIST()
|
||
# ... 添加点 ...
|
||
extended_points = PySSMath.extend3DList(points_to_extend, 10, True) # 尾部延伸 10 个单位
|
||
|
||
# 计算中点
|
||
midpoint = PySSMath.midPoint(p_start, p_end)
|
||
|
||
# 计算垂足
|
||
test_point = PySSMath.Point3D(50, 20, 0)
|
||
foot_point = PySSMath.perpend(test_point, p_start, p_end)
|
||
```
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2841-L2850)
|
||
|
||
## API 快速索引表
|
||
|
||
### 按功能分类
|
||
|
||
| 功能分类 | 关键函数 |
|
||
|----------|----------|
|
||
| **坐标转换** | degToRadian, radianToDeg, dmsToDeg, degToDms, rightToPolar, polarToRight |
|
||
| **距离计算** | distance, distance3d, getDistSquare, getDistPtToLine, getNearstDistSquare |
|
||
| **面积计算** | getPolyArea, get3DArea, get3DAreaInDirection, calTriHeight |
|
||
| **角度计算** | bearing, openAngle, openAngleDeg, jiaoPingfenFangWei, getDirection |
|
||
| **几何变换** | rotate2DList, rotate3DList, offset2DList, offset3DList, zoom3DList, mirror3DList, smooth3DList |
|
||
| **点操作** | midPoint, calPoint, extend3DList, innerInsertPoint, removeRepeatPoint |
|
||
| **线操作** | getLinesSumlen, getLinesSumlen3d, parallel, lineBreakByPoint, plineSplit |
|
||
| **弧操作** | arc3pLength, getArcLength, getArcMidPoint, isArcClockwise, arcBreakByPoint |
|
||
| **关系判断** | isSamePoint, isPointOnLine, ptInPoly, isLineCrossLine, isPolygonInPolygonComplex |
|
||
| **辅助工具** | fRounding, calculateNormal, getMinimumRectangle, sortByValue |
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2670-L5400)
|
||
|
||
## 性能优化建议
|
||
|
||
1. **批量操作优先**：对于大量点集的操作，优先使用 `POINT3DLIST` 容器和批量处理函数（如 `rotate3DList`），避免逐点循环。
|
||
|
||
2. **合理使用限差参数**：在关系判断函数中（如 `isSamePoint`, `ptInPoly`），根据数据精度合理设置 `epsilon` 或 `limit` 参数，避免浮点数精度问题。
|
||
|
||
3. **避免重复计算**：对于需要多次使用的结果（如距离、面积），缓存中间结果而非重复计算。
|
||
|
||
4. **使用距离平方**：在仅需比较距离大小的场景下，使用 `getDistSquare` 而非 `distance`，避免开方运算开销。
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2680-L2720)
|
||
|
||
## 进阶主题
|
||
|
||
### 复杂多边形处理
|
||
|
||
对于带岛（洞）的复杂多边形，使用 `isPolygonInPolygonComplex` 函数判断多边形间关系。该函数支持嵌套多边形结构，返回详细的关系标识（包含、相交、独立等）。
|
||
|
||
### 弧线重建与识别
|
||
|
||
使用 `gotoBeeline` 和 `polylineRebuild` 函数可以将拟合的弧线转换为直线段，或将直线段识别为弧线结构，配合 `ArcInfoList` 输出弧线参数信息。
|
||
|
||
### 高级几何变换
|
||
|
||
`mapping3DList` 函数支持基于控制点的仿射变换，可实现不规则的空间映射，适用于校正变形数据。
|
||
|
||
Sources: [PySSMath.py](PySSMath.py#L2893-L2950)
|
||
|
||
## 相关文档
|
||
|
||
- [坐标转换工具](44-zuo-biao-zhuan-huan-gong-ju) - 专门的坐标系统转换模块
|
||
- [地理对象类型定义](42-di-li-dui-xiang-lei-xing-ding-yi) - 地理对象类型与属性
|
||
- [工作空间与地图概念](8-gong-zuo-kong-jian-yu-di-tu-gai-nian) - 空间参考与投影系统 |