sunvpy-docs/docs/content/41-objbaseattr-shu-xing-suo-yin.md

ObjBaseAttr 类是 SunvStation 系统中地物对象属性管理的核心组件，提供统一的属性名称注册、索引映射和属性值读写接口。该类通过集中管理所有地物属性的名称与索引映射关系，实现了属性访问的标准化和高效化，支持点、线、面、注记等多种地物类型的属性操作。

Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L6-L110)

## 属性分类体系

ObjBaseAttr 将地物属性划分为五大类别，每类属性对应不同的功能维度和数据类型。这种分类设计既体现了属性的业务语义，也便于开发者快速定位所需属性。

### 属性分类概览

```mermaid
graph TB
    A[ObjBaseAttr 属性体系] --> B[点属性]
    A --> C[地物通用属性]
    A --> D[几何参量属性]
    A --> E[注记属性]
    A --> F[操作属性]
    
    B --> B1[SSObj_PointName<br/>坐标点名称]
    B --> B2[SSObj_PointCount<br/>坐标点数量]
    B --> B3[SSObj_PointType<br/>坐标点类型]
    B --> B4[SSObj_X/Y/Z<br/>坐标值]
    
    C --> C1[标识属性<br/>ID, Code, Name]
    C --> C2[图形属性<br/>Color, LineType, LineWidth]
    C --> C3[变换属性<br/>Angle, ScaleX, ScaleY]
    C --> C4[时间属性<br/>CreateTime, ModifyTime]
    
    D --> D1[面积属性<br/>Area, EllipsoidArea]
    D --> D2[长度属性<br/>Length, 3DLength]
    D --> D3[边界属性<br/>minX, minY, maxX, maxY]
    
    E --> E1[字体属性<br/>FontWidth, FontHeight, FontName]
    E --> E2[文本属性<br/>FontString, FontStringCount]
    E --> E3[样式属性<br/>Alignment, FontWeight, ItalicAngle]
    
    F --> F1[SSObj_Reverse<br/>方向反转]
    F --> F2[SSObj_Reference<br/>引用关系]
```

### 点属性索引

点属性用于描述地物对象的坐标点信息，是构成线、面等复杂几何形状的基础元素。此类属性支持通过参数索引访问特定位置的坐标点。

Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L38-L44)

| 属性常量 | 属性名 | 数据类型 | 说明 | 参数支持 |
|---------|--------|---------|------|---------|
| `pointName` | SSObj_PointName | string | 坐标点名称 | (n) - 第n个点 |
| `pointCount` | SSObj_PointCount | int | 坐标点数量 | 无 |
| `pointType` | SSObj_PointType | int | 坐标点类型 | (n) - 第n个点 |
| `x` | SSObj_X | double | X坐标值 | (n) - 第n个点 |
| `y` | SSObj_Y | double | Y坐标值 | (n) - 第n个点 |
| `z` | SSObj_Z | double | Z坐标值 | (n) - 第n个点 |

**参数说明**：括号内的数字表示坐标点索引（从0开始）。例如 `SSObj_X(0)` 获取第一个点的X坐标。

### 地物通用属性索引

通用属性适用于所有地物类型，涵盖了对象标识、图形表现、变换参数和元数据等核心信息。

Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L46-L70)

| 属性常量 | 属性名 | 数据类型 | 说明 | 可读写 |
|---------|--------|---------|------|-------|
| **标识属性** |||||
| `id` | SSObj_ID | int | 对象唯一标识 | 只读 |
| `groupID` | SSObj_GroupID | int | 分组标识 | 可写 |
| `code` | SSObj_Code | int | 地物编码 | 只读 |
| `byname` | SSObj_Byname | string | 地物别名 | 可写 |
| `name` | SSObj_Name | string | 地物名称 | 可写 |
| `type` | SSObj_Type | string | 对象类型（POINT/LINE/AREA/NOTE） | 只读 |
| **图形属性** |||||
| `color` | SSObj_Color | int | 颜色值（支持RGB/COLORNO格式） | 可写 |
| `lineType` | SSObj_LineType | int | 线型 | 可写 |
| `lineWidth` | SSObj_LineWidth | int | 线宽 | 可写 |
| `layerName` | SSObj_LayerName | string | 图层名称 | 只读 |
| **变换属性** |||||
| `angle` | SSObj_Angle | double | 旋转角度（度） | 可写 |
| `scaleX` | SSObj_ScaleX | double | X方向缩放比例 | 可写 |
| `scaleY` | SSObj_ScaleY | double | Y方向缩放比例 | 可写 |
| `scaleXY` | SSObj_ScaleXY | double | 统一缩放比例 | 可写 |
| **元数据属性** |||||
| `status` | SSObj_Status | int | 对象状态 | 可写 |
| `dataMark` | SSObj_DataMark | string | 数据标记 | 可写 |
| `relationID` | SSObj_RelationID | string | 关联标识 | 可写 |
| `createTime` | SSObj_CreateTime | string | 创建时间（YYYY-MM-DD HH:MM:SS） | 可写 |
| `modifyTime` | SSObj_ModifyTime | string | 修改时间（YYYY-MM-DD HH:MM:SS） | 可写 |
| **扩展属性** |||||
| `hatchStyle` | SSObj_HatchStyle | int | 填充样式 | 可写 |
| `hatchDensityScale` | SSObj_HatchDensityScale | double | 填充密度比例 | 可写 |
| `lShapeOffset` | SSObj_LShapeOffset | int | L型偏移 | 可写 |
| `memoData` | SSObj_MemoData | string | 备注数据 | 可写 |

### 几何参量属性索引

几何参量属性提供对地物对象空间特征的定量描述，包括面积、长度、边界范围等计算结果。

Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L72-L85)

| 属性常量 | 属性名 | 数据类型 | 说明 | 精度 |
|---------|--------|---------|------|------|
| **面积属性** |||||
| `area` | SSObj_Area | double | 对象面积 | 6位小数 |
| `ellipsoidArea1` | SSObj_EllipsoidArea1 | double | 椭球面积1 | - |
| `ellipsoidArea2` | SSObj_EllipsoidArea2 | double | 椭球面积2 | - |
| **长度属性** |||||
| `length` | SSObj_Length | double | 对象周长/长度 | 6位小数 |
| `length3D` | SSObj_3DLength | double | 三维长度 | 6位小数 |
| **边界属性** |||||
| `minX` | SSObj_minX | double | 最小X坐标 | 6位小数 |
| `minY` | SSObj_minY | double | 最小Y坐标 | 6位小数 |
| `maxX` | SSObj_maxX | double | 最大X坐标 | 6位小数 |
| `maxY` | SSObj_maxY | double | 最大Y坐标 | 6位小数 |
| **标签属性** |||||
| `drawAreaLabelStatus` | SSObj_DrawAreaLabelStatus | string | 区域标签状态 | - |
| `areaLabelX` | SSObj_AreaLabelX | double | 标签X坐标 | - |
| `areaLabelY` | SSObj_AreaLabelY | double | 标签Y坐标 | - |

### 注记属性索引

注记属性专用于注记对象（e_Note_Obj），控制字体、文本内容、对齐方式、角度等显示效果。

Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L87-L105)

| 属性常量 | 属性名 | 数据类型 | 说明 | 可读写 |
|---------|--------|---------|------|-------|
| **字体属性** |||||
| `fontName` | SSObj_FontName | string | 字体名称 | 可写 |
| `fontWidth` | SSObj_FontWidth | double | 字体宽度 | 可写 |
| `fontHeight` | SSObj_FontHeight | double | 字体高度 | 可写 |
| `fontClass` | SSObj_FontClass | string | 注记分类 | 可写 |
| **文本属性** |||||
| `fontString` | SSObj_FontString | string | 注记文本内容 | 可写 |
| `fontStringCount` | SSObj_FontStringCount | int | 字符串长度 | 只读 |
| `fontRealHeight` | SSObj_FontRealHeight | double | 实际显示高度 | 只读 |
| `fontRealLength` | SSObj_FontRealLength | double | 实际显示长度 | 只读 |
| **对齐与定位** |||||
| `fontAlignment` | SSObj_FontAlignment | int | 对齐方式 | 可写 |
| `fontPosType` | SSObj_FontPosType | int | 定位类型 | 可写 |
| `fontDirection` | SSObj_FontDirection | int | 文字方向 | 可写 |
| **角度属性** |||||
| `fontWordAngle` | SSObj_FontWordAngle | double | 单词旋转角度 | 可写 |
| `fontStringAngle` | SSObj_FontStringAngle | double | 字符串旋转角度 | 可写 |
| `fontItalicAngle` | SSObj_FontItalicAngle | double | 斜体角度 | 可写 |
| `fontDownAngle` | SSObj_FontDownAngle | double | 下划线角度 | 可写 |
| **样式属性** |||||
| `fontWeight` | SSObj_FontWeight | int | 字体粗细 | 可写 |
| `fontUnderLine` | SSObj_FontUnderLine | int | 下划线标志 | 可写 |
| `fontInterval` | SSObj_FontInterval | double | 字符间距 | 可写 |

### 操作属性索引

