Endblay Opslay

.github/workflows/blender-tests.yml

@@ -37,10 +37,10 @@ jobs:
           $BLENDER_PYTHON -m pip --version
 
           # Install dependencies
-          $BLENDER_PYTHON -m pip install numpy opencv-python Pillow scipy
+          $BLENDER_PYTHON -m pip install -r blender_blocking/requirements.txt
 
           # Verify installation
-          $BLENDER_PYTHON -c "import numpy, cv2, PIL, scipy; print('Dependencies installed')"
+          $BLENDER_PYTHON -c "import numpy, cv2, PIL, scipy, skimage, open3d; print('Dependencies installed')"
 
       - name: Run test suite
         run: |
@@ -76,8 +76,8 @@ jobs:
         run: |
           BLENDER_PYTHON=$(blender --background --python-expr "import sys; print(sys.executable)" 2>&1 | grep -oP '/[^ ]+python[0-9.]*' | head -1)
           echo "Blender Python: $BLENDER_PYTHON"
-          $BLENDER_PYTHON -m pip install numpy opencv-python Pillow scipy
-          $BLENDER_PYTHON -c "import numpy, cv2, PIL, scipy; print('Dependencies installed')"
+          $BLENDER_PYTHON -m pip install -r blender_blocking/requirements.txt
+          $BLENDER_PYTHON -c "import numpy, cv2, PIL, scipy, skimage, open3d; print('Dependencies installed')"
 
       - name: Run test suite
         run: |
@@ -107,7 +107,7 @@ jobs:
       - name: Install dependencies
         run: |
           BLENDER_PYTHON=$(blender --background --python-expr "import sys; print(sys.executable)" 2>&1 | grep -oP '/[^ ]+python[0-9.]*' | head -1)
-          $BLENDER_PYTHON -m pip install numpy opencv-python Pillow scipy
+          $BLENDER_PYTHON -m pip install -r blender_blocking/requirements.txt
 
       - name: Run quick tests
         run: |

.gitignore

@@ -13,12 +13,17 @@ stacked_cubes.py
 __pycache__/
 *.py[cod]
 *$py.class
+.venv/
+.venv*/
+venv/
 
 # Blender temp files
 *.blend1
 *.blend2
 
 # Generated test artifacts
+temp/
+test_output/
 test_images/
 blender_blocking/test_images/
 blender_blocking/test_output/

blender_blocking/BLENDER_SETUP.md

@@ -4,7 +4,7 @@ Complete guide to configuring Blender's Python environment to use the blocking t
 
 ## The Challenge
 
-Blender bundles its own Python interpreter, which doesn't have access to your virtual environment by default. We need to make the dependencies (numpy, opencv-python, Pillow, scipy) available to Blender's Python.
+Blender bundles its own Python interpreter, which doesn't have access to your virtual environment by default. We need to make the dependencies (numpy, opencv-python, Pillow, scipy, scikit-image, and Open3D) available to Blender's Python.
 
 ## REQUIRED Setup: Install to Blender's Python
 
@@ -69,6 +69,8 @@ import numpy as np
 import cv2
 from PIL import Image
 import scipy
+import skimage
+import open3d
 
 print("✓ All dependencies available!")
 
@@ -122,9 +124,56 @@ Or install for user only:
 
 Version mismatch between numpy and Blender's Python. Install a compatible version:
 ```bash
-$BLENDER_PYTHON -m pip install "numpy<2.0" opencv-python Pillow scipy
+$BLENDER_PYTHON -m pip install -r /path/to/blendslop/blender_blocking/requirements.txt
+```
+
+### Visual hull only emits point clouds instead of meshes
+
+Install or repair `scikit-image` in Blender's Python. Visual hull marching-cubes extraction requires `skimage.measure.marching_cubes`.
+
+```bash
+$BLENDER_PYTHON -m pip install scikit-image
+```
+
+### Poisson postprocess is skipped
+
+Install or repair `open3d` in Blender's Python. Poisson and screened-Poisson postprocess modes are explicit optional stages and will report a structured skip when Open3D is unavailable.
+
+```bash
+$BLENDER_PYTHON -m pip install open3d
+```
+
+### LPIPS / torch / torchvision are unavailable
+
+`torch`, `torchvision`, and `lpips` are optional research dependencies used by LPIPS novel-view scoring and some experimental differentiable paths. On Windows/Blender 5, use the repository repair command instead of a loose `pip install torch`, because newer CPU wheels can import in Blender's standalone `python.exe` but fail once loaded inside the Blender process.
+
+```powershell
+$BLENDER_PYTHON = "C:\Program Files\Blender Foundation\Blender 5.0\5.0\python\bin\python.exe"
+& $BLENDER_PYTHON blender_blocking\verify_setup.py --install-research-deps
 ```
 
+Dry-run the exact commands first:
+
+```powershell
+& $BLENDER_PYTHON blender_blocking\verify_setup.py --install-research-deps --dry-run
+```
+
+The supported plan installs the CPU-only `torch==2.5.1+cpu` / `torchvision==0.20.1+cpu` pair, `sympy==1.13.1`, and `lpips==0.1.4` into the active Blender Python user site. This is appropriate for AMD/non-CUDA machines. It does not install `nvdiffrast`.
+
+On Windows, Open3D and CPU PyTorch can load incompatible native runtimes inside the same Blender process. The setup verifier probes the LPIPS/PyTorch stack in isolated Blender subprocesses so availability reporting cannot crash the main process. If you need both Open3D postprocessing and LPIPS metrics for one asset, run those phases in separate Blender invocations.
+
+### OpenVDB export is skipped
+
+OpenVDB is optional. The tool probes both `pyopenvdb` and `openvdb` bindings and falls back to sparse NPZ interchange when neither binding is available. A plain `pip install openvdb` often has no Windows wheel, so direct `.vdb` export usually requires a compatible Blender-bundled binding, conda package, or source-built OpenVDB Python binding for the exact Python runtime.
+
+Use `require_openvdb=true`, `openvdb_required=true`, `fail_on_openvdb_skip=true`, or `export_openvdb_required=true` only when a missing direct `.vdb` binding should fail the candidate instead of recording a structured NPZ fallback.
+
+### nvdiffrast is unavailable
+
+`nvdiffrast` is NVIDIA's differentiable rasterizer. It is optional and not a normal dependency for this project. The `differentiable_refine` backend always has the deterministic `cpu_soft_silhouette` path; the `nvdiffrast` path is only for machines with the NVIDIA CUDA stack and the source-built NVlabs extension.
+
+There is no official ROCm version of `nvdiffrast`. On AMD/ROCm machines, keep using `cpu_soft_silhouette` for mesh/primitive refinement, or treat ROCm GSplat-style Gaussian splatting as a separate research backend instead of a drop-in replacement.
+
 ### Different Python versions
 
 If you see errors about missing extensions or binary incompatibility, your venv and Blender are using different Python versions. This is why you MUST install directly into Blender's Python - the compiled extensions must match Blender's Python version exactly.

blender_blocking/CI_CD.md

@@ -21,6 +21,14 @@ Exit codes:
 - `1`: One or more tests failed
 - `2`: Test runner error (not running in Blender, etc.)
 
+Pure-Python refinement lab coverage is included in the pure phase:
+
+```bash
+python blender_blocking/test_runner.py --phase pure --no-progress
+```
+
+Full refinement sweeps are intentionally not part of default CI because they generate reports, renders, and per-variant artifacts. Keep those under ignored `temp/refinement-runs/` and upload them only as ad hoc diagnostic artifacts when a workflow explicitly asks for them.
+
 ## GitHub Actions Workflow
 
 Create `.github/workflows/blender-tests.yml`:
@@ -57,7 +65,7 @@ jobs:
           echo "Blender Python: $BLENDER_PYTHON"
 
           # Install dependencies
-          $BLENDER_PYTHON -m pip install numpy opencv-python Pillow scipy
+          $BLENDER_PYTHON -m pip install -r blender_blocking/requirements.txt
 
       - name: Run tests
         run: |
@@ -87,7 +95,7 @@ jobs:
         run: |
           BLENDER_PYTHON=$(blender --background --python-expr "import sys; print(sys.executable)" 2>&1 | grep -oP '/[^ ]+python[0-9.]*')
           echo "Blender Python: $BLENDER_PYTHON"
-          $BLENDER_PYTHON -m pip install numpy opencv-python Pillow scipy
+          $BLENDER_PYTHON -m pip install -r blender_blocking/requirements.txt
 
       - name: Run tests
         run: |
@@ -121,7 +129,7 @@ test:blender-5:
   before_script:
     - BLENDER_PYTHON=$(blender --background --python-expr "import sys; print(sys.executable)" 2>&1 | grep -oP '/[^ ]+python[0-9.]*')
     - echo "Installing dependencies in Blender Python $BLENDER_PYTHON"
-    - $BLENDER_PYTHON -m pip install numpy opencv-python Pillow scipy
+    - $BLENDER_PYTHON -m pip install -r blender_blocking/requirements.txt
   script:
     - cd blender_blocking
     - blender --background --python test_runner.py
@@ -140,7 +148,7 @@ test:blender-4:
   image: "nytimes/blender:4.2-cpu-ubuntu22.04"
   before_script:
     - BLENDER_PYTHON=$(blender --background --python-expr "import sys; print(sys.executable)" 2>&1 | grep -oP '/[^ ]+python[0-9.]*')
