Metadata-Version: 2.1
Name: jupyterscad
Version: 0.3.0
Summary: Solid 3D Cad (SCAD) renderer and viewer for Jupyter
Author: Jennifer Reiber Kyle
License: GPLv3
Project-URL: Homepage, https://jreiberkyle.github.io/jupyterscad/
Project-URL: Documentation, https://jreiberkyle.github.io/jupyterscad/
Project-URL: Repository, https://github.com/jreiberkyle/jupyterscad
Project-URL: Changelog, https://github.com/jreiberkyle/jupyterscad/blob/main/CHANGELOG.md
Keywords: openscad,scad,jupyter,jupyterlab,notebook,viewer,render,solidpython,solidpython2
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: COPYING
Requires-Dist: numpy-stl
Requires-Dist: ipywidgets
Requires-Dist: pythreejs
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: solidpython2; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs<2; extra == "docs"
Requires-Dist: mkdocs-material<10; extra == "docs"
Requires-Dist: mkdocstrings-python; extra == "docs"

# Jupyter SCAD: SCAD in Jupyter


Jupyter SCAD provides rendering and interactive visualization for 3D objects described in [SolidPython2](https://github.com/jeff-dh/SolidPython) within a Jupyter notebook. Additionally, it provides interactive visualization for STLs.

This program is focused on the use case of generating stl files with Python (aka SolidPython2) interactively within a Jupyter notebook.

## Documentation

Documentation is hosted at https://jreiberkyle.github.io/jupyterscad/.

## Quick Start

Jupyter SCAD can be installed with `pip`:

```console
pip install jupyterscad
```

An OpenSCAD object can be defined using SolidPython2, viewed in a Jupyter
notebook, and saved to an `stl` file with:

```python
from jupyterscad import view
from solid2 import cube

view(cube([1.5,2,1],center=True), outfile='cube.stl')
```

![render example](https://github.com/jreiberkyle/jupyterscad/blob/main/images/render_cube.png?raw=True)

## Alternatives

As an alternative to Jupyter SCAD, one could use a Jupyter notebook as an external editor, using SolidPython2 to update the SCAD file and OpenSCAD to visualize and render the SCAD file.
The benefit to this approach is that one can visualize the preview. The drawback is that the two-program workflow can feel distracting.
See more on using external editors for OpenSCAD [here](https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Using_an_external_Editor_with_OpenSCAD).

Or, one can use [ViewSCAD](https://github.com/nickc92/ViewSCAD), which was the motivation for this project. However the last time ViewSCAD was updated was 2019 (checked on 9/21/2023). It only supports SolidPython, not SolidPython2.

## Transitioning from ViewSCAD

This package was inspired by [ViewSCAD](https://github.com/nickc92/ViewSCAD) and therefore
maintains a very similar interface.

To transition from ViewSCAD, replace
```python
import viewscad

r = viewscad.Renderer()
r.render(obj)
```

with
```python
from jupyterscad import view

view(obj)
```

## Visualization Backend

This package uses [pythreejs](https://pythreejs.readthedocs.io/) for visualization.

Alternatives considered, ordered from closest fit to farthest:
- [pyvolume](https://pyvolume.readthedocs.io/): provides mesh visualization and interaction but (as of 2023.09.24) the latest release is alpha and documentation is sparse.
- [matplotlib mplot3d](https://matplotlib.org/2.2.2/mpl_toolkits/mplot3d/faq.html#toolkit-mplot3d-faq): provides mesh visualization and interaction but is slow.
- [pyvista](https://pyvista.org/): provides stl loading and visualization but visualization does not work in docker image.

## Acknowledgements

Thanks to [nickc92](https://github.com/nickc92) for creating [ViewSCAD](https://github.com/nickc92/ViewSCAD), which is the inspiration for this project.
