• Stars
    star
    171
  • Rank 222,266 (Top 5 %)
  • Language
    C++
  • License
    Other
  • Created over 3 years ago
  • Updated 12 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

The official implementation of the research paper "DAG Amendment for Inverse Control of Parametric Shapes"

DAG Amendment for Inverse Control of Parametric Shapes

Teaser

This repository is the official Blender implementation of the paper "DAG Amendment for Inverse Control of Parametric Shapes" by Élie Michel and Tamy Boubekeur, published in Transactions on Graphics (Siggraph 2021).

@article{MB:2021:DAGA, 
  title = "DAG Amendment for Inverse Control of Parametric Shapes", 
  author = "Elie Michel and Tamy Boubekeur", 
  year = "2021", 
  journal = "ACM Transactions on Graphics",
  number = "4",
  volume = "40",
  pages  = "173:1--173:14",
}

Video

Usage

A. Download the latest release zip file and install it like any other Blender add-on (in Edit > Preferences > Add-ons > Install)

B. You should see two new panels in scene properties. The "Parametric Shape - Rig" panel (1) is where one defines the list of public hyper-parameters of the scene and the "Parametric Shape - Anim" panel (2) that exposes all hyper-parameters once they are defined.

Parametric Shape panels in scene properties

C. We first use the Rig panel. Let's add a few hyper-parameters using the "+" button. Select in the list (1) an hyper-parameter to access to its settings bellow. An hyper-parameter drives a given component of an object's property, so for each of them one must define the object (2), the property (3) -- that is typically location, rotation or scale but can be any other property accessible from the Python API -- and the component (4), either 0, 1, 2 or 3 for X, Y, Z or W respectively.

Definition of a few hyper-parameters

