Difference between revisions of "Python modules for extensions"

From Inkscape Wiki
Jump to navigation Jump to search
m (Use better language)
 
(7 intermediate revisions by 4 users not shown)
Line 1: Line 1:
[[Category:Extensions]]
[[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.
This page contained API documentation for various modules in inkex. A more complete API documentation is available in the [https://inkscape.gitlab.io/extensions/documentation/source/index.html documentation of the extensions repository.]
 
== 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.

Latest revision as of 22:06, 10 March 2022


This page contained API documentation for various modules in inkex. A more complete API documentation is available in the documentation of the extensions repository.

Retrieved from "https://wiki.inkscape.org/wiki/index.php?title=Python_modules_for_extensions&oldid=120981"