From BlenderWiki

Jump to: navigation, search

Blender 2.67: Freestyle Line Rendering Engine

Freestyle is a new non-photorealistic (NPR) rendering engine integrated into Blender. Originally developed as a stand-alone program in an academic research project, Freestyle provides artists with a new tool set for generating 2D line drawing out of a given 3D scene prepared with Blender. Generated lines can be stylized by a variety of stylization options for tweaking line color, alpha transparency, line thickness, and line geometry. The resulting line art can be combined with other render components (e.g., render passes from the Blender Internal renderer and Cycles) through render layers and the compositor. Examples of Freestyle use cases include cartoon rendering, architectural visualization, technical drawing, blue prints, and computer-generated sketches. Freestyle expands Blender's rendering capabilities on the basis of geometry-based visualization solutions specifically geared to 2D-like computer graphics.

By mato.sus304. CC BY-SA
By Rylan Wright (RONIN). CC BY (
By Rylan Wright (RONIN). CC BY

Geometry-Based Line Art Generation

Freestyle generates 2D line drawing from a set of mesh objects. Mesh vertices, edges and faces are used to identify feature edges of interest to artists. The detected feature edges are then transformed into stylized lines through a number of stylization options. Unlike Blender's good old Edge (Toon) option that only generates a raster image, Freestyle feature edges can be manipulated by means of geometrical information, for example by line length, angle formed with two adjacent lines, and distance from the camera. In addition, identified feature lines can be stylized in many ways, such as different line colors, alpha transparency, and line thickness. Straight line segments can also be transformed into fancy curves by adding random displacements and fitting to smooth Bezier curves, for instance.

The block diagram below shows key processing components of Freestyle. The input is a 3D scene populated with mesh objects. The given scene is transformed into 2D stylized lines as follows:

  1. A feature edge detection algorithm is applied to the 3D scene to extract feature edges of interest, such as silhouette lines, borders and crease lines. The set of identified feature edges is called view map. A view map is computed for each render layer of the scene. Render layers have new Freestyle options for controlling the view map construction.
  2. The feature edges are manipulated by user-defined operations to create chains of feature edges that will be the base geometry of final stylized lines. The set of feature edges under manipulation is called line set upon which a number of options for feature edge selection, chaining (i.e., edge concatenation), splitting, and sorting are defined. Multiple line sets can be defined with respect to a view map (i.e., for each render layer). For instance, two line sets can be defined to draw visible lines and hidden lines, respectively.
  3. The chains of feature edges are transformed into stylized lines (strokes) by applying user-defined stylization options. A set of stylization options is called line style. Line styles are new datablocks in Blender, which means that line styles can be shared by multiple line sets, possibly from a different scene as well as from within external .blend files, making it easy to apply the same stylization to different sets of lines.
  4. The stylized strokes are finally rendered and the resulting 2D line drawing is merged into the Combined pass of the Blender Internal renderer.
Key processing components of Freestyle

It is noted that Freestyle generates line drawing only. Hatching and shading of faces, as well as shadows are out of the scope of Freestyle at the moment. However, Freestyle has been fully integrated into render layers and the compositor, so that Freestyle line drawing can be easily combined with other render components (see below).

User Control of Feature Edge Detection

Detection of feature edges from the input 3D scene can be controlled at different levels.

Freestyle options in render layers

First, each render layer has an independent set of Freestyle options for customizing the feature edge detection according to application requirements (see the screen capture on the right). Edge detection options include: (a) crease angle, to control the amount of crease lines (the larger the crease angle is, the more crease lines you get); (b) culling, to exclude those edges in the input 3D scene that are out of the 2D image boundary (mostly for performance improvements, but also some visual differences may appear depending on line stylization options); (c) face smoothness, to take the smoothness of mesh faces into account (usually resulting in smoother silhouette lines of objects, at the cost of additional rendering time); and (d) material boundary, to find two adjacent faces having different materials and take the edges between them as feature edges.

Second, mesh datablocks have been extended to allow users to directly annotate individual edges and faces to assist the feature edge detection. Mesh edges have a new attribute named Freestyle Edge Mark to specify mesh edges of interest for Freestyle line drawing. These edge marks can be used to: (a) force specific edges to be detected as feature edges; and (b) to exclude them from Freestyle line drawing. Similarly, mesh faces may have Freestyle Face Marks to specify regions of interest for Freestyle rendering. Marked faces can be used either to force edges within the marked faces to be detected as feature edges, or to exclude the edges from the Freestyle rendering process.

Marking Freestyle Edges in edit mode.
Render without Edge Marks.
Render with Edge Marks enabled.

Line Stylization Options

Freestyle for Blender has two complementary modes for line stylization: the Parameter Editor and Python Scripting mode. Each render layer is set to one of the two modes to apply line stylization operations to the associated view map.

Parameter Editor Mode

The Parameter Editor mode allows users to interactively manipulate a rich set of line stylization options. The user-tunable options in this mode are divided into two groups, namely line set options and line style options.

Line set options.

Line set options are used to pick up a subset of feature edges from the view map and feed them to the subsequent line stylization process. Edge selection can be conditioned by: (a) line visibility (i.e., only visible lines, only hidden lines, or those within a range of qualitative invisibility); (b) edge types (such as silhouette lines, crease lines, and edge marks); (c) face marks (to include or exclude edges of marked faces); (d) object groups (to focus on edges from a group of objects); and (e) image boundary (to completely exclude off-image feature edges). The selection criteria can be combined through logical AND, OR and negation operations.

Line style options (in the Geometry section).

Line style options are used to create user-defined line styles. Selected feature edges are concatenated into chains of feature edges by chaining to construct the base geometry of stylized lines (strokes). Available chaining options are plain chaining for simply concatenating edges one after another, and sketchy chaining for creating one or more rounds of strokes to emulate hand-drawn multiple touches by human artists. Chains can be refined by splitting (e.g., at points where the angle between two adjacent edges is within a specified range) and selecting (e.g., to remove chains shorter than a length threshold). The appearance of strokes is defined by base line color, alpha transparency, and line thickness, as well as by a series of modifiers applied to the base stylization parameters. The base stroke geometry can also be modified by geometry modifiers. Round and square line caps, as well as dashed lines based on user-defined patterns are also supported.

Python Scripting Mode

The Python Scripting mode offers full programmability for line stylization. In this control mode, all stylization operations are written as Python scripts referred to as style modules in the Freestyle terminology. The input to a style module is a view map (i.e., a set of detected feature edges), and the output is a set of stylized strokes.

A style module is composed of successive calls of five basic operators: selection, chaining, splitting, sorting and stroke creation. The selection operator identifies a subset of input feature edges based on one or more user-defined selection conditions (predicates). The selected edges are processed with the chaining, splitting and sorting operators to build chains of feature edges. These operators are also controlled by user-supplied predicates and functions in order to determine how to transform the feature edges into chains. Finally, the chains are transformed into stylized strokes by the stroke creation operator, which takes a list of user-defined stroke shaders.

Python style modules are stored within .blend files as text datablocks. External style module files first need to be loaded in the Text Editor window. Then the pull-down menu within an entry of the style module stack allows you to select a module from the list of loaded style modules.

A style module ( loaded in the Text Editor window, and a pull-down menu for style module selection in the Freestyle tab in the Render Layer buttons.

Freestyle for Blender comes with a number of Python style modules that can serve as a starting point of your own style module writing. See also the section of the Freestyle Python API in the Blender Python API reference manual for the full detail of style module constructs.

Post-Processing with the Compositor

Line drawing results from Freestyle are integral part of the Combined pass in addition to the conventional components such as Solid and Sky. Freestyle renders are superimposed on top of the other Combined elements (except for Halo). A Freestyle-only "pass" can be obtained by using Include options: Enable Freestyle and uncheck the other Combined components, as shown in the screen capture below.

Settings of render layer Include: options for creating a Freestyle-only "pass".

Freestyle is fully compatible with the compositor, allowing for arbitrary post-processing of line drawing results. Full-sample anti-aliasing (FSAA) is also functional with Freestyle.

Simple example of line drawing composition.

Freestyle Artwork Showcase

FreeStyle logo animation by Lee Posey (jikz). CC BY-SA
The Light At The End by Cris Burton. CC BY-SA
A cartoon scene from Oha-Studios (the .blend file). © Mechanimotion Entertainment.
HVAC Pre-Viz by Lee Posey. CC0 (
ABC of AKARI by Vicente Carro. © AnigoAnimation
Kitchen by Vicente Carro. © AnigoAnimation
Over Weight Boss by Mclelun Lee. CC BY-SA
Boy Playing in Snow by Mclelun Lee. CC BY-SA
Kaede and the Mountains by Barkóczi Gergely. CC BY-SA
Kaede versus Giant by Barkóczi Gergely. CC BY-SA
Turning pages animation by T.K., using Python Scripting Mode. CC0 (File:Turning
Sawshark by Charblaze. CC0 (File:SawShark
Tire Bike by Pro Creaciones. CC BY
Line demo by Ronan Ducluzeau using render layers (with physic animation) (File:Line Demo Render and using groups by Vicente Carro (File:Line Demo CC0
ATV buggy by Rylan Wright (RONIN). CC BY (
Guitar Quote Poster by LightBWK. CC0 (
Temple Xylography by Charblaze. CC-BY
By mato.sus304. CC BY-SA (File:Mato sus304


Freestyle documentation

Freestyle Links

History of Freestyle integration