Freestyle integration into Blender

August 11, 2010

Weekly update July 12-August 11

Filed under: Update — The dev team @ 8:59 AM

Since early June, the dev team has been working on the new Parameter Editor mode that is intended to be an artist-friendly graphical user interface (GUI) for the Freestyle renderer.  A number of new UI elements have been introduced, and most of them are now considered functional.  Although the Parameter Editor mode is still a work in progress, a brief description of the new UI elements would be useful both from branch users’ perspective and for the purpose of GUI design review.

With the aim of organizing a number of stylization parameters in a clean and easy-to-understand form, two new notions of lineset and line style have been introduced. Lineset is a set of selected feature edges that are subsequently chained to create strokes.  Line style is a set of stylization parameters that define the appearance of a lineset.  Each render layer may have an arbitrary number of linesets, each of which is associated with a line style.  Line style is a new data block type in Blender, meaning that a line style is shared by different linesets (like the materials that can be shared by multiple objects).

A lineset accommodates a set of options for selecting feature edges on which you want to draw strokes.  First, you specify the types of selection criteria based on which feature edges are selected.  There are two types of selection criteria: edge visibility and edge types.

  • By edge visibility, you can select all visible edges, all invisible (hidden) edges, or the edges within a range of quantitative invisibility (QI).  It is recalled that the QI of a feature edge is the number of occluding faces between the edge and the camera (i.e., the QI value is integer).
  • Feature edges can also be selected by their types: silhouette, border, crease, ridge, valley, suggestive contour, material boundary, contour, and external contour.  Conditions on edge types can be combined by logical OR and logical AND.  In addition, there are two options named Inclusive and Exclusive.  By enabling the Inclusive option, the feature edges that satisfy the given AND/OR-combined edge type conditions are selected.  With the Exclusive option enabled, the feature edges that do not satisfy the given conditions are selected.

At the moment, there are no options for controlling how to chain selected feature edges to create strokes and how to split strokes into pieces.  New UI elements for chaining and stroke splitting will be added later.  For now, a specific chaining rule is used to convert selected feature edges to strokes.

A line style comprises a number of stylization parameters that define the appearance of strokes to be drawn on the feature edges selected by a lineset.  New UI elements for controlling line color, alpha transparency, and line thickness among many other stylization parameters are available in the Freestyle: Line Style tab.  A line style defines the base line color, base alpha transparency, and base line thickness.  In addition, these base values can be altered by modifiers.  Color, alpha and thickness are independently modified by a list of modifiers as shown below.  Modifiers are processed in the order within a list, namely in such a way that a base value is first modified by modifier #1, then modified by modifier #2, and so on.

Modifiers have two common properties: blend type and influence.  The blend type specifies the way how the modifier changes a base value, whereas the influence (on the interval 0 to 1) determines how much the modifier changes the base value.  An example of blend types is Mix to blend the base value and a new value based on the influence as follows.  Let B be the base value, X be the new value, and F be the influence.  Then, the base value is changed to B(1 – F) + XF.  If F = 1, then B is set equal to X.

As of this writing, there are three modifiers: Along Stroke, Distance from Camera, and Distance from Object.  These modifiers are all available as color modifiers, alpha modifiers, and thickness modifiers.

Along Stroke modifiers alter a base value (i.e., color, alpha, or thickness) by a new value that is defined along a stroke.  Suppose that a point moves along the stroke from the beginning to the end, and the location of the point is expressed by parameter T on the interval 0 to 1.  The Along Stroke modifiers yield a new value based on the T value.  The Along Stroke color modifier has a color ramp which is used to translate the T value to a new color, as illustrated in the figure below:

Both the Along Stroke alpha and thickness modifiers have a mapping that translates T to a new alpha/thickness value.  The mapping is either linear or curve.  The linear mapping is used for linear fade-out (see panel (a) in the figure below).  The linear mapping has the “invert” option for linear fade-in (see panel (b)).  The curve mapping allows you to specify a non-linear variation of new alpha/thickness values (see panel (c)).

The Along Stroke thickness modifier also has the Value Min and Value Max options that specify the range of the new thickness values.

Using all the Along Stroke color, alpha and thickness modifiers (with the curve mappings enabled for the latter two) gives the following render.

Distance from Camera modifiers change a base value by a new value that is determined based on the distance from the camera to a point lying on a stroke.  The distance is measured in the three-dimensional space and is expressed by parameter T on the interval 0 to 1.  The Distance from Camera color, alpha and thickness modifiers commonly have the Range Min and Range Max options.  When the distance from the camera to the point is equal to or less than the Range Min, the parameter T takes the value zero.  The T value approaches to one as the distance gets close to the Range Max.  The parameter T takes the value one if the distance is equal to or greater than the Range Max.

The Distance from Camera color modifier has a color ramp option for translating the T value to a new color, which is then blended with the base color (see panel (a) in the figure below).  The Distance from Camera alpha and thickness modifiers commonly have a mapping (either linear or curve) to translate T to a new alpha/thickness value (see panels (b) and (c)).  The Distance from Camera thickness modifier also has the Value Min and Value Max options to define the range of new thickness values.

