The Document class encapsulates a Krita Document/Image. A Krita document is an Image with a filename. Libkis does not differentiate between a document and an image, like Krita does internally.
Methods
Member documentation
retrieve the node that is currently active in the currently active window
Return
the active node. If there is no active window, the first child node is returned. |
get total frame range for animation
Return
total frame range for animation |
the actual data for the annotation for this type. It's a simple QByteArray, what's in it depends on the type of the annotation
Parameters
| type | the type of the annotation |
Return
a bytearray, possibly empty if this type of annotation doesn't exist |
gets the pretty description for the current annotation
Parameters
| type | the type of the annotation |
Return
a string that can be presented to the user |
returns the list of annotations present in the document. Each annotation type is unique.
Return
(no description provided) |
Return current audio level for document
Return
A value between 0.0 and 1.0 (1.0 = 100%) |
Return a list of current audio tracks for document
Return
List of absolute path/file name of audio files |
Return autosave status for document Notes: - returned value is Autosave flag value
Even if autosave is set to True, under condition Krita will not proceed to automatic save of document:
- autosave is globally deactivated
- document is read-only - When autosave is set to False, Krita never execute automatic save for document
Return
True if autosave is active, otherwise False |
returns the current background color of the document. The color will also include the opacity.
Return
QColor |
Batchmode means that no actions on the document should show dialogs or popups.
Return
true if the document is in batchmode. |
create a shallow clone of this document.
Return
a new Document that should be identical to this one in every respect. |
Close the document: remove it from Krita's internal list of documents and close all views. If the document is modified, you should save it first. There will be no prompt for saving.
After closing the document it becomes invalid.
Return
true if the document is closed. |
colorDepth A string describing the color depth of the image:
- U8: unsigned 8 bits integer, the most common type
- U16: unsigned 16 bits integer
- F16: half, 16 bits floating point. Only available if Krita was built with OpenEXR
- F32: 32 bits floating point
Return
the color depth. |
retrieve the current color model of this document:
- A: Alpha mask
- RGBA: RGB with alpha channel (The actual order of channels is most often BGR!)
- XYZA: XYZ with alpha channel
- LABA: LAB with alpha channel
- CMYKA: CMYK with alpha channel
- GRAYA: Gray with alpha channel
- YCbCrA: YCbCr with alpha channel
Return
the internal color model string. |
Parameters
| name | (no description provided) |
| source | (no description provided) |
Return
Creates a colorize mask, which can be used to color fill via keystrokes.
Parameters
| name | - the name of the layer. |
Return
a TransparencyMask |
returns a layer that shows an external image.
Parameters
| name | name of the file layer. |
| fileName | the absolute filename of the file referenced. Symlinks will be resolved. |
| scalingMethod | how the dimensions of the file are interpreted can be either "None", "ImageToSize" or "ImageToPPI" |
| scalingFilter | filter used to scale the file can be "Bicubic", "Hermite", "NearestNeighbor", "Bilinear", "Bell", "BSpline", "Lanczos3", "Mitchell" |
Return
a FileLayer |
creates a fill layer object, which is a layer
Parameters
| name | (no description provided) |
| generatorName | - name of the generation filter. |
| configuration | - the configuration for the generation filter. |
| selection | - the selection. |
Return
a filllayer object. from krita import *d = Krita.instance().activeDocument()i = InfoObject();i.setProperty("pattern", "Cross01.pat")s = Selection();s.select(0, 0, d.width(), d.height(), 255)n = d.createFillLayer("test", "pattern", i, s)r = d.rootNode();c = r.childNodes();r.addChildNode(n, c[0])d.refreshProjection() |
creates a filter layer, which is a layer that represents a filter applied non-destructively.
Parameters
| name | name of the filterLayer |
| filter | the filter that this filter layer will us. |
| selection | the selection. |
Return
a filter layer object. |
Creates a filter mask object that much like a filterlayer can apply a filter non-destructively.
Parameters
| name | the name of the layer. |
| filter | the filter assigned. |
| selection_source | a node from which the selection should be initialized |
Return
a FilterMask |
Returns a grouplayer object. Grouplayers are nodes that can have other layers as children and have the passthrough mode.
Parameters
| name | the name of the layer. |
Return
a GroupLayer object. |
create a new node of the given type. The node is not added to the node hierarchy; you need to do that by finding the right parent node, getting its list of child nodes and adding the node in the right place, then calling Node::SetChildNodes
Parameters
| name | The name of the node |
| nodeType | The type of the node. Valid types are:
When relevant, the new Node will have the colorspace of the image by default; that can be changed with Node::setColorSpace. The settings and selections for relevant layer and mask types can also be set after the Node has been created. d = Application.createDocument(1000, 1000, "Test", "RGBA", "U8", "", 120.0)root = d.rootNode();print(root.childNodes())l2 = d.createNode("layer2", "paintLayer")print(l2)root.addChildNode(l2, None)print(root.childNodes()) |
Return
the new Node. |
Creates a selection mask, which can be used to store selections.
Parameters
| name | - the name of the layer. |
Return
a SelectionMask |
Creates a transform mask, which can be used to apply a transformation non-destructively.
Parameters
| name | - the name of the layer mask. |
Return
a TransformMask |
Creates a transparency mask, which can be used to assign transparency to regions.
Parameters
| name | - the name of the layer. |
Return
a TransparencyMask |
Creates a vector layer that can contain vector shapes.
Parameters
| name | the name of this layer. |
Return
a VectorLayer. |
the image to rectangle described by x, y, w and h
Parameters
| x | x coordinate of the top left corner |
| y | y coordinate of the top left corner |
| w | width |
| h | height |
get current frame selected of animation
Return
current frame selected of animation |
creates and XML document representing document and author information.
Return
a string containing a valid XML document with the right information about the document and author. The DTD can be found here: https://phabricator.kde.org/source/krita/browse/master/krita/dtd/ <?xml version="1.0" encoding="UTF-8"?><!DOCTYPE document-info PUBLIC '-//KDE//DTD document-info 1.1//EN' 'http://www.calligra.org/DTD/document-info-1.1.dtd'><document-info xmlns="http://www.calligra.org/DTD/document-info"><about> <title>My Document</title> <description></description> <subject></subject> <abstract><![CDATA[]]> <keyword></keyword> <initial-creator>Unknown</initial-creator> <editing-cycles>1</editing-cycles> <editing-time>35</editing-time> <date>2017-02-27T20:15:09 <creation-date>2017-02-27T20:14:33 <language></language> </about> <author> <full-name>Boudewijn Rempt</full-name> <initial></initial> <author-title></author-title> <email></email> <telephone></telephone> <telephone-work></telephone-work> <fax></fax> <country></country> <postal-code></postal-code> <city></city> <street></street> <position></position> <company></company> </author></document-info> |
export the image, without changing its URL to the given path.
Parameters
| filename | the full path to which the image is to be saved |
| exportConfiguration | a configuration object appropriate to the file format. An InfoObject will used to that configuration. The supported formats have specific configurations that must be used when in batchmode. They are described below: \b png
\b jpeg
|
Return
true if the export succeeded, false if it failed. |
get the full clip range end time
Return
full clip range end time |
get the full clip range start time
Return
full clip range start time |
Returns a GridConfig grid configuration for current document
Return
a GridConfig object with grid configuration |
Returns a GuidesConfig guides configuration for current document
Return
a GuidesConfig object with guides configuration |
DEPRECATED - use guidesConfig() instead Returns guide lockedness.
Return
whether the guides are locked. |
DEPRECATED - use guidesConfig() instead Returns guide visibility.
Return
whether the guides are visible. |
DEPRECATED - use guidesConfig() instead The horizontal guides.
Return
a list of the horizontal positions of guides. |
Import an image sequence of files from a directory. This will grab all images from the directory and import them with a potential offset (firstFrame) and step (images on 2s, 3s, etc)
Parameters
| files | (no description provided) |
| firstFrame | (no description provided) |
| step | (no description provided) |
Return
whether the animation import was successful |
Why this should be used, When it should be used, How it should be used, and warnings about when not.
Return
(no description provided) |
[low-level] Lock the image without waiting for all the internal job queues are processed
WARNING: Don't use it unless you really know what you are doing! Use barrierLock() instead!
Waits for all the **currently running** internal jobs to complete and locks the image for writing. Please note that this function does **not** wait for all the internal queues to process, so there might be some non-finished actions pending. It means that you just postpone these actions until you unlock() the image back. Until then, then image might easily be frozen in some inconsistent state.
The only sane usage for this function is to lock the image for **emergency** processing, when some internal action or scheduler got hung up, and you just want to fetch some data from the image without races.
In all other cases, please use barrierLock() instead!
returns true if the document has unsaved modifications.
Return
(no description provided) |
Return
the name of the document. This is the title field in the documentInfo() |
searches the node tree for a node with the given name and returns it
Parameters
| name | the name of the node |
Return
the first node with the given name or 0 if no node is found |
searches the node tree for a node with the given name and returns it.
Parameters
| id | (no description provided) |
Return
the node with the given unique id, or 0 if no node is found. |
reads the given rectangle from the image projection and returns it as a byte array. The pixel data starts top-left, and is ordered row-first.
The byte array can be interpreted as follows: 8 bits images have one byte per channel, and as many bytes as there are channels. 16 bits integer images have two bytes per channel, representing an unsigned short. 16 bits float images have two bytes per channel, representing a half, or 16 bits float. 32 bits float images have four bytes per channel, representing a float.
You can read outside the image boundaries; those pixels will be transparent black.
The order of channels is:
- Integer RGBA: Blue, Green, Red, Alpha
- Float RGBA: Red, Green, Blue, Alpha
- LabA: L, a, b, Alpha
- CMYKA: Cyan, Magenta, Yellow, Key, Alpha
- XYZA: X, Y, Z, A
- YCbCrA: Y, Cb, Cr, Alpha
The byte array is a copy of the original image data. In Python, you can use bytes, bytearray and the struct module to interpret the data and construct, for instance, a Pillow Image object.
Parameters
| x | x position from where to start reading |
| y | y position from where to start reading |
| w | row length to read |
| h | number of rows to read |
Return
a QByteArray with the pixel data. The byte array may be empty. |
get end time of current playback
Return
end time of current playback |
get start time of current playback
Return
start time of current playback |
creates a QImage from the rendered image or a cutout rectangle.
Parameters
| x | (no description provided) |
| y | (no description provided) |
| w | (no description provided) |
| h | (no description provided) |
Return
(no description provided) |
Starts a synchronous recomposition of the projection: everything will wait until the image is fully recomputed.
remove the specified annotation from the image
Parameters
| type | the type defining the annotation |
resizes the canvas to the given left edge, top edge, width and height. Note: This doesn't scale, use scale image for that.
Parameters
| x | the new left edge |
| y | the new top edge |
| w | the new width |
| h | the new height |
the root node is the invisible group layer that contains the entire node hierarchy.
Return
the root of the image |
Rotate the image by the given radians.
Parameters
| radians | the amount you wish to rotate the image in radians |
the image to its currently set path. The modified flag of the document will be reset
Return
true if saving succeeded, false otherwise. |
save the document under the filename. The document's filename will be reset to filename.
Parameters
| filename | the new filename (full path) for the document |
Return
true if saving succeeded, false otherwise. |
Parameters
| w | the new width |
| h | the new height |
| xres | the new xres |
| yres | the new yres |
| strategy | the scaling strategy. There's several ones amongst these that aren't available in the regular UI. The list of filters is extensible and can be retrieved with Krita::filter
|
Create a Selection object around the global selection, if there is one.
Return
the global selection or None if there is no global selection. |
make the given node active in the currently active view and window
Parameters
| value | the node to make active. |
Add the given annotation to the document
Parameters
| type | the unique type of the annotation |
| description | the user-visible description of the annotation |
| annotation | the annotation itself |
Set current audio level for document
Parameters
| level | Audio volumne between 0.0 and 1.0 (1.0 = 100%) |
Set a list of audio tracks for document Note: the function allows to add more than one file while from Krita's UI, importing a file will replace the complete list
The reason why this method let the ability to provide more than one file is related to the internal's Krita method from KisDocument class: void KisDocument::setAudioTracks(QVector
Parameters
| files | List of absolute path/file name of audio files |
Return
True if all files from list have been added, otherwise False (a file was not found) |
Allow to activate/deactivate autosave for document When activated, it will use default Krita autosave settings It means that even when autosave is set to True, under condition Krita will not proceed to automatic save of document: - autosave is globally deactivated - document is read-only
Being able to deactivate autosave on a document can make sense when a plugin use internal document (document is not exposed in a view, only created for intenal process purposes)
Parameters
| active | True to activate autosave |
sets the background color of the document. It will trigger a projection update.
Parameters
| color | A QColor. The color will be converted from sRGB. |
Return
bool |
sets the background color of the document. It will trigger a projection update.
Parameters
| color | A QColor. The color will be converted from sRGB. |
Return
bool |
Set batchmode to value. If batchmode is true, then there should be no popups or dialogs shown to the user.
Parameters
| value | (no description provided) |
set the color profile of the image to the given profile. The profile has to be registered with krita and be compatible with the current color model and depth; the image data is not converted.
Parameters
| colorProfile | (no description provided) |
Return
false if the colorProfile name does not correspond to to a registered profile or if assigning the profile failed. |
convert the nodes and the image to the given colorspace. The conversion is done with Perceptual as intent, High Quality and No LCMS Optimizations as flags and no blackpoint compensation.
Parameters
| colorModel | A string describing the color model of the image:
|
| colorDepth | A string describing the color depth of the image:
|
| colorProfile | a valid color profile for this color model and color depth combination. |
Return
false the combination of these arguments does not correspond to a colorspace. |
set current time of document's animation
Parameters
| time | (no description provided) |
set the Document information to the information contained in document
Parameters
| document | A string containing a valid XML document that conforms to the document-info DTD that can be found here: https://phabricator.kde.org/source/krita/browse/master/krita/dtd/ |
set the full path of the document to value
Parameters
| value | (no description provided) |
set frames per second of document
Parameters
| fps | (no description provided) |
set full clip range end time
Parameters
| endTime | (no description provided) |
set start time of animation
Parameters
| startTime | (no description provided) |
Set grid configuration for current document
Parameters
| gridConfig | a GridConfig object to apply for grid configuration To modify/set grid property on a document # get document (create one or get active one for example)newDoc = Krita.instance().createDocument(500, 500, "Test", "RGBA", "U8", "", 300)# retrieve document grid configurationnewDocGrid = newDoc.gridConfig()# update propertiesnewDocGrid.setColorMain(QColor('#ff00ff'))newDocGrid.setLineTypeMain('dashed')newDocGrid.setVisible(True)newDocGrid.setAngleLeft(30)newDocGrid.setAngleRight(15)newDocGrid.setType('isometric')# set grid configuration to documentnewDoc.setGridConfig(newDocGrid) |
Set guides configuration for current document
Parameters
| guidesConfig | a GuidesConfig object to apply for guides configuration To modify/set guides property on a document # get document (create one or get active one for example)newDoc = Krita.instance().createDocument(500, 500, "Test", "RGBA", "U8", "", 300)# retrieve document guides configurationnewDocGuides = newDoc.guidesConfig()# update propertiesnewDocGuides.setColor(QColor('#ff00ff'))newDocGuides.setLineType('dotted')newDocGuides.setVisible(True)newDocGuides.setLocked(True)newDocGuides.setSnap(True)newDocGuides.setHorizontalGuides([100,200])# set guides configuration to documentnewDoc.setGuidesConfig(newDocGuides) |
DEPRECATED - use guidesConfig() instead set guides locked on this document
Parameters
| locked | whether or not to lock the guides on this document. |
DEPRECATED - use guidesConfig() instead set guides visible on this document.
Parameters
| visible | whether or not the guides are visible. |
resize the document to value height. This is a canvas resize, not a scale.
Parameters
| value | (no description provided) |
DEPRECATED - use guidesConfig() instead replace all existing horizontal guides with the entries in the list.
Parameters
| lines | a list of floats containing the new guides. |
sets the modified status of the document
Parameters
| modified | if true, the document is considered modified and closing it will ask for saving. |
sets the name of the document to value. This is the title field in the documentInfo()
Parameters
| value | (no description provided) |
set temporary playback range of document
Parameters
| start | (no description provided) |
| stop | (no description provided) |
set the resolution of the image; this does not scale the image
Parameters
| value | the resolution in pixels per inch |
set or replace the global selection
Parameters
| value | a valid selection object. |
DEPRECATED - use guidesConfig() instead replace all existing horizontal guides with the entries in the list.
Parameters
| lines | a list of floats containing the new guides. |
resize the document to value width. This is a canvas resize, not a scale.
Parameters
| value | (no description provided) |
sets the left edge of the canvas to x.
Parameters
| x | (no description provided) |
set the horizontal resolution of the image to xRes in pixels per inch
Parameters
| xRes | (no description provided) |
sets the top edge of the canvas to y.
Parameters
| y | (no description provided) |
set the vertical resolution of the image to yRes in pixels per inch
Parameters
| yRes | (no description provided) |
shear the whole image.
Parameters
| angleX | the X-angle in degrees to shear by |
| angleY | the Y-angle in degrees to shear by |
create a thumbnail of the given dimensions.
If the requested size is too big a null QImage is created.
Parameters
| w | (no description provided) |
| h | (no description provided) |
Return
a QImage representing the layer contents. |
toplevelNodes return a list with all top level nodes in the image graph
Return
(no description provided) |
Tries to lock the image without waiting for the jobs to finish
Same as barrierLock(), but doesn't block execution of the calling thread until all the background jobs are finished. Instead, in case of presence of unfinished jobs in the queue, it just returns false
Return
whether the lock has been acquired |
Unlocks the image and starts/resumes all the pending internal jobs. If the image has been locked for a non-readOnly access, then all the internal caches of the image (e.g. lod-planes) are reset and regeneration jobs are scheduled.
DEPRECATED - use guidesConfig() instead The vertical guide lines.
Return
a list of vertical guides. |
Wait for all the internal image jobs to complete and return without locking the image. This function is handy for tests or other synchronous actions, when one needs to wait for the result of his actions.
Return
xRes the horizontal resolution of the image in pixels per inch |
Return
yRes the vertical resolution of the image in pixels per inch |