.. _blender_freestyle:

Freestyle tricks
================

.. contents:: Table of contents
   :local:
   :backlinks: none


Setting up freestyle in a script
--------------------------------

Freestyle is not enabled by default in Blender. Here is an example snippet of code to
enable it and to set some basic options that are particularly suited to the curve
example below.

.. literalinclude:: ../../../../../examples/blender/docs/freestylify.py
   :language: python
   :start-after: [freestyle settings setup]
   :end-before: [freestyle settings setup]

Some relevant blender documentation pages to look for more options are
`bpy.types.FreestyleSettings <https://docs.blender.org/api/current/bpy.types.FreestyleSettings.html>`_,
`bpy.types.FreestyleLineSet <https://docs.blender.org/api/current/bpy.types.FreestyleLineSet.html>`_
and
`bpy.types.FreestyleLineStyle <https://docs.blender.org/api/current/bpy.types.FreestyleLineStyle.html>`_.

Of course you can also play with all of this in the Blender GUI, in the `Render
Properties` and `View Layer Properties` panels.


Enabling freestyle for curves
-----------------------------

One of Blender's many quirks is that freestyle does not work for curves or edges of a
mesh which do not belong to a large enough face. But we can trick blender by creating
tiny faces and marking one of the two edges as freestyle. This is what the function
:py:func:`ddg.blender.freestyle.freestylify_curve` does:

.. autofunction:: ddg.blender.freestyle.freestylify_curve
   :noindex:

The function can handle both polygonal curves and 1D mesh objects. Here are two
functions that can set up examples for either case for you:

.. literalinclude:: ../../../../../examples/blender/docs/freestylify.py
   :language: python
   :pyobject: curve_example

.. literalinclude:: ../../../../../examples/blender/docs/freestylify.py
   :language: python
   :pyobject: mesh_example

.. note::
   When generating blender object for curves, we have set `curve_properties={}`. Having 
   a curve blender object with any sort of properties will generate freestyle borders for
   a tube instead!

The following code will then enable freestyle on the edges of the curve and hide the
original curve in the render. You might or might not want to hide the original curve,
depending on your situation.

.. literalinclude:: ../../../../../examples/blender/docs/freestylify.py
   :language: python
   :start-after: [main]
   :end-before: [main]

Now we can do a little bit of camera and light setup:

.. literalinclude:: ../../../../../examples/blender/docs/freestylify.py
   :language: python
   :start-after: [camera and light]
   :end-before: [camera and light]

and we end up with these pictures for the curve and mesh examples:

.. image:: freestylify_curve.png

.. image:: freestylify_mesh.png


Exporting freestyle edges as SVG
--------------------------------

Check out the `Freestye SVG Exporter plugin <https://docs.blender.org/manual/en/4.0/addons/render/render_freestyle_svg.html>`_.
Everything is explained there.