導覽 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'。
此函數會傳回來自單一元件的全部字串屬性值，如果沒有可用的資料/元件，則會傳回 undefined。如果給定的 propName 是陣列，則會傳回值的字串 []。
範例：
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 (方位、旋轉、比例)
• {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。
傳回一個新邊界物件，該物件代表軸對齊的邊界外框，且該外框已經過指定的方位、旋轉與比例轉換，並圈住原始邊界外框。
只要執行此操作，原始邊界物件即可維持原樣。
範例：
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
位置的方位元件，以具有屬性 x、y 與 z 的物件表示，並會以「asArray」形式將這三個值以陣列型式傳回。
範例：
PTC.Structure.fromId(‘model-1’).then( (structure) => {
var location = structure.getLocation(‘/0/6’);
var pos_X = location.position.x;
}
rotation
位置的旋轉元件，以旋轉物件表示。
範例：
PTC.Structure.fromId(‘model-1’).then( (structure) => {
var location = structure.getLocation(‘/0/6’);
var rot = location.rotation;
}
Structure.Location 物件函數
宣告
參數
描述
transform (方位、旋轉、比例)
• {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。
傳回代表原始位置已經過指定方位、旋轉及比例轉換的新位置物件。
只要執行此操作，原始位置物件即可維持原樣。
範例：
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 ()
取得旋轉的歐拉數代表。以具有屬性 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;
});