ofn-luminosity-masks

Purpose

This plug-in creates a selection mask based on the luminosity of pixels.

These selection masks are called "Luminosity masks" and are a very powerful technique to perform smooth and natural color changes in a picture. This technique is very well explained in PatDavid's canonical tutorial on the subject.

This plug-in creates the masks shown in the tutorial, among others

Unlike the tutorial, and unlike most Gimp scripts based on this tutorial,

• The script creates only one mask at a time.
• The mask is not created by addition/composition of other masks, but by applying directly the equivalent curve with the Curves tool.
• The script creates a mask using the current state of the layer. The tutorial and the scripts create all the masks once, usually on the initial state of the image, so when the masks are used successively, the pixels remain selected based on their initial luminosity and not on the luminosity they reached following the previous edits (unless you redo all the masks of course).

A side benefit of the single-mask approach is that the selection can be automatically set from the mask and this saves a few mouse clicks.

Operation

• The plug-in is called from the entries under Select>Luminosity in the image window. There is one menu entry per mask, and there are no parameters, so that you can assign your favorite masks to keystrokes (filter on ofn-luminosity to find them).
• The plug-in should be called on an active layer or active group. In the case of a group, the mask is based on the composition of the group. The plug-in will not work on a channel (it will complain with a message box or in the error console).
• The plug-in creates the selection directly, but the mask is also saved in a channel named #Luminosity:<name of mask>.
• To avoid an unnecessary accumulation of channels, this mask is deleted if you re-run the script.. In practice, the script deletes all the masks with a name that starts with #Luminosity:, so to keep a mask you just have to rename it.
• The "marching ants" selection indicator is of little use with a selections created from a luminosity mask. It is best turned of (View>Show selection or QCtrl-T)
• You can easily check the generated mask using Select>Selection Editor

Defining your own masks

Defining a luminosity mask is exactly equivalent to defining a "curve", the only difference being how the curve is interpreted.

• In a regular "Curves" usage, the input is the range of values of the channel, and the output is the corresponding new values for the same channel.
• For masks, the output is the amount of selection applied to pixels that have the input luminosity.

The usual masks correspond to simple curves:

But you can make arbitrary ones, for instance, if you want to deal with things that are light, but not very light (according to some authors, S-shaped sides make for smoother transitions):

For a one-shot usage, you would:

• Create a channel from a desaturated version of the image
• Create a selection from the channel (these first two steps are also conveniently what is done when asking for the Raw luminosity mask).
• Start the "quickmask"
• Apply the Curves tool on the "quickmask" (what is not selected turns red).

But if you often use the same mask this gets tedious. You can of course save the curve as a preset of the Curves tool, but this plug-in lets you define your own curves by putting them in a plug-in configuration file.

The file structure is simple. Lines are either

• Lines that start with a #; these are optional comments

• Lines that are made of three sections, separated by a ;:

  • The curve name (this is used to define the menu entry and the mask name)
  • The curve description (it appears in the "mouse-over" information)

  • The points that define the curves, as spaces-separated pairs of "X Y" coordinates

    Example/Middle-Light;Light mediums;0.00 0.00 0.75 1.00 1.00 0.00
    

It would be tedious to copy points coordinates between the Curves display and the configuration file, but there is an easy way: if you apply the curve once (for instance when using the "quickmask", as mentioned above), it is saved as a preset, and this preset is the first that appears in the Presets selector (you can also save it and give it a name by clicking the + icon).

The presets are saved in a text file: in 2.10 this is {your Gimp profile}/filters/GimpCurvesConfig.settings.

(GimpCurvesConfig "2019-11-16 00:11:19"
    (time 1573859479)
    (linear no)
    (channel value)
    (curve
        (curve-type smooth)
        (points 14 0 0 0.43941411451398138 0.2421875 0.5352862849533957 0.875 0.61651131824234351⏎
        0.98828125 0.69241011984021306 0.88671875 0.76964047936085211 0.30078125 1 0)
        (point-types 7 smooth smooth smooth smooth smooth smooth smooth)
        (n-samples 256)
[... snip ...]

The top item is the last saved preset. The line that starts with (points is the one of interest. Its contents (minus the opening (points, the first number (14), and the closing )) can be used directly in the plug-in configuration:

Example/Middle-Light;Light mediums;0 0 0.43941411451398138 0.2421875⏎ 
0.5352862849533957 0.875 0.61651131824234351 0.98828125 0.69241011984021306⏎
0.88671875 0.76964047936085211 0.30078125 1 0

(the line above is folded for readability, this should be one single line). There is no need to be this accurate in practice, the values can be rounded to a couple of decimals to make the line an easier read:

Example/Middle-Light;Light mediums;0 0 0.44 0.24 0.54 0.86 0.62 0.99 0.69 0.89 0.77 0.30 1 0

In practice

• An example configuration file is provided in the Doc directory.
• The configuration file should have the same name as the plug-in with extension .ini instead of .py.
• The configuration file is searched, in that order (only the first one found counts):
  • in the tool-presets subdirectory of the Gimp profile
  • in the Gimp profile itself
  • in the directory where the plug-in Python file is kept
• To create menu entries the plug-in registration should be executed, but Gimp will not re-execute it if the plug-in executable is not changed (only the configuration file changes here). To make Gimp consider that the plug-in changed, you can remove/rename it, restart Gimp, and put it back and restart Gimp again.
• Once the menu entries are created, you can change the curves values without needing to re-register or even to restart Gimp.
• Your additional masks can also be assigned to keyboard shortcuts.
• You can create sub-menus by using '/' in the mask name.