Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Integrate sphinxcadquery to visualize 3D parts #111

Merged
merged 5 commits into from
Aug 18, 2020

Conversation

Peque
Copy link
Contributor

@Peque Peque commented Feb 26, 2019

@jmwright
Copy link
Member

@Peque Very cool. Great to see people using PeerTube as well.

@adam-urbanczyk
Copy link
Member

@Peque thanks!

@codecov
Copy link

codecov bot commented Feb 26, 2019

Codecov Report

Merging #111 into master will not change coverage.
The diff coverage is 100.00%.

Impacted file tree graph

@@           Coverage Diff           @@
##           master     #111   +/-   ##
=======================================
  Coverage   93.58%   93.58%           
=======================================
  Files          25       25           
  Lines        5316     5316           
  Branches      554      554           
=======================================
  Hits         4975     4975           
  Misses        215      215           
  Partials      126      126           
Impacted Files Coverage Δ
cadquery/occ_impl/exporters/__init__.py 92.70% <100.00%> (ø)

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 5ad5fdf...7f02429. Read the comment docs.

@Peque
Copy link
Contributor Author

Peque commented Feb 26, 2019

Both issues are closed now, but read:

CadQuery/sphinxcadquery#8

Feel free to merge/close this. If any of you know (or want to learn) CSS and want to take on that issue, I would gladly accept a pull request! 😜

It is unlikely that I will work on that issue myself in the short (or maybe even long) term. 😇

@jmwright
Copy link
Member

@Peque Sorry that this has been left sitting for so long. If I'm reading issue #8 from your fork correctly, this will break our ReadTheDocs theme (not badly, but still broken). There's also an issue of the patch breaking if the theme receives an update. Is that correct?

Themes could change and patches would break. Also, some themes can be affected by the patches.
The Read the Docs theme, for example, would lose its "gray" right column, which would become white instead, just like the text/content background.

Also, it sounds like the viewer is not working correctly at mobile device screen sizes.

You've been using this for your own project for awhile. What are your thoughts now on us using it for our Read The Docs implementation?

@Peque
Copy link
Contributor Author

Peque commented Dec 18, 2019

@jmwright Don't worry. This can stay idle until either:

  • You decide that having interactive 3D views in the examples is worth the downsides/risks (i.e.: slightly broken theme, broken display in mobile devices)
  • I, or someone else fixes sphinxcadquery's issues

So basically, you are correct. 😄

My thoughts are that 3D is cool enough, but that may be only because:

  • I would not really browse CadQuery's documentation on my phone
  • Maybe I am being selfish too, since having my project deployed in more places increases the chances of someone contributing a fix for those issues (they are at least fixable and there is documentation to do it).

If you do not want to integrate this (I would understand that), I think it would be good to leave the PR open anyways. This way, if someone wants to take on #105, they have a starting point.

@rowanG077
Copy link

What's the status of this? I would like to use this for quite some time. What is blocking this?

@Peque
Copy link
Contributor Author

Peque commented Jul 20, 2020

I just rebased this MR and fixed CadQuery/sphinxcadquery#8 (in master, I did not make a new release, so if you want to try it out remember to use the latest development version of sphinxcadquery).

However, it seems 3D pieces are not showing up. There seems to be something broken when exporting to TJS from CadQuery or when loading these files from sphinxcadquery. If someone can have a look at it, that would be great. I do not think I will find time to fix that soon. 😇

I also quickly tried with AMF, but the result is the same: no 3D objects shown. If I replace the CadQuery exported AMFs with a rook, then the rook is displayed. So maybe something is broken with AMF exporting too or maybe I am just exporting it wrong... 😂

@Peque
Copy link
Contributor Author

Peque commented Jul 20, 2020

@adam-urbanczyk It seems the OCP support resulted in some changes in the exported files.

Doing a Git bisect:

The exported TJS of this part:

result = cadquery.Workplane("front").box(2.0, 2.0, 0.5)

Used to look like this:

