UV Scatter Script 1.4

Download UV Scatter Script 1.4
Last Updated 24 March 2013
This plugin requires the pyQT python libraries to be added to your maya installation. They can be downloaded here for windows and here for mac

I have only tested this plugin with maya 2013 64bit for Windows and Mac OS (Mountain Lion), but it should work on other versions.
If you run into any issues on 2011/2012 drop a comment about it and I will try and add support.


  • Quickly scatter multiple instanced objects over mesh surfaces.
  • Control the density of scattered objects using an image map.
  • Objects can be oriented to face normals.
  • Script can now bypass the LOD step if you do not require it.
  • Screen-space objects culling to hide and show objects visible to a specified camera.
  • Rotation and scale of scattered objects can be controlled through image maps.
  • LOD Grouping is setup automatically and associated with a camera of your choice.


  • PyQT libraries are required to use this plugin (the interface was built with pyqt)
    Nathan Horne very kindly has built libraries of PyQT for maya and they are available here
  • This plugin has only been tested on maya 2013 x64 (windows), but it should work with all version from 2011 onward.

Keep Updated

  • If you would like to be kept in the loop as to new versions of this software please sign up to the mailing list below


  •  Install the PyQt libraries if required. They can be downloaded here. Copy them into site-packages folder located in your maya install directory.
    e.g C:Program FilesAutodeskMaya2013PythonLibsite-packages
  •  Copy ScatterMap.ui to your default script directory located in your user folder.
    e.g. C:UsersusernameDocumentsmayascripts
  •  Copy the shelf file “shelf_uvScatter.mel” to your default shelf directory.
    e.g. C:UsersusernameDocumentsmaya2013-x64prefsshelves
  •  Copy the shelf icon  “uvScatter.png ” to your default icon directory.
    e.g. C:UsersusernameDocumentsmaya2013-x64prefsicons
  •  Copy ScatterMap.py to your maya plugins directory.
    e.g. C:Program FilesAutodeskMaya2013binplug-ins
  •  Open up maya and display the plugins menus. (windows -> setting/preferences -> Plugin Manager)
  •  Activate the plugin. (if pyqt is found and the UI file is loaded successfully the plugin will activate)
  •  Load the shelf.
  •  To launch the scatter plugin, click the shelf icon or type “uvScatter;” into the mel command line at the bottom of the maya window

UI Layout & Controls

UI window for uv scatter script

  • 1. “Load target”:
    loads the object that will be scattered onto.
  • 2. “Orient Scatter to Target”:
    Rotates the scattered objects to match the orientation of the face normals of each face being scattered onto.
  • 3a-3b. “Load Meshes”:
    Loads and displays a list of the high-resolution meshes that will be scattered. The order can be rearranged by clicking and dragging in the list box (3a).
  • 4a-4b. “lod replacements”:
    loads and displays a list of the proxy / “Level of detail” (LOD) meshes that will be swapped out when the camera moves outside of the specified LOD boundary.
  • 5a-5c. “search & replace”:
    By  naming you meshes with the suffixes contained in the search & replace boxes,  the script will be able to auto-load your LOD objects by replacing the “search” suffix with the “replace” suffix thereby correctly loading the  object(s) into the LOD list.
    e.g. it will look for an object called “TREE_hires” and load “TREE_lod”   into the LOD list. This is the recommended workflow. This will ensure that the LOD objects are associated with the correct high res mesh.
  • 5d. “Bypass LOD”:
    Scatters instances without setting up an LOD system.
  • 6a. “Select LOD Camera”:
    Displays a list of cameras that can drive the LOD switching.
  • 6b. “refresh list”:
    Refreshes the list of cameras.
  • 6c. “LOD Switch Distance:”
    Sets the distance from the camera that will trigger the switch between the high resolution object and the matching LOD objects.
  • 7. “load Map”:
    Loads an image map to determine the likelyhood of scattering in a particular area of the map. Useful for controlling where you want objects to be scattered.
  • 8. “Grid Density”:
    Sets how many “samples” the script will take of the target mesh and the image map. Higher values take longer to process. This value is dependent on the scale of your target and objects you wish to scatter. It is best to test with low numbers (around 64).
  • 9. “Scatter Quantity”:
    Sets the quantity of objects to be scattered.
  • 10 “Go!”:
    Checks the settings and scatters the object.