操作属性用于触发特定的地物处理操作，而非存储常规属性值。

Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L107-L109)

| 属性常量 | 属性名 | 操作类型 | 说明 |
|---------|--------|---------|------|
| `reverse` | SSObj_Reverse | 方向反转 | 值为1时执行反转操作 |
| `reference` | SSObj_Reference | 引用关系 | 当前未实现 |

## 核心方法参考

### 属性索引管理

ObjBaseAttr 提供三个核心方法用于属性名称与索引的双向映射：

Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L111-L178)

| 方法名 | 功能 | 参数 | 返回值 |
|--------|------|------|-------|
| `registerObjBaseAttrName(name)` | 注册新属性名到索引表 | name: 属性名（自动去除SSObj_前缀） | 属性索引 |
| `get_value_index(field)` | 获取属性名的索引 | field: 属性名（支持SSObj_前缀） | 索引值，未找到返回-1 |
| `get_value_index_param(field)` | 解析带参数的属性名 | field: 格式为'属性名(参数)' | (索引, 参数字符串) |

**命名规范**：属性名在内部存储时自动转换为小写并去除 `SSObj_` 前缀，外部访问时两种形式均可识别。

### 属性值读写

#### getGeoValue 方法

获取单个地物对象的属性值，支持动态参数解析和多类型对象处理。

Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L188-L360)

```python
def getGeoValue(map: ScaleMap, geo: GeoBase, field: str) -> str
```

**处理流程**：

```mermaid
flowchart TD
    A[调用 getGeoValue] --> B[解析属性名和参数]
    B --> C{属性索引是否存在?}
    C -->|否| D[返回空字符串]
    C -->|是| E{对象类型?}
    E -->|注记对象| F[处理注记专用属性]
    E -->|通用对象| G[处理公共基本属性]
    F --> H{有值返回?}
    G --> H
    H -->|是| I[返回属性值]
    H -->|否| J[处理坐标点属性]
    J --> K{有值返回?}
    K -->|是| I
    K -->|否| L[处理几何量属性]
    L --> I
```

**参数支持示例**：
- `SSObj_X(0)` → 获取第一个点的X坐标
- `SSObj_PointName(2)` → 获取第三个点的名称
- `SSObj_Area` → 获取对象面积

#### setGeoValue 方法

批量设置多个地物对象的属性值，支持扩展属性和基本属性的统一处理接口。

Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L362-L624)

```python
def setGeoValue(map: ScaleMap, geoList: GeoBaseList, field: str, value: str)
```

**扩展属性处理**：当属性名以 `[` 开头时，系统将其识别为扩展属性，存储在 MemoData 中。

Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L364-L394)

**颜色值格式支持**：
- 颜色号格式：`COLORNO(1)`
- RGB格式：`RGB(255,123,224)`
- 数值格式：`16777215`（24位颜色值）

Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L408-L411)

## 属性索引值映射表

为便于直接使用，下表列出了所有属性的实际索引值（基于初始化顺序）：

Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L13-L36)

| 索引 | 属性名（无前缀） | 属性常量 |
|-----|----------------|---------|
| 0 | angle | `self.angle` |
| 1 | area | `self.area` |
| 2 | arealabelx | `self.areaLabelX` |
| 3 | arealabely | `self.areaLabelY` |
| 4 | byname | `self.byname` |
| 5 | code | `self.code` |
| 6 | color | `self.color` |
| 7 | createdata | `self.createTime` |
| 8 | datamark | `self.dataMark` |
| 9 | drawarealabelstatus | `self.drawAreaLabelStatus` |
| 10 | ellipsoidarea1 | `self.ellipsoidArea1` |
| 11 | ellipsoidarea2 | `self.ellipsoidArea2` |
| 12 | fontalignment | `self.fontAlignment` |
| 13 | fontclass | `self.fontClass` |
| 14 | fontdownangle | `self.fontDownAngle` |
| 15 | fontheight | `self.fontHeight` |
| 16 | fontitalicangle | `self.fontItalicAngle` |
| 17 | fontinterval | `self.fontInterval` |
| 18 | fontname | `self.fontName` |
| 19 | fontpos | `self.fontPosType` |
| 20 | fontrealheight | `self.fontRealHeight` |
| 21 | fontreallength | `self.fontRealLength` |
| 22 | fontstring | `self.fontString` |
| 23 | fontstringangle | `self.fontStringAngle` |
| 24 | fontstringcount | `self.fontStringCount` |
| 25 | fontunderline | `self.fontUnderLine` |
| 26 | fontwidth | `self.fontWidth` |
| 27 | fontwordangle | `self.fontWordAngle` |
| 28 | groupid | `self.groupID` |
| 29 | hatchdensityscale | `self.hatchDensityScale` |
| 30 | hatchstyle | `self.hatchStyle` |
| 31 | id | `self.id` |
| 32 | lshapeoffset | `self.lShapeOffset` |
| 33 | length | `self.length` |
| 34 | length3d | `self.length3D` |
| 35 | layername | `self.layerName` |
| 36 | linetype | `self.lineType` |
| 37 | linewidth | `self.lineWidth` |
| 38 | max | `self.maxX` |
| 39 | maxy | `self.maxY` |
| 40 | memodata | `self.memoData` |
| 41 | minx | `self.minX` |
| 42 | miny | `self.minY` |
| 43 | modifydata | `self.modifyTime` |
| 44 | name | `self.name` |
| 45 | pointcount | `self.pointCount` |
| 46 | pointname | `self.pointName` |
| 47 | pointtype | `self.pointType` |
| 48 | reference | `self.reference` |
| 49 | relationid | `self.relationID` |
| 50 | reverse | `self.reverse` |
| 51 | scale | `self.scaleX` |
| 52 | scalex | `self.scaleX` |
| 53 | scaley | `self.scaleY` |
| 54 | scalexy | `self.scaleXY` |
| 55 | status | `self.status` |
| 56 | type | `self.type` |
| 57 | x | `self.x` |
| 58 | y | `self.y` |
| 59 | z | `self.z` |

**注意**：索引值按属性名字母顺序排序，通过 `valueNames.sort()` 维护。使用属性常量（如 `attr.area`）比直接使用索引值更具可读性和维护性。

## 使用场景与最佳实践

### 基础属性访问

```python
# 获取对象面积
area_value = attr.getGeoValue(map, geo, "SSObj_Area")

# 修改对象颜色（支持多种格式）
attr.setGeoValue(map, geoList, "SSObj_Color", "RGB(255,0,0)")
attr.setGeoValue(map, geoList, "SSObj_Color", "16711680")  # 红色
```

Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L332-L335)

### 坐标点操作

```python
# 获取第一个点的X坐标
x0 = attr.getGeoValue(map, geo, "SSObj_X(0)")

# 设置第三个点的Z值为100.0
attr.setGeoValue(map, geoList, "SSObj_Z(2)", "100.0")
```

Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L307-L318)

### 扩展属性管理

```python
# 设置单个扩展属性
attr.setGeoValue(map, geoList, "[自定义属性]", "属性值")

# 批量设置多个扩展属性
attr.setGeoValue(map, geoList, "[属性1,属性2,属性3]", "值1,值2,值3")
```

Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L364-L394)

### 注记对象样式控制

```python
# 设置注记字体和大小
attr.setGeoValue(map, geoList, "SSObj_FontName", "宋体")
attr.setGeoValue(map, geoList, "SSObj_FontHeight", "12.5")

# 设置注记旋转角度
attr.setGeoValue(map, geoList, "SSObj_FontStringAngle", "30.0")
```

Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L535-L594)

## 与其他模块的交互

ObjBaseAttr 作为属性管理中枢，与多个核心模块协同工作：

```mermaid
graph LR
    A[ObjBaseAttr] --> B[PySSCore<br/>GeoBase/GeoBaseList]
    A --> C[PySSMath<br/>几何计算函数]
    A --> D[PySSMap<br/>ScaleMap]
    
    B --> E[提供地物对象]
    C --> F[3D长度计算]
    D --> G[地图比例尺]
    
    A --> H[SSProcessManager]
    H --> I[选择集管理]
    I --> A[属性读写]
```

Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L1-L4)

**关键依赖**：
- `GeoBase`：地物对象基类，提供属性访问方法
- `GeoBaseList`：地物对象列表，支持批量操作
- `ScaleMap`：地图对象，提供比例尺等上下文信息
- `get3DLength`：来自 PySSMath 的三维长度计算函数
- `getColorValue`：颜色值解析函数

Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L336-L340)

## 参考文档延伸

要深入了解属性的具体使用场景，可参考以下文档：

- [获取地物属性值](15-huo-qu-di-wu-shu-xing-zhi)：详细说明属性读取的完整流程
- [修改地物属性值](16-xiu-gai-di-wu-shu-xing-zhi)：批量属性修改的操作指南
- [地物基本属性详解](17-di-wu-ji-ben-shu-xing-xiang-jie)：属性的业务含义详解
- [扩展属性与自定义属性](18-kuo-zhan-shu-xing-yu-zi-ding-yi-shu-xing)：MemoData 扩展机制说明
- [SSProcessManager 完整 API](40-ssprocessmanager-wan-zheng-api)：结合选择集使用属性的示例