Navigating Vuforia Studio > Project Pane > Resources > Incorporate 3D Model Structure Bounding Box and Location Data Into an Experience
  
Incorporate 3D Model Structure Bounding Box and Location Data Into an Experience
The PTC.Structure API provides information about the bounding box and location of each part of a 3D Model. You can use this information in an experience to position widgets (3D Image, Label, etc.) relative to a model, or individual parts within a model.
* 
To use this API, the Allow the Experience access to CAD metadata checkbox must be selected when importing a model.
The API consists of function calls to obtain the bounding box and location information, and a set of JavaScript objects used to represent and manipulate this information. To use the PTC.Structure API, you must first call the fromId(…) function, supplying the Id of the 3D Model for which you want to retrieve structure information; this function returns a JavaScript promise.
These APIs are based on promise. For more information on promise, see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise.
For example:
PTC.Structure.fromId(‘model-1’).then( (structure) => {
// Do something with ‘structure’
});
Structure API Functions
Declaration
Parameters
Description
getBounds (idpath)
• {string|string[]} idpath— id path such as '/0/1', or array of id paths ['/0/1', '/0/2'].
• {string|string[]} propName—(Optional) For example, 'Display Name' or ['Display Name', 'Part ID Path']
• {string|string[]} categoryName—(Optional) For example, 'PROE Parameters'.
Gets a metadata object representing the id path or property value(s) for the given idpath and propName.
This function returns the metadata object representing the given idpath, or if propName is given then the value of the property on the component.
Example:
PTC.Metadata.fromId('model-1').then( (metadata) => {
var result = metadata.get('/0/6', 'Display Name')
});
getLocation (idpath)
• {string|string[]} propName—(Optional) For example, 'Display Name' or ['Display Name', 'Part ID Path']
• {string|string[]} categoryName—(Optional) For example, 'PROE Parameters'.
This function returns all string property values from a single component, or undefined if no data/components available. If the given propName was an array, it returns string[] of values.
Example:
PTC.Metadata.fromId('model-1').then( (metadata) => {
var result = metadata.get('/0/1').getProp('Display Name');
});
Structure.Bounds Object
The Structure.Bounds object represents an axis-aligned bounding box (AABB) in 3D Space.
Structure.Bounds Object Properties
Property
Description
min
The minimum extents of the bounding box, expressed as an object with properties x, y and z, and an asArray method which returns these three values as an array.
Example:
PTC.Structure.fromId(‘model-1’).then( (structure) => {
var bounds = structure.getBounds(‘/0/6’);
var min_X = bounds.min.x;
}
max
The maximum extents of the bounding, expressed as an object with properties x, y and z, and an asArray method which returns these three values as an array.
Example:
PTC.Structure.fromId(‘model-1’).then( (structure) => {
var bounds = structure.getBounds(‘/0/6’);
var max_X = bounds.max.x;
}
center
The center-point of the bounding box, expressed as an object with properties x, y and z, and an asArray method which returns these three values as an array.
Example:
PTC.Structure.fromId(‘model-1’).then( (structure) => {
var bounds = structure.getBounds(‘/0/6’);
var center_X = bounds.center.x;
}
corners
An array of the 8 corner points of the bounding box, each expressed as an object with properties x, y and z, and an asArray method which return these three values as an array.
Example:
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 Object Functions
Declaration
Parameters
Description
transform (position, rotation, scale)
• {number[]|string[]|string} position— the positional component of the required transform, provided as an array of three numbers ([0,0,5]), an array of strings representing numbers ([‘0’,’0’,’5’]), or a single string of three numbers separated by commas (‘0,0,5’)
• {number[]|string[]|string} rotation— the rotational component of the required transform, provided as an array of three numbers ([0,0,5]), an array of strings representing numbers ([‘0’,’0’,’5’]), or a single string of three numbers separated by commas (‘0,0,5’). If omitted, no rotational transform is applied.
• {number[]|string[]|string|number} scale— the scale component of the required transform, provided as an array of three numbers ([0,0,5]), an array of strings representing numbers ([‘0’,’0’,’5’]), a single string of three numbers separated by commas (‘0,0,5’), or a single number giving a uniform scale factor. If omitted, a scale factor of 1 is assumed.
Returns a new bounds object representing the axis-align bounding box enclosing the original bounding box, having undergone the specified positional, rotational and scale transformation.
The original bounds object remains unchanged by this operation.
Example:
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 Object
The Structure.Location object represents a location in 3D space, comprising a position (translational offset) and rotation (orientation).
Structure.Location Object Properties
Property
Description
matrix
A 4x4 transformation matrix representing the location expressed as a column-major array.
position
The positional component of the location, expressed as an object with properties x, y and z, and an 'asArray' method which returns these three values as an array.
Example:
PTC.Structure.fromId(‘model-1’).then( (structure) => {
var location = structure.getLocation(‘/0/6’);
var pos_X = location.position.x;
}
rotation
The rotational component of the location, expressed as a rotation object.
Example:
PTC.Structure.fromId(‘model-1’).then( (structure) => {
var location = structure.getLocation(‘/0/6’);
var rot = location.rotation;
}
Structure.Location Object Functions
Declaration
Parameters
Description
transform (position, rotation, scale)
• {number[]|string[]|string} position— the positional component of the required transform, provided as an array of three numbers ([0,0,5]), an array of strings representing numbers ([‘0’,’0’,’5’]), or a single string of three numbers separated by commas (‘0,0,5’)
• {number[]|string[]|string} rotation— the rotational component of the required transform, provided as an array of three numbers ([0,0,5]), an array of strings representing numbers ([‘0’,’0’,’5’]), or a single string of three numbers separated by commas (‘0,0,5’). If omitted, no rotational transform is applied.
• {number[]|string[]|string|number} scale— the scale component of the required transform, provided as an array of three numbers ([0,0,5]), an array of strings representing numbers ([‘0’,’0’,’5’]), a single string of three numbers separated by commas (‘0,0,5’), or a single number giving a uniform scale factor. If omitted, a scale factor of 1 is assumed.
Returns a new location object representing the original location having undergone the specified positional, rotational, and scale transformation.
The original location object remains unchanged by this operation.
Example:
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 Object Properties
The Structure.Rotation object represents a rotation or orientation in 3D space.
Structure.Rotation Object
Property
Description
matrix
A 3x3 rotation matrix representing the rotation expressed as a column-major array.
Structure.Rotation Object Functions
Declaration
Parameters
Description
asEuler ()
Gets the euler representation of the rotation. This is a expressed as an object with properties x, y and z, and an asArray method which returns these three values as an array. The values are in degrees.
Example:
PTC.Structure.fromId(‘model-1’).then( (structure) => {
var location = structure.getLocation(‘/0/6’);
var euler_array = location.rotation.asEuler().asArray();
}
Usage Example
// 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;
});