###########
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 |HCNOW| 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.

.. csv-table::
	:header: "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 :ref:`Model.getNodeUnitMultiplier() <api_ref/viewing/classes/Communicator.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.

.. literalinclude:: /../../applications/client/docs/PG_Units.ts
	   :start-after: //! [units_edge_length]
	   :end-before: //! [units_edge_length]


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 :js:meth:`~Communicator.Model.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:

.. image:: images/model_automatic_unit_scaling.png

The cube, which has been defined in inches appears very large in the scene, because |HCNOW| 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 :js:meth:`~Communicator.Model.setEnableAutomaticUnitScaling`. In this case, performing the same operations above results in a much different picture:

.. image:: images/model_automatic_unit_scaling_false.png

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.
