Autumn Leaves 1.1.0 for Maya (maya script)

Autumn Leaves v.1.1
===================

AUTHOR:    Mayec Rancel
https://www.mayec.eu

VERSION: 1.1

Tested in Maya Versions: 2011 x64, 2009 x64


PURPOSE:
=======        

This script prepares a scene for a realistic simulation of falling tree-leaves.
You can also make them blow in the wind, or collide with the ground or other objects, etc.

The simulation itself is done with nCloth. The idea is to have one or several leaf models,
and their corresponding low-res models (sub-divided and shaped planes, basically). This script
will:
1. Scatter as many copies as you want of those leaves, on the NURBS surface of your choice
    (with random rotations), avoiding intersections.
2. Combine all the low-res models into a single object (named "simLeaves_Lo") , which will be
    simulated with nCloth.
3. Apply wrap deformers to the high-res leaves, so they will have the movement and deformations of the
    simulated low-res leaves.
4. Set basic parameters of the nCloth simulation, although you will have to tweak those depending
    on the scale of your scene/leaves and desired behaviour.


INSTRUCTIONS:
============

For the script to work, you need to have in your scene:
- A high-res model for each of you different leaf variations, named "leaf*_Hi"
    (e.g.: leaf1_Hi, leaf2_Hi and leaf3_Hi.)
- As many corresponding low-res models, properly aligned and with the same number
    as their corresponding high-res leaf. Their names should be "leaf*_Lo".
    (e.g.: leaf1_Lo, leaf2_Lo, leaf3_Lo). These models are to be simulated
    with nCloth. For instructions on how to optimize them for this use, read
    the Maya documentation on nCloth, or take a look at the Autumn Leaves example scene.
- A NURBS surface, where all your leaf copies will be placed.
When you execute the script, you just have to confirm (or modify) the number of different
leaf models you want to use, input the name of your Placement Surface object, and enter
the number of copies you want of each leaf variation.

Execute the script. And after all the calculations and setup, your scene should be ready to play
and sim. By default, script hides low-res leaves and leaves high-res leaves visible. If you hide the
high-res and show the low-res instead, your simulation will go faster (for display reasons). You can
cache it, and then bring back on the high-res leaves for playblasting/rendering.

You will probably want to tweak the parameters of the nCloth object, to adapt to your scene
scale and/or desired behaviour. The default settings are suposed to work pretty well with a real scale
(leaves aproximately 10cm large). The script sets the following parameters to these values:

    nucleus1:
            Space Scale: 0.05
            Use Plane: true
            SubSteps: 12
            Collision Iterations: 16
            Start Frame: 1
    nClothShape:
            Thickness: 0.3
            Lift: 0.6
            Drag: 0.6
            Mass: 5
            Bend Resistance: 5

So if things look weird for your specific scale, these could be the first parameters to adjust: Space Scale,
Thickness, Lift, Drag, Mass and Bend Resistance.

After running the script, you can add fields or collisions to the nCloth sim.


TEST SCENE:
==========

With this script you will find a test scene, called "autumnLeaves_testScene.ma". It´s an example of how to
set your scene before using Autumn Leaves. Just open it, and launch the AutumnLeaves MEL script. Leave
everything at default, and set up the number of copies (around 20 is a good value), then run, and you should
see the pretty leaves flying around.

The leaf models in this scene were modeled and kindly donated by Bego Gonzalez. Feel free to use them for your
animations, as long as proper credit is given to her (and to me, if you use the script ;).

KNOWN BUGS:
==========

TO DO:
=====
    - more precise check for intersections.
    - more scatter options:
         - scatter leaves on an object's surface (make it work for Poly)
         - scatter leaves in an object's volume
         - scatter leaves at particles
     - option to have other names for leaf models.