###########
Measurement
###########

How to measure a model
======================

There are two ways to measure a model. We can measure with the triangulated data, or for models that contain BREP data, we can measure using the data that is embedded when the model is converted. Using the BREP data will give us a more accurate measurement. This will work for faces and edges, however for point to point measurement, we will have to use the triangulated data. 

The subentity properties for a face or edge can be retrieved using the :ref:`getFaceProperty <api_ref/viewing/classes/Communicator.Model:getfaceproperty>` and 
:ref:`getEdgeProperty <api_ref/viewing/classes/Communicator.Model:getedgeproperty>` functions. 

The subentity properties contains measurement data for the corresponding face or line. Each property object corresponds to the type of edge or line, and the measurement properties that can be accessed will differ accordingly. 

For example, a ``LineElement``, which corresponds to a Line edge type, will have a length property. Some face or edge types may have properties that are the same. For example, a ``CircleElement``, ``CylinderElement``, and ``ConeElement``, will all have radius, origin, and normal properties.

To see all the subentity property types, please refer to the docs :doc:`here  </api_ref/viewing/modules/communicator.subentityproperties>`

When measuring, it is important to take into account the unit scale. The unit scale is a number that represents the size of the unit. A model measured in inches would have a unit scale of 25.4. 

All measurements values are in millimeters. To get inches, divide by the unit scale of 25.4. For example, when measuring the length of an edge, a value of 50.8 represents 2 inches.

For more information on unit scaling, see the :doc:`Model Units Programming Guide </prog_guide/viewing/data_model/model-units>`.	


Edge / face / point measure
===========================

|HCNOW| has native four measurement operators:

:doc:`MeasureEdgeLengthOperator  </api_ref/viewing/classes/Communicator.Operator.MeasureEdgeLengthOperator>` - Measures the length of edges. For circles, measures the radius.
:doc:`MeasureFaceFaceAngleOperator  </api_ref/viewing/classes/Communicator.Operator.MeasureFaceFaceAngleOperator>` - Measures the angles between two faces.
:doc:`MeasureFaceFaceDistanceOperator  </api_ref/viewing/classes/Communicator.Operator.MeasureFaceFaceDistanceOperator>` - Measures the distance between two faces.
:doc:`MeasurePointPointDistanceOperator  </api_ref/viewing/classes/Communicator.Operator.MeasurePointPointDistanceOperator>` - Measures the distance between two points.


How to insert 2D and 3D text
============================

3D text can be inserted by creating a texture. [See the text_insertion example]
2D text can be inserted by creating a markup item with a text shape. 

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

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


Measure operator
================

In the following sample operator, we select a node, and fetch its subentity properties. In this case, we use the markup item above to add a text box with the length of an edge, or radius of a cylinder.

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


Callbacks
=========

The following callbacks are used to detect when measurement values are created and deleted, or modified.

* :ref:`measurementBegin  <api_ref/viewing/interfaces/Communicator.CallbackMap:measurementbegin>`
* :ref:`measurementCreated <api_ref/viewing/interfaces/Communicator.CallbackMap:measurementcreated>`
* :ref:`measurementDeleted <api_ref/viewing/interfaces/Communicator.CallbackMap:measurementdeleted>`
* :ref:`measurementHidden  <api_ref/viewing/interfaces/Communicator.CallbackMap:measurementhidden>`
* :ref:`measurementLoaded  <api_ref/viewing/interfaces/Communicator.CallbackMap:measurementloaded>`
* :ref:`measurementShown <api_ref/viewing/interfaces/Communicator.CallbackMap:measurementshown>`
* :ref:`measurementValueSet  <api_ref/viewing/interfaces/Communicator.CallbackMap:measurementvalueset>`
