Working With Units


How Units are Expressed

Units are expressed as a multiple of millimeters. For example, an inch unit will be expressed as 25.4, a meter unit as 1000, and a millimeter unit as 1.

You can get the unit value by calling the Model::getUnitMultiplier() method on the model object.

You can also use Util::formatWithUnit() to convert your measurement value to a formatted string.

Here's an example using the command line in a browser console, with "hwv" representing the Communicator.WebViewer object:

Unit Authoring

Using the AssemblyTree lib you can specify the unit when creating a node with the setNodeUnit() method.

If the unit value changes from one node to another it is your responsibility to scale the scene accordingly. For example, assuming your root node is defined in millimeters and you create a subnode defined as inches, then you'll have to set a scale matrix, so that your inch object fits into the millimeter scene.

More generally speaking, the unit set on the root node is the unit that will be used for measurement. For instance, if you're importing from a CAD format where the assembly is defined in meters and you then import a cube in inches and another in centimeters, you will always do your measurement in the unit defined on the root node (in this case, meters).

Unit information is also serialized into the XML:

<ProductOccurence Id="0" Name="Cube" Behaviour="1" Children="1" Unit="25.400000"/>

Building a Scene with Mixed Units

Suppose we've defined a cube using inches. If we load this model into the WebViewer and measure it, we get the following results:

The length of the edge of the cube is 3.35 inches (85 millimeters)

Now we restart and load a scene in millimeters.

We then load the cube into this existing scene:

const model = hwv.model
const newNode = model.createNode(null, "Cube")
model.loadSubtreeFromModel(newNode, "cube")

The cube, which is defined in inches, will then be measured in millimeters because it gets imported in millimeters. In this case, Communicator will automatically scale the imported object to make it fit to the existing scene unit.

In some cases you might not want the object to automatically scale to fit the unit of the existing scene. This can be turned off by calling the setEnableAutomaticUnitScaling() method of the Model object:

hwv.model.loadSubtreeFromModel(newNode, "cube")

In this case the cube won't be rescaled to fit millimeter units and will be a lot smaller relative to the other object in the scene:

top_level:2 prog_guide:1 data_import:1