{
    "metadata" :
    {
        "formatVersion" : 3,
        "generatedBy"   : "ParametricParts",
        "vertices"      : 24,
        "faces"         : 12,
        "normals"       : 0,
        "colors"        : 0,
        "uvs"           : 0,
        "materials"     : 1,
        "morphTargets"  : 0
    },

    "scale" : 1.0,

    "materials": [    {
    "DbgColor" : 15658734,
    "DbgIndex" : 0,
    "DbgName" : "Material",
    "colorAmbient" : [0.0, 0.0, 0.0],
    "colorDiffuse" : [0.6400000190734865, 0.10179081114814892, 0.126246120426746],
    "colorSpecular" : [0.5, 0.5, 0.5],
    "shading" : "Lambert",
    "specularCoef" : 50,
    "transparency" : 1.0,
    "vertexColors" : false
    }],

    "vertices": [-1.0, -1.0, -0.25, -1.0, -1.0, 0.25, -1.0, 1.0, 0.25, -1.0, 1.0, -0.25, 1.0, -1.0, -0.25, 1.0, -1.0, 0.25, 1.0, 1.0, 0.25, 1.0, 1.0, -0.25, -1.0, -1.0, -0.25, 1.0, -1.0, -0.25, 1.0, -1.0, 0.25, -1.0, -1.0, 0.25, -1.0, 1.0, -0.25, 1.0, 1.0, -0.25, 1.0, 1.0, 0.25, -1.0, 1.0, 0.25, -1.0, -1.0, -0.25, -1.0, 1.0, -0.25, 1.0, 1.0, -0.25, 1.0, -1.0, -0.25, -1.0, -1.0, 0.25, -1.0, 1.0, 0.25, 1.0, 1.0, 0.25, 1.0, -1.0, 0.25],

    "morphTargets": [],

    "normals": [],

    "colors": [],

    "uvs": [[]],

    "faces": [0, 3, 1, 2, 0, 0, 1, 3, 0, 5, 7, 6, 0, 5, 4, 7, 0, 9, 10, 8, 0, 8, 10, 11, 0, 14, 13, 12, 0, 14, 12, 15, 0, 17, 18, 16, 0, 16, 18, 19, 0, 22, 21, 20, 0, 22, 20, 23]
}

And now it looks like this:

{
    "metadata" :
    {
        "formatVersion" : 3,
        "generatedBy"   : "ParametricParts",
        "vertices"      : 24,
        "faces"         : 12,
        "normals"       : 0,
        "colors"        : 0,
        "uvs"           : 0,
        "materials"     : 1,
        "morphTargets"  : 0
    },

    "scale" : 1.0,

    "materials": [    {
    "DbgColor" : 15658734,
    "DbgIndex" : 0,
    "DbgName" : "Material",
    "colorAmbient" : [0.0, 0.0, 0.0],
    "colorDiffuse" : [0.6400000190734865, 0.10179081114814892, 0.126246120426746],
    "colorSpecular" : [0.5, 0.5, 0.5],
    "shading" : "Lambert",
    "specularCoef" : 50,
    "transparency" : 1.0,
    "vertexColors" : false
    }],

    "vertices": [-1.0, -1.0, -0.25, -1.0, -1.0, 0.25, -1.0, 1.0, -0.25, -1.0, 1.0, 0.25, 1.0, -1.0, -0.25, 1.0, -1.0, 0.25, 1.0, 1.0, -0.25, 1.0, 1.0, 0.25, -1.0, -1.0, -0.25, 1.0, -1.0, -0.25, -1.0, -1.0, 0.25, 1.0, -1.0, 0.25, -1.0, 1.0, -0.25, 1.0, 1.0, -0.25, -1.0, 1.0, 0.25, 1.0, 1.0, 0.25, -1.0, -1.0, -0.25, -1.0, 1.0, -0.25, 1.0, -1.0, -0.25, 1.0, 1.0, -0.25, -1.0, -1.0, 0.25, -1.0, 1.0, 0.25, 1.0, -1.0, 0.25, 1.0, 1.0, 0.25],

    "morphTargets": [],

    "normals": [],

    "colors": [],

    "uvs": [[]],

    "faces": [0, 2, 1, 3, 0, 2, 3, 4, 0, 6, 5, 7, 0, 6, 7, 8, 0, 12, 10, 9, 0, 12, 9, 11, 0, 16, 14, 13, 0, 16, 13, 15, 0, 20, 18, 17, 0, 20, 17, 19, 0, 24, 22, 21, 0, 24, 21, 23]
}

If you replace the new file with the old one then the part is correctly visualized in the docs.

Peek 2020-07-20 17-57

@Peque Peque mentioned this pull request Jul 28, 2020
@jmwright
Copy link
Member

jmwright commented Aug 4, 2020

@Peque You've been involved so I'm sure you're aware, but #420 should have fixed this issue.

@Peque
Copy link
Contributor Author

Peque commented Aug 4, 2020

@jmwright Thanks! I just rebased the PR. Have a look and tell me if it looks good to you (make sure to update to latest sphinxcadquery too). 😊

Some exported shapes look very rough by default (see the last one for example), but that seems to be because of the CadQuery's default tolerance. If the default tolerance is set to 0.001 instead of 0.1, it looks much nicer. Would it make sense to change that default?

@jmwright
Copy link
Member

jmwright commented Aug 5, 2020

@Peque Sorry for my ignorance. Are you running this in a cadquery conda environment? Are you just running ./build-docs.sh? I keep getting the following error, so I'm not doing something right.

  File "/home/jwright/anaconda3/envs/cadquery/lib/python3.7/site-packages/cadquery/cq_directive.py", line 93, in setup
    app.add_directive("cq_plot", cq_directive, True, (0, 2, 0), **options)
TypeError: add_directive() got an unexpected keyword argument 'height'

@marcus7070
Copy link
Member

@jmwright, that's the same error as #398, are you using sphinx 2.4?

@jmwright
Copy link
Member

jmwright commented Aug 5, 2020

I think I have a newer version. Isn't that what the following means? It's the same version number I get if I do sphinx-build --version.

$ pip install -U sphinx
Requirement already up-to-date: sphinx in /home/jwright/anaconda3/lib/python3.7/site-packages (3.1.2)

@Peque
Copy link
Contributor Author

Peque commented Aug 5, 2020

@jmwright I think Sphinx 3 should be fine.

It seems not, just try with:

pip install sphinx==2.4

Apparently cadquery.cq_directive is not compatible with Sphinx 3. If you remove cadquery.cq_directive from doc/conf.py you should be fine as well, since the directive is no longer used.

@jmwright
Copy link
Member

jmwright commented Aug 5, 2020

I got a little further after forcing version 2.4.

$ ./build-docs.sh 
Running Sphinx v2.4.0
/home/jwright/anaconda3/lib/python3.7/site-packages/sphinx/util/docutils.py:287: RemovedInSphinx30Warning: function based directive support is now deprecated. Use class based directive instead.
  RemovedInSphinx30Warning)
making output directory... done

Theme error:
sphinx_rtd_theme is no longer a hard dependency since version 1.4.0. Please install it manually.(pip install sphinx_rtd_theme)

So I did the pip install that the error message suggested and the docs seem to build now. I get these warnings though, I'm not sure if any of them matter.

WARNING: failed to import Workplane.rotateAndCopy
WARNING: failed to import BoxSelector
WARNING: failed to import BaseDirSelector
WARNING: failed to import DirectionNthSelector
WARNING: failed to import BinarySelector
WARNING: failed to import AndSelector
WARNING: failed to import SumSelector
WARNING: failed to import SubtractSelector
WARNING: failed to import InverseSelector
WARNING: failed to import BoxSelector
WARNING: failed to import BaseDirSelector
WARNING: failed to import DirectionNthSelector
WARNING: failed to import BinarySelector
WARNING: failed to import AndSelector
WARNING: failed to import SumSelector
WARNING: failed to import SubtractSelector
WARNING: failed to import InverseSelector
/home/jwright/anaconda3/lib/python3.7/site-packages/cadquery/cq.py:docstring of cadquery.Workplane.ellipse:10: WARNING: Unexpected indentation.
/home/jwright/anaconda3/lib/python3.7/site-packages/cadquery/cq.py:docstring of cadquery.Workplane.ellipse:11: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/jwright/anaconda3/lib/python3.7/site-packages/cadquery/cq.py:docstring of cadquery.Workplane.ellipse:16: WARNING: Unexpected indentation.
/home/jwright/anaconda3/lib/python3.7/site-packages/cadquery/cq.py:docstring of cadquery.Workplane.interpPlate:11: WARNING: Unexpected indentation.
/home/jwright/anaconda3/lib/python3.7/site-packages/cadquery/cq.py:docstring of cadquery.Workplane.interpPlate:12: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/jwright/anaconda3/lib/python3.7/site-packages/cadquery/cq.py:docstring of cadquery.Workplane.interpPlate:14: WARNING: Field list ends without a blank line; unexpected unindent.
/home/jwright/anaconda3/lib/python3.7/site-packages/cadquery/cq.py:docstring of cadquery.Workplane.wedge:5: WARNING: Field list ends without a blank line; unexpected unindent.
/home/jwright/anaconda3/lib/python3.7/site-packages/cadquery/cq.py:docstring of cadquery.Workplane.wedge:11: WARNING: Unexpected indentation.
/home/jwright/anaconda3/lib/python3.7/site-packages/cadquery/cq.py:docstring of cadquery.Workplane.wedge:12: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/jwright/anaconda3/lib/python3.7/site-packages/cadquery/occ_impl/shapes.py:docstring of cadquery.Wire.assembleEdges:6: WARNING: Unexpected indentation.
/home/jwright/anaconda3/lib/python3.7/site-packages/cadquery/selectors.py:docstring of cadquery.StringSyntaxSelector:36: WARNING: Inline substitution_reference start-string without end-string.
/home/jwright/anaconda3/lib/python3.7/site-packages/cadquery/selectors.py:docstring of cadquery.StringSyntaxSelector:36: WARNING: Inline substitution_reference start-string without end-string.
/home/jwright/anaconda3/lib/python3.7/site-packages/cadquery/selectors.py:docstring of cadquery.StringSyntaxSelector:40: WARNING: Inline substitution_reference start-string without end-string.
/home/jwright/Downloads/temp/cadquery/doc/installation.rst:11: WARNING: Title underline too short.

Anaconda or Miniconda (Python 3.x editions), Python 3.x
----------------------------------------------
/home/jwright/Downloads/temp/cadquery/doc/intro.rst:57: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/home/jwright/Downloads/temp/cadquery/doc/intro.rst:58: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/jwright/Downloads/temp/cadquery/doc/quickstart.rst:7: WARNING: duplicate object description of cadquery, other instance in classreference, use :noindex: for one of them
/home/jwright/Downloads/temp/cadquery/doc/quickstart.rst:12: WARNING: Title underline too short.

Prerequisites: Anaconda/Miniconda + CQ-editor running from an environment
==============================================================

@jmwright
Copy link
Member

jmwright commented Aug 5, 2020

@Peque Should you go ahead and remove cadquery.cq_directive so that this will work with Sphinx 3? Will that cause a conflict with master?

You rebased on cadquery master after the tessellation update, correct? I still don't see the model in the view in the generated docs.

Screenshot from 2020-08-05 11-47-25

@adam-urbanczyk
Copy link
Member

@jmwright please don't remove the old SVG rendering. If someone can fix it for sphinx 3 then great, if not I'd propose to leave it and stick with 2.4 (RTD supports custom sphinx version - we are currently building with 2.4).

@jmwright
Copy link
Member

jmwright commented Aug 5, 2020

@adam-urbanczyk Do you not want the old SVG rendering removed because of browser compatibility?

@Peque
Copy link
Contributor Author

Peque commented Aug 5, 2020

@adam-urbanczyk By removing it I just meant the line in the docs/config.py file. That is enough to fix Sphinx 3 compatibility when building the documentation with this PR. 😊

With this PR all cq_plot directives are replaced with the new 3D ones, so it would not be necessary. The code would still be there for future use and a possible fix/upgrade of the directive for Sphinx 3 compatibility.

@jmwright Yeah, you need to serve the local files. That means, you could call python3 -m http.server from the target/docs directory and see if it works that way. It may be possible to avoid this somehow, but did not have a look at it.

@adam-urbanczyk
Copy link
Member

@jmwright I want the SVG rendering kept to be able to generate pdf docs.

@Peque could you explain why the python3 -m http.server call is need?

@Peque
Copy link
Contributor Author

Peque commented Aug 6, 2020

@adam-urbanczyk Not really 🤷 . If you open the docs file directly with your browser and open your browser's console you will see some CORS policy errors when trying to load the local files.

As I said, it is probably fixable, but I am not sure how to do it. If someone can help with that, it would be great! 😇

@adam-urbanczyk
Copy link
Member

So is this PR going to work with readthedocs?

@Peque
Copy link
Contributor Author

Peque commented Aug 9, 2020

@adam-urbanczyk I think you should be able to try that by enabling autobuild documentation for PRs. 😊

@Peque
Copy link
Contributor Author

Peque commented Aug 9, 2020

@adam-urbanczyk I tried it and it seems to work just fine:

https://cadquerytest.readthedocs.io/en/sphinxcadquery-nocqdirective/examples.html

However, I needed to push this commit, not sure why readthedocs was not using Sphinx 2.4 as specified in the .readthedocs.yaml config file. 🤷 If you do not mind, and since the cq_plot directive is not currently being used, I could push that commit to this PR too.

@adam-urbanczyk
Copy link
Member

Closed/reopened o trigger readthedocs build.

@adam-urbanczyk
Copy link
Member

@Peque thanks. The issue you are referring to is with readthedocs conf - I remember I had to contact their staff to enable defining sphinx version form the conda env. I did enable the readthedocs builds as you can see above and it looks indeed very nice in most of the cases. For more complicated objects I see some distortions though (below). Do you know what could cause them?
obraz

@Peque
Copy link
Contributor Author

Peque commented Aug 17, 2020

@adam-urbanczyk Yeah, that is just the result of the tessellation.

As mentioned in #111 (comment):

Some exported shapes look very rough by default (see the last one for example), but that seems to be because of the CadQuery's default tolerance. If the default tolerance is set to 0.001 instead of 0.1, it looks much nicer. Would it make sense to change that default?

What do you think? Lower tolerance by default may be the expected behavior by the end-user (i.e.: prefer quality over file size by default). But maybe not? 🤷

@rowanG077
Copy link

@Peque Is it not possible to make that configureable in the sphinx config? That way a user can specify the accuracy he/she wants.

@adam-urbanczyk
Copy link
Member

@Peque with the new defaults it looks much better, but some artifacts remain. Would you know how to change the angular tolerance for edge detection in three.js ?
obraz

@Peque
Copy link
Contributor Author

Peque commented Aug 18, 2020

@adam-urbanczyk Here:

https://github.com/Peque/sphinxcadquery/blob/master/sphinxcadquery/sphinxcadquerystatic/main.js#L51

It is set to 15 degrees now. That could be increased by default or parameterized, but 15 sounded as lenient enough to me. 🤷

@Peque
Copy link
Contributor Author

Peque commented Aug 18, 2020

@Peque Is it not possible to make that configureable in the sphinx config? That way a user can specify the accuracy he/she wants.

@rowanG077 Sure! Pull requests are welcome. 😜

@adam-urbanczyk
Copy link
Member

@Peque I changed the default angular tolerance of toString to 0.05 [rad] (~3 deg) and the artifacts are completely gone. As far as I'm concerned it is good enough. Shall I merge this PR @jmwright ?

@jmwright
Copy link
Member

@adam-urbanczyk +1 on merge

@adam-urbanczyk
Copy link
Member

Thanks for the contribution @Peque , the docs look way cooler now.

@adam-urbanczyk adam-urbanczyk merged commit c7b7e95 into CadQuery:master Aug 18, 2020
@jmwright
Copy link
Member

Yes, thank you @Peque

@jmwright
Copy link
Member

Is anyone else having a problem with this page bogging their browser down now?

https://cadquery.readthedocs.io/en/latest/examples.html

@Peque
Copy link
Contributor Author

Peque commented Aug 18, 2020

@jmwright In my case I can feel the browser struggling a couple of seconds on load. Then it all feels smooth. But that may depend on your device of course (mine is a good laptop from 8 years ago: i7-2670QM @ 2.2GHz and 8 GB DDR3 1333 RAM). Maybe performance is really hurt on mobile devices (?).

Your internet connection speed may impact performance too, since there are many examples and maybe now, with the higher tolerance, some of them weight significantly more.

Performance could maybe be improved on sphinxcadquery side: CadQuery/sphinxcadquery#18

Also, maybe the examples section could be divided to avoid some load.

@adam-urbanczyk
Copy link
Member

adam-urbanczyk commented Aug 18, 2020

@jmwright It takes a moment to load, but after that it works fine (on my desktop PC).

@Peque
Copy link
Contributor Author

Peque commented Aug 19, 2020

@jmwright Maybe open a separate issue to discuss it?

@rowanG077
Copy link

Works perfectly fine. It does take a while to load. But once it does it's fine for me. I run on an laptop with an Intel-7660u CPU. It's a couple of years old now.

@jmwright
Copy link
Member

The page eventually loads for me, but Firefox keeps telling me that a script is slowing things down and asking me if I want to kill it. Both laptops I've tested on are within 1-1/2 years old and have decent specs.

I've opened an issue to discuss: #441

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3D rendering in the online documentation
5 participants