LivePathEffects

Google Summer of Code 2007 Project.

INTRO:

Live Path Effects allow arbitrary path-changing effects to be applied to any path object. These effects are fully live and interactive. Inkscape will remember the original path before the transformation was applied, so you will be able to remove the effect, chain several effects on the same path, adjust their parameters, etc. All the effects metadata will be stored in Inkscape-only attributes. At the same time, the resulting visible path (with the effects applied) is saved using pure SVG elements and attributes and thus visible to all SVG renderers, thus upholding Inkscape's basic principle of operation: drawings must look exactly the same in Inkscape as in any SVG-compliant renderer.

This approach will allow us to make many of the effects currently implemeted as extensions (in the Effects menu) live and interactive. Path randomization, putting pattern along path, blends, envelopes, various distortions - all these can and should be live path effects, not the clunky, slow, and inconvenient Python scripts. Fortunately, Inkscape architecture makes creating live path effects relatively easy.

The Stage I was a very simple test done by ACSpike. It proved the feasibility of the approach. Now we need to move ahead. Johan is currently working on Live Path Effects for Google's Summer of Code!

Also see: LivePathEffects Discussion

BUGS:

Put here the bugs that you have found please! I will strike-through them when I think they are fixed; test again and remove if indeed it was fixed! Btw, please SVN UP and clean build just to be sure that the bug is still present in the latest bleeding edge latest version ;)

• Skeletal Strokes
  • Stretch doesn't work
  • Can't use clones as "pattern" (object pasted on skeletal path)
• Spinbutton of effect parameters can get stuck: it keeps on increasing and increasing and is impossible to stop!

I had the same thing with opacity. It's a GTK bug. The workaround is to disable display interruptibility while you are updating document from the spinbutton's change. See how I did it here: http://inkscape.svn.sourceforge.net/viewvc/inkscape/inkscape/trunk/src/ui/widget/selected-style.cpp?r1=13149&r2=13257&sortby=date --bbyak

I added the dis-interrupt functions. Now, it only gets stuck when the dialog is not selected before pressing the spinbutton. If the item is selected, then right after the spinbutton is pressed, it gets stuck again. However now, it can be stopped by clicking the spinbutton again... --johan

• Undo history does not combine spinbutton increasing of the same parameter over and over: i.e. when the spinbutton gets stuck, the undo-history explodes.
• Reapplying a different effect does not remove the previous effect's parameters from XML. Is that a bug or feature? Bug at the moment, because they are not read back when reapplying the old effecttype
• No helperpath on shapes other than paths.

PREVIEW:

What's it going to look like?

Skeletal strokes works a bit! :D

Screenie of slant effect in action:

And gears...

BUILDING THE BRANCH:

The branch can be found on the SVN server at: https://inkscape.svn.sourceforge.net/svnroot/inkscape/inkscape/branches/live-path-effects

Extra dependencies: boost is needed to build this branch. boost because that is a dependency of lib2geom (boost headers are needed when including 2geom headers).

When all is done and Inkscape builds, there is an example file you can look at! inkscape/share/examples/live-path-effects.svg

Windows

Libs:

• Download the gsl package here: http://inkscape.modevia.com/win32libs/gsl-1.8-mingw.zip
  • unpack the bin, include, info, lib, man and share dirs into your gtk210 dir.
• Boost must be downloaded from sourceforge: http://sourceforge.net/project/showfiles.php?group_id=7586). Don't download the .zip if you can handle other fileformats aswell. The zip is buggy/slow/awfull for some reason.
  • pay attention to where you unpack boost. It must be specified in build.xml.
  • Locate the line in build.xml: <property name="boost" location="c:/boost"/>
  • change it to where you have unpacked boost. In the default build.xml line stated above, boost was unpacked such that for example the directory "C:\boost\doc" exists.
• Note that build28.xml has not been updated for this branch and therefore cannot be used (yet?).

Linux

Johan works on Fedora so all info here is tested only on Fedora (Core 6 and 7), but Inkscape and 2geom devs are able to build this one their Linux distros with no problems!

• install boost and boost-devel
• make install
• PLEASE MAIL IF IT DOES NOT WORK FOR YOU!

EMAIL HISTORY:

• BByak's email detailing live path effects, stage II*

Overall, our Stage II goals are:

1. make the system capable of handling several different effects, with new ones easy to add

2. make sure effects are correctly read in SPPath and in all shapes

3. make sure objects with effects are correctly transformed

4. make sure paths with effects are correctly node-edited

5. make sure shapes with effects are correctly handle-edited

6. make sure objects with effects are correctly written and rendered the same in Batik

Most of these goals are surprisingly easy to achieve  :) So don't be frightened by the length of this email - it's just wordy explanations.

After all this works, we can move on to implementing the Path Effects tool and handle-dragging UI for editing effects on canvas... that will be Stage III.

Now, the goals in detail:

1. The inkscape:path-effect attribute would store a string identifier of the effect to apply, or "none". If there's no such attribute, it's the same as "none". In addition, register several attributes for distortion parameters:

inkscape:path-effect-param1 inkscape:path-effect-param2 inkscape:path-effect-param3

etc. The interpretation of these will of course depend on the value of inkscape:path-effect.

Then, move the reading of these attributes into SPShape, as they will be used by all its subclasses (not only SPPath but also shapes) in the same way. (That is, sp_object_read_attr(object, "inkscape:path-effect") etc must also be in sp_shape_build.) Store the values in appropriate new members of SPShape. Write a generic function that takes SPCurve and a SPShape pointers and distorts the SPCurve according to the values of the members of SPShape. Store that function in sp-shape.cpp and declare in sp-shape.h so that it can be used from outside.

You can even code a couple useful effects at this stage  :)

2. For SPPath, it's all ready: it reads original-d, distorts it and sets the curve from that. In shapes, it's even simpler. Take SPStar for an example. In sp-star.cpp, find the line

sp_shape_set_curve_insync (SP_SHAPE (star), c, TRUE);

and just insert the call to the distortion function in sp-shape before that, passing it the curve and SP_SHAPE (star). That is all! Shapes have no need for original-d because their path is generated from the shape parameters anyway.

3. Transforming objects works like this. In "preserve" mode (see Inkscape Prefs), a transform= attribute is added or edited on all transformed objects. In the "optimize" mode (which is the default), various types of objects variously try to embed the transform, or a component thereof. If this is not possible, again, transform= attribute is added. For example, for paths, sp_path_transform can completely embed all of the transform into its curve (i.e. into d=), by transforming each path point by that matrix, so it returns identity and transform= is not set. For rects, sp_rect_set_transform embeds only translation and scaling components of the matrix; the remainder, if any, is written as transform=. For stars and ellipses, no embedding is attempted at all, so the whole transform is always written as transform=.

Now, for paths, sp_path_transform currently transforms the (SPShape*)path->curve, i.e. the distorted curve stored in base SPShape instance. But we also need to transform the original path by the same matrix too, so that it stays in sync. The easiest way to do this, which will also have other benefits, is to store the original path in SPPath as another SPCurve. That is, (SPShape*)path->curve will be the distorted path, while (SPPath*)path->original_curve will store the original path.

You will thus need to add this member in sp-path.h and to add to store the original SPCurve before distortion in that member in sp_path_set, case SP_ATTR_ORIGINAL_D. (You may need to figure out how to copy SPCurves and/or bpaths. Also don't forget to free the SPCurve when destroying the path in sp_path_release.) Then look at sp_path_transform:

   /* Transform the path */
   NRBPath dpath, spath;
   spath.path = shape->curve->bpath;
   nr_path_duplicate_transform(&dpath, &spath, xform);
   SPCurve *curve = sp_curve_new_from_bpath(dpath.path);
   if (curve) {
       sp_shape_set_curve(shape, curve, TRUE);
       sp_curve_unref(curve);
   }

And just do the same also for your original SPCurve stored in SPPath. That is all.

For shapes, you normally don't need to do anything at all. Those that don't attempt any embedding and always use transform= attribute are not affected at all. Those that do embed do it just by adjusting their internal shape parameters and regenerating the curve - for example sp_rect_set_transform calls sp_rect_set_shape(rect). Provided you inserted a distortion call into *_set_shape, you are all set.

CAVEAT: rects are the only shape which currently uses <rect>, not <path>. So you cannot apply shape effects to rects at all, until this is changed. It's on my TODO for a long time, hope I will get a round tuit soon.

4. The Inkscape::NodePath::Path reads the path from SPCurve, but after modifying it, it writes directly to the d= attribute. This needs to be changed thus: (a) if the path is distorted, read the SPCurve from SPPath, not from SPShape (i.e. the original, not the distorted one), and (b) if the path is distorted, write the edited path to inkscape:original-d= instead of d= (in update_repr_internal). Setting inkscape:original-d will trigger reading it and setting both original and distorted curves, the latter in turn triggering a redisplay of the distorted path. So I think this will be enough for nodepath to edit the source path, with the nodes generally not lying on the visible distorted path. Adding a helper display of the original path between nodepath nodes can be left for later.

5. I think here nothing at all is needed. The knotholder thing reads and writes from the shape's internal parameters, and thus is totally unaffected by the visible distorted path.

6. Look at sp_path_write: it writes the d= attribute from (SPShape*)path->curve, that is, from the distorted path. So the "same display in Batik" part is already taken care of. We only need to write the original-d so it stays in sync. Just repeat this block:

   if ( shape->curve != NULL ) {
       NArtBpath *abp = sp_curve_first_bpath(shape->curve);
       if (abp) {
           gchar *str = sp_svg_write_path(abp);
           sp_repr_set_attr(repr, "d", str);
           g_free(str);
       } else {
           sp_repr_set_attr(repr, "d", "");
       }
   } else {
       sp_repr_set_attr(repr, "d", NULL);
   }

but for path->original_curve and the inkscape:original-d attribute, and you are all set.

For shapes, again, nothing needs to be done. Except for rects, shapes' _write methods (e.g. sp_star_write) create <path> element and set its d= from the SPShape curve. This is just what we need.

That is all - as you see, it's all quite simple, logical and fits neatly. There will be gotchas of course, but overall the system looks quite straightforward and robust. I'm really excited by this.

REFERENCE:

• Inkscape-devel: path effects: our plan
• Inkscape-devel: Live Effects Discussion
• Inkscape-devel: path effect grammar
• Vector Effects in SVG 1.2