View source for Calligra/Paintops/Spray brush

=== Spray brush ===

This is WIP documentation!
I started Spray brush as paintop, brush engine which should be better airbrush in Krita. You can name it splatter too. It sprays particles and these particles can be various shapes.

== Settings ==

= Brush size =

Here you can setup diameter of the brush and amount of particles per one dab. By default you enter amount of particles in particles box. If you check use density, density option will be used.
You setup density in percents from 0% to 100%.

The amount of particles will be set like this: let's have diameter of 100, so the radius is 100/2, density 0.1,. The amount of particles will me PI * 50 * 50 * density ~ 785;

Jitter movement randomly shift the whole dab according the radius of the brush and amount of the shift you specify.
Jitter size gives diameter of the brush by random.

Spacing is known also in other brushes, it sets the distance between two dabs in a stroke.

Scale scales the generated distance of the generated particle. You can have different effects when using scale + diameter, then using just bigger diameter.

= Particle type =

Spray can splatter various shapes. Spray object can be a pixel, just like when you spray in KolourPaint. Or it can be anti-aliased pixel. If you select Shape object, which is selected by default, you can splatter ellipse, rectangle or meta-balls. Meta-balls will be probably moved to custom paintop in the future. 

You can specify size of the ellipse and rectangle. You can use exact pixel values for both width and height.
You can also use proportional size which is in percents. It is proportion to the diameter. If you change the brush diameter, the particles will be also bigger.

If you check random size, particles will have size from 0 to size you specified by proportional or exact value.

Meta-balls take just width in the account. Thresholds are used for meta-balls but will be probably removed. High-quality rendering is just for meta-balls too.

Gauss distribution will be probably part of the Brush size setting as proposed by maninalift [1]. If checked, gauss distribution is used for distributing particles.

= Color options =
HSV and opacity can be changed through stroke. 
If you check Random HSV, you have to speficy interval. E.g. if you set the Hue to 100, then the color of the particle will have colors of the selected color with transformed hue in range 0 to 100.
Same is true for saturation and value.

Random opacity set the opacity from 0 to 100% randomly.

= Painting mode = 
Same for every brush in Krita. "Build up" gives nice results.

 

=== Developer notes === 

Warning: You have to be at least tester if you want to spend time reading this

= TODO: =
* <strike>add a button to synchronize the aspect ratio (width/height)</strike>
* add distributions to the brush size dialog(gauss, other), see [1]

= enki e-mail = 
I tried to find the "variables" from real airbrushes and their equivalent in the spray PaintOp:

'''Rate''' : how much [paint+air] per time unit. If I understand correctly, it can't be done well in Krita currently. It is split between spacing (when the brush moves), and rate (when the brush doesn't move). If we move the cursor slowly, there is the same amount of particles than when moving fast.(probably one of the problems we have with proportional scaling?)
 
'''Distance to canvas''' : (= scaling setting): Area covered by the spray on the canvas (= brush size). Would be affected by stylus pressure by default ?
 
'''Coverage''' : % of the brush that is really painted.
 
'''Paint/air ratio %''': Ratio of paint and air at the output of the airbrush. For some airbrush, paint & air are two separated trigger (I wonder if it affect the rate then). In a perfect world, paint/air ratio would be equal to coverage. ^^
 
'''Angle of coverage''' : (= scale + fading ?). When the angle is small, borders are sharp; when angle is wide, it's blurry.
I don't think it should works like a real airbrush, because it would change the size of the brush. Instead, it'd work like Autobrush's fading, or even better, with a curve widget.
 
'''Paint fluidity-liquidity''' : (= particle size + opacity ?) If the paint is thick it would make more opaques, bigger drops. If it is thin, it would scatter a lot in small transparent drops.
 
In the future, we could imagine that if two drops overlap on the canvas, they would "merge" somehow, depending on the thickness, like watercolors or ink.
It would also depend on what paper we would paint on. Then there would be a per-particle fading too.
 
'''Angle to canvas''' : (stylus angle) Paint is projected depending of direction & angle of the stylus. It seems hard to do.

== References ==
[1][http://lukast.mediablog.sk/log/?p=66#comment-387 user requests by maninalift]

[2][http://lukast.mediablog.sk/log/?p=66 blog-post about spray]

[3][http://www.sysf.physto.se/~klere/airbrush/ information about _real_ airbrushes]