MacroScript SuperPainter v2.0 Help documentation

MacroScript SuperPainter v2.0 lets you distribute objects in certain areas or on the surface of another object. A variety of parameters are adjustable: number, type and weight of source objects, boundary spline, distance between clonings, random transformations and materials. It is possible to save and load script presets. The main purpose of the script, for which it was created - distribution of tree models on various surfaces and areas.

Limitations:
Paint and Spread functions do not work with groups. Most of functions work only in world coordinate system. For example, tool Glue moves objects only along Z axis. The main purpose of the script leads to limitations of the way algorithm works in Z direction and world plane XY, e.g. in correspondence with the direction of tree growth.

Definitions:
Source Objects - appear in the list: Sphere01, Box01, etc., objects that will be cloned.
Ńlonings - objects originated from the source objects.
Base - base object, on which surface clonings can be created.
ID - Object ID, for each source object and its clonings.
Weight - percentage of cloned objects within all clonings.
Paint - tool to paint clonings manually on object surface or world XY plane.
Glue - tool to move any selected objects onto base surface or world XY plane..
Spread - tool to distribute clonings within selected spline or only on its contour.
Draw - tool to paint spline manually on surface of base object or in the world XY plane.


Description of the interface:

1 - main window of the script.
2 - second, additional window of the script for work with materials and presets. Shows up when button Materials is pressed.


Main window (1)

Blue area - buttons to pick and remove source objects from the array. Any object can appear only once in the array list. Base-object cannot be in the list.
Button Add - adds selected objects to the array and shows them in the list.
Button Pick - allows to choose objects one by one by hit, adds them to the array and shows them in the list.
Button Rem. (Remove) - removes from the array the selected object in the list.
Button Clear - nulls the array of source objects and clears the list.

Orange area - list of source objects array and their parameters: ID, Weight, Radius. Buttons and spinners to adjust object's particular weight, radius and Object ID. Also you can use spinner below button SR % to adjust selection percentage in SR mode if the button unchecked. Tooltip and text of the button changes automatically when you press it.

Clicking on the elements of the list selects the source objects in the scene. Double clicking selects all clonings of that source object. Ctrl+clicking adds selected to the current. If you don't want anything in the list to be selected - select one and ctrl+click on it again. Number of source objects and size of the list is unlimited.

Button ID - shows/hides Objects ID in the list.
Spinner ID - assigns Object ID to the selected objects in the list and their clonings.
Button Weight - shows/hides objects weights in the list.
Spinner Weight - defines weight of clonings of chosen objects. Total weight can't exceed 100%, it is always automatically checked before cloning and recalculated if necessary. Source objects with zero weight don't participate in the cloning except in special cases (see below the descriptions of cloning types).

Button SR % / Radius - In unchecked state hides Radiuses (Spread mode uses those values) of the objects in the list. In this case you can use same spinner to set percentage for the SR mode. In checked state shows radiuses in the list and you can use spinner to set them for Spread mode.
Spinner SR % / Radius - In SR % state sets percentage of the current selection for SR mode. In Radius state sets Radius value intended for increasing of the distribution density in Spread mode. It changes in percents and works like this: during calculation of distance to neighbouring objects script takes by default the maximum over all dimensions of the object (in the XY plane), multiplied by R/100. Because of that, you can decrease radius individually for each object, in order to reduce the distance between clonings. Good results without intersection are usually reached at R from 30 to 40%.

Pink area - buttons to define types of clonings: C - Copy, I - Instance, R - Reference.

Yellow area - spinners, defining distance between clonings.
Spinner Min - minimum distance between objects. Spinner shows display units and simultaneously in the prompt line - in system units. It is used in Paint mode and Spread mode.
Spinner Max - maximum distance between objects. Spinner shows display units and simultaneously in the prompt line - in system units. It is used in Paint mode and Spread mode.

Green area - buttons SS and SC to select objects and button as box for altering display mode.
Button SS (Select Source-objects) - selects all source objects in the scene and in the list.
Button SC (Select clonings) - selects all clonings. Selection is applied by name, e.g. digits are removed from behind the name of the source object, if there are such and by this filter all objects, which match it, are selected. Don't forget to take this into consideration and give unique names to the source objects.
Button as box - turns on/off mode of object display - Display as box. Use this, if geometry of source objects is complex and slows down viewport performance.


Red area - two modes of cloning: Paint č Spread (button X - additional parameter of Spread mode), Draw mode to draw splines, Base-button to choose Base, Glue-button to move selected objects, SR-button to select random objects, RS-button to replace current selection with clonings.
Button Paint - switches on/off Paint clonings mode. If Base is turned on, clonings are created on the surface of the base object, otherwise in the XY plane of current viewport.
How to paint: on base - just click or hold left button while moving mouse around to create sequence of clonings; on XY plane - hold without releasing to create sequence of clonings, or click, move a bit and release to create a single clone.
If during painting you press and hold Alt, the objects will not be oriented to the normals of the base surface, e.g. orientation regarding Z axis will not change. If you press and hold Ctrl, then will be cloning only selected objects in the list disregarding weight and they will appear instantly. If you press Ctrl only once and there is more than one object in the list, then instead of objects Dummy will be painted in the beginning, which after final painting are automatically replaced with objects from the list with regards to weight. Source objects with zero weight during this operation are ignored and no their clonings are created.
Distance between clonings - random value between two limits, upper one is assigned by spinner Max, lower - correspondingly with Min spinner. If both spinners have zero values - no clonings will be painted.
If both values of spinners are equal, then painting is only possible with "clicking", e.g. pressing and holding left mouse button will do nothing. If you paint by moving the mouse around - new clone will be created at the moment when distance from mouse cursor to previous clone exceeds the generated random value, but is lower than the Max value. That is why, if you move mouse too fast - you can "escape" from the previous clone and then nothing will be painted, until mouse cursor is again in the necessary limits, e.g. must return to the last painted clone. Or you can release the button and start painting again.
Button Glue - works only with currently selected objects, moving them along Z axis on the XY plane, or onto base object. It works correctly with Groups. If you press the button, while holding Alt, then local axis Z of objects will be made vertical. Glue works with splines also, moving their vertices, in particular you can easily make splines a flat.
Button Base - turns on/off/chooses base object. When Base-button is turned off, role of the base object is performed by world XY plane, when turned on - by base object picked by user. When button is pressed, the title on top of macroscript will display which is the base object at this moment or user will be prompted to choose base object - Pick Base Object.
Button X - turns on/off intersections of clonings in Spread mode. If X is turned off - algorithm is more accurate, chaotic position of clonings and intersections will be kept to minimum. If turned on - chaotic positions will be more and intersections correspondingly a lot more.
Button Spread - fills selected spline with clonings if spline is already selected, if not - asks to choose spline and fills it. Values of spinners Min and Max during Spread can be equal to zero. Lower parameter R, if you want clonings to be distributed closer one to another. Clonings will be automatically positioned inside on distance away from spline boundary, so that they don't intersect. The offset distance is either equal to maximum dimension of the biggest source object, or by the value of Max spinner - whatever is higher equals that offset distance.
If you don't want clonings to move to offset distance - press and hold Alt when you press Spread.
If when pressing Spread you press and hold Shift - clonings will be distributed only on spline boundary.
In the prompt line during Spread appears information about cloning progress. At the beginning places for future clonings are defined, then at the actual place clonings are created with regards to their weight. Minimum amount of clonings till first break of algorithm - 5000. Next - 10000. The breaks are necessary in case too many clonings are created. At the end of cloning script will "ask" for orientation of objects along Z - if their local Z axis needs to orient the same as world Z or remain as is. This question - analogous to button Alt in Paint mode on base.
Button Draw - turns on/off mode of spline drawing on surface of base object, or XY plane. Spline is automatically optimized after creation (lowering number of vertices), if you want to turn off optimization, draw with pressed Shift.
Button SR - selects Random Percentage of the Selected Objects. Select something and set percentage in spinner SR % / Radius before pressing.
Button RS - replaces Selected Objects with Clones of Source objects. Hold Ctrl when pressing to clone only selected in the list source objects. Old objects will be deleted, new clonings will be selected. Clonings inherits position and orientation of replacements, if MRS-transformation are turned on then scripts applies it too. Source objects are impossible to replace, script automatically deselects them when you press RS button.

Blue area - buttons and spinners, responsible for object transformation. Basic workflow: turn on any of buttons M, R or S (turning more than one at the same time is not going to work) and define in spinner necessary limits. Let's say you pressed M and put value 20 in Z. This means that when pressing Apply (which is relevant to the current transformation) selected objects will move each to random value from -20 to 20 along Z axis( local or world). If Paint mode is active, then you can turn on MRS-buttons the way you want and paint instantly transforming clonings, but because of that you must not define limits - they are set before turning Paint mode on. If you turn off Paint mode - everything returns to starting position and new limits can be defined.
Buttons M (Move) R (Rotate) S (Scale) - turn on/off editing of limits in XYZ spinners for transformation of selected objects or clonings, created during Paint and Spread modes and set current transformation.
Spinners XYZ - high limits of transformation along three axes. Lower limit is equal to the negative value of higher limit. Transformation is a random number between these two values.
Button Apply - applies current transformation to selected objects.
Button All - applies all transformations to the selected objects or turns them on/off for clone modes Paint and Spread.
Button 3 A - turns on/off equal limits of transformations along all three axes XYZ. Turn on this button and change any spinner limits - value in rest of spinners will become the same.
Button Same - turns on/off equal random values for Scale ( and only Scale) transformation along all three axes XYZ. Necessary for uniform scaling. Works only if button 3 A is turned on.
Buttons W (World) and L (Local) - define current coordinate system.

Button Materials - closes/opens second additional window.


Additional window (2)

Group Presets
Button Load - loads a preset (previously saved file with extension spp), in which are defined source objects, their parameters and values of script spinners. During loading of preset previous array of source objects is nullified, list is cleared, instantly new array is built based on the preset data, and the list is filled again. Path to the preset file is shown in the field Current.
Button Save - saves to preset the array of current objects and values of script spinners. Path to the preset file is shown in the field Current.
Button Layers - shows/hides Layer Manager window for layers adjustments.

Group Random Materials
Spinners From and To - define range of materials, which will be assigned to the objects.
Radio buttons Medit (Material Editor) č Mlibrary (Material Library) - define material source.
Checkbox Full Range - assigns in spinners From and To values, corresponding to the full range of materials from the current source: material editor or material library.
Button Apply - applies material on selected object(s).

Button Help / About - opens this document and prints information about the author of this script in the MAXScript Listener window.