These essential settings can be set directly from the hyper-parameter list for quicker access, but there are also extra settings, namely the boundaries, the default value, and the display name (automatically filled in using the object's name and target property/index by default).

D. Make sure your scene uses only supported modifiers, then click on Dag Amendment. This will insert modifiers in the scene, with name starting by _AMENDMENT_.

Dag Amendment button

E. In Object mode (1), enable the "SmartGrab" tool (2). This is the brush that enables one to manipulate the scene in a way that will only affect hyper-parameters. Setting are displayed in (3) upon activation of the tool.

SmartGrab tool

F. (optional) Tune the settings. The brush radius can be modified using Ctrl + Mouse Left, or the F key. Other settings are accessible in the upper bar. The two drop down menus are used to chose the solver (1) and the jacobian filtering algorithm (2), and depending on your choice they might have dedicated settings in (1b) et (2b) respectively. Then come settings related to the sampling and finite differences (3) and to display options (4). Default values are the one used in the paper.

SmartGrab settings overview

Advanced Usage

Drivers Hyper-parameter targets are simple object properties, like an object's position, but if you want to drive properties from other entities, like a parameter of a modifier for instance, you can use Blender's drivers to link the driven object (typically an empty) to the actual target.

Setup From Collection If you organized your scene such that a collection groups all the objects driven by hyper-parameters and that you locked all transform channels that must not be changed, then instead of manually adding the hyper-parameters one by one you may simply use the Setup From Collection button:

Setup from collection scene tree

Setup from collection button

View Layer The SmartGrab brush can use a different view layer than the one you are visualizing. Points at which jacobians are measured are sampled using the view layer stated at the beginning of the Rig panel. Typically, use this if you want to see in wireframe the operands of some boolean operation but want the brush to ignore these.

Supported modifiers

As a general rule of thumb, we support the modifiers that are able to transmit UV coordinates from input to output without introducing overlap, or if they introduce overlap with the possibility to disambiguate it like for instance the array modifier enables one to offset UVs for each instance.

A note about Geometry Nodes Geometry Nodes would be a very natural target for our method, but they did not exist in the main branch of Blender until a few months ago, so our prototype was developed without them. As a consequence, they are not supported yet by this add-on; we stuck to modifiers.

Building

NB If you just want to use the add-on, you do not need to build it yourself, you may simply download the latest release.

Steps 1 and 2 can be performed by simply running:

# on linux: apt install build-essential cmake python3.10-dev
python make_releases.py
  1. Build Accel
cd Accel
mkdir build
cd build
cmake .. -DPYTHON_EXECUTABLE="C:\Python310\python.exe"
cmake --build . --config Release
cmake --install .

The install command simply copies the pyd file that results from building (e.g. Accel.cp310-win_amd64.pyd) to DagAmendment.

NB: For Blender <= 2.92, the python version must be 3.7 (the filename must contain cp37). From 2.93 to 3.0 use Python 3.9 (cp39) and from 3.1 on, it must be Python 3.10 (cp310). If it is not the case, you must either set your PATH so that where python or which python points to the relevant version, or use -DPYTHON_EXECUTABLE as in the example above. This requires to have the relevant version of Python installed independently of Blender's embedded version (because the latter does not include libraries to link against).

  1. Create zip from DagAmendment/ and copy it to the releases directory (gitignore'd). This zip file is an add-on that can be installed in Blender.

  2. In Blender, go to Edit > Preferences, Add-ons tab, "Install...", browse to the release directory created by the script above and install DiffParam and DepsgraphNodes.

Walkthrough

Main entry points

The four main sections of the code that relates to the paper are:

  • DAG Amendment: Located in dag_amendment_operators.py, it inserts new nodes (in practice new modifiers) in the scene based on the analysis of the dependency graph generated using the DepsgraphNodes/ submodule.

  • Jacobian Filtering: Located in JFilters/NegativeJFilter.py for the one described in the paper, but other alternative jacobian filtering algorithm are available (at least the naive AverageJFilter.py, for comparison). The JFilter takes the list of sample points and their gradients (through an instance of the SamplePoints class) and builds a single jacobian, for the solver to use.

  • Solver: Located in Solvers/StandardSolver.py, with an option to use active sets or not, the solver uses the jacobian returned by the JFilter and the user stroke to decide on an update of the hyper-parameters.

  • The main interaction loop: Located in smartgrab_operators.py, this operator is called when the "SmartGrab tool" is enabled to handle key/mouse events and orchestrate the calls to the jacobian filtering and solver.

File layout

The root of the add-on is the DagAmendment directory, which contains only Python code. A small module is accelerated using C++ and put aside in the Accel directory. Once built, this module is a .pyd file that must be copied inside of DagAmendment.

As most Blender add-ons do, DagAmendment defines:

  • properties: extra fields attached to scenes and objects, and save into .blend files. These are defined by all files ending with ...properties.py. Hyper-parameters for instance are properties we attach to a scene.
  • operators: actions that can be called from the UI or from other scripts, that can change properties and call other operators. They are defined in all files ending with ...operators.py.
  • panels: the extra sections that appear in the scene properties (see usage instructions above)
  • overlays: callbacks drawing on top of the 3D viewport:
  • tools: a mapping from key/mouse event bindings to operators that is used only when the tool is activated (in the left-hand side of the 3D viewport). For instance, the "SmartGrab" tool that we define tells that when it is activated, a mouse click event must trigger the operator defined in smartgrab_operators.py.
  • preferences: global settings exposed in the add-ons section of Edit > User preferences.
  • handlers: callbacks executed by Blender at events such as file loaded, scene changed etc. Used here mostly to ensure that hyper-parameter boundaries are respected.

Then, files starting with a capital letter only define a class whose name is the same as the file. Most of them are abstraction meant to make our core implementation less tied to Blender. ParametricShape wraps around a scene to only expose methods we need for the interaction loop and Brush, Projector, Ray, ViewportState and Stroke are used by solvers instead of calling Blender specific equivalent. SamplePoints holds the list of points that are sampled within the brush, and measures the jacobians at each of these points.

uv_coparam holds the function used to convert co-parameters, which identify points independently of the value of the hyper-parameters, into Tuv parameters which quickly identify a point using a triangle index and barycentric coordinates but is valid for the current value of the hyper-parameters only. This is the part that uses Accel to quickly iterate the geometry.

blender_imgui is used only if you manually install the imgui module, to draw colored sliders in the viewport.

Other files are either self explanatory or of minor importance. Files ending with ...utils.py are unorganized lists of utility functions.

The directory DepsgraphNodes/ is an embedded add-on that introduces a new node panel where the relations from the scene (parenting, drivers, pointers to other objects in modifiers, etc.) are represented as nodes. The node tree is built by analyzing the scene. This is used because Blender's API does not natively provides a consistent graph-like interface to access this, while our DAG Amendment needs so for a clear implementation.

The directories JFilters/ and Solvers/ contain class files defining variants of jacobian filter and solvers respectively. When using the SmartGrab tool, the user can chose in drop down menus which of these to use. To create new alternatives, simply copy one of the existing files and change its content, then the files jfilter_registry.py and solver_registry.py will automatically find them and show them in the UI.

Troubleshooting

If the estimation of jacobians seems messy:

  • Check that you are using only supported modifiers
  • Try adding a triangulate modifier on the object that causes trouble
  • Tune the finite difference step

Before reporting an issue Please have a look at the system console (Window > Toggle System Console) for error messages. When reporting an issue, you must attach the full content of this console.

License

Being a Blender add-on, this code is distributed as a whole under the terms of the GPLv3 license. In details, files that use the bpy module (Blender Python) must be GPL, other files use the more permissive MIT license.

Copyright (c) 2020-2022 - Télécom Paris (Élie Michel)

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

More Repositories

1

MapsModelsImporter

A Blender add-on to import models from google maps
Python
2,414
star
2

LilySurfaceScraper

Import shaders end environments in Blender from a single URL
Cython
596
star
3

LearnWebGPU

Learn to use WebGPU for native graphic applications in C++
C++
383
star
4

BMeshUnity

A Unity package to make runtime procedural mesh generation more flexible.
C#
350
star
5

WebGPU-Cpp

A single-file zero-overhead C++ idiomatic wrapper for WebGPU native
C++
277
star
6

HoudiniEngineForBlender

Branch of Blender featuring a Houdini Engine based modifier
181
star
7

OpenMfxForBlender

A branch of Blender featuring an OpenMfx modifier
C
176
star
8

OpenMfx

A low-overhead mesh-processing plug-in API for cross-software procedural effects
C
161
star
9

WebGPU-distribution

Distributions of WebGPU for native and web development, easy to integrate and interchangeable.
CMake
145
star
10

LearnWebGPU-Code

The accompanying code of the Learn WebGPU C++ programming guide
99
star
11

BlenderImgui

Custom GUI for your Blender add-ons using Dear ImGui
Python
94
star
12

glfw3webgpu

An extension for the GLFW library for using WebGPU native.
C
62
star
13

LilyRender360

Lily Render 360 is a tool for rendering a Unity scene into stitch-free equirectangular images
C#
59
star
14

MfxHoudini

A Houdini-Engine based Open Mesh Effect
C
57
star
15

AdvancedBlenderAddon

A starter kit and reference for writing advanced Blender add-ons
Python
39
star
16

Python3dViewer

A simple starter Python code for experimenting 3D graphics
Python
30
star
17

sdl2webgpu

An extension for the SDL2 library for using WebGPU native.
C
25
star
18

MesoGen

The official implementation of MesoGen: Designing Procedural On-Surface Stranded Mesostructures (Siggraph 2023)
C++
24
star
19

RayStep

A real-time 3D distance field modeling software
C++
22
star
20

MapsModelsImporter-samples

Sample file to check MapsModelsImporter installation
20
star
21

LilyImageFromURL

A very very simple Blender add-on to very very quickly import images from URLs.
Python
17
star
22

GrainViewer

The official implementation of the research paper "Real-time multiscale rendering of dense dynamic stackings"
C++
13
star
23

MonumentValley

A little toy reproducing Monument Alley basic mechanism in Unity
C#
12
star
24

MfxVCG

An OpenMfx plug-in providing effects from VCGlib
C++
12
star
25

WebGPU-utils

A bunch of utility functions for WebGPU
C++
11
star
26

WebGPU-AutoLayout

An online utility tool to generate C++ boilerplate binding code by parsing WGSL.
Rust
10
star
27

TownBuilder

This is an experiment around the reproduction of Stalberg's Townscaper
C#
10
star
28

IRL

Inverse Reinforcement Learning
Jupyter Notebook
9
star
29

CodenameGogh

A node-based front-end to ffmpeg
C++
8
star
30

MfxExamples

An example of OpenMfx plug-in using the C++ SDK
C++
7
star
31

ModernGlad

Depreciation warnings to help writing more modern OpenGL using glad
Python
7
star
32

AugenLight

A cross-plateform OpenGL 4.5 starter kit
C++
6
star
33

firefox-webmention-addon

Firefox add-on to send webmentions though context menu
JavaScript
6
star
34

WebGPU-binaries

A CMake-ready binary release of a WebGPU native implementation (wgpu-native)
C
6
star
35

GreaseJs

A little demo of Grease Pencil using ThreeJS
JavaScript
6
star
36

sphinx_literate

An advanced literate programming tool for writing incremental programming courses.
Python
6
star
37

IvyGenerator

Update of Thomas Luft's original
C++
5
star
38

PythonMfx

A Python-based host for running OpenMfx mesh processing plugins
Python
5
star
39

WebGPU-Cpp-WebBackend

This is the backend of the Web service of https://github.com/eliemichel/WebGPU-Cpp
C++
5
star
40

fxos-AlphaRemote

A Firefox OS remote controller for Sony Alpha series cameras
JavaScript
4
star
41

AlignTools

Alignment tools add-on for Blender
Python
4
star
42

BiharmonicCoords

Webpage for the SIGGRAPH 24 paper "Biharmonic Coordinates and their Derivatives for Triangular 3D Cages"
HTML
4
star
43

WebGPU-raii

An RAII wrapper around the objects of the WebGPU native API.
C++
4
star
44

reshade

Fork ReShade adding Remote Control feature
C++
3
star
45

Cooldown

Feed rythm into live-coding tools
Rust
3
star
46

ReACORN

An attempt to reimplement ACORN
Python
3
star
47

WebMfx

A web-based host for OpenMfx using WASM plugins
C
3
star
48

PolyGreenCoords

Public page of "Polynomial 2D Green Coordinates for Polygonal Cages"(Siggraph 2023)
HTML
3
star
49

StatDeps

A lightweight C++ dependency graph library for compile-time dependent resource management.
C++
3
star
50

cartes-electorales

Python
2
star
51

MfxPlugins

Simple Open Mesh Effect plugins
C++
2
star
52

highspeedracer

Online racing game using Blender Game Engine
Python
2
star
53

LilyFuture

A header-only utiliy library to make std:futures fun to use!
C++
2
star
54

todo

A dead simple command line TODO-list manager
Python
2
star
55

Spillr

Mixed GLSL/C++ static C++ processor aiming at reducing boilerplate in shader writing
OCaml
2
star
56

UnitySsPattern

A screen space shader for Unity with object tracking
ShaderLab
2
star
57

SdfManipulation

Public page of "Direct Manipulation of Analytic Implicit Surfaces"(Siggraph Asia 2024)
HTML
2
star
58

webgpu-doc-jam

Set up for an incoming documentation jam of webgpu-headers, stay tuned!
2
star
59

JeuDePresse

Dessins d'actualité interactifs, produits en quelques heures avec MS Paint
JavaScript
2
star
60

irssi-notify

Notifications for Irssi via a simple http server
Python
1
star
61

WorLd

Simple 2D strategy game whom levels are autogenerated based on mathematical assertions
C++
1
star
62

texdown

Extension of markdown to support mathematics. Based on marked and MathJax.
JavaScript
1
star
63

join.js

The smallest JS library to love promises
JavaScript
1
star
64

fake-position

Firefox addon to spoof geolocation using openstreetmap
JavaScript
1
star
65

ColorSpaceViewer

A browser-based tool for visualizing images in color space
JavaScript
1
star
66

fHMM

Project for the lecture of Probabilistic Graphical Models
TeX
1
star
67

MemoryIDF

Code source du jeu Memory pour l'Ile de France, inspiré de la version pour Paris
HTML
1
star
68

OscToSpout

Forward OSC messages to KodeLife using a texture-sharing via Spout
C++
1
star
69

Dawn

Custom branches of Dawn for the Learn WebGPU for C++ guide
C++
1
star
70

PolyworldJs

Low-poly styled dynamic forest in ThreeJS
JavaScript
1
star
71

ZigDawn

Starter C++ project for using WebGPU native
C
1
star