Undocumented command in MAYA mel/python: "polyIterOnPoly" ?!

Can anyone shed some light on mysterious command: “polyIterOnPoly”?
This command is present in both MEL and Python.
But there is no mention of it in the Maya documentation.
Google search has been fruitless…
Please, post an explanation of the flag syntax for this command, and examples of the use of this command.

Let me take you through my process.

Step 1: Grep for it in the maya install folder. Unfortunately this turned up nothing other than pymel registering the command, and some link to Debug.dll in bin/commandList

Step 2: Ask for help: help(cmds.polyIterOnPoly), and that returned something I wasn’t expecting. Usually it’s something like Help on built-in function, but I got this:

Help on function stubFunc in module maya.app.commands:

stubFunc(*args, **keywords)
    Dynamic library stub function

Ok, so this function is definitely different. Also, it’s on maya.app.commands, not maya.cmds. The plot thickens.

Step 3: I ran dir(cmds.polyIterOnPoly), and because it’s not a normal cmds function, maybe this will shed some light … and it does! Kind of. This object has the python code properties, that includes things like arguments defaults, and maybe the code itself!
Oooh, there’s a cmds.polyIterOnPoly.func_code property.
<code object stubFunc at 0000025BF39DECB0, file "C:\Program Files\Autodesk\Maya2020\Python\lib\site-packages\maya\app\commands.py", line 15>

I should probably check out that file!
Ooh, That file’s got a function called __makeStubFunc, and since the help() for that function said Help on function stubFunc, this is probably where it’s coming from.

Reading the docstrings and comments, it looks like it’s making some connections to some dll’s. Also, since cmds.polyIterOnPoly is a closure (an inner function returned by an outer function that may contain references to the outer function’s arguments), we should be able to read the closure args, and we can!

cmds.polyIterOnPoly.func_closure[0].cell_contents
cmds.polyIterOnPoly.func_closure[1].cell_contents

Which returns the strings polyIterOnPoly and Debug.dll respectively

So, it looks like code inspection is a dead end, at least from python.

However, since those are the values I saw in the grep from bin/commandList, I should check it out just to see what it is. And it’s exactly what it sounds like. A list of maya.cmds function names, and the dll’s they probably come from.

And just doing some spot-checks, it looks like everything that’s loading from Debug.dll is a stub func, while most of the other functions have been somehow resolved.


So, best guess. This is a function that’s part of Autodesk’s test suite or a leftover from some debugging test, and unless you want to start inspecting dll’s directly, it’s not something you should, or even could use.

2 Likes

@tfox_TD While polyIterOnPoly is a useless, your response is very useful.

3 Likes

One of my favorite PyCon talks ever was a guy figuring out how python bytecode worked on the fly. The discovery process he uses to dig into those internals is at least as important as the “how bytecode works” portion of the talk. Absolutely worth your time if you want to dig into this stuff.

5 Likes

Just using help polyIterOnPoly; in mel, I got the following text.

To get connected edges from a vertex would be
print cmds.polyIterOnPoly(vertexToEdge=True, vertex=2)

Synopsis: polyIterOnPoly [flags] [String…]
Flags:
-e -edge Int
-ef -edgeToFace
-efl -edgeToLeftFace
-efr -edgeToRightFace
-f -face Int
-s -silent
-te -traverseEdge
-tf -traverseFace
-tv -traverseVertex
-v -vertex Int
-ve -vertexToEdge
-vf -vertexToFace

3 Likes

Good call on the mel help. I get so focused on python-land, that I forget mel is still a thing :blush:

Oh, that’s fun… If you’ve ever dug into the mesh representation that ma/mb files use, they use a kind of windged-edge format, but they don’t expose that to the user any place in the api that I know of. That would make the edgeToLeftFace and edgeToRightFace make more sense in context.

2 Likes

Thanks mate, your advice is (as always) invaluable!

Narwhal, thank you so much!
I was so focused on tinkering with the Python/Python API that I completely forgot about “Occam’s razor”…