-name

-name labels selections for reference during execution of gmic scripts and for managing layer properties of host applications like Gimp or Krita. Naming conventions differ between these two contexts. See The Host Application Use Case for how -name interacts with host applications which support image layers.

Since this command is frequently used to label selections containing one image, it is easy to misconstrue its purpose to just one of labeling images. As misconstructions go, this is mostly harmless; its malfeasance lies mainly with the mental blocks erected in the minds of gmic script writers who forget the benefits of classifying related images under one meaningful name.

The format of the command is:

-name[<selection>] “<name>”

The command associates the collection of images referenced by <selection> with the label <name>. The images become members of a named selection that <name> identifies. Its shortcut is -nm,

Formally, the label <name> may be written with any characters supported by the host computer, but if the intent is to use labels as named selections in command decorators or image parameters, contexts where [ and ] selection operators apply, then gmic further restricts character usage to the class [a-zA-Z0-9_] and such names cannot begin with a numeric.

gmic scripts operating within the context of the host application plug-in may use -name to communicate with the host for setting layer properties, including setting the layer's name in the host application. This host layer name is not the same as the label that -name sets; In fact, the gmic script writer uses -name to label the image with a string composed according to a simple syntax that resembles calling functions. The host application retrieves this gmic-produced label and executes internal functions to set position, layer modes, opacity and the host application layer name, which can be, and usually are, quite different than the gmic label. See The Host Application Use Case for details.

Usage of -name with selection operators [ and ]

In gmic scripts operating within a host plug-in or in a command shell, -name associates a collection of images selected by the command's right hand decorator with a named selection, identified by the string argument given to name.

gmic \ -sample rose \ -name[0] BlurMe \ -blur[BlurMe] 4 \ -output[BlurMe] rose.png

The sample image, rose, becomes an image in the named selection BlurMe. At some subsequent point in the pipeline, all members of the BlurMe named selection are selected for blurring. It so happens that there is only one member of the named selection which is affected by this operation.

Position Tracking

Once an image is a member of a named selection it retains its association even though it changes its position on the image list.

gmic \ -input 300,250,1,3 \ -name[0] AmpersandMe \ -input[0] ampersand.cimg \ -name[0] TheAmpStamp \ -local[AmpersandMe,TheAmpStamp] \ -noise[AmpersandMe] 0.03,2 \ -display \ -shift[AmpersandMe] 0,0,0,1.375,2,1 \ -convolve[AmpersandMe] [TheAmpStamp],1,1 \ -endlocal \ -normalize 0,{2^8-1} \ -output[AmpersandMe] amped.png

[gmic]-0./ Start G'MIC interpreter. [gmic]-0./ Input black image at position 0 (1 image 300x250x1x3). [gmic]-1./ Set name of image [0] to 'AmpersandMe'. [gmic]-1./ Input file 'ampersand.cimg' at position 0 (1 image 137x137x1x1). [gmic]-2./ Set name of image [0] to 'TheAmpStamp'. [gmic]-2./*local/ Add salt&pepper noise to image [1], with standard deviation 0.03. [gmic]-2./*local/ Display images [0,1] = 'TheAmpStamp, AmpersandMe'. [gmic]-2./*local/ Shift image [1] by displacement vector (0,0,0,1.375), periodic boundary conditions and linear interpolation. [gmic]-2./*local/ Convolve image [1] with kernel [0] and neumann boundary conditions, with normalization. [gmic]-2./ Normalize images [0,1] in range [0,255]. [gmic]-2./ Display images [0,1] = 'TheAmpStamp, AmpersandMe'. [gmic]-2./ Output image [1] as png file 'amped.png' (1 image 300x250x1x3). [gmic]-2./ End G'MIC interpreter.

With the insertion of a new item at the beginning of the list, the sole image in the AmpersandMe named selection acquires a new list index of ‘1.’ Reindexing does not remove it from the AmpersandMe named selection, however, even though the former index of ‘0’ initially linked this image in the named selection. Nor does the apparent error of ‘naming selection zero twice’ hold. The ampersand template, loaded from ampersand.cimg, becomes included in the ‘TheAmpStamp’ named selection through an independent naming operation. Selections provide for the inclusion of images in named selections just at the moment of creation. Subsequent re-indexing does not change associations. The image created in the first step of this example continues its association with AmpersandMe even as the composition of the image list changes. In light of this, script writers mostly do not have to worry about where images in named selections are on the list, saving much counting on one's fingers.

