.. currentModule:: Autograph


Using 2D Paths
==============

:class:`Path2DParam` represents a single Cubic Bezier curve in Autograph. 
A :class:`GeomGroup2DParam` contains a list of :class:`Path2DParam`. For each path, a boolean operation can be specified with the :attr:`Geom2DParam.booleanOperation` parameter.

You can retrieve the final composite geometry (also applying any modifier on it) by calling :meth:`Geom2DParam.getGeometry`.

Accessing the GeomGroup2D Param
-------------------------------

The :class:`GeomGroup2DParam` are usually found on the `Shape:Stroke <https://www.left-angle.com/public/doc-autograph/dev-master/chapters/reference/Generators/Image/com_leftangle_AppLib_StrokeShapeGenerator/main.html>`_  and `Shape:Fill&Feather <https://www.left-angle.com/public/doc-autograph/dev-master/chapters/reference/Generators/Image/com_leftangle_AppLib_ShapeFeatherGenerator/main.html>`_ generators.

It can be accessed as any other Param:

.. code-block::

	stroke=Autograph.Effect('Autograph.StrokeShapeGenerator')
	geomGroup=stroke.param('geometry')


Creating new :class:`Path2DParam`
---------------------------------

You can create a new :class:`Path2DParam` and insert it in a :class:`GeomGroup2DParam`


.. code-block::

	stroke=Autograph.Effect('Autograph.StrokeShapeGenerator')
	geomGroup=stroke.param('geometry')

	path=Autograph.Path2DParam()
	path.setDisplayName('My Path')
	geomGroup.addParam(path)


Editing Control points
----------------------

A :class:`Path2DParam` internally stores 2 cubic bezier curves: One for the main contour and one for the *feather* contour.
When you add control points, the *feather* control points are simultaneously added to the path.

Each point added to the list actually adds 3 control points: The Left bezier control point, followed by the Central point (the curve passes by this point), followed by the Right control point.

The following figure explains how control points are connected

.. figure:: img/bezierSegments.jpeg
    :width: 400
    :align: center


.. code-block::

	# Create a rectangle
	path.insertControlPoint(-1, 0., 0.)
	path.insertControlPoint(-1, 0., 100.)
	path.insertControlPoint(-1, 100., 100.)
	path.insertControlPoint(-1, 100., 0.)
	path.closed = True


If the :attr:`Path2DParam.closed` attribute is set to True, the path will be closed.


For convenience, the :meth:`GeomGroup2DParam.setToPath` function can take a :class:`Path2D` and create automatically the corresponding :class:`Path2DParam` . This is easier to do than manually creating the :class:`Path2DParam` and setting control points.


Example
---------

.. code-block::

	project=Autograph.app.getActiveProject()

	# Create a new comp
	comp=project.createComposition()

	# Create a layer
	layer=Autograph.Layer2D()
	comp.addLayer(layer)

	# Create a path
	path=Autograph.Path2D()
	path.addEllipse([0.,0.], 200., 200.)

	# Create a Stroke generator  
	stroke=Autograph.Effect('Autograph.StrokeShapeGenerator')

	# Set the GeomGroup2DParam geometry to the path we created
	stroke.param('geometry').setToPath(path)

	# Set the Stroke as generator of the source of the layer
	layer.source.setGeneratorEffect(stroke)