Metadata-Version: 2.4
Name: transform-base
Version: 0.0.5
Summary: 欧拉角、旋转矩阵、四元数、角轴、UTM/ENU 及多格式矩阵计算基础库
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20
Requires-Dist: pyproj>=3.6
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# transform-base

欧拉角、旋转矩阵、四元数、角轴及外参变换基础库，支持多种旋转顺序（XYZ/XZY/YXZ/YZX/ZXY/ZYX），并提供多输入格式解析、矩阵乘法/求逆/比较/方程求解、UTM/ENU 坐标转换的通用 API。

## 安装

```bash
pip install transform-base
```

## 功能特性

- **角度归一化**：`normalize_angle` 将角度归一化到 [-180, 180]
- **欧拉角 ↔ 旋转矩阵**：支持 6 种旋转顺序（order），默认 ZYX
- **旋转矩阵 ↔ 四元数**：`[x, y, z, w]` 格式
- **旋转矩阵 ↔ 角轴**：Rodrigues 公式
- **外参类 ExtrinsicParam**：欧拉/旋转矩阵/四元数/角轴多种初始化，齐次矩阵、点变换、复合与逆
- **多格式输入解析**：支持旋转矩阵+平移、四元数+平移、欧拉角+平移、4x4 齐次矩阵、JSON/proto/flex 四元数格式
- **矩阵计算**：支持统一格式输出、矩阵比较、`A = C @ B` / `A = B @ D` 求解
- **地理坐标转换**：支持 UTM -> 经纬度、经纬高 -> ENU，以及 TUM UTM 轨迹文件转换为 ENU
- **参考 INS 位姿**：使用 PyProj + GRS80 逐记录计算 UTM，支持南北半球、`height + geoid_undulation` 与 `qz * qy * qx`

## 快速开始

```python
from transform_base import (
    normalize_angle,
    standard_euler_to_rotation_matrix,
    rotation_matrix_to_standard_euler,
    ExtrinsicParam,
    parse_transform_input,
    transform_from_input,
    transform_to_all_formats,
    compare_transforms,
    solve_transform_equations,
    convert_tum_utm_rows_to_enu_rows,
    geodetic_pose_to_utm_tum,
    utm_to_latlon,
)

# 欧拉角 -> 旋转矩阵 -> 欧拉角
euler = [10.0, 20.0, 30.0]  # roll, pitch, yaw (度)
R = standard_euler_to_rotation_matrix(*euler, order="ZYX")
euler_back = rotation_matrix_to_standard_euler(R, order="ZYX")

# 外参：欧拉角 + 平移
ext = ExtrinsicParam(euler=[0, 0, 90], translation=[1, 0, 0])
p_out = ext.transform_point([1, 0, 0])
ext_inv = ext.inverse()

# 多格式输入 -> 外参
raw = '''
"translation": {"x": 1, "y": 2, "z": 3},
"rotation": {"qx": 0.0, "qy": 0.0, "qz": 0.70710678, "qw": 0.70710678}
'''
parsed = parse_transform_input(raw, format_name="json_rotation_translation_qxyzw")
ext_from_input = transform_from_input(raw, format_name="json_rotation_translation_qxyzw")
all_formats = transform_to_all_formats(ext_from_input)

# 比较与方程求解
cmp_result = compare_transforms(ext, ext_inv.inverse())
solve_result = solve_transform_equations(ext, ext_from_input)

# UTM / ENU
lat, lon = utm_to_latlon(500000.0, 3450000.0, zone=50)
enu_rows = convert_tum_utm_rows_to_enu_rows([
    "1000.000 500000.000 3450000.000 10.000 0 0 0 1",
    "1001.000 500010.000 3450000.000 10.000 0 0 0 1",
])

pose = geodetic_pose_to_utm_tum(
    lat=22.5096,
    lon=114.0441,
    height=10.0,
    geoid_undulation=1.25,
    roll_deg=10.0,
    pitch_deg=20.0,
    yaw_deg=30.0,
)
```

## 版本记录

- 0.0.5：新增 `latlon_to_utm_grs80`、`euler_rz_ry_rx_to_quaternion`、`geodetic_pose_to_utm_tum`，统一参考 INS 程序的 GRS80 UTM、南北半球、姿态和高度计算。
- 0.0.4：新增 geodesy API：`utm_to_latlon`、`latlon_to_enu`、`convert_tum_utm_rows_to_enu_rows`、`convert_tum_utm_file_to_enu_file`。

## 依赖

- Python >= 3.10
- numpy >= 1.20
- pyproj >= 3.6
- PyYAML >= 6.0

## 支持的输入格式

- `rotation_matrix_translation`
- `quaternion_translation`
- `euler_degree_translation`
- `homogeneous_matrix_4x4`
- `json_rotation_translation`
- `json_rotation_translation_qxyzw`
- `translation_rotation_quaternion`
- `rotation_translation_flex`

## License

MIT
