Auto gen wrappers

[abelnation]

This is a significant re-work of the pythreejs extension that introduces an "autogen" script that generates the majority of the ipython-widget code to wrap each of three.js's types. It also takes a different view towards the pythreejs API. Whereas pythreejs adds custom functionality to the classes, sometimes renaming, etc., this approach attempts to mimic the low-level three.js API as closely as possible, opening up the possibility for others to build utility libraries on top of this.

This PR does not support all the functionality of the current pythreejs, but it is a significant step forward in terms of the potential to support the majority of three.js's features. Currently supported features:

• Basic building blocks of a scene:
  • Textures (both Image-based and Data-based)
  • Materials
  • Geometries
  • Meshs
  • Scene, Lights, Cameras, WebGLRenderer

---

The autogen script, generate-wrappers.js, takes advantage of a config file three-class-config.js to auto-generate both javascript and python files to define the ipywidget wrappers for each three.js class. The generated javascript files will have .autogen.js as the extension. The generated python files have _autogen.py as their extension. The script uses the handlebars template system to generate the various code files.

The autogen solution allows for overriding the default behavior of the generated classes. E.g., if Object3D.js is present, then it will be loaded into the namespace as opposed to loading Object3D.autogen.js. It is up to the author of the override classe to decide whether to inherit behavior from the autogen class or not. Same goes for the python modules. This allows for writing custom methods on both the python and javascript side when needed.

The autogen script relies on a json-like config file (three-class-config.js) to describe the classes. Reasonable defaults should take care of most, but it allows specifying the base class, constructor args, etc. for each of the wrappers. A base version of this file can be generated by generate-class-config.js, but beware, it overwrites any customization to the config file that has already been done.

List of relevant files:

js/package.json
js/webpack.config.js

# Files for auto-generation
js/scripts/clean-generated-files.js
js/scripts/generate-class-config.js
js/scripts/generate-wrappers.js
js/scripts/prop-types.js
js/scripts/templates/js_index.mustache
js/scripts/templates/js_param_obj.mustache
js/scripts/templates/js_wrapper.mustache
js/scripts/templates/py_top_level_init.mustache
js/scripts/templates/py_wrapper.mustache
js/scripts/three-class-config-defaults.js
js/scripts/three-class-config.js
js/scripts/three-class-config.js.backup

# New bases classes for supporting wrapper classes
js/src/_base/RendererPool.js
js/src/_base/Three.js
js/src/_base/enums.js
pythreejs/_base/Three.py
pythreejs/enums.py
pythreejs/traits.py

# Overridden classes
js/src/core/Object3D.js
js/src/textures/DataTexture.js
js/src/textures/ImageTexture.js # custom classed created to ease image texture loading
js/src/renderers/WebGLRenderer.js
pythreejs/core/Object3D.py
pythreejs/renderers/WebGLRenderer.py

# Updated examples notesbooks
examples/Examples.ipynb
examples/Geometries.ipynb
examples/Textures.ipynb
examples/renderer_limit.ipynb
examples/test.ipynb
examples/img/checkerboard.png
examples/img/earth.jpg

# Pulled in latest version of examples files from three.js source
js/src/examples/Detector.js
js/src/examples/controls/MomentumCameraControls.js
js/src/examples/controls/OrbitControls.js
js/src/examples/controls/TrackballControls.js
js/src/examples/js/controls/OrbitControls.js
js/src/examples/renderers/CanvasRenderer.js
js/src/examples/renderers/Projector.js

[abelnation]

@jasongrout @SylvainCorlay would love to discuss this idea with you guys. i've fleshed out a lot of the basics, and curious if you think it's promising. i think there are two situations where auto-generation becomes tricky:

1. classes where three.js is generating new objects that then need to be pushed back into the models (e.g. BoxGeometry/SphereGeometry)
2. complex models, e.g. the Geometry classes which tend to have references to multiple collections of other three objects.

In theory, you could just manually write the implementations of just those complex classes.

I'm a bit confused by some of the various conventions used in the current codebase:

• update() method replaces the three obj with a new one, using replace_obj
• new_obj creates a new three.js obj
• render also creates a new three.js obj

It could be useful for auto-gen purposes to move towards a common pattern for creating and updating three.js objects.

[abelnation]

Hey there! Wanted to give a shout, since I've been AWOL the last few weeks (got sucked into some contracting work for a spell).

I've updated my branch to fix a number of bugs and get a simple working example in place. Would be great to discuss a plan with you guys to figure out if you still want to move forward with this direction, and what the steps should be to work towards a merge.

I've also updated the PR description.

@SylvainCorlay @jasongrout

[vidartf]

This seems like it could potentially solve many issues. Is this still alive? Is there anything conceptually wrong with this approach, or is the lack of response simply because of the huge diff? If the last case, is there anything that could be done to help? If this is going in, it seems silly to spend a lot of time on manually adjusting what is included.

[SylvainCorlay]

@vidartf this stalled mostly because of the lack of response from us. We wanted to get ipywidgets 6.0 out of the door before integrating this. @abelnation had an amazing demo of this including

• setting up default renderer, texture, etc for displaying an object alone
• setting up default renderer, shape etc, for displaying a texture alone

etc...

I really think that this is the way to go with this.

[SylvainCorlay]

With more people looking at this now

• ipywidgets 6.0 is out finally
• you, jason and marteen back into 3-D visualization with the notebook

it is probably the time to revive this.

[vidartf]

you, jason and marteen back into 3-D visualization with the notebook

@martinal is also on this full time for the rest of the year at least, and there are other efforts via OpenDreamKit as well.

[jasongrout]

@abelnation - as you can see above, there are a number of people interested in pushing things forward with pythreejs now. Thanks again for your work on all of this, especially at a time when we were all busy with other things. Do you know the status of this autogeneration code now?

[SylvainCorlay]

Awesome! So it seems we might have a much bigger team working on widgets stuff!

[honorabel]

I'm glad to hear there's still interest! I'm unfortunately in a full-time role now, but would be happy to schedule a video chat w/ whoever is interested in continuing development to do a download of my approach and do a code walk through. The diff is definitely intimidating :P

[vidartf]

@honorable It is at least comforting that a large part of the diff is example notebooks :)

[jasongrout]

@vidartf, @honorable, @SylvainCorlay, @martinal - if you're interested in going through this walkthrough, can you indicate times you are available this week at http://whenisgood.net/9nbmxfb ?

[jasongrout]

I think we have times spanning basically half the world, so I hope it's not too difficult to find a time to do it together. If it's all right with the participants, we might also record it so others can see.

[SylvainCorlay]

Noon in EST should work for most people.

[vidartf]

@jasongrout : Those days are all holidays here (Easter), so me and @martinal are likely out. However, if you record it, it should hopefully be sufficient for us to catch the relevant bits later (we're still new to this repo either way).

[honorabel]

It's probably worth just postponing until @vidartf @martinal can make it, as I'll be presenting nothing new that @jasongrout @SylvainCorlay have not seen before.

[jasongrout]

Oh, right, it is a holiday. Let's try next week. Is Sylvain's suggestion, noon EST (1600 GMT) a good time for everyone? We have the ipython dev meeting on Tuesday and the JupyterLab dev meeting on Friday at that time, but Monday, Wednesday, or Thursday work at that time for me.

[honorabel]

Should work for me

[vidartf]

Let's try next week.

You mean the week after? Or were your original dates off?

[vidartf]

To be explicit from our side: This week me and @martinal are available. Most/all of next week will be difficult. The week after that should be OK except the Monday (17th, also holiday).

Regarding timing, all days of the week except Friday should work for me, and 1600UTC is fine.

[SylvainCorlay]

I am available anytime

[jasongrout]

Sorry for the confusion. I hadn't realized that whenisgood displayed next week by default, and then got confused about when Easter was.

Okay, let's try this again. @honorabel - what times work for you? Would two days from now (Thursday, April 6) at 1600UTC/noon Eastern work?

[honorabel]

Yeah, that should work. Probably need to keep the call to an hour tops, though.

[jasongrout]

Great, thanks! Let's meet on the Jupyter bluejeans channel at https://bluejeans.com/jupyter, April 6 at 1600UTC (Noon Eastern, 9am Pacific).

[SylvainCorlay]

Deal!

[jasongrout]

Great, thanks! Let's meet on the Jupyter bluejeans channel at https://bluejeans.com/jupyter, April 6 at 1600UTC (Noon Eastern, 9am Pacific).

Also CCing @misolietavec, who has been answering a lot of questions on issues recently. Feel free to join us, if you'd like!

[martinal]

Great, 1600 UTC tomorrow, I'll be there.

[abelnation]

This branch has been moved to the main upstream repo, same name, auto-gen-wrappers https://github.com/jovyan/pythreejs/tree/auto-gen-wrappers

[abelnation]

And FYI, just pushed some simple cleanup. Added the notes from this PR to the README for ease of use, cleaned up some commented code, and added setup/build instructions.

[abelnation]

Closing to open a new PR from the upstream repo and to track todo's to be able to merge