One Association at a Time

An image cannot be associated with more than one named selection at a time. If an image is subsequently enrolled in a different named selection, it loses its association with the previous one.

gmic \ -sample rose \ -name[0] BlurMe \ -input[0] [-1],[-1],[-1],[-1],255*u \ -name[0-–1] Granfalloon \ -blur[BlurMe] 4 \ -output[BlurMe] rose.png
[gmic]-0./ Start G'MIC interpreter [gmic]-1./ Input sample image 'rose' (1 image 600x500x1x3) [gmic]-1./ Set name of image [0] to 'BlurMe' [gmic]-1./ Input image at position 0, with values '255*u' (1 image 600x500x1x3). [gmic]-2./ Set name of images [0,1] to 'Granfalloon' [gmic]./ *** Error *** Command '-blur': Invalid selection [BlurMe] (undefined label 'BlurMe').

With the inclusion of all images on the list within the named selection Granfalloon, the rose image ceases its association with BlurMe. Since the rose image is the only member of that named selection, the selection itself ceases to exist and subsequent references to it raise an exception. Had there been other members of BlurMe, the named selection would have persisted but the rose image would not have been blurred or saved.

Example: Multiple Image Tracking

The following example illustrates the inclusion of a multiple number of images within single image selections. Without named selections, this example would have been both harder to code and harder to read. In addition to index bookkeeping, named selections let the gmic script writer signal intent through an apt choice of selection names.

gmic                                                                   \
   -input '(127,215,130,90,215^129,64,210,125,180^131,90,37,220,63)'        \
   -input ampersand.cimg                                                    \
   [-1]x12                                                                  \
   -name[1--1:4] Red                                                        \
   -name[2--1:4] Green                                                      \
   -name[3--1:4] Blue                                                       \
   -name[4--1:4] Yellow                                                     \
   -name[0] Colormap                                                        \
   -local[Colormap,Red] -map[Red] [Colormap] -endlocal                      \
   -local[Colormap,Blue] -mul[Blue] 3 -map[Blue] [Colormap] -endlocal       \
   -local[Colormap,Green] -mul[Green] 2 -map[Green] [Colormap] -endlocal    \
   -local[Colormap,Yellow] -mul[Yellow] 4 -map[Yellow] [Colormap] -endlocal \
   -remove[Colormap]                                                        \
   -append x                                                                \
   -output. ampersand.png

ampersand.png:

The template, ampersand.cimg, is a single channel binary mask with each pel being set to either 0 (background) or 1(foreground). We multiplex this mask twelve times, leaving thirteen ampersands on the image list, and group these into separate selections using the modulo-n (:n) selection notation. See 1.5 Command Items in the G’MIC Handbook or Command Decorations at this site. The initial -input command introduces a three channel color map with four swatches, written as an image specification, and organized for use with -map.

The game is to group these ampersand masks into named selections, one for each color, then pull the members of the various named selections into corresponding local image lists, scaling and color mapping the masks to the color maps in each local image list. Citing named selections instead of literal selections eases the complexity of setting up each local image list, the name clearly signaling the intent of the local list.

The Host Application Use Case

When running in the hosted gmic plugin in such applications as Gimp, Krita and similar layer-based graphics applications, filter authors can set the name, opacity, compositing mode and position of newly exported layers. -name is able to convey a small script to the host application that, when executed, sets pertinent layer attributes. The filter author may also query the host application for current values of a layer's name, opacity, composition mode and position. These are available through a set of gmic commands that are only defined when a gmic script runs in the gmic plugin, and not in other environments.

Example: MapMaker Filter

The following utility generates a feathered selection mask when given a central color of interest and a selectivity value.The mask most strongly selects the central color of interest. Unlike -select_color, however, this mask does not produce a binary, all-or-nothing selection, but, instead, assigns a percentage of selection inversely related to the distance of a given color to the central color of interest, using a Euclidean color space metric - see -norm and Orientation Color Theory for background. Selectivity determines how rapidly the mask deselects other colors as they differ from the central color of interest. Higher selectivity — as in higher selectivity means fewer selected pixels — gives rise to a more rapid drop-off. The utility shares a great deal of its machinery with -select_color, differing mainly in that it uses a Gaussian distribution curve to set the rate of dropoff, rather than a step function.

