README.md

---
license: cc-by-2.0
pipeline_tag: text-to-image
---

# ShadowDraw: From Any Object to Shadow–Drawing Compositional Art

This repository contains the models and code for **ShadowDraw**, a framework that transforms ordinary 3D objects into shadow-drawing compositional art. Given a 3D object, the system predicts scene parameters, including object pose and lighting, together with a partial line drawing, such that the cast shadow completes the drawing into a recognizable image.

-   **Paper**: [ShadowDraw: From Any Object to Shadow-Drawing Compositional Art](https://huggingface.co/papers/2512.05110)
-   **Project Page**: https://red-fairy.github.io/ShadowDraw/
-   **Code**: https://github.com/Red-Fairy/ShadowDraw

<div align="center">
  <img src="https://github.com/Red-Fairy/ShadowDraw/raw/main/assets/teaser.gif" alt="ShadowDraw Teaser" width="600"/>
</div>

## 🔧 Installation

First, create a conda environment and install the dependencies:

```bash
git clone https://github.com/red-fairy/ShadowDraw.git
cd ShadowDraw
conda env create -f environment.yml
```

Then, install Blender 4.3.2 following the instructions [here](https://download.blender.org/release/Blender4.3/), unzip it, and specify the path to the Blender executable in the `blender_path` argument of the `main.py` script.

## 🎨 Generate Your Own Shadow-Drawing Art

### Shadow-Drawing Art from a Single Object

First, download the LoRA weights for the line drawing generation model from HuggingFace:
```bash
huggingface-cli download RedFairy/Flux-ShadowDraw-LoRA --local-dir ./checkpoints
```

Then, prepare your 3D object file in `.obj`, `.glb`, or `.ply` format, and run the following command:

```bash
python scripts/launch.py --object_filepaths PATH_TO_OBJECT_FILE \
    --save_name SAVE_NAME \
    --output_root OUTPUT_ROOT \
    --optimize_object_params
```

To accelerate the generation process, you can remove `--optimize_object_params` and instead add `--sample_distribution`. This will fix the azimuths and fit a distribution of object internal rotations with respect to fractal dimension and sample internal rotations accordingly. 

To add gravity to the object, add `--use_gravity`. If specified, the object will be first animated by gravity to find a stable pose and then rendered. 

### Shadow-Drawing Art from Multiple Objects

For multi-object compositions, you can use the following command:

```bash
python scripts/launch.py --object_filepaths PATH_TO_OBJECT_FILES \
    --save_name SAVE_NAME \
    --output_root OUTPUT_ROOT \
    --sample_distribution
```

Here, `PATH_TO_OBJECT_FILES` should be a space-separated list of `.obj`, `.glb`, or `.ply` files.

For user-specified subject, add `--user_character CHARACTER_NAME` and `--system_prompt_path system_prompts/prompt_proposal_user.txt`.

## 📊 Citation
If you find this work useful, please consider citing:

```bibtex
@article{luo2025shadowdraw,
  title={ShadowDraw: From Any Object to Shadow–Drawing Compositional Art},
  author={Luo, Rundong and Snavely, Noah and Ma, Wei-Chiu},
  journal={arXiv preprint arXiv:2512.05110},
  year={2025}   
}
```