Feature/additional geometry file export methods

[josephburkhart]

Description

I have added a some methods to the shapes.Polyhedron class to allow users to export 3D geometry to a handful of common file formats. None of these methods introduce additional dependencies. The following file formats would be supported:

• .obj Wavefront OBJ
• .off Object File Format
• .stl Stereolithography
• .ply Polygon File Format
• .x3d Extensible 3D
• .vtk Legacy VTK
• .html HTML (embedded X3D in a simple HTML document)

Note: this is a DRAFT PULL REQUEST. With input from other collaborators, I may still make significant changes to the new methods.

Motivation and Context

This change could make it significantly easier for users to visualize their geometries and export them for rendering and other publication-related tasks. Currently, users have to hack together their own export functions if they want to export their geometries to, say, blender.

Types of Changes

• Documentation update
• Bug fix
• New feature
• Breaking change¹

¹The change breaks (or has the potential to break) existing functionality.

Checklist:

• I am familiar with the Contributing Guidelines.
• I agree with the terms of the Contributor Agreement.
• The changes introduced by this pull request are covered by existing or newly introduced tests.
• I have updated the changelog and the credits.

[josephburkhart]

Planning to start drafting some tests tomorrow.

[josephburkhart]

In a conversation offline, @janbridley suggested putting this functionality in a separate file, rather than attaching it via methods to the shapes.Polyhedron class.

Currently, the implementation only works for polyhedrons, because it requires explicitly defined vertices and faces. If we put export functions into a separate file, it may be reasonable to allow them to accept any subclass of shapes.Shape3D. If we wanted to do that, we would need a way to generate vertices and faces to approximate the surfaces of shapes.Ellipsoid and shapes.Sphere. If any folks have suggestions on previous implementations of such calculations in coxeter's current dependencies, I'd appreciate it. I could implement such calculations myself, but I expect someone else has already done this.

[janbridley]

In a conversation offline, @janbridley suggested putting this functionality in a separate file, rather than attaching it via methods to the shapes.Polyhedron class.

Currently, the implementation only works for polyhedrons, because it requires explicitly defined vertices and faces. If we put export functions into a separate file, it may be reasonable to allow them to accept any subclass of shapes.Shape3D. If we wanted to do that, we would need a way to generate vertices and faces to approximate the surfaces of shapes.Ellipsoid and shapes.Sphere. If any folks have suggestions on previous implementations of such calculations in coxeter's current dependencies, I'd appreciate it. I could implement such calculations myself, but I expect someone else has already done this.

As a simpler alternative, we could have the export code in a separate file that is called as aPolyhedron method. This gets us the development and maintenance benefits without requirements additional approximations for rounded shapes. If those approximations are something we wanted, then this approach seems perfect. I do know that mesh approximations of concave curved shapes were brought up offline recently, although generalizations of this sort are nontrivial.

[josephburkhart]

pre-commit.ci autofix

[janbridley]

This is a nice little snippet

[janbridley]

Consider rewriting this with numpy functions - ravel, etc. Should be possible to simplify!

[josephburkhart]

@janbridley all the tests are now passing, thanks to @joaander 's help. As the code currently stands, we would need to re-generate the control files with every version release, since the export functions include the coxeter version number in some of the files. There's an if __name__ == "__main__" block in tests/test_io.py that generates new control files, so a call to this file would need to be added to the version release workflow. If that sounds like too much of a hassle, I could add in some functionality that ignores coxeter version numbers during the file comparison check, but this might complicate adding support for new file formats in the future.

[janbridley]

Looks good! Thank you for this

[janbridley]

@janbridley all the tests are now passing, thanks to @joaander's help. As the code currently stands, we would need to re-generate the control files with every version release, since the export functions include the coxeter version number in some of the files. There's an if __name__ == "__main__" block in tests/test_io.py that generates new control files, so a call to this file would need to be added to the version release workflow. If that sounds like too much of a hassle, I could add in some functionality that ignores coxeter version numbers during the file comparison check, but this might complicate adding support for new file formats in the future.

It should be fairly simple to automate running that file with the CI. I'll add this in the next release PR. I think the comparison function is good for now, and we can always replace the contents of that function in the future for more detailed/version-agnostic feedback.