Model Units

Overview

Most CAD files specify measurement units for geometry contained in the file. In most cases, source systems allow units to be specified at multiple granularities ranging from global units to units for individual parts.

In the HOOPS Communicator API, all model units are specified relative to millimeters. If a source model file contains multiple unit types, they will all be scaled into a common unit type during the model conversion process.

The table below lists common unit types and their associated multiplier.

Unit	Multiplier
point	25.4 / 72.0
inch	25.4
millimeter	1
centimeter	10
pica	25.4 / 6.0
foot	12.0 * 25.4
yard	3.0 * 12.0 * 25.4
meter	1000
kilometer	1000000
mile	1760.0 * 3.0 * 12.0 * 25.4

Working with model units

When performing measurement on models it is desirable to display the measurement value in the part’s native units. In order to compute the correct value, you will need to utilize the Model.getNodeUnitMultiplier() method. Once a node’s multiplier has been retrieved, the value in its native unit type can be determined by dividing the raw value by the multiplier. The multiplier returned by this function can be used to determine a correct text label by cross-referencing the multiplier value with the table above.

In the following code sample, we show a code snippet illustrating the flow of picking a line from a mouse click and computing its length in its native unit. In the listing, we omit error and type checking for brevity.

        const selectionItem = await viewer.view.pickFromPoint(mousePosition, pickConfig);
        const nodeId = selectionItem.getNodeId();
        const unitMultiplier = viewer.model.getNodeUnitMultiplier(nodeId);
        const lineEntity = selectionItem.getLineEntity();
        const lineProperty = (await viewer.model.getEdgeProperty(
            nodeId,
            lineEntity.getLineId(),
        )) as Communicator.SubentityProperties.LineElement;
        const lengthInUnits = lineProperty.length / unitMultiplier;

Multiple units with model aggregation

When the viewer is started, the initial loaded model’s units determine the unit that will be used for subsequent models that are loaded in the scene. The default behavior is that additional loaded models will be scaled to fit the existing scene unit. This behavior can be enabled or disabled using the setEnableAutomaticUnitScaling() method.

For example, using the default behavior, if we start the viewer with a microengine which is defined in millimeters, and then subsequently load a unit cube into the scene, which is defined in inches, we will see the following picture:

The cube, which has been defined in inches appears very large in the scene, because Communicator has scaled the geometry to match scene’s units, which are millimeters. It is also important to note that although the cube is defined in inches, it is being measured now in millimeters.

The scaling behavior can be disabled by passing false to setEnableAutomaticUnitScaling(). In this case, performing the same operations above results in a much different picture:

With automatic scaling disabled, the units authored into the cube model are interpreted as the scene’s unit. Since the microengine was the first model loaded, the scene’s unit is set to millimeters. The effects can be observed in both the size of the cube and its measurement values. The size and measurement values are no longer interpreted as inches.