Inkscape Wiki - User contributions [en]

Script extensions

2017-11-06T20:59:35Z

Matyilona: /* See Also */ Adding link to Python modules for extensions

[Note: This page concerns using scripting languages to create new Inkscape functionality. To access Inkscape functionality from scripting languages (i.e. to script Inkscape), see the Inkscape man page (especially in the development version or v0.46 or later, which provide --select and --verb options), or see the work in the src/extension/script directory of Inkscape source.]

== Introduction ==

Traditional Unix scripts can be used to extend Inkscape's functionality. Such programs read a stream of data on standard input, transform the data in some way, and then write the modified data to standard output. This is an easy way to expand Inkscape and provide custom functionality without learning the internals of Inkscape. Libraries for reading and writing SVG data exist for many programming languages, and most provide support for XML. This tutorial describes the "ins and outs" of writing one of these scripts and making it work with Inkscape's core functionality.

== Script functions ==

There are three kinds of functions that can be added with a script:

* Input, providing translation from a file format to SVG
* Output, providing translation from SVG to a format
* Effect, taking in SVG, changing it, and then outputting SVG

While all of these are very similar in the scripting interface, there are slight differences between them.

== Interaction ==

It is important for a script author to understand how Inkscape and scripts communicate.

<pre>
(interpreter)? your_script (--param=value)* /path/to/input[[/SVGfile]] | inkscape
</pre>

Inkscape runs your script (optionally with an interpreter, more info here: [[Extension_Interpreters | Extension Interpreters]]), passing it any number of parameters in long gnu style. The final argument is the name of the temporary svg file your script should read. After processing, the script should return the modified svg file to inkscape on STDOUT.

== Important Tips ==

* Receive the inkscape arguments.
* Clear temp files if it creates one.
* Write full changed SVG to the default output.
* Don't break an <code>xml:space="preserve"</code> area.
* Send error text to the error output and help the user.

== Extension description file ==

In order for Inkscape to make use of an external script or program, you must describe that script to Inkscape using an INX file. See the inkscape share directory for examples.

The INX file allows you to:
* Define the script file and other dependencies.
* List all parameters and their types (to generate an input dialog window).
* Mark dialog window text for translation.
* Define an Inkscape menu entry.
* Chain extensions.

See [[INX extension descriptor format]] for help creating an INX file.

=== Parameters ===
The INX file describes which parameters the extension needs. Inkscape will prompt the user with a UI to fill out these parameters before the extension is called. Each parameter will be passed to the script as <code>--paramname=paramvalue</code>. Specify the script file to be run with the <code><command></code> tag.

For example, if you have described a string parameter with name <code>string1</code> in the INX file, Inkscape will present a textbox to the user. When the user fills in <code>text</code> and presses Apply, it will pass <code>--string1="text"</code> to the script.

There are several types of parameters that can be requested by the INX description:

* String (textbox)
* Boolean (checkbox)
* Int (numeric textbox)
* Float (numeric textbox)
* Enum (drop down selection list)
* Option group (radio buttons)
* Notebook (pages/tabs)
* Description (not a parameter, provides static text)

For a detailed description of all parameters and input controls, see [[INX Parameters]].

== Verbs interface and the id tag ==
When you define your extension you will have name and id tags at the top of the INX file.
The id tag is used for two purposes:

* as an identifier in the config file so the most recently used parameter values are stored and recalled each time the extension is run.
* as the identifier for the verbs interface so your extension can be run from the command line.

Inkscape can be called from the command line and the extension can be run using this interface.

E.g. Assuming the id in your extension was <code><id>foo.github.my_extension</id></code>

<code>inkscape --verb foo.github.my_extension</code> will open Inkscape and open the dialog to your extension..

<code>inkscape --verb foo.github.my_extension.noprefs</code> will open inkscape and run the dialog with the last set values.

<code>inkscape --verb ZoomPage --verb foo.github.my_extension</code> will open inkscape, Zoom full page, and open the dialog to your extension.

<code>inkscape --verb-list</code> will show you the available verbs.

== Installing ==

Installing is as simple as copying the script (unless it resides in your path) and its INX file to the inkscape/share/extensions ($HOME/.config/inkscape/extensions) directory. (If you install a script in your home directory be sure to copy the dependencies.)

If you are looking to use scripts that have already been written, the most difficult part will likely be the installation. Since scripts are separate programs they may have any number of dependencies that are not included with inkscape. Currently, the best way to find missing dependencies is by reading the error messages produced by running the script from the command line.

== See Also ==

*[[Generating_objects_from_extensions]]. How to use a script to generate actual objects inside SVG documents.

*[[PythonEffectTutorial]]

*[[Python modules for extensions]]

*[[Tips For Python Script Extensions]]

[[Category:Developer Documentation]]
[[Category:Extensions]]

Generating objects from extensions

2017-11-06T20:56:52Z

Matyilona: Adding link to Python modules for extensions

If you need an extension to generate an object in Inkscape, there are many tools that already exist to help you. <tt>inkex.py</tt> is the most notable, as this provides the routines to insert the SVG element into the XML tree of the SVG document, for more info on these is available at [[Python modules for extensions]].

There is currently no universal set of tools to allow a single function to be called, because different extension have different attibutes for thir objects. For example, the barcode extension merely needs a black rectangle with no stroke, but another may need a way to set the stroke width, dashes and opacity. Thus, it is often best to write your own subroutine for generating your objects.

==A simple example==
Let's look at a simple Python function for drawing a black rectangle:
<pre>
#SVG element generation routine
def draw_SVG_square((w,h), (x,y), parent):

style = { 'stroke' : 'none',
'stroke-width' : '1',
'fill' : '#000000'
}

attribs = {
'style' : simplestyle.formatStyle(style),
'height' : str(h),
'width' : str(w),
'x' : str(x),
'y' : str(y)
}
circ = inkex.etree.SubElement(parent, inkex.addNS('rect','svg'), attribs )
</pre>

The first thing to notice is that all the attributes of the object are stored in a dictionary format, with everything being a string. This means you have to convert all your parameters to strings if appropriate (like the <tt>height</tt> and <tt>width</tt> attributes).

Next, all the style attributes (colours, widths, fonts, etc) are put together in SVG under <tt>style</tt>. To generate this string, there exists a helper function <tt>simplestyle.formatStyle()</tt>. You simply feed this function a dictionary of the styles you want, just like the attributes. You can then use this directly as the style attribute.

The next thing to see is how to add the element to the XML tree. <tt>inkex.py</tt> has the function to do this using the LXML parser. This needs to be given the "parent" of the object (we'll come back to this), the "type" of the object, and the attributes of the object.

The type of the object is in the <tt>svg</tt> namespace, which means it begins <tt>svg:</tt> (for a rectangle, it is <tt>svg:rect</tt>). LXML cannot parse colons, so we use the <tt>inkex.addNS</tt> to prepend the namespace.

The attributes of the object just needs to be passed the dictionary <tt>attribs</tt> we made earlier.

The "parent" of the object is the containing element. This is usually a group or a layer. This will be passed in by the calling function, and we will see it in action later.

When this function is run with the right parameters, the rectangle will be added to the SVG document.

==Getting the parent==

Finding the parent is easy: you can just pass in the current layer from the <tt>self</tt> object if you like:
<pre><nowiki>
parent = self.current_layer
draw_SVG_square((1,1), (0,0), parent)
</nowiki></pre>

This will just plonk the rectangle into the document, centred on the origin.

Alternatively, you can create a group much like any other object:
<pre><nowiki>
centre = self.view_center #Put in in the centre of the current view
grp_transform = 'translate' + str( centre )

grp_name = 'Group Name'
grp_attribs = {inkex.addNS('label','inkscape'):grp_name,
'transform':grp_transform }
grp = inkex.etree.SubElement(self.current_layer, 'g', grp_attribs)#the group to put everything in
</nowiki></pre>

By the way, any object can be assigned a name as we did there, which is often helpful when generating many objects:

<pre><nowiki>
inkex.addNS('label','inkscape') : name
</nowiki></pre>

By setting the transform as <tt>self.view_center</tt>, we made sure the origin of the group is in the centre of the current view of the document. We will come back to transforms later.

The <tt>grp</tt> object can now be used as a parent for the rectangle:
<pre><nowiki>
draw_SVG_square((1,1), (0,0), grp)
</nowiki></pre>
This will draw a 1×1 black square in the center of the view.

==Transforms==

It is easy to transform an object: just supply a string like the folllowing as the <tt>transform</tt> attribute of the element:
*<tt>trans = 'translate(10,10)'</tt>
*<tt>trans = 'translate(10,10) rotate(10)'</tt>
*<tt>trans = 'skewX(-1)'</tt>

Available commands: <tt>translate, scale, rotate, skewX, skewY, matrix</tt>. The transforms are composed in left-right order (i.e. the translate comes first in the second example).

==More Examples==

===Ellipses===

Ellipses are actually path elements, but Inkscape generates the nodes automatically if you feed it the correct attributes in the Sodipodi namespace. The vital ones are <tt>rx, ry, cx, cy</tt>.

Ellipses require some attributes in the <tt>sodipodi:</tt> namespace, so we also use the <tt>addNS()</tt> function in the attribute dictionary:

<pre><nowiki>
def draw_SVG_ellipse((rx, ry), (cx, cy), parent, start_end=0,2*pi),transform='' ):

style = { 'stroke' : '#000000',
'stroke-width' : '1',
'fill' : 'none' }
ell_attribs = {'style':simplestyle.formatStyle(style),
inkex.addNS('cx','sodipodi') :str(cx),
inkex.addNS('cy','sodipodi') :str(cy),
inkex.addNS('rx','sodipodi') :str(rx),
inkex.addNS('ry','sodipodi') :str(ry),
inkex.addNS('start','sodipodi') :str(start_end[0]),
inkex.addNS('end','sodipodi') :str(start_end[1]),
inkex.addNS('open','sodipodi') :'true', #all ellipse sectors we will draw are open
inkex.addNS('type','sodipodi') :'arc',
'transform' :transform

}
ell = inkex.etree.SubElement(parent, inkex.addNS('path','svg'), ell_attribs )
</nowiki></pre>

This will draw an open arc, with a black stroke of width 1 and no fill. The transform here can be passed in from outside.

If in doubt about the right attribute name and format, just check a similar object in the XML viewer in Inkscape.

===Line Segment===

Paths can be quite tricky to get the hang of if you don't know the meaning of the letters. Read the SVG specification for a full list.

Here, the style information has been passed in from outside the function.

<pre><nowiki>
#draw an SVG line segment between the given (raw) points
def draw_SVG_line( (x1, y1), (x2, y2), style, name, parent):
line_style = { 'stroke': style.l_col,
'stroke-width':str(style.l_th),
'fill': style.l_fill
}

line_attribs = {'style' : simplestyle.formatStyle(line_style),
inkex.addNS('label','inkscape') : name,
'd' : 'M '+str(x1)+','+str(y1)+' L '+str(x2)+','+str(y2)}

line = inkex.etree.SubElement(parent, inkex.addNS('path','svg'), line_attribs )
</nowiki></pre>

[[Category:Developer Documentation]]
[[Category:Extensions]]

PythonEffectTutorial

2017-11-06T20:53:06Z

Matyilona: /* Effect Extension Script */ provide link to documentation of inkex.py and simplestyle.py

Effect extensions in Inkscape means a simple programs or scripts that reads an SVG file from standard input, transforms it somehow and prints it to the standard output. Usually Inkscape sits on both ends, providing the file with some parameters as input first and finally reading the output, which is then used for further work.
[[Image:Effect_flow.svg|thumb|right|400px]]

We will write a simple effect extension script in [http://docs.python.org Python] that will create a new "Hello World!" or "Hello <value of --what option>!" string in the center of document and inside a new layer.

== Effect Extension Script ==

First of all create a file ''hello_world.py'' and make it executable with the Python interpreter with the well-known directive:
<pre>
#!/usr/bin/env python
</pre>

If you're going to put the file somewhere else than into Inkscape's installation directory, we need to add a path so that python can find the necessary modules:
<pre>
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary
</pre>

Import the ''inkex.py'' file with the ''Effect'' base class that will do most of the work for us and the ''simplestyle.py'' module with support functions for working with CSS styles, for more information on these modules see [[Python modules for extensions]]. We will use just the ''formatStyle'' function from this module:
<pre>
import inkex
from simplestyle import *
</pre>

Declare a ''HelloWordEffect'' class that inherits from ''Effect'' and write a constructor where the base class is initialized and script options for the option parser are defined:
<pre>
class HelloWorldEffect(inkex.Effect):
def __init__(self):
inkex.Effect.__init__(self)
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')
</pre>

The complete documentation for the ''OptionParser'' class can be found at [https://docs.python.org/2/library/optparse.html docs.python.org]. Here we just use the ''add_option'' method which has as first argument a short option name, as second argument a long option name and then a few other arguments with this meaning:

* ''action'' - An action which should be done with option value. In this case we use action ''store'' which will store option value in ''self.options.<destination>'' attribute.
* ''type'' - Type of option value. We use string here.
* ''dest'' - Destination of option action specified by ''action'' argument. Using ''what'' value we say that we want to store option value to self.options.what attribute.
* ''default'' - Defalut value for this option if it is not specified.
* ''help'' - A help string that will be displayed if script will be given no arguments or some option or argument will have wrong syntax.

Inkscape will create a GUI form with widgets for all specified options and prefill them with the default values specified using the ''.inx'' file for this extension which we will write later.

We need to override only one ''Effect'' class method to provide the desired effect functionality:
<pre>
def effect(self):
what = self.options.what
</pre>
As you can imagine we just stored the ''--what'' option value to the ''what'' variable.

Now we will finally start to do something. We will have to work with the XML representation of the SVG document that we can access via ''Effect'''s ''self.document'' attribute.
It is of lxml's '' _ElementTree'' class type. Complete documentation for the lxml package can be found at [http://lxml.de/ lxml.de].

First we get SVG document's ''svg'' element and its dimensions:
<pre>
svg = self.document.getroot()
# or alternatively
# svg = self.document.xpath('//svg:svg',namespaces=inkex.NSS)[0]

# Again, there are two ways to get the attibutes:
width = self.unittouu(svg.get('width'))
height = self.unittouu(svg.attrib['height'])
</pre>
The ''xpath'' function returns a list of all matching elements so we just use the first one of them.

We now create an SVG group element ('' 'g' '') and "mark" it as a layer using Inkscape' SVG extensions:
<pre>
layer = inkex.etree.SubElement(svg, 'g')
layer.set(inkex.addNS('label', 'inkscape'), 'Hello %s Layer' % (what))
layer.set(inkex.addNS('groupmode', 'inkscape'), 'layer')
</pre>
This creates ''inkscape:label'' and ''inkscape:groupmode'' attributes, which will only be read by Inkscape or compatible applications. To all other viewers, this new element looks just like a plain SVG group.

Now we create an SVG text element with a text value containing the "Hello World" string:
<pre>
text = inkex.etree.Element(inkex.addNS('text','svg'))
text.text = 'Hello %s!' % (what)
</pre>

Set the position of the text to the center of SVG document:
<pre>
text.set('x', str(width / 2))
text.set('y', str(height / 2))
</pre>

If we want to center the text on its position we need to define the CSS style of the SVG ''text'' element. Actually we use the ''text-anchor'' SVG extension to CSS styles to do that work:
<pre>
style = {'text-align' : 'center', 'text-anchor' : 'middle'}
text.set('style', formatStyle(style))
</pre>

Finally we connect all created elements together and put them into the SVG document:
<pre>
layer.append(text)
</pre>

We just defined a class that inherited from the original effect extension so we have to create an instance of it and execute it in the main control flow:
<pre>
effect = HelloWorldEffect()
effect.affect()
</pre>

== Extension Description File ==

To include script in Inkscape's main menu create ''hello_world.inx'' file describing script evokation.

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<inkscape-extension xmlns="http://www.inkscape.org/namespace/inkscape/extension">
<_name>Hello World!</_name>
<id>org.ekips.filter.hello_world</id>
<dependency type="executable" location="extensions">hello_world.py</dependency>
<dependency type="executable" location="extensions">inkex.py</dependency>
<param name="what" type="string" _gui-text="What would you like to greet?">World</param>
<effect>
<object-type>all</object-type>
<effects-menu>
<submenu _name="Examples"/>
</effects-menu>
</effect>
<script>
<command reldir="extensions" interpreter="python">hello_world.py</command>
</script>
</inkscape-extension>
</pre>

Create ''<param>'' element for every option of a script and ''<dependency>'' for every included module which is not from Python standard library. Inkscape will search for this modules in directory with script. ''<effect>'' element and its descendants defines name of menu item evoking our new "Hello World!" extension.

If the inx file isn't well formed or if any of the dependencies wasn't met, the extension won't show up in the menu. If your extension doesn't show up, take a look at extension-errors.log, which may give you a hint why it wasn't loaded.

== Installation ==

To install a new extenstion just put ''hello_world.py'' and ''hello_world.inx'' files with all dependency modules to the ''<path_to_inkscape>/extensions'' or ''~/.config/inkscape/extensions'' directory. On Linux you will probably have to make the python script executable first if you haven't done this yet. This is usually done by the usual command (or in your preferred file manager):
<pre>
$ chmod a+x hello_world.py
</pre>

Now start Inkscape. A new menu item ''Hello World!'' in ''Extensions->Examples'' menu should appear.

== Complete Source Code ==

Here is a complete commented source pre of ''hello_world.py'' script file:

<pre>
#!/usr/bin/env python

# These two lines are only needed if you don't put the script directly into
# the installation directory
import sys
sys.path.append('/usr/share/inkscape/extensions')

# We will use the inkex module with the predefined Effect base class.
import inkex
# The simplestyle module provides functions for style parsing.
from simplestyle import *

class HelloWorldEffect(inkex.Effect):
"""
Example Inkscape effect extension.
Creates a new layer with a "Hello World!" text centered in the middle of the document.
"""
def __init__(self):
"""
Constructor.
Defines the "--what" option of a script.
"""
# Call the base class constructor.
inkex.Effect.__init__(self)

# Define string option "--what" with "-w" shortcut and default value "World".
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')

def effect(self):
"""
Effect behaviour.
Overrides base class' method and inserts "Hello World" text into SVG document.
"""
# Get script's "--what" option value.
what = self.options.what

# Get access to main SVG document element and get its dimensions.
svg = self.document.getroot()
# or alternatively
# svg = self.document.xpath('//svg:svg',namespaces=inkex.NSS)[0]

# Again, there are two ways to get the attibutes:
width = self.unittouu(svg.get('width'))
height = self.unittouu(svg.attrib['height'])

# Create a new layer.
layer = inkex.etree.SubElement(svg, 'g')
layer.set(inkex.addNS('label', 'inkscape'), 'Hello %s Layer' % (what))
layer.set(inkex.addNS('groupmode', 'inkscape'), 'layer')

# Create text element
text = inkex.etree.Element(inkex.addNS('text','svg'))
text.text = 'Hello %s!' % (what)

# Set text position to center of document.
text.set('x', str(width / 2))
text.set('y', str(height / 2))

# Center text horizontally with CSS style.
style = {'text-align' : 'center', 'text-anchor': 'middle'}
text.set('style', formatStyle(style))

# Connect elements together.
layer.append(text)

# Create effect instance and apply it.
effect = HelloWorldEffect()
effect.affect()
</pre>

Last edited by --[[User:Rubikcube|Rubikcube]] 21:18, 7 August 2008 (UTC), based on a version by
[[User:Blackhex|Blackhex]] 11:59, 26 April 2007 (UTC)
[[Category:Developer Documentation]]
[[Category:Extensions]]

Python modules for extensions

2017-11-04T21:55:35Z

Matyilona: /* simpletransform.py */ Detailed description for simpletransform

[[Category:Extensions]]

These modules are provided as part of Inkscape and can be found in /usr/share/inkscape/extensions on GNU/Linux, ... on Windows, and ... on Mac OS X along with the extensions bundled with Inkscape. They can be <code>import</code>ed from an extension just like any other python module.

== inkex.py ==

This module encapsulates the basic behavior of a script extension, allowing the author to concentrate on manipulating the SVG data. It relies on [http://lxml.de/tutorial.html <code>lxml.etree</code>] to work with the XML tree. inkex.py was originally designed to provide the Effect (filter) extension type, but has been used for Input/Output extensions simply by overriding additional class methods.

=== Functions ===
inkex.py provides the following functions:
;<code>errormsg( msg )</code>
: End-user visible error message, it should always be used with translation: <code>inkex.errormsg(_("This extension requires two selected paths"))</code>
;<code>addNS( tag, ns=None )</code>
: Returns the selected tag, with the namespace applied. The namespace is selected from a list supplied with the module.

=== The <code>Effect</code> class ===

The most important part of inkex.py is the <code>Effect</code> class. To implement an effect type extension in Python see [[PythonEffectTutorial]]

==== Methods ====
;<code>effect()</code>
: You should overwrite this method with your own, as shown in [[PythonEffectTutorial#Effect Extension Script]]
;<code>getElementById( id )</code>
: Returns the firs found element with given id, as a <code>lxml</code> element.
;<code>getParentNode( node )</code>
: Returns the parent of <code>node</code>. Probably the same as <code>node.getparent()</code> from <code>lxml</code>?
;<code>createGuide( x, y, angle )</code>
: Creates guide at position (<code>x</code>,<code>y</code>), with angle <code>angle</code>.
;<code>affect()</code>
: Actuate the script.
;<code>xpathSingle( path )</code>
: An xpath wrapper to return a single node.
;<code>uniqueId( old_id )</code>
: Return an id that is unique in the document given a proposed id, by appending random alphanumeric characters to it.
;<code>getDocumentWidth()</code>
: Return width of document, as a string.
;<code>getDocumentHeight()</code>
: Return height of document, as a string.
;<code>getDocumentUnit()</code>
: Return a string representing the default unit for the document. Full list of possible units is defined in the module.
;<code>unittouu( string )</code>
: Convert given value (as a string, e.g: "4px") to units used by the document. Returns float.
;<code>uutounit( value, unit )</code>
: Convert a value (float) in document default units to given units.

==== Properties ====

;<code>document</code>
: DOM document, as a <code>lxml.etree</code>.
;<code>selected</code>
: A dict mapping ids to nodes, for all nodes selected in Inkscape.
;<code>doc_ids</code>:
: A dict mapping ids to the constant 1, for all of the ids used in the original document. Does not get automatically updated when adding elements.
;<code>options</code>
: Options passed to the script.

== simplestyle.py ==
Provides methods for dealing with css data embedded in SVG's style attribute. When a color is represented as integers they should be in the (0, 255) range, when represented as floats, they should be in the (0.0, 1.0) range.

;<code>parseStyle( string )</code>
: Create a dictionary of attribute-value pairs from the value of an inline style attribute.
;<code>formatStyle( dict )</code>
: Format an inline style attribute from a dictionary of attribute-value pairs, values are converted to strings by <code>str()</code>.
;<code>isColor( c )</code>
: Determine if <code>c</code> is a valid color.
;<code>parseColor( c )</code>
: Creates a rgb int array. <code>c</code> can be any type of string representation of a color.
;<code>formatColoria( a )</code>
: Convert int array to #rrggbb string.
;<code>formatColorfa( a )</code>
: Convert float array to #rrggbb string.
;<code>formatColor3i( r, g, b )</code>
: Convert 3 ints to #rrggbb string.
;<code>formatColor3f( r, g, b )</code>
: Convert 3 floats to #rrggbb string.
;<code>svgcolors</code>
: A dictionary defining legal color names and corresponding color values.

== simplepath.py ==
Provides functions to round trip svg path d="" attribute data and a simple path format mimicking that datastructure, and additional functions for scaling translating and rotating path data.

;<code>parsePath( d )</code>
: Parse SVG path and return an array of segments. Removes all shorthand notation. Converts coordinates to absolute. Returns list of <code>[ command, params ]</code> list.

;<code>formatPath( l )</code>
: Format path data from a list. Returns the string representing the path, <code>l</code> should have the same format as returned by <code>parsePath</code>.

;<code>translatePath( p, x, y ), scalePath( p, x, y ), rotatePath( p, angle, cx=0, cy=0 )</code>
: Transforms path <code>p</code>.

== cubicsuperpath.py ==
An alternative path representation, accessing both handles of a node at once. Loses a paths open/closed identity.

;<code>CubicSuperPath( simplepath )</code>
: Given a path as a list returned by <code>simplepath.parsePath</code>, it returns a list of lists in <code>[ [ [ h1_0, pt_0, h2_0 ], [ h1_1, pt_1, h2_1 ], ... ], [ [ h1_m, pt_m, h2_m ], ...], ... ]</code> format, where <code>h1_n</code> and <code>h2_n</code> are handles for the node at point <code>pt_n</code>. All points/handles are lists of two floats (<code>[ x, y ]</code>). The list is the representation of the whole path, the first level sub-lists are representations of sub-paths, and the lists containing 3 points represent the individual control nodes.

;<code>unCubicSuperPath( csp )</code>
: Given a path in the format returned by <code>CubicSuperPath</code> returns it in the format used by <code>simplepath</code>.

;<code>parsePath( d )</code>
: Parse a string representation directly.

;<code>formatPath( p )</code>
: Format path as a string.

== simpletransform.py ==

Provides code to easily transform objects. Transformations are represented as [https://en.wikipedia.org/wiki/Transformation_matrix#Affine_transformations affine transformation matrices]. Since the last row of such matrices is always the same ([0,0,1]) it is not included, so the final matrix is a list of two lists of 3 floats containing the first two rows of the matrix. Wherever <code>E</code> is used as a default argument it means the identity matrix, a transformation that does nothing.

;<code>parseTransform( transform, mat=E )</code>
: Takes a string representing a transformation (like a SVG nodes transform attribute), and returns a transformation matrix. If <code>mat</code> is supplied, the returned matrix is <code>composeTransform( mat, matrix)</code>.

;<code>formatTransform( mat )</code>
: Returns string representation for transform (for use in transform attribute).

;<code>invertTransform( mat )</code>
: Returns inverse of transformation given by <code>mat</code>.

;<code>composeTransform( mat1, mat2 )</code>
: Returns matrix representing a transformation equal to applying <code>mat1</code> then <code>mat2</code>.

;<code>composeParents( node, mat )</code>
: Returns <code>mat</code> composed with every transformation that applies to <code>node</code>. If a node has a transformation applied to it, and is part of a group that has an other transformation applied to it, both apply to the node. This function composes all the nodes ancestors' transformations.

;<code>applyTransformToNode( mat, node )</code>
: Apply transform to <code>node</code> by setting its transform attribute, does not change coordinates in any part of node.

;<code>applyTransformToPath( mat, path )</code>
: Apply transform to path, by changing the coordinates of points and handles. <code>path</code> has to be a representation used by <code>SuperCubicPath</code>.

;<code>applyTransformToPoint( mat, point )</code>
: Apply transform to a point given as a list <code>[ x, y ]</code>.

;<code>fuseTransform( node )</code>
: Removes the transform attribute from a node, and applies it to the node, changing the nodes points' coordinates.

The following functions might be broken out into a separate module in the future (see comment in code).

;<code>roughBBox( path )</code>
: Returns four floats <code>xmin, xMax, ymin, yMax</code>, the coordinates for a rough bounding box. <code>path</code> has to be a representation used by <code>SuperCubicPath</code>.

;<code>refinedBBox( path )</code>
: Same as the above, takes longer to calculate but more precise.

;<code>computeBBox( node_list, mat = E )</code>
: Returns the bounding box for a list of nodes. If supplied <code>mat</code> is applied to the nodes before calculating the bounding box. Uses <code>refinedBBox</code> when applicable, text nodes are not yet supported.

;<code>computePointInNode( pt, node, mat = E )</code>
: Given a point and a node, returns the coordinates that when transformed by the nodes and its ancestors transformations are the same as <code>pt</code>. For example take a circle created with its centre at (0,0) and then transformed by applying a pure translation to (1,0). If the centre is now set to (0,1) the centre of the circle will actually be at (1,1) because the transformation still applies. It can be avoided by using <code>computePointInNode( [ 0, 1 ], circle )</code> which gives (-1,1), setting the centre to this the circle will appear at the desired (0,1).

== pturtle.py ==

Provides turtle graphics primitives with svg path data output

== beziermisc.py ==
Utility functions for working with bezier curves

== cspsubdiv.py ==
Decompose a path into polylines

== ff*.py ==

an obscure set of tools for dealing with musical scales.

Python modules for extensions

2017-11-04T19:20:00Z

Matyilona: /* cubicsuperpath.py */ typo

[[Category:Extensions]]

These modules are provided as part of Inkscape and can be found in /usr/share/inkscape/extensions on GNU/Linux, ... on Windows, and ... on Mac OS X along with the extensions bundled with Inkscape. They can be <code>import</code>ed from an extension just like any other python module.

== inkex.py ==

This module encapsulates the basic behavior of a script extension, allowing the author to concentrate on manipulating the SVG data. It relies on [http://lxml.de/tutorial.html <code>lxml.etree</code>] to work with the XML tree. inkex.py was originally designed to provide the Effect (filter) extension type, but has been used for Input/Output extensions simply by overriding additional class methods.

=== Functions ===
inkex.py provides the following functions:
;<code>errormsg( msg )</code>
: End-user visible error message, it should always be used with translation: <code>inkex.errormsg(_("This extension requires two selected paths"))</code>
;<code>addNS( tag, ns=None )</code>
: Returns the selected tag, with the namespace applied. The namespace is selected from a list supplied with the module.

=== The <code>Effect</code> class ===

The most important part of inkex.py is the <code>Effect</code> class. To implement an effect type extension in Python see [[PythonEffectTutorial]]

==== Methods ====
;<code>effect()</code>
: You should overwrite this method with your own, as shown in [[PythonEffectTutorial#Effect Extension Script]]
;<code>getElementById( id )</code>
: Returns the firs found element with given id, as a <code>lxml</code> element.
;<code>getParentNode( node )</code>
: Returns the parent of <code>node</code>. Probably the same as <code>node.getparent()</code> from <code>lxml</code>?
;<code>createGuide( x, y, angle )</code>
: Creates guide at position (<code>x</code>,<code>y</code>), with angle <code>angle</code>.
;<code>affect()</code>
: Actuate the script.
;<code>xpathSingle( path )</code>
: An xpath wrapper to return a single node.
;<code>uniqueId( old_id )</code>
: Return an id that is unique in the document given a proposed id, by appending random alphanumeric characters to it.
;<code>getDocumentWidth()</code>
: Return width of document, as a string.
;<code>getDocumentHeight()</code>
: Return height of document, as a string.
;<code>getDocumentUnit()</code>
: Return a string representing the default unit for the document. Full list of possible units is defined in the module.
;<code>unittouu( string )</code>
: Convert given value (as a string, e.g: "4px") to units used by the document. Returns float.
;<code>uutounit( value, unit )</code>
: Convert a value (float) in document default units to given units.

==== Properties ====

;<code>document</code>
: DOM document, as a <code>lxml.etree</code>.
;<code>selected</code>
: A dict mapping ids to nodes, for all nodes selected in Inkscape.
;<code>doc_ids</code>:
: A dict mapping ids to the constant 1, for all of the ids used in the original document. Does not get automatically updated when adding elements.
;<code>options</code>
: Options passed to the script.

== simplestyle.py ==
Provides methods for dealing with css data embedded in SVG's style attribute. When a color is represented as integers they should be in the (0, 255) range, when represented as floats, they should be in the (0.0, 1.0) range.

;<code>parseStyle( string )</code>
: Create a dictionary of attribute-value pairs from the value of an inline style attribute.
;<code>formatStyle( dict )</code>
: Format an inline style attribute from a dictionary of attribute-value pairs, values are converted to strings by <code>str()</code>.
;<code>isColor( c )</code>
: Determine if <code>c</code> is a valid color.
;<code>parseColor( c )</code>
: Creates a rgb int array. <code>c</code> can be any type of string representation of a color.
;<code>formatColoria( a )</code>
: Convert int array to #rrggbb string.
;<code>formatColorfa( a )</code>
: Convert float array to #rrggbb string.
;<code>formatColor3i( r, g, b )</code>
: Convert 3 ints to #rrggbb string.
;<code>formatColor3f( r, g, b )</code>
: Convert 3 floats to #rrggbb string.
;<code>svgcolors</code>
: A dictionary defining legal color names and corresponding color values.

== simplepath.py ==
Provides functions to round trip svg path d="" attribute data and a simple path format mimicking that datastructure, and additional functions for scaling translating and rotating path data.

;<code>parsePath( d )</code>
: Parse SVG path and return an array of segments. Removes all shorthand notation. Converts coordinates to absolute. Returns list of <code>[ command, params ]</code> list.

;<code>formatPath( l )</code>
: Format path data from a list. Returns the string representing the path, <code>l</code> should have the same format as returned by <code>parsePath</code>.

;<code>translatePath( p, x, y ), scalePath( p, x, y ), rotatePath( p, angle, cx=0, cy=0 )</code>
: Transforms path <code>p</code>.

== cubicsuperpath.py ==
An alternative path representation, accessing both handles of a node at once. Loses a paths open/closed identity.

;<code>CubicSuperPath( simplepath )</code>
: Given a path as a list returned by <code>simplepath.parsePath</code>, it returns a list of lists in <code>[ [ [ h1_0, pt_0, h2_0 ], [ h1_1, pt_1, h2_1 ], ... ], [ [ h1_m, pt_m, h2_m ], ...], ... ]</code> format, where <code>h1_n</code> and <code>h2_n</code> are handles for the node at point <code>pt_n</code>. All points/handles are lists of two floats (<code>[ x, y ]</code>). The list is the representation of the whole path, the first level sub-lists are representations of sub-paths, and the lists containing 3 points represent the individual control nodes.

;<code>unCubicSuperPath( csp )</code>
: Given a path in the format returned by <code>CubicSuperPath</code> returns it in the format used by <code>simplepath</code>.

;<code>parsePath( d )</code>
: Parse a string representation directly.

;<code>formatPath( p )</code>
: Format path as a string.

== simpletransform.py ==

Provides code to easily transform objects. Transformations are represented as [https://en.wikipedia.org/wiki/Transformation_matrix#Affine_transformations affine transformation matrices]. Since the last row of such matrices is always the same ([0,0,1]) it is not included, so the final matrix is a list of two lists of 3 floats containing the first two rows of the matrix.

*parseTransform
:Takes a string such as <tt>rotate(10)</tt> and produces a transformation matrix. If you also supply an initial matrix, the new one will be composed with the old one.
:Available commands: <tt>translate, scale, rotate, skewX, skewY, matrix</tt>. Other examples:
::matrix = parseTransform('rotate(10)')
::matrix = parseTransform('skewY(10)')
::matrix = parseTransform('translate(10 10)')
::matrix = parseTransform(' rotate(10)')
::matrix = parseTransform('translate(700,210) rotate(-30)')

== pturtle.py ==

Provides turtle graphics primitives with svg path data output

== beziermisc.py ==
Utility functions for working with bezier curves

== cspsubdiv.py ==
Decompose a path into polylines

== ff*.py ==

an obscure set of tools for dealing with musical scales.

Python modules for extensions

2017-11-04T19:18:35Z

Matyilona: /* cubicsuperpath.py */

[[Category:Extensions]]

These modules are provided as part of Inkscape and can be found in /usr/share/inkscape/extensions on GNU/Linux, ... on Windows, and ... on Mac OS X along with the extensions bundled with Inkscape. They can be <code>import</code>ed from an extension just like any other python module.

== inkex.py ==

This module encapsulates the basic behavior of a script extension, allowing the author to concentrate on manipulating the SVG data. It relies on [http://lxml.de/tutorial.html <code>lxml.etree</code>] to work with the XML tree. inkex.py was originally designed to provide the Effect (filter) extension type, but has been used for Input/Output extensions simply by overriding additional class methods.

=== Functions ===
inkex.py provides the following functions:
;<code>errormsg( msg )</code>
: End-user visible error message, it should always be used with translation: <code>inkex.errormsg(_("This extension requires two selected paths"))</code>
;<code>addNS( tag, ns=None )</code>
: Returns the selected tag, with the namespace applied. The namespace is selected from a list supplied with the module.

=== The <code>Effect</code> class ===

The most important part of inkex.py is the <code>Effect</code> class. To implement an effect type extension in Python see [[PythonEffectTutorial]]

==== Methods ====
;<code>effect()</code>
: You should overwrite this method with your own, as shown in [[PythonEffectTutorial#Effect Extension Script]]
;<code>getElementById( id )</code>
: Returns the firs found element with given id, as a <code>lxml</code> element.
;<code>getParentNode( node )</code>
: Returns the parent of <code>node</code>. Probably the same as <code>node.getparent()</code> from <code>lxml</code>?
;<code>createGuide( x, y, angle )</code>
: Creates guide at position (<code>x</code>,<code>y</code>), with angle <code>angle</code>.
;<code>affect()</code>
: Actuate the script.
;<code>xpathSingle( path )</code>
: An xpath wrapper to return a single node.
;<code>uniqueId( old_id )</code>
: Return an id that is unique in the document given a proposed id, by appending random alphanumeric characters to it.
;<code>getDocumentWidth()</code>
: Return width of document, as a string.
;<code>getDocumentHeight()</code>
: Return height of document, as a string.
;<code>getDocumentUnit()</code>
: Return a string representing the default unit for the document. Full list of possible units is defined in the module.
;<code>unittouu( string )</code>
: Convert given value (as a string, e.g: "4px") to units used by the document. Returns float.
;<code>uutounit( value, unit )</code>
: Convert a value (float) in document default units to given units.

==== Properties ====

;<code>document</code>
: DOM document, as a <code>lxml.etree</code>.
;<code>selected</code>
: A dict mapping ids to nodes, for all nodes selected in Inkscape.
;<code>doc_ids</code>:
: A dict mapping ids to the constant 1, for all of the ids used in the original document. Does not get automatically updated when adding elements.
;<code>options</code>
: Options passed to the script.

== simplestyle.py ==
Provides methods for dealing with css data embedded in SVG's style attribute. When a color is represented as integers they should be in the (0, 255) range, when represented as floats, they should be in the (0.0, 1.0) range.

;<code>parseStyle( string )</code>
: Create a dictionary of attribute-value pairs from the value of an inline style attribute.
;<code>formatStyle( dict )</code>
: Format an inline style attribute from a dictionary of attribute-value pairs, values are converted to strings by <code>str()</code>.
;<code>isColor( c )</code>
: Determine if <code>c</code> is a valid color.
;<code>parseColor( c )</code>
: Creates a rgb int array. <code>c</code> can be any type of string representation of a color.
;<code>formatColoria( a )</code>
: Convert int array to #rrggbb string.
;<code>formatColorfa( a )</code>
: Convert float array to #rrggbb string.
;<code>formatColor3i( r, g, b )</code>
: Convert 3 ints to #rrggbb string.
;<code>formatColor3f( r, g, b )</code>
: Convert 3 floats to #rrggbb string.
;<code>svgcolors</code>
: A dictionary defining legal color names and corresponding color values.

== simplepath.py ==
Provides functions to round trip svg path d="" attribute data and a simple path format mimicking that datastructure, and additional functions for scaling translating and rotating path data.

;<code>parsePath( d )</code>
: Parse SVG path and return an array of segments. Removes all shorthand notation. Converts coordinates to absolute. Returns list of <code>[ command, params ]</code> list.

;<code>formatPath( l )</code>
: Format path data from a list. Returns the string representing the path, <code>l</code> should have the same format as returned by <code>parsePath</code>.

;<code>translatePath( p, x, y ), scalePath( p, x, y ), rotatePath( p, angle, cx=0, cy=0 )</code>
: Transforms path <code>p</code>.

== cubicsuperpath.py ==
An alternative path representation, accessing both handles of a node at once. Loses a paths open/closed identity.

;<code>CubicSuperPath( simplepath )</code>
: Given a path as a list returned by <code>simplepath.parsePath</code>, it returns a list of lists in <code>[ [ [ h1_0, pt_0, h2_0 ], [ h1_1, pt_1, h2_1 ], ... ], [ [ h1_m, pt_m, h2_m ], ...], ... ]</code> format, where <code>h1_n</code> and <code>h2_n</code> are handles for the node at point <code>pt_n</code>. All points/handles are lists of two floats (<code>[ x, y ]</code>). The list is the representation of the whole path, the first level sub-lists are representations of sub-paths, and the list containing 3 points represent the individual control nodes.

;<code>unCubicSuperPath( csp )</code>
: Given a path in the format returned by <code>CubicSuperPath</code> returns it in the format used by <code>simplepath</code>.

;<code>parsePath( d )</code>
: Parse a string representation directly.

;<code>formatPath( p )</code>
: Format path as a string.

== simpletransform.py ==

Provides code to easily transform objects. Transformations are represented as [https://en.wikipedia.org/wiki/Transformation_matrix#Affine_transformations affine transformation matrices]. Since the last row of such matrices is always the same ([0,0,1]) it is not included, so the final matrix is a list of two lists of 3 floats containing the first two rows of the matrix.

*parseTransform
:Takes a string such as <tt>rotate(10)</tt> and produces a transformation matrix. If you also supply an initial matrix, the new one will be composed with the old one.
:Available commands: <tt>translate, scale, rotate, skewX, skewY, matrix</tt>. Other examples:
::matrix = parseTransform('rotate(10)')
::matrix = parseTransform('skewY(10)')
::matrix = parseTransform('translate(10 10)')
::matrix = parseTransform(' rotate(10)')
::matrix = parseTransform('translate(700,210) rotate(-30)')

== pturtle.py ==

Provides turtle graphics primitives with svg path data output

== beziermisc.py ==
Utility functions for working with bezier curves

== cspsubdiv.py ==
Decompose a path into polylines

== ff*.py ==

an obscure set of tools for dealing with musical scales.

Python modules for extensions

2017-11-04T19:13:43Z

Matyilona: /* simpletransform.py */

[[Category:Extensions]]

These modules are provided as part of Inkscape and can be found in /usr/share/inkscape/extensions on GNU/Linux, ... on Windows, and ... on Mac OS X along with the extensions bundled with Inkscape. They can be <code>import</code>ed from an extension just like any other python module.

== inkex.py ==

This module encapsulates the basic behavior of a script extension, allowing the author to concentrate on manipulating the SVG data. It relies on [http://lxml.de/tutorial.html <code>lxml.etree</code>] to work with the XML tree. inkex.py was originally designed to provide the Effect (filter) extension type, but has been used for Input/Output extensions simply by overriding additional class methods.

=== Functions ===
inkex.py provides the following functions:
;<code>errormsg( msg )</code>
: End-user visible error message, it should always be used with translation: <code>inkex.errormsg(_("This extension requires two selected paths"))</code>
;<code>addNS( tag, ns=None )</code>
: Returns the selected tag, with the namespace applied. The namespace is selected from a list supplied with the module.

=== The <code>Effect</code> class ===

The most important part of inkex.py is the <code>Effect</code> class. To implement an effect type extension in Python see [[PythonEffectTutorial]]

==== Methods ====
;<code>effect()</code>
: You should overwrite this method with your own, as shown in [[PythonEffectTutorial#Effect Extension Script]]
;<code>getElementById( id )</code>
: Returns the firs found element with given id, as a <code>lxml</code> element.
;<code>getParentNode( node )</code>
: Returns the parent of <code>node</code>. Probably the same as <code>node.getparent()</code> from <code>lxml</code>?
;<code>createGuide( x, y, angle )</code>
: Creates guide at position (<code>x</code>,<code>y</code>), with angle <code>angle</code>.
;<code>affect()</code>
: Actuate the script.
;<code>xpathSingle( path )</code>
: An xpath wrapper to return a single node.
;<code>uniqueId( old_id )</code>
: Return an id that is unique in the document given a proposed id, by appending random alphanumeric characters to it.
;<code>getDocumentWidth()</code>
: Return width of document, as a string.
;<code>getDocumentHeight()</code>
: Return height of document, as a string.
;<code>getDocumentUnit()</code>
: Return a string representing the default unit for the document. Full list of possible units is defined in the module.
;<code>unittouu( string )</code>
: Convert given value (as a string, e.g: "4px") to units used by the document. Returns float.
;<code>uutounit( value, unit )</code>
: Convert a value (float) in document default units to given units.

==== Properties ====

;<code>document</code>
: DOM document, as a <code>lxml.etree</code>.
;<code>selected</code>
: A dict mapping ids to nodes, for all nodes selected in Inkscape.
;<code>doc_ids</code>:
: A dict mapping ids to the constant 1, for all of the ids used in the original document. Does not get automatically updated when adding elements.
;<code>options</code>
: Options passed to the script.

== simplestyle.py ==
Provides methods for dealing with css data embedded in SVG's style attribute. When a color is represented as integers they should be in the (0, 255) range, when represented as floats, they should be in the (0.0, 1.0) range.

;<code>parseStyle( string )</code>
: Create a dictionary of attribute-value pairs from the value of an inline style attribute.
;<code>formatStyle( dict )</code>
: Format an inline style attribute from a dictionary of attribute-value pairs, values are converted to strings by <code>str()</code>.
;<code>isColor( c )</code>
: Determine if <code>c</code> is a valid color.
;<code>parseColor( c )</code>
: Creates a rgb int array. <code>c</code> can be any type of string representation of a color.
;<code>formatColoria( a )</code>
: Convert int array to #rrggbb string.
;<code>formatColorfa( a )</code>
: Convert float array to #rrggbb string.
;<code>formatColor3i( r, g, b )</code>
: Convert 3 ints to #rrggbb string.
;<code>formatColor3f( r, g, b )</code>
: Convert 3 floats to #rrggbb string.
;<code>svgcolors</code>
: A dictionary defining legal color names and corresponding color values.

== simplepath.py ==
Provides functions to round trip svg path d="" attribute data and a simple path format mimicking that datastructure, and additional functions for scaling translating and rotating path data.

;<code>parsePath( d )</code>
: Parse SVG path and return an array of segments. Removes all shorthand notation. Converts coordinates to absolute. Returns list of <code>[ command, params ]</code> list.

;<code>formatPath( l )</code>
: Format path data from a list. Returns the string representing the path, <code>l</code> should have the same format as returned by <code>parsePath</code>.

;<code>translatePath( p, x, y ), scalePath( p, x, y ), rotatePath( p, angle, cx=0, cy=0 )</code>
: Transforms path <code>p</code>.

== cubicsuperpath.py ==
An alternative path representation, accessing both handles of a node at once. Loses a paths open/closed identity.

;<code>CubicSuperPath( simplepath )</code>
: Given a path as a list returned by <code>simplepath.parsePath</code>, it returns a list of lists in <code>[ [ h1_0, pt_0, h2_0 ], [ h1_1, pt_1, h2_1 ], ... ]</code> format, where <code>h1_n</code> and <code>h2_n</code> are handles for the node at point <code>pt_n</code>. All points/handles are lists of two floats (<code>[ x, y ]</code>).

;<code>unCubicSuperPath( csp )</code>
: Given a path in the format returned by <code>CubicSuperPath</code> returns it in the format used by <code>simplepath</code>.

;<code>parsePath( d )</code>
: Parse a string representation directly.

;<code>formatPath( p )</code>
: Format path as a string.

== simpletransform.py ==

Provides code to easily transform objects. Transformations are represented as [https://en.wikipedia.org/wiki/Transformation_matrix#Affine_transformations affine transformation matrices]. Since the last row of such matrices is always the same ([0,0,1]) it is not included, so the final matrix is a list of two lists of 3 floats containing the first two rows of the matrix.

*parseTransform
:Takes a string such as <tt>rotate(10)</tt> and produces a transformation matrix. If you also supply an initial matrix, the new one will be composed with the old one.
:Available commands: <tt>translate, scale, rotate, skewX, skewY, matrix</tt>. Other examples:
::matrix = parseTransform('rotate(10)')
::matrix = parseTransform('skewY(10)')
::matrix = parseTransform('translate(10 10)')
::matrix = parseTransform(' rotate(10)')
::matrix = parseTransform('translate(700,210) rotate(-30)')

== pturtle.py ==

Provides turtle graphics primitives with svg path data output

== beziermisc.py ==
Utility functions for working with bezier curves

== cspsubdiv.py ==
Decompose a path into polylines

== ff*.py ==

an obscure set of tools for dealing with musical scales.

Python modules for extensions

2017-11-04T18:42:21Z

Matyilona: /* cubicsuperpath.py */

Python modules for extensions

2017-11-02T19:46:49Z

Matyilona: /* simplepath.py */

Python modules for extensions

2017-11-01T15:49:47Z

Matyilona: /* simplestyle.py */

Python modules for extensions

2017-11-01T15:45:58Z

Matyilona: Reformatting and extending simplestyle.py

Python modules for extensions

2017-11-01T15:22:21Z

Matyilona:

Python modules for extensions

2017-10-31T19:41:33Z

Matyilona: Providing more detail on inkex.py

[[Category:Extensions]]

These modules are provided as part of Inkscape and can be found in /usr/share/inkscape/extentions on GNU/Linux, ... on Windows, and ... on Mac OS X along with the extensions bundled with Inkscape. They can be <code>import</code>ed from an extension as any other python module.

== inkex.py ==

This module encapsulates the basic behavior of a script extension, allowing the author to concentrate on manipulating the SVG data. It relies on [http://lxml.de/tutorial.html <code>lxml.etree</code>] to work with the XML tree. inkex.py was originally designed to provide the Effect (filter) extension type, but has been used for Input/Output extensions simply by overriding additional class methods.

=== Functions ===
inkex.py provides the following functions:
;<code>errormsg( msg )</code>
: End-user visible error message, it should always be used with translation: <code>inkex.errormsg(_("This extension requires two selected paths"))</code>
;<code>addNS( tag, ns=None )</code>
: Returns the selected tag, with the namespace applied. The namespace is selected from a list supplied with the module.

=== The <code>Effect</code> class ===

The most important part of inkex.py is the <code>Effect</code> class. To implement an effect type extension in python see [[PythonEffectTutorial]]

==== Methods ====
;<code>effect()</code>
: You should overwrite this method with your own, as show in [[PythonEffectTutorial#Effect Extension Script]]
;<code>getElementById( id )</code>
: Returns the firs found element with given id, as a <code>lxml</code> element.
;<code>getParentNode( node )</code>
: Returns the parent of <code>node</code>. Probably the same as <code>node.getparent()</code> from <code>lxml</code>?
;<code>createGuid( x, y, angle )</code>
: Creates guide at position (<code>x</code>,<code>y</code>), with angle <code>angle</code>.
;<code>affect()</code>
: Actuate the script.
;<code>xpathSingle( path )</code>
: An xpath wrapper to return a single node.
;<code>uniqueId( old_id )</code>
: Return an id that is unique in the document given a proposed id, by appending random alphanumeric characters to it.
;<code>getDocumentWidth()</code>
: Return width of document, as a string.
;<code>getDocumentHeight()</code>
: Return height of document, as a string.
;<code>getDocumentUnit()</code>
: Return a string representing the default unit for the document. Full list of possible units is defined in the module.
;<code>unittouu( string )</code>
: Convert given value (as a string, e.g: "4px") to units used by the document. Returns float.
;<code>uutounit( value, unit )</code>
: Convert a value (float) in document default units to given units.

==== Properties ====

;<code>document</code>
: DOM document, as a <code>lxml.etree</code>.
;<code>selected</code>
: A dict mapping ids to nodes, for all nodes selected in Inkscape.
;<code>doc_ids</code>:
: A dict mapping ids to the constant 1, for all of the ids used in the original document. Does not get automatically updated when adding elements.
;<code>options</code>
: Options passed to the script.

== simplestyle.py ==
Provides methods for dealing with css data embeded in SVG's style="" atribute

*parseStyle(string): Create a dictionary from the value of an inline style attribute
*formatStyle(dict): Format an inline style attribute from a dictionary
*isColor(c): Determine if its a color we can use. If not, leave it unchanged.
*parseColor(c): Creates a rgb int array
*formatColoria(a): int array to #rrggbb
*formatColorfa(a): float array to #rrggbb
*formatColor3i(r,g,b): 3 ints to #rrggbb
*formatColor3f(r,g,b): 3 floats to #rrggbb

*svgcolors: a dictionary defining legal color names and corresponding color values

== simplepath.py ==
Provides functions to round trip svg path d="" attribute data and a simple path format mimicing that datastructure. additional functions for scaling translating and rotating path data.

== cubicsuperpath.py ==
An alternative path representation. access both handles of a node at once. loses a paths open/closed identity.

== simpletransform.py ==

Provides code to easily transform objects.

*parseTransform
:Takes a string such as <tt>rotate(10)</tt> and produces a transformation matrix. If you also supply an initial matrix, the new one will be composed with the old one.
:Available commands: <tt>translate, scale, rotate, skewX, skewY, matrix</tt>. Other examples:
::matrix = parseTransform('rotate(10)')
::matrix = parseTransform('skewY(10)')
::matrix = parseTransform('translate(10 10)')
::matrix = parseTransform(' rotate(10)')
::matrix = parseTransform('translate(700,210) rotate(-30)')

== pturtle.py ==

Provides turtle graphics primitives with svg path data output

== beziermisc.py ==
Utility functions for working with bezier curves

== cspsubdiv.py ==
Decompose a path into polylines

== ff*.py ==

an obscure set of tools for dealing with musical scales.