README.md

---
title: ObjectAssembler - LEGO 3D Assembly Prediction
emoji: 🧱
colorFrom: blue
colorTo: red
sdk: docker
app_port: 7860
pinned: false
license: mit
preload_from_hub:
  - 0xZohar/object-assembler-models
  - openai/clip-vit-base-patch32
env:
  HF_HOME: /home/user/.cache/huggingface
  HF_HUB_CACHE: /home/user/.cache/huggingface/hub
  TRANSFORMERS_CACHE: /home/user/.cache/huggingface/transformers
  HF_HUB_DISABLE_XET: "1"
  LDRAW_LIBRARY_PATH: /home/user/ldraw
---

# ObjectAssembler: Assemble Your Object with Diverse Components

A deep learning-based system for predicting and visualizing LEGO brick assembly sequences using transformer models.

## Features

- **LDR File Processing**: Upload `.ldr` (LDraw format) files containing LEGO brick assembly instructions
- **Text-to-LEGO**: Describe your desired design in natural language (e.g., "red sports car")
- **AI-Powered Prediction**: Uses GPT-based transformer models to predict optimal assembly sequences
- **3D Rendering**: Generates high-quality 3D visualizations using Blender
- **Part Visualization**: Displays individual brick components with rendered previews
- **Interactive UI**: User-friendly Gradio interface for easy interaction

## Model Architecture

- **GPT Model**: 5-layer transformer with 12 attention heads
- **Shape Tokenizer**: VQ-VAE autoencoder with 16,384 token vocabulary
- **CLIP Integration**: Vision-language model for text-to-design retrieval
- **Model Size**: ~1.6GB total weights

## Usage

### Option 1: Upload LDR File
1. Upload an `.ldr` file containing LEGO part names
2. Click "Load Input" to process and visualize individual parts
3. Click "Generate New LDR & Render" to predict assembly sequence
4. Download the generated LDR file or view the 3D rendering

### Option 2: Text-to-LEGO
1. Enter a text description (e.g., "red sports car", "blue police car")
2. Click "Load Input" to retrieve a similar design
3. Click "Generate New LDR & Render" to generate assembly sequence
4. View the AI-generated LEGO model

## Hardware Requirements

- **GPU**: Runs on HuggingFace ZeroGPU (H200, 70GB VRAM)
- **Memory**: At least 8GB RAM
- **Storage**: ~2GB for model weights and dependencies

## Technical Stack

- PyTorch 2.0+
- Gradio 5.12.0+
- Blender 3.6 (for rendering)
- Transformers (Hugging Face)
- CLIP (OpenAI)
- **ZeroGPU** for efficient GPU allocation

## Citation

If you use this work in your research, please cite:

```bibtex
@article{objectassembler2024,
  title={ObjectAssembler: Assemble Your Object with Diverse Components},
  year={2024}
}
```

## License

MIT License

## Acknowledgments

Built with PyTorch, Gradio, Blender, and HuggingFace ZeroGPU.

---

**Latest Update (2025-11-24)**: Enhanced LDraw library verification with detailed part counts and critical part checks.

**Previous Update (2025-11-14)**: Added complete label mapping files for Text-to-LEGO functionality.