Refactor Shader interface and set up documentation (#9)

* Update README.md with CI badge * Add docs * Update docs * Update shaders * Format shaders and docs * Update shaders * Clean up * Fix light_direction and base_style configuration * Update example to fit new api * Implement ABC * Update to new non-base shader * Continue adding docs * Add svgwrite to conf.py * Docs for main package * Update conf.py * Update doc code * Continue documentation * Format example.py * Move images to _static * Document most methods in the main package * Update RST files and README * Fix doctest config * Add logos * Update docs * Add logos in correct photo * Remove duplicate files * Update version to 0.1.0
janbridley · Nov 27, 2024 · 8ef64c1 · 8ef64c1
1 parent 414d6da
commit 8ef64c1
Show file tree

Hide file tree

Showing 41 changed files with 1,429 additions and 94 deletions.
diff --git a/1AI0.mtl b/1AI0.mtl
@@ -0,0 +1,128 @@
+newmtl 0x4259ff1
+illum 2
+Ns 163
+Ni 0.001
+Ka 0 0 0
+Kd 0.259 0.349 1
+Ks 0.25 0.25 0.25
+d 1
+newmtl 0x1b9e771
+illum 2
+Ns 163
+Ni 0.001
+Ka 0 0 0
+Kd 0.106 0.62 0.467
+Ks 0.25 0.25 0.25
+d 1
+newmtl 0xff26181
+illum 2
+Ns 163
+Ni 0.001
+Ka 0 0 0
+Kd 1 0.149 0.094
+Ks 0.25 0.25 0.25
+d 1
+newmtl 0xffffff1
+illum 2
+Ns 163
+Ni 0.001
+Ka 0 0 0
+Kd 1 1 1
+Ks 0.25 0.25 0.25
+d 1
+newmtl 0xffff3e1
+illum 2
+Ns 163
+Ni 0.001
+Ka 0 0 0
+Kd 1 1 0.243
+Ks 0.25 0.25 0.25
+d 1
+newmtl 0xd95f021
+illum 2
+Ns 163
+Ni 0.001
+Ka 0 0 0
+Kd 0.851 0.373 0.008
+Ks 0.25 0.25 0.25
+d 1
+newmtl 0x7570b31
+illum 2
+Ns 163
+Ni 0.001
+Ka 0 0 0
+Kd 0.459 0.439 0.702
+Ks 0.25 0.25 0.25
+d 1
+newmtl 0xe7298a1
+illum 2
+Ns 163
+Ni 0.001
+Ka 0 0 0
+Kd 0.906 0.161 0.541
+Ks 0.25 0.25 0.25
+d 1
+newmtl 0x66a61e1
+illum 2
+Ns 163
+Ni 0.001
+Ka 0 0 0
+Kd 0.4 0.651 0.118
+Ks 0.25 0.25 0.25
+d 1
+newmtl 0xe6ab021
+illum 2
+Ns 163
+Ni 0.001
+Ka 0 0 0
+Kd 0.902 0.671 0.008
+Ks 0.25 0.25 0.25
+d 1
+newmtl 0xa6761d1
+illum 2
+Ns 163
+Ni 0.001
+Ka 0 0 0
+Kd 0.651 0.463 0.114
+Ks 0.25 0.25 0.25
+d 1
+newmtl 0x6666661
+illum 2
+Ns 163
+Ni 0.001
+Ka 0 0 0
+Kd 0.4 0.4 0.4
+Ks 0.25 0.25 0.25
+d 1
+newmtl 0xe41a1c1
+illum 2
+Ns 163
+Ni 0.001
+Ka 0 0 0
+Kd 0.894 0.102 0.11
+Ks 0.25 0.25 0.25
+d 1
+newmtl 0x377eb81
+illum 2
+Ns 163
+Ni 0.001
+Ka 0 0 0
+Kd 0.216 0.494 0.722
+Ks 0.25 0.25 0.25
+d 1
+newmtl 0x4daf4a1
+illum 2
+Ns 163
+Ni 0.001
+Ka 0 0 0
+Kd 0.302 0.686 0.29
+Ks 0.25 0.25 0.25
+d 1
+newmtl 0x984ea31
+illum 2
+Ns 163
+Ni 0.001
+Ka 0 0 0
+Kd 0.596 0.306 0.639
+Ks 0.25 0.25 0.25
+d 1
diff --git a/README.md b/README.md
@@ -15,6 +15,7 @@ Many thanks to the [Keenan 3D Model repository](https://www.cs.cmu.edu/~kmcrane/
 
 [![GitHub Actions](https://github.com/janbridley/svg3d/actions/workflows/run-pytest.yaml/badge.svg)](https://github.com/janbridley/svg3d/actions)
 
+
 ## Installation
 
 ```bash

diff --git a/README.rst b/README.rst
@@ -0,0 +1,169 @@
+.. container:: row
+
+   .. image:: _static/cube-wireframe.svg
+      :alt: Cube Wireframe
+      :width: 17%
+
+   .. image:: _static/cycle-compact.svg
+      :alt: Alternation Cycle
+      :width: 17%
+
+   .. image:: _static/CrumpledDevelopable-tri-compact.svg
+      :alt: Keenan CrumpledDevelopable
+      :width: 17%
+
+   .. image:: _static/oloid_64-tri-compact.svg
+      :alt: Keenan Oloid
+      :width: 17%
+
+   .. image:: _static/bunny-tri-compact.svg
+      :alt: Stanford Bunny
+      :width: 17%
+
+
+
+SVG3D was designed to bridge the gap between raytraced rendering engines like Blender and plotting tools like matplotlib and plotly. Common computer graphics techniques and models have been adapted to work within the counstraints of vector art, an approach that enables users to generate compact, scalable images with realistic shading.
+
+A reimagining of the excellent `original library <https://prideout.net/blog/svg_wireframes/#using-the-api>`_ with the same name, this version has many new features, a more general interface, and a somewhat different scope. We aim to streamline the process of rendering scenes of geometries for scientific publications, although the libary is useful for a diverse array of applications.
+
+Many thanks to the `Keenan 3D Model repository <https://www.cs.cmu.edu/~kmcrane/Projects/ModelRepository/>`_ and the `Georgia Tech Large Models Archive <https://sites.cc.gatech.edu/projects/large_models/>`_ for the models rendered in the header image.
+
+.. image:: https://github.com/janbridley/svg3d/actions/workflows/run-pytest.yaml/badge.svg
+   :target: https://github.com/janbridley/svg3d/actions
+
+.. _installing:
+
+Installation
+============
+
+`svg3d` is not yet available via PyPI or Conda Forge. While this is the case, please
+build from source to install the package.
+
+.. code-block:: bash
+
+   # Clone the repository
+   git clone https://github.com/janbridley/svg3d.git
+   cd svg3d
+
+   # Install to your python environment!
+   python -m pip install .
+
+
+Quickstart Example
+==================
+
+`svg3d` provides convenience `View` options for standard rendering perspectives - isometric, dimetric, and trimetric. Shapes can be easily created from coxeter objects, or from raw mesh data.
+
+.. code-block:: python
+
+   from coxeter.families import ArchimedeanFamily
+   import svg3d
+
+   style = {
+       "fill": "#00B2A6",
+       "fill_opacity": "0.85",
+       "stroke": "black",
+       "stroke_linejoin": "round",
+       "stroke_width": "0.005",
+   }
+
+   truncated_cube = ArchimedeanFamily.get_shape("Truncated Cube")
+
+   scene = [
+       svg3d.Mesh.from_coxeter(
+           truncated_cube, style=style, shader=svg3d.shaders.diffuse_lighting
+       )
+   ]
+
+   # Convenience views: isometric, dimetric, and trimetric
+   iso = svg3d.View.isometric(scene, fov=1.0)
+   dim = svg3d.View.dimetric(scene, fov=1.0)
+   tri = svg3d.View.trimetric(scene, fov=1.0)
+
+   for view, view_type in zip([iso, dim, tri], ["iso", "dim", "tri"]):
+       svg3d.Engine([view]).render(f"{view_type}.svg")
+
+.. list-table:: 
+   :header-rows: 1
+
+   * - Isometric
+     - Dimetric
+     - Trimetric
+   * - .. image:: _static/iso.svg
+     - .. image:: _static/dim.svg
+     - .. image:: _static/tri.svg
+
+.. _usage:
+
+Usage Example
+=============
+
+In addition to convenience methods, `svg3d` allows full control over the viewport, scene geometry, image style, and shaders. Methods are based on OpenGL standards and nomenclature where possible, and images can be created from any set of vertices and faces - even from ragged arrays! Simply pass an array of vertices and a list of arrays (one for vertex indices of each face, as below) to `svg3d.Mesh.from_vertices_and_faces` to render whatever geometry you like. Custom shader models can be implemented as a callable that takes a face index and a `svg3d.Mesh` object to shade.
+
+.. code-block:: python
+
+   import numpy as np
+   import svg3d
+
+   # Define the vertices and faces of a cube
+   vertices = np.array(
+       [[-1., -1., -1.],
+       [-1., -1.,  1.],
+       [-1.,  1., -1.],
+       [-1.,  1.,  1.],
+       [ 1., -1., -1.],
+       [ 1., -1.,  1.],
+       [ 1.,  1., -1.],
+       [ 1.,  1.,  1.]]
+   )
+
+   faces = [
+       [0, 2, 6, 4],
+       [0, 4, 5, 1],
+       [4, 6, 7, 5],
+       [0, 1, 3, 2],
+       [2, 3, 7, 6],
+       [1, 5, 7, 3]
+   ]
+
+   # Set up our rendering style - transparent white gives a nice wireframe appearance
+   style = {
+       "fill": "#FFFFFF",
+       "fill_opacity": "0.75",
+       "stroke": "black",
+       "stroke_linejoin": "round",
+       "stroke_width": "0.005",
+   }
+
+   empty_shader = lambda face_index, mesh: {} # Does nothing, but illustrates the shader API
+
+   pos_object = [0.0, 0.0, 0.0]  # "at" position
+   pos_camera = [40, 40, 120]  # "eye" position
+   vec_up = [0.0, 1.0, 0.0]  # "up" vector of camera. This is the default value.
+
+   z_near, z_far = 1.0, 200.0
+   aspect = 1.0  # Aspect ratio of the view cone
+   fov_y = 2.0  # Opening angle of the view cone. fov_x is equal to fov_y * aspect
+
+   look_at = svg3d.get_lookat_matrix(pos_object, pos_camera, vec_up=vec_up)
+   projection = svg3d.get_projection_matrix(
+       z_near=z_near, z_far=z_far, fov_y=fov_y, aspect=aspect
+   )
+
+   # A "scene" is a list of Mesh objects, which can be easily generated from raw data
+   scene = [
+       svg3d.Mesh.from_vertices_and_faces(vertices, faces, style=style, shader=empty_shader)
+   ]
+
+   view = svg3d.View.from_look_at_and_projection(
+       look_at=look_at,
+       projection=projection,
+       scene=scene,
+   )
+
+   svg3d.Engine([view]).render("cube-wireframe.svg")
+
+Running the code above generates the following image:
+
+.. image:: _static/cube-wireframe.svg
+
diff --git a/doc/Makefile b/doc/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/doc/make.bat b/doc/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/doc/requirements.in b/doc/requirements.in
@@ -0,0 +1,4 @@
+autodocsumm
+furo
+numpy
+sphinx
Original file line number	Diff line number	Diff line change
Expand Up		@@ -15,6 +15,7 @@ Many thanks to the [Keenan 3D Model repository](https://www.cs.cmu.edu/~kmcrane/

		[![GitHub Actions](https://github.com/janbridley/svg3d/actions/workflows/run-pytest.yaml/badge.svg)](https://github.com/janbridley/svg3d/actions)


		## Installation

		```bash
Expand Down