"Animbrush Tools" - documentation

[guru]

When the Frank Lyon's 'Natural Media Vol. 1' brush collection was in beta, I promised I would prepare some docs to assist anyone interested in creating similar "Animbrush Tools" of their own.

The idea is to encourage proliferation of these tools by allowing Mirage artists to access the functions we provided with the original download. These functions permit you to create new Animbrush Tools without writing the necessary Element routines. (As well, this encourages a consistent implementation offering easy and trouble free sharing between users.)

The next post will provide all the info necessary. (This thread will be locked and 'sticky', but please feel free to ask questions in other threads in this Forum or the Element one.)

[guru]

Animbrush Tools for Mirage

Creative Mirage users often take advantage of Mirage’s animbrush feature to fashion interesting and stylish custom drawing tools.

To facilitate this kind of innovation, with the release of the “Natural Media Brush Set, Vol. 1” we provided some new tools. (We’re referring to this custom brush class as Animbrush Tools, to distinguish them from other more mundane animbrush applications.)

Animbrush Tools and the Custom Panel

The Custom Panel in Mirage from version 1.5 makes a great repository Animbrush Tool sets.

It’s worth noting that the files involved can sometimes be rather large. As convenient as it might be to add these animbrushes directly to the Custom Brush Bin, doing so indiscriminately can tax system resources. Using Custom Panel buttons to execute an Element script to load (and optionally re-color) the file directly from disk seems preferable with current technology.

To drastically reduce the effort needed to create the supporting scripts for such a button panel, we have provided an Element “Include” file to ‘dish up’ all the necessary function! This makes it very easy for would-be brush designers to assign pre-programmed functions to new Animbrush Tools.


What is Required?

The Source Project

To assign a new Animbrush Tool to a Custom Panel button, you must first design the source animbrush itself. This is then saved as a .mir (Mirage Project) file.

The .mir file must be placed in a specific subdirectory of the main Mirage program folder:

Custom Panels\NaturalMedia\brushes\yourfoldername\

Notes: brush source projects should be in a resolution appropriate for the tool being designed, but ‘smaller is better’ when it comes to loading times.

Also, while the whole idea is to provide an animated drawing tool, excess frames take longer to load. Surprisingly good results can be obtained with just a few frames, and there surely would seldom be a need to exceed perhaps 50-60 frames.

The Element Script

Only a superficial understanding of Element scripting is needed. As with all Element scripts, the file is a simple ascii text file. Examining the scripts in the subfolder(s) of Element\NaturalMedia\ may provide you with all you need to know. (You could even simply modify the examples found there and save them under a new name!)

Here are the basics:

The Element file begins with a ‘commented’ title line such as:

// Natural Brush Loader Template ver.1

Next comes a line that tells Mirage the script does not require any user input

PARAM None

Following this are the ‘working’ lines of the Element. As a minimum, only 4 lines must be supplied, as shown below:

bname = "mybrush.mir"
bdir = "myfolder"
defopac = 100
#Include Element\Include\nmbrush.grg

 The first statement identifies the name of the brush project file, and the value (the filename) must be surrounded by double quotes.

 The next line identifies the name of the folder the source brush project is in (this folder must itself be inside the Mirage main program folder named here:

Custom Panels\NaturalMedia\brushes\

(Again, double quotes must surround the directory name.)

 The default Opacity for the tool after loading
 The Include statement, typed exactly as shown.

So – the complete (basic) Element to be assigned to the button would look like this:

// Natural Brush Loader Template ver.1

PARAM None
bname = "mybrush.mir"
bdir = "myfolder"
defopac = 100
#Include Element\Include\nmbrush.grg

Save the file as text, with the filename extension “.grg” Place it in the Element folder, preferably in a self-named subfolder of the Element\NaturalMedia directory.


Default Functions

When the script has been assigned to a button, the specified source project will be loaded as the current tool from the folder defined. In the Custom Brush panel, the default Opacity value supplied in the script will be preset.

In the absence of any of the optional variables discussed later, certain defaults will apply:

 A popup menu will appear when you click the button. This menu lets the end-user elect to load the tool using the “Default Colors” (derived from the source project) or re-color the new tool with the current A/B pen colors before loading it.

 If the brush source project is 1) comprised of two layers and 2) A/B is chosen in the popup menu, the current A color will be applied to the uppermost layer while the lower layer gets the B color.

 The application mode for the tool after loading will be set to “Color”

 “Step” will be turned off for the tool.

 The tool’s “Opacity” connection will be set to “None”

 “Drying” will be turned off

 The “Anim” mode will be set to “Pressure”


Using Optional Functions

The defaults just described are easily changed to permit very different Animbrush Tool designs. For example, there are actually 3 recolor modes available to you. (Really, the default option is not likely the best choice for most purposes!)

Optional functions are enabled by the use of additional variables supplied in the brush-button Element script.

For example, adding the following line (before the Include statement) changes the paint mode of the tool after loading to “Behind,” rather than “Color”:

paintmode = 1

(As mentioned earlier, if this optional line is omitted, the tool defaults to “Color” mode.)


Here is a list of the optional functions you can use, and the variables and values that control them:

Menu
Enable or disable the popup “re-color?” menu

showmenu = 0 // show the menu
showmenu = 1 // do not show the menu

Use A/B?
Force A/B on or off; for use when showmenu = 1 (no menu)

useabcolor = 0 // always use original color(s)
useabcolor = 1 // always re-color using A/B pen colors

Swap A/B?
Reverse standard A/B re-coloring order

swapAB = 0 // apply A color first
swapAB = 1 // apply B color first

Paint Mode
Set the application mode for the tool after loading to Color, Behind, Erase, etc. The value supplied is the line number of the mode in Mirage, with line 0 being “Color,” line 1 being “Behind,” and so-on.

paintmode = 0 // use Color mode for the tool
paintmode = 1 // use Behind mode for the tool
etc. …

Brush Step
Turn “Step” ON or OFF, and set the Step value. Using a zero for the value turns Step OFF. Any other number enables it and sets the Step value.

brushstep = 0 // Step is OFF
brushstep = 12.5 // Step is ON, and set to 12.5%

Opacity Connection
This option controls the connection type (if any) for the newly loaded tool. The value to be supplied should be surrounded with double-quotes, and is a letter of the alphabet. You can use N,S,D,O,F,R,P,T,A,or FI.

opac_con = “R” // the Opacity connection will be set to “Random”
opac_con = “P” // the Opacity connection will be set to “Pressure”
etc., …

Anim Mode
Determine the Anim mode setting in the tool upon loading. This requires a text value entry surrounded by double quotes.

animmode = “Random” // the Anim mode will be set to “Random”
animmode = “Pressure” // the Anim mode will be set to “Pressure”
etc., …

Recolor Method
As mentioned earlier, 3 different A/B recoloring methods are available.

Multi-layer: although this is the default, it is the slowest method. The source project can be one or more layers. If there are at least two layers, the top layer and second layer are re-colored using the current A/B pen colors, then merged.

Alpha Mode: only a single layer is required in the source project. The contents of the frames in the layer will be re-colored using a gradient spanning the current A and B colors, with the color applied to each pixel being controlled by its individual alpha channel level.

Luma Mode: only a single layer is required in the source project. The contents of the frames in the layer will be re-colored using a gradient spanning the current A and B colors, with the color applied to each pixel being controlled by its luminance level.

recolormode = 0 // multi-layer re-color method
recolormode = 1 // alpha based re-color method
recolormode = 2 // luma based re-color method

Hint: Luma is arguably the best approach to use for most designs. Unlike the Alpha method, it permits fully opacity at both ends of the A/B gradient, while respecting opacity for edge feathering, anti-aliasing, etc.

When creating either Luma or Alpha based brush source projects, set the Mirage background to a medium gray to aid with visibility. This will not affect the end-result, yet makes it easier to tweak alpha values or black and white extremes during the creation process.

If you need advice or assistance, please avail yourself of the Forums, or e-mail support. And please condsider sharing your custom Animbrush Tools with the Mirage community via the Content Exchange!
.