Freestyle integration into Blender

February 27, 2011

Development updates on February 26

Filed under: Update — The dev team @ 12:39 AM

During the last two months both this blog and the integration work were quiet mainly due to very limited time resources.  However, all the changes in the trunk have been merged into the Freestyle branch on a weekly basis.  In addition, a few problems that affected many branch users have been addressed as summarized below.

1. Fixes for unexpected long straight lines

First, the issue of occasional unexpected long straight lines has been partially addressed.  Branch users may encounter this issue when a number of frames for animation is rendered.  A typical situation is that a few frames (e.g., one or two out of a hundred frames) suffer from weird long straight lines that are not in the scene data.  An example of such a long straight line is shown in the image below.  This problem is mostly due to a known bug in stroke mesh generation.  The bug is that quick U-turns in stroke topology are not handled properly.  A fix for this bug is planned as part of a comprehensive improvement of stroke mesh generation described in a blog post in last September.  As a quick remedy for now, the Parameter Editor mode has been extended so as to prevent strokes from doing quick U-turns.

Branch users writing custom style modules may be interested in the way how the fix is implemented.  Take a look at AngleLargerThanBP1D() in scripts/freestyle/style_modules/  This predicate is used with ChainPredicateIterator() to allow two consecutive edges to be chained only when the angle of the two edges is larger than a given threshold.

In the meantime, another issue was identified as a source of unexpected long straight lines.  This issue arose when stroke thickness was specified by a curve mapping of a thickness modifier in the Parameter Editor mode.  In some occasions the curve mapping resulted in extrapolation, which gave an extremely large thickness value.  Now the extrapolation option is unconditionally disabled to prevent this issue, even when users turn on the option through the GUI.

2. Consolidation of stroke drawing

Second, consolidation of stroke drawing has been made through several related bug fixes.  After the introduction of face smoothness in last November, branch users may have seen a warning message shown below in the middle of stroke drawing:

Warning: you should not be there…

This warning turned out to be due to those edges in the view map that have a two-dimensional length almost or exactly equal to zero.  When such a zero-length edge was in a chain of edges on which a stroke was drawn, a number of style module API functions such as MaterialF0D() failed.  In addition, MaterialF0D() had another bug that an error condition was ignored due to a wrong return value.  In the end, these bugs jointly caused stroke color to be left undefined.

This stroke drawing instability has been addressed by automatically removing the zero-length edges (and chains of them) before stroke drawing begins and after stroke splitting is performed (e.g., using Operators.sequentialSplit()).  The bug in MaterialF0D was also fixed.

Moreover, possible memory leaks due to errors in user-defined style modules have been fixed.  Since scripting errors during style module coding are inevitable, these fixes improve the stability of the program regardless of having temporary programming errors in user-defined predicates, chaining iterators, and shaders.



  1. solid update, thanks!

    Comment by ike ahloe — February 27, 2011 @ 7:51 AM

  2. Awesome work on Freestyle!

    Does Freestyle have an open Wiki somewhere? A place to create tutorials & post scripts. Or a repository to upload & download Style Modules. If not, one might prove helpful.

    Comment by Camp — February 27, 2011 @ 4:54 PM

  3. Thank you guys for the comments!

    The idea of having a site for sharing knowledge and user experience pops up once in a while, but so far there are no wiki and style module repository. If you are interested in building and maintaining such a community site, please feel free to do so ;-)

    Comment by The dev team — February 28, 2011 @ 9:47 PM

  4. Astounding work on the freestyle integration 8-)

    Not sure where to report this (is there a tracker for the freestyle code?)
    I think the “Crease Angle” setting might not be calculated correctly … or I’m mixing something up.
    If I compare it to the edge split modifier or to the “select sharp edges” command it gives me different edges (I know that I need to subtract the value from 180° to get the matching value).

    Also: wouldn’t it be a good idea to add
    “Edges marked as sharp”
    “Edges marked as seam”
    “Edges with crease value set to XXX or higher”
    to the “Selection by edge types” options?

    Comment by mbue — March 1, 2011 @ 10:06 PM

  5. mbue,
    Thank you for the suggestions of a nice test for crease angle, as well as of edge selection options.
    There is no tracker for the Freestyle integration project. Please post reports here or to the Freestyle thread at

    Concerning the crease angle, let us consider two faces sharing an edge. Suppose that the angle between the two faces is 135 degrees.

    In Freestyle, the edge is considered as crease when the angle between two faces sharing the edge is smaller than the threshold.
    So, if you want to select the edge as crease, you put an angular threshold slightly more than 135 degrees (e.g., 135.1 degrees).

    Apparently, the Edge Split modifier splits edges depending on the angle between the face normals of two faces.
    In the case of our example, the angle between the face normals is 45 degrees.
    Therefore, the edge is split if you specify an angular threshold slightly less than 45 degrees (e.g., 44.9 degrees).

    As far as I tested, both worked as described above. If you find inconsistency, please let me know how to reproduce it.

    For what concerns the edge selection options you suggested, the first two are difficult to implement, because
    all that the Freestyle renderer receives from Blender is a bunch of tris and quads (generated by applying all
    mesh modifiers). The data do not include any information about edge marks. Supporting the suggested two options
    will require a significant extension of the Blender internal renderer. The last option, on the other hand, is
    much easier to implement. I would add it to the list of edge selection options if time permits.


    Comment by The dev team — March 2, 2011 @ 12:48 AM

  6. Thanks for your reply.
    A tracker would be pretty handy though ;-)

    Angles – so to sum it up:
    Freestyle: 180°=flat
    Edge-Split: 0°=flat
    Unless my brain is playing tricks on me again.

    I that’s correct this would mean that 160° in Freestyle would be 20° in Edge-Split.
    I’ve attached a link to a test file and rendering of the “inconsistence” I mean:
    I hope the image makes it clear what I mean?

    New options … So Freestyle does not receive these settings? That’s a shame.
    I’m not sure I explained what I meant with the 3. option well.
    It’s the crease value you can set via the [Shift]+[E] (“Edge Crease”) shortcut in Blender.
    I assume this is stored similar to the first 2 settings?
    If not that would be cool … and the only way to manually define lines :-)


    Comment by mbue — March 2, 2011 @ 6:40 PM

  7. Forgot to add this in the last post:
    I could increase the Freestyle Crease Angle up to 179.9 and not get the two lines to show up (the ones that are marked in red)

    Kinda nit-picky, but adding a simple flat mesh doesn’t create any “Silhouette” lines/edges.
    (e.g. the red circles in the test file, but adding a simple plane does the same).

    Comment by mbue — March 2, 2011 @ 9:27 PM

  8. mbue,
    With the test .blend file and render, everything is now very clear, thanks!

    First, I need to correct my description of the crease angle in Freestyle.
    From a user’s perspective, the crease angle works as an angle between two faces, only when the faces are flat.
    Internally, crease edges are detected based on vertex normals.
    This means that crease edges may be detected or not depending on face smoothness (i.e., flat face or smooth face).
    Consider two faces A and B sharing an edge. Let V be one of two vertices of the edge.
    When A and B are flat, V has at least two vertex normals.
    One vertex normal is equal to the face normal of A, and another equal to the face normal of B.
    These two vertex normals are used for crease angle detection (in the same way as the Edge Split modifier).
    When A and B are smooth across the edge, V has only one vertex normal.
    Therefore, the edge will never be considered as crease.

    You have enabled the Face Smoothness option in the test .blend file.
    With this option enabled, the feature edge detection takes face smoothness into account.
    In this case, the edges in question (highlighted by the red circles in the .blend file) won’t be detected as crease,
    because they lie between smooth faces.
    Try to turn off the Face Smoothness option, and you will get the highlighted edges detected as crease.

    In summary, the crease angle in Freestyle and sharp edges in Blender are complementary.
    If you want to have crease edges in a smooth mesh, you need to use both functionalities when you turn on the Face Smoothness option.
    I hope all this explanation makes sense.

    Concerning the third edge detection option (i.e., “Edges with crease value set to XXX or higher”),
    I was missing the Edge Crease functionality ([Shift]+[E]).
    This attribute as well as the other edge marks are not available in the data Freestyle receives from Blender.
    Supporting these types of edge information in Freestyle is not a trivial task.
    Another related idea for edge selection is to expose vertex groups to Freestyle.
    This way you have a very fine control on feature edge selection.
    Vertex weights would also be useful for controlling stroke appearance such as color and thickness.
    I hope I will be able to implement these new features in the future.

    Comment by The dev team — March 3, 2011 @ 12:34 AM

  9. Yes, it makes sense to me now.
    I’ll test the Face Smoothness setting ASAP – I didn’t see/test this for some reason :-)

    BTW: Another way to quickly set edges to render as lines (especially for technical stuff) …
    Mark edges as “Sharp” in the mesh and apply an EdgeSplit modifier with only “[x] Sharp Edges” activated.
    Problem is that this is per-object and possibly has other limitations.

    Many thanks for your response,

    Comment by mbue — March 3, 2011 @ 7:29 AM

  10. Is there some recent freestyle tutorial? I have tried all Freestyle modules and various parameter settings and all I’ve managed do get is contours without inner lines :(

    Comment by damir — March 7, 2011 @ 12:34 PM

  11. @The dev team:
    Disabling the “Smoothness” option worked perfectly, thank you for your help :-)

    I’ve updated my technical test file with some more examples (most of them work perfectly).

    2 open “issues” still visible here:
    * Completely flat shapes (tested meshes and fonts) do not cause “Silhouette” lines to be drawn (as mentioned previously).
    * Fonts (esp. extruded ones) do not seem to be handled the same as normal meshes?

    For some reason I often get crashes in the line-rendering part.
    The error itself is a memory access error, it often happens to me when rendering the technical2.blend file.
    The problem is that I could not yet debug it since it locks up my X Server and/or input stuff.
    It’s a PITA since that means I can’t run it with gdb at all without locking up my complete system. Not even changing to a virtual console works :-(

    @damir: Didn’t see one, but digging through some of the older entries in this blog might help.
    If you need technical line-drawings I can help you set _that_ up step-by-step though.
    If it’s organic/artistic stuff I’m no wiser than you :-)


    Comment by mbue — March 7, 2011 @ 7:00 PM

  12. I’m VERY thankful for the straight line bug being fixed, appreciated. And I’m also glad to hear the smoothed faces error is gone(and its root cause), nice work. Cant wait to see how freestyle continues to develop thanks to your talent & hard work.

    I’d like to add my own personal +1 for exposing (selected/chosen)vertex groups to Freestyle; that would open MANY possibilities.

    Comment by Blenderificus — March 12, 2011 @ 11:46 AM

  13. mbue,
    For extruded fonts and flat shapes, you get proper strokes with the “Border” option enabled in the “Selection by Edge Types”.
    I have no idea about the reason(s) why the line drawing stage of rendering technical2.blend locks up the operating system…
    I am going to try to reproduce the problem on my side.

    Comment by The dev team — March 13, 2011 @ 12:38 PM

  14. The dev team:
    That works fine for the outline, unfortunately it also seem to screw up the drawing of circles and circle-mesh based shapes.

    See this image (marked in green):

    Comment by mbue — March 13, 2011 @ 7:13 PM

  15. Forgot to mark this in the image, but you can also see it in the head of the screw in the middle.

    Comment by mbue — March 13, 2011 @ 7:20 PM

  16. mbue,
    The red circle meshes and gray filled circle mesh have irregular face normals.
    Try to “Recalculate Outside” (Ctrl-N in the edit mode), and you will get clean strokes.
    The straight line in the head of the screw in the middle will disappear by applying “Remove Doubles”.
    There are lots of vertices at the center of the head.
    Freestyle is very sensitive to this kind of mesh topology, often leading to unexpected line drawing results.

    Comment by The dev team — March 13, 2011 @ 10:21 PM

  17. Ah, that sounds like it would cause problems.
    I didn’t check the geometry (especially the one of the circle), so I’m blaming myself here ;-)
    I’ll update the .blend file at some point so this doesn’t happen again.

    Comment by mbue — March 13, 2011 @ 10:51 PM

RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

Blog at

%d bloggers like this: