Code base updates

1. Experimental fix for incorrect view edge visibility

Given a 3D scene populated with mesh objects, Freestyle generates a data structure called view map consisting of view edges.  Each view edge is basically a polyline, i.e., a series of connected straight edges (referred to as FEdges) originated from the input mesh objects.

The problem addressed here is an ages old issue that the visibility of view edges in the view map may be incorrect. The main cause of this issue is that view edges are constructed from a series of FEdges without testing the visibility of individual edges being concatenated.  In a subsequent processing stage the view edges are split into pieces if two view edges intersect with each other in the 2D image coordinate system.  The visibility of the view edges is then computed by taking account of occluding faces in the 3D scene.  In many cases this procedure results in correct line visibility, but not always (that is the problem).

A simple solution experimentally implemented here is not to chain FEdges at all.  Instead, view edges are constructed from at most one FEdge now.  This leads to better line visibility results, but at the cost of a much larger view edge count, which may impose a performance penalty in the following processing stages.  For now this solution is only applied to sharp FEdges (roughly corresponding to edges in the input mesh data; specifically, silhouette, crease, border, edge mark, contour, external contour, and material boundary).

A better solution would be to reorder the three steps of view edges construction mentioned above, i.e., first splitting FEdges at 2D intersection, computing the visibility of the FEdges, and then concatenating them to build view edges.  This solution will require a bigger refactoring, and thus is left for future work at the moment.

2. Performance improvements of temporary scene generation for stroke rendering

Two-dimensional strokes (e.g., silhouette and crease lines) are automatically generated from a given 3D scene and superimposed on top of the Combined pass.  For this purpose, a temporary scene populated by mesh data representing the 2D strokes is created and rendered with the Blender Internal (BI).

Individual strokes are translated into distinct mesh objects, resulting in a large number of mesh objects. This is especially true when chaining is disabled and strokes are made of at most one view edge.  Because of the aforementioned change in the view map construction, the view map is likely populated by a large number of view edges (e.g., on the order of ten thousand).  As a result, the temporary scene generation may take an appreciable amount of time.  This issue was reported by a branch user with a fairly complex 3D scene that results in more than 11000 strokes.

In a discussion of this issue in the bf-committers mailing list, Joshua Leung (aligorith) kindly provided the dev team with insightful performance analysis results concerning the generation of many mesh objects at once.  As a matter of fact, mesh objects are full Blender objects and not intended to be a lightweight data structure for quick throwaway geometry generation in a time-critical loop.  A solution suggested by Joshua is to extend the BI to render stroke meshes through a new lightweight data structure specifically designed for that purpose.  Another possible direction is to rely on an external 2D rendering engine as discussed earlier.  Because of other priority tasks in the branch development, these solutions are kept for future options.

For now, a quick attempt was made to optimize the performance of temporary scene generation directly based on the performance analysis results by Joshua.  The following plots compare the performance of stroke mesh generation before (left) and after the performance optimization (right).

The performance improvement is significant with the average time per stroke 15 times shorter than the non-optimized timing result.  Still it can be seen that the elapsed time per mesh object tends to increase over time (because of a linear search over existing objects in the scene to make object names unique).  Additionally, there is some non-linear time component, whose source is unknown at the moment and further performance analysis is required.

3. Additional improvements

• Fix for OCIO-based color management not working properly with Freestyle.
• New button to make a copy of the active modifier in the Parameter Editor mode.  Code contribution by flokkievids, thanks!

User artwork showcase

An active user base is a key for a successful free software project.  In this sense the Freestyle integration project is very well supported by an increasing number of computer graphics artists all over the world.  Here is a mini gallery of selected artwork by three branch users.

“Fries” by Rylan Wright (RONIN) is a funny stop motion animation clip showing a conversation between two friends of him trying to figure out what to have for lunch.

The following fan-art image of Japanese Anime “Kei-On!” is done by Mohe & Shiratama (Moonlight Jellyfish).  Their modeling and rendering workflow is illustrated in this blog article (in Japanese).

“Japanese Railway’s 140th Anniversary” by mato.sus304 is a series of cool scenery shots showing trains in urban areas.  A making-of blog article about the production workflow of this movie clip is available here (in Japanese).

Thank you RONIN, Mohe & Shiratama, and mato.sus304 for using Freestyle for the excellent artwork!

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 BlenderArtists.org, 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!

BlenderNPR.org 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.

New features and changes in the Parameter Editor mode

The following two stroke geometry modifiers have been added.

• 2D Offset: Adds two-dimensional offsets to stroke backbone geometry.
• 2D Transform: Applies two-dimensional scaling and rotation to stroke backbone geometry.

The 2D Offset geometry modifier has four parameters: start, end, X and Y.  The first two parameters add offset values in the direction perpendicular to the stroke direction.  The offset values are linearly interpolated from the beginning to the end of a stroke.  The X and Y parameters add absolute horizontal and vertical offset values.  The following image illustrates the effects of these parameters.

The 2D Transform modifier transforms stroke geometry by X and Y scaling factors and a rotation angle.  The center (pivot) of these 2D transformations can be: the stroke center, the beginning and the end of the stroke, a point along the stroke (specified by a value between 0 and 1, called stroke pivot parameter), and absolute 2D point (specified by X and Y coordinate values).

Example renders below demonstrate the effects of 2D offset, scaling and rotation (from left to right), where three external contours were modified separately with different modifier parameters.

With a view to a better use of screen space, the locations of edge type options within the Selection by Edge Types have been rearranged as shown below.  Frequently used edge types come first, and less used ones come after.

The two edge types “Ridge” and “Valley” have been unified into “Ridge & Valley”, since the Valley edge type is merely an alias of Ridge in the present Freestyle implementation.

Sphere radius and Kr derivative epsilon were removed from the Parameter Editor mode.  Now sphere radius of 1.0 and Kr derivative epsilon of 0.0 are used by default.  The rationale of the removal is two-fold: little predictability and very minor artistic values.  The effects of these parameters are hard to estimate in advance, which likely leads to a frustration of users due to repeated trials and unpredicted results.  Therefore, the two parameters are considered to have quite limited artistic values.  Proper definitions of the two parameters more and less require the knowledge of differential geometry and would not make sense to most artists for which the Parameter Editor is intended.

Sphere radius and Kr derivative epsilon are still available in the Python Scripting mode, but now in an “advanced options” section that is disabled and hidden by default.  In this way new users are properly warned, while expert users with specific technical needs can enable these options if they want.  The same default values mentioned above are used when the two parameters are disabled in the Python Scripting mode.

Fix for degenerate triangles in imported mesh data

A line visibility issue was identified by means of a .blend file supplied by a branch user.  The issue was caused by so-called degenerate triangles that are triangular faces whose area is zero.  It is useful to distinguish two types of degenerate triangles as follows.  Let A, B and P denote the three vertices of a triangle.  The triangle is said a degenerate triangle if:

1. A and B are in the same position in the 3D space; or
2. the distance between point P and line segment AB is zero.

Note that the former condition is a special case of the latter.  Degenerate triangles in the first form can be (and have been) addressed in the same way as the standard Remove Doubles command in Blender.  Those in the second form, on the other hand, are more difficult to address and thus require special treatment.

For what concerns line visibility in Freestyle, degenerate triangles become harmless if they are transformed into non-zero area triangles.  Hence, a preprocessor of imported mesh data from Blender to Freestyle was implemented to resolve degenerate triangles in the second form, where two different approaches to the solution of the issue have been attempted.

One approach is to check if a degenerate triangle is part of a quad face.  This checking is easily done by testing if three of the four vertices are colinear (i.e., they are lying on a line).  If that is the case, then depending on how the quad is separated into two triangles, one of them can be a degenerate triangle.  Degenerate triangles of this form is addressed by rotating the diagonal edge of the quad face without affecting the visual outcome.

The other approach is to add a very small offset to P so that the resulting triangles have a non-zero area.  The visual side-effect of this solution is likely to occur at a sub-pixel level, and thus considered negligible.

Several other attempts were made to explore the best way to handle degenerate triangles, and the two solutions above are found the most effective.  The dev team still keeps close eyes to the line visibility issue due to degenerate triangles.  More fixes will follow if some other sources of degenerate triangles are identified.  Problem reports on this matter are very welcome.

Bug fixes and miscellaneous improvements

The following user-visible bugs were fixed, many of which were kindly reported by branch users.

• Color management was not working properly with Freestyle.
• Color ramps were not immediately updated during the manipulation of a color picker.
• The Selection by Image Border was not working correctly.
• A crash due to invalid pointers within a copied line set was fixed.  Now the line set buffer is cleared when a new .blend file is opened, so that a line set may not be copied and pasted between .blend files.
• The Backbone Stretcher geometry modifier had a hard-coded limit that the effect was applied to stokes with 2D length longer than 50.  Now the geometry modifier can be applied to strokes of any length.
• A crash with FSAA enabled and Freestyle disabled was fixed.
• Line style names were not made unique after a new name was set.

The dev team is grateful to branch users for their active testing of the software and problem reports.

Freestyle artwork by branch users

An increasing number of Blender artists have been sharing their results with Freestyle, through the BlenderArtists.org Freestyle thread, personal blogs, tweets and so on.  Here, two excellent pieces of artwork by RONIN (left) and s12a (right) are presented.

Many thanks for your contributions, RONIN and s12a!

Updates in the Parameter Editor mode

The function of the ‘+’ button to the right of a line style name in the Freestyle: Line Style tab has been changed so as to make a copy of the active line style instead of creating a new line style with default settings.  This is meant to be consistent with the creation of new data blocks in other parts of Blender (for instance, creating a new material will result in a copy of the active material).  Also a button to make a single-user copy of a line style (i.e., the button that indicates the number of users) has been implemented.

Copy and paste operations for line sets have been added to make it easy to duplicate the settings of a line set.

It is recalled that line sets have a reference to a line style.  When the settings of a line set A having a reference to a line style X is pasted into a line set B, the latter line set will have a reference to X.  That is, the paste operation changes the line style references, but does not modify the settings of line styles.  If you also want a copy of the referenced line style after the paste operation, you have to make it using the copy operation for line styles as described above.

An extended set of conditions for feature edge selection by edge types has been introduced.  Each edge type check button in the Selection by Edge Types has now an associated toggle button to exclude the edge type from the feature edge selection.  This allows you to select, for instance, those edges that are silhouette lines but not external contours by enabling the two edge types and also the toggle button for external contours, as shown in the screen shot below.

A new option for disabling the chaining of feature edges has been added to the ‘Stroke’ panel of the Freestyle: Line Style tab.  This option is useful for examining the initial set of feature edges in the view map.

New options for splitting chains of feature edges by a minimum and maximum 2D angle and by a 2D length limit have been added to the ‘Stroke’ panel of the Freestyle: Line Style tab.  These options are useful for splitting long strokes into small pieces.  See the example renders of the Guiding Lines geometry modifier below for an example use of splitting by 2D length.

Three new stroke geometry modifiers have been implemented.

• Polygonization
• Guiding Lines
• Blueprint

The Polygonization geometry modifier transforms smooth strokes into jagged polylines.  The “error” parameter specifies how much deviation is allowed from the original stroke geometry (the larger the error parameter is, the more jagged the resulting polylines are).  The following test renders illustrate the effect of the Polygonization modifier: (a) without applying the modifier, strokes along arcs are smooth; (b) with the polygonization modifier applied with the error parameter set to 5, the strokes are transformed into jagged polylines; and (c) the error parameter set to 20 gives more jagged polylines.

The Guiding Lines geometry modifier replaces a stroke with a straight line connecting both ends of the stroke.  This modifier will produce reasonable results when strokes are short enough, because shorter strokes are more likely to be well approximated by straight lines.  Therefore, it is recommended to use this modifier together with the splitting options (by 2D angle or by 2D length) mentioned above.  The following images show how splitting and geometry modifiers can be combined: (a) smooth strokes along arcs are split into small pieces by the 2D Length option; (b) the Guiding Lines gemoetry modifier is then applied to approximate the split stroke segments by straight lines; and (c) the Backbone Stretch geometry modifier is further applied to extend both ends of each straight stroke.

The render below is a combination of the Guiding Lines and Spatial Noise geometry modifiers.  Both modifiers were applied to two identical line sets to duplicate the guiding lines.  The line sets contain only external contours.  The Spatial Noise modifier was applied before the Guiding Lines modifier, so that two sets of guiding lines display some variability.

The Blueprint geometry modifier produces a blueprint using circular, elliptic, and square contour strokes.  A blueprint here refers to those lines drawn in the beginning of free-hand drawing to capture the silhouette of objects with a simple shape such as circles, ellipses and squares, as illustrated below.

The Perlin Noise 1D geometry modifier had an issue that noise frequency was relative to the stroke length (i.e., the number of noise displacement values was the same for strokes of different lengths).  This resulted in very noisy short strokes and much less noisy long strokes.  Now the noise frequency is relative to the distance from the starting point of a stroke.  That is, two strokes of the same length will be distorted by the same number of noise displacement values, whereas longer strokes will have more noise displacement values along stroke.

Stability improvements

• A fix was made to address duplicated feature edges due to a numerical instability of line clipping by near/far Z planes.
• View map construction was not properly taking face marks into account.  This caused incorrect (and unpredictable) feature edge selection results when face marks were used.
• A crash caused by temporary scenes for stroke rendering was fixed.  Freestyle generates a temporary scene containing a number of stroke meshes to achieve stroke rendering using the Blender internal renderer.  This temporary scene may appear in the outliner and undergo user interaction when the stroke rendering takes a long time.  The crash was due to the deletion of the scene without taking care of references to the scene from screens, one of which was the outliner.
• The interaction between Blender and Freestyle was revised to address a crash when two scenes in the compositor have different render resolution (i.e., image width and height, scaled by a percent parameter).
• Stroke rendering instability with stroke geometry shaders was addressed.  Stroke::Resample(int nPoints) was not properly working when a wrong value was returned from Stroke::getLength2D(), resulting in repeated warning messages “Warning: incorrect points number” during stroke rendering.  The main cause was that stroke geometry shaders did not update the two-dimensional (2D) length (also referred to as curvilinear abscissa) after they modified the 2D points of stroke vertices.  Now all stroke geometry shaders make explicit calls for Stroke::UpdateLength() that has been introduced for recomputing the 2D length.
• A bug in Operators.recursiveSplit() that splitting could not take place within the last segment of a chain was fixed.

Remarks on the merge into the trunk

The dev team has been receiving an increasing number of questions from branch users concerning the merge into the trunk (i.e., official release of Blender).  It is remarked that the merge has already been agreed with the core Blender developers of the trunk, and the only major question is when the merge is done.

In June 2010, the dev team defined a list of unfinished components that need to be done before the merge is finally asked.  The list includes three major components: (a) GUI for the Parameter Editor mode; (b) feature edge detection at the intersection of two faces; and (c) Freestyle Python API improvements.  Subjective achievement rates of the three components are 90%, 0%, and 80%, respectively.  In other words, the Freestyle branch needs more development before it gets ready for code review that is required for the merge to happen.

At the moment the official release of Blender 2.62 is planned in February 2012, but it is unlikely that Freestyle is included into this release because of the short deadline for code review in January.

Considering an admittedly limited amount of time resources, it is still difficult to predict when all the unfinished components are done and the code review for the merge can be asked.  We appreciate the understanding and patience of branch users.

Stability improvements with the face smoothness option

Several branch users kindly reported that Freestyle failed when the Face Smoothness option was enabled and object materials were used to determine line colors.  When the Face Smoothness option is enabled, the view map computed from a given 3D scene is populated by not only sharp FEdges (i.e., edges in the original meshes) but also smooth FEdges (i.e., newly constructed edges across faces).  This situation often resulted in a failure of the getFEdge() method (defined in the Interface0D class and its subclasses) used to obtain the FEdge between two given 0D elements (such as SVertices and CurvePoints).  The instability of getFEdge() caused many related issues because the method is widely used in other predicates and functions that rely on it.  The most prominent example of related user-visible problems is a failure of the built-in MaterialF0D class that retrieves object materials of given 0D elements, as seen in the problem reports from branch users.

The persistent failure of getFEdge() was resulting from several bugs in the view map construction algorithm.  These bugs were fixed through careful code revisions and intensive testing.  Also, the built-in MaterialF0D turned out to be incapable of handling Curve objects (such as chains and strokes), so that a new CurveMaterialF0D class has been introduced to address the material retrieval in the case of Curve objects.

These changes have improved the stability of the renderer with the Face Smoothness enabled.  The dev team is very grateful to those branch users who provided the bug reports together with .blend files to reproduce the issues.  The .blend files were indeed indispensable test cases during the bug hunting.

Fine control of feature edge selection with mesh face and edge marks

With the aim of allowing for fine control of feature edge selection, new “face marks” and “edge marks” have been introduced in mesh data blocks.  In the edit mode of a mesh object, face marks can be put to selected faces by choosing Mesh > Faces > Mark Freestyle Face from the menu of a 3D View window or Ctrl-F > Mark Freestyle Face from the context menu.  Similarly, edge marks can be put to selected edges by Mesh > Edges > Mark Freestyle Edge or Ctrl-E > Mark Freestyle Edge.  These marks should work fine with the Subdivision Surface and Mirror modifiers.

Moreover, two new conditions for feature edge selection have been added to the Parameter Editor mode, as described below:

1. The Selection by Edge Types option now includes the new Edge Mark type, which can be used to (de)select feature edges having edge marks.  This option can be used to add to (or remove from) the view map arbitrary edges of mesh objects.
2. Selection by Face Marks option has been newly introduced, in which face marks are used for feature edge selection in two ways.  One option is called “One Face” which is to (de)select feature edges if one of faces on the left and right of each feature edge has a face mark.  The other option is “Both Faces” to (de)select feature edges if both faces on the left and right have a face mark.  Those feature edges that meet the conditions are selected if the Inclusive option is enabled; they are deselected if the Exclusive option is turned on.

The following screenshot shows the new GUI controls (highlighted in red) based on face and edge marks.

Edge marks are useful when you want to draw lines along particular mesh edges.  The following example images demonstrate the use of edge marks.

The image on the left shows a sphere mesh with edge marks (in the edit mode).  In a 3D View window, edge marks are displayed in light green.  The image on the right is a render without the Edge Mark type enabled in the Selection by Edge Types option (the black line shows the silhouette of the sphere).  The image below is a rendering result with the Edge Mark type enabled.  The blue lines indicate those resulting from mesh edges with edge marks.

Face marks are useful for removing lines from certain portions of mesh surfaces.  Suppose that two faces of the default cube have face marks as shown in the image on the left below.  Marked faces are displayed in light green.  The image on the right is a rendering result without using the Selection by Face Marks option.

The following images show how rendering results vary with four combinations of the Inclusive/Exclusive and One Face/Both Faces toggle options.  Notice that only the edge between the two marked faces is (de)selected when the Both Faces option is used, while all the edges touching the marked faces are (de)selected when the One Face option is enabled.

Renders from branch users

In the meantime, branch users have been sharing their renders made with Blender and Freestyle.  Here are some selected rendering results.

Toon rendering of Sintel by jikz (the model is base on Sintel Lite 2.57b by BenDansie):

Architectural line drawing by flokkievids:

Many thanks to jikz and flokkievids for the excellent contributions!

Enhancement of the Parameter Editor mode

New line style controls have been added to the Parameter Editor mode that is intended to be an artist-friendly GUI for manipulating line styles without any user efforts on Python scripting.  Recent major additions and changes are described as follows.

• A new line style option for sketchy chaining of feature edges has been added.  The conventional default chaining method is now called Plain, while the new chaining option is called Sketchy.  The latter option allows for generating chains of feature edges with sketchy multiple strokes.  Both Plain and Sketchy chaining options have the Same Object toggle button in common, whereas the Sketchy option has an additional option called Rounds.  With the Same Object option enabled, only feature edges of the same object are chained.  The Rounds option specifies the number of rounds in sketchy strokes.  The following render shows a visual effect of sketchy chaining (3 rounds, with the Spatial Noise geometry modifier specified to enhance the sketchy appearance of strokes).

• A calligraphic thickness modifier has been implemented.  This modifier gives strokes variable thickness that looks as if they are drawn with a broad and flat pen for calligraphy.  The following test render illustrates a typical effect of calligraphic thickness.

• A new parameter called Angle has been added to the Perlin Noise 1D and 2D geometry modifiers to specify a displacement direction in degrees (zero degree indicates the positive X direction).  The following images demonstrate how the Angle parameter makes a difference in rendering results (left: the Angle parameter set to 45 degrees; right: 135 degrees).

• The behavior of the Perlin Noise 1D geometry modifier has been changed so that it works differently from the Perlin Noise 2D geometry modifier.  Now the Perlin Noise 1D modifier distorts strokes using the curvilinear abscissa of stroke vertices as the input of the Perlin noise generator.  It is remarked that curvilinear abscissa is a scalar value between 0 and 1.  The first and last vertices of a stroke have the values 0 and 1, respectively, and the values for other stroke vertices are linearly interpolated over the stroke.  Therefore, the Perlin Noise 1D modifier gives identical noise displacements to strokes if the strokes have the same length and sampling interval (the latter is specified by the Sampling geometry modifier).  In contrast, the Perlin Noise 2D modifier generates noisy displacements using 2D coordinates of stroke vertices as the input of the noise generator.  Therefore, strokes in different positions in a render will be distorted with different displacements by the Perlin 2D noise generator even if the strokes have the same length and sampling interval.  The differences between the Perlin Noise 1D and 2D modifiers are illustrated in the following test renders.  The image on the left shows a set of vertical lines and another set of star-shaped strokes, both distorted by the Perlin Noise 1D modifier.  Strokes in each set of lines have identical noisy displacements, because of the same stroke length and sampling interval.  The image on the right shows a render of the same scene with the Perlin Noise 2D modifier, which gives different displacements to each of the strokes because of their 2D positions in the image that are different from each other.

• New line style options for selecting chains by min/max 2D lengths have been added.  Using these options you can select strokes that are longer and/or shorter than specified stroke lengths.

Link and Append

A proper support for the Link and Append commands has been implemented.  Now you can link/append line styles as well as scenes with line styles from within other .blend files.

Stability improvements and bug fixes

An attempt to fix the long-standing issue of occasional infinite straight lines has been made.  The fix is still not the best solution, but seems to yield much better results as illustrated in the following test renders (left: examples of unwanted infinite lines due to the bug; right: infinite lines no longer appear after the bug fix).

Since the solution looks quite effective, a temporary workaround (implemented by means of a custom chaining rule) for infinite straight lines was removed.  This change has resulted in much cleaner strokes.  If you have suffered from a lot of segmented strokes that are supposed to be a single straightforward stroke, then using the latest Freestyle branch would be a solution for the issue.

In addition, several other bug fixes have been made to improve the general stability of the Freestyle renderer.  Most of the bugs were reported by branch users, some with example .blend files for reproducing the problems.  These reports were really invaluable, and we appreciate the feedback from the branch users.

Concluding remarks

That is all for now.  More additions to the Parameter Editor mode as well as further development work on other priority tasks (i.e., unfinished components that must be completed before the merge into the trunk is asked) are anticipated in the next weeks.

Stroke geometry modifiers

A new set of line style options for modifying stroke geometry was introduced in the Parameter Editor mode.  Stroke geometry refers to the backbone polyline of a stroke.  Now stroke geometry can be modified by a list of stroke geometry modifiers specified in the Geometry tab (previously referred to as Distort).  At the moment the following geometry modifiers are available, each with a set of animateable parameters:

• Sampling: Changes the resolution of stroke backbone polylines.
• Bezier Curve: Replace stroke backbone with a Bezier approximation of the stroke backbone.
• Sinus Displacement: Add sinus displacement to stroke backbone.
• Spatial Noise: Add spatial noise to stroke backbone.
• Perlin Noise 1D: Add one-dimensional Perlin noise to stroke backbone.
• Perlin Noise 2D: Add two-dimensional Perlin noise to stroke backbone.
• Backbone Stretcher: Stretch the beginning and the end of stroke backbone.
• Tip Remover: Remove a piece of stroke at the beginning and the end of stroke backbone.

Note to branch users: When you have a .blend file with Freestyle options specified, you need to add a Sampling modifier with the Sampling parameter value set to 5, which is the default polyline resolution previously used for line drawing in Freestyle.  Before geometry modifiers were introduced, this initial sampling was automatically done.  Now the initial sampling is a tunable parameter that can be omitted, allowing better control on polyline resolution.  If no sampling modifier is specified, your line drawing will result in coarse polylines.

Images below are a few example renders made with the following stroke geometry modifiers used: (a) no geometry modifiers, showing baseline stroke backbones; (b) Bezier Curve modifier; (c) Sinus Displacement modifier; (d) Backbone Stretcher and Spatial Noise modifiers.

Fill Range by Selection

A new push button Fill Range by Selection was added to the Distance from Camera and Distance from Object modifiers (see figures below).  This button allows you to automatically fill the Range Min and Max entries based on selected mesh objects.  For the Distance from Camera modifier, the Range Min (Max) entry is filled with the minimum (maximum) distance between the active camera and the vertices of selected mesh objects.  For the Distance from Object modifier, the distance between the target object and the mesh vertices is measured.

Stroke splitting at material boundary

A new toggle button for splitting strokes at material boundary was added to the Strokes tab.  This option divides strokes into pieces at material boundary.  The following renders illustrate the effect of the splitting option: (a) disabling the option results in a smooth (blurred) transition of stroke colors across material boundary; (b) enabling the option permits a flat color transition at material boundary.

In addition, the Parameter Editor mode of the Freestyle graphical user interface was enhanced with new Material modifiers that allow you to change the line color, alpha transparency, and line thickness of strokes by object materials.  The screenshot below shows the GUI controls of the Material color modifier.

The following set of rendering results demonstrates a typical use the Material color modifier: (a) the stroke color is constant (i.e., the base color is black); (b) the Material color modifier is applied and the base color is replaced by the the diffuse color of object materials (i.e., blend = Mix, influence = 1.0); (c) same as (b) but the diffuse color of object materials is blended into the base color (blend = Add and influence = 0.4).

Artwork with Freestyle for Blender

In the meantime, several branch users released excellent animation shorts and movie clips made partly with Freestyle.  First, Chris Burton and his colleagues released a finished animation short “The Light at the End“.  This is one of the most impressive pieces of artwork that give you a real sense of how line drawing with Freestyle looks like.

Dolf Veenvliet (macouno) has been using Freestyle for his Entoforms project.  Entoforms are little creatures generated by a program that “grows” them through a kind of DNA strings.  The use of Freestyle is meant to give a “drawn” look to 3D renders according to one of project blog posts.

And last but not least, Ike AhLoe released a finished animation short “Clocked In“.  During the production of this artwork, he contributed to the Freestyle integration project through a number of bug reports and development updates.

We are very grateful for the authors of these art products, since the early adoption of the Freestyle renderer should have been tough and time-consuming due to bugs and limitations.  We hope these frontier examples encourage further use of Freestyle in future 3D art projects.

Technical overview of the optimization

Now let us describe Alex’s optimization work from a technical perspective.  The performance improvements have been mainly done in two major components of the view map construction: silhouette edge detection, and edge visibility calculation.

Silhouette edge detection is to find feature edges of interest that constitute a basis of line drawing in Freestyle.  To optimize this data processing for speed, Alex made careful changes to the code base so as to exploit compilers’ optimization capability.  This modification leads to a shorter rendering time independently of the spatial structure of a given scene.

The detected feature edges then undergo the edge visibility calculation where an integer value expressing quantitative visibility is assigned to each feature edge.  The edge visibility is determined by a raycasting algorithm with the help of a spatial grid structure that allows efficient traversal of faces in the 3D space (i.e., tris and quads) from the view point of a camera.  As a matter of fact, the non-optimized old view map code relied on a grid data structure that was implemented with the assumption that the faces were evenly distributed within the 3D bounding box.  In addition, the old code was internally creating a list of occluders by copying polygons again and again, which slowed down the view map construction.  Alex devised new grid data structures (SphericalGrid for perspective cameras and BoxGrid for orthographic cameras; automatically switched based on the camera types) that do not assume the ideal even distribution of polygons, as well as a heuristic grid density calculation algorithm that enables an adaptive population of the grid structures with polygons.  Moreover, an iterator is employed for obtaining the occluders on demand instead of making a local copy of them.

Based on these internal improvements, two optimized edge visibility calculation algorithms have been added: a “traditional” algorithm for emulating old visibility algorithms, and a “cumulative” algorithm for improved, more consistent line visibility.  Both algorithms exploit the new spatial grid data structures for fast raycasting.  Each optimized algorithm comes with two variations: culled and unculled.  The culled visibility algorithms exclude most of the feature edges outside the image boundary.  This will result in much faster visibility calculation at the cost of possible alterations to the results of edge chaining.  The unculled algorithms take all feature edges into account.  The latter is useful when off-image edges matter for chaining.

New rendering options

A new option “Raycasting Algorithm” has been added to the Freestyle tab to allow users to choose a raycasting algorithm.  Available choices are:

• Normal Ray Casting
• Fast Ray Casting
• Very Fast Ray Casting
• Culled Traditional Visibility Detection
• Unculled Traditional Visibility Detection
• Culled Cumulative Visibility Detection
• Unculled Cumulative Visibility Detection

The first three algorithms are those available in the original Freestyle (the “normal” raycasting was used unconditionally, though).  The “fast” and “very fast” raycasting algorithms achieve a faster calculation at the cost of less visibility accuracy.  The other four are newly introduced optimized options.  The visibility accuracy of the “traditional” algorithms are the same with the “normal” algorithm, while that of the “cumulative” algorithms is supposed to be the same with or better than the “normal” case.  Performance improvements over the old algorithms depend on the scenes to be rendered.  The recommended options for branch users are the culled/unculled cumulative visibility algorithms.  These two options are intended to replace the other algorithms in the future.

Performance results

To conclude this brief introduction of Alex’s wonderful optimization work, some performance results are shown below using four test scenes.  In all cases, the non-optimized ”normal” visibility algorithm in revision 35506 was compared with the culled cumulative visibility algorithm.

Ichiotsu (orthographic)

73448 vertices, 72260 faces, orthographic camera.

Ichiotsu (perspective)

73448 vertices, 72260 faces, perspective camera.

Lily

64011 vertices, 60346 faces, perspective camera.

A scene by Greg Sandor (from Lighting Challenge #15: Film Noir)

109180 vertices, 189191 faces, perspective camera.

The first two examples indicate that the new grid data structures for perspective and orthographic cameras have comparable performance.  The third test showed a huge performance gain in silhouette edge detection.  The last big scene resulted in an incredible speedup rate in the view map building phase.  Remarkably, these amazing performance results are solely by means of Alex’s optimization work.  Again, thank you Alex!  This is really great!

Branch users are encouraged to test the new raycasting algorithms from both performance and artistic perspectives.  Performance reports and rendering results are highly welcome, possibly through the Freestyle thread in BlenderArtists.org.

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/parameter_editor.py.  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.