This patch set reorganizes the modules of the Freestyle Python API in line with the bpy module and its submodules, now that some breakage of backwards compatibility is allowed with the upcoming 2.70 release. The proposed changes aim to address the following issues observed in the present Freestyle implementation:
- Freestyle API constructs for style module writing in Python are not logically organized. The API modules are partly organized in terms of implementation languages (C and Python) and partly based on implemented roles (predicates, chaining iterators, and so on).
- All Python scripts for Freestyle, i.e., both API modules and application programs (style modules), are stored in the same 'release/scripts/freestyle/style_modules' directory. This makes it difficult for new users to find style modules.
The new Python module directory structure is proposed as follows:
- release/scripts/freestyle/modules - Freestyle API modules
- release/scripts/freestyle/styles - predefined style modules
In Python, the Freestyle API modules are reorganized as follows:
- freestyle - top-level package just containing the following submodules.
- freestyle.types - classes for core data structures, and base classes for user-defined stylization rules (i.e., chaining iterators, predicates, functions, and shaders).
- freestyle.chainingiterators - predefined chaining iterators.
- freestyle.predicates - predefined 0D and 1D predicates.
- freestyle.functions - predefined 0D and 1D functions.
- freestyle.shaders - predefined stroke shaders.
- freestyle.utils - utility functions for style module writing.
The effects of the proposed changes are illustrated below by taking the japanese_bigbrush.py style module as example. With the present API organization (before the proposed changes), the import statements in the beginning of the style module have been written as follows:
from freestyle import BezierCurveShader, ChainSilhouetteIterator, ConstantColorShader, \ ConstantThicknessShader, IntegrationType, Operators, QuantitativeInvisibilityUP1D, \ SamplingShader, TextureAssignerShader, TipRemoverShader from Functions0D import pyInverseCurvature2DAngleF0D from PredicatesB1D import pyLengthBP1D from PredicatesU0D import pyParameterUP0D from PredicatesU1D import pyDensityUP1D, pyHigherLengthUP1D, pyHigherNumberOfTurnsUP1D from logical_operators import NotUP1D from shaders import pyNonLinearVaryingThicknessShader, pySamplingShader
With the proposed API changes, these import statements will be written as follows:
from freestyle.chainingiterators import ChainSilhouetteIterator from freestyle.functions import pyInverseCurvature2DAngleF0D from freestyle.predicates import ( NotUP1D, QuantitativeInvisibilityUP1D, pyDensityUP1D, pyHigherLengthUP1D, pyHigherNumberOfTurnsUP1D, pyLengthBP1D, pyParameterUP0D, ) from freestyle.shaders import ( BezierCurveShader, ConstantColorShader, ConstantThicknessShader, SamplingShader, TextureAssignerShader, TipRemoverShader, pyNonLinearVaryingThicknessShader, pySamplingShader, ) from freestyle.types import IntegrationType, Operators
From the applicative perspective, the new organization will be much easier for style module writers to find relevant Python constructs from the freestyle.* submodules. It is remarked that there is no functional difference (no visual effects in rendering results) between the present and new module organizations.
Acknowledgement: flokkievids (Folkert Vries) for careful discussions, code review and patches through the task T37565.