Weekly update April 5-18

Over the last two weeks, the dev team was intensively working on major updates of the Freestyle Python API documentation.  The idea was to incorporate the contents of the original Freestyle API reference manual into the Blender/Freestyle Python API implementation in the form of Sphinx-based docstrings (i.e., pieces of API descriptions in string literals).  This way the dev team can take the advantages of the new Blender 2.5 documentation system that allows us 1) to keep the API implementation and documentation in sync by having docstrings within the source code, and 2) to generate an up-to-date and nicely formatted API reference manual through the fully automated Blender 2.5 documentation tools.  Not only we imported the contents of the original Freestyle API reference manual and reformatted them with Sphinx mark-ups, but also we made a substantial revision of the text by filling missing entries, elaborating sparse descriptions, and making C++-oriented descriptions more suitable for Python programmers.

For those who are interested in how the new Freestyle Python API reference looks like, here is a screenshot (click it to enlarge):

Branch users can generate the API reference themselves by following the instructions shown in the Web page of the documentation tools.  Note that generating the formatted API documentation is not part of the usual build process.  You need to start the documentation generation separately after you have built a Blender executable file.

The next target is to finish the Python API improvements (finally).  The documentation updates were indeed a nice opportunity to go through the current API implementation with a fresh mind, and we identified some remaining API design and implementation issues.  We are going to address them in the next weeks.  The work on the API improvements will also be accompanied with further documentation updates in line with any changes in the API implementation.  All standard style modules are accordingly updated as well.

Weekly update March 29-April 4

During the last week, the Freestyle branch was updated with regard to render border options (Border and Crop).  These options allow you to render a small cut-out of the entire image.  The region to be rendered can be specified by switching to the camera view (Numpad 0) and using a rubber band (Shift+B).  Previously enabling the Border option resulted in broken strokes.  Now the issue has been addressed, and Freestyle should work fine with both render border options.  With these options enabled, render passes will also be cropped.  This means that when diffuse and Z depth passes are accessed from within style modules, they have a cropped image size as well.

Blender has a number of render options that affect the final dimensions of a render in units of pixels.  As of this writing, the following options are respected by Freestyle: 1) X and Y resolutions; 2) percentage scale; 3) pixel aspect ratio; and 4) render border.  In addition, Freestyle deals with two 2D coordinate systems.  One is the 2D vertex coordinate system in which 2D points of vertices are specified (the 2D points can be retrieved by the getPoint2D method of Interface0D objects).  The other coordinate system is for render passes (i.e., diffuse and Z depth passes).  Since all these details may cause a bit of confusion, here we summarize the definitions of dimensions in the 2D coordinate systems in Freestyle.  Let W_* and H_* be horizontal and vertical numbers of pixels, respectively, then the dimensions of a render in the 2D coordinate systems are specified in terms of the 4 render options as follows:

• The dimensions of a render in the 2D vertex coordinate system are always defined as
  

  W_vert = X,
  H_vert = AY,

  where X is the X resolution, Y is the Y resolution, and A is the pixel aspect ratio defined by horizontal aspect U and vertical aspect V as A = V / U.

• If the render border is disabled, the dimensions of a render in the render pass coordinate system are defined as
  

  W_pass = PX,
  H_pass = APY,

  where P is the percentage scale in the interval 0 to 1.  If the render border is enabled, the dimensions are defined as

  W_pass = P (R – L + 1),
  H_pass = AP (T – B + 1),

  where L, R, T and B are the left, right, top and bottom coordinates of the render border, respectively.

DensityF0D and LocalAverageDepthF0D functors are used to retrieve a weighted sum of pixels from the diffuse and Z depth passes.  The callers of these functors specify a region of interest by the 2D vertex coordinate system, whereas the functors fetch the pixels based on the render pass coordinate system.  Consequently, a coordinate system transformation takes place in order to convert a pixel location in the former system into the corresponding location in the latter system.  If the render border is enabled, any pixel outside the border is considered to be zero.

In the next weeks, we move on to Freestyle Python API improvements as described in the new to-do list.  This time we are going to finish the new Python-oriented API syntax and remove the old SWIG/C++-based syntax from the API (see the blog entries on December 1, 2008 and on August 4, 2009 for more information on the syntactic improvements).  This means that existing style modules written in the old syntax need to be updated based on the new syntax.  Since the original Freestyle documentation will be out of date, we also work on a new API reference using the Sphinx-based Blender 2.5 documentation system.