ScriptSpot

Script

Instance Tool

By Matan · Credited author: Matan Halberstadt · 2011-05-16

Version
2.6
Version requirement
Tested on 3ds Max 2019
Date updated
2020-09-23
Votes
51
Description

Instance tool analyze the geometry objects in the scene and finds groups of objects that could be represented as instances of one of them. Then the user can turn every group into actual instances and choose which object from the group will be preserved. The objects in the group are objects that have the same topology (could be morph targets of one another) and the difference between them could be described with transformation alone. After making a group into instances, all the objects in the group except the master object will become instances of the master and a new transformation value (position rotation and scale) will be applied to transform them back to their original shape and orientation.

 

The advantages of using instances over just copies of objects are:

  1. It saves storage space.
  2. It saves memory.
  3. It saves render time.
  4. It saves work time (modifying one instance effect all of them, like uv mapping).

 

Updates:

version 2.6

  • fix an error with corona scatter

version 2.5

  • fix for the "undefined to integer" error (tested and confirmed on 2019)
  • fix for issues with "preserve pivot"

version 2.4

  • Added Group by Material ID checkbox - if checked, only objects with the same material ID setup will be grouped as instances.
  • UI is now resizeable on the height axis.

version 2.3

  • Added Group by Scale checkbox - if checked, only objects with the same scale will be grouped as instances.
  • Added Group by Material checkbox - if checked, only objects with the same material will be grouped as instances.

 version 2.1

  • "-- Unknown property: "getName" in undefined" error message in early max versions is now fixed.

version 2.0

  • All mesh geomety is now supported including Editable mesh, Editable poly and primitives.

Installation:

 

  1. Drag and drop the mzp file into the viewport, the tool will pop up.
  2. Go to Customize -> Customize user interface.. -> Toolbars tab
  3. Under the category "Snowball VFX" you will find the InstanceTool, drag it into a toolbal.
  4. Enjoy.

 

 

UI description:

 

  • Get groups Button: analyze the scence and collect the potential groups. In no objects are selected, the whole scene will be analized, but if there are selected objects, only groups containing at list 1 selected object will be created (this will take less time).
  • Tolerance Spinner: set the maximum distance alowed for every vertex of an object to move from it's original location in order to become instanced to another object.
  • Ignore hidden objects CheckBox: If checked, it will ignor hidden objects.
  • Random wirecolor per group CheckBox: if checked, every group will recieve a unified  random wirecolor.
  • Instance selected group Button: Make the selected group in the Groups listbox into instances of the master object.
  • Instance all groups Button: Make all groups into instances.
  • Groups ListBox: Shows all the found groups after the analyze is done, and let the user select a group. Double clicking the group will select the objects of the group in the scene.
  • Remove selected group Button: Delete the selected group from the list.
  • Group Membets ListBox: Shows the objects in the selected group. Selecting an object from the list will select it in the scene. Double clicking an object in the list will set it to be the master (the master is the object that has the prefix ">>" in the list. This is the object that will not be changed at all when instancing the group, all the other objects will become instances of it).
  • Remove selected Object Button: Delete the selected object from the group.
  • Attach selected group Button: Attach all the members of the selected group into one mesh.
  • Attach all groups Button: Attach all the groups, every group will become one mesh.
  • Detach selected objects Button: this option is only available if you are running snowball pipeline for now.
  • Select instances: Select all the instances of the selected objects in the scene.

 

Instance tool UI

 

Links:

http://www.snowballvfx.com/

http://cargocollective.com/matan#1450373/Instance-tool

Videos
Attachments

Tags: instance, geometry, automated

Comments (81)

The Tool is not worling with some objects

Tornado · 2024-05-19

Hello,

Thank you for creating this tool.

I have encountered an issue where the tool does not function correctly with detached Editable Mesh objects.

You can find an example of this issue at the following link:
https://www.dropbox.com/scl/fi/3lrbj4stwptxjsr3g3im3/Instance-Test.max?r…

Any suggestions would be greatly appreciated.

Additionally, I have another question. Could this tool be translated to Python to take advantage of multiprocessing capabilities? I'm curious if AI tools might facilitate this process.

Thank you.

link broken

crystal3d · 2022-02-11

too bad i could try...

Matan · 2022-02-11

what link are you talking about?
They all seems to be working for me

Matan · 2022-12-08

which link? everything looks ok to me

Matan · 2022-12-08

which link? everything looks ok to me

Matan · 2022-12-08

which link? everything looks ok to me

todor · 2021-10-26

Looks cool :)

This script description is like a dream

nnq2603 · 2021-10-24

...and probably comes true. Just I haven't run it at the moment to witness it. Thanks you. I gonna have it tested on work very soon. Nice day there.

undefined type integer

zrK · 2020-08-30

Hello Matan, thanks a lot for your time saver script ! very usefull !
I also have the error "undefined type integer" using 3ds max 2019. I tried to download your last version 2.4.1 if that could fix this error but the script remains in version 2.4 from 2016. Could you help me with this ?
Cheers !

Thomas

Matan · 2020-09-09

Hey zrK, thanks for letting me know.
I'm pretty sure that version 2.5 should solve the "undefined type integer" issue once and for all

thanks !

zrK · 2020-09-14

yep :) that seems to fix my issue, thanks a lot Matan for your work !

A strange Problem

Madgik51 · 2020-03-04

Hi,
First i want to thank you for your amazing script.

I use your script like 'hypersapien', for game engine purpose. Im going to give you plz some steps to reproduce the problem.

1.Create a box and convert it to editable poly

2.Detach all faces and delete the original box that is empty.

3.Open your tool then "Get Groups" check "Reset Transform controller" and "Preserve Pivot" then "Instance Groups"

4.You will notice that the created instances are not perpendicular but like slightly rotated <= This is the problem

5.Click on "Hierarchy -> Pivot -> Affect Object only -> Center to Pivot"

This Result is what I get on the game engine, the instances are all rotated with some percentage (not the original one); so they are not 'snapped'

Plz see if there is some steps that maybe can solve the problem before using your script. I tried to do xform before your script, but it doesnt help

Thank you very much

Matan · 2020-09-09

Hey Madgik, sorry for taking so long to reply. Thank you for reporting this issue and giving the steps to reproduce it. Version 2.5 solves some issues with the "Preserve Pivot" feature. Note that if you retry the same steps, it will still not produce a perfect result. One of the box sides won't be instanced with the others. This is due to the way this specific side is numbered. The vertex numbering of this side is different from the others and therefore it can't be instanced using this tool.

Most sides of the box are numbered like this:
1-----------------2
|......................|
|......................|
|......................|
3-----------------4

But one side of the box is numbered like this:
1-----------------4
|......................|
|......................|
|......................|
2-----------------3

Simply irreplaceable script!!!

xStatic · 2019-11-07

Thank you very much, Mr. Halberstadt!)

arak · 2019-05-06

Can't live without it anymore!

Thanks!!!

Ignore Hidden Objects checkbox triggers Get Groups

mitchfx · 2018-08-23

GREAT TOOL!!! One small bug I've found that if you uncheck the "Ingore Hidden Objects" option, the script will trigger the GET GROUPS action automatically even if you are not ready to do that yet. In large scenes this can take several minutes and makes it seem like the script is frozen.

Thanks for the awesome script!

Problem with conservation of UV.

alexish657 · 2018-04-25

Hi there,

your scripts is seems to work in most of the cases.

However, I presently have a situation where the UV's are not preserved when I transform the individuals meshes into instanced meshes.

I'm trying to optimise some planes that are used to created hair on a character head. So originally there is like 6 planes that are instanced many times (250+) on the head of the character.

I need to corrected the geometry of these planes. So you script is perfect for this situation. I proceed like this.

I detach all the planes from the original hair mesh. I got after that almost 250 individual planes with the same material on it. Then, I use your script to turn the meshes into instancied ones. However, the majority of the now instanced plane see their UV messed up.

Do you a way that I can secure or lock the UV as it is before I use your script ?

thank you

Love this!

Medart123 · 2017-06-05

This is a great tool. Thank you!

Saved my bacon!

stevirt · 2017-03-06

Thanks a million! I had my son place a few thousand meshes in a scene. Had to be positioned just right so it was not a fast or easy task. At the end his file was over 350,000 mb. Ouch! I knew immediately that he had copied instead of instanced. There were only 4 different meshes, each with it's own material. I found this plugin and was very skeptical. It was fast and worked to perfection. New file size : 29,000 mb. Thanks again!!!

error: Unable to convert

HalukOzkul · 2017-02-01

Hi Matan,

I tried using the v2.4 with default settings. The objects in the scene are editable mesh. I get this error message:

--Unable to convert: undefined to type: Integer

Do you know how to fix this? Thanks for your time, cheers.

Attachments

Me too

hypersapien · 2017-08-29

I also get the problem about "unidentified type: integer". Before I was using Max 2012 and had no problems, but recently I updated to Max 2017 and now this problem occurs.

The only work around I have found is to limit it to running the tool on smaller groups of objects at a time- rather than the entire scene all at once. It seems there is some object(s) in the scene that just break it, but I haven't been able to figure out which.

Matan · 2018-01-02

Hi hypersapien, sorry for the late answer.
I don't have Max 2017 so I can't test it out but I just updated the script with something that might just fix the issue. Please let me know if it now works

migero · 2016-08-11

will it work on vray/corona proxy ?

Non-Orthogonal matrix support

hypersapien · 2016-06-21

Hello, your script seems potentially amazing and a huge time-saver, but I am running into an issue:

I am making a scene to be exported to FBX and then into a game engine. Sometimes, when I use your instancing script it causes the effected objects to throw a "Warning: Non-orthogonal matrix support" error.

I've tested this as thoroughly as I can manage- I'll export clean geometry to FBX and it works fine, then I run this script and immediately try to export again, and now all the geometry that was re-instanced now has this error.

Is there any way to fix this? The only way I know how to fix non-orthogonal matrix problems is to apply reset x-form, which then breaks instances, so I'm back at square-one.

script freeze

antomor · 2016-04-11

I try work with huge mesh objects, and script freeze and not response. I need close a 3ds max.
And script error with corona scatter object

Great Tool !

Robert Y. · 2016-03-30

Hello,

Thanks Very much for this tool, but I have a question :

Could you make this tool work with mirrored objects ? , Since if I have few complicated objects and I start to mirrored them and by mistake I forget to choose mirrored as instances.

Regards,

Matan · 2016-03-31

mirroring should work

Thanks!

Robert Y. · 2016-03-31

Yes it's works!, may be my 3D Max was hanging!

Additional Features

voltaire585 · 2016-02-16

Hi Matan , love the script very useful to optimize large files.

I would like to add some additional options. ie
- check to instance only objects of the same scale
- checkbox to instance objects only of the same material

We would be happy to implement these features ourselves if that would help. Would it be possible to get the script as human readable?

Thanks

Additional Features

Tornado · 2016-03-05

This additional features looks great, when we expect to see it ?, and are you going to make for your personal use or you can share it ?

Best Regards,

Matan · 2016-03-06

the new version has the requested features:
* checkbox - group by scale
* checkbox - group by same material
cheers.

Scrolling tab is needed

Tornado · 2016-03-08

Hello Matan,
Thanks very much for the update :) :), it's very useful, but i can't use all tabs and because now the script window become larger, I hope you can help me with this problem , adding Scrolling tab and re-sizing the window may be solve the problem.

My screen resolution is 1360 X 768.

Also I try to use "Instance material" option but it is not instance the objects with same material, it's made for something else !

Best Regards,
Thanks in advance

Attachments

Matan · 2016-03-08

Updated the tool to be resizeable.

'Instance material' is used when you want the material to be instanced together with the objects, so that all the objects in a group will share the same material.

What you want to use is the new checkbox named 'Group by material'. This option will only instance objects that share the same material already.

Its work like a charm :)

Tornado · 2016-03-08

Many thanks Matan :) you are the boss :)

