diff --git a/reference_manual/audio_for_animation.rst b/reference_manual/audio_for_animation.rst index f678334ea..13b7f1782 100644 --- a/reference_manual/audio_for_animation.rst +++ b/reference_manual/audio_for_animation.rst @@ -1,67 +1,69 @@ .. meta:: :description: The audio playback with animation in Krita. .. metadata-placeholder :authors: - Wolthera van Hövell tot Westerflier - Scott Petrovic - Marcidy :license: GNU free documentation license 1.3 or later. .. index:: Animation, Audio, Sound, Timeline .. _audio_animation: =================== Audio for Animation =================== .. caution:: Audio for animation is an unfinished feature. It has multiple bugs and may not work on your system. You can add audio files to your animation to help sync lips or music. This functionality is available in the timeline docker. Importing Audio Files --------------------- Krita supports MP3, OGM, and WAV audio files. When you open up your timeline docker, there will be a speaker button in the top left area. If you press the speaker button, you will get the available audio options for the animation. * Open * Mute * Remove audio * Volume slider Krita saves the location of your audio file. If you move the audio file or rename it, Krita will not be able to find it. Krita will tell you the file was moved or deleted the next time you try to open the Krita file up. + Using Audio +----------- After you import the audio, you can scrub through the timeline and it will play the audio chunk at the time spot. When you press the Play button, the entire the audio file will playback as it will in the final version. There is no visual display of the audio file on the screen, so you will need to use your ears and the scrubbing functionality to position frames. Exporting with Audio -------------------- To get the audio file included when you are exporting, you need to include it in the Render Animation options. In the :menuselection:`File --> Render Animation` options there is a checkbox :guilabel:`Include Audio`. Make sure that is checked before you export and you should be good to go. Packages needed for Audio on Linux ---------------------------------- The following packages are necessary for having the audio support on Linux: For people who build Krita on Linux: * libasound2-dev * libgstreamer1.0-dev gstreamer1.0-pulseaudio * libgstreamer-plugins-base1.0-dev * libgstreamer-plugins-good1.0-dev * libgstreamer-plugins-bad1.0-dev For people who use Krita on Linux: * libqt5multimedia5-plugins * libgstreamer-plugins-base1.0 * libgstreamer-plugins-good1.0 * libgstreamer-plugins-bad1.0 diff --git a/reference_manual/brushes/brush_settings/options.rst b/reference_manual/brushes/brush_settings/options.rst index 0665d1a91..bafd057d7 100644 --- a/reference_manual/brushes/brush_settings/options.rst +++ b/reference_manual/brushes/brush_settings/options.rst @@ -1,190 +1,190 @@ .. meta:: :description: Krita's Brush Engine options overview. .. metadata-placeholder :authors: - Wolthera van Hövell tot Westerflier - Raghavendra Kamath - Scott Petrovic - Hulmanen - Nmaghrufusman :license: GNU free documentation license 1.3 or later. .. _brush_options: ======= Options ======= .. index:: Airbrush .. _option_airbrush: Airbrush -------- .. image:: /images/en/Krita_2_9_brushengine_airbrush.png If you hold the brush still, but are still pressing down, this will keep adding colour onto the canvas. The lower the rate, the quicker the colour gets added. .. index:: Mirror .. _option_mirror: Mirror ------ .. image:: /images/en/Krita_Pixel_Brush_Settings_Mirror.png This allows you to mirror the Brush-tip with Sensors. Horizontal Mirrors the mask horizontally. Vertical Mirrors the mask vertically. .. image:: /images/en/Krita_2_9_brushengine_mirror.jpg Some examples of mirroring and using it in combination with :ref:`option_rotation`. .. _option_rotation: Rotation -------- This allows you to affect Angle of your brush-tip with Sensors. .. image:: /images/en/Krita_2_9_brushengine_rotation.png .. image:: /images/en/Krita_Pixel_Brush_Settings_Rotation.png In the above example, several applications of the parameter. #. Drawing Angle -- A common one, usually used in combination with rake-type brushes. Especially effect because it does not rely on tablet-specific sensors. Sometimes, Tilt-Direction or Rotation is used to achieve a similar-more tablet focused effect, where with Tilt the 0° is at 12 o'clock, Drawing angle uses 3 o'clock as 0°. #. Fuzzy -- Also very common, this gives a nice bit of randomness for texture. #. Distance -- With careful editing of the Sensor curve, you can create nice patterns. #. Fade -- This slowly fades the rotation from one into another. #. Pressure -- An interesting one that can create an alternative looking line. .. _option_scatter: Scatter ------- This parameter allows you to set the random placing of a brush-dab. You can affect them with Sensors. X The scattering on the angle you are drawing from. Y - The scattering, perpendicular tot he drawing angle (has the most effect) + The scattering, perpendicular to the drawing angle (has the most effect) .. image:: /images/en/Krita_2_9_brushengine_scatter.png .. _option_sharpness: Sharpness --------- .. image:: /images/en/Krita_Pixel_Brush_Settings_Sharpness.png Puts a threshold filter over the brush mask. .. _option_size: Size ---- .. image:: /images/en/Krita_Pixel_Brush_Settings_Size.png This parameter is not the diameter itself, but rather the curve for how it's affected. So, if you want to lock the diameter of the brush, lock the Brush-tip. Locking the size parameter will only lock this curve. Allowing this curve to be affected by the Sensors can be very useful to get the right kind of brush. For example, if you have trouble drawing fine lines, try to use a concave curve set to pressure. That way you'll have to press hard for thick lines. .. image:: /images/en/Krita_2_9_brushengine_size_01.png Also popular are setting the size to the sensor fuzzy or perspective, with the later in combination with a :ref:`assistant_perspective` .. image:: /images/en/Krita_2_9_brushengine_size_02.png .. _option_softness: Softness -------- This allows you to affect Fade with Sensors. .. image:: /images/en/Krita_2_9_brushengine_softness.png Has a slight brush-decreasing effect, especially noticeable with soft-brush, and is overall more noticeable on large brushes. .. _option_source: Source ------ Picks the source-colour for the brush-dab. Plain Color Current foreground color. Gradient Picks active gradient Uniform Random Gives a random colour to each brush dab. Total Random Random noise pattern is now painted. Pattern Uses active pattern, but alignment is different per stroke. Locked Pattern Locks the pattern to the brushdab .. _option_mix: Mix --- Allows you to affect the mix of the :ref:`option_source` color with Sensors. It will work with Plain Color and Gradient as source. If Plain Color is selected as source, it will mix between foreground and background colors selected in color picker. If Gradient is selected, it chooses a point on the gradient to use as painting color according to the sensors selected. .. image:: /images/en/Krita_2_9_brushengine_mix_01.png Uses ~~~ .. image:: /images/en/Krita_2_9_brushengine_mix_02.png Flow map The above example uses a :program:`Krita` painted flowmap in the 3d program :program:`Blender`. a brush was set to source Gradient and Mix:Drawing angle. The gradient in question contained the 360° for normal map colours. Flow maps are used in several Shaders, such as brushed metal, hair and certain river-shaders. .. _option_gradient: Gradient ~~~~~~~~ Exactly the same as using Source:Gradient with Mix, but only available for the Color Smudge Brush. .. index:: Spacing .. _option_spacing: Spacing ------- .. image:: /images/en/Krita_Pixel_Brush_Settings_Spacing.png This allows you to affect :ref:`option_brush_tip` with :ref:`sensors`. .. image:: /images/en/Krita_2_9_brushengine_spacing_02.png -;Isotropic. -:Instead of the spacing being related to the ratio of the brush, it will be on diameter only. +Isotropic + Instead of the spacing being related to the ratio of the brush, it will be on diameter only. .. image:: /images/en/Krita_2_9_brushengine_spacing_01.png .. index:: Ratio .. _option_ratio: Ratio ----- Allows you to change the ratio of the brush and bind it to parameters. This also works for predefined brushes. .. image:: /images/en/Krita_3_0_1_Brush_engine_ratio.png diff --git a/reference_manual/filters/edge_detection.rst b/reference_manual/filters/edge_detection.rst index 6fd7e3964..e1baaa5f5 100644 --- a/reference_manual/filters/edge_detection.rst +++ b/reference_manual/filters/edge_detection.rst @@ -1,93 +1,93 @@ .. meta:: :description: Overview of the edgedetection filters. .. metadata-placeholder :authors: - Wolthera van Hövell tot Westerflier - Raghavendra Kamath :license: GNU free documentation license 1.3 or later. .. index:: Edge Detection, Sobel, Prewitt .. _edge_detection_filters: ============== Edge Detection ============== Edge detection filters focus on finding sharp contrast or border between colors in an image to create edges or lines. -Since 4.0 there's only two edge detection filters. +Since 4.0 there are only two edge detection filters. Edge Detection -------------- .. versionadded:: 4.0 A general edge detection filter that encapsulates all other filters. Edge detection filters that were separate before 4.0 have been folded into this one. It is also available for filter layers and filter brushes. .. figure:: /images/en/Krita_4_0_edge_detection.png :align: center :figwidth: 800 From left to right: Original, with prewitt edge detection applied, with prewitt edge detection applied and result applied to alpha channel, and finally the original with an edge detection filter layer with the same settings as 3, and the filter layer blending mode set to multiply Formula The convolution kernel formula for the edge detection. The difference between these is subtle, but still worth experimenting with. Simple A Kernel that is not square unlike the other two, and while this makes it fast, it doesn't take diagonal pixels into account. Prewitt A square kernel that includes the diagonal pixels just as strongly as the orthogonal pixels. Gives a very strong effect. Sobol A square kernel that includes the diagonal pixels slightly less strong than the orthogonal pixels. Gives a more subtle effect than Prewitt. Output The output. All sides Convolves the edge detection into all directions and combines the result with the Pythagorean theorem. This will be good for most uses. Top Edge This only detects changes going from top to bottom and thus only has top lines. Bottom Edge This only detects changes going from bottom to top and thus only has bottom lines. Right Edge This only detects changes going from right to left and thus only has right lines. Left Edge This only detects changes going from left to right and thus only has left lines. Direction in Radians This convolves into all directions and then tries to output the direction of the line in radians. Horizontal/Vertical radius The radius of the edge detection. Default is 1 and going higher will increase the thickness of the lines. Apply result to Alpha Channel. The edge detection will be used on a grayscale copy of the image, and the output will be onto the alpha channel of the image, meaning it will output lines only. .. index:: Height Map, Normal Map Height to Normal Map -------------------- .. versionadded:: 4.0 .. image:: /images/en/Krita_4_0_height_to_normal_map.png :align: center A filter that converts Height maps to Normal maps through the power of edge detection. It is also available for the filter layer or filter brush. Formula The convolution kernel formula for the edgedetection. The difference between these is subtle, but still worth experimenting with. Simple A Kernel that is not square unlike the other two, and while this makes it fast, it doesn't take diagonal pixels into account. Prewitt A square kernel that includes the diagonal pixels just as strongly as the orthogonal pixels. Gives a very strong effect. Sobol A square kernel that includes the diagonal pixels slightly less strong than the orthogonal pixels. Gives a more subtle effect than Prewitt. Channel Which channel of the layer should be interpreted as the grayscale heightmap. Horizontal/Vertical radius The radius of the edge detection. Default is 1 and going higher will increase the strength of the normal map. Adjust this if the effect of the resulting normal map is too weak. XYZ An XYZ swizzle, that allows you to map Red, Green and Blue to different 3d normal vector coordinates. This is necessary mostly for the difference between Mikkt-space normal maps (+X, +Y, +Z) and the OpenGL standard normal map (+X, -Y, +Z). diff --git a/reference_manual/preferences/performance_settings.rst b/reference_manual/preferences/performance_settings.rst index c6e965421..ba77b00e9 100644 --- a/reference_manual/preferences/performance_settings.rst +++ b/reference_manual/preferences/performance_settings.rst @@ -1,120 +1,120 @@ .. meta:: :description: Performance settings in Krita. .. metadata-placeholder :authors: - Wolthera van Hövell tot Westerflier - Scott Petrovic :license: GNU free documentation license 1.3 or later. .. index:: Preferences, Settings, Performance, Multithreading, RAM, Memory Usage, Lag .. _performance_settings: ==================== Performance Settings ==================== -:program:`Krita`, as a painting program, juggles a lot of data around, like the brushes you use, the colours you picked, but primarily, each pixel in your image. Due to this, how :program:`Krita` organises where it stores all the data can really speed up :program:`Krita` while painting, just like having an organised artist's workplace can really speed up the painting process in real life. +:program:`Krita`, as a painting program, juggles a lot of data around, like the brushes you use, the colors you picked, but primarily, each pixel in your image. Due to this, how :program:`Krita` organizes where it stores all the data can really speed up :program:`Krita` while painting, just like having an organized artist's workplace can really speed up the painting process in real life. These preferences allow you to configure :program:`Krita's` organisation, but all do require you to restart :program:`Krita`, so it can do this organisation properly. RAM --- RAM, or Random Access Memory, is the memory your computer is immediately using. The difference between RAM and the hard drive memory can be compared to the difference between having files on your desk and having files safely stored away in an archiving room: The files on your desk as much easier to access than the ones in your archive, and it takes time to pull new files from the archive. This is the same for you computer and RAM. Files need to be loaded into RAM before the computer can really use them, and storing and removing them from RAM takes time. These settings allow you to choose how much of your virtual desk you dedicate to :program:`Krita`. :program:`Krita` will then reserve them on start-up. This does mean that if you change any of the given options, you need to restart :program:`Krita` so it can make this reservation. Memory Limit This is the maximum space :program:`Krita` will reserve on your RAM on startup. It's both available in percentages and Bytes, so you can specify precisely. :program:`Krita` will not take up more space than this, making it safe for you to run an internet browser or music on the background. Internal Pool - A feature for advanced computer users. This allows :program:`Krita` to organise the area it takes up on the virtual working desk before putting its data on there. Like how a painter has a standard spot for their canvas, :program:`Krita` also benefits from giving certain data it uses its place (a memory pool), so that it can find them easily, and it doesn't get lost amongst the other data (memory fragmentation). It will then also not have to spent time finding a spot for this data. + A feature for advanced computer users. This allows :program:`Krita` to organize the area it takes up on the virtual working desk before putting its data on there. Like how a painter has a standard spot for their canvas, :program:`Krita` also benefits from giving certain data it uses its place (a memory pool), so that it can find them easily, and it doesn't get lost among the other data (memory fragmentation). It will then also not have to spent time finding a spot for this data. Increasing this of course means there's more space for this type of data, but like how filling up your working desk with only one big canvas will make it difficult to find room for your paints and brushes, having a large internal pool will result in :program:`Krita` not knowing where to put the other non-specific data. On the opposite end, not giving your canvas a spot at all, will result in you spending more time looking for a place where you will put the new layer or that reference you just took out of the storage. This happens for :program:`Krita` as well, making it slower. This is recommended to be a size of one layer of your image, e.g. if you usually paint on the image of 3000x3000x8bit-ARGB, the pool should be something like 36 MiB. As :program:`Krita` does this on start-up, you will need to restart :program:`Krita` to have this change affect anything. Swap Undo After :program:`Krita` also needs to keep all the Undo states on the virtual desk (RAM). Swapping means that parts of the files on the virtual desk get sent to the virtual archive room. This allows :program:`Krita` to dedicate more RAM space to new actions, by sending old Undo states to the archive room once it hits this limit. This will make undoing a little slower, but this can be desirable for the performance of :program:`Krita` overall. This too needs :program:`Krita` to be restarted. Swapping -------- File Size Limit This determines the limit of the total space :program:`Krita` can take up in the virtual archive room. If :program:`Krita` hits the limit of both the memory limit above, and this Swap File limit, it can't do anything any more (and will freeze). Swap File Location This determines where the Swap File will be stored on you hard-drive. Location can make a difference, for example, Solid State Drives (SSD) are faster than Hard Disk Drives (HDD). Some people even like to use USB-sticks for the swap file location. Advanced -------- Multithreading ~~~~~~~~~~~~~~ Since 4.0, Krita supports multithreading for the animation cache and handling the drawing of brush tips when using the pixel brush. CPU Limit The amount of cores you want to allow Krita to use when multithreading. Frame Rendering Clones Limit When rendering animations to frames, Krita multithreads by keeping a few copies of the image, with a maximum determined by the amount of cores your processor has. If you have a heavy animation file and lots of cores, the copies can be quite heavy on your machine, so in that case try lowering this value. Other ~~~~~ Limit frames per second while painting. This makes the canvas update less often, which means Krita can spend more time calculating other things. Some people find fewer updates unnerving to watch however, hence this is configurable. -Debuglogging of OpenGL framerate +Debug logging of OpenGL framerate Will show the canvas framerate on the canvas when active. Debug logging for brush rendering speed. Will show numbers indicating how fast the last brush stroke was on canvas. -Disable vector optimisations (For AMD CPUs) - Vector optimisations are a special way of asking the CPU to do maths, these have names such as SIMD and AVX. These optimisations can make Krita a lt faster when painting, except when you have a AMD CPU under windows. There seems to be something strange going on there, so just deactivate them then. -Enable Progress Reporting +Disable vector optimizations (for AMD CPUs) + Vector optimizations are a special way of asking the CPU to do maths, these have names such as SIMD and AVX. These optimizations can make Krita a lot faster when painting, except when you have a AMD CPU under windows. There seems to be something strange going on there, so just deactivate them then. +Enable progress reporting This allows you to toggle the progress reporter, which is a little feedback progress bar that shows up in the status bar when you let Krita do heavy operations, such as heavy filters or big strokes. The red icon next to the bar will allow you to cancel your operation. This is on by default, but as progress reporting itself can take up some time, you can switch it off here. Performance logging This enables performance logging, which is then saved to the ``Log`` folder in your ``working directory``. Your working directory is where the auto save is saved at as well. So for unnamed files, this is the ``$home`` folder in Linux, and the ``%TEMP%`` folder in windows. Animation Cache --------------- .. versionadded:: 4.1 The animation cache is the space taken up by animation frames in the memory of the computer. A cache in this sense is a cache of precalculated images. Playing back a video at 25 FPS means that the computer has to precalculate 25 images per second of video. Now, video playing software is able to do this because it really focuses on this one single task. However, Krita as a painting program also allows you to edit the pictures. Because Krita needs to be able to do this, and a dedicated video player doesn't, Krita cannot do the same kind of optimizations as a dedicated video player can. Still, an animator does need to be able to see what kind of animation they are making. To do this properly, we need to decide how Krita will regenerate the cache after the animator makes a change. There's fortunately a lot of different options how we can do this. However, the best solution really depends on what kind of computer you have and what kind of animation you are making. Therefore in this tab you can customize the way how and when the cache is generated. Cache Storage Backend ~~~~~~~~~~~~~~~~~~~~~ In-memory Animation frame cache will be stored in RAM, completely without any limitations. This is also the way it was handled before 4.1. This is only recommended for computers with huge amount of RAM and animations that must show full-canvas full resolution 6k at 25 fps. If you do not have a huge amount (say, 64GiB) of ram, do *not* use this option (and scale down your projects). .. warning:: Please make sure your computer has enough RAM *above* the amount you requested in the general tab. Otherwise you might face system freezes. * For 1 second of FullHD @ 25 FPS you will need 200 extra MiB of Memory * For 1 second of 4K UltraHD@ 25 FPS, you will need 800 extra MiB of Memory. On-disk Animation frames are stored in the hard disk in the same folder as the swap file. The cache is stored in a compressed way. A little amount of extra RAM is needed. Since data transfer speed of the hard drive is slow. You might want to limit the :guilabel:`Cached Frame Size` to be able to play your video at 25 fps. A limit of 2500 px is usually a good choice. Cache Generation Options ~~~~~~~~~~~~~~~~~~~~~~~~ Limit Cached Frame Size Render scaled down version of the frame if the image is bigger than the provided limit. Make sure you enable this option when using On-Disk storage backend, because On-Disk storage is a little slow. Without the limit, there's a good chance that it will not be able to render at full speed. Lower the size to play back faster at the cost of lower resolution. Use Region Of Interest We technically only need to use the section of the image that is in view. Region of interest represents that section. When the image is above the configurable limit, render only the currently visible part of it. Enable Background Cache Generation This allows you to set whether the animation is cached for playback in the background (that is, when you're not using the computer). Then, when animation is cached when pressing play, this caching will take less long. However, turning off this automatic caching can save power by having your computer work less. diff --git a/reference_manual/tools/colorize_mask.rst b/reference_manual/tools/colorize_mask.rst index 4efeaad2d..acf6bd452 100644 --- a/reference_manual/tools/colorize_mask.rst +++ b/reference_manual/tools/colorize_mask.rst @@ -1,174 +1,174 @@ .. meta:: :description: How to use the colorize mask in Krita. .. metadata-placeholder :authors: - Wolthera van Hövell tot Westerflier - Scott Petrovic :license: GNU free documentation license 1.3 or later. .. index:: Tools, Lazybrush, Colorize Mask, Masks, Layers, Flat Color .. _colorize_mask: ============= Colorize Mask ============= |toolcolorizemask| -A tool for quickly coloring lineart, the Colorize Mask Editing tool can be found next to the gradient tool on your toolbox. +A tool for quickly coloring line art, the Colorize Mask Editing tool can be found next to the gradient tool on your toolbox. -This feature is technically already in 3.1, but disabled by default because we had not optimised the filling algorithm for production use yet. To enable it, find your krita configuration file, open it in notepad, and add "disableColorizeMaskFeature=false" to the top. Then restart Krita. Its official incarnation is in 4.0. +This feature is technically already in 3.1, but disabled by default because we had not optimized the filling algorithm for production use yet. To enable it, find your krita configuration file, open it in notepad, and add "disableColorizeMaskFeature=false" to the top. Then restart Krita. Its official incarnation is in 4.0. Usage ----- This tool works in conjunction with the colorize mask, and the usage is as follows: -For this example, we'll be using the ghost lady also used to explain masks on the basic concepts page. +For this example, we'll be using the ghost lady also used to explain masks on :ref:`the basic concepts page `. .. image:: /images/en/Krita_4_0_colorize_mask_usage_01.png :width: 800 :align: center This image has the line art for the lady separated from the background, and what's more, the background is made up of two layers: one main and one for the details. -First, select the colorize mask editing tool while having the lineart layer selected. |mouseleft| the canvas will add a colorize mask to the layer. -You can also |mouseright| the line art layer, and then :menuselection:`Add --> Colorize Mask`. The line art will suddenly become really weird, this is the prefiltering which are filters through which we put the lineart to make the algorithm easier to use. The tool options overview below shows which options control that. +First, select the colorize mask editing tool while having the line art layer selected. |mouseleft| the canvas will add a colorize mask to the layer. +You can also |mouseright| the line art layer, and then :menuselection:`Add --> Colorize Mask`. The line art will suddenly become really weird, this is the prefiltering which are filters through which we put the line art to make the algorithm easier to use. The tool options overview below shows which options control that. .. image:: /images/en/Krita_4_0_colorize_mask_usage_02.png :width: 800 :align: center Now, You make strokes with brush colors, press :guilabel:`Update` in the tool options, or tick the last icon of the colorize mask properties. In the layer docker, you will be able to see a little progress bar appear on the colorize mask indicating how long it takes. The bigger your file, the longer it will take. .. image:: /images/en/Krita_4_0_colorize_mask_usage_03.png :width: 800 :align: center We want to have the blue transparent. In the tool options of the colorize editing tool you will see a small palette. These are the colors already used. You can remove colors here, or mark a single color as standing for transparent, by selecting it and pressing "transparent". Updating the mask will still show the blue stroke, but the result will be transparent: .. image:: /images/en/Krita_4_0_colorize_mask_usage_04.png :width: 800 :align: center Because the colorize mask algorithm is slow, and we only need a part of our layer to be filled to fill the whole ghost lady figure, we can make use of :guilabel:`Limit to layer bounds`. This will limit Colorize Mask to use the combined size of the line art and the coloring key strokes. Therefore, make sure that the colorizing keystrokes only take up as much as they really need. .. image:: /images/en/Krita_4_0_colorize_mask_usage_05.png :width: 800 :align: center Now the algorithm will be possibly a lot faster, allowing us to add strokes and press update in rapid succession: .. image:: /images/en/Krita_4_0_colorize_mask_usage_06.png :width: 800 :align: center To see the final result, disable :guilabel:`Edit Key Strokes` or toggle the second to last icon on the colorize mask. .. image:: /images/en/Krita_4_0_colorize_mask_usage_07.png :width: 800 :align: center If you want to edit the strokes again, re-enable :guilabel:`Edit Key Strokes`. -Now, the colorize mask, being a mask, can also be added to a group of line art layers. It will then use the composition of the whole group as the line art. This is perfect for our background which has two separate line art layers. It also means that the colorize mask will be disabled when added to a group with pass-through enabled, because those have no final composition. You can recognise a disabled colorize mask because its name is stricken through. +Now, the colorize mask, being a mask, can also be added to a group of line art layers. It will then use the composition of the whole group as the line art. This is perfect for our background which has two separate line art layers. It also means that the colorize mask will be disabled when added to a group with pass-through enabled, because those have no final composition. You can recognize a disabled colorize mask because its name is stricken through. To add a colorize mask to a group, select the group and |mouseleft| the canvas with the Colorize Mask editing tool, or |mouseright| the layer to :menuselection:`Add --> Colorize Mask`. .. image:: /images/en/Krita_4_0_colorize_mask_usage_08.png :width: 800 :align: center Now, we add strokes to the background quickly. We do not need to use the :menuselection:`Limit to Layer Bounds` because the background covers the whole image. .. image:: /images/en/Krita_4_0_colorize_mask_usage_09.png :width: 800 :align: center For the record, you can use other brushes and tools also work on the colorize mask as long as they can draw. The Colorize Mask Editing tool is just the most convenient because you can get to the algorithm options. Out final result looks like this: .. image:: /images/en/Krita_4_0_colorize_mask_usage_10.png :width: 800 :align: center Now we are done, |mouseright| the colorize mask and :menuselection:`Convert --> to Paint Layer`. Then, :menuselection:`Layer --> Split --> Split Layer`. This will give separate color islands that you can easily edit: .. image:: /images/en/Krita_4_0_colorize_mask_usage_11.png :width: 800 :align: center This way we can very quickly paint the image. Due to the colorize mask going from the first image to the following took only 30 minutes, and would've taken quite a bit longer. .. image:: /images/en/Krita_4_0_colorize_mask_usage_12.png :width: 800 :align: center The colorize masks are saved to the .kra file, so as long as you don't save and open to a different file format, nor convert the colorize mask to a paintlayer, you can keep working adjust the results. Tool Options ------------ Update Run the colorize mask algorithm. The progress bar for updates on a colorize mask shows only in the layer docker. Edit key strokes - Put the mask into edit mode. In edit mode, it will also show the 'pre-filtering' on the line-art, which is for example a blur filter for gap closing. + Put the mask into edit mode. In edit mode, it will also show the 'prefiltering' on the line art, which is for example a blur filter for gap closing. Show output Show the output of the colorize mask. If :guilabel:`Edit key strokes` is active, this will be shown semi-transparently, so it will be easy to recognise the difference between the strokes and the output. .. figure:: /images/en/Krita_4_0_colorize_mask_show_output_edit_strokes.png :width: 800 :align: center On the **Left**: :guilabel:`Show Output` is on, :guilabel:`Edit Strokes` is off. In the **Middle**: :guilabel:`Show Output` and :guilabel:`Edit Strokes` are on. On the **Right**: :guilabel:`Show Output` is off and :guilabel:`Edit Strokes` is on.]] Limit to layer bounds Limit the colorize mask to the combined layer bounds of the strokes and the line art it is filling. This can speed up the use of the mask on complicated compositions, such as comic pages. Edge detection Activate this for line art with large solid areas, for example shadows on an object. For the best use, set the value to the thinnest lines on the image. In the image below, note how edge detection affects the big black areas: .. figure:: /images/en/Krita_4_0_colorize_mask_edge_detection.png :width: 800 :align: center From left to right: an example with big black shadows on an object but no edge detection, the same example without the edit strokes enabled. Then the same example with edge detection enabled and set to 2px, and that same example with out edit strokes enabled. Gap close hint While the algorithm is pretty good against gaps in contours, this will improve the gap recognition. The higher this value is, the bigger the gaps it will try to close, but a too high value can lead to other errors. Note how the pre-filtered line art (that's the blurry haze) affects the color patches. .. figure:: /images/en/Krita_4_0_colorize_mask_gap_close_hint.png :width: 800 :align: center On the **Left**: :guilabel:`Gap close hint` is 0px. In the **Middle**: :guilabel:`Gap close hint` is 15px (the lines are 10px). On the **Right**: :guilabel:`Gap close hint` is 275px. Clean-up strokes This will attempt to handle messy strokes that overlap the line art where they shouldn't. At 0 no clean up is done, at 100% the clean-up is most aggressive. .. image:: /images/en/Krita_4_0_colorize_mask_clean_up.png :width: 800 :align: center Keystrokes This palette keeps track of the colors used by the strokes. This is useful so you can switch back to colors easily. You can increase the swatch size by hovering over it with the mouse, and doing :kbd:`Ctrl +` |mousescroll|. Transparent This button is under the keystrokes palette, you can mark the selected color to be interpreted a 'transparent' with this. In the clean-up screenshot above, cyan had been marked as transparent. Layer properties ---------------- The colorize mask layer has four properties. They are all the buttons on the right side of the layer: Show output The first button, it allows you to toggle whether you'll see the output from the colorize algorithm. Lock Stops the mask from being edited. Edit key strokes Whether the colorize mask is in edit mode. In edit mode it'll show the strokes, and the output will be semi-transparent. Update The last button will force the colorize mask to update, even when you're in a different tool. Colorize masks cannot be animated. diff --git a/user_manual/python_scripting/krita_python_plugin_howto.rst b/user_manual/python_scripting/krita_python_plugin_howto.rst index 50b370b1e..e5dd03189 100644 --- a/user_manual/python_scripting/krita_python_plugin_howto.rst +++ b/user_manual/python_scripting/krita_python_plugin_howto.rst @@ -1,355 +1,355 @@ .. meta:: :description: Guide on all the specifics of creating Krita python plugins. .. metadata-placeholder :authors: - Wolthera van Hövell tot Westerflier - BrendanD - Scott Petrovic - Boudewijn Rempt - TPaulssen :license: GNU free documentation license 1.3 or later. .. index:: Python, Python Scripting, Scripting, Plugin .. _krita_python_plugin_howto: ================================= How to make a Krita Python plugin ================================= You might have some neat scripts you have written in the Scripter Python runner, but maybe you want to do more with it and run it automatically for instance. Wrapping your script in a plugin can give you much more flexibility and power than running scripts from the Scripter editor. Okay, so even if you know python really well, there are some little details to getting Krita to recognize a python plugin. So this page will give an overview how to create the various types of python script unique to Krita. These mini-tutorials are written for people with a basic understanding of python, and in such a way to encourage experimentation instead of plainly copy and pasting code, so read the text carefully. Getting Krita to recognize your plugin -------------------------------------- -A script in Krita has two components - the script directory (holding your script's Python files) and a ".desktop" file that Krita uses to load and register your script. For Krita to load your script both of these must put be in the pykrita subdirectory of your Krita resources folder (on Linux ~/.local/share/krita/pykrita). To find your resources folder start Krita and click the :menuselection:`Settings --> Manage Resources menu item`. This will open a dialog box. Click the :guilabel:`Open Resources Folder` button. This should open a file manager on your system at your Krita resources folder. See the `API `_ docs under "Auto starting scripts". If there is no pykrita subfolder in the Krita resources directory use your file manager to create one. +A script in Krita has two components - the script directory (holding your script's Python files) and a ".desktop" file that Krita uses to load and register your script. For Krita to load your script both of these must put be in the pykrita subdirectory of your Krita resources folder (on Linux ~/.local/share/krita/pykrita). To find your resources folder start Krita and click the :menuselection:`Settings --> Manage Resources` menu item. This will open a dialog box. Click the :guilabel:`Open Resources Folder` button. This should open a file manager on your system at your Krita resources folder. See the `API `_ docs under "Auto starting scripts". If there is no pykrita subfolder in the Krita resources directory use your file manager to create one. Scripts are identified by a file that ends in a .desktop extension that contain information about the script itself. Therefore, for each proper plugin you will need to create a folder, and a desktop file. The desktop file should look as follows:: [Desktop Entry] Type=Service ServiceTypes=Krita/PythonPlugin X-KDE-Library=myplugin X-Python-2-Compatible=false X-Krita-Manual=myPluginManual.html Name=My Own Plugin Comment=Our very own plugin. Type This should always be service. ServiceTypes This should always be Krita/PythonPlugin for python plugins. X-KDE-Library This should be the name of the plugin folder you just created. X-Python-2-Compatible Whether it is python 2 compatible. If Krita was built with python 2 instead of 3 (``-DENABLE_PYTHON_2=ON`` in the cmake configuration), then this plugin will not show up in the list. X-Krita-Manual An Optional Value that will point to the manual item. This is shown in the Python Plugin manager. If it's `an HTML file it'll be shown as rich text `_, if not, it'll be shown as plain text. Name The name that will show up in the Python Plugin Manager Comment The description that will show up in the Python Plugin Manager. Krita python plugins need to be python modules, so make sure there's an __init__.py script, containing something like... .. code:: python from .myplugin import * Where .myplugin is the name of the main file of your plugin. If you restart Krita, it now should show this in the Python Plugin Manager in the settings, but it will be grayed out, because there's no myplugin.py. If you hover over disabled plugins, you can see the error with them. Summary ^^^^^^^ In summary, if you want to create a script called *myplugin*: - in your Krita *resources/pykrita* directory create - a folder called *myplugin* - a file called *myplugin.desktop* - in the *myplugin* folder create - a file called *__init__.py* - a file called *myplugin.py* - in the *__init__.py* file put this code: .. code:: python from .myplugin import * - in the desktop file put this code:: [Desktop Entry] Type=Service ServiceTypes=Krita/PythonPlugin X-KDE-Library=myplugin X-Python-2-Compatible=false Name=My Own Plugin Comment=Our very own plugin. - write your script in the ''myplugin/myplugin.py'' file. Creating an extension --------------------- `Extensions `_ are relatively simple python scripts that run on Krita start. They are made by extending the Extension class, and the most barebones extension looks like this: .. code:: python from krita import * class MyExtension(Extension): def __init__(self, parent): #This is initialising the parent, always important when subclassing. super().__init__(parent) def setup(self): pass def createActions(self, window): pass # And add the extension to Krita's list of extensions: Krita.instance().addExtension(MyExtension(Krita.instance())) This code of course doesn't do anything. Typically, in createActions we add actions to Krita, so we can access our script from the :guilabel:`Tools` menu. First, let's create an `action `_. We can do that easily with `Window.createAction() `_. Krita will call createActions for every Window that is created and pass the right window object that we have to use. So... .. code:: python def createActions(self, window): action = window.createAction("myAction", "My Script", "tools/scripts") "myAction" This should be replaced with a unique id that Krita will use to find the action. "My Script" This is what will be visible in the tools menu. if you now restart Krita, you will have an action called "My Script". It still doesn't do anything, because we haven't connected it to a script. -So, lets make a simple export document script. Add the following to the extension class, make sure it is above where you add the extension to Krita: +So, let's make a simple export document script. Add the following to the extension class, make sure it is above where you add the extension to Krita: .. code:: python def exportDocument(self): # Get the document: doc = Krita.instance().activeDocument() # Saving a non-existent document causes crashes, so lets check for that first. if doc is not None: # This calls up the save dialog. The save dialog returns a tuple. fileName = QFileDialog.getSaveFileName()[0] # And export the document to the fileName location. # InfoObject is a dictionary with specific export options, but when we make an empty one Krita will use the export defaults. doc.exportImage(fileName, InfoObject()) And add the import for QFileDialog above with the imports: .. code:: python from krita import * from PyQt5.QtWidgets import QFileDialog Then, to connect the action to the new export document: .. code:: python def createActions(self, window): action = window.createAction("myAction", "My Script") action.triggered.connect(self.exportDocument) -This is an example of a `signal/slot connection `_, which QT applications like Krita use a lot. We'll go over how to make our own signals and slots a bit later. +This is an example of a `signal/slot connection `_, which Qt applications like Krita use a lot. We'll go over how to make our own signals and slots a bit later. Restart Krita and your new action ought to now export the document. Creating configurable keyboard shortcuts ---------------------------------------- -Now, your new action doesn't show up in :menuselection:`Settings --> configure Krita --> Keyboard Shortcuts`. +Now, your new action doesn't show up in :menuselection:`Settings --> Configure Krita --> Keyboard Shortcuts`. Krita, for various reasons, only adds actions to the shortcuts menu when they are present in an .action file. The action file to get our action to be added to shortcuts should look like this: .. code:: xml My Scripts My Script 10000 0 ctrl+alt+shift+p false My Scripts This will create a sub-category under scripts called "My Scripts" to add your shortcuts to. name This should be the unique id you made for your action when creating it in the setup of the extension. icon the name of a possible icon. These will only show up on KDE plasma, because Gnome and Windows users complained they look ugly. text The text that it will show in the shortcut editor. whatsThis - The text it will show when a QT application specifically calls for 'what is this', which is a help action. + The text it will show when a Qt application specifically calls for 'what is this', which is a help action. toolTip The tool tip, this will show up on hover-over. iconText The text it will show when displayed in a toolbar. So for example, "Resize Image to New Size" could be shortened to "Resize Image" to save space, so we'd put that in here. activationFlags This determines when an action is disabled or not. activationConditions - No clue + This determines activation conditions (e.g. activate only when selection is editable). See `the code `_ for examples. shortcut Default shortcut. isCheckable Whether it is a checkbox or not. statusTip - No Clue. + The status tip that is displayed on a status bar. Save this file as "myplugin.action" where myplugin is the name of your plugin. The action file should be saved, not in the pykrita resources folder, but rather in a resources folder named "actions". (So, share/pykrita is where the python plugins and desktop files go, and share/actions is where the action files go) Restart Krita. The shortcut should now show up in the shortcut action list. Creating a docker ----------------- Creating a custom `docker `_ is much like creating an extension. Dockers are in some ways a little easier, but they also require more use of widgets. This is the barebones docker code: .. code:: python from PyQt5.QtWidgets import * from krita import * class MyDocker(DockWidget): def __init__(self): super().__init__() self.setWindowTitle("My Docker") def canvasChanged(self, canvas): pass Krita.instance().addDockWidgetFactory(DockWidgetFactory("myDocker", DockWidgetFactoryBase.DockRight, MyDocker)) The window title is how it will appear in the docker list in Krita. canvasChanged always needs to be present, but you don't have to do anything with it, so hence just 'pass'. For the addDockWidgetFactory... "myDocker" Replace this with an unique ID for your docker that Krita uses to keep track of it. DockWidgetFactoryBase.DockRight The location. These can be DockTornOff, DockTop, DockBottom, DockRight, DockLeft, or DockMinimized MyDocker - Replace this with the class name of the docker your wanna add. + Replace this with the class name of the docker you want to add. -So, if we add our export document function we created in the extension section to this docker code, how do we allow the user to activate it? First, we'll need to do some QT GUI coding: Let's add a button! +So, if we add our export document function we created in the extension section to this docker code, how do we allow the user to activate it? First, we'll need to do some Qt GUI coding: Let's add a button! -Krita standardly uses pyQT, but their documentation is pretty bad, mostly because the regular QT documentation is really good, and you'll often find that the pyQT documentation of a class, say, `QWidget `_ is like a weird copy of the regular `QT documentation `_ for that class. +By default, Krita uses PyQt, but its documentation is pretty bad, mostly because the regular Qt documentation is really good, and you'll often find that the PyQT documentation of a class, say, `QWidget `_ is like a weird copy of the regular `Qt documentation `_ for that class. Anyway, what we need to do first is that we need to create a QWidget, it's not very complicated, under setWindowTitle, add: .. code:: python mainWidget = QWidget(self) self.setWidget(mainWidget) Then, we create a button: .. code:: python buttonExportDocument = QPushButton("Export Document", mainWidget) Now, to connect the button to our function, we'll need to look at the signals in the documentation. `QPushButton `_ has no unique signals of its own, but it does say it inherits 4 signals from `QAbstractButton `_, which means that we can use those too. In our case, we want clicked. .. code:: python buttonExportDocument.clicked.connect(self.exportDocument) If we now restart Krita, we'll have a new docker and in that docker there's a button. Clicking on the button will call up the export function. However, the button looks aligned a bit oddly. That's because our mainWidget has no layout. Let's quickly do that: .. code:: python mainWidget.setLayout(QVBoxLayout()) mainWidget.layout().addWidget(buttonExportDocument) Qt has several `layouts `_, but the `QHBoxLayout and the QVBoxLayout `_ are the easiest to use, they just arrange widgets horizontally or vertically. Restart Krita and the button should now be laid out nicely. -PyQT Signals and Slots +PyQt Signals and Slots ---------------------- -We've already been using pyqt signals and slots already, but there are times where you want to create your own signals and slots. -`As pyQt's documentation is pretty difficult to understand `_, and the way how signals and slots are created is very different from C++ qt, we're explaining it here: +We've already been using PyQt signals and slots already, but there are times where you want to create your own signals and slots. +`As pyQt's documentation is pretty difficult to understand `_, and the way how signals and slots are created is very different from C++ Qt, we're explaining it here: -All python functions you make in pyQt can be understood as slots, meaning that they can be connected to signals like Action.triggered or QPushButton.clicked. However, QCheckBox has a signal for toggled, which sends a boolean. How do we get our function to accept that boolean? +All python functions you make in PyQt can be understood as slots, meaning that they can be connected to signals like Action.triggered or QPushButton.clicked. However, QCheckBox has a signal for toggled, which sends a boolean. How do we get our function to accept that boolean? First, make sure you have the right import for making custom slots: ``from PyQt5.QtCore import pyqtSlot`` (If there's from ``PyQt5.QtCore import *`` already in the list of imports, then you won't have to do this, of course) -Then, you need to add a pyQt slot definition before your function: +Then, you need to add a PyQt slot definition before your function: .. code:: python @pyqtSlot(bool) def myFunction(self, enabled): enabledString = "disabled" if (enabled == True): enabledString = "enabled" print("The checkbox is"+enabledString) -Then, when you ave created your checkbox, you can do something like myCheckbox.toggled.connect(self.myFunction) +Then, when you have created your checkbox, you can do something like myCheckbox.toggled.connect(self.myFunction) Similarly, to make your own PyQt signals, you do the following: .. code:: python # signal name is added to the member variables of the class signal_name = pyqtSignal(bool, name='signalName') def emitMySignal(self): # And this is how you trigger the signal to be emitted. self.signal_name.emit(True) and use the right import: ``from PyQt5.QtCore import pyqtSignal`` To emit or create slots for objects that aren't standard python objects, you only have to put their names between quotation marks. Conclusion ---------- Okay, so that covers all the Krita specific details for creating python plugins. It doesn't handle how to parse the pixel data, or best practices with documents, but if you have a little bit of experience with python you should be able to start creating your own plugins. As always, read the code carefully and read the API docs for python, Krita and Qt carefully to see what is possible, and you'll get pretty far.