You should try my 'Local Similarity Mask' which is in the Repair folder.

wow, fantastic! I know you are the best GMIC coder for portrait enhancements!
so, would it be possible to build on it to perform what I had in mind?
1-create as output an image with two channels, or maybe three: matching [white], partially matching[grey], excluded[black], so to apply afterwards:
2-split c
3-do whatever on each channel
4-append c

I would probably do it like this:

Create mask
Apply effect 'A' to duplicate image

-append c # to add mask to duplicate image as alpha

Apply effect 'B' to original image

-blend alpha,1,0


I'll have a think about it, but it won't be a priority. If I have a revelation about a good solution I might get a burst of enthusiasm and get something done, but we'll see.

I have tried skin masks before, and never quite got a decent solution. It's easy to get something to work on one or two images but when you start adding variables like different ethnicities, different lighting etc, things start to fall apart.

many thanks, Iain

tip #14

because in the last period I started to look at command for de-noising images, today I wanted to create artificial images and test all the various methodologies under
GMIC > repair > smooth
I created two different images:
1-a gradient (to check the ability to de-noise in smooth areas)
2-a grid filled with many different colours (to check the ability to de-noise in areas having borders well defined)
To both base images I added RGB noise.
Well, results were a surprise for me: only ONE methodology was able to produce acceptable results, the one based on wavelets de-noising.
A foreward is absolutely necessary: I did play using ONLY the default parameters, in the assumption that those are in general good, for the author.
I attach here two folders, one for each image. Have a look yourself!

as you point out you take default values - your results show very different degrees of noise suppression applied but this is adjustable
without adjusting then it is hard to judge consequent side-effects .. each method has its own drawbacks and can perform differently on types of noise

most complex filters were developed for specific purposes so you're unlikely to see the benefit in other situations, the generic blocks and gradients base images are not typical of most photos

if someone has a real-world case photo, I recommend Iain's denoise algorithms which add complex post-processing options tuned to suppress colour-noise and recover edge details
for example : Testing / Iain Fergusson / Noise Reduction 5
which does use the wavelet as a base method

Yes, Jayprich!
I underlined the strong limitation of these tests, I put them here because I was very much surprised.
Also, I will continue with methodologies not in the list I mentioned (..repair->smooth).
I have a lot of confidence (trust) in Iain, I think he's the best GMIC coder in de-noising, especially portraits.

tip #15

because during the last days I played with Iain's filter "local similarity", I'd like to point out here about my (even if limited) experience.
1-it's an excellent filter to identify the skin area in a portrait
2-I recommend (if you want to use it inside a own filter) to include the preview in order to detect the "origin" point
3-it's important to point to a pixel on the face which is representative of the "average" skin tone, not too light, not too dark
4-it's preferable to select channel "red" to get a better defined mask (when skin is concerned, this is what I found out)
5-maybe the mask is better defined by reducing the "keep" and "reject" values, I found good values around 30 and 100
6-before calling your own filter based on Iain's command, I suggest to refine the input x,y of the "origin" point (which becomes input to your own filter) by experimenting on Iain's command using the same image on which you like to apply your filter, to "preview" the expected mask.
Have a nice trial you too!

this can be replaced by the -channels command

-channels[mask] 0 # keep the first channel (0) of image [mask] and remove the others

thanks Iain!
I didn't know that command (always to learn a lot from you!)

Tip #16

Recently I bumped into the (native) command
-normalize_local
So I'd like to report here my personal ideas on that one.
Just a little foreword: I looked at it ONLY for image enhancement, not for image transformation.
I say that because - going through the available filters in G'MIC - I found some uses of this command primarily in image transformation filters, like:
- sketching, painting, rodilius, etc.
all excellent creative filters which btw do not keep the "feeling" of the original image.
But playing with the command -normalize_local I saw it can be used to get more colour, more clarity.
If you have dull images, you can improve them by using that command.
Practically, it performs a stretching of the contrast, both in colours and in luminosity.
The main parameters to play with are:
1-amplitude
2-radius
3-neighbourhood smoothness
4-average smoothness
the other 3 parameters I left as defaulted (is-cut=1, min=0, max=255) during my tests
The first parameter seems to act as the strength of the command, the value is without limit but practically values over 6 have no effect, maybe because resulting high values are afterwards "cut".
So, the range I suggest is 1 to 6; default is 3.
The second parameter defines the area used as base for stretching the values of colour and luminosity.
Default is 16, to obtain still good but smoother stretching you can play up to 80;
values lower than 16 imo are good for artistic transformation, but not for simple photo enhancement (btw, in the various artistic filters which use -normalize_local, the second value is often 5 or 6).
The third and fourth parameters have as defaults: 4% and 2%.
Having to do with smoothness, I suggest to use the defaults or even to reduce them when dealing with landscapes, but increasing the values when dealing with figures, faces (to get a better skin); you can go up to 16% and 8%, respectively.
I attach here a folder with tests made on a landscape and on a figure.
The names specify the values used, for instance:
- figure_3-16-8-4 means that the 4 parameters used were: 3,16,8%,4%
- landscape_2-32 means that the first 2 parameters used were: 2,32
if you find orig means original image, dft means filter used with defaults