The filter harnesses -name to incorporate both the RGB components of the central color of interest and the selectivity setting in the mask's host application layer name. With this, the filter user can later reference the properties of the mask, and perhaps, later on, produce another mask with similar settings.

 1 #@gui  __
 2 #@gui  <b>Testing</b>
 3 #@gui  <i>Gmic tutorials</i>
 4 #@gui  Mask Maker : gtutor_maskmaker, gtutor_maskmaker_preview(0)+
 5 #@gui  : Notabene =  note(<small>1. Choose color of interest. Your mask affects this the most.</small>)
 6 #@gui  : Notabene =  note(<small>2. Choose selectivity. Higher selectivity limits mask to mainly the color of interest.</small>)
 7 #@gui  : Notabene =  note(<small>3. Press 'OK.'</small>)
 8 #@gui  : Notabene =  note(<small>4. [In Gimp] Choose mask from Layer dialog. Switch to channel dialog.</small>)
 9 #@gui  : Notabene =  note(<small>5. Drag any one of the Red, Green or Blue color channels to the lower section, re-creating it as a selection mask.</small>)
10 #@gui  : Notabene =  note(<small>6. Right mouse button click on the new selection mask and choose \"Channel to Selection.\"</small>)
11 #@gui  : Notabene =  note(<small>7. Central color of interest will be most susceptible to change by subsequent edits; similar colors less so.</small>)
12 #@gui  : Notabene =  note(<small>8. Activate and preset mask opacity to compare with original. Set output to \"New Layer(s)\" for an original to compare.</small>) 
13 #@gui  : Notabene =  note(<small>9. Tutorial eventually.</small>)
14 #@gui  : sep1     = separator()
15 #@gui  : Color of Interest    = color(127,127,127,255)
16 #@gui  : Selectivity          = float(1.0,0.0,6.0)
17 #@gui  : Preset Opacity?      = bool(0)
18 #@gui  : Opacity              = float(0.01,0.01,100.0)
19 #@gui  : sep1     = separator()
20 #@gui  : Sep = separator(), note = note("<small>Author: <i>Garry R. Osgood</i>. Latest update: <i>2017/09/01</i>.</small>")
21 gtutor_maskmaker :
22    -repeat $!
23       -local[$>]
24          nm=${-gui_layer_name}
25          -softsel. ${5},${1-3}
26          nnm=$nm-S:{round($5,0.001,0)},R:$1,G:$2,B:$3
27          -if $6
28             -name. name($nnm),opacity($7)
29          -else
30             -name. name($nnm)
31          -endif
32       -endlocal
33    -done
34 gtutor_maskmaker_preview :
35    -gui_split_preview "-gtutor_maskmaker ${^0}",$-1
36 #@gui  __
37 
38 #@cli softsel : 0<=selectivity<=6,col1,...,colN
39 #@cli : Make single channel liminance mask in which maximum luminance
40 #@cli : coincides with the selected color. selectivity: higher -> steeper
41 #@cli : drop-off around selected color. 
42 softsel : -skip ${1=0}
43     -echo[^-1] "Select color (${2--1}) in image$? through Gaussian window of width $1."
44     -verbose -
45     -repeat $!
46         -local[$>]
47             dfg={iM>(2^8-1)}
48             dep={2^(2^(3+$dfg))-1}
49             -remove_opacity.
50             --fill_color. ${2--1} 
51             -sub[-2,-1]
52             -mul. {1/(iM-im)}
53             -norm.
54             -fill. gauss(i,2^(-($1+1)))
55             -normalize 0,$dep
56         -endlocal
57     -done
58     -verbose +

Copy and paste this code in your local .gmic file. Users of legacy pre-2.0 gmic plug-ins need to change comment tag #@gui to #@gimp and #@cli to #@gmic (See the 2.0.0 G'MIC release notes). The directions for using the filter are embedded in it's header.

The mask generator itself, -sofsel, has been implemented for the command line environment and most of its workings are described in -select_color theory. -softsel differs from -select_color in the final stage. instead of harnessing a binary function to set pixels as in-or-out of tolerance boolean flags, -softsel uses a Gaussian distribution function to set a varying degree of selection. Largely deselected pixels are not luminant, mostly selected ones are, and they vary in accordance to a Gaussian distribution.

The coding germane to this article is in the plug-in wrapper and the pertinent lines are highlighted with color. In the green line, the script author asks for the host application layer name corresponding to the current image. -gui_layer_name returns this name as a part of its status, which sets the command level variable$nm. Currently, there are four such host access commands: