NX二次开发必会：UF_VEC3_distance两点距离计算详解

简介面向NX二次开发初学者的工程源码包围绕UFUN库中的UF_VEC3_distance接口演示如何在UG/NX环境里用C计算三维空间中两点距离。包内提供完整工程源代码、VS工程配置与编译产物从源文件编写、库依赖配置到动态库生成的完整脉络一目了然适合初步接触NX二次开发、希望了解UFUN调用流程的工程师对照学习。压缩包共25个文件以C源码、工程文件、动态库、调试信息、说明文档等类型为主整体大小约3.4MB结构简洁便于本地编译验证。已有894人浏览学习。借助源码可掌握该接口的函数签名与欧几里得距离运算实现同时理解NX二次开发项目从创建、编译到注册调用的基础过程对于后续处理更复杂的几何对象、装配关系或工程图功能也是一条清晰起点。1. NX二次开发绕不开的UF_VEC3_distance两点距离计算做NX二次开发的人几乎都会遇到同一个需求拿到两个三维点坐标算出它们之间的距离。有人直接写sqrt((x1-x2)^2(y1-y2)^2(z1-z2)^2)但UFUN函数库里其实提供一个现成函数UF_VEC3_distance很多老工程师都在用。这个函数的作用就是计算两个double[3]类型点坐标之间的欧氏距离返回值是double代码量只有一行但背后涉及的传参方式、头文件引用、错误码处理、单位换算新手第一次用大概率会踩坑。这篇文章把这套流程拆开来讲——从为什么应该用UF_VEC3_distance而不是手写公式到完整的VS工程代码、UFUN和NXOpen的混用方式再到实际开发中遇到的四个高频坑最后给出批量距离计算的进阶封装。不管你是刚接触NX二次开发的初学者还是已经在写DLL的老手这篇都值得花几分钟过一遍。2. 为什么选UF_VEC3_distance从函数签名到坐标系选型2.1 UF_VEC3_distance函数签名与返回值语义UF_VEC3_distance在UFUN库里的声明长这样double UF_VEC3_distance( const double vec1[3], const double vec2[3] );两个参数都是const double[3]数组分别表示第一个点和第二个点的X、Y、Z坐标。返回值就是两点之间的直线距离。注意这个函数不返回错误码——这点和UFUN里大多数函数不一样。UFUN大部分函数返回int类型的错误码0表示成功非0表示失败但UF_VEC3_distance直接返回一个double距离算不出来或者参数有问题的场景它并不会告诉你。传进去的数组如果不是有效数值比如NaN或无穷大函数也不会报错只会返回一个NaN或无穷大的结果。所以调用前确保点坐标是真实有效的数值这一点在后文的避坑章节会重点展开。2.2 手写公式和UF_VEC3_distance的差异手写三维距离公式当然不难double dist sqrt( pow(p1[0] - p2[0], 2) pow(p1[1] - p2[1], 2) pow(p1[2] - p2[2], 2) );这段代码逻辑上完全等价但实际开发中我更推荐直接用UF_VEC3_distance原因有三个。第一UF_VEC3_distance是NX官方内部使用的同一个实现精度和NX自身测量功能保持完全一致。曾经有开发者手写公式算出结果和NX的测量命令相差0.000001mm排查半天发现是浮点运算舍入方式不同。第二从代码可读性角度UF_VEC3_distance一行就表达意图后续维护的人不需要去读sqrt和pow那一串。第三UFUN函数库在NX各版本之间保持二进制兼容你的DLL用UF_VEC3_distance写的代码从NX 8.5到NX 2212都能正常编译运行不会因为接口变动而翻车。/* 推荐写法直接调用UFUN距离函数 */ double dist UF_VEC3_distance(point1, point2);2.3 坐标系的潜在影响工作坐标系还是绝对坐标系这是新手最容易忽略的一个点。UF_VEC3_distance本身不关心坐标系它只对传进来的数值做数学计算。问题在于你的点在哪个坐标系下获取的。从UF_CSYS_ask_wcs拿到的点坐标值是相对于工作坐标系的从UF_CSYS_ask_origin_of_object拿到的点坐标值是相对于绝对坐标系的。同一个物体在这两个坐标系下的坐标完全不同算出来的距离自然也不同。如果两个点来自不同坐标系直接传给UF_VEC3_distance算出来的结果就是错误的。常见做法是先把点统一转换到绝对坐标系再计算。#include uf.h #include uf_csys.h #include uf_vec.h /* 把工作坐标系下的点转换到绝对坐标系 */ double wcs_point[3] {x_wcs, y_wcs, z_wcs}; double abs_point[3]; UF_CSYS_map_point(UF_CSYS_ROOT_COORDS, wcs_point, UF_CSYS_WORK_COORDS, abs_point);UF_CSYS_map_point这个函数负责坐标系转换第一个参数是源坐标系第三个参数是目标坐标系这里把根坐标系绝对坐标系下的点映射到工作坐标系下——等等这个用法需要澄清一下。UF_CSYS_map_point的参数含义是从源坐标系映射到目标坐标系源点坐标和结果点坐标分别用第二和第四个参数传入。如果要把WCS下的点转到绝对坐标系第一个参数应该传UF_CSYS_WORK_COORDS第三个传UF_CSYS_ROOT_COORDS。我之前在这里就写反过一次算出来的距离差得离谱后来翻帮助文档才发现参数搞反了。3. 完整工程实现从VS项目配置到DLL生成3.1 开发环境准备和头文件依赖开发NX二次开发DLL需要准备三样东西NX软件本身、Visual Studio推荐2017或2019版本、NX自带的NXOpen C开发包。安装NX时勾选开发环境模块后安装目录下会出现UGOPEN文件夹里面就是开发需要的头文件和库文件。一个最简的UFUN程序需要包含以下头文件#include uf.h /* UFUN初始化相关函数 */ #include uf_ui.h /* 用户界面接口用于打印信息到NX信息窗口 */ #include uf_curve.h /* 曲线相关函数 */ #include uf_vec.h /* 向量和距离计算函数UF_VEC3_distance就在这里面 */ #include uf_csys.h /* 坐标系相关函数 */编译链接阶段需要添加的库文件包括libufun.lib、libnxopenuicpp.lib、libnxopencpp.lib等。在VS的工程属性里附加依赖项里添加这些lib文件。如果用的是NX 12或更高版本还需要把$(UGII_BASE_DIR)\UGOPEN添加到附加包含目录把$(UGII_BASE_DIR)\UGOPEN添加到附加库目录。3.2 最小可运行的UF_VEC3_distance计算代码下面是一个可以在NX里直接运行的完整代码片段。这段代码的作用是在NX信息窗口输出两个已知点之间的距离。#include uf.h #include uf_ui.h #include uf_vec.h /* NX入口函数在NX里执行菜单或命令时被调用 */ extern C DllExport void ufusr(char* param, int* returnCode, int rlen) { /* 初始化UFUN环境很多新手忘了这步直接调函数会报错 */ UF_initialize(); /* 定义两个测试点的坐标 */ double point1[3] {0.0, 0.0, 0.0}; double point2[3] {30.0, 40.0, 0.0}; /* 调用UF_VEC3_distance计算两点距离 */ double distance_val UF_VEC3_distance(point1, point2); /* 在NX信息窗口输出结果方便调试 */ char message[256]; sprintf(message, 两点距离 %f mm, distance_val); UF_UI_open_listing_window(); UF_UI_write_listing_window(message); /* 释放UFUN环境 */ UF_terminate(); }这段代码的逻辑是入口函数ufusr是NX调用DLL的约定入口整个流程分为三块——初始化UFUN环境、执行距离计算、输出结果到信息窗口。计算本身只有一行UF_VEC3_distance(point1, point2)输入是double[3]数组输出是距离数值。参数说明point1和point2分别是起点和终点的X、Y、Z坐标。在这个例子里(0,0,0)到(30,40,0)的距离是sqrt(30^2 40^2) 50运行后信息窗口会显示50.000000。UF_UI_open_listing_window和UF_UI_write_listing_window是UFUN输出调试信息的两个必要步骤前者负责打开信息窗口后者负责写入内容。3.3 从任意UF对象获取点坐标并计算实际开发中很少直接手工定义一个点坐标更多是从NX模型里选中物体、再获取它的关键点坐标。这里演示一个从已有直线端点计算长度的例子#include uf.h #include uf_obj.h #include uf_curve.h #include uf_vec.h extern C DllExport void ufusr(char* param, int* returnCode, int rlen) { UF_initialize(); /* 获取当前工作部件中第一条直线的标签 */ tag_t line_tag NULL_TAG; UF_OBJ_cycle_objs_in_part(UF_PART_ask_display_part(), UF_line_type, line_tag); if (line_tag ! NULL_TAG) { /* 把直线对象转换成曲线数据结构 */ UF_CURVE_line_t line_data; UF_CURVE_ask_line_data(line_tag, line_data); /* 直线的起点和终点坐标 */ double start_point[3] {line_data.start_point[0], line_data.start_point[1], line_data.start_point[2]}; double end_point[3] {line_data.end_point[0], line_data.end_point[1], line_data.end_point[2]}; /* 计算直线长度这个就是UF_VEC3_distance的典型场景 */ double length UF_VEC3_distance(start_point, end_point); char message[256]; sprintf(message, 直线长度 %f mm, length); UF_UI_open_listing_window(); UF_UI_write_listing_window(message); } else { UF_UI_open_listing_window(); UF_UI_write_listing_window(当前部件中没有直线对象); } UF_terminate(); }这段代码展示了从NX模型对象中提取坐标的完整链路。UF_OBJ_cycle_objs_in_part遍历部件中所有直线类型的对象返回第一个找到的直线tagUF_CURVE_ask_line_data把tag转换为包含起终点坐标的数据结构。最终交给UF_VEC3_distance计算的就是这个真实模型中的几何数据。这个写法在批量处理场景里很有用。比如要获取一个部件里所有直线段的长度只需要用循环遍历所有tag对每条线段重复执行UF_CURVE_ask_line_data和UF_VEC3_distance就可以了。3.4 工程配置避坑debug和release模式要区分VS工程配置NX二次开发DLL时Debug和Release两个模式下的配置建议分开做。Debug模式下使用MDd运行库Release模式下使用MD运行库混用会在运行时出现内存分配错误。另外NX加载DLL要求64位编译在VS的解决方案平台里选择x64否则NX会直接拒绝加载并报错。一个更隐蔽的问题是预处理器定义。NXOpen工程需要在预处理器里加上_USRDLL和NXOPENCPP这两个宏定义。有些开发者只加了_USRDLL编译时头文件包含逻辑就不对报出一堆莫名其妙的语法错误。4. 进阶封装把UF_VEC3_distance变成批量距离计算工具4.1 封装成通用工具函数一个项目里可能需要在几十个地方调用距离计算每次写double[3]数组比较麻烦。更好的做法是封装一个工具函数统一入口和错误处理逻辑。#include uf.h #include math.h /* 工具函数计算两个三维点的距离带坐标合法性检查 */ double CalculateDistance(double* point1, double* point2) { /* 非法坐标检查如果包含NaN或无穷大就直接返回0避免污染计算结果 */ if (!isfinite(point1[0]) || !isfinite(point1[1]) || !isfinite(point1[2]) || !isfinite(point2[0]) || !isfinite(point2[1]) || !isfinite(point2[2])) { return 0.0; } /* 直接调用UFUN距离函数 */ return UF_VEC3_distance(point1, point2); }这个封装函数在两个场景下特别有用一是从建模API拿到的坐标可能包含未初始化的值二是用户在交互选择过程中可能存在点选不到的情况导致坐标数组未赋值。isfinite是C标准库math.h里的函数能同时检查NaN和无穷大。参数说明point1和point2是double数组指针调用时传入double[3]即可。如果坐标合法就正常返回距离值如果非法返回0.0并让调用方知道数据有问题。4.2 批量计算点到点的距离在实际项目中比如装配干涉检查、刀路模拟、测量分析经常需要计算一个点到一组点之间的距离然后找出最近或最远的那一个。下面是批量距离计算的实现思路#include uf.h /* 批量计算参考点到所有目标点的距离返回最近距离和对应索引 */ double FindNearestDistance(double* ref_point, double** target_points, int point_count, int* nearest_index) { double min_dist DBL_MAX; int min_idx -1; for (int i 0; i point_count; i) { double dist UF_VEC3_distance(ref_point, target_points[i]); /* 记录距离最小的点 */ if (dist min_dist) { min_dist dist; min_idx i; } } *nearest_index min_idx; return min_dist; }这个函数解决了「一个参考点对多个目标点求最近距离」的常见需求。target_points是二维数组每一行是一个点坐标point_count是目标点的数量nearest_index通过指针参数把距离最近的点的索引回传给调用方。返回值是最小距离值。实际使用中要注意DBL_MAX在float.h头文件里定义如果你的工程没有包含这个头文件编译会报错。另外当所有点都不合法时这个函数会返回DBL_MAX调用方需要感知到这个边界情况。4.3 把UF_VEC3_distance和NXOpen的Point对象打通现在很多NX二次开发项目是NXOpen和UFUN混用的。从NXOpen的Point对象获取坐标再交给UF_VEC3_distance计算这个流程很多人写错过。NXOpen的Point.Coordinates返回的是Point3d结构体不能直接传给UF_VEC3_distance。/* C#版本的NXOpen混用示例 */ using NXOpen; using NXOpen.UF; public class DistanceTool { public double DistanceBetweenPoints(Point point1, Point point2) { /* 从NXOpen Point对象提取坐标 */ Point3d p1 point1.Coordinates; Point3d p2 point2.Coordinates; /* 转换成UFUN的double[3]格式 */ double[] ufPoint1 new double[3] { p1.X, p1.Y, p1.Z }; double[] ufPoint2 new double[3] { p2.X, p2.Y, p2.Z }; /* 调用UF_VEC3_distance */ double distance UFUFSession.GetUFSession().Vec3.Distance(ufPoint1, ufPoint2); return distance; } }这里的核心转换逻辑是NXOpen用Point3d结构体成员是X、Y、ZUFUN用double[3]数组。两者看起来很像但类型不同不能直接强转。先用point.Coordinates取出坐标再new一个double数组把值填进去最后通过UFUFSession.GetUFSession().Vec3.Distance调用UF_VEC3_distance函数。4.4 距离计算性能批量场景下的优化空间UF_VEC3_distance本身的开销极小每次调用只有几个乘法和一个开方。真正的性能瓶颈在遍历点的循环本身以及从tag获取坐标数据的IO操作。数据规模是10万个点以下UF_VEC3_distance直接调用完全没问题。数据规模到了百万级别就要考虑减少UF_CURVE_ask_line_data这种获取坐标信息的高开销调用最好一次性把所有坐标都读出来存入内存数组再循环计算距离。/* 批量坐标读取后统一计算距离避免反复调用UF API */ double* all_points (double*)malloc(point_count * 3 * sizeof(double)); /* 循环中只做UF_VEC3_distance运算 */ for (int i 0; i point_count; i) { double dist UF_VEC3_distance(ref_point, all_points[i * 3]); /* 处理距离结果 */ } free(all_points);all_points[i * 3]这种写法相当于把一维数组当成二维数组用第i个点的坐标存储在all_points[3*i]、all_points[3*i1]、all_points[3*i2]这三个连续内存槽位里。这样做的优势是内存连续CPU缓存命中率高比二维数组double[point_count][3]的形式在遍历时更友好。5. 避坑与大坑排查UF_VEC3_distance常见问题记录5. 避坑与大坑排查UF_VEC3_distance常见问题记录5.1 忘记了UF_initialize直接调用函数导致死机现象在ufusr入口函数里直接调用UF_VEC3_distance没有先调用UF_initialize()。程序运行到计算那行时NX直接崩溃或者函数返回异常值。原因UFUN库的大部分函数都要求先调用UF_initialize()来初始化运行环境。这个初始化会建立UFUN和NX核心的数据交互通道没有初始化的情况下直接调用内部指针是空指针或无效状态函数行为未定义。解决在ufusr函数的第一行加UF_initialize()在函数返回前加UF_terminate()。这个习惯必须养成不要只加初始化忘记了终止否则NX会话里会积累未释放的内存资源长时间运行会导致NX越来越卡。5.2 坐标获取方式不对导致距离结果和NX测量不一致现象计算出来的距离和NX的测量命令Analysis - Measurement结果不一样差值可能是几百毫米甚至上千毫米。原因NX测量命令默认是在工作坐标系下显示的但你从UF_CSYS_ask_origin_of_object获取的对象坐标是绝对坐标系下的值。两套坐标系不一致时直接计算当然结果对不上。解决确认两个点来自同一个坐标系。如果来自不同坐标系先通过UF_CSYS_map_point统一坐标系再计算。还有一个最隐蔽的情况——NX的测量命令可能启用了「投影距离」而UF_VEC3_distance计算的是真实三维直线距离。投影距离是把点投影到某个平面再量距离那结果当然更小。遇到结果不一致时先确认NX测量面板里选的是「3D距离」而不是「投影距离」。5.3 传了非法值给UF_VEC3_distance函数现象计算结果是一个极大值、极小值或者NaN完全不符合实际情况。原因两个点坐标数组里含有未初始化数据或者NaN。这在交互选择点失败、建模函数返回错误点、或者数组越界写入时经常发生。UF_VEC3_distance本身不校验输入数据拿到什么算什么。解决调用UF_VEC3_distance之前用isfinite检查点坐标的每个分量发现非法值就返回错误提示而不是继续计算。写一个工具函数统一处理这个问题不建议在业务代码里重复写检查逻辑。/* 安全计算带数据合法性检查的距离计算 */ double SafeDistance(double* p1, double* p2) { for (int i 0; i 3; i) { if (!isfinite(p1[i]) || !isfinite(p2[i])) { return -1.0; /* 返回负值表示计算失败 */ } } return UF_VEC3_distance(p1, p2); }5.4 Debug和Release混用导致DLL加载崩溃现象DLL编译成功但在NX里执行菜单命令时NX直接闪退没有任何错误提示。用Debug模式编译的DLL在Release版NX环境里运行尤其容易出现这种问题。原因Debug模式下C运行时库是MDdRelease模式是MD。两种模式的内存管理机制不同Debug模式下分配的内存块带有调试信息头Release模式的NX在释放时不知道如何处理这些额外的调试数据导致内存损坏。解决发布给用户使用时必须用Release模式编译勾选x64平台。开发调试阶段可以用Debug模式但发布前要养成检查配置的习惯。另外注意NX 12.0及以上版本只支持64位DLL32位编译的DLL就算Release模式也加载不了。5.5 数组下标越界导致计算结果随机波动现象距离计算结果的数值每次都变有时候对有时候错完全琢磨不定。原因传入UF_VEC3_distance的数组长度不足3或者调用前越界写入了别的值覆盖了数组内容。C语言不检查数组越界程序不会直接报错但数据已经被破坏后续计算自然不稳定。解决检查所有创建坐标数组的代码确保申请了3个double的内存空间。如果用了struct类型传参要确保结构体里就是三个连续double成员中间不能夹杂其他变量。从NXOpen转换坐标时务必用new double[3]显式创建不要用double[]的猜法。6. 活用UF_VEC3_distance测量模块开发的一种轻量方案NX自带的测量命令功能完整但有些场景下我们需要的不是复杂测量而是快速拿到特定几何的距离做后续判断。比如在自动检查装配间隙的代码里只需要知道两个面的最近距离是否大于某个阈值或者在加工路径规划时需要判断刀尖点到工件表面的距离。UF_VEC3_distance在这些场景里可以作为测量模块的轻量替代方案。做法是这样的拿到两个几何对象后先用UF_MODL_ask_minimum_dist_3计算它们之间的最小距离。这个函数输出的结果里就包含距离值同时还能给出两个面上距离最近的一对点坐标。把这两个点坐标再用UF_VEC3_distance算一遍交叉验证结果的正确性#include uf_modl.h #include uf_vec.h /* 计算两个对象之间的最小距离并用UF_VEC3_distance做交叉验证 */ double MinDistanceBetweenObjects(tag_t object1, tag_t object2) { double min_dist 0.0; double point_on_obj1[3], point_on_obj2[3]; double closest_points[2][3]; /* 调用UFUN求最小距离函数 */ UF_MODL_ask_minimum_dist_3(object1, object2, 0.0, min_dist, point_on_obj1, point_on_obj2, closest_points); /* 用UF_VEC3_distance验证最近点对之间的距离 */ double verify_dist UF_VEC3_distance(point_on_obj1, point_on_obj2); /* 如果两者差异超过0.001mm说明计算有问题 */ if (fabs(min_dist - verify_dist) 0.001) { return -1.0; /* 返回-1表示计算不一致 */ } return min_dist; }UF_MODL_ask_minimum_dist_3的第一个参数是对象1的tag第二个是对象2的tag第三个是精度控制参数传0.0表示使用默认精度第四个是输出距离值第五和第六个参数是最近点的坐标输出。这个函数本身已经能给到距离值那为什么还要用UF_VEC3_distance做验证因为UF_MODL_ask_minimum_dist_3在某些复杂曲面场景下可能出现收敛不到全局最优解的情况返回的最小距离局部最优——如果和最近点坐标算出来的直线距离差异超过0.001mm就说明结果不可靠。这个验证逻辑在模具分型面间隙检查里帮过大忙。批量场景的处理方式是把所有对象存放在数组里双重循环遍历每对组合对每组调用MinDistanceBetweenObjects。注意UF_MODL_ask_minimum_dist_3是计算密集型函数N个对象就是N*(N-1)/2次调用对象数量超过500个时运行时间会比较明显建议放在后台线程执行同时加上进度条反馈给用户。从那以后我每次接到NX几何计算的需求都会先想清楚一个问题——我要的是真实三维距离、投影距离、还是最小距离确定之后再选UF_VEC3_distance还是UF_MODL_ask_minimum_dist而不是拿到需求就直接复制代码。这个区分也建议你保持能省掉大量排查和返工的时间。希望帮到你。本文还有配套的精品资源点击获取