Tolerance Not Working

leejk · 2015-03-04

After experimenting some more, the tolerance setting does not work for me in 3ds max 2015. Regardless of what it is set to, I get the same result. It often will try to instance square like objects that are clearly visually different. I'd be happy to share an example scene to demonstrate.

rgds

Doesn't Handle Square Objects

leejk · 2015-02-24

Hello,

Very useful tool, but as someone else mentioned it has problems with objects that are the same in vertex count, but have different widths & heights. For example, it makes all square like objects of different sizes all the same instance. Not sure the tolerance setting is working as it should in this case.

rgds

Does not work with like objects

eyepiz · 2014-06-18

Great tool...but it instances unwanted items, such items that are exactly the same only different in height and lengths.

I don't this the Tolerance Spinner works.

Creates problems with UV's

Matan · 2014-11-24

The tolerance parameter works like this: two objects are considered as potential instances if one of them can be transformed into the other with a single linear transformation, in the sense that all of it's vertexes will align with the other object's matching (by index) vertexes with a maximum error distance of the tolerance value. I hope this is clear enough.

latest version

ltchest · 2014-06-11

anyone got this working in Max 2015 ?

Matan · 2014-11-24

works for me on 2015, can you give me some more info on the error you get?

and for splines?

lillolas · 2014-05-20

good job! this is a great tool, no doubt, but I'll like to use it for splines (shapes) too. consider this for future versions please!

mxdsa · 2014-02-10

amazing; thanks!

Ruddy · 2014-01-22

Same problem as the user below, the pivots are all mispositioned and even after centering them they somehow still remember those wrong positions which make it useless if I want to replace the base objects with another one, please, please fix this.

kurt_hectic · 2013-05-23

works well, thanks!!!

This totally saved my ass today

rotem · 2013-05-22

I'm glad I remembered it :)

version 1.5?

cptSwing · 2013-04-22

Hey man, drag-dropping works fine now. Funnily enough, it seems to install version 1.5? Or do I have fragments of my old version lying around on my harddisk? ;)

That said, 1.5 worked fine, so I'm not complaining!

Matan · 2013-04-23

I just forgot to update the title, fixed it now

Matan · 2013-04-22

I think now I got everything working, I also tested it on max 2013 without this sp variable to be sure.

Still get the error..

cptSwing · 2013-04-17

..at least with the version linked to in here (105.8 kb).

>> MAXScript MacroScript Error Exception:
-- Compile error: Undeclared variable: sp <<
-- Error occurred during fileIn in #C:\Users\xx.xx\AppData\Local\Autodesk\3dsMax\2013 - 64bit\ENU\scripts\Snowball_Tools\InstanceTool\InstanceTool.mse; line number: 155
-- Error occurred in anonymous codeblock; filename: C:\Users\xx.xx\AppData\Local\Autodesk\3dsMax\2013 - 64bit\ENU\scripts\Snowball_Tools\InstanceTool\InstanceTool.mse; position: 4060; line: 155

I'm running Max 2013 64 bit on Windows 7

EDIT: I get the error when I try to execute the script, not when I install (which seems to work)

the same error

jefim · 2013-04-16

on drag and drop :

-- Compile error: Undeclared variable: sp

fixed the sp variable error

Matan · 2013-04-17

fixed the global sp error, sorry for that

error

VitaminD · 2013-04-15

on execution i get error :

-- Compile error: Undeclared variable: sp

declaring this variable ("global sp" in listener) helps ))

Doesnt work...?

roamn · 2013-03-29

i get this error message when clicking the button get groups:

-- Unknown property: "getName" in undefined

I have 3ds max 2009 64 bit, windows 7 system...

i had converted the geometry to editable mesh...
it still gives me this:

-- Unknown property: "getName" in undefined

how can i fix it please?

Matan · 2013-04-02

"i get this error message when clicking the button get groups:

-- Unknown property: "getName" in undefined"

This bug should be fixed in version 2.1

Script for Max 9 or Max 2009

ojgang · 2012-07-26

is it possible that this script will work on max 9 or max 2009 ?