-    - $BLENDER_PYTHON -m pip install numpy opencv-python Pillow scipy
+    - $BLENDER_PYTHON -m pip install -r blender_blocking/requirements.txt
   script:
     - cd blender_blocking
     - blender --background --python test_runner.py
@@ -177,7 +185,7 @@ docker run --rm \
   nytimes/blender:5.0-cpu-ubuntu22.04 \
   bash -c "
     BLENDER_PYTHON=\$(blender --background --python-expr 'import sys; print(sys.executable)' 2>&1 | grep -oP '/[^ ]+python[0-9.]*')
-    \$BLENDER_PYTHON -m pip install numpy opencv-python Pillow scipy
+    \$BLENDER_PYTHON -m pip install -r blender_blocking/requirements.txt
     blender --background --python test_runner.py
   "
 ```
@@ -191,7 +199,7 @@ FROM nytimes/blender:5.0-cpu-ubuntu22.04
 
 # Install Python dependencies
 RUN BLENDER_PYTHON=$(blender --background --python-expr "import sys; print(sys.executable)" 2>&1 | grep -oP '/[^ ]+python[0-9.]*') && \
-    $BLENDER_PYTHON -m pip install numpy opencv-python Pillow scipy
+    $BLENDER_PYTHON -m pip install -r blender_blocking/requirements.txt
 
 # Set working directory
 WORKDIR /workspace
@@ -219,6 +227,40 @@ Test against multiple Blender versions to catch compatibility issues early:
 
 **Recommendation**: Test against current + previous LTS release minimum.
 
+## Optional Refinement Diagnostics Job
+
+Use this only for manual workflow dispatch or a failing reconstruction branch. It runs one small refinement smoke and uploads the ignored run root for inspection:
+
+```yaml
+  refinement-smoke:
+    name: Refinement lab smoke
+    runs-on: ubuntu-latest
+    container:
+      image: nytimes/blender:5.0-cpu-ubuntu22.04
+    if: github.event_name == 'workflow_dispatch'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install dependencies in Blender Python
+        run: |
+          BLENDER_PYTHON=$(blender --background --python-expr "import sys; print(sys.executable)" 2>&1 | grep -oP '/[^ ]+python[0-9.]*')
+          $BLENDER_PYTHON -m pip install -r blender_blocking/requirements.txt
+      - name: Run refinement smoke
+        run: |
+          blender --background --python blender_blocking/test_e2e_validation.py -- \
+            --refinement-suite default-vase \
+            --refinement-track profile-loft-refinement \
+            --refinement-max-runs 1 \
+            --refinement-result-root temp/refinement-runs/ci-smoke-profile \
+            --refinement-html-report \
+            --no-progress
+      - name: Upload refinement artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: refinement-smoke
+          path: temp/refinement-runs/ci-smoke-profile
+```
+
 ## What Tests Must Verify
 
 Critical tests that must run in actual Blender:
@@ -296,7 +338,7 @@ chmod +x .git/hooks/pre-commit
 python3 -m ensurepip --default-pip
 
 # Or use system pip with target
-pip install --target=/path/to/blender/python/lib numpy opencv-python Pillow scipy
+pip install --target=/path/to/blender/python/lib -r blender_blocking/requirements.txt
 ```
 
 ### Tests timeout in CI

blender_blocking/E2E_TESTING_FEASIBILITY.md

@@ -256,7 +256,7 @@ def test_reconstruction_accuracy():
 
     # Render orthogonal views
     print("Rendering orthogonal views...")
-    rendered_paths = render_orthogonal_views('test_output/renders/')
+    rendered_paths = render_orthogonal_views('../temp/renders/')
 
     # Compare each view
     print("Comparing rendered views to references...")

blender_blocking/E2E_VALIDATION_SUMMARY.md

@@ -206,7 +206,7 @@ jobs:
         uses: actions/upload-artifact@v2
         with:
           name: failed-renders
-          path: blender_blocking/test_output/e2e_renders/
+          path: temp/e2e/renders/
 ```
 
 ## Benefits

blender_blocking/INTEGRATION.md

@@ -30,6 +30,18 @@ The integration combines image processing, shape analysis, and 3D primitive plac
 ### 6. Main Integration (`main_integration.py`)
 - **BlockingWorkflow** - Main workflow class that orchestrates the entire pipeline
 
+### 7. Refinement Lab (`refinement_lab/`)
+- **contracts.py** - Typed experiment cases, variants, results, and run manifests
+- **presets.py** - Built-in suites and parameter tracks
+- **matrix.py** - Deterministic grid, random, coordinate, and successive-halving plan construction
+- **runner.py** - In-process and subprocess execution against the E2E CLI
+- **parameter_search.py** - Objective scoring and ranking
+- **candidate_autopsy.py** - Structured failure diagnosis
+- **bounds_debug.py** - Visual-hull transform, projection, and bounds diagnostics
+- **artifact_report.py** - Static HTML reports and overlay/diff assets
+- **human_labels.py** - Reviewer labels that influence human-adjusted ranking
+- **cli.py** - Pure command line interface for list/plan/run/report/rank/autopsy/label/promote
+
 ## Dependencies
 
 ### Python Packages
@@ -45,13 +57,13 @@ scipy
 
 Install Python dependencies:
 ```bash
