Vuforia Studio 导航 > 项目窗格 > 资源 > 将 3D 模型结构边界框和位置数据合并到体验中
  
将 3D 模型结构边界框和位置数据合并到体验中
PTC.Structure API 可提供 3D 模型各个部件的边界框和位置的相关信息。此信息可用于在体验中相对于模型或模型内各个部件的位置定位小组件（3D 图像、标签等）。
* 
要使用此 API，必须在导入模型时选中“允许体验访问 CAD 元数据”复选框。
API 包括用于获取边界框和位置信息的函数调用，以及一组用于表示和处理此信息的 JavaScript 对象。要使用 PTC.Structure API，必须先调用 fromId(…) 函数，并提供要检索其结构信息的 3D 模型的 Id；该函数返回 JavaScript Promise。
这些 API 基于 Promise。有关 Promise 的详细信息，请参阅 https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise。
例如：
PTC.Structure.fromId(‘model-1’).then( (structure) => {
// Do something with ‘structure’
});
结构 API 函数
声明
参数
说明
getBounds (idpath)
• {string|string[]} idpath - ID 路径 (例如 '/0/1') 或 ID 路径数组 ['/0/1', '/0/2']。
• {string|string[]} propName -（可选）例如 'Display Name' 或 ['Display Name', 'Part ID Path']
• {string|string[]} categoryName -（可选）例如 'PROE Parameters'。
获取表示指定 idpath 和 propName 的 ID 路径或属性值的元数据对象。
此函数返回表示指定 idpath 的元数据对象，若指定 propName，则返回组件的属性值。
示例：
PTC.Metadata.fromId('model-1').then( (metadata) => {
var result = metadata.get('/0/6', 'Display Name')
});
getLocation (idpath)
• {string|string[]} propName -（可选）例如 'Display Name' 或 ['Display Name', 'Part ID Path']
• {string|string[]} categoryName -（可选）例如 'PROE Parameters'。
此函数返回单个组件的所有字符串属性值，若无可用的数据/组件，则函数未定义。若指定的 propName 是数组，则返回值的 string[]。
示例：
PTC.Metadata.fromId('model-1').then( (metadata) => {
var result = metadata.get('/0/1').getProp('Display Name');
});
Structure.Bounds 对象
Structure.Bounds 对象表示 3D 空间中的轴对齐边界框 (AABB)。
Structure.Bounds 对象属性
属性
说明
min
边界框的最小区域，表示为一个具有属性 x、y 和 z 的对象，以及将这三个值作为数组返回的 asArray 方法。
示例：
PTC.Structure.fromId(‘model-1’).then( (structure) => {
var bounds = structure.getBounds(‘/0/6’);
var min_X = bounds.min.x;
}
max
边界框的最大区域，表示为一个具有属性 x、y 和 z 的对象，以及将这三个值作为数组返回的 asArray 方法。
示例：
PTC.Structure.fromId(‘model-1’).then( (structure) => {
var bounds = structure.getBounds(‘/0/6’);
var max_X = bounds.max.x;
}
center
边界框的中心点，表示为一个具有属性 x、y 和 z 的对象，以及将这三个值作为数组返回的 asArray 方法。
示例：
PTC.Structure.fromId(‘model-1’).then( (structure) => {
var bounds = structure.getBounds(‘/0/6’);
var center_X = bounds.center.x;
}
corners
由边界框的 8 个拐角点构成的数组，每个拐角点表示为一个具有属性 x、y 和 z 的对象，以及将这三个值作为数组返回的 asArray 方法。
示例：
PTC.Structure.fromId(‘model-1’).then( (structure) => {
var bounds = structure.getBounds(‘/0/6’);
var one_corner = bounds.corners[0];
var one_corner_X = one_corner.x
}
Structure.Bounds 对象函数
声明
参数
说明
transform (position, rotation, scale)
• {number[]|string[]|string} position - 所需变换的位置分量，可指定为三个数字构成的数组（[0,0,5]）、表示这些数字的字符串数组（[‘0’,’0’,’5’]），或者以逗号分隔的三个数字构成的单个字符串（‘0,0,5’）
• {number[]|string[]|string} rotation - 所需变换的旋转分量，可指定为三个数字构成的数组（[0,0,5]）、表示这些数字的字符串数组（[‘0’,’0’,’5’]），或者以逗号分隔的三个数字构成的单个字符串（‘0,0,5’）。如果省略，则不应用旋转变换。
• {number[]|string[]|string|number} scale - 所需变换的比例分量，可指定为三个数字构成的数组（[0,0,5]）、表示这些数字的字符串数组（[‘0’,’0’,’5’]）、以逗号分隔的三个数字构成的单个字符串 ‘0,0,5’，或者表示统一缩放因子的单个数字。如果省略，则假定比例因子为 1。
返回一个新的 bounds 对象，用于表示经过指定的位置、旋转和比例变换后，包含原始边界框的轴对齐边界框。
原始 bounds 对象保持不变。
示例：
PTC.Structure.fromId(‘model-1’).then( (structure) => {
var bounds = structure.getBounds(‘/0/6’);
var rotated_bounds = bounds.transform([0,0,0], [45, 0, 0], 1);
}
Structure.Location 对象
Structure.Location 对象表示 3D 空间中的位置，由一个位置（平移偏移）和旋转（方向）组成。
Structure.Location 对象属性
属性
说明
matrix
4x4 变换矩阵，表示以列主序数组代表的位置。
position
location 对象的位置分量，表示为具有属性 x、y 和 z 的对象，以及将这三个值作为数组返回的 'asArray' 方法。
示例：
PTC.Structure.fromId(‘model-1’).then( (structure) => {
var location = structure.getLocation(‘/0/6’);
var pos_X = location.position.x;
}
rotation
location 对象的旋转分量，以 Rotation 对象表示。
示例：
PTC.Structure.fromId(‘model-1’).then( (structure) => {
var location = structure.getLocation(‘/0/6’);
var rot = location.rotation;
}
Structure.Location 对象函数
声明
参数
说明
transform (position, rotation, scale)
• {number[]|string[]|string} position - 所需变换的位置分量，可指定为三个数字构成的数组（[0,0,5]）、表示这些数字的字符串数组（[‘0’,’0’,’5’]），或者以逗号分隔的三个数字构成的单个字符串（‘0,0,5’）
• {number[]|string[]|string} rotation - 所需变换的旋转分量，可指定为三个数字构成的数组（[0,0,5]）、表示这些数字的字符串数组（[‘0’,’0’,’5’]），或者以逗号分隔的三个数字构成的单个字符串（‘0,0,5’）。如果省略，则不应用旋转变换。
• {number[]|string[]|string|number} scale - 所需变换的比例分量，可指定为三个数字构成的数组（[0,0,5]）、表示这些数字的字符串数组（[‘0’,’0’,’5’]）、以逗号分隔的三个数字构成的单个字符串 ‘0,0,5’，或者表示统一缩放因子的单个数字。如果省略，则假定比例因子为 1。
返回一个新的 location 对象，表示经过指定位置、旋转和缩放变换后的原始 location 对象。
原始 location 对象保持不变。
示例：
PTC.Structure.fromId(‘model-1’).then( (structure) => {
var location = structure.getLocation(‘/0/6’);
var moved_location = location.transform([5,0,0], [0, 0, 0], 1);
}
Structure.Rotation 对象属性
Structure.Rotation 对象表示 3D 空间中的旋转或方向。
Structure.Rotation 对象
属性
说明
matrix
3x3 旋转矩阵，表示以列主序数组代表的旋转。
Structure.Rotation 对象函数
声明
参数
说明
asEuler ()
获取 rotation 对象的欧拉表示。这表示为具有属性 x、y 和 z 的对象，以及将这三个值作为数组返回的 asArray 方法。值以度为单位。
示例：
PTC.Structure.fromId(‘model-1’).then( (structure) => {
var location = structure.getLocation(‘/0/6’);
var euler_array = location.rotation.asEuler().asArray();
}
用法示例
// Get the Structure information for model-1
PTC.Structure.fromId('model-1').then ( (structure) => {
// Get the properties of the 'model-1' widget
var widgetProps = $scope.view.wdg['model-1'];

// Get the bounding box information for part '/0/6'
var bbox = structure.getBounds('/0/6');

// Transform the bounding box to account for the 'model-1' widget's location
var xform_bbox = bbox.transform(
[widgetProps.x, widgetProps.y, widgetProps.z],
[widgetProps.rx, widgetProps.ry, widgetProps.rz],
widgetProps.scale);
// Move '3DImage-1' to the center of the bounding box
$scope.view.wdg['3DImage-1'].x = xform_bbox.center.x;
$scope.view.wdg['3DImage-1'].y = xform_bbox.center.y;
$scope.view.wdg['3DImage-1'].z = xform_bbox.center.z;
// Get the location information for part '/0/2/8'
var loc = structure.getLocation('/0/2/8');

// Transform the location to account for the 'model-1' widget's location
var xform_loc = loc.transform(
[widgetProps.x, widgetProps.y, widgetProps.z],
[widgetProps.rx, widgetProps.ry, widgetProps.rz],
widgetProps.scale);

// Get the rotational component as euler angles
var rot = xform_loc.rotation.asEuler();

// Rotate '3DImage-2' to match the rotation
$scope.view.wdg['3DImage-2'].rx = rot.x;
$scope.view.wdg['3DImage-2'].ry = rot.y;
$scope.view.wdg['3DImage-2'].rz = rot.z;
});