Standard Workflow

  • 1. Model target surface.
    The surface must be a mesh object and unwrapped correctly without any uv overlaps (auto unwrap will work too if necessary). The uv’s must fall within 0 – 1 space and should ideally use as much of the UV space as possible for optimum performance. The script uses UV co-ordinates to do a lot of the work so without good UV’s the script will fail. Transformations on the model should be frozen before scattering as they affect how the  scattered objects will be oriented to the surface.
  • 2. Prepare the high resolution and LOD models.
    Set you pivot points and origins very carefully. For best results, place the two objects on top of each other at the origin, set the pivots and freeze transformations.
  • 3. Name your objects for easy LOD association.
    uvScatter script supports auto-loading of the LOD models based on naming convention. If you append the search and replace suffix to your object names, the LOD objects will be auto loaded and associated correctly with the matching hi-resolution object when you click the “guess lod” button. An example of the naming would be  as follows:
  • 4. Clean up model.
    Make sure history is deleted on your objects and that you do not have any transforms parented under them. The script does not currently support nested transforms and will result in a failure.
  • 5. Open  the uvScatter window.
    click the “uvScatter” shelf button to launch the menu or type uvScatter; into the mel command bar at the bottom of the maya window.
  • 6.Load the target.
    Select the mesh you want to scatter onto and click “load target”.
  • 7.Load your meshes.
    Select your high resolution mesh objects and load them by clicking “loads meshes”.
    Either repeat for the LOD objects (you may need to manually arrange them, by dragging the names in the list) or click “guess LOD” if you have named your objects correctly.
  • 8. Select your LOD camera.
    Select the camera out of the camera list that will drive the LOD system. This will most likely be your render camera.
  • 9. Set the LOD switch distance.
    The best way to work out this value is by turning on camera distance in your Heads-Up-Display and select an object in your camera view
  • 10.Load the scatter map.
    Load a grey scale image that will determine where on your target the meshes will be scattered. If no image is loaded, the meshes will be scattered uniformly.
  • 11. Set the grid density.
    The script divides the mesh into  a grid in order to efficiently calculate  the placement of objects. The more objects you want to scatter, the higher this number needs to be. Higher values will increase calculation time.
  • 12. Set the amount of objects you want to scatter
  • 13. Save your scene
    Calculation of this script can be resource intensive so it is advised that you save your scene before continuing with the scatter.
  • 13. Click “Go” to scatter objects
    If any errors in your setup are detected a warning message will display pointing out the issues. If the settings pass the check,  the script will execute and scattering will commence.

Current Limitations

  •  The target object must be unwrapped without any overlapping uv’s (you can achieve this with an automatic unwrap if you want). Utilise as much of the 0-1 UV space as possible. anything out of that range will be ignored.
  •  Only mesh objects can be targets. Nurbs and curves will not work.
  •  Meshes being scattered cannot have complex hierarchies (i.e. objects parents under objects etc)

Bugs Reporting / Feature Requests

  • If you have any bugs you would like to report, or if you would like to request a feature please leave me a comment or send me a mail: info(at)shanemarks.co.za


  • Version 1.3:
    • Added object / camera culling
    • Fixed orientation bug
    • Fixed crash on low grid density
    • added debug mode (set debugMode to True in debug.py)
    • Modularised Code
    • Version 1.3:
      • Cleaned up undo system
      • Added scale and rotation control
    • Version 1.1.1:
      • Fixed UI loading error.
    • Version 1.1:
      • Added “Bypass LOD” feature
      • Improved LOD generation
      • Improved human-error checking
    • Version 1.01:
      • Added Mac OS support.

Tags: , , , , , ,

UV Scatter Script 1.4

30 Responses

  1. The script looks great but I seem to get some kind of error when loading the plugin.

    // Error: SystemExit: 2 //
    // Warning: Failed to run file: /swiss/people/thomas/maya/2012-x64/plug-ins/ScatterScript.py //
    // Error: pymel.core : Failed to get command list from ScatterScript //
    // Error: pymel.core : Failed to get depend nodes list from ScatterScript //
    // Error: (ScatterScript) //

    And also a pop-up which say there was a problem with Qt when your plugin, although I have other scripts based on PyQt running fine.

    “the PyQt libraries could not be loaded. Please check that you have them installed”.

    When loading everything step by step from your script I get an error here:

    import sip
    sip.setapi(‘QString’, 2)
    sip.setapi(‘QVariant’, 2)

    Error: ValueError: API ‘QString’ has already been set to version 1 #
    Error: ValueError: API ‘QVariant’ has already been set to version 1 #

    So I tried removing them like this:

    #sip.setapi(‘QString’, 2)
    #sip.setapi(‘QVariant’, 2)

    I didnt get the same error this time, instead I got told that it couldnt find scatterMap.ui, although the path is correct. I tried changing your script to return the exact path to scattermap.ui (/swiss/people/thomas/maya/2012-x64/scripts/) but still got the same error.

    Any idea of what is going on? Thanks.

    maya 2012 SAP, linux.

    Thomas January 8, 2013 at 1:04 pm #
    • Hi, Thanks for taking the time to to report this error to me. Everything seems to be working correctly on my end, I have not tried this plugin on linux as I do not have maya 2012 or linux so it is tricky for me to diagnose the problem. Perhaps with your help we can get to the bottom of it, I have outlined the problems and my proposed solutions below though:

      Ok so problem 1)

      It seems like your pyQT / sip API is being set to version #1 by another plugin, which is conflicting with my setup:

      sip.setapi – “This sets the version number of an API. An exception is raised if a different version number has already been set, either explicitly by a previous call, or implicitly by importing the module that defines it.”

      That being said, the plugin should still work with the API values set to “1”. As you tried You should be able to comment these lines out and everything should run as normal, so please do that for now. In my next release I will add a bit of logic to check these values.

      Problem 2)
      As for not finding the UI , I had a similar problem on Mac systems. The way maya spits out the list of environment directories is different on each OS, so unless I can see what the resulting string looks like I cant diagnose it. If you could run the following mel line: getenv MAYA_SCRIPT_PATH and tell me what separator they are using to separate the different paths I can use that info to try and fix the UI loader for unix….

      in the mean time:


      try and replace this line:

      Scatter_form, Scatter_base = uic.loadUiType(findUI())

      with this line:

      Scatter_form, Scatter_base = uic.loadUiType(“/swiss/people/thomas/maya/2012-x64/scripts/ScatterMap.ui”)

      Please make sure you have permissions to read the file, if not maybe move it to a public directory. Let me know how this works for you and then we can move from there? If it doesn’t work I will take further steps to fix the problem



      shane January 8, 2013 at 1:43 pm #
  2. The seperator is a colon :

    And your fix worked, very cool 🙂 let me know if you need more testing on linux.

    Thomas January 8, 2013 at 3:36 pm #
    • Also, another thing I just noticed, it would be cool if you could use mayas 2d textures as maps too 🙂

      Thomas January 8, 2013 at 3:40 pm #
      • Hm, spaming a bit here, but the script doesnt work when I scatter the objects. Retried with a simple setup, standard plane and sphere, turned off lod, set grid to 1 and density to 4. A window pops up called “scattering objects” but its very small and empty, and maya just keeps on working with nothing happening.

        Thomas January 8, 2013 at 3:47 pm #
        • Spaming some more: it works with very low values, like 1 grid 3 scatter on a 4 poly plane, but more and maya seem to crash. Seeing as you recommended 64 in grid as a low value, I guess there is something funny going on.

          Thomas January 8, 2013 at 3:56 pm #
          • Hi there, That is very strange. It could have something to do with the fact that you are using maya 2012 (i have only tested from 2013 onwards) – everything is working correctly on my end. Could you let me know what error it is spitting out in the command console? I may need to add some debug outputs and then if you are willing to work with me on it we can work out all the bugs

            Also is the image you are supplying non-square (you dont have to supply an image too)?

            shane January 8, 2013 at 5:31 pm #
  3. I tried without a map because I wanted to try it as basic as possible. But I tried it with a square 2k black/white ramp now, grid 2, quantiy 4, and maya hung. Btw, I cant use the arrows to change the grid density but must enter it manually, maybe a ui-error?

    Anyhow, this is the last data the console put out when pressing go before it hung. Not an error but a warning at least:

    # Warning: object, ‘pCone2’, skipped. It is already a child of the parent, ‘world’. #

    Thomas January 9, 2013 at 9:01 am #
  4. I will try it on my windows maya 2012 at home later to see if it works there.

    Thomas January 9, 2013 at 9:05 am #
    • great thanks, that way we can establish if it is maya 2012 causing the issues or if it is linux. Try a smaller ramp too, perhaps 512×512. Though it should not make a different as it is using the grid density to sample the image map.

      shane January 9, 2013 at 12:03 pm #
      • Another issue 🙂 When I try using the script with lod, it doesnt crash maya but instead nothing happens and I get this error:

        # Traceback (most recent call last):
        # File “/swiss/people/thomas/maya/2012-x64/plug-ins/ScatterScript.py”, line 911, in computeF
        # scatter = ScatterMap(self.objects.getShelf(“source”),self.objects.getShelf(“lod”),self.objects.getShelf(“target”)[0],self.mapText.text(),quantity,gridDensity,camera,switch,False,self.orientToTarget.isChecked(),self.bypassLOD.isChecked(),randomScale,randomRotate)
        # File “/swiss/people/thomas/maya/2012-x64/plug-ins/ScatterScript.py”, line 165, in __init__
        # self.cameraSH=cmds.listRelatives(self.camera[1],children=True)[0]
        # ValueError: No object matches name: camera1

        and when I pasted this here I just noticed this line “self.objects.getShelf”

        I don’t know much about coding but are you trying to access the shelf in the script, or is it just a command completely unrelated to the maya shelf? Because I have it turned off and simply run your script with uvScatter;

        Thomas January 9, 2013 at 12:53 pm #
        • No it has nothing to do with the maya shelf, it has to do with the script not being able to find the camera you selected, did you delete or rename “camera1” between selecting it and scattering? Is there any way I can get a copy of your scene to look at? if possible please email it to me. I will make a plan to get maya 2012 so I can add support. Thanks for all the reports!

          shane January 9, 2013 at 1:17 pm #
          • Sure, I’ll send you the scene but I dont think the scene will give you anything interesting, I just opened a new scene, created a plane and a sphere + a duplicate to use as LOD, then I ran the script with my perspective cam selected in the LOD-camlist and got the error I posted above, I then created a new camera just to see if it was a problem with using the default camera, but still got the error that I posted.

            Thomas January 9, 2013 at 1:35 pm #
          • I tested out your scene, works perfectly on my side, it must be that the script does not function in maya 2012 🙁 I will have to makes some adjustments on my side. I will let you know when I get it working:)

            shane January 9, 2013 at 1:43 pm #
  5. Oh well, will test it tonight on windows just to make sure.

    Thomas January 9, 2013 at 1:55 pm #
    • Ok great, please let me know how that goes

      shane January 9, 2013 at 2:11 pm #
    • Also Upon further testing, the camera problem you are having is being caused by the API mode being set to 1, which is causing the output of the UI to be slightly different, I will also work on fixing that. If you can, when you test the script on your windows machine be sure to leave the SIP.setApi uncommented:)

      shane January 9, 2013 at 6:59 pm #
      • Ok, will do. Btw, completely forgot to test it, will do it tonight instead 🙂

        Thomas January 10, 2013 at 8:48 am #
      • Ok, tested at home, maya 2012 x64, win7, it still say it cant find the qt libs. Have python 2.7 with qt4 installed in site packages.

        thomas January 12, 2013 at 11:27 am #
        • Ok thanks, Well it appears the plugin is not working in 2012:[ Until I get a copy of 2012 there is not much I can do, that being said I will endevour to make a plan! I am back at work now so my time is a little short, but I will let you know when I get it right:)

          Thanks for your help

          shane January 13, 2013 at 4:19 pm #
          • No problem, let me know if you need a tester 🙂

            Thomas January 14, 2013 at 9:43 am #
  6. Hi Shane! Thanks for an awesome plugin! I can see so many uses for it. Unfortunately, I can’t seem to get the “orient scatter to target” to work as intended. The script turns the objects according to the slope of the target, but inversed. See the attached screenshot below. I was working with Z up and thought that this might be the problem, but the problem is still there after I have created a new document with Y up. I’m I doing something wrong? I have tried rotating the objects’ LRAs and inverted normals several times, but none seem to work.

    Screenshot: http://i.imgur.com/UGoSGgG.jpg

    Thanks for your help

    Carl August, Sweden

    Carl August March 5, 2013 at 2:12 pm #
    • Hi Carl,

      Have you tried freezing transforms before running the script? If you have and it is still not working then this is likely a bug (thank you for letting me know). I will fix it for the next release. Let me know if freezing transforms works for you



      shane March 5, 2013 at 3:18 pm #
      • Hi Shane. Thank you for your reply. I have tested it again and been very thorough to freeze transforms and delete all history by type for all the objects before running the script. I still can’t seem to get it to work. I have found out that the only error is that two transformation values are inverted. If I change the positive values to negatives and vice versa for the first and third number under rotation, the object seems to align perfectly, see screenshot.

        Also, the script seems to be designed only with “Y up” in mind (see screenshot below). Perhaps, in a future version, there could be a switch to let the user decide what axis to be up? Good for us working with Rhino and other software where it is not possible to change an axis 🙂

        Screenshot of the results and corrected numbers with Y up: http://i.imgur.com/K6FND2i.jpg
        Screenshot of simple setting with Z up: http://i.imgur.com/083dBc9.jpg

        Carl August March 5, 2013 at 4:22 pm #
        • Hey thanks for taking the time to send these images through to me, I will have a look at what is going on and then see what is involved into adding support for setting an up-axis. I am wrapping up with some projects this week so I will probably have time to look at it after then.


          shane March 6, 2013 at 4:26 am #
        • Hi there,
          Thought I would let you know that I have resolved the “orient to normal issue”.
          You can can see a screen grab of the results here:
          orient to normal
          I will be uploading a new version *hopefully* on monday. I will send out a mail when I do .


          shane March 22, 2013 at 7:11 am #
  7. script works beautifully! thank you for that. I was wondering if a Scatter Quantity of 999 is a current limitation? I can’t put in numbers higher than this.


    dave July 9, 2013 at 3:12 pm #
    • Hi there, Firstly THANKS!!!!! makes my day when my scripts work as intended hehe. Yes 999 is a limit, its “hard coded” into the UI, you can try and get around it (haven’t tested it though), by opening the ScatterMap.UI in a text editor and searching for this line Amount of objects to scatter

      Increase the number 999 that is just below it and you will be able to scatter more.

      I will get around to updating this for maya 2014 soonish (I hope), and then I will increase the limit.

      shane July 9, 2013 at 8:10 pm #
  8. Hi Shane, thank you very much for you UV Scatter script, works like a charm!
    I’ve tried BonusTool-Paint Geometry Tool, to populate trees on my scene…A Complete disaster (memory was spiking high like 16Gb and more, renders failed at 60% of the picture and so on)…
    Your UV Scatter made my day, I’ve been testing this morning, and got the 999 cubes proxy’s, render time and memory usage are good! 🙂

    Keep it up

    philip February 7, 2014 at 2:49 pm #
  9. Hello, thank you for sharing with script. In maya 2015 I can’t load plugin. Maya says “the pyQT libraries could not be loaded. Please check they have been installed. For more info on the pyQT libraries please visit http://shanemarks.co.za/2012/11/uv-scatter-script/“. If you know quick solution to this trouble please let me know.

    Oleg December 26, 2014 at 8:07 am #

Leave a Reply