Krita

Node.h
1 /*
2  * SPDX-FileCopyrightText: 2016 Boudewijn Rempt <[email protected]>
3  *
4  * SPDX-License-Identifier: LGPL-2.0-or-later
5  */
6 #ifndef LIBKIS_NODE_H
7 #define LIBKIS_NODE_H
8 
9 #include <QObject>
10 
11 #include <kis_types.h>
12 
13 #include "kritalibkis_export.h"
14 #include "libkis.h"
15 
16 /**
17  * Node represents a layer or mask in a Krita image's Node hierarchy. Group layers can contain
18  * other layers and masks; layers can contain masks.
19  *
20  */
21 class KRITALIBKIS_EXPORT Node : public QObject
22 {
23  Q_OBJECT
25 
26 public:
27  static Node *createNode(KisImageSP image, KisNodeSP node, QObject *parent = 0);
28  ~Node() override;
29  bool operator==(const Node &other) const;
30  bool operator!=(const Node &other) const;
31 
32 public Q_SLOTS:
33 
34  /**
35  * @brief clone clone the current node. The node is not associated with any image.
36  */
37  Node *clone() const;
38 
39  /**
40  * @brief alphaLocked checks whether the node is a paint layer and returns whether it is alpha locked
41  * @return whether the paint layer is alpha locked, or false if the node is not a paint layer
42  */
43  bool alphaLocked() const;
44 
45  /**
46  * @brief setAlphaLocked set the layer to value if the node is paint layer.
47  */
48  void setAlphaLocked(bool value);
49 
50  /**
51  * @return the blending mode of the layer. The values of the blending modes are defined in @see KoCompositeOpRegistry.h
52  */
53  QString blendingMode() const;
54 
55  /**
56  * @brief setBlendingMode set the blending mode of the node to the given value
57  * @param value one of the string values from @see KoCompositeOpRegistry.h
58  */
59  void setBlendingMode(QString value);
60 
61  /**
62  * @brief channels creates a list of Channel objects that can be used individually to
63  * show or hide certain channels, and to retrieve the contents of each channel in a
64  * node separately.
65  *
66  * Only layers have channels, masks do not, and calling channels on a Node that is a mask
67  * will return an empty list.
68  *
69  * @return the list of channels ordered in by position of the channels in pixel position
70  */
71  QList<Channel*> channels() const;
72 
73  /**
74  * @brief childNodes
75  * @return returns a list of child nodes of the current node. The nodes are ordered from the bottommost up.
76  * The function is not recursive.
77  */
78  QList<Node*> childNodes() const;
79 
80  /**
81  * @brief findChildNodes
82  * @param name name of the child node to search for. Leaving this blank will return all nodes.
83  * @param recursive whether or not to search recursively. Defaults to false.
84  * @param partialMatch return if the name partially contains the string (case insensitive). Defaults to false.
85  * @param type filter returned nodes based on type
86  * @param colorLabelIndex filter returned nodes based on color label index
87  * @return returns a list of child nodes and grand child nodes of the current node that match the search criteria.
88  */
89  QList<Node*> findChildNodes(const QString &name = QString(), bool recursive = false, bool partialMatch = false, const QString &type = QString(), int colorLabelIndex = 0) const;
90 
91  /**
92  * @brief addChildNode adds the given node in the list of children.
93  * @param child the node to be added
94  * @param above the node above which this node will be placed
95  * @return false if adding the node failed
96  */
97  bool addChildNode(Node *child, Node *above);
98 
99  /**
100  * @brief removeChildNode removes the given node from the list of children.
101  * @param child the node to be removed
102  */
103  bool removeChildNode(Node *child);
104 
105  /**
106  * @brief setChildNodes this replaces the existing set of child nodes with the new set.
107  * @param nodes The list of nodes that will become children, bottom-up -- the first node,
108  * is the bottom-most node in the stack.
109  */
110  void setChildNodes(QList<Node*> nodes);
111 
112  /**
113  * colorDepth A string describing the color depth of the image:
114  * <ul>
115  * <li>U8: unsigned 8 bits integer, the most common type</li>
116  * <li>U16: unsigned 16 bits integer</li>
117  * <li>F16: half, 16 bits floating point. Only available if Krita was built with OpenEXR</li>
118  * <li>F32: 32 bits floating point</li>
119  * </ul>
120  * @return the color depth.
121  */
122  QString colorDepth() const;
123 
124  /**
125  * @brief colorModel retrieve the current color model of this document:
126  * <ul>
127  * <li>A: Alpha mask</li>
128  * <li>RGBA: RGB with alpha channel (The actual order of channels is most often BGR!)</li>
129  * <li>XYZA: XYZ with alpha channel</li>
130  * <li>LABA: LAB with alpha channel</li>
131  * <li>CMYKA: CMYK with alpha channel</li>
132  * <li>GRAYA: Gray with alpha channel</li>
133  * <li>YCbCrA: YCbCr with alpha channel</li>
134  * </ul>
135  * @return the internal color model string.
136  */
137  QString colorModel() const;
138 
139  /**
140  * @return the name of the current color profile
141  */
142  QString colorProfile() const;
143 
144  /**
145  * @brief setColorProfile set the color profile of the image to the given profile. The profile has to
146  * be registered with krita and be compatible with the current color model and depth; the image data
147  * is <i>not</i> converted.
148  * @param colorProfile
149  * @return if assigning the color profile worked
150  */
151  bool setColorProfile(const QString &colorProfile);
152 
153  /**
154  * @brief setColorSpace convert the node to the given colorspace
155  * @param colorModel A string describing the color model of the node:
156  * <ul>
157  * <li>A: Alpha mask</li>
158  * <li>RGBA: RGB with alpha channel (The actual order of channels is most often BGR!)</li>
159  * <li>XYZA: XYZ with alpha channel</li>
160  * <li>LABA: LAB with alpha channel</li>
161  * <li>CMYKA: CMYK with alpha channel</li>
162  * <li>GRAYA: Gray with alpha channel</li>
163  * <li>YCbCrA: YCbCr with alpha channel</li>
164  * </ul>
165  * @param colorDepth A string describing the color depth of the image:
166  * <ul>
167  * <li>U8: unsigned 8 bits integer, the most common type</li>
168  * <li>U16: unsigned 16 bits integer</li>
169  * <li>F16: half, 16 bits floating point. Only available if Krita was built with OpenEXR</li>
170  * <li>F32: 32 bits floating point</li>
171  * </ul>
172  * @param colorProfile a valid color profile for this color model and color depth combination.
173  */
174  bool setColorSpace(const QString &colorModel, const QString &colorDepth, const QString &colorProfile);
175 
176  /**
177  * @brief Krita layers can be animated, i.e., have frames.
178  * @return return true if the layer has frames. Currently, the scripting framework
179  * does not give access to the animation features.
180  */
181  bool animated() const;
182 
183  /**
184  * @brief enableAnimation make the current layer animated, so it can have frames.
185  */
186  void enableAnimation() const;
187 
188  /**
189  * @brief Sets whether or not node should be pinned to the Timeline Docker,
190  * regardless of selection activity.
191  */
192  void setPinnedToTimeline(bool pinned) const;
193 
194  /**
195  * @return Returns true if node is pinned to the Timeline Docker or false if it is not.
196  */
197  bool isPinnedToTimeline() const;
198 
199  /**
200  * Sets the state of the node to the value of @param collapsed
201  */
202  void setCollapsed(bool collapsed);
203 
204  /**
205  * returns the collapsed state of this node
206  */
207  bool collapsed() const;
208 
209  /**
210  * Sets a color label index associated to the layer. The actual
211  * color of the label and the number of available colors is
212  * defined by Krita GUI configuration.
213  */
214  int colorLabel() const;
215 
216  /**
217  * @brief setColorLabel sets a color label index associated to the layer. The actual
218  * color of the label and the number of available colors is
219  * defined by Krita GUI configuration.
220  * @param index an integer corresponding to the set of available color labels.
221  */
222  void setColorLabel(int index);
223 
224  /**
225  * @brief inheritAlpha checks whether this node has the inherits alpha flag set
226  * @return true if the Inherit Alpha is set
227  */
228  bool inheritAlpha() const;
229 
230  /**
231  * set the Inherit Alpha flag to the given value
232  */
233  void setInheritAlpha(bool value);
234 
235  /**
236  * @brief locked checks whether the Node is locked. A locked node cannot be changed.
237  * @return true if the Node is locked, false if it hasn't been locked.
238  */
239  bool locked() const;
240 
241  /**
242  * set the Locked flag to the give value
243  */
244  void setLocked(bool value);
245 
246  /**
247  * @brief does the node have any content in it?
248  * @return if node has any content in it
249  */
250  bool hasExtents();
251 
252 
253  /**
254  * @return the user-visible name of this node.
255  */
256  QString name() const;
257 
258  /**
259  * rename the Node to the given name
260  */
261  void setName(QString name);
262 
263  /**
264  * return the opacity of the Node. The opacity is a value between 0 and 255.
265  */
266  int opacity() const;
267 
268  /**
269  * set the opacity of the Node to the given value. The opacity is a value between 0 and 255.
270  */
271  void setOpacity(int value);
272 
273  /**
274  * return the Node that is the parent of the current Node, or 0 if this is the root Node.
275  */
276  Node* parentNode() const;
277 
278  /**
279  * @brief type Krita has several types of nodes, split in layers and masks. Group
280  * layers can contain other layers, any layer can contain masks.
281  *
282  * @return The type of the node. Valid types are:
283  * <ul>
284  * <li>paintlayer
285  * <li>grouplayer
286  * <li>filelayer
287  * <li>filterlayer
288  * <li>filllayer
289  * <li>clonelayer
290  * <li>vectorlayer
291  * <li>transparencymask
292  * <li>filtermask
293  * <li>transformmask
294  * <li>selectionmask
295  * <li>colorizemask
296  * </ul>
297  *
298  * If the Node object isn't wrapping a valid Krita layer or mask object, and
299  * empty string is returned.
300  */
301  virtual QString type() const;
302 
303  /**
304  * @brief icon
305  * @return the icon associated with the layer.
306  */
307  QIcon icon() const;
308 
309  /**
310  * Check whether the current Node is visible in the layer stack
311  */
312  bool visible() const;
313 
314  /**
315  * Check to see if frame number on layer is a keyframe
316  */
317  bool hasKeyframeAtTime(int frameNumber);
318 
319  /**
320  * Set the visibility of the current node to @param visible
321  */
322  void setVisible(bool visible);
323 
324  /**
325  * @brief pixelData reads the given rectangle from the Node's paintable pixels, if those
326  * exist, and returns it as a byte array. The pixel data starts top-left, and is ordered row-first.
327  *
328  * The byte array can be interpreted as follows: 8 bits images have one byte per channel,
329  * and as many bytes as there are channels. 16 bits integer images have two bytes per channel,
330  * representing an unsigned short. 16 bits float images have two bytes per channel, representing
331  * a half, or 16 bits float. 32 bits float images have four bytes per channel, representing a
332  * float.
333  *
334  * You can read outside the node boundaries; those pixels will be transparent black.
335  *
336  * The order of channels is:
337  *
338  * <ul>
339  * <li>Integer RGBA: Blue, Green, Red, Alpha
340  * <li>Float RGBA: Red, Green, Blue, Alpha
341  * <li>GrayA: Gray, Alpha
342  * <li>Selection: selectedness
343  * <li>LabA: L, a, b, Alpha
344  * <li>CMYKA: Cyan, Magenta, Yellow, Key, Alpha
345  * <li>XYZA: X, Y, Z, A
346  * <li>YCbCrA: Y, Cb, Cr, Alpha
347  * </ul>
348  *
349  * The byte array is a copy of the original node data. In Python, you can use bytes, bytearray
350  * and the struct module to interpret the data and construct, for instance, a Pillow Image object.
351  *
352  * If you read the pixeldata of a mask, a filter or generator layer, you get the selection bytes,
353  * which is one channel with values in the range from 0..255.
354  *
355  * If you want to change the pixels of a node you can write the pixels back after manipulation
356  * with setPixelData(). This will only succeed on nodes with writable pixel data, e.g not on groups
357  * or file layers.
358  *
359  * @param x x position from where to start reading
360  * @param y y position from where to start reading
361  * @param w row length to read
362  * @param h number of rows to read
363  * @return a QByteArray with the pixel data. The byte array may be empty.
364 
365  */
366  QByteArray pixelData(int x, int y, int w, int h) const;
367 
368  /**
369  * @brief pixelDataAtTime a basic function to get pixeldata from an animated node at a given time.
370  * @param x the position from the left to start reading.
371  * @param y the position from the top to start reader
372  * @param w the row length to read
373  * @param h the number of rows to read
374  * @param time the frame number
375  * @return a QByteArray with the pixel data. The byte array may be empty.
376  */
377  QByteArray pixelDataAtTime(int x, int y, int w, int h, int time) const;
378 
379  /**
380  * @brief projectionPixelData reads the given rectangle from the Node's projection (that is, what the node
381  * looks like after all sub-Nodes (like layers in a group or masks on a layer) have been applied,
382  * and returns it as a byte array. The pixel data starts top-left, and is ordered row-first.
383  *
384  * The byte array can be interpreted as follows: 8 bits images have one byte per channel,
385  * and as many bytes as there are channels. 16 bits integer images have two bytes per channel,
386  * representing an unsigned short. 16 bits float images have two bytes per channel, representing
387  * a half, or 16 bits float. 32 bits float images have four bytes per channel, representing a
388  * float.
389  *
390  * You can read outside the node boundaries; those pixels will be transparent black.
391  *
392  * The order of channels is:
393  *
394  * <ul>
395  * <li>Integer RGBA: Blue, Green, Red, Alpha
396  * <li>Float RGBA: Red, Green, Blue, Alpha
397  * <li>GrayA: Gray, Alpha
398  * <li>Selection: selectedness
399  * <li>LabA: L, a, b, Alpha
400  * <li>CMYKA: Cyan, Magenta, Yellow, Key, Alpha
401  * <li>XYZA: X, Y, Z, A
402  * <li>YCbCrA: Y, Cb, Cr, Alpha
403  * </ul>
404  *
405  * The byte array is a copy of the original node data. In Python, you can use bytes, bytearray
406  * and the struct module to interpret the data and construct, for instance, a Pillow Image object.
407  *
408  * If you read the projection of a mask, you get the selection bytes, which is one channel with
409  * values in the range from 0..255.
410  *
411  * If you want to change the pixels of a node you can write the pixels back after manipulation
412  * with setPixelData(). This will only succeed on nodes with writable pixel data, e.g not on groups
413  * or file layers.
414  *
415  * @param x x position from where to start reading
416  * @param y y position from where to start reading
417  * @param w row length to read
418  * @param h number of rows to read
419  * @return a QByteArray with the pixel data. The byte array may be empty.
420  */
421  QByteArray projectionPixelData(int x, int y, int w, int h) const;
422 
423  /**
424  * @brief setPixelData writes the given bytes, of which there must be enough, into the
425  * Node, if the Node has writable pixel data:
426  *
427  * <ul>
428  * <li>paint layer: the layer's original pixels are overwritten
429  * <li>filter layer, generator layer, any mask: the embedded selection's pixels are overwritten.
430  * <b>Note:</b> for these
431  * </ul>
432  *
433  * File layers, Group layers, Clone layers cannot be written to. Calling setPixelData on
434  * those layer types will silently do nothing.
435  *
436  * @param value the byte array representing the pixels. There must be enough bytes available.
437  * Krita will take the raw pointer from the QByteArray and start reading, not stopping before
438  * (number of channels * size of channel * w * h) bytes are read.
439  *
440  * @param x the x position to start writing from
441  * @param y the y position to start writing from
442  * @param w the width of each row
443  * @param h the number of rows to write
444  * @return true if writing the pixeldata worked
445  */
446  bool setPixelData(QByteArray value, int x, int y, int w, int h);
447 
448  /**
449  * @brief bounds return the exact bounds of the node's paint device
450  * @return the bounds, or an empty QRect if the node has no paint device or is empty.
451  */
452  QRect bounds() const;
453 
454  /**
455  * move the pixels to the given x, y location in the image coordinate space.
456  */
457  void move(int x, int y);
458 
459  /**
460  * @brief position returns the position of the paint device of this node. The position is
461  * always 0,0 unless the layer has been moved. If you want to know the topleft position of
462  * the rectangle around the actual non-transparent pixels in the node, use bounds().
463  * @return the top-left position of the node
464  */
465  QPoint position() const;
466 
467  /**
468  * @brief remove removes this node from its parent image.
469  */
470  bool remove();
471 
472  /**
473  * @brief duplicate returns a full copy of the current node. The node is not inserted in the graphic
474  * @return a valid Node object or 0 if the node couldn't be duplicated.
475  */
476  Node* duplicate();
477 
478  /**
479  * @brief save exports the given node with this filename. The extension of the filename determines the filetype.
480  * @param filename the filename including extension
481  * @param xRes the horizontal resolution in pixels per pt (there are 72 pts in an inch)
482  * @param yRes the horizontal resolution in pixels per pt (there are 72 pts in an inch)
483  * @param exportConfiguration a configuration object appropriate to the file format.
484  * @param exportRect the export bounds for saving a node as a QRect
485  * If \p exportRect is empty, then save exactBounds() of the node. If you'd like to save the image-
486  * aligned area of the node, just pass image->bounds() there.
487  * See Document->exportImage for InfoObject details.
488  * @return true if saving succeeded, false if it failed.
489  */
490  bool save(const QString &filename, double xRes, double yRes, const InfoObject &exportConfiguration, const QRect &exportRect = QRect());
491 
492  /**
493  * @brief mergeDown merges the given node with the first visible node underneath this node in the layerstack.
494  * This will drop all per-layer metadata.
495  */
496  Node *mergeDown();
497 
498  /**
499  * @brief scaleNode
500  * @param origin the origin point
501  * @param width the width
502  * @param height the height
503  * @param strategy the scaling strategy. There's several ones amongst these that aren't available in the regular UI.
504  * <ul>
505  * <li>Hermite</li>
506  * <li>Bicubic - Adds pixels using the color of surrounding pixels. Produces smoother tonal gradations than Bilinear.</li>
507  * <li>Box - Replicate pixels in the image. Preserves all the original detail, but can produce jagged effects.</li>
508  * <li>Bilinear - Adds pixels averaging the color values of surrounding pixels. Produces medium quality results when the image is scaled from half to two times the original size.</li>
509  * <li>Bell</li>
510  * <li>BSpline</li>
511  * <li>Lanczos3 - Offers similar results than Bicubic, but maybe a little bit sharper. Can produce light and dark halos along strong edges.</li>
512  * <li>Mitchell</li>
513  * </ul>
514  */
515  void scaleNode(QPointF origin, int width, int height, QString strategy);
516 
517  /**
518  * @brief rotateNode rotate this layer by the given radians.
519  * @param radians amount the layer should be rotated in, in radians.
520  */
521  void rotateNode(double radians);
522 
523  /**
524  * @brief cropNode crop this layer.
525  * @param x the left edge of the cropping rectangle.
526  * @param y the top edge of the cropping rectangle
527  * @param w the right edge of the cropping rectangle
528  * @param h the bottom edge of the cropping rectangle
529  */
530  void cropNode(int x, int y, int w, int h);
531 
532  /**
533  * @brief shearNode perform a shear operation on this node.
534  * @param angleX the X-angle in degrees to shear by
535  * @param angleY the Y-angle in degrees to shear by
536  */
537  void shearNode(double angleX, double angleY);
538 
539  /**
540  * @brief thumbnail create a thumbnail of the given dimensions. The thumbnail is sized according
541  * to the layer dimensions, not the image dimensions. If the requested size is too big a null
542  * QImage is created. If the current node cannot generate a thumbnail, a transparent QImage of the
543  * requested size is generated.
544  * @return a QImage representing the layer contents.
545  */
546  QImage thumbnail(int w, int h);
547 
548  /**
549  * @brief layerStyleToAsl retrieve the current layer's style in ASL format.
550  * @return a QString in ASL format representing the layer style.
551  */
552  QString layerStyleToAsl();
553 
554  /**
555  * @brief setLayerStyleFromAsl set a new layer style for this node.
556  * @param aslContent a string formatted in ASL format containing the layer style
557  * @return true if layer style was set, false if failed.
558  */
559  bool setLayerStyleFromAsl(const QString &asl);
560 
561  /**
562  * @brief index the index of the node inside the parent
563  * @return an integer representing the node's index inside the parent
564  */
565  int index() const;
566 
567  /**
568  * @brief uniqueId uniqueId of the node
569  * @return a QUuid representing a unique id to identify the node
570  */
571  QUuid uniqueId() const;
572 
573 
574 private:
575 
576  friend class Filter;
577  friend class Document;
578  friend class Selection;
579  friend class GroupLayer;
580  friend class FileLayer;
581  friend class FilterLayer;
582  friend class FillLayer;
583  friend class VectorLayer;
584  friend class FilterMask;
585  friend class SelectionMask;
586  friend class TransparencyMask;
587  friend class TransformMask;
588  friend class ColorizeMask;
589  friend class CloneLayer;
590 
591  explicit Node(KisImageSP image, KisNodeSP node, QObject *parent = 0);
592 
593  /**
594  * @brief paintDevice gives access to the internal paint device of this Node
595  * @return the paintdevice or 0 if the node does not have an editable paint device.
596  */
597  KisPaintDeviceSP paintDevice() const;
598  KisImageSP image() const;
599  KisNodeSP node() const;
600 
601  struct Private;
602  Private *const d;
603 
604 };
605 
607 
608 #endif // LIBKIS_NODE_H
InfoObject wrap a properties map.
Definition: InfoObject.h:19
Q_SLOTSQ_SLOTS
The ColorizeMask class A colorize mask is a mask type node that can be used to color in line art.
Definition: ColorizeMask.h:59
The GroupLayer class A group layer is a layer that can contain other layers.
Definition: GroupLayer.h:29
The Document class encapsulates a Krita Document/Image.
Definition: Document.h:33
Selection represents a selection on Krita.
Definition: Selection.h:30
The TransformMask class A transform mask is a mask type node that can be used to store transformation...
Definition: TransformMask.h:22
The SelectionMask class A selection mask is a mask type node that can be used to store selections.
Definition: SelectionMask.h:26
The CloneLayer class A clone layer is a layer that takes a reference inside the image and shows the e...
Definition: CloneLayer.h:25
Filter: represents a filter and its configuration.
Definition: Filter.h:30
The TransparencyMask class A transparency mask is a mask type node that can be used to show and hide ...
The FillLayer class A fill layer is much like a filter layer in that it takes a name and filter.
Definition: FillLayer.h:24
The FileLayer class A file layer is a layer that can reference an external image and show said refere...
Definition: FileLayer.h:26
Node represents a layer or mask in a Krita image's Node hierarchy.
Definition: Node.h:21
The VectorLayer class A vector layer is a special layer that stores and shows vector shapes.
Definition: VectorLayer.h:31
The FilterMask class A filter mask, unlike a filter layer, will add a non-destructive filter to the c...
Definition: FilterMask.h:28
Q_DISABLE_COPY(Class)
QObject * parent() const const
The FilterLayer class A filter layer will, when compositing, take the composited image up to the poin...
Definition: FilterLayer.h:33
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Sep 29 2023 04:08:11 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.