PNG, SVG or Both in Documentation?

[jmwright]

During the hackathon we were limited to SVG output (outlines and hidden lines only). After seeing the renders on the field dissection microscope (a variant of the OpenFlexure microscope) on Experiment.com, I developed a Gist that provides a method of outputting similar PNG renders from CadQuery.

I have two questions:

1. Do we want to incorporate PNG export in the auto-documentation?
2. If so, how do we want to incorporate it?

We could use a mix of SVG and PNG depending on the situation (SVG for views where hidden lines need to be seen, or with exploded views listing the parts). We could also just decide to use one or the other.

The Gist I provided above is not complete (no camera or image size control), but I can push it forward and work on getting it integrated into CadQuery if there is interest.

[julianstirling]

While I think that SVG should be universal, I have seen more website viewing issues with SVG, so I think PNG is great.

I don't understand the technicalities enough about the hidden lines. Is there a reason the means that hidden lines will be seen differently if we choose PNG over SVG? If so, do you have and example of the differences?

[jmwright]

@julianstirling I'm using the VTK library that OpenCASCADE is usually paired with to export the PNG images, and I haven't seen anything that would allow hidden lines to be included in those renders. So the rendering of the PNG will only show the outside faces of the object (at least for now), whereas with SVG export I can request to see hidden interior lines. However, the SVG export won't show shaded faces the way the PNG images will, so there are pros and cons to each type of export.

Hidden line example in SVG: https://codeberg.org/7BIndustries/poc-stereoscope/raw/branch/main/docs/images/stereoscope_center_piece_with_screws_in_assembly_exploded_annotated_side_view.svg

The PNG exports will look similar to your dissection microscope images I linked above.

[jmwright]

I generated a few sample images in both PNG and SVG format to help illustrate the differences. I got the views as close as I could, but the camera settings between the PNG and SVG renderers are not 1-to-1. The renders are of a simple assembly with two cubes in it, and the camera is set to Y-up in the exports because that is the default with SVG. The PNG export Gist has been updated with both camera and image size control (as well as a parallel projection toggle).

SVG with Hidden Lines

SVG without Hidden Lines

PNG

Screenshot of Assembly from CQ-editor for Reference

[drayde]

I vote for having both options :-)

[jmwright]

I think this question has been answered, and the work is being tracked in #34 . Closing.