3D rendering in the online documentation

[adam-urbanczyk]

We could use what @Peque has done ( https://github.com/Peque/sphinxcadquery ) to make the online documentation more appealing.

Cf. #13 for initial discussion

[Peque]

Pros

It may look good/cool:

https://bulebule.readthedocs.io/en/sphinxcadquery/building.html#rim

Cons

https://github.com/Peque/sphinxcadquery/issues

Worst is the "absolute URL" issue, which means it would only work well for the default branch when documentation is deployed in Read the Docs. Might be fixable.

Notes

It uses a slightly modified version of Thingiview.js. I do not know JavaScript, but the code looks awful (and unmaintained). I may have a look at three.js this weekend, which may fix both issues at the same time while providing a better and updated API.

I would keep the same options/syntax in the Sphinx extension, so if it gets integrated now, the move to three.js should be transparent and should not require any changes on your side.

Moving to three.js would also allow for potentiallly better formats (avoiding STL intermediate format).

[dcowden]

if only master branch works, it would not be a step backwards. previously we only built docs on master pushes.

It would be a luxury to be able to test docs on branches though.

[jmwright]

Tagging @zignig here since he has experience with using three.js to do these sorts of things with cqparts.

[zignig]

pong !

The viewer that I am using for my cqparts web_api work only loads gltf files.

can be found at https://github.com/cqparts/cqparts_webapi/blob/master/static/js/cqpartsViewer.js

It is largely built from the threejs tutorials.

[Peque]

@zignig Cool project! 😊

I am having a look at three.js and it looks great. I am guessing your implementation hits the same "Too many active WebGL contexts" issue if you put too many visualizations on a single page, right? As it seems you are creating a different WebGLRenderer for each one.

[zignig]

@Peque , I'm only really using one per page for viewing ( see https://cqparts.github.io/examples/ ). I did look at turning it into a web components some time ago , but never got anywhere. What you could do is a have the context show an image, an when you click on it it changes into a threejs viewer. With some global variables and some interlock code , you could ensure that only one of them was an active threejs viewer at any point.

[Peque]

I have got a working prototype that uses three.js. Should fix all issues the old implementation had, including the inability to show many scenes on a single page. 😊

I will probably make a release "soon". Still want to improve initial camera positioning and lighting.

It will still use the STL intermediate representation for now, but that can be easily changed to AMF if that is a better format. What other exporters does CadQuery have?

[dcowden]

@Peque that's AWESOME!

do you think it makes sense to re-group the cq documentation into more than one page, from a performance viewpoint? Even if it works, it might be annoying if the performance is slow.

[jmwright]

@Peque Here is a list of the supported export formats. Please note that there is direct three.js export support (TJS). That's actually what I use for cadquery-gui.

Thanks for working on this.

[adam-urbanczyk]

@Peque sounds great!

[Peque]

Pushed version 1.0.0 to PyPI. Tell me if it works fine! 😊

@dcowden I think you should not note any performance penalties, even if you have many scenes on one page, but tell me otherwise.

@jmwright Thanks, I opened this issue, in case someone wants to jump in. 😜

[dcowden]

@Peque This. Is. So. GREAT.

[Peque]

Not directly related to this, but in case you came over this issue before and know how to deal with it...

I am integrating sphinxcadquery in my own project and, while I have no problems in my local computer and while Read the Docs generates the pages successfully, Travis seems to complain:

https://travis-ci.org/Peque/bulebule

If you have any ideas, they will be more than welcome! 😇

[adam-urbanczyk]

AFAIR there is _Visualization.so in pythonocc. Could it be that you are running the failing command not from the right conda env?

[Peque]

It seems I am running it from within the virtual environment (I only create one virtual environment, I activate it, then I successfully run the tests, then only sphinx-build fails). 😕

[Peque]

Had to ask Travis to install libglu1-mesa first, but it is working now. 🤷‍♀️

[adam-urbanczyk]

Indeed, I have a similar line here: https://github.com/CadQuery/CQ-editor/blob/d9652505d10205cf2bdd4553df7139588ac9ef0f/appveyor.yml#L14 . Not sure anymore why it is needed.

[fragmuffin]

@Peque I had the same issue with running multiple three.js scenes on a single page.

https://cqparts.github.io/cqparts/doc/tutorials/assembly.html

I put each one into an iframe to get around the issue, but it's a messy solution.

[fragmuffin]

@Peque

What other exporters does CadQuery have

cqparts also has a GLTF exporter, which is just awesome (GLTF I mean 😉)

[Peque]

@fragmuffin In sphinxcadquery I am using a single canvas (allowing for many scenes on a single page without the need to use iframes). In case you want to have a look at it.

It seems to be working fine (I have already integrated it in my docs).

It currently has one drawback though, which is it would need better CSS to integrate well with all Sphinx themes. Currently it patches Alabaster and Read the Docs themes. But others could not work well out-of-the-box.

[fragmuffin]

@Peque : ooooo, I would definitely like to have a look, thank you!

[Peque]

Pushed a new sphinxcadquery version. It uses the TJS exporter. It looks better now (see a live example).

Before:

After:

It seems the three.js JSON loader has been deprecated. So maybe it is not the best format either, but looks like the best available in CadQuery 😊. Or is AMF/STEP better?

[adam-urbanczyk]

That looks really good @Peque ! What are the non-deprecated formats? If nothing too crazy, we could add another exporter

[adam-urbanczyk]

I see AMF and STL loaders. Is it possible to achieve equally nice result with the latter format?

[Peque]

@adam-urbanczyk I was using STL previously. Probably not the best format (?).

I think glTF may be a good one, but do not know if it would be easy to integrate what @fragmuffin has in cqparts into CadQuery. Ideally, I guess a lossless format would be preferred. Supported three.js loaders can be seen in the three.js examples page.

I do not know much about formats, sorry. 😂