Enabling all the three Distance from Camera modifiers above results in the following render:

Distance from Object modifiers are similar to the Distance from Camera modifiers, and the difference is that the distance is measured from a specified object (more specifically, from the center point of the object) instead of the camera.  Distance from Object modifiers have all options the Distance from Camera modifiers have, plus an entry to specify an object from which the distance to a point lying on a stroke is measured.

Enabling all the three Distance from Object modifiers above gives the following render:

That’s all for now.  More updates to the Parameter Editor mode are anticipated in the next weeks.  Feedback of any kind concerning the design and implementation of the Parameter Editor mode is much appreciated.


  1. Be sure that this great GUI will considerably help the adoption of Freestyle. Congratulation for your results!

    Comment by Steren — August 11, 2010 @ 9:19 AM

  2. Now I’m starting to get interested in Freestyle! The last time I tried it it wasn’t artist friendly enough for me (you could only select predefined py-styles).
    Is this already in the branch so I can test those parameters?

    Comment by Andreas Galster — August 11, 2010 @ 9:35 AM

  3. Excellent explanations of the different options, I only have one question: Is the distance from object measured in 3d space or 2d space? (And is it to the center point or to nearest point?)

    Comment by yoff — August 11, 2010 @ 12:23 PM

  4. Andreas,
    Yes, the Parameter Editor mode is already in the branch and usable by end users.

    Good point. The distance is measured in the three-dimensional space and from the center point of an object. I have just revised the text to clarify your questions. Thanks!

    Comment by The dev team — August 11, 2010 @ 12:54 PM

  5. This it!
    right direction!

    Comment by TUNGEE — August 11, 2010 @ 1:08 PM

  6. Very, very, VERY impressive. I have not dreamed that Freestyle would go so far when I first found it. I am not good with Blender, but damn, maybe when tools are so user-friendly it is time to learn?

    Comment by Barts — August 11, 2010 @ 1:34 PM

  7. I just want to thank the the dev team for all of its hard work. Freestyle in Blender will be an exceptionally useful tool. The Parameter Editor looks great! Also, thank you for the great explanations.

    Comment by Nestor — August 11, 2010 @ 2:40 PM

  8. TK: Great descriptions! This will be a great starting place for getting familiar with the GUI elements! Seems pretty powerful already with just these controls… Thank you sooooo much for this effort!

    Comment by mzungu — August 11, 2010 @ 4:25 PM

  9. wow, looking good :)

    Comment by RH2 — August 11, 2010 @ 4:54 PM

  10. Hello, I’ve been looking at Freestyle for a while, and trying to figure out how it incorporates into Blender. I stumbled across this blog, and it looks like an official source for the project…

    I’ve hunted around, though, and can’t seem to find a website for the latest build of the Freestyle branch, though I see it referred to in multiple places. Am I missing something?

    Comment by Andy — August 11, 2010 @ 8:47 PM

  11. Andy, you can find the builds at :-)
    TK, I think the distance to camera could only really make sense as a 3d distance (unless you think of the 2d distance to center of canvas), so the 3d distance should probably be specified under “distance to object”. But it is not actually confusing… :-)

    Comment by yoff — August 12, 2010 @ 12:15 PM

  12. TK, awesome job, in blenderartist thread I posted a couple of renders were I tested and the results are really nice. Distance from object is very cool! But can’t get material boundary to work :\

    Also I tried rendering an old animation file I had and it renders with no problem still pictures, but after the an image is rendered, blender becomes unstable and crashes quickly, when rendering the animation, it manages to render a few frames but crashes too. I stripped down the file of several animation features I used in it (softbody, uv projection) but can’t find what is crashing it, I put a link to the file if you want to test it out (it’s ready to render the animation). I used revision 31026 in windows xp.

    Comment by Cloud_GL — August 12, 2010 @ 10:54 PM

  13. Wow…. I’m speechless. I assumed freestyle would be beyond me to use, but…. I can use this:) Thank you SOOOOOOOOOOOO MUCH! I agree with your gui and love it!

    Comment by nrk — August 14, 2010 @ 3:15 AM

  14. Thank you all for the positive feedback!

    Thanks for the problem reports. I have retrieved the blend file you kindly provided and am looking into the crash. I am also going to see what is wrong with respect to material boundaries. If the latter issue can be reproduced in some way, that would be much helpful for bug hunting.

    Comment by The dev team — August 14, 2010 @ 1:26 PM

    • Thanks for the answer, I uploaded a file in the thread where I tried to make appear the material boundary line, but it doesn’t, not sure if I’m doing it wrong, but it just doesn’t appear whatever combination I do.

      Comment by Cloud_GL — August 14, 2010 @ 4:22 PM

  15. I could not find your build. when i download freestyle latest, I get those module script loading builds.
    I am looking for win32

    Comment by Karan — August 29, 2010 @ 4:25 PM

  16. I must say this is really cool. Very intuitive!

    Comment by Karlis — September 10, 2010 @ 7:45 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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s

Blog at

%d bloggers like this: