Freestyle integration into Blender

August 5, 2012

Development updates on August 5

Filed under: Update — The dev team @ 11:40 AM

Since the last blog update, the Freestyle branch made a slow but steady progress.  Here is a brief summary of new elements and user-visible changes in the Freestyle rendering engine and its user interface.

General usability improvements

1. New options for specifying unit line thickness has been added in the Post Processing tab in the Render buttons.  These options allow you to define unit line thickness in two different modes:

  • Absolute mode: The unit line thickness is given by a user-specified number in units of pixels.  The default value is 1.
  • Relative mode: The unit line thickness is scaled by the proportion of the present vertical image resolution to 480 pixels.  For instance, the unit line thickness is 1 with the image height set to 480, 1.5 with 720, and 2 with 960.

2. A long-standing bug due to an inappropriate removal of singular points in stroke creation was fixed.

The previous stroke creation procedure was trying to clean stroke topology by removing overlapping stroke vertices in the same 2D location.  The idea was to avoid having to address this kind of singularity during subsequent stroke shading.  In-depth analyses revealed, however, that this was a wrong way to ensure clean stroke topology, since just deleting overlapping vertices may break the continuity of the underlying series of FEdges on top of which the stroke has been built.  Such a break of linked FEdges was a major cause of frequent failure in CurvePoint::getFEdge().

The implemented solution aims to address the singularity issue by adding small offsets to the 2D location of overlapping vertices and making them non-overlapping to each other.  Since the offsets only result in sub-pixel differences, the impact on visual outcomes is expected to be negligible.

In addition, an attempt was made to fix an instability issue in stroke rendering due to a failure of Normal2DF0D with smooth FEdges.  The fix is to avoid generating new FEdgeSmooth instances whose length is shorter than epsilon.

3. The response of the ESC key for stopping Freestyle rendering has been improved throughout the rendering process.  The rendering with Freestyle consists of several steps including: (1) mesh data loading, (2) winged edge construction, (3) silhouette edge detection, (4) view map construction, and (5) stroke drawing.  All these steps have been extended to frequently check if the ESC key is pressed, so that users can abort time-consuming rendering at any point of time.

4. New operators have been introduced for adding the data paths to Freestyle edge/face mark properties of selected edges/polygons into the active keying set.  These operators are intended to make it easy to keyframe a number of Freestyle edge/face marks.

  • Add Edge Marks to Keying Set (bpy.ops.scene.freestyle_add_edge_marks_to_keying_set)
  • Add Face Marks to Keying Set (bpy.ops.scene.freestyle_add_face_marks_to_keying_set)

These operators are accessible from the Space bar menu by entering the operator names, as illustrated in the following screen captures.


5. The lower limit of Kr derivative epsilon has been changed from 0 to -1000 so as to permit a negative value.

New elements in the Parameter Editor mode

1. New options for controlling the position of stroke thickness have been introduced.  These options enable a better control on the position of stroke thickness with respect to stroke backbone geometry.  Three predefined positions are:

  • center: thickness is evenly split to the left and right side of the stroke geometry.
  • inside: strokes are drawn within object boundary.
  • outside: strokes are drawn outside the object boundary.

Another option called “relative” allows you to specify the relative position by a number between 0 (inside) and 1 (outside).

The following renders show the effects of the three predefined positions.


The following render is an example of the relative position with the thickness ratio set to 0.3.

The thickness position options are applied only to strokes of the edge types SILHOUETTE and BORDER, since these are the only edge types defined in terms of object boundary.  Strokes of other edge types are always drawn using the “center” option.

The thickness position options are also applied only when chaining is disabled or the Plain chaining is used with the Same Object option enabled (as shown below).  The default “center” positioning is used otherwise.

2. Sphere radius and Kr derivative epsilon have been recovered in the Parameter Editor mode.  Several users requested the recovery as the removal of the two parameters was considered over-simplification for advanced users (see the blog article on April 2 for the rationale of the removal).  As in the Python Scripting mode, the two parameters are in the “advanced edge detection options” section and disabled by default.

Bug fixes

  • Fix for Freestyle-related UI components showing up in the Render buttons when Cycles was selected.
  • Fix for NaN (not a number) in the Z component of projected points.  This issue arose when the Z depth of the bounding box of the scene being rendered is zero.
  • Fix for emitted objects of a particle system not rendered properly.  The problem was reported by octane98 with a sample .blend file.  Thanks!
  • Fix for the WithinImageBorderUP1D predicate not working with a ViewEdge such that none of the SVertices are within the image boundary but an FEdge intersects with the image boundary.
  • Fix for X and Y aspect ratios not working properly with Freestyle stroke rendering.  The problem was reported by octane98 through the BA Freestyle thread.  Thanks!
  • Fix for the Selection by Group not working correctly when the specified group was empty. The problem was reported by vicentecarro with an example .blend file to reproduce the issue.  Thanks!
  • Fix for a crash due to a corruption of data for addressing degenerate triangles in imported mesh data.
  • Fix for a crash in the single layer mode with Freestyle enabled.

Freestyle user activities

Freestyle branch users are active and keep sharing their results and new ideas through the, personal blogs, and so on.  Recently mclelun has started new project “the Overweight Boss” using Blender and Freestyle.  Here is a couple of excellent results from him.  The dev team is very grateful for his achievement! is a new hub site for gathering information about non-photorealistic (NPR) rendering with Blender.  Freestyle tips and results are part of the new site’s main topics.  In addition, a new discussion thread has been open for collecting feature requests, new ideas and thoughts to improve Freestyle.  If you have something that you want to see in Freestyle in the future, you are definitely encouraged to post it in this discussion thread.



  1. I know it’s been a while since this has been published, but I would like to say: good job! Thank you for your continued efforts in creating Freestyle.

    Can I ask what are the plans concerning integrating it into the main branch of Blender? Are there any timelines?

    Comment by barts706 — September 5, 2012 @ 2:31 PM

    • Thanks for your continued interest in the Freestyle integration.

      In short, the present plan is to get the integration project ready for code review by core developers.
      Several rounds of code reviews are expected. After that a date for the merge is set.

      Specifically, a status report of the integration project was sent to the bf-committers mailing list in May.
      Ton suggested focusing on functionality evaluation instead of specific implementation details.
      To facilitate the evaluation process, a brief description of key components and their functionalities was also sent to the list.
      The difference between the trunk and the Freestyle branch at that time was quickly reviewed by several developers.
      Campbell pointed out that more work is necessary on the Freestyle Python API.
      Dan discussed the possibility to auto-generate the Python API from the underlying C/C++ code base.
      Thomas, Tom and Vicente expressed their favorable opinions on the merge even at this stage of development.

      The aforementioned plan was then discussed in a weekend meeting.

      That’s it for now. Hope this answers to your questions.

      Comment by The dev team — September 6, 2012 @ 6:45 PM

      • Excellent, I am glad to hear that. I don’t see Freestyle in recent 2.64 RC, but it’s great that A) you are continuously making progress on Freestyle and B) the vision of getting Freestyle integrated with Blender is at last starting to loom on the horizon.

        Keep up the good work!

        Comment by barts706 — October 3, 2012 @ 11:24 AM

  2. Woah, woah, woah! I just re-read this. Is my interpretation of 4. correct that it is possible to keyframe edge marking?!?!? That’s huge, if true!

    Comment by Rudiger — September 11, 2012 @ 4:01 AM

    • Yes, you are right. The functionality in No. 4 is meant to allow you to keyframe edge marks (:

      Comment by The dev team — September 12, 2012 @ 6:12 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: