Difference between revisions of "Python modules for extensions"

From Inkscape Wiki
Jump to navigation Jump to search
(update macOS path)
(Move documentation.)
Tags: Replaced Visual edit
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 /Applications/Inkscape.app/Contents/Resources/share/inkscape/extensions/ on macOS along with the extensions bundled with Inkscape. They can be <code>import</code>ed from an extension just like any other python module.
The API documentation for inkex has been moved to 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 path's 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.

Revision as of 20:58, 10 March 2022


The API documentation for inkex has been moved to the documentation of the extensions repository.

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