diff options
9 files changed, 394 insertions, 21 deletions
diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index 9ec8f9ad2c2..226b1ecd1f3 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -274,6 +274,12 @@ else: "mathutils.kdtree", "mathutils.noise", "freestyle", + "freestyle.chainingiterators", + "freestyle.functions", + "freestyle.predicates", + "freestyle.shaders", + "freestyle.types", + "freestyle.utils", ] # ------ @@ -316,7 +322,13 @@ try: __import__("freestyle") except ImportError: BPY_LOGGER.debug("Warning: Built without 'freestyle' module, docs incomplete...") - EXCLUDE_MODULES = list(EXCLUDE_MODULES) + ["freestyle"] + EXCLUDE_MODULES = list(EXCLUDE_MODULES) + ["freestyle", + "freestyle.chainingiterators", + "freestyle.functions", + "freestyle.predicates", + "freestyle.shaders", + "freestyle.types", + "freestyle.utils"] # examples EXAMPLES_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "examples")) @@ -1780,8 +1792,14 @@ def write_rst_importable_modules(basepath): "mathutils.geometry" : "Geometry Utilities", "mathutils.kdtree" : "KDTree Utilities", "mathutils.noise" : "Noise Utilities", - "freestyle" : "Freestyle Data Types & Operators", - } + "freestyle" : "Freestyle Module", + "freestyle.types" : "Freestyle Types", + "freestyle.predicates" : "Freestyle Predicates", + "freestyle.functions" : "Freestyle Functions", + "freestyle.chainingiterators" : "Freestyle Chaining Iterators", + "freestyle.shaders" : "Freestyle Shaders", + "freestyle.utils" : "Freestyle Utilities", + } for mod_name, mod_descr in importable_modules.items(): if mod_name not in EXCLUDE_MODULES: module = __import__(mod_name, diff --git a/release/scripts/freestyle/modules/freestyle/__init__.py b/release/scripts/freestyle/modules/freestyle/__init__.py index 5874488f684..d2795f65b6a 100644 --- a/release/scripts/freestyle/modules/freestyle/__init__.py +++ b/release/scripts/freestyle/modules/freestyle/__init__.py @@ -17,8 +17,21 @@ # ##### END GPL LICENSE BLOCK ##### """ -Top-level module containing all Freestyle stylization constructs +This module provides data types of view map components (0D and 1D +elements), base classes for defining line stylization rules +(predicates, functions, chaining iterators, and stroke shaders), as +well as helper functions for style module writing. + +Submodules: + +* :mod:`freestyle.types` +* :mod:`freestyle.predicates` +* :mod:`freestyle.functions` +* :mod:`freestyle.chainingiterators` +* :mod:`freestyle.shaders` +* :mod:`freestyle.utils` """ + # module members from . import chainingiterators, functions, predicates, shaders, types, utils diff --git a/release/scripts/freestyle/modules/freestyle/chainingiterators.py b/release/scripts/freestyle/modules/freestyle/chainingiterators.py index 8d144bf17fd..90523f94e61 100644 --- a/release/scripts/freestyle/modules/freestyle/chainingiterators.py +++ b/release/scripts/freestyle/modules/freestyle/chainingiterators.py @@ -17,10 +17,10 @@ # ##### END GPL LICENSE BLOCK ##### """ -Chaining iterators used for the chaining operation to construct long -strokes by concatenating feature edges according to selected chaining -rules. Also intended to be a collection of examples for defining -chaining iterators in Python +This module contains chaining iterators used for the chaining +operation to construct long strokes by concatenating feature edges +according to selected chaining rules. The module is also intended to +be a collection of examples for defining chaining iterators in Python. """ __all__ = ( diff --git a/release/scripts/freestyle/modules/freestyle/functions.py b/release/scripts/freestyle/modules/freestyle/functions.py index 674c1f01864..8ad7e74ea86 100644 --- a/release/scripts/freestyle/modules/freestyle/functions.py +++ b/release/scripts/freestyle/modules/freestyle/functions.py @@ -17,11 +17,99 @@ # ##### END GPL LICENSE BLOCK ##### """ -Functions operating on vertices (0D elements) and polylines (1D -elements). Also intended to be a collection of examples for predicate -definition in Python. +This module contains functions operating on vertices (0D elements) and +polylines (1D elements). The module is also intended to be a +collection of examples for function definition in Python. + +User-defined functions inherit one of the following base classes, +depending on the object type (0D or 1D) to operate on and the return +value type: + +- :class:`freestyle.types.UnaryFunction0DDouble` +- :class:`freestyle.types.UnaryFunction0DEdgeNature` +- :class:`freestyle.types.UnaryFunction0DFloat` +- :class:`freestyle.types.UnaryFunction0DId` +- :class:`freestyle.types.UnaryFunction0DMaterial` +- :class:`freestyle.types.UnaryFunction0DUnsigned` +- :class:`freestyle.types.UnaryFunction0DVec2f` +- :class:`freestyle.types.UnaryFunction0DVec3f` +- :class:`freestyle.types.UnaryFunction0DVectorViewShape` +- :class:`freestyle.types.UnaryFunction0DViewShape` +- :class:`freestyle.types.UnaryFunction1DDouble` +- :class:`freestyle.types.UnaryFunction1DEdgeNature` +- :class:`freestyle.types.UnaryFunction1DFloat` +- :class:`freestyle.types.UnaryFunction1DUnsigned` +- :class:`freestyle.types.UnaryFunction1DVec2f` +- :class:`freestyle.types.UnaryFunction1DVec3f` +- :class:`freestyle.types.UnaryFunction1DVectorViewShape` +- :class:`freestyle.types.UnaryFunction1DVoid` """ +__all__ = ( + "ChainingTimeStampF1D", + "Curvature2DAngleF0D", + "Curvature2DAngleF1D", + "CurveMaterialF0D", + "CurveNatureF0D", + "CurveNatureF1D", + "DensityF0D", + "DensityF1D", + "GetCompleteViewMapDensityF1D", + "GetCurvilinearAbscissaF0D", + "GetDirectionalViewMapDensityF1D", + "GetOccludeeF0D", + "GetOccludeeF1D", + "GetOccludersF0D", + "GetOccludersF1D", + "GetParameterF0D", + "GetProjectedXF0D", + "GetProjectedXF1D", + "GetProjectedYF0D", + "GetProjectedYF1D", + "GetProjectedZF0D", + "GetProjectedZF1D", + "GetShapeF0D", + "GetShapeF1D", + "GetSteerableViewMapDensityF1D", + "GetViewMapGradientNormF0D", + "GetViewMapGradientNormF1D", + "GetXF0D", + "GetXF1D", + "GetYF0D", + "GetYF1D", + "GetZF0D", + "GetZF1D", + "IncrementChainingTimeStampF1D", + "LocalAverageDepthF0D", + "LocalAverageDepthF1D", + "MaterialF0D", + "Normal2DF0D", + "Normal2DF1D", + "Orientation2DF1D", + "Orientation3DF1D", + "QuantitativeInvisibilityF0D", + "QuantitativeInvisibilityF1D", + "ReadCompleteViewMapPixelF0D", + "ReadMapPixelF0D", + "ReadSteerableViewMapPixelF0D", + "ShapeIdF0D", + "TimeStampF1D", + "VertexOrientation2DF0D", + "VertexOrientation3DF0D", + "ZDiscontinuityF0D", + "ZDiscontinuityF1D", + "pyCurvilinearLengthF0D", + "pyDensityAnisotropyF0D", + "pyDensityAnisotropyF1D", + "pyGetInverseProjectedZF1D", + "pyGetSquareInverseProjectedZF1D", + "pyInverseCurvature2DAngleF0D", + "pyViewMapGradientNormF0D", + "pyViewMapGradientNormF1D", + "pyViewMapGradientVectorF0D", + ) + + # module members from _freestyle import ( ChainingTimeStampF1D, diff --git a/release/scripts/freestyle/modules/freestyle/predicates.py b/release/scripts/freestyle/modules/freestyle/predicates.py index 344b89d869c..68ec9e05f6e 100644 --- a/release/scripts/freestyle/modules/freestyle/predicates.py +++ b/release/scripts/freestyle/modules/freestyle/predicates.py @@ -17,11 +17,84 @@ # ##### END GPL LICENSE BLOCK ##### """ -Predicates operating on vertices (0D elements) and polylines (1D -elements). Also intended to be a collection of examples for predicate -definition in Python +This module contains predicates operating on vertices (0D elements) +and polylines (1D elements). It is also intended to be a collection +of examples for predicate definition in Python. + +User-defined predicates inherit one of the following base classes, +depending on the object type (0D or 1D) to operate on and the arity +(unary or binary): + +- :class:`freestyle.types.BinaryPredicate0D` +- :class:`freestyle.types.BinaryPredicate1D` +- :class:`freestyle.types.UnaryPredicate0D` +- :class:`freestyle.types.UnaryPredicate1D` """ +__all__ = ( + "AndBP1D", + "AndUP1D", + "ContourUP1D", + "DensityLowerThanUP1D", + "EqualToChainingTimeStampUP1D", + "EqualToTimeStampUP1D", + "ExternalContourUP1D", + "FalseBP1D", + "FalseUP0D", + "FalseUP1D", + "Length2DBP1D", + "NotBP1D", + "NotUP1D", + "ObjectNamesUP1D", + "OrBP1D", + "OrUP1D", + "QuantitativeInvisibilityRangeUP1D", + "QuantitativeInvisibilityUP1D", + "SameShapeIdBP1D", + "ShapeUP1D", + "TrueBP1D", + "TrueUP0D", + "TrueUP1D", + "ViewMapGradientNormBP1D", + "WithinImageBoundaryUP1D", + "pyBackTVertexUP0D", + "pyClosedCurveUP1D", + "pyDensityFunctorUP1D", + "pyDensityUP1D", + "pyDensityVariableSigmaUP1D", + "pyHighDensityAnisotropyUP1D", + "pyHighDirectionalViewMapDensityUP1D", + "pyHighSteerableViewMapDensityUP1D", + "pyHighViewMapDensityUP1D", + "pyHighViewMapGradientNormUP1D", + "pyHigherCurvature2DAngleUP0D", + "pyHigherLengthUP1D", + "pyHigherNumberOfTurnsUP1D", + "pyIsInOccludersListUP1D", + "pyIsOccludedByIdListUP1D", + "pyIsOccludedByItselfUP1D", + "pyIsOccludedByUP1D", + "pyLengthBP1D", + "pyLowDirectionalViewMapDensityUP1D", + "pyLowSteerableViewMapDensityUP1D", + "pyNFirstUP1D", + "pyNatureBP1D", + "pyNatureUP1D", + "pyParameterUP0D", + "pyParameterUP0DGoodOne", + "pyShapeIdListUP1D", + "pyShapeIdUP1D", + "pyShuffleBP1D", + "pySilhouetteFirstBP1D", + "pyUEqualsUP0D", + "pyVertexNatureUP0D", + "pyViewMapGradientNormBP1D", + "pyZBP1D", + "pyZDiscontinuityBP1D", + "pyZSmallerUP1D", + ) + + # module members from _freestyle import ( ContourUP1D, diff --git a/release/scripts/freestyle/modules/freestyle/shaders.py b/release/scripts/freestyle/modules/freestyle/shaders.py index 502d9b69a97..108f5684bba 100644 --- a/release/scripts/freestyle/modules/freestyle/shaders.py +++ b/release/scripts/freestyle/modules/freestyle/shaders.py @@ -22,10 +22,80 @@ # Purpose : Stroke shaders to be used for creation of stylized strokes """ -Stroke shaders used for creation of stylized strokes. Also intended -to be a collection of examples for shader definition in Python. +This module contains stroke shaders used for creation of stylized +strokes. It is also intended to be a collection of examples for +shader definition in Python. + +User-defined stroke shaders inherit the +:class:`freestyle.types.StrokeShader` class. """ +__all__ = ( + "BackboneStretcherShader", + "BezierCurveShader", + "BlenderTextureShader", + "CalligraphicShader", + "ColorNoiseShader", + "ColorVariationPatternShader", + "ConstantColorShader", + "ConstantThicknessShader", + "ConstrainedIncreasingThicknessShader", + "GuidingLinesShader", + "IncreasingColorShader", + "IncreasingThicknessShader", + "PolygonalizationShader", + "RoundCapShader", + "SamplingShader", + "SmoothingShader", + "SpatialNoiseShader", + "SquareCapShader", + "StrokeTextureShader", + "StrokeTextureStepShader", + "TextureAssignerShader", + "ThicknessNoiseShader", + "ThicknessVariationPatternShader", + "TipRemoverShader", + "fstreamShader", + "py2DCurvatureColorShader", + "pyBackboneStretcherNoCuspShader", + "pyBackboneStretcherShader", + "pyBluePrintCirclesShader", + "pyBluePrintDirectedSquaresShader", + "pyBluePrintEllipsesShader", + "pyBluePrintSquaresShader", + "pyConstantColorShader", + "pyConstantThicknessShader", + "pyConstrainedIncreasingThicknessShader", + "pyDecreasingThicknessShader", + "pyDepthDiscontinuityThicknessShader", + "pyDiffusion2Shader", + "pyFXSVaryingThicknessWithDensityShader", + "pyGuidingLineShader", + "pyHLRShader", + "pyImportance2DThicknessShader", + "pyImportance3DThicknessShader", + "pyIncreasingColorShader", + "pyIncreasingThicknessShader", + "pyInterpolateColorShader", + "pyLengthDependingBackboneStretcherShader", + "pyMaterialColorShader", + "pyModulateAlphaShader", + "pyNonLinearVaryingThicknessShader", + "pyPerlinNoise1DShader", + "pyPerlinNoise2DShader", + "pyRandomColorShader", + "pySLERPThicknessShader", + "pySamplingShader", + "pySinusDisplacementShader", + "pyTVertexRemoverShader", + "pyTVertexThickenerShader", + "pyTimeColorShader", + "pyTipRemoverShader", + "pyZDependingThicknessShader", + "streamShader", + ) + + # module members from _freestyle import ( BackboneStretcherShader, diff --git a/release/scripts/freestyle/modules/freestyle/types.py b/release/scripts/freestyle/modules/freestyle/types.py index 8f596fd275c..22f80f41dfc 100644 --- a/release/scripts/freestyle/modules/freestyle/types.py +++ b/release/scripts/freestyle/modules/freestyle/types.py @@ -17,9 +17,96 @@ # ##### END GPL LICENSE BLOCK ##### """ -Submodule containing all Freestyle types. +This module contains core classes of the Freestyle Python API, +including data types of view map components (0D and 1D elements), base +classes for user-defined line stylization rules (predicates, +functions, chaining iterators, and stroke shaders), and operators. + +Class hierarchy: + +- :class:`BBox` +- :class:`BinaryPredicate0D` +- :class:`BinaryPredicate1D` +- :class:`Id` +- :class:`Interface0D` + + - :class:`CurvePoint` + + - :class:`StrokeVertex` + + - :class:`SVertex` + - :class:`ViewVertex` + + - :class:`NonTVertex` + - :class:`TVertex` + +- :class:`Interface1D` + + - :class:`Curve` + + - :class:`Chain` + + - :class:`FEdge` + + - :class:`FEdgeSharp` + - :class:`FEdgeSmooth` + + - :class:`Stroke` + - :class:`ViewEdge` + +- :class:`Iterator` + + - :class:`AdjacencyIterator` + - :class:`CurvePointIterator` + - :class:`Interface0DIterator` + - :class:`SVertexIterator` + - :class:`StrokeVertexIterator` + - :class:`ViewEdgeIterator` + + - :class:`ChainingIterator` + + - :class:`orientedViewEdgeIterator` + +- :class:`Material` +- :class:`Noise` +- :class:`Operators` +- :class:`SShape` +- :class:`StrokeAttribute` +- :class:`StrokeShader` +- :class:`UnaryFunction0D` + + - :class:`UnaryFunction0DDouble` + - :class:`UnaryFunction0DEdgeNature` + - :class:`UnaryFunction0DFloat` + - :class:`UnaryFunction0DId` + - :class:`UnaryFunction0DMaterial` + - :class:`UnaryFunction0DUnsigned` + - :class:`UnaryFunction0DVec2f` + - :class:`UnaryFunction0DVec3f` + - :class:`UnaryFunction0DVectorViewShape` + - :class:`UnaryFunction0DViewShape` + +- :class:`UnaryFunction1D` + + - :class:`UnaryFunction1DDouble` + - :class:`UnaryFunction1DEdgeNature` + - :class:`UnaryFunction1DFloat` + - :class:`UnaryFunction1DUnsigned` + - :class:`UnaryFunction1DVec2f` + - :class:`UnaryFunction1DVec3f` + - :class:`UnaryFunction1DVectorViewShape` + - :class:`UnaryFunction1DVoid` + +- :class:`UnaryPredicate0D` +- :class:`UnaryPredicate1D` +- :class:`ViewMap` +- :class:`ViewShape` +- :class:`IntegrationType` +- :class:`MediumType` +- :class:`Nature` """ + # module members from _freestyle import ( AdjacencyIterator, diff --git a/release/scripts/freestyle/modules/freestyle/utils.py b/release/scripts/freestyle/modules/freestyle/utils.py index e6dca93b777..e0679a53954 100644 --- a/release/scripts/freestyle/modules/freestyle/utils.py +++ b/release/scripts/freestyle/modules/freestyle/utils.py @@ -17,9 +17,33 @@ # ##### END GPL LICENSE BLOCK ##### """ -Helper functions used for Freestyle style module writing. +This module contains helper functions used for Freestyle style module +writing. """ +__all__ = ( + "ContextFunctions", + "bound", + "bounding_box", + "find_matching_vertex", + "getCurrentScene", + "get_chain_length", + "get_test_stroke", + "integrate", + "iter_distance_along_stroke", + "iter_distance_from_camera", + "iter_distance_from_object", + "iter_material_value", + "iter_t2d_along_stroke", + "pairwise", + "phase_to_direction", + "rgb_to_bw", + "stroke_curvature", + "stroke_normal", + "tripplewise", + ) + + # module members from _freestyle import ( ContextFunctions, @@ -27,13 +51,13 @@ from _freestyle import ( integrate, ) +# constructs for helper functions in Python from freestyle.types import ( Interface0DIterator, Stroke, StrokeVertexIterator, ) - from mathutils import Vector from functools import lru_cache, namedtuple from math import cos, sin, pi diff --git a/source/blender/freestyle/intern/python/Iterator/BPy_Interface0DIterator.cpp b/source/blender/freestyle/intern/python/Iterator/BPy_Interface0DIterator.cpp index fca4c979bbb..c972db1e680 100644 --- a/source/blender/freestyle/intern/python/Iterator/BPy_Interface0DIterator.cpp +++ b/source/blender/freestyle/intern/python/Iterator/BPy_Interface0DIterator.cpp @@ -138,8 +138,8 @@ static PyObject *Interface0DIterator_iternext(BPy_Interface0DIterator *self) PyDoc_STRVAR(Interface0DIterator_object_doc, "The 0D object currently pointed to by this iterator. Note that the object\n" "may be an instance of an Interface0D subclass. For example if the iterator\n" -"has been created from :method:`Stroke.vertices_begin`, the .object property\n" -"refers to a :class:`StrokeVertex` object.\n" +"has been created from the `vertices_begin()` method of the :class:`Stroke`\n" +"class, the .object property refers to a :class:`StrokeVertex` object.\n" "\n" ":type: :class:`Interface0D` or one of its subclasses."); |