File indexing completed on 2024-05-12 15:59:07
0001 /* 0002 * SPDX-FileCopyrightText: 2016 Boudewijn Rempt <boud@valdyas.org> 0003 * 0004 * SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 #ifndef LIBKIS_NODE_H 0007 #define LIBKIS_NODE_H 0008 0009 #include <QObject> 0010 0011 #include <kis_types.h> 0012 0013 #include "kritalibkis_export.h" 0014 #include "libkis.h" 0015 0016 /** 0017 * Node represents a layer or mask in a Krita image's Node hierarchy. Group layers can contain 0018 * other layers and masks; layers can contain masks. 0019 * 0020 */ 0021 class KRITALIBKIS_EXPORT Node : public QObject 0022 { 0023 Q_OBJECT 0024 Q_DISABLE_COPY(Node) 0025 0026 public: 0027 static Node *createNode(KisImageSP image, KisNodeSP node, QObject *parent = 0); 0028 ~Node() override; 0029 bool operator==(const Node &other) const; 0030 bool operator!=(const Node &other) const; 0031 0032 public Q_SLOTS: 0033 0034 /** 0035 * @brief clone clone the current node. The node is not associated with any image. 0036 */ 0037 Node *clone() const; 0038 0039 /** 0040 * @brief alphaLocked checks whether the node is a paint layer and returns whether it is alpha locked 0041 * @return whether the paint layer is alpha locked, or false if the node is not a paint layer 0042 */ 0043 bool alphaLocked() const; 0044 0045 /** 0046 * @brief setAlphaLocked set the layer to value if the node is paint layer. 0047 */ 0048 void setAlphaLocked(bool value); 0049 0050 /** 0051 * @return the blending mode of the layer. The values of the blending modes are defined in @see KoCompositeOpRegistry.h 0052 */ 0053 QString blendingMode() const; 0054 0055 /** 0056 * @brief setBlendingMode set the blending mode of the node to the given value 0057 * @param value one of the string values from @see KoCompositeOpRegistry.h 0058 */ 0059 void setBlendingMode(QString value); 0060 0061 /** 0062 * @brief channels creates a list of Channel objects that can be used individually to 0063 * show or hide certain channels, and to retrieve the contents of each channel in a 0064 * node separately. 0065 * 0066 * Only layers have channels, masks do not, and calling channels on a Node that is a mask 0067 * will return an empty list. 0068 * 0069 * @return the list of channels ordered in by position of the channels in pixel position 0070 */ 0071 QList<Channel*> channels() const; 0072 0073 /** 0074 * Return a list of child nodes of the current node. The nodes are ordered from the bottommost up. 0075 * The function is not recursive. 0076 */ 0077 QList<Node*> childNodes() const; 0078 0079 /** 0080 * @brief addChildNode adds the given node in the list of children. 0081 * @param child the node to be added 0082 * @param above the node above which this node will be placed 0083 * @return false if adding the node failed 0084 */ 0085 bool addChildNode(Node *child, Node *above); 0086 0087 /** 0088 * @brief removeChildNode removes the given node from the list of children. 0089 * @param child the node to be removed 0090 */ 0091 bool removeChildNode(Node *child); 0092 0093 /** 0094 * @brief setChildNodes this replaces the existing set of child nodes with the new set. 0095 * @param nodes The list of nodes that will become children, bottom-up -- the first node, 0096 * is the bottom-most node in the stack. 0097 */ 0098 void setChildNodes(QList<Node*> nodes); 0099 0100 /** 0101 * colorDepth A string describing the color depth of the image: 0102 * <ul> 0103 * <li>U8: unsigned 8 bits integer, the most common type</li> 0104 * <li>U16: unsigned 16 bits integer</li> 0105 * <li>F16: half, 16 bits floating point. Only available if Krita was built with OpenEXR</li> 0106 * <li>F32: 32 bits floating point</li> 0107 * </ul> 0108 * @return the color depth. 0109 */ 0110 QString colorDepth() const; 0111 0112 /** 0113 * @brief colorModel retrieve the current color model of this document: 0114 * <ul> 0115 * <li>A: Alpha mask</li> 0116 * <li>RGBA: RGB with alpha channel (The actual order of channels is most often BGR!)</li> 0117 * <li>XYZA: XYZ with alpha channel</li> 0118 * <li>LABA: LAB with alpha channel</li> 0119 * <li>CMYKA: CMYK with alpha channel</li> 0120 * <li>GRAYA: Gray with alpha channel</li> 0121 * <li>YCbCrA: YCbCr with alpha channel</li> 0122 * </ul> 0123 * @return the internal color model string. 0124 */ 0125 QString colorModel() const; 0126 0127 /** 0128 * @return the name of the current color profile 0129 */ 0130 QString colorProfile() const; 0131 0132 /** 0133 * @brief setColorProfile set the color profile of the image to the given profile. The profile has to 0134 * be registered with krita and be compatible with the current color model and depth; the image data 0135 * is <i>not</i> converted. 0136 * @param colorProfile 0137 * @return if assigning the color profile worked 0138 */ 0139 bool setColorProfile(const QString &colorProfile); 0140 0141 /** 0142 * @brief setColorSpace convert the node to the given colorspace 0143 * @param colorModel A string describing the color model of the node: 0144 * <ul> 0145 * <li>A: Alpha mask</li> 0146 * <li>RGBA: RGB with alpha channel (The actual order of channels is most often BGR!)</li> 0147 * <li>XYZA: XYZ with alpha channel</li> 0148 * <li>LABA: LAB with alpha channel</li> 0149 * <li>CMYKA: CMYK with alpha channel</li> 0150 * <li>GRAYA: Gray with alpha channel</li> 0151 * <li>YCbCrA: YCbCr with alpha channel</li> 0152 * </ul> 0153 * @param colorDepth A string describing the color depth of the image: 0154 * <ul> 0155 * <li>U8: unsigned 8 bits integer, the most common type</li> 0156 * <li>U16: unsigned 16 bits integer</li> 0157 * <li>F16: half, 16 bits floating point. Only available if Krita was built with OpenEXR</li> 0158 * <li>F32: 32 bits floating point</li> 0159 * </ul> 0160 * @param colorProfile a valid color profile for this color model and color depth combination. 0161 */ 0162 bool setColorSpace(const QString &colorModel, const QString &colorDepth, const QString &colorProfile); 0163 0164 /** 0165 * @brief Krita layers can be animated, i.e., have frames. 0166 * @return return true if the layer has frames. Currently, the scripting framework 0167 * does not give access to the animation features. 0168 */ 0169 bool animated() const; 0170 0171 /** 0172 * @brief enableAnimation make the current layer animated, so it can have frames. 0173 */ 0174 void enableAnimation() const; 0175 0176 /** 0177 * @brief Sets whether or not node should be pinned to the Timeline Docker, 0178 * regardless of selection activity. 0179 */ 0180 void setPinnedToTimeline(bool pinned) const; 0181 0182 /** 0183 * @return Returns true if node is pinned to the Timeline Docker or false if it is not. 0184 */ 0185 bool isPinnedToTimeline() const; 0186 0187 /** 0188 * Sets the state of the node to the value of @param collapsed 0189 */ 0190 void setCollapsed(bool collapsed); 0191 0192 /** 0193 * returns the collapsed state of this node 0194 */ 0195 bool collapsed() const; 0196 0197 /** 0198 * Sets a color label index associated to the layer. The actual 0199 * color of the label and the number of available colors is 0200 * defined by Krita GUI configuration. 0201 */ 0202 int colorLabel() const; 0203 0204 /** 0205 * @brief setColorLabel sets a color label index associated to the layer. The actual 0206 * color of the label and the number of available colors is 0207 * defined by Krita GUI configuration. 0208 * @param index an integer corresponding to the set of available color labels. 0209 */ 0210 void setColorLabel(int index); 0211 0212 /** 0213 * @brief inheritAlpha checks whether this node has the inherits alpha flag set 0214 * @return true if the Inherit Alpha is set 0215 */ 0216 bool inheritAlpha() const; 0217 0218 /** 0219 * set the Inherit Alpha flag to the given value 0220 */ 0221 void setInheritAlpha(bool value); 0222 0223 /** 0224 * @brief locked checks whether the Node is locked. A locked node cannot be changed. 0225 * @return true if the Node is locked, false if it hasn't been locked. 0226 */ 0227 bool locked() const; 0228 0229 /** 0230 * set the Locked flag to the give value 0231 */ 0232 void setLocked(bool value); 0233 0234 /** 0235 * @brief does the node have any content in it? 0236 * @return if node has any content in it 0237 */ 0238 bool hasExtents(); 0239 0240 0241 /** 0242 * @return the user-visible name of this node. 0243 */ 0244 QString name() const; 0245 0246 /** 0247 * rename the Node to the given name 0248 */ 0249 void setName(QString name); 0250 0251 /** 0252 * return the opacity of the Node. The opacity is a value between 0 and 255. 0253 */ 0254 int opacity() const; 0255 0256 /** 0257 * set the opacity of the Node to the given value. The opacity is a value between 0 and 255. 0258 */ 0259 void setOpacity(int value); 0260 0261 /** 0262 * return the Node that is the parent of the current Node, or 0 if this is the root Node. 0263 */ 0264 Node* parentNode() const; 0265 0266 /** 0267 * @brief type Krita has several types of nodes, split in layers and masks. Group 0268 * layers can contain other layers, any layer can contain masks. 0269 * 0270 * @return The type of the node. Valid types are: 0271 * <ul> 0272 * <li>paintlayer 0273 * <li>grouplayer 0274 * <li>filelayer 0275 * <li>filterlayer 0276 * <li>filllayer 0277 * <li>clonelayer 0278 * <li>vectorlayer 0279 * <li>transparencymask 0280 * <li>filtermask 0281 * <li>transformmask 0282 * <li>selectionmask 0283 * <li>colorizemask 0284 * </ul> 0285 * 0286 * If the Node object isn't wrapping a valid Krita layer or mask object, and 0287 * empty string is returned. 0288 */ 0289 virtual QString type() const; 0290 0291 /** 0292 * @brief icon 0293 * @return the icon associated with the layer. 0294 */ 0295 QIcon icon() const; 0296 0297 /** 0298 * Check whether the current Node is visible in the layer stack 0299 */ 0300 bool visible() const; 0301 0302 /** 0303 * Check to see if frame number on layer is a keyframe 0304 */ 0305 bool hasKeyframeAtTime(int frameNumber); 0306 0307 /** 0308 * Set the visibility of the current node to @param visible 0309 */ 0310 void setVisible(bool visible); 0311 0312 /** 0313 * @brief pixelData reads the given rectangle from the Node's paintable pixels, if those 0314 * exist, and returns it as a byte array. The pixel data starts top-left, and is ordered row-first. 0315 * 0316 * The byte array can be interpreted as follows: 8 bits images have one byte per channel, 0317 * and as many bytes as there are channels. 16 bits integer images have two bytes per channel, 0318 * representing an unsigned short. 16 bits float images have two bytes per channel, representing 0319 * a half, or 16 bits float. 32 bits float images have four bytes per channel, representing a 0320 * float. 0321 * 0322 * You can read outside the node boundaries; those pixels will be transparent black. 0323 * 0324 * The order of channels is: 0325 * 0326 * <ul> 0327 * <li>Integer RGBA: Blue, Green, Red, Alpha 0328 * <li>Float RGBA: Red, Green, Blue, Alpha 0329 * <li>GrayA: Gray, Alpha 0330 * <li>Selection: selectedness 0331 * <li>LabA: L, a, b, Alpha 0332 * <li>CMYKA: Cyan, Magenta, Yellow, Key, Alpha 0333 * <li>XYZA: X, Y, Z, A 0334 * <li>YCbCrA: Y, Cb, Cr, Alpha 0335 * </ul> 0336 * 0337 * The byte array is a copy of the original node data. In Python, you can use bytes, bytearray 0338 * and the struct module to interpret the data and construct, for instance, a Pillow Image object. 0339 * 0340 * If you read the pixeldata of a mask, a filter or generator layer, you get the selection bytes, 0341 * which is one channel with values in the range from 0..255. 0342 * 0343 * If you want to change the pixels of a node you can write the pixels back after manipulation 0344 * with setPixelData(). This will only succeed on nodes with writable pixel data, e.g not on groups 0345 * or file layers. 0346 * 0347 * @param x x position from where to start reading 0348 * @param y y position from where to start reading 0349 * @param w row length to read 0350 * @param h number of rows to read 0351 * @return a QByteArray with the pixel data. The byte array may be empty. 0352 0353 */ 0354 QByteArray pixelData(int x, int y, int w, int h) const; 0355 0356 /** 0357 * @brief pixelDataAtTime a basic function to get pixeldata from an animated node at a given time. 0358 * @param x the position from the left to start reading. 0359 * @param y the position from the top to start reader 0360 * @param w the row length to read 0361 * @param h the number of rows to read 0362 * @param time the frame number 0363 * @return a QByteArray with the pixel data. The byte array may be empty. 0364 */ 0365 QByteArray pixelDataAtTime(int x, int y, int w, int h, int time) const; 0366 0367 /** 0368 * @brief projectionPixelData reads the given rectangle from the Node's projection (that is, what the node 0369 * looks like after all sub-Nodes (like layers in a group or masks on a layer) have been applied, 0370 * and returns it as a byte array. The pixel data starts top-left, and is ordered row-first. 0371 * 0372 * The byte array can be interpreted as follows: 8 bits images have one byte per channel, 0373 * and as many bytes as there are channels. 16 bits integer images have two bytes per channel, 0374 * representing an unsigned short. 16 bits float images have two bytes per channel, representing 0375 * a half, or 16 bits float. 32 bits float images have four bytes per channel, representing a 0376 * float. 0377 * 0378 * You can read outside the node boundaries; those pixels will be transparent black. 0379 * 0380 * The order of channels is: 0381 * 0382 * <ul> 0383 * <li>Integer RGBA: Blue, Green, Red, Alpha 0384 * <li>Float RGBA: Red, Green, Blue, Alpha 0385 * <li>GrayA: Gray, Alpha 0386 * <li>Selection: selectedness 0387 * <li>LabA: L, a, b, Alpha 0388 * <li>CMYKA: Cyan, Magenta, Yellow, Key, Alpha 0389 * <li>XYZA: X, Y, Z, A 0390 * <li>YCbCrA: Y, Cb, Cr, Alpha 0391 * </ul> 0392 * 0393 * The byte array is a copy of the original node data. In Python, you can use bytes, bytearray 0394 * and the struct module to interpret the data and construct, for instance, a Pillow Image object. 0395 * 0396 * If you read the projection of a mask, you get the selection bytes, which is one channel with 0397 * values in the range from 0..255. 0398 * 0399 * If you want to change the pixels of a node you can write the pixels back after manipulation 0400 * with setPixelData(). This will only succeed on nodes with writable pixel data, e.g not on groups 0401 * or file layers. 0402 * 0403 * @param x x position from where to start reading 0404 * @param y y position from where to start reading 0405 * @param w row length to read 0406 * @param h number of rows to read 0407 * @return a QByteArray with the pixel data. The byte array may be empty. 0408 */ 0409 QByteArray projectionPixelData(int x, int y, int w, int h) const; 0410 0411 /** 0412 * @brief setPixelData writes the given bytes, of which there must be enough, into the 0413 * Node, if the Node has writable pixel data: 0414 * 0415 * <ul> 0416 * <li>paint layer: the layer's original pixels are overwritten 0417 * <li>filter layer, generator layer, any mask: the embedded selection's pixels are overwritten. 0418 * <b>Note:</b> for these 0419 * </ul> 0420 * 0421 * File layers, Group layers, Clone layers cannot be written to. Calling setPixelData on 0422 * those layer types will silently do nothing. 0423 * 0424 * @param value the byte array representing the pixels. There must be enough bytes available. 0425 * Krita will take the raw pointer from the QByteArray and start reading, not stopping before 0426 * (number of channels * size of channel * w * h) bytes are read. 0427 * 0428 * @param x the x position to start writing from 0429 * @param y the y position to start writing from 0430 * @param w the width of each row 0431 * @param h the number of rows to write 0432 * @return true if writing the pixeldata worked 0433 */ 0434 bool setPixelData(QByteArray value, int x, int y, int w, int h); 0435 0436 /** 0437 * @brief bounds return the exact bounds of the node's paint device 0438 * @return the bounds, or an empty QRect if the node has no paint device or is empty. 0439 */ 0440 QRect bounds() const; 0441 0442 /** 0443 * move the pixels to the given x, y location in the image coordinate space. 0444 */ 0445 void move(int x, int y); 0446 0447 /** 0448 * @brief position returns the position of the paint device of this node. The position is 0449 * always 0,0 unless the layer has been moved. If you want to know the topleft position of 0450 * the rectangle around the actual non-transparent pixels in the node, use bounds(). 0451 * @return the top-left position of the node 0452 */ 0453 QPoint position() const; 0454 0455 /** 0456 * @brief remove removes this node from its parent image. 0457 */ 0458 bool remove(); 0459 0460 /** 0461 * @brief duplicate returns a full copy of the current node. The node is not inserted in the graphic 0462 * @return a valid Node object or 0 if the node couldn't be duplicated. 0463 */ 0464 Node* duplicate(); 0465 0466 /** 0467 * @brief save exports the given node with this filename. The extension of the filename determines the filetype. 0468 * @param filename the filename including extension 0469 * @param xRes the horizontal resolution in pixels per pt (there are 72 pts in an inch) 0470 * @param yRes the horizontal resolution in pixels per pt (there are 72 pts in an inch) 0471 * @param exportConfiguration a configuration object appropriate to the file format. 0472 * @param exportRect the export bounds for saving a node as a QRect 0473 * If \p exportRect is empty, then save exactBounds() of the node. If you'd like to save the image- 0474 * aligned area of the node, just pass image->bounds() there. 0475 * See Document->exportImage for InfoObject details. 0476 * @return true if saving succeeded, false if it failed. 0477 */ 0478 bool save(const QString &filename, double xRes, double yRes, const InfoObject &exportConfiguration, const QRect &exportRect = QRect()); 0479 0480 /** 0481 * @brief mergeDown merges the given node with the first visible node underneath this node in the layerstack. 0482 * This will drop all per-layer metadata. 0483 */ 0484 Node *mergeDown(); 0485 0486 /** 0487 * @brief scaleNode 0488 * @param origin the origin point 0489 * @param width the width 0490 * @param height the height 0491 * @param strategy the scaling strategy. There's several ones amongst these that aren't available in the regular UI. 0492 * <ul> 0493 * <li>Hermite</li> 0494 * <li>Bicubic - Adds pixels using the color of surrounding pixels. Produces smoother tonal gradations than Bilinear.</li> 0495 * <li>Box - Replicate pixels in the image. Preserves all the original detail, but can produce jagged effects.</li> 0496 * <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> 0497 * <li>Bell</li> 0498 * <li>BSpline</li> 0499 * <li>Lanczos3 - Offers similar results than Bicubic, but maybe a little bit sharper. Can produce light and dark halos along strong edges.</li> 0500 * <li>Mitchell</li> 0501 * </ul> 0502 */ 0503 void scaleNode(QPointF origin, int width, int height, QString strategy); 0504 0505 /** 0506 * @brief rotateNode rotate this layer by the given radians. 0507 * @param radians amount the layer should be rotated in, in radians. 0508 */ 0509 void rotateNode(double radians); 0510 0511 /** 0512 * @brief cropNode crop this layer. 0513 * @param x the left edge of the cropping rectangle. 0514 * @param y the top edge of the cropping rectangle 0515 * @param w the right edge of the cropping rectangle 0516 * @param h the bottom edge of the cropping rectangle 0517 */ 0518 void cropNode(int x, int y, int w, int h); 0519 0520 /** 0521 * @brief shearNode perform a shear operation on this node. 0522 * @param angleX the X-angle in degrees to shear by 0523 * @param angleY the Y-angle in degrees to shear by 0524 */ 0525 void shearNode(double angleX, double angleY); 0526 0527 /** 0528 * @brief thumbnail create a thumbnail of the given dimensions. The thumbnail is sized according 0529 * to the layer dimensions, not the image dimensions. If the requested size is too big a null 0530 * QImage is created. If the current node cannot generate a thumbnail, a transparent QImage of the 0531 * requested size is generated. 0532 * @return a QImage representing the layer contents. 0533 */ 0534 QImage thumbnail(int w, int h); 0535 0536 /** 0537 * @brief layerStyleToAsl retreive the current layer's style in ASL format. 0538 * @return a QString in ASL format representing the layer style. 0539 */ 0540 QString layerStyleToAsl(); 0541 0542 /** 0543 * @brief setLayerStyleFromAsl set a new layer style for this node. 0544 * @param aslContent a string formatted in ASL format containing the layer style 0545 * @return true if layer style was set, false if failed. 0546 */ 0547 bool setLayerStyleFromAsl(const QString &asl); 0548 0549 /** 0550 * @brief index the index of the node inside the parent 0551 * @return an integer representing the node's index inside the parent 0552 */ 0553 int index() const; 0554 0555 /** 0556 * @brief uniqueId uniqueId of the node 0557 * @return a QUuid representing a unique id to identify the node 0558 */ 0559 QUuid uniqueId() const; 0560 0561 0562 private: 0563 0564 friend class Filter; 0565 friend class Document; 0566 friend class Selection; 0567 friend class GroupLayer; 0568 friend class FileLayer; 0569 friend class FilterLayer; 0570 friend class FillLayer; 0571 friend class VectorLayer; 0572 friend class FilterMask; 0573 friend class SelectionMask; 0574 friend class TransformMask; 0575 friend class CloneLayer; 0576 0577 explicit Node(KisImageSP image, KisNodeSP node, QObject *parent = 0); 0578 0579 /** 0580 * @brief paintDevice gives access to the internal paint device of this Node 0581 * @return the paintdevice or 0 if the node does not have an editable paint device. 0582 */ 0583 KisPaintDeviceSP paintDevice() const; 0584 KisImageSP image() const; 0585 KisNodeSP node() const; 0586 0587 struct Private; 0588 Private *const d; 0589 0590 }; 0591 0592 typedef QSharedPointer<Node> NodeSP; 0593 0594 #endif // LIBKIS_NODE_H