diff --git a/docs/source/index.rst b/docs/source/index.rst index 7e1f55b88..5f2e6ad88 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -16,6 +16,7 @@ Enable Documentation kiva/backends.rst kiva/quickref.rst kiva/fonts.rst + kiva/compiled_path.rst credits.rst diff --git a/docs/source/kiva/compiled_path.rst b/docs/source/kiva/compiled_path.rst new file mode 100644 index 000000000..14e236943 --- /dev/null +++ b/docs/source/kiva/compiled_path.rst @@ -0,0 +1,35 @@ +CompiledPath +============ + +A path is a collection of geometric objects that can be drawn in a graphics +context with coloring and an affine transformation applied to it. It is the +basic unit of drawing in a graphics context. + +Every graphics context instance has a current path which can be manipulated by +the :ref:`kiva_path_functions`. However, some drawing operations are easier to +implement with an independent path instance +(specifically :py:meth:`draw_path_at_points`). + +An independent path instance can be created in two ways. The first is via the +:py:meth:`GraphicsContext.get_empty_path` method. The second method is to use +the :class:`CompiledPath` class imported from the backend being used. The +interface of a :class:`CompiledPath` instance is the same as the +:ref:`kiva_path_functions` (modulo :py:meth:`get_empty_path`). + +Once you have a path object, it can be drawn by adding it to the graphics +context with the :py:meth:`GraphicsContext.add_path` method (which adds the path +to the current path) and then calling any of the :ref:`kiva_drawing_functions` +which operate on the current path. + +For certain backends which support it, the +:py:meth:`GraphicsContext.draw_path_at_points` method can be used to draw a +path object at many different positions with a single function call. + +Example +------- +.. image:: images/compiled_path_ex.png + :width: 300 + :height: 300 + +.. literalinclude:: compiled_path_ex.py + :linenos: diff --git a/docs/source/kiva/compiled_path_ex.py b/docs/source/kiva/compiled_path_ex.py new file mode 100644 index 000000000..59aa6a095 --- /dev/null +++ b/docs/source/kiva/compiled_path_ex.py @@ -0,0 +1,20 @@ +from math import pi +from kiva.agg import GraphicsContextArray as GraphicsContext + +gc = GraphicsContext((600, 600)) + +path = gc.get_empty_path() +path.move_to(10, 40) +path.line_to(60, 40) +path.line_to(60, 90) +path.close_path() + +gc.scale_ctm(2, 2) +gc.translate_ctm(150, 150) +for i in range(0, 12): + gc.rotate_ctm(2*pi / 12.0) + gc.set_fill_color((i / 12.0, 0.0, 1.0 - (i / 12.0))) + gc.add_path(path) + gc.fill_path() + +gc.save("example.png") diff --git a/docs/source/kiva/images/compiled_path_ex.png b/docs/source/kiva/images/compiled_path_ex.png new file mode 100644 index 000000000..254eadfd3 Binary files /dev/null and b/docs/source/kiva/images/compiled_path_ex.png differ diff --git a/docs/source/kiva/quickref.rst b/docs/source/kiva/quickref.rst index bb7b1f089..be95c47f2 100644 --- a/docs/source/kiva/quickref.rst +++ b/docs/source/kiva/quickref.rst @@ -83,6 +83,8 @@ Clipping functions .. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.even_odd_clip +.. _kiva_path_functions: + Path functions ~~~~~~~~~~~~~~ The path has the concept of a "current point", which can be though of as the @@ -104,6 +106,7 @@ position for the geometry which is added to the path. .. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.arc .. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.arc_to +.. _kiva_drawing_functions: Drawing functions ~~~~~~~~~~~~~~~~~ @@ -215,15 +218,6 @@ to create specific kinds of :class:`AffineMatrix` instances: * ``scaling_matrix(float x_scale, float y_scale)`` * ``skewing_matrix(float x_shear, float y_shear)`` - -CompiledPath -~~~~~~~~~~~~ -A path is a collection of geometry that can be drawn in a graphics context with -coloring and an affine transformation applied to it. It is the basic unit of -drawing in a graphics context. - -Interface is the same as the `Path functions`_ . - Enumerations ~~~~~~~~~~~~ The following enumerations are represented by top-level constants in the "agg"