---
title: Gradio Openpose 3D Editor Component Demo
emoji: 🧘
colorFrom: pink
colorTo: blue
sdk: gradio
sdk_version: 6.14.0
python_version: '3.13'
app_file: app.py
pinned: false
license: apache-2.0
short_description: Gradio Openpose 3D Editor  Component
---

# `gradio-openpose-3d`
<img alt="Static Badge" src="https://img.shields.io/badge/version%20-%200.0.3%20-%20blue">  
<a href="https://huggingface.co/spaces/elismasilva/gradio_openpose3d_editor"><img src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Demo-blue"></a>  
<span>💻 <a href='https://github.com/DEVAIEXP/gradio_component_openpose3d_editor'>Component GitHub Code</a></span>

A powerful, custom interactive 3D character posing component for Gradio apps using `gr.HTML` and Three.js (r160). It allows users to manipulate a 3D model's bones in real-time, adjust camera angles, apply aspect ratio cropping, and export the resulting pose map directly to the Python backend.

Perfect for AI image generation pipelines (like ControlNet or T2I-Adapter), reference posing, or any Gradio app requiring precise visual spatial conditioning.

Inspired by the Openart OpenPose Editor

## Features and Key Characteristics

- **Interactive 3D Viewport:** Full OrbitControls implementation (zoom, pan, rotate) and TransformControls for bone manipulation.
- **Client-Side Rendering via ESM:** Loads modern Three.js directly via CDN (`esm.sh`) dynamically. No heavy local Node.js builds required.
- **Built-in Undo/Redo System:** Autonomous history tracking for bone transformations (Rotation and Translation) with keyboard shortcuts (`Ctrl+Z`, `Ctrl+Shift+Z`).
- **Aspect Ratio Cropping:** Visual crop overlay with predefined aspect ratios (1:1, 16:9, 9:16, etc.) to frame the exact pose you need.
- **Direct Python Export:** clicking the export icon renders the cropped canvas and sends it directly to Gradio server as a PNG file path.
- **Theme Aware UI:** The floating toolbar completely integrates with Gradio's native light/dark mode CSS variables.

## Installation

```bash
pip install gradio-openpose3d-editor
```

## Usage

```py
import gradio as gr
from gradio_openpose3d_editor import OpenPose3DEditor

def process_pose(image_path: str):
    """
    Receives the PNG file path exported by the 3D editor.
    You can open it with PIL, pass it to ControlNet, etc.
    """
    if not image_path:
        return None
    return image_path

with gr.Blocks() as demo:
    gr.Markdown("# 🧍 3D OpenPose Editor")
    
    with gr.Row():
        # Initialize the 3D Editor
        editor = OpenPose3DEditor(
            #fbx_url="https://huggingface.co/buckets/elismasilva/assets/resolve/base.fbx?download=true",  here optional if you want a custom fbx model.
            height=560
        )
        
        # Output component to display the exported PNG
        preview = gr.Image(label="Exported Pose Map", type="filepath")
    
    # Listen to the 'export' event triggered by the floppy disk icon inside the component
    editor.export(
        fn=process_pose,
        inputs=editor,
        outputs=preview
    )
    
demo.launch()
```

## Component API

### Initialization Properties

| Property | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `fbx_url` | `str` | *Default URL* | Optional URL or relative path to the `.fbx` character model. |
| `height` | `int` | `540` | Height of the 3D viewport container in pixels. |
| `label` | `str \| None` | `None` | Optional label for the component. |
| `visible` | `bool` | `True` | Whether the component is visible on the screen. |
| `elem_id` | `str \| None` | `None` | Custom HTML ID for targeting with CSS or JavaScript. |
| `elem_classes` | `list[str] \| str \| None` | `None` | Additional CSS classes applied to the component wrapper. |

### Events

| Event | Description |
| :--- | :--- |
| `.export(fn, inputs, outputs, ...)` | Triggered when the user clicks the "Floppy Disk" export button in the UI. The component's `value` is automatically updated to the server-side file path (`str`) of the rendered PNG image, which is then passed to your Python function. |

## Acknowledgements / Credits

The default 3D model used in this component is provided under the CC BY 4.0 license:
* ["Base Mesh T Pose FBX"](https://skfb.ly/owXpQ) by [nuffylabz](https://sketchfab.com/nuffylabz) is licensed under [Creative Commons Attribution 4.0](http://creativecommons.org/licenses/by/4.0/).

---
Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference