Metadata-Version: 2.1
Name: gendr
Version: 0.1.0
Summary: GenDR - The Generalized Differentiable Renderer
Home-page: https://github.com/Felix-Petersen/gendr
Author: Felix Petersen
Author-email: ads0475@felix-petersen.de
License: MIT License
Description: # GenDR - The Generalized Differentiable Renderer
        
        ![gendr_logo](gendr_logo.png)
        
        Official implementation for our CVPR 2022 Paper "GenDR: A Generalized Differentiable Renderer".
        
        Paper @ [ArXiv](https://arxiv.org/abs/2204.13845),
        Video @ [Youtube](https://youtu.be/p-ZCcUWzriE).
        
        ## 💻 Installation
        
        `gendr` can be installed via pip from PyPI with
        ```shell
        pip install gendr
        ```
        > ⚠️ Note that `gendr` requires CUDA, the CUDA Toolkit (for compilation), and `torch>=1.9.0` (matching the CUDA version).
        
        Alternatively, GenDR may be installed from source, e.g., in a virtual environment like
        ```shell
        virtualenv -p python3 .env1
        . .env1/bin/activate
        pip install torch==1.9.0+cu111 torchvision==0.10.0+cu111 -f https://download.pytorch.org/whl/torch_stable.html
        pip install .
        ```
        Make sure that the CUDA version of PyTorch (e.g., `cu111` for CUDA 11.1) matches the locally installed version.
        However, on some machines, compiling works only with specific subversions that may be unequal to the local subversion, 
        so a potential quick fix is trying different PyTorch version and CUDA subversion combinations.
        
        ## 👩‍💻 Documentation
        
        A differentiable renderer may be defined as follows
        
        ```python
        import gendr
        
        diff_renderer = gendr.GenDR(
            image_size=256,
            dist_func='uniform',
            dist_scale=0.01,
            dist_squared=False,
            aggr_alpha_func='probabilistic',
            aggr_rgb_func='hard',
        )
        ```
        
        In the following, we provide the entire set of arguments of `GenDR`.
        The most important parameters are marked in **bold**.
        For the essential parameters `dist_func` and `aggr_alpha_func`, we give a set of options. 
        For a reference, see [the paper](https://arxiv.org/abs/2204.13845).
        
        * `image_size` **the size of the rendered image** (default: 256)
        * `background_color` (default: [0, 0, 0])
        * `anti_aliasing` render it at 2x the resolution and average to reduce aliasing (default: False)
        
        * `dist_func` **the distribution used for the differentiable occlusion test** (default: uniform)
          * `hard` hard, non-differentiable rendering, Dirac delta distribution, Heaviside function (alias `heaviside`)
          * `uniform` uniform distribution
          * `cubic_hermite` Cubic-Hermite sigmoid function
          * `wigner_semicircle` Wigner Semicircle distribution
          * `gaussian` Gaussian Distribution
          * `laplace` Laplace Distribution
          * `logistic` logistic Distribution
          * `gudermannian` Gudermannian function, hyperbolic secant distribution (alias `hyperbolic_secant`)
          * `cauchy` Cauchy distribution
          * `reciprocal` reciprocal sigmoid function
          * `gumbel_max` Gumbel-max distribution
          * `gumbel_min` Gumbel-min distribution
          * `exponential` exponential distribution
          * `exponential_rev` exponential distribution (reversed / mirrored)
          * `gamma` gamma distribution
          * `gamma_rev` gamma distribution (reversed / mirrored)
          * `levy` Levy distribution
          * `levy_rev` Levy distribution (reversed / mirrored)
        * `dist_scale` **the scale parameter of the distribution, tau in the paper** (default: 1e-2)
        * `dist_squared` optionally, use the square-root distribution of `dist_func` (default: False)
        * `dist_shape` for some distributions, we need a shape parameter (default: None)
        * `dist_shift` for some distributions, we need an optional shift parameter (default: None or 0)
        * `dist_eps` pixels further away than `dist_scale*dist_eps` are ignored for performance reasons (default: 1e4)
        
        * `aggr_alpha_func` **the t-conorm used to aggregate occlusion values** (default: probabilistic)
          * `hard` to be used with `dist_func='hard'`
          * `max` maximum T-conorm
          * `probabilistic` probabilistic T-conorm
          * `einstein` Einstein sum T-conorm
          * `hamacher` Hamacher T-conorm
          * `frank` Frank T-conorm
          * `yager` Yager T-conorm
          * `aczel_alsina` Aczel-Alsina T-conorm
          * `dombi` Dombi T-conorm
          * `schweizer_sklar` Schweizer-Sklar T-conorm
        * `aggr_alpha_t_conorm_p` for some t-conorms, we need a shape parameter (default: None)
        
        * `aggr_rgb_func` (default: softmax)
        * `aggr_rgb_eps` (default: 1e-3)
        * `aggr_rgb_gamma` (default: 1e-3)
        
        * `near` value for the viewing frustum (default: 1)
        * `far` value for the viewing frustum (default: 100)
        * `double_side` render all faces from both sides (default: False)
        * `texture_type` type of texture sampling (default: surface; options: surface, vertex)
        
        
        ## 🧪 Experiments
        
        ### 🐼 Shape Optimization (`opt_shape.py`)
        
        ```shell
        python experiments/opt_shape.py -sq --gif
        ```
        
        ### 📽 Camera Pose Optimization (`opt_camera.py`)
        
        ```shell
        python experiments/opt_camera.py -sq --gif
        ```
        
        ### ✈️ Single-View 3D Reconstruction (`train_reconstruction.py`)
        
        Optimal default parameters for `--dist_scale` are automatically used in the script for the set of distributions
        and t-conorms that are benchmarked on this task in the paper.
        
        ```shell
        python experiments/train_reconstruction.py --distribution uniform --t_conorm probabilistic
        ```
        
        ## 📖 Citing
        
        ```bibtex
        @inproceedings{petersen2022gendr,
          title={{GenDR: A Generalized Differentiable Renderer}},
          author={Petersen, Felix and Goldluecke, Bastian and Borgelt, Christian and Deussen, Oliver},
          booktitle={IEEE/CVF International Conference on Computer Vision and Pattern Recognition (CVPR)},
          year={2022}
        }
        ```
        
        ## License
        
        `gendr` is released under the MIT license. See [LICENSE](LICENSE) for additional details about it.
        
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/markdown
