Bad experience with scripting tab on Mac OS; 2 recommendations

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.fbx with bpy.ops.export_scene.gltf. I click “Run Script”. It doesn’t work.

What went wrong

There were two problems.

  1. As you see if you look very carefully at the documentation (see link above), all of the functions in bpy.ops.export_scene take a named parameter named use_selection=Trueexcept gltf(). That function has a signature totally unlike the other three, and the appropriate named parameter is export_selected.

    However it took me quite a while to figure this out, because:

  2. 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 use_selection to 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:

  1. It is very confusing that bpy.ops.export_scene contains 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.gltf but I assume you can’t change API once it’s shipped. So instead I’d recommend the documentation for bpy.ops.export_scene should explicitly call out the named parameter differences for gltf(). If the parameter doc for export_selected said “(same as use_selection in 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_selection must 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?

  2. 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.

Thanks

I remember having the similar problem when using Blender on Windows a long time ago. I think someone added the “Show System Console” since then for Windows, but it didn’t get added for Mac OS or Linux (for Linux it seems less necessary, since most people start Blender from the command line in LInux). I will look to see if there’s a way to add this for MacOS. It is especially annoying for MacOS as it is not even that easy to find the path to Blender,

I develop Blender on MacOS (and Linux) and haven’t run into this problem because I always start Blender from within XCode, which has its own console. But I realize this isn’t a good answer for script developers who may not feel like building all of Blender on their own (though, if you are a developer who knows C, I would encourage you to do so, as it sometimes helps find problems quicker even as a script developer if you can see inside of Blender when something goes wrong on a script).

The maintainer of gltf seems to be @JulienDuroure and maybe he can change the documentation or even better, change the signature of the exporter to match the others.

While not disagreeing with your comments, I’d suggest giving a go to https://www.blender.org/community/. Some devs hangout at stackexchange too.

Filed a ticket at https://github.com/KhronosGroup/glTF-Blender-IO/issues/956 for this. I expect we can update the signature.

Yes, we will update the signature :slight_smile:
Thanks @mcc111 to point it out!

Note that the change is now committed in master, and will be available in blender 2.83

@JulienDuroure, @donmccurdy, thank you!

Howard_Trickey, thank you for looking into this. I think it is worth at least considering allowing the console on Linux also. While I imagine many or most Linux users probably do launch Blender from the command line some may launch it from eg the Ubuntu launcher. I don’t have a sense of how many people do so but those options do exist.