Matan · 2013-04-02

it should work now

Works Great,

onodi.andras · 2012-06-07

Hello Matan,
Thanks for the great script. It works like a charm. I have just imported a 800Mb scene from Maya, and seems like I can dramatically reduce file size. Any chance that you are planning to enhance this masterpiece? I would have a suggestion:
It would be awesome to rename obejcts in one instance-group to something like "object_name_xyz". Right now the only way to do that is manually.

Could this script work on 3ds Max 9

adriandw3 · 2012-04-24

Hello Matan

This script is great and really useful for the type of geometry I am working with (originating from CAD data)

I have it working on Max 2010.

However I am restricted to using 3ds Max 9 because of some software I am exporting to. When I try and run with Max 9 (by dragging and dropping mzp into max 9) I get error:
-- Syntax error: at bad, expected
-- In line:

Is there a way this script could run for 3ds max 9?

Many thanks
Adrian Williams

cptSwing · 2011-12-15

i've had success just slapping a shared Edit Mesh modifier on top of the Editable Polies, running the instance tool, and then deleting it again. great script!

sry but it does nothing

dddesign · 2011-08-19

when I click the Get groups button nothing happens! It´s a scene with some copys of a cube.
tested in max2011 and max2012...

Matan · 2011-08-21

the script only works on editable mesh objects, convert these boxes to editable mesh and try again

this has been tried before but none could achieve a realible

crystal3d · 2011-07-14

solution and i am curous about what it does...thank you for sharing already

It doesn't seem to pick up mirrored objects

Alex Morris · 2011-06-28

This is a huge time saver but I've noticed that it is not recognising some mirrored geometry as potential instances.

Matan · 2011-07-14

Alex thanks for the reply, There is no reason for it not to recognize mirrored objects. I would appreciated it if you could send me a scene with 2 objects that are mirrors of each other and that the tool doesn't recognize. Cheers, Matan.

silencer77 · 2011-06-20

Now nothing happens for me also. It just worked but now it doesn't. Strange

silencer77 · 2011-06-20

It also seems to to mess up any animation on the objects

silencer77 · 2011-06-20

extremly useful. However when I use it it messes up my mapping on the new instances. Any idea?

Matan · 2011-06-22

"when I use it it messes up my mapping on the new instances. Any idea?"

This is because when instancing a group, the script copies the base object of the master to the rest of the group. Any difference between the base objects will be lost once instanced. However ant modify will be saved. So in order to keep the mapping you will have to make sure the mapping data is saved in the modify stack and not in the base object. If you have already collapsed the stack you can use a "UVW Mapping Paste" modifer to extract the mapping data to the stack.

"It also seems to to mess up any animation on the objects"

This is because when instancing the objects I change their transformation. (This is the opposite operation of reset xform)
You can keep the animation intact by creating a dummy to hold the animation for the geometry and to act as their parent.

Matan · 2011-05-23

The script should work on 2012 (works on my station).
Are you running the latest version of the script?
Can you tell me what does the error say?

cheers,
matan.

wolfsoull · 2011-05-23

i install it on max 2012, but dont work :(

Script dont work

Shiva · 2011-05-18

Very usefull script but unfortunatly don`t work on 3dsmax9

titane357 · 2011-05-18

hello, thanks for this script, but do it supposed to work on 2012 ?

Matan · 2011-05-18

Didn't test it on 2012 yet but I don't think there should be a problem.
Let me know if you have any problems.

titane357 · 2011-05-23

hello, I get a message error when I run the script
"--Compile error: Undeclared variable: sp"
Maxdesign 2012 win 7
Thanks.

Matan · 2011-05-24

try to download and re-install the script as I have already fixed this issue.

titane357 · 2011-05-25

hello, thanks for update, but run the script, clic the button and nothing happen... MAXdesign 2012

Matan · 2011-05-26

You might be using the tool wrong.
Is it working for you on a previous version of max?
Could you send me an example scene?

begon · 2011-05-17

Not work dovnload link

Matan · 2011-05-17

sorry about that, fixed.