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) - 空间参考与投影系统