#############
Line Patterns
#############

Line patterns give you the ability to customize the lines on nodes.


Setting/unsetting line patterns
===============================

To set a node's line pattern call the :ref:`setNodesLinePattern() <api_ref/viewing/classes/communicator.model:setnodeslinepattern>` function. The first argument to the function is a :ref:`NodeId <api_ref/viewing/modules/Communicator:nodeid>` array, elements of this array are the nodes who will have their line pattern set. The next argument is the :ref:`LinePattern <api_ref/viewing/modules/Communicator:linepattern>` you want to use. A line pattern is an array of 1's or 0's where 1's represent visible pixels and 0's represent invisible pixels. Following the LinePattern argument pass a number that specifies the :ref:`patternLength <api_ref/viewing/classes/Communicator.Model:setnodeslinepattern>` which is the length of a single repetition of the pattern. The final argument to the function is the :doc:`patternLengthUnit </api_ref/viewing/enums/Communicator.LinePatternLengthUnit>` which specifies the unit used to measure the length of the pattern. The code snippet below sets a basic dashed line pattern on nodes selected in the Web Viewer.

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

.. image:: images/line-pattern-comparison.png

*On the right, a basic dashed line pattern has been set.*

.. image:: images/line-pattern-size.png

*Pattern length is 1 on the left and 4 on the right. Both use object space as a unit of measurement.*

To remove a line pattern from a node use the :ref:`unsetNodesLinePattern() <api_ref/viewing/classes/Communicator.Model:unsetnodeslinepattern>` function.

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


Define a style
==============

To customize the appearance of your :ref:`line pattern <api_ref/viewing/modules/Communicator:linepattern>` you can pass a unique array of 1's and 0's as the second argument to :ref:`setNodesLinePattern() <api_ref/viewing/classes/Communicator.Model:setnodeslinepattern>`. Additionally, users can set a line pattern in conjunction with setting :ref:`nodes' line colors <api_ref/viewing/classes/Communicator.Model:setnodeslinecolor>` to further customize their nodes' lines. In the snippet below the selected nodes' lines are set to a red color and are set to follow a pattern described as [1, 1, 1, 1, 0, 0, 1, 0, 0]. This will produce a pattern with a dash followed by a gap, then a dot, then another gap before the pattern repeats itself. The size of the pattern below has been set to 5 using World space as a unit of length measurement.

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

.. image:: images/line-pattern-style.png

A model using the line color and pattern settings from the snippet above.


Limitations
===========

Line patterns limitations concern the :ref:`LinePatternLengthUnit.ProportionOfScreenHeight <api_ref/viewing/enums/Communicator.LinePatternLengthUnit:proportionofscreenheight>` and :ref:`LinePatternLengthUnit.ProportionOfScreenWidth <api_ref/viewing/enums/Communicator.LinePatternLengthUnit:proportionofscreenwidth>` properties.

When using these units to scale your line pattern it will cause the pattern to appear the same regardless of zoom or distance from the camera. Measuring the length for line patterns these ways requires a calculation for each vertex in the line reducing prerformance compared to the other :doc:`LinePatternLengthUnits </api_ref/viewing/enums/Communicator.LinePatternLengthUnit>`.
