Hi, I’m trying to re-learn Blender now that the 2.8 UI is out. I tried using the scripting interface tonight and had a pretty bad experience, mostly because of 2 bad problems that I was only able to get past by the help of people on Twitter (in other words, without a good Twitter network I wouldn’t have solved them at all). I have recommendations that would have alleviated both issues. I’m posting here instead of filing bugs because the bug tracker says not to file “Functionality which works as intended but could be improved” and what I encountered might have been Blender’s intent.
Here’s what I did: I ran Blender 2.8.0 on Mac OS X 10.13.6 (I later re-ran all steps with Blender 2.8.2). I had created a scene with several models, and I wanted to export each model to its own GLTF file. Because I might need to do the export several times, I figured it would make sense to script the export step. I clicked the “Script” tab, I noticed there is a “Templates” button, I noticed there is a template named “Batch Export” and hey, I read the source and it does EXACTLY what I wanted! It exports to FBX, but there’s a comment by the export_scene call that says
# Can be used for multiple formats # bpy.ops.export_scene.x3d(filepath=fn + ".x3d", use_selection=True)
So that’s easy. I consult the documentation. I see the gltf function is named “gltf”. I replace
bpy.ops.export_scene.gltf. I click “Run Script”. It doesn’t work.
What went wrong
There were two problems.
As you see if you look very carefully at the documentation (see link above), all of the functions in
bpy.ops.export_scenetake a named parameter named
gltf(). That function has a signature totally unlike the other three, and the appropriate named parameter is
However it took me quite a while to figure this out, because:
When I ran “Run Script”, I was presented with the completely unhelpful error in the screenshot linked above (“doesn’t work”). In two places on the screen it told me to check the “system console”. What is the “system console”? There is no indication.
What I eventually found out is on Windows, Blender has an option in the Window menu titled “Show System Console”. However, this setting is not present on Macintosh, and there is nothing matching “system” or “system console” in the F3 search. (A friend checked and told me this option is also not present on Linux.)
On a tip from someone on Twitter, here is the only way I could get the error message that Blender told me existed: I actually had to launch Blender from the command line. Normally I’d expect that is not necessary, my expectation is usually STDOUT errors from Mac OS GUI apps go to system.log in Console.App. However Blender doesn’t seem to be printing to anything in Console.App that I can find. I had to launch Blender by manually executing
/Applications/Blender.app/Contents/MacOS/Blender(after unsetting my PYTHONPATH, since it broke Blender). This is very weird and I think many users would not know how to do this, even if they know Python.
Once I ran Blender from the command line like this, I was able to see the exception being thrown by gltf() and eventually realize I needed to change
export_selected. Once I made this change the script worked fine. But it took me about an hour each to figure out each of these problems.
Is this a problem?
Even given the number of “papercuts” Blender has on its TODO list, I think this is pretty bad. Consider: What I did was follow the exact instructions in a sample-code template that ships with Blender— the comment said to replace fbx with the format I wanted, and I did— and not only did it not work, it was not possible to see the error message explaining why not. Blender directed me into a timesink.
How to fix it
Here’s what I would do:
It is very confusing that
bpy.ops.export_scenecontains four functions that do the exact same thing, and three of them have seemingly identical signatures, and the fourth is entirely different. I would recommend changing the signature of
bpy.ops.export_scene.gltfbut I assume you can’t change API once it’s shipped. So instead I’d recommend the documentation for
bpy.ops.export_sceneshould explicitly call out the named parameter differences for
gltf(). If the parameter doc for
export_selectedsaid “(same as
use_selectionin other functions)” then at least someone ctrl-f-ing the document for “use_selection” would find it (it is hard to interact with this doc any other way since it is dense and uses iframes). It also might make sense to add a note to the comment in the “Batch Export” template noting
use_selectionmust be changed for gltf.
I’d be happy to make this change myself if it would be accepted; is the only way to edit the docs to join the mailing list?
The “Show System Console” menu item really should be added to the OS X and Linux versions. Running Blender from the command line just in case I need to use the scripts tab is really inconvenient, but I can’t imagine using the scripts tab without it because writing Python without access to print() statements or exceptions is just not viable. Even if it had turned out I could read the Blender stdout/stderr from console.app, it’s quite weird to have an integrated text editor and two separate python consoles inside blender, yet be tabbing into another application to see the results of the scripts I run inside blender.
If you really don’t want to include “Show System Console” for some reason, you should at least change the message when a script fails. A big problem is that right now, Blender is showing an error message which directs the user to a window that does not exist. The “system console” is a piece of Blender vocabulary. If you said “Blender STDOUT”, I would have at least had a fighting chance of figuring out where to look, but telling me to look in a window that only exists on Blender for Windows was too hard of a puzzle.