feat: 算法升级、整车配准集成与性能分析文档

算法更新: delivery v1.2.1、平整度v1.5、测距v2.2、整车配准v1.3 适配器: vehicle-registration 新增、各算法 manifest 和 adapter 更新后端: taskCadFiles/source 字段迁移、derivedPointClouds 注册、取消任务联动前端: ElapsedTime 时长显示、两步算法流程、canRun 逻辑修复文档: 新增5份算法性能分析报告
2026-06-25 08:22:20 +00:00
parent cec0766e67
commit 29f1d45d66
266 changed files with 1311475 additions and 2846 deletions
--- a/alg/平整度、平面度、轮廓测量v1.5/packaging/.gitignore
+++ b/alg/平整度、平面度、轮廓测量v1.5/packaging/.gitignore
@@ -0,0 +1,5 @@
+build/
+dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/
--- a/alg/平整度、平面度、轮廓测量v1.5/packaging/MANIFEST.in
+++ b/alg/平整度、平面度、轮廓测量v1.5/packaging/MANIFEST.in
@@ -0,0 +1,6 @@
+include README.md
+recursive-include geometry_measure *.yaml
+global-exclude __pycache__/*
+global-exclude *.py[cod]
+prune datasets
+prune archive
--- a/alg/平整度、平面度、轮廓测量v1.5/packaging/README.md
+++ b/alg/平整度、平面度、轮廓测量v1.5/packaging/README.md
@@ -0,0 +1,139 @@
+# geometry-measure 打包说明
+
+这个目录只负责打包，不存放数据集；仅包含已接入统一 CLI 的必要归档工作流。
+
+## 本地开发安装
+
+在项目根目录执行：
+
+```bash
+python packaging/build_package.py
+pip install -e packaging/build
+geometry-measure --help
+```
+
+也可以进入 `packaging/` 后执行：
+
+```bash
+python build_package.py
+pip install -e build
+geometry-measure --help
+```
+
+## 构建 wheel
+
+需要先安装构建工具：
+
+```bash
+pip install build
+```
+
+然后执行：
+
+```bash
+python packaging/build_package.py
+python -m build packaging/build
+```
+
+构建产物会出现在：
+
+```text
+packaging/build/dist/
+```
+
+## 运行示例
+
+从项目根目录运行：
+
+```bash
+geometry-measure contour --pointcloud datasets/PointCloud/11.ply --cad datasets/CAD/11.step --no-visualize
+geometry-measure contour --cad datasets/CAD/11.step --pointcloud datasets/Noise_PointCloud/11_noisy.ply --save vis/11_contour.ply --excel-output --no-visualize
+geometry-measure registration --pointcloud datasets/Noise_PointCloud/11_noisy.ply --mesh datasets/Mesh/11.stl --no-visualize
+geometry-measure denoise --pointcloud datasets/PointCloud/11.ply --noise-std 4 --no-visualize
+```
+
+`contour` 是轮廓/平整度/平面度评估的统一入口，本质上是点云到 STEP CAD 或 Mesh 的距离计算。需要保存距离热力图时传 `--save`，需要保存 Excel 时传 `--excel-output`。如需单独指定网格，可显式传入 `--mesh datasets/Mesh/11.stl`。
+`contour --excel-output` 不带值时会保存 `excel/contour.xlsx`；只传文件名时会自动放到 `excel/` 文件夹。Excel 默认读取 `excel/测量结果.xlsx` 模板，按任务号迁移对应行，表头保持模板一致，只写入本次 `测量结果` 和 `测量结论`。可用 `--result-template` 指定其它模板。
+`contour` 也支持批量运行：`--tasks 13,31,40` 执行指定任务，其中 `13` 会自动匹配 `13_1`、`13_2` 等样本；`--tasks 13_1` 只运行单个样本。`--all` 优先执行 `datasets/Mesh` 下全部样本，没有 Mesh 时退回 `datasets/CAD` 下全部 STEP；批量模式用 `--pointcloud-kind noise|clean` 选择加噪点云或干净点云。所有成功热力图会按原始坐标额外保存成一个合并 PLY：未传 `--save` 时为 `vis/combined_contour.ply`，`--save vis/contour` 时为 `vis/contour/combined_contour.ply`。合并点云默认加入 `datasets/train/train_2_10M.ply`，可用 `--combined-context-pointcloud` 切换为 `train_2_100M.ply` 或 `train_2_1T.ply`。未传 `--no-visualize` 时，合并结果也会按原始坐标在一个 Open3D 窗口展示。
+
+使用配置文件：
+
+```bash
+geometry-measure --config config.yaml full --no-visualize
+```
+
+如果使用打包生成的默认配置，构建脚本会把默认路径改为：
+
+```text
+datasets/CAD/11.step
+datasets/Mesh/11.stl
+datasets/PointCloud/11.ply
+datasets/Noise_PointCloud/11_noisy.ply
+```
+
+## 数据要求
+
+wheel 不包含 `datasets/`，运行时需要自己提供数据路径。建议保持以下结构：
+
+```text
+datasets/
+  CAD/                 # STEP CAD，例如 11.step
+  Mesh/                # STL/OBJ/PLY Mesh，例如 11.stl
+  PointCloud/          # 原始点云 PLY，例如 11.ply
+  Noise_PointCloud/    # 加噪或待配准点云 PLY，例如 11_noisy.ply
+```
+
+CAD、Mesh 和点云需要处在同一坐标系和同一单位下。示例数据按毫米量级处理。`contour` 默认认为输入点云已经与参考模型对齐。
+
+大规模点云可能运行较慢。可以通过配置文件调整：
+
+```yaml
+evaluation:
+  chunk_size: 2048
+  triangle_chunk_size: 4096
+  cad_mesh_deflection: 0.1
+```
+
+`chunk_size` 控制点云分块，`triangle_chunk_size` 控制三角面分块，`cad_mesh_deflection` 控制 STEP 三角化精度。
+
+## 输出建议
+
+建议把日志和可视化产物放到项目根目录的 `vis/`：
+
+```bash
+mkdir -p vis
+geometry-measure curvature --pointcloud datasets/PointCloud/11.ply --save vis/11_curvature.ply --no-visualize
+geometry-measure contour --cad datasets/CAD/11.step --pointcloud datasets/Noise_PointCloud/11_noisy.ply --save vis/11_contour.ply --excel-output 11_contour.xlsx --no-visualize
+geometry-measure contour --tasks 13,31,40 --data-root datasets --pointcloud-kind noise --save vis/contour --excel-output selected_contour.xlsx --no-visualize
+```
+
+如果需要保存命令行指标，可以使用重定向：
+
+```bash
+geometry-measure contour --pointcloud datasets/PointCloud/11.ply --cad datasets/CAD/11.step --no-visualize > vis/contour.log 2>&1
+```
+
+## CAD 转换依赖
+
+基础安装不强制安装 CAD 转换依赖。需要使用 `cad2mesh` 时，建议使用项目根目录的 `environment.yml` 创建或更新独立 Python 3.10 环境：
+
+```bash
+conda env create -f environment.yml
+conda activate point-porj
+pip install -r requirements.txt
+```
+
+如果环境已存在，则执行：
+
+```bash
+conda env update -n point-porj -f environment.yml
+pip install git+https://github.com/AutodeskAILab/occwl
+```
+
+`pythonocc-core` 在很多平台无法通过 pip 安装，请使用 conda 方式。`pythonocc-core=7.5.1` 不支持 Python 3.12，如果 base 环境被固定为 Python 3.12，请新建 Python 3.10 环境。
+
+## 说明
+
+- `datasets/` 不会打进 wheel，请通过命令行参数或配置文件指定本地数据路径。
+- 只有 `translate-align` 依赖的归档脚本会打进 wheel，其他 `archive/` 实验脚本不会打包。
+- 根目录源码保持原样；`packaging/build_package.py` 会生成临时标准包 `geometry_measure`。
--- a/alg/平整度、平面度、轮廓测量v1.5/packaging/build_package.py
+++ b/alg/平整度、平面度、轮廓测量v1.5/packaging/build_package.py
@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+
+PACKAGING_DIR = Path(__file__).resolve().parent
+PROJECT_ROOT = PACKAGING_DIR.parent
+BUILD_DIR = PACKAGING_DIR / "build"
+PACKAGE_DIR = BUILD_DIR / "geometry_measure"
+
+SOURCE_FILES = [
+    "main.py",
+    "pipeline.py",
+    "io_handler.py",
+    "config_loader.py",
+    "cad_converter.py",
+    "registration.py",
+    "evaluation.py",
+    "visualization.py",
+    "config.yaml",
+]
+
+SOURCE_DIRS = [
+    "preprocessing",
+]
+
+ARCHIVE_FILES = [
+    "translate_align_pointcloud_to_cad.py",
+]
+
+IMPORT_REWRITES = {
+    "from pipeline import MeasurementPipeline": "from geometry_measure.pipeline import MeasurementPipeline",
+    "from cad_converter import CADConverter": "from geometry_measure.cad_converter import CADConverter",
+    "from config_loader import ConfigLoader": "from geometry_measure.config_loader import ConfigLoader",
+    "from evaluation import Evaluator": "from geometry_measure.evaluation import Evaluator",
+    "from io_handler import IOHandler": "from geometry_measure.io_handler import IOHandler",
+    "from preprocessing.curvature import CurvatureEstimator": (
+        "from geometry_measure.preprocessing.curvature import CurvatureEstimator"
+    ),
+    "from preprocessing.filters import PreprocessingRunner": (
+        "from geometry_measure.preprocessing.filters import PreprocessingRunner"
+    ),
+    "from preprocessing.noise import GaussianNoiseAdder": (
+        "from geometry_measure.preprocessing.noise import GaussianNoiseAdder"
+    ),
+    "from preprocessing.plane import PlaneEstimator": "from geometry_measure.preprocessing.plane import PlaneEstimator",
+    "from preprocessing.plane import PlaneResult": "from geometry_measure.preprocessing.plane import PlaneResult",
+    "from registration import PointCloudRegistration": "from geometry_measure.registration import PointCloudRegistration",
+    "from visualization import Visualizer": "from geometry_measure.visualization import Visualizer",
+}
+
+PATH_REWRITES = {
+    "CAD/11.step": "datasets/CAD/11.step",
+    "Mesh/11.stl": "datasets/Mesh/11.stl",
+    "PointCloud/11.ply": "datasets/PointCloud/11.ply",
+    "Noise_PointCloud/11_noisy.ply": "datasets/Noise_PointCloud/11_noisy.ply",
+}
+
+
+def main() -> None:
+    rebuild_dir()
+    copy_packaging_metadata()
+    copy_sources()
+    write_package_markers()
+    rewrite_python_imports()
+    rewrite_default_paths()
+    print(f"Build package prepared at: {BUILD_DIR}")
+    print("Install with: pip install -e packaging/build")
+
+
+def rebuild_dir() -> None:
+    if BUILD_DIR.exists():
+        shutil.rmtree(BUILD_DIR)
+    PACKAGE_DIR.mkdir(parents=True)
+
+
+def copy_packaging_metadata() -> None:
+    shutil.copy2(PACKAGING_DIR / "pyproject.toml", BUILD_DIR / "pyproject.toml")
+    shutil.copy2(PACKAGING_DIR / "MANIFEST.in", BUILD_DIR / "MANIFEST.in")
+    shutil.copy2(PACKAGING_DIR / "README.md", BUILD_DIR / "README.md")
+
+
+def copy_sources() -> None:
+    for relative in SOURCE_FILES:
+        src = PROJECT_ROOT / relative
+        if not src.exists():
+            raise FileNotFoundError(f"Missing source file: {src}")
+        shutil.copy2(src, PACKAGE_DIR / relative)
+
+    for relative in SOURCE_DIRS:
+        src = PROJECT_ROOT / relative
+        if not src.exists():
+            raise FileNotFoundError(f"Missing source directory: {src}")
+        shutil.copytree(src, PACKAGE_DIR / relative)
+
+    archive_dir = PACKAGE_DIR / "archive"
+    archive_dir.mkdir(parents=True, exist_ok=True)
+    for relative in ARCHIVE_FILES:
+        src = PROJECT_ROOT / "archive" / relative
+        if not src.exists():
+            raise FileNotFoundError(f"Missing archive file: {src}")
+        shutil.copy2(src, archive_dir / relative)
+
+
+def write_package_markers() -> None:
+    (PACKAGE_DIR / "__init__.py").write_text(
+        '"""Industrial geometry measurement toolkit."""\n\n__version__ = "0.1.0"\n',
+        encoding="utf-8",
+    )
+    preprocessing_init = PACKAGE_DIR / "preprocessing" / "__init__.py"
+    preprocessing_init.write_text('"""Preprocessing tools for point-cloud workflows."""\n', encoding="utf-8")
+    archive_init = PACKAGE_DIR / "archive" / "__init__.py"
+    archive_init.write_text('"""Archived developer workflows exposed by the CLI."""\n', encoding="utf-8")
+
+
+def rewrite_python_imports() -> None:
+    for path in PACKAGE_DIR.rglob("*.py"):
+        text = path.read_text(encoding="utf-8")
+        for old, new in IMPORT_REWRITES.items():
+            text = text.replace(old, new)
+        path.write_text(text, encoding="utf-8")
+
+
+def rewrite_default_paths() -> None:
+    targets = [PACKAGE_DIR / "config.yaml", PACKAGE_DIR / "config_loader.py"]
+    for path in targets:
+        text = path.read_text(encoding="utf-8")
+        for old, new in PATH_REWRITES.items():
+            text = text.replace(old, new)
+        path.write_text(text, encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main()
--- a/alg/平整度、平面度、轮廓测量v1.5/packaging/pyproject.toml
+++ b/alg/平整度、平面度、轮廓测量v1.5/packaging/pyproject.toml
@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "geometry-measure"
+version = "0.1.0"
+description = "Industrial point cloud and mesh geometry measurement toolkit"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "numpy==2.2.2",
+  "scipy",
+  "open3d==0.19.0",
+  "trimesh==4.5.3",
+  "torch",
+  "torchvision",
+  "torchaudio",
+  "PyYAML",
+]
+
+[project.optional-dependencies]
+cad = [
+  "occwl @ git+https://github.com/AutodeskAILab/occwl",
+]
+build = [
+  "build",
+]
+
+[project.scripts]
+geometry-measure = "geometry_measure.main:main"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+include = ["geometry_measure*"]
+
+[tool.setuptools.package-data]
+geometry_measure = ["config.yaml"]