----------Scatter macro. Quick overview.-------------

This macro will help you to scatter objects on a ground, which can be a plane, a heightfield, an iso, whatever you want.
It uses a fairly simple geometrical algorithm which can lead to pleasant results, although not always physically correct.  
    

The scatter.mcr file contains two macros:

scatter (file_name): use this one if you want to place only one kind of objects.

scatter_multiple (number_of_objects, file_name): use this one if you want to give the macro a series of different objects to place.

Having two different macros for these two purposes makes them highly optimized and leads to faster results.
Be aware that this is just a *beta* version. There might be errors and bugs. This documentation is also temporary and does not include
an accurate description of the algorithms implemented.    
    
---------How do I use these macros?----------------

-------scatter (file_name)-------------------------

Of course you have to include the scatter.mcr file.
Then you have to declare a few variables.

scatter_land: the ground you want to place your objects on.
    *Don't use it in your scene as an object identifier, because it *grows* inside the macro (every object placed is put into it)*
    So I would suggest you to use another identifier for your land as you can see in the following example:
        
        #declare my_land = plane {y,0}
        #declare scatter_land = object {my_land}
        object {my_land}
            
                                      
total_objects: this is quite self explanatory. It tells the macro how many objects you want to place.
    
scatter_object: the object you want to place. It doesn't have to be textured. Any texture or material will be just ignored (soon you'll
                understand why).
                    
x_accuracy and z_accuracy: these two variables control how many times your objects are subdivided by the macro's algorithm. Higher values
                           quickly lead to much slower and not always better results. 10 subdivisions are often enough. If your objects
                           intersect, then you'll need higher values. If your objects don't intersect but are placed in a weird way then
                           you should probably lower these values. Dose these two values accurately: if you have a stick you may want to
                           lower the accuracy of the base to 5 and increase the accuracy along its length.
                            
height_accuracy: sometimes the objects are badly placed, and the three points of contact the macro usually searches for don't touch each other.
                 This float controls the minimum distance at which two points shouldn't be considered coincident. A value of 0.005 should 
                 work fine for most cases. Increase it if you're getting really too many 'Object badly placed, its position is being changed' 
                 messages (but remember that these messages are not error streams, it's normal getting many of these messages).

max_height: this is the only optional variable. It indicates the maximum height from the ground at which an object can be placed. Use it to
            prevent unrealistic growing of piles of objects.  

#macro position_macro () : You have to write a macro which chooses a (random or not) position. The full documentation (which I'll write and
                           publish within a few days) will include many examples and pre-written macros. At the moment I assume you know what
                           a macro is and how to write one. The macro should return a vector (of the XZ plane). Here are two simple examples:
                  
                    #macro position_macro ()
                    <-5+10*rand(RS),0,-5+10*rand(RS)>
                    #end
                        
                    #macro position_macro ()
                    #ifndef (counter) #declare counter=1; #end
                    #local vec = <counter,0,rand(RS)>;
                    #declare counter=counter+1;
                    vec
                    #end        
                                    
RS: it's the random seed used in the macro. The macro uses it when randomly rotates the objects around the Y axis. Nothing forbids you to
                                            use another seed for the position_macro.

#macro scatter_object_macro (): The scatter macro writes the objects placed on a file (see below) in the form of scatter_object_macro ().
                                This allows you to indipendently texture every object.
                                See this example:
                                    
                    #declare scatter_object = cylinder {0,0.1*y,1}
                    
                    #macro scatter_object_macro ()
                        object {scatter_object
                                pigment {rgb <rand(RS,rand(RS),rand(RS)>}
                                }
                    #end
                        
             Again, you can be sure that I will put much more examples in the *true* documentation.  
             
NEW:

#macro scatter_texture_macro (): this macro is optional. Define this macro if you want your objects to be textured according to their position.
                                 IMPORTANT: if you use scatter_texture_macro you DO NOT HAVE to define a scatter_object_macro.
                                 Just declare an untextured scatter_object.
                                 Example:
                    
                    #macro scatter_texture_macro ()
                    texture {
                        pigment {
                            gradient x color_map {[0 rgb 0][1 rgb 1]}
                            scale 5}
                            }
                            }
                            #end
                            
                    Since this macro is run after the object's tranformations the objects will be textured according to their position.
                    
                                            
Once this variables have been declared you have to *launch* the macro this way:

                    scatter (file_name) where file_name is a string which indicates the name of the file which will contain the union of 
                                        the objects placed.

Then you can include the file_name directly or within an object block:
                    #include file_name
                        
                    object {#include file_name}

I would suggest you not to use the macro and include the file in the same render instance. This could be memory expensive if you're placing
many complex objects. I would first run the macro, then comment it out and include the file. POV-Ray 3.5 allows renders without objects so 
this should be okay. That said, I have to say that I usually use the macro and include the file in the same render instance... :)
    
Warning: remember that the scatter object has to be properly oriented, with its bottom pointing down. Don't declare a stick with its base
         laying on the XZ plane and its length parallel to the Y axis unless you want to get very odd results (i.e. hundreds of sticks standing up).

---------scatter_multiple (N,file_name)-----------------
    
You have to declare all the variables listed above, except the scatter_object.
Here you will directly use a scatter_object_macro (Object), where Object is an integer which indicates which object to use.

The macro HAS to be this form:
    
        #macro scatter_object_macro (Object)
            switch (Object)
                case(1)
                object {object1}
                #break
                case(2)
                object {object2}
                #break
                ...
                case (N)
                object {objectN}
                #end
        #end

The case (0) will be ignored by the macro, which will randomly pick an integer between 1 and N.
If you want your objects to have different probabilities to be picked up use the #range keyword (again I will assume you know what 
I'm talking about). 

If you want your objects to be textured according to their position, use the scatter_texture_macro this way (*this time you HAVE to 
define the scatter_object_macro too*):

        #macro scatter_texture_macro (Object)
            #switch (Object)
                case (1)
                texture {T1}
                #break
                ...
                case (N)
                texture {TN}
                #end
            #end
           
            Again these textures will be applied after the object's transformations.    

Then launch the macro this way:
                scatter_multiple (N, file_name) where N is the maximum integer the macro will randomly pick to choose the object to place.


--------------------------------------------------------- 
I wouldn't suggest you to have a look to the code at the moment. It's really too messy. I will spend the next days cleaning the code up
and writing a more decent documentation, which will include a *step by step* description of how the macro works to allow people to adapt it
to their own needs.    

If you find this short reference a bit enigmatic wait for the full documentation or e-mail me.

You can freely use this macro in your works.

Jonathan Rafael Ghiglia.
Florence, 25th November 2001.                                                    
                    
                        
                                               
                                      
   

            

                                
            
    
        