Organize projects into folders with READMEs and preview renders.

Move the Ring solar siding adapter into its own directory, add repo and project documentation, and introduce a preview script (OpenSCAD+xvfb or PyVista fallback) for catalog images.
2026-06-13 17:09:11 -04:00
parent 31e750b4d8
commit 5d15a1fd82
6 changed files with 349 additions and 0 deletions
@@ -0,0 +1,79 @@
+# OpenSCAD Projects
+
+Parametric 3D-printable parts designed in [OpenSCAD](https://openscad.org/). Each project lives in its own folder with a `.scad` source file, a `README.md`, and a `preview.png` render.
+
+Designs are tuned for FDM printing on a **Bambu Lab P2S** (256 × 256 × 256 mm build volume).
+
+## Requirements
+
+- [OpenSCAD](https://openscad.org/downloads.html) 2021.01 or newer (tested with the Customizer UI)
+- A slicer for your printer (e.g. Bambu Studio)
+
+Most models here use **vanilla OpenSCAD** only. Future projects may use [BOSL2](https://github.com/BelfrySCAD/BOSL2); see `.cursor/skills/openscad-bosl2/` for house-style conventions when working with that library.
+
+## Quick start
+
+1. Clone the repo and open a project's `.scad` file in OpenSCAD.
+2. Adjust parameters in the **Customizer** panel (View → Customizer).
+3. Press **F6** to render, then **File → Export → Export as STL**.
+4. Slice and print. Generated `.stl` files are gitignored; export locally as needed.
+
+## Projects
+
+| Preview | Project | Description |
+|---------|---------|-------------|
+| ![Ring Solar Siding Adapter](ring-solar-siding-adapter/preview.png) | [ring-solar-siding-adapter](ring-solar-siding-adapter/) | Adapter plate to mount a Ring Solar Charger on horizontal beaded vinyl lap siding |
+
+## Preview images
+
+OpenSCAD can export **PNG** previews from the command line when OpenGL is available (local GUI, or headless via `xvfb-run`):
+
+```bash
+openscad --render --viewall --imgsize=1200,900 \
+  -o ring-solar-siding-adapter/preview.png \
+  ring-solar-siding-adapter/ring-solar-siding-adapter.scad
+```
+
+OpenSCAD does **not** export JPG natively; convert PNG if needed.
+
+**Headless WSL / CI** — install PyVista for the script's fallback renderer (smooth shaded, no wireframe):
+
+```bash
+pip install pyvista
+python3 scripts/render-preview.py ring-solar-siding-adapter
+```
+
+**Best quality (native OpenSCAD look)** — install a virtual display so OpenSCAD can export PNG directly:
+
+```bash
+sudo apt install xvfb
+python3 scripts/render-preview.py ring-solar-siding-adapter
+```
+
+The script tries OpenSCAD + `xvfb-run` first, then falls back to PyVista.
+
+## Repository layout
+
+```
+openscad-projects/
+├── README.md
+├── AGENTS.md
+├── .gitignore                         # Ignores exported *.stl files
+├── scripts/
+│   └── render-preview.py              # Headless preview generator
+└── <project-name>/
+    ├── README.md                      # Purpose, parameters, workflow
+    ├── preview.png                    # Catalog render (committed)
+    ├── <project-name>.scad            # Parametric source
+    └── *.backup.scad                  # Optional design checkpoints
+```
+
+When adding a new project, create a kebab-case folder, add a single primary `.scad` file, write a README describing purpose and parameters, and generate a preview.
+
+## Printer
+
+Designs target a **Bambu Lab P2S**. Build volume and material notes live in [`.cursor/skills/openscad-bosl2/references/bambu-p2s.md`](.cursor/skills/openscad-bosl2/references/bambu-p2s.md). Parts from this repo should fit within 256 × 256 × 256 mm unless noted otherwise.
+
+## License
+
+No license file is included yet. Add one before publishing or sharing models externally.