RBA Tools: DynamicPaintbrush
A dynamic paintbrush for PixInsight

Ever wanted to use a paintbrush in PixInsight to help you adjust your masks? If yes, you're in the right place!


Screenshot of some random DynamicPaintbrush application

RBA-Tools's DynamicPaintbrush is a dynamic (doh!) process that allows us to define a custom brush and use it to paint over any view (opened image) in PixInsight.

Since directly painting over an astroimage is not typically needed, the DynamicPaintbrush tool was designed to paint on images that we'd be using as masks. For that reason, this implementation only paints in black, white and any level of opacity. We can also define the brush size and softness - from 100% hard edges to nicely smoothed, blurry brushes.

The full documentation for DynamicPaintbrush is included a few paragraphs below.

TRY IT!

The processes in the RBA-Tools collection are not free, but you can try a 100% functional copy for 30 days.

Since at the moment DynamicPaintbrush is the only process in RBA-Tools, it is being released and priced as an individual module, at just 4.99 US$. However, should you decide to register your copy now, and later acquire the entire RBA-Tools set (after more tools are added to it), what you pay today will go towards the price of the set. Your purchase also gives you a lifetime of free upgrades.

DynamicPaintbrush is a PixInsight module (or process), not just a script. Although modules offer several solid advantages compared to scripts, they need to be compiled for each operating system. Therefore, when you download your fully-functional copy, please make sure you download the right version for your OS:

Please, don't contact us asking when we'll be releasing the version for <name your OS>. When we know the answer to that question, we'll be adding a note right next to the links above.

REGISTER YOUR COPY!

When you register your copy of DynamicPaintbrush, you can install and use it on any machine you have also installed PixInsight, regardless of operating system (your registration is valid for any and all platforms) or number of installations. Please, select your payment method below:

  Pay with  (Click/tap here to use PayPal to make your purchase)

  Pay with (Click/tap here to use Zelle (USA only!), and pay only 4.50 US$)




DYNAMICPAINTBRUSH - DOCUMENTATION


Requirements
DynamicPaintbrush is currently available only for Windows. Linux and macOS versions should be available sometime mid-late April 2021.

Other than that, DynamicPaintbrush simply needs a working copy of PixInsight that supports the API version 0x170. At the time of this writing (April 1, 2021), this is only true for PixInsight version 1.8.8-7. Using the latest PixInsight version available is always recommended.

Installation

The DynamicPaintbrush dialog box

Installing the DynamicPaintbrush module follows the same procedure as installing any other PixInsight module.

If you have my book Mastering PixInsight, the section "Modules and Scripts" in Chapter III gives you all the details. In a nutshell, once we have downloaded the .zip file with the right module, this is what we need to do:

  1. We extract the module from the .zip file to a permanent location. Whether we extract it to a protected folder (like the "bin" folder in the PixInsight installation) or somewhere else is up to us, but that's the location where the module file will stay permanently, so don't extract it to a random or temporary location.

  2. We open PixInsigh and do PROCESS > Modules > Install Modules

  3. We set the Search Directory to the directory/folder where we saved the module file.

  4. We click Search and we should get a small window letting us know PixInsight has found one (1) additional module. We click OK.

  5. The module should now be listed in the list box, and it should be selected by default, with a green check-mark visible to the left of the module's filename. If we see a red X instead, we double-click on it to select it.

  6. We click the Install button.


If we get an error about the wrong API being used, please read the "Requirements" section above.

Otherwise, the DynamicPaintbrush module is now ready to use!


Launching DynamicPaintbrush

Launching DynamicPaintbrush via the PROCESS menu

DynamicPaintbrush is under the Painting category, so we can navigate to that category using PixInsight's PROCESS menu or the Process Explorer.

Paintbrush is a dynamic process, much like DynamicCrop or DBE.

Dynamic here means that the process needs to interact with an image as we use the process. For a painting tool, this makes a lot of sense. Clearly, we can't define where we want to paint without an image! (okay, we could, but let's not go there!)

Therefore, the first thing we do after launching the DynamicPaintbrush tool is to click anywhere on the view we want to paint. Until then, all controls in the DynamicPaintbrush window will be disabled, with the message "No view selected" being displayed.


A circled cursor means we're ready to paint

The moment we click on a view, such view is locked with the DynamicPaintbrush tool (the "dynamic" interface between the tool and the view), the controls in the DynamicPaintbrush window become enabled, and our mouse cursor becomes a small circle around the cross-hair when we hover over our selected view. That circle, by the way, shows us the current brush size.

We're ready to paint.


Painting with DynamicPaintbrush
Painting is as easy as clicking on our selected view and dragging the mouse around as we please. We can click and drag (or just click if we want to draw a dot/circle) as many times as we need.

DynamicPaintbrush was designed to work on non-linear images. Using it on linear images may not produce good results, unless we use very low opacity values (See the "Usage Hints" section below for more details on this).


We can use DynamicPaintbrush for more than just masks :-)

If you've used the CloneStamp tool, the interface probably looks very familiar. Indeed, the DynamicPaintbrush tool works exactly the same as the CloneStamp tool (without the cloning, of course), offering similar brush property parameters and a history of "strokes" that we can navigate back and forth (undo/redo/etc).

Indeed, as we do new strokes, we'll notice that we start to build a "history" or sequence of this painting session, one stroke at a time.


We can undo/redo our strokes with the navigation toolbar

Now, remember that DynamicPaintbrush is a dynamic process. This is not GIMP or Photoshop. Therefore, it's very important that we remember the following:

Although we can see the results of our painting in real time, nothing is actually applied to our image until we execute the process, by clicking on the green check-mark.

If, instead of executing our painting session, we decide to cancel the whole thing, we would instead click on the red (the one next to the green check-mark!) and our entire painting sequence would be dismissed.


Brush Parameters
We can adjust the brush size, softness and opacity, as well as whether we want to paint in black or white color.


Paintbrus parameters

Size: This is the brush radius size in pixels. The current version allows values from 1 to 255 pixels.

For those needing precise measurements, the actual values may sometimes be rounded up/down by a pixel or so.


Softness: This parameter defines how "soft" the edges of the brush would be.

A value of 0.00 means the edges won't be soft at all, literally only painting on the image values of 1 (brightest possible pixel value) or 0 (unless we also adjust the opacity, defined next). This behavior is actually forced in the tool, as a softness value of 0.01 already defines a noticeably softer brush.

A value of 1.00 on the contrary defines very soft, Gaussian brush edges. Values between 0.00 and 1.00 control the amount of "blur" we're adding to the brush.


Opacity: We adjust this parameter to increase or decrease the transparency or opacity of the brush. Technically, the brush values are multiplied by this parameter prior to being applied.

A value of 1.00 means we're applying full force on the brush - this is how DynamicPaintbrush is typically used. A value of 0.01 (the minimum allowed value) results in almost imperceptible strokes.


Brush Color: On the right area of the dialog box we can see a small brush image that changes as we adjust the previous three parameters. We can click on the image to change the color of the brush, from white to black, or from black to white.


Navigation bar: The navigation bar under the brush icon should be self-explanatory.

When we click on the red x button, the current stroke in our paintbrush history is deleted, while all other strokes are preserved.

The other four buttons are to Undo all, Undo, Redo and Redo All our position in the DynamicPaintbrush history.


Info/Help icon:  Under the navigation bar we can see a small "info" icon. We can click on it to obtain information about the module's version, registration, help links and copyright information.


Usage Hints/Known Issues
Painting on linear images
As mentioned earlier, DynamicPaintbrush was designed to work on non-linear images.

This is because when we paint, the tool typically uses a brush that utilizes the entire [0,1] range of pixel values, so it's way too bright for astronomical linear images. We can try to make it work on linear images by reducing considerably the brush's opacity. However, since DynamicPaintbrush is mostly useful for working on masks, we rarely need to worry about using the tool directly on linear images.

Just to be clear, using DynamicPaintbrush to paint on an image that is being applied as a mask to a linear image is perfectly fine (see the next two paragraphs). The "final" image may be linear but the mask -which is where we're painting- is not, and that's probably how we want it.

Painting on a mask
If we're painting on a view that has been set as a mask for another view, every stroke we make is reflected on the masked image immediately after finishing the stroke - no need to wait until we execute the process to preview how our painting would affect the masking. This can be very useful.

Painting on a masked image
When we paint on a view that has a mask applied to it, our strokes will respect the mask, as long as the mask is enabled. If we disable the mask before executing our painting sequence, DynamicPaintbrush will respect that and display any painted areas that were previously hidden by the mask.

The important thing to remember is that our results when we execute the DynamicPaintbrush process will depend on whether we have a mask applied or not at the time we execute the process, regardless of whether the mask was applied when we painted the strokes.

Known issue using the history toolbar
If we don't use the Undo/Redo buttons in the navigation toolbar often, we can disregard this suggestion.

Otherwise, when painting with very large brushes or doing very large strokes in a single sequence, using Undo and Redo in the sequence history can sometimes be rather slow, with a noticeable pause between the moment we click the undo/redo history button and the moment the image gets updated.

For that reason, although we can do as many strokes as we want during a DynamicPaintbrush sequence, if we're going to be doing many strokes or very long ones, it's probably a good idea to do a few strokes and execute (click on the green check-mark), then continue doing more strokes in a new sequence, and execute again, repeating as needed.

Known issue using the opacity
The current implementation of DynamicPaintbrush uses a different painting method depending on whether we're painting at full opacity or not.

When we're at full opacity (opacity value of 1.00), DynamicPaintbrush uses a method that should feel familiar to paintbrush tools in other applications.

When not painting at full opacity (opacity value of 0.99 or less), in addition to adjusting for the opacity level, the brush works and feels slightly differently. It would take a while to explain the how and why, but in short, the brush handles self-overlapping differently as we drag it.

This behavior should change to the more familiar approach in a future version.


Future versions, updates and technical notes
The current implementation of DynamicPaintbrush is more a proof of concept than everything I would like this tool to be, both programmatically and from a feature/interface perspective. So you should expect updates and improvements over time.

Currently, any updates will be notified by email to registered users, and announced on the PixInsight forum and a few other PixInsight related groups in social media, requiring you to download the updated module and replace it in your PixInsight installation.

In the near future, we will offer an update repository that you can add to your PixInsight installation, making future updates fully automatic.

Ultimately, DynamicPaintbrush should end up also being integrated in the RBA-Tools interface, as more tools are added to the set. It will take a few months but I think it's going to be nice, and not only with more features but also much easier to work with than what it is today!


Credits
DynamicPaintbrush was developed using the PixInsight Class Library version 2.4.7 (API version 0x170). Any product derived from the PCL, including DynamicPaintbrush, must reproduce the following acknowledgment:

This product is based on software from the PixInsight project, developed by Pleiades Astrophoto and its contributors (http://pixinsight.com/).

The above statement refers to our use of the PCL to develop DynamicPaintbrush only. DynamicPaintbrush is developed independently, without any relation to or specific contributions from Pleiades Astrophoto.