Krita

Node.h
1/*
2 * SPDX-FileCopyrightText: 2016 Boudewijn Rempt <boud@valdyas.org>
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 */
21class KRITALIBKIS_EXPORT Node : public QObject
22{
23 Q_OBJECT
24 Q_DISABLE_COPY(Node)
25
26public:
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
32public 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 * @brief paint a line on the canvas. Uses current brush preset
575 * @param pointOne starting point
576 * @param pointTwo end point
577 */
578 void paintLine(const QPointF pointOne, const QPointF pointTwo);
579
580 /**
581 * @brief paint a rectangle on the canvas. Uses current brush preset
582 * @param rect QRect with x, y, width, and height
583 */
584 void paintRectangle(const QRectF &rect);
585
586 /**
587 * @brief paint a polygon on the canvas. Uses current brush preset
588 * @param list of Qpoints
589 */
590 void paintPolygon(const QList<QPointF> points);
591
592 /**
593 * @brief paint an ellipse on the canvas. Uses current brush preset
594 * @param rect QRect with x, y, width, and height
595 */
596 void paintEllipse(const QRectF &rect);
597
598 /**
599 * @brief paint a custom path on the canvas. Uses current brush preset
600 * @param path QPainterPath to determine path
601 */
602 void paintPath(const QPainterPath &path);
603
604 /**
605 * @brief paintAbility can be used to determine whether this node can be painted on with the current brush preset.
606 * @return QString, one of the following:
607 * <ul>
608 * <li>VECTOR - This node is vector-based.</li>
609 * <li>CLONE - This node is a Clone Layer.</li>
610 * <li>PAINT - This node is paintable by the current brush preset.</li>
611 * <li>UNPAINTABLE - This node is not paintable, or a null preset is somehow selected./li>
612 * <li>MYPAINTBRUSH_UNPAINTABLE - This node's non-RGBA colorspace cannot be painted on by the currently selected MyPaint brush.</li>
613 */
614 QString paintAbility();
615
616private:
617
618 friend class Filter;
619 friend class Document;
620 friend class Selection;
621 friend class GroupLayer;
622 friend class FileLayer;
623 friend class FilterLayer;
624 friend class FillLayer;
625 friend class VectorLayer;
626 friend class FilterMask;
627 friend class SelectionMask;
628 friend class TransparencyMask;
629 friend class TransformMask;
630 friend class ColorizeMask;
631 friend class CloneLayer;
632
633 explicit Node(KisImageSP image, KisNodeSP node, QObject *parent = 0);
634
635 /**
636 * @brief paintDevice gives access to the internal paint device of this Node
637 * @return the paintdevice or 0 if the node does not have an editable paint device.
638 */
639 KisPaintDeviceSP paintDevice() const;
640 KisImageSP image() const;
641 KisNodeSP node() const;
642
643 struct Private;
644 Private *const d;
645
646};
647
649
650#endif // LIBKIS_NODE_H
The CloneLayer class A clone layer is a layer that takes a reference inside the image and shows the e...
Definition CloneLayer.h:26
The ColorizeMask class A colorize mask is a mask type node that can be used to color in line art.
The Document class encapsulates a Krita Document/Image.
Definition Document.h:37
The FileLayer class A file layer is a layer that can reference an external image and show said refere...
Definition FileLayer.h:27
The FillLayer class A fill layer is much like a filter layer in that it takes a name and filter.
Definition FillLayer.h:25
The FilterLayer class A filter layer will, when compositing, take the composited image up to the poin...
Definition FilterLayer.h:34
The FilterMask class A filter mask, unlike a filter layer, will add a non-destructive filter to the c...
Definition FilterMask.h:29
The GroupLayer class A group layer is a layer that can contain other layers.
Definition GroupLayer.h:30
InfoObject wrap a properties map.
Definition InfoObject.h:20
Node represents a layer or mask in a Krita image's Node hierarchy.
Definition Node.h:22
The SelectionMask class A selection mask is a mask type node that can be used to store selections.
Selection represents a selection on Krita.
Definition Selection.h:31
The TransformMask class A transform mask is a mask type node that can be used to store transformation...
The TransparencyMask class A transparency mask is a mask type node that can be used to show and hide ...
The VectorLayer class A vector layer is a special layer that stores and shows vector shapes.
Definition VectorLayer.h:32
Q_SLOTSQ_SLOTS
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 19 2024 11:57:55 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.