简介：本资源面向UG/NX二次开发初学者与需要定制几何计算功能的工程师，围绕UFUN函数库中UF_VEC3_distance的调用展开，解决三维空间中两点欧几里得距离的编程计算问题。压缩包共25个文件，约3.4MB，包含cpp源代码、vcxproj工程文件、sln解决方案、dll动态库、lib导入库及pdb调试符号等，另有tlog、log日志与obj中间文件，完整保留了从源码到编译产物的工程结构，便于直接打开调试或对照学习。已有894人学习下载，说明该案例在NX二次开发入门中具有一定参考价值。读者可从中获取可编译运行的工程模板、函数注册与链接库配置思路，以及将自定义UFUNC集成到NX环境的完整实践路径，适合作为掌握NX API几何计算模块的起步练习。
1. 从一行 UF_VEC3_distance 说起：这个 NX 二次开发源码包到底能干什么
如果你正在做 NX 二次开发，大概率绕不开一个最基础的需求：算两个点之间的距离。听起来简单，但真到写代码的时候，问题就来了——用 UF 函数还是 NXOpen？点坐标怎么从 UI 里拿？单位怎么处理？算出来的结果怎么回写到模型属性里？我见过不少刚入行的朋友，卡在UF_VEC3_distance这个函数上，不是不会调，而是不知道它在整个开发流程里该放在哪一层。
这份源码包就是围绕UF_VEC3_distance展开的一个完整可运行示例。它不是一个孤立的函数 demo，而是一个能挂到 NX 菜单上、能弹对话框、能选点、能算距离、能把结果写回模型的完整小项目。适合两类人：一是刚接触 NX 二次开发、想找一个最小可运行闭环的新手；二是已经会写 NXOpen、但想回头补 UFUN 底层函数功底的熟手。整个包的结构不复杂，但麻雀虽小，从入口、UI、核心计算到结果输出，链路是完整的。
2. 项目结构拆解：从菜单入口到核心计算的完整链路
2.1 目录结构与文件职责
拿到源码包，先别急着编译。我一般会先花五分钟把目录扫一遍，搞清楚每个文件是干什么的。这个项目的结构是典型的 NX 二次开发小项目布局，大致长这样：
NX_Distance_Demo/ ├── application/ │ └── distance_demo.men # 菜单脚本，注册到 NX 菜单栏 ├── startup/ │ └── distance_demo.dlx # 对话框文件，定义 UI 布局 ├── code/ │ ├── distance_demo_main.cpp # 入口函数 ufusr / ufsta │ ├── distance_demo_ui.cpp # 对话框回调逻辑 │ └── distance_demo_core.cpp # 核心计算，调用 UF_VEC3_distance ├── include/ │ └── distance_demo.h # 公共头文件，结构体与函数声明 └── build/ └── CMakeLists.txt # 编译配置application目录放菜单脚本，NX 启动时会扫描这个目录，把菜单项挂上去。startup目录放对话框文件，.dlx是 NX 的对话框定义格式，可以用 Block UI Styler 生成。code目录是真正的业务代码，我习惯把入口、UI 回调、核心计算分开，这样改 UI 的时候不会碰到计算逻辑，改计算的时候也不会误伤 UI。include放公共声明，build放编译脚本。
提示：不同 NX 版本对目录名的要求略有差异，
application和startup这两个名字是约定俗成的，别随便改，改了 NX 可能扫不到。
2.2 菜单与对话框的注册方式
菜单脚本distance_demo.men的内容不复杂，核心是定义一个菜单项，绑定到对话框。常见写法是这样：
VERSION 120 EDIT UG_GATEWAY_MAIN_MENUBAR BEFORE UG_HELP CASCADE_BUTTON DISTANCE_DEMO_MENU LABEL 距离计算工具 END_OF_BEFORE MENU DISTANCE_DEMO_MENU BUTTON DISTANCE_DEMO_BTN LABEL 计算两点距离 ACTIONS distance_demo.dlx END_OF_MENU这段脚本做了三件事：声明版本、在帮助菜单前面插入一个级联菜单、在级联菜单下挂一个按钮，按钮的ACTIONS指向对话框文件。BEFORE UG_HELP是位置控制，意思是插在帮助菜单之前。CASCADE_BUTTON定义父菜单，BUTTON定义子项。
对话框文件.dlx一般用 Block UI Styler 可视化生成，里面会定义点选择控件、结果显示控件、确定取消按钮。每个控件有一个唯一的BlockID，这个 ID 就是后面 C++ 回调里用来识别控件的钥匙。我一般会在生成对话框后，把 BlockID 抄到一张纸上，写代码的时候对着看，省得来回切窗口。
2.3 入口函数与初始化流程
NX 二次开发的入口函数有两个常见选择：ufusr和ufsta。ufusr是用户手动触发时调用，ufsta是 NX 启动时自动调用。这个项目用的是ufusr，因为距离计算是用户主动发起的操作。
#include <uf.h> #include <uf_ui.h> #include "distance_demo.h" extern "C" DllExport void ufusr(char *param, int *retCode, int paramLen) { UF_initialize(); // 初始化 UFUN 环境 // 弹出对话框，进入 UI 交互 UF_UI_open_dialog("distance_demo.dlx", UF_UI_DIALOG_TYPE_MODAL, distance_demo_ui_cb, NULL, &dialog_id); UF_terminate(); // 释放 UFUN 环境 *retCode = 0; }UF_initialize()和UF_terminate()必须成对出现，这是 UFUN 的规矩。中间那句UF_UI_open_dialog打开对话框，第三个参数是回调函数指针，所有 UI 事件都会进到这个回调里。UF_UI_DIALOG_TYPE_MODAL表示模态对话框，用户不关掉它就不能操作 NX 主界面。
这里有个血泪经验：UF_initialize()如果忘了写，后面所有 UF 函数都会返回错误码，而且错误信息很模糊，新手很容易在这里翻车。我一般会在入口函数第一行就写上，形成肌肉记忆。
3. 核心计算模块：UF_VEC3_distance 的参数、返回值与调用姿势
3.1 函数原型与参数含义
UF_VEC3_distance的函数原型在uf_vec.h里，长这样：
int UF_VEC3_distance( const double vec1[3], // 第一个点的三维坐标 const double vec2[3], // 第二个点的三维坐标 double *distance // 输出：两点之间的距离 );三个参数：两个输入点坐标数组，一个输出距离指针。返回值是错误码，0表示成功，非0表示失败。点坐标是double[3]，分别对应 X、Y、Z。这个函数不修改输入点，只读不写，所以传const没问题。
注意一点：这个函数算的是欧几里得距离，也就是直线距离，不考虑曲面、路径、投影。如果你要算的是沿曲线距离或者最短路径，这个函数不适用，得换别的 API。
3.2 核心计算代码逐段讲解
核心计算模块distance_demo_core.cpp里，我一般会封装一个函数，把 UI 层和计算层隔开：
#include <uf_vec.h> #include "distance_demo.h" // 计算两点距离，返回错误码 int calc_two_point_distance(const double p1[3], const double p2[3], double *out_dist) { if (p1 == NULL || p2 == NULL || out_dist == NULL) { return -1; // 空指针保护 } double dist = 0.0; int err = UF_VEC3_distance(p1, p2, &dist); if (err != 0) { // 记录错误日志，方便排查 char msg[256]; sprintf_s(msg, "UF_VEC3_distance failed, err=%d", err); UF_print_syslog(msg, FALSE); return err; } *out_dist = dist; return 0; }这段代码做了四件事：空指针检查、调用UF_VEC3_distance、错误日志记录、结果回写。空指针检查是防御性编程，虽然 UI 层理论上不会传空，但多一层保护不亏。错误日志用UF_print_syslog写到 NX 系统日志里，出问题的时候可以去日志里翻。
参数说明：p1和p2是输入点坐标，调用方保证是double[3]；out_dist是输出指针，调用方负责分配内存。返回值0成功，非0失败，失败时out_dist不被修改。
3.3 从 UI 选点到坐标提取
UI 层拿到用户选的点和计算层拿到坐标，中间需要一个转换。NX 里点选择控件返回的通常是UF_UI_POINT结构或者 tag，需要转成double[3]：
// UI 回调中提取点坐标 static int get_point_coord_from_ui(tag_t point_tag, double coord[3]) { UF_CURVE_point_t point_data; int err = UF_CURVE_ask_point_data(point_tag, &point_data); if (err != 0) { return err; } coord[0] = point_data.point[0]; coord[1] = point_data.point[1]; coord[2] = point_data.point[2]; return 0; }UF_CURVE_ask_point_data是查询点数据的函数，返回的UF_CURVE_point_t结构里包含坐标。这里要注意，如果用户选的是草图点或者基准点，返回的 tag 类型可能不一样，需要先判断类型再查询。我一般会在 UI 回调里加一个类型检查，不是点类型就直接报错，别硬转。
3.4 结果回写与单位处理
算完距离，结果要显示在对话框上，有时候还要写到模型属性里。显示到对话框用UF_UI_set_dialog_item_value，写属性用UF_ATTR_assign。单位方面，NX 内部默认是毫米，如果模型单位是英寸，需要做转换。常见做法是查一下模型单位，然后乘换算系数：
// 根据模型单位转换距离 double convert_distance_by_unit(double dist_mm, int unit_type) { if (unit_type == UF_UNIT_INCH) { return dist_mm / 25.4; } return dist_mm; // 默认毫米 }UF_UNIT_INCH是英寸的单位常量，25.4是毫米到英寸的换算系数。这个逻辑不复杂，但容易漏。我见过有人算出来的距离数值对，但单位标错了，用户一看就懵。
4. 编译、部署与运行：把源码跑起来的完整步骤
4.1 编译环境与依赖配置
编译 NX 二次开发代码，需要 NX 的 Open API 头文件和库文件。常见做法是在 CMakeLists.txt 里指定 NX 安装目录：
cmake_minimum_required(VERSION 3.10) project(NX_Distance_Demo) set(NX_ROOT "C:/Program Files/Siemens/NX") include_directories( ${NX_ROOT}/NXOPEN/INCLUDE ${NX_ROOT}/NXOPEN/INCLUDE/uf ) add_library(distance_demo SHARED code/distance_demo_main.cpp code/distance_demo_ui.cpp code/distance_demo_core.cpp ) target_link_libraries(distance_demo ${NX_ROOT}/NXOPEN/LIB/libufun.lib ${NX_ROOT}/NXOPEN/LIB/libnxopen.lib )NX_ROOT指向 NX 安装目录，include_directories加头文件路径，target_link_libraries链接libufun和libnxopen。这两个库是 UFUN 和 NXOpen 的核心库，基本每个项目都要链。
注意：不同 NX 版本的库文件名可能略有差异，有的版本是
libufun.lib，有的是ufun.lib，编译报链接错误的时候先去目录里看一眼实际文件名。
4.2 部署到 NX 运行目录
编译出.dll之后，需要把相关文件放到 NX 能扫描到的目录。常见做法是建一个自定义目录，然后在 NX 环境变量里加路径：
自定义目录/ ├── application/ │ └── distance_demo.men ├── startup/ │ └── distance_demo.dlx └── distance_demo.dll然后在 NX 的custom_dirs.dat文件里加上这个自定义目录的路径。custom_dirs.dat一般在 NX 安装目录的UGII文件夹下。加完之后重启 NX，菜单就会出现在菜单栏上。
4.3 运行验证与日志查看
点菜单项，弹出对话框，选两个点，点确定，看结果。如果一切正常，对话框上会显示距离值。如果没反应，先看 NX 系统日志，路径一般在%TEMP%下的syslog文件里。日志里会记录UF_print_syslog输出的错误信息，这是排查问题的第一手资料。
我一般会在关键节点都加日志输出，比如入口函数进来打一条、计算前打一条、计算后打一条。这样出问题的时候，看日志就知道卡在哪一步。日志不嫌多，出问题的时候你就知道它的好了。
5. 避坑与常见问题：那些年我在 NX 二次开发里踩过的坑
5.1 现象：编译通过但运行时报错「找不到入口点」
原因：.dll导出函数名不对。NX 要求入口函数必须是ufusr或ufsta，而且要用extern "C"和DllExport修饰。如果用了 C++ 的 name mangling，NX 就找不到。
解决：检查入口函数声明，确保有extern "C"和DllExport。可以用dumpbin /exports看一下导出表，确认函数名是ufusr而不是?ufusr@@YAXPEADPEAHH@Z这种。
5.2 现象：对话框能弹出但选点没反应
原因：对话框回调函数没绑定对，或者 BlockID 写错了。.dlx文件里每个控件有一个 ID，C++ 回调里用这个 ID 来识别控件。ID 写错一个字母，回调就进不去。
解决：把.dlx文件里的 BlockID 和 C++ 代码里的 ID 逐一对照，确保完全一致。我一般会把 BlockID 定义成常量，别用魔法字符串。
5.3 现象：距离算出来是 0 或者负数
原因：点坐标没取到，或者取到了但传参传错了。常见的是把tag当坐标传了，或者数组越界。
解决：在调用UF_VEC3_distance之前，先把两个点的坐标打印到日志里，确认数值合理。如果坐标是(0,0,0)，说明点没取到，回去检查UF_CURVE_ask_point_data的返回值。
5.4 现象：NX 启动变慢或者菜单不显示
原因：custom_dirs.dat路径写错，或者菜单脚本语法有误。NX 启动时会扫描所有自定义目录，如果某个目录下的.men文件语法错误，可能导致整个扫描过程变慢甚至失败。
解决：先用一个最简单的菜单脚本测试，确认路径和语法没问题，再逐步加内容。菜单脚本的语法检查可以用 NX 自带的工具，或者手动对照官方示例。
5.5 现象：多线程调用 UF 函数崩溃
原因：UFUN 函数不是线程安全的，NX 主线程之外调用可能崩溃。
解决：所有 UF 函数调用都放在 NX 主线程里，别自己开线程。如果确实需要异步，用 NX 提供的回调机制，别硬来。
6. 二次开发改造思路：从距离计算到通用几何工具
这个项目虽然小，但骨架是完整的。如果你想把它改成一个通用的几何计算工具，有几个方向可以走。
第一个方向是扩展计算类型。现在只算两点距离，你可以加点到直线的距离、点到平面的距离、两平行线距离等等。核心思路是一样的：从 UI 拿几何对象，转成坐标或方程，调对应的 UF 函数，回写结果。我一般会定义一个枚举类型表示计算类型，然后写一个分发函数，根据类型调不同的计算逻辑。
enum CalcType { CALC_POINT_POINT = 0, CALC_POINT_LINE, CALC_POINT_PLANE, CALC_LINE_LINE }; int dispatch_calc(CalcType type, const GeoInput &input, double *result) { switch (type) { case CALC_POINT_POINT: return calc_two_point_distance(input.p1, input.p2, result); case CALC_POINT_LINE: return calc_point_line_distance(input.p1, input.line, result); // ... 其他类型 default: return -1; } }GeoInput是一个结构体，把各种几何输入统一起来。这样加新类型的时候，只需要加一个 case 和一个计算函数，不用动 UI 层。
第二个方向是批量计算。现在是一次算一对点，你可以改成选一组点，两两算距离，输出一个距离矩阵。这个在检具检测、装配分析里很常用。批量计算要注意性能，点多了之后UF_VEC3_distance调用次数是平方级增长，我一般会加一个进度条，别让用户以为卡死了。
第三个方向是结果可视化。算完距离，可以在两个点之间画一条临时直线，把距离标注上去。用UF_DISP_create_line画线，用UF_DISP_create_text加标注。这样用户能直观看到算的是哪两个点之间的距离，减少误操作。
验证改造是否成功，我一般用三个测试用例：重合点（距离应为 0）、单位距离点（距离应为 1）、大坐标点（验证数值精度）。这三个过了，基本逻辑就没问题。
从那以后我每次改完核心计算函数，都强制走一遍这三个用例，不管改动多小。有一次我改了一个坐标转换的逻辑，觉得肯定没问题，结果重合点算出来是1e-15而不是0，虽然数值上可以忽略，但用户看到科学计数法就慌了。后来我加了一个阈值判断，小于1e-10的直接归零，省得解释。希望这些经验帮到你，少走点弯路。
本文还有配套的精品资源，点击获取