Tip #17

(after a while...)

Recently I did some experiments with the native command
-orientation
and I put here some comments for those who did not play with it already (or for G'MIC novices).
What does -orientation command perform?
I can only report the description from the manual:
"Compute the pointwise orientation of vector-valued pixels in selected images".
For me, -not mathematician nor graphic scientist- it's like chinese, but in any case I'm only interested in the results, quite interesting.

As usual, my experiments are related to photo enhancements.
I found that command useful to improve colours, in any kind of images.

For novices only, I recap here how you can experiment commands; follow these steps:
-open gimp
-open an image (necessary to have G'MIC not greyed out)
-go to filters or whichever menu entry you used for G'MIC (I have G'MIC under G'MIC menu entry)
-select gmic
-when gmic opens:
-select "various"
-then select "custom code (local)"
-remove whatever you find in there
-then put your command(s)
-select "update" to see result in preview window
-select "apply" / "OK" to have it executed

Now, to test -orientation you may enter:
--orientation #no parameters, double hyphen is for having the result in a new layer
-normalize 0,255 #otherwise you do not see the result
-blend overlay,0.7 #try any other value, according to your taste and the original image

that's it, very simple.

I attach here results of experiments made on: landscape, portrait, seascape; in all cases I see a better colours look.

If you like the effect, you can put permanently this small sequence in your "gmic" file.
Again, for novices:
G'MIC when Gimp starts opens not only the official filters of the many contributors, but also your personal filters.
It performs that by reading the file "gmic" (without any extension) you may put under:
-Users/your-user-name/AppData/Roaming
If this is your first attempt, you may put in that file the following lines, using a text editor like notepad++:
------------------------------------------------------------
#@gimp My Directory

############################################################

#@gimp test orientation : test_orientation, test_orientation
test_orientation :
--orientation
-normalize 0,255
-blend overlay,0.7

############################################################

#@gimp _
------------------------------------------------------------
A last note:
the command -orientation is good also to improve photos taken
against the light, but better to play with other blending params.

Tip #17

(a small step forward ...)

Maybe -if you did some experiments- you noticed that, while the use of the interactive command code allows a couple of choices (value range and channels) for the execution of the native command -orientation, when a small filter is created the command itself has to be entered without parameters.
So, how can we exploit theses capabilities?
Two are the choices you can make when using the interactive [b]command code:
1- value range = cut or normalize
we have already exploited this option by entering (after -orientation)
the command -normalize 0,255
2- channels = a lot of choices
to have the same capability in a written down filter we have to encapsulate the -orientation command
in another command: -apply_channels
This command allows to specify exactly the two options available interactively (practically, the command code works that way): so, we can replace the line entered in the small filter created in the previous post, with the following:
-apply_channels "-orientation",0,1 #the command to be executed has to be entered as a text, the other two values mean: all channels(0) and normalize values(1)
By this way we can:
- omit the subsequent -normalize command, which is now included as an option of -apply_channels
- exploit all the possibilities of channels selection (more than 20), for example, instead of 0, we may use:
2(RGB), 3(Luminance), 12(saturation) ....
First, play online, then modify the small filter according to your taste.

Hi dinasset,

I enjoy these tips you've been writing. Hope you keep it up; They help
me keep the discussion somewhat down-to-earth in the documentation
project I'm working on.

As a way of expressing my appreciation, I'd like to clear up some of
the mystery surrounding the -orientation command -- the "pointwise
orientation of vector-valued pixels" business. Hopefully, I won't make
the concept even more mysterious.

Color **does** have orientation. To give this idea some heft, we need
a point to orient with. To that end, let us declare black as the point
at the center of a red-green-blue color space. Black is unique in that
it has no red, no green, no blue component. In the space of color, it
sits at the origin.

I can orient ('position') every other color I can imagine with respect
to black by way of their red, green and blue components or - to
stretch a term, perhaps, their 'color coordinates.'

Here's one color with which we can experiment: Alice Blue, which
Wikipedia asserts was a particular favorite of Alice Roosevelt, eldest
daughter of Theodore Roosevelt, America's 26th President. ("I can
either run the country or I can attend to Alice, but I cannot possibly
do both." -- TR) Alice Blue is one of the formally defined 1987 X11
Color Names, so it has a widely recognized composition: Red: 240 (0xf0,
base 16) Green 248 (0xf8, base 16) and Blue: 255 (0xff, base 16) - a
pale azure, almost white. Plug it into Gimp and see what it looks like.

We may think of these red, green and blue parts as coordinates that
plots a point in a volume. Starting from black (Red = Green = Blue =
0) we can walk 240 pixels in the Red direction, turn 90 degrees to our
left and walk 248 pixels in the Green direction, then climb a vertical
ladder for 255 pixels in the Blue direction. That's an orientation, or
direction, expressed in terms of three reference directions. I can also
express this orientation in a way to please astronomers: a declination
and hour angle, but I can't be arsed.

How far are we from black? Easy. Pythagorean Theorem to the rescue.
`Tis the sum of the squares of Red (240*240 = 57,600) plus the square
of Green (248*248 = 61,504) plus the square of Blue (255*255 = 65,025)
taken as a square root: sqrt( 57,600 + 61,504 + 65,025) = 429.1026
pixels. At point Alice Blue, we are nearly 430 pixels from black.

Take another X11 color, a dark one. Slate Gray at rgb(112, 128, 144),
a kind of dull turquoise (in hex: #708090). By the same method, it's
distance from black is sqrt(112*112 + 128*128 + 144*144) = 222.8542
pixels, just about 206 and a quarter pixels closer to black than Alice
Blue.

Here's a third X11 color - Papaya Whip (my favorite!): rgb(255, 239, 213)
(hex: #ffefd5), 409.2860 pixels from black - almost, but not
quite, as far away from black as Alice Blue, but in a different
direction: Papaya Whip is off in a orange-red direction, Alice Blue is
in a blue-green direction, mainly. Plug Papaya Whip into Gimp and see
what it looks like.

I can go on and on in this vein, but you probably hope I won't. The
key idea is that Alice Blue, Slate Gray, and Papaya Whip -- every
single one of them -- are vectors. Any RGB color you care to name is a
certain distance from black and a particular direction from
black. Direction and distance. The combination of the two concepts
makes a vector.

Now 'Vector' is one of those words that makes eyes glaze, and that is
a pity. It is not a complicated word and we use the concept all the
time in our day-to-day life. 'Go North 500 meters.' A vector is just a
two-part number with a direction piece and a distance piece. How tough
is that?
(Continued next post...)

(-orientation - what is it? continued...)

Now there are two G'MIC commands that break these pieces out: one is
-norm -- it breaks out the distance piece. The other is our friend
-orientation. It breaks out the direction piece.

Most folk playing around with G'MIC think -norm is a funny kind of
-luminance command; superficially, the behavior of the commands are
alike in that they turn color images into shades of gray, but not
the same grays. An image with Alice Blue, Slate Gray, and Papaya
Whip colored pixels will have, under the -norm command output pixels of
429.1026 (Alice Blue), 222.8542 (Slate Gray) and 409.2860 (Papaya Whip)
-- precisely, exactly, the distances these colors are from black.

What -norm does is that it throws out the direction piece of information.
If all we knew about these colors was what -norm told us, it would be
that Alice Blue is the furthest from black, and that Papaya Whip is nearly
as far, and that Slate Gray is only about as half as far from black as the
other two, but we'd have no hint from just these distances alone that Alice
Blue is a pale, pale azure, and that Slate Gray is a dull turquoise, that
Papaya Whip is orange-like. Sometimes, though, distances are all we care
about and when we want to focus on distance and ignore direction, -norm
is the command for us.

Now, -orientation is the flip-side of -norm: it throws away distances
and saves the direction bit. In particular, it takes a color like
Alice Blue, with coordinates rgb(240, 248, 255) and divides these
through with its distance from black -- 429.1026 pixels, remember? --
to get a triplet of numbers like (0.5593, 0.5780, 0.5943) -- the
relative color intensities of Alice Blue. Run those numbers through Pythagorean's
Theorem and you'll get a number very nearly equal to one: plus or
minus a smidgen for rounding error. Now we can eyeball this triplet
and get the sense that Alice Blue is mainly off in the blue-green
direction, and that Papaya Whip, at (0.6230, 0.5839, 0.5204) points in
an orange direction and that Slate Gray is, like Alice Blue, another
kind of blue-green, with (0.5026, 0.5744, 0.6462). In fact, distances
aside, Slate Gray is more blue-like than Alice Blue. So, what's in a name?

In fact, distances aside, we have no idea, from what -orientation
tells us, that Alice Blue and Papaya Whip are light colors and that
Slate Gray is a dull turquoise. -orientation has made all of their
distances from black equal to one, points on a sphere with a one-pixel
radius, but has preserved color orientation.

Sometimes, Gimp can be a pain when trying to grok G'MIC commands.
-orientation by its lonesome makes everything black and -norm by
its lonesome is a crazy kind of luminance command that burns out
highlights and midtones. As you have observed, these commands need
to be -normalize'd before they work in a Gimp Layer, which somewhat
obscures their purpose.

Artistic purposes, however, need not parallel the technical purposes,
which is what I have been rattling on about so far. Indeed,
-orientation **is** a kind of "color extraction" command, as distance
from black (the idea behind luminance) has been thrown out, leaving
only normalized color intensities. Once extracted, the color-only data
can be selectively reapplied to a source image as a kind of color
enhancing tool, which is what you have been doing with the command.

Hope some of this helps, or, at least, has been entertaining.

Thank you for your post Garry (grosood), I've been enjoying your G'MIC tutorials.

Thanks a lot, Garry!
I did understand -orientation as explained so clearly by you.
The problem for me of continuing on this subject is that whenever I try to experiment some new effect using G'MIC-Gimp I spend a lot of hours without getting what I hope to get...really frustrating !
I wait upon your next steps in the tutorial to find out some good stimulus.
Thanks again

Yep. Lot of time can go into debugging.

Over in G'MIC Tutorial Land, the concentration is entirely
on the interpreter. Gimp isn't even running. Some
ways that actually simplifies matters; -display works
and that furnishes metrics and diagnostics on images as they are
on the G'MIC image stack, and that explains/catches
a good many image oddities.

Over here in Gimp Chat Land, most access the G'MIC
interpreter through Gimp ('Various'->'Global' or 'Local') and
I'm going to have to spend some time on that particular
venue. For example, last night I wrote that -norm replaces
all pixels in an RGB input image (say one pixel in such is powder blue:
#B0E0E6 or rgb(176, 224, 230)) with their exact, precise
distance from black. (366.1311 pixels in powder blue's case).

Well, golly gee, that's easy to figure out with the standalone
interpreter; the -display command has a pixel-picker and you
can pick a pixel and read out what the pixel is, even when
-display normalizes the image. Hover the pixel picker over the
now-gray version of powder blue and discover that it has a value
of 366.1311, and you know you're going to have to do output normalization
or cutting of some sort because that is a 'gray' that is whiter-than-white in
the world of eight bit, 0-to-255, channels. More to the point, you
garner some insight into what -norm is doing. 'Ah hah! -norm makes an
image of gray pixels that report the distance from black of the original
color pixels.' That insight is harder to come by in the Gimp interface.

One can put the command interpreter filter into very verbose (console)
mode and then insert -display commands in one's test script. Doesn't
bring up G'MIC's native display window (console output only, no display support)
but -display metrics still print on the console. That set of metrics prints the
first half dozen pixels in an image and overall image statistics, a help.

I think you threw that bit of snoopery into a tip awhile back.

Take care - Garry

Tip #18

This time I want to go through the details of a very nice artistic effect:
-Stained glass (in '/Patterns/')
which tries to emulate the appearance of an artistic stained glass window starting from a normal photo.
First thing to do is certainly playing with the parameters of the filter, which I did recently (previously I did use only the defaults).
As a base image I take one which I frequently use: Angel III (from Deviant Art).
First image shown here is obtained with default parameters.
Not bad but let's play a bit.
Second image is obtained by setting the parameter Colors to 3.
Better result (if you like colours, obviously).
Third image is obtained by setting also the parameter Gamma to -0.50.
More colourful.
Forth image is obtained by setting also the parameter Contrast to 1.24.
Again more colourful, maybe too much.
Fifth image is obtained by setting also the parameter Brightness to -33.
Now more thank an angel it looks like a ...demon!
Really we can get a lot of variations on colours.
Now I will play with a different aspect: let me call it the structure.
I start as a base with the third image (medium colours), then I change the Edges parameter.
Sixth image is obtained changing Edges from 20 to 25, and shading to 0.25.
New glass structure.
Increasing again the value does not lead to nice results, for me.
So, seventh image is obtained by reducing Edges from 20 to 15, and shading to 0.15.
Again a different structure.
If the values are too reduced, it does no more look as a stained glass, really.
That's to say: keep value of Edges between 15 and 25.
Another parameter that can be played with is Equalize: removing this option let the results
adhere better to the general look of the original image; only an example:
eight image, with all default values except Equalize.
So, this concludes the first part of this post, totally from a filter user viewpoint , the follow-on on this topic will be entering in the details of the filter code to analyse them.
Because our goal is to understand the G'MIC commands (as fas as possible for me).
note: all images are zipped in the attached file