Metadata-Version: 2.1
Name: retexture
Version: 0.1.1
Summary: ReTexture dataset toolkit for generation and analysis
Home-page: https://github.com/mhyatt000/retexture
Author: Matt Hyatt
Author-email: Matthew Hyatt <mhyatt000@gmail.com>
License: MIT License
        
        Copyright (c) 2023 Matthew Hyatt
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/mhyatt000/retexture
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tqdm >=4.61.2
Requires-Dist: numpy >=1.23.5
Requires-Dist: hydra-core >=1.3

# retexture
ReTexture dataset toolkit for generation and analysis

<img src="assets/teaser.png" alt="" width="100%"/>

## Installation

1. clone the repo `git clone "https://github.com/mhyatt000/retexture"`
2. `pip install -e .`

### Installing blender

* MacOS: `brew install blender`
* Unix: `apt-get install blender`

### Install Blender via script

see [`retexture/scripts/setup/install_blender.sh`](retexture/scripts/setup/install_blender.sh)

## Dataset Setup

place all models in `datasets/models` and place textures in `datasets/textures` like so:

```
datasets
├── models
│   ├── bird1.dae
│   ├── butterfly1.dae
│   ...
├── datasets/textures
│   ├── bird1.jpg
│   ├── butterfly1.png
│   ...
```

## Config Setup

see [`configs/base.yaml`](configs/base.yaml)

## Run

`python -m retexture run`

## NOTES and Design Choices

### Blender is incompatible with external python libraries

* Blender uses its own distribution of Python
* does not allow changes to site packages (without weird hacks)
    * ie: using `sys.path.append` as a workaround

### Argparse conflicts with blender commandline arguments

Solution: 
* `blender -b -P <script.py> -- <args>`

### GPU rendering seems to cause problems
* Yields a black image 
    * could be due to external servers having limited GUI
    * could be due to problems with the GPU and CUDA compatible libraries
* Blender provides lower level gpu support... see [Blender Official Docs](https://docs.blender.org/api/current/gpu.html)

### Memory required increases with job runtime
* Blender keeps a history of all operations

Solution: 
* Render jobs are split into batches
* Master script spins off Blender processes with the child script

## Known Problems

* Bounding box centering fails occasionally