-pip install numpy opencv-python Pillow scipy
+pip install -r requirements.txt
 ```
 
 For Blender's Python environment:
 ```bash
 # macOS example (adjust path for your Blender version)
-/Applications/Blender.app/Contents/Resources/4.2/python/bin/python3.11 -m pip install numpy opencv-python Pillow scipy
+/Applications/Blender.app/Contents/Resources/4.2/python/bin/python3.11 -m pip install -r /path/to/blendslop/blender_blocking/requirements.txt
 ```
 
 ## Usage
@@ -132,6 +144,24 @@ workflow.analyze_shapes()
 workflow.create_3d_blockout(num_slices=15, primitive_type='CYLINDER')
 ```
 
+### Refinement Lab Workflow
+
+Use the lab when comparing reconstruction strategies or diagnosing a bad output. The lab builds a plan, executes variants, writes structured results, and ranks them by objective:
+
+```bash
+python -m blender_blocking.refinement_lab.cli list-suites
+python -m blender_blocking.refinement_lab.cli list-tracks
+python -m blender_blocking.refinement_lab.cli plan --suite default-vase --track visual-hull-transform --max-runs 4 --out temp/refinement-runs/plan-smoke.json
+```
+
+Run through Blender:
+
+```bash
+blender --background --python blender_blocking/test_e2e_validation.py -- --refinement-suite default-vase --refinement-track visual-hull-transform --refinement-search coordinate --refinement-max-runs 48 --refinement-result-root temp/refinement-runs/default-vase-vh-transform --refinement-bounds-debug --refinement-autopsy --no-progress
+```
+
+The run root includes `manifest.json`, `plan.json`, `index.jsonl`, `leaderboard.md`, `report.html`, per-variant `result.json`, optional `autopsy.json`, and optional `bounds-debug.json`. Generated run roots are ignored and must not be committed.
+
 ## Workflow Steps
 
 The integration follows these steps:
@@ -153,6 +183,7 @@ The integration follows these steps:
 7. **Place Primitives** - Position and scale primitives for each slice
 8. **Boolean Union** - Join all primitives into single mesh
 9. **Scene Setup** - Add camera and lighting for rendering
+10. **Optional Refinement Loop** - Sweep candidate parameters, inspect report/autopsy output, label winners, and promote the best reproducible configuration
 
 ## Example Output
 

blender_blocking/QUICKSTART.md

@@ -159,6 +159,30 @@ mesh = workflow.run_full_workflow(num_slices=20)
 mesh = workflow.run_full_workflow(num_slices=8)
 ```
 
+## Refining Reconstruction Quality
+
+When a result is close but not good enough, use the refinement lab instead of hand-editing one knob at a time. It sweeps reconstruction modes and parameters, ranks candidates, writes autopsies, and produces an HTML report under ignored `temp/refinement-runs/`.
+
+Plan a small run without opening Blender:
+
+```bash
+python -m blender_blocking.refinement_lab.cli plan --suite default-vase --track profile-loft-refinement --max-runs 4 --out temp/refinement-runs/plan-smoke.json
+```
+
+Run one actual Blender refinement smoke:
+
+```powershell
+& "C:\Program Files\Blender Foundation\Blender 5.0\blender.exe" --background --python blender_blocking\test_e2e_validation.py -- `
+  --refinement-suite default-vase `
+  --refinement-track profile-loft-refinement `
+  --refinement-max-runs 1 `
+  --refinement-result-root temp\refinement-runs\smoke-profile `
+  --refinement-html-report `
+  --no-progress
+```
+
+See [REFINEMENT_LAB.md](REFINEMENT_LAB.md) for visual-hull diagnostics, ranking, labels, and promotion commands.
+
 ## Troubleshooting
 
 ### "No module named numpy" or dependency errors
@@ -193,6 +217,11 @@ Pillow has compiled C extensions that must match Blender's Python version exactl
 - Reduce `num_slices` to 8 or 10
 - Check that your images have clear silhouettes
 
+### Visual hull mesh extraction is skipped
+- Install `scikit-image` into Blender's Python; visual hull marching cubes needs `skimage.measure`.
+- If Poisson postprocess is skipped, install `open3d` into Blender's Python.
+- Run `verify_setup.py` from Blender's Python console to confirm both packages are visible to Blender.
+
 ### Import errors
 
 Make sure you: