### Start Docker Container

Source: https://github.com/aiuniai/unique3d/blob/main/docker/README.md

Starts a previously created and stopped Docker container.

```bash
docker start unique3d
```

--------------------------------

### Launch Gradio Web Demo

Source: https://context7.com/aiuniai/unique3d/llms.txt

Starts the interactive local Gradio demo. Supports options for network access (--listen), public sharing (--share), and custom ports (--port).

```bash
# Minimal local launch on port 7860
python app/gradio_local.py --port 7860

# Expose to the local network (e.g., for Docker or remote machine)
python app/gradio_local.py --port 7860 --listen

# Create a public share link via Gradio
python app/gradio_local.py --port 7860 --share

# Behind a reverse proxy at /myapp
python app/gradio_local.py --port 7860 --gradio_root /myapp
```

--------------------------------

### launch() - Gradio Web Demo

Source: https://context7.com/aiuniai/unique3d/llms.txt

Starts the interactive local Gradio demo for Unique3D. Supports options for network access, public sharing, and custom ports.

```APIDOC
## launch() - Gradio Web Demo

### Description
Initializes all models and starts a Gradio Blocks UI with the 3D generation tab. This function allows for interactive use of the Unique3D system.

### Method
`launch()`

### Parameters
None directly in the function signature, but accepts command-line arguments:
- `--listen`: Bind to `0.0.0.0` for LAN access.
- `--share`: Create a public Gradio tunnel.
- `--port` (int): Set a custom port (default is 7860).
- `--gradio_root` (str): Set the Gradio root path (e.g., for reverse proxy).

### Request Example (Command Line)
```bash
# Minimal local launch on port 7860
python app/gradio_local.py --port 7860

# Expose to the local network (e.g., for Docker or remote machine)
python app/gradio_local.py --port 7860 --listen

# Create a public share link via Gradio
python app/gradio_local.py --port 7860 --share

# Behind a reverse proxy at /myapp
python app/gradio_local.py --port 7860 --gradio_root /myapp
```

### Request Example (Programmatic)
```python
import fire
from gradio_app import launch
fire.Fire(launch)
```

### Response
None (starts a web server).
```

--------------------------------

### Windows Setup Script for Unique3D

Source: https://github.com/aiuniai/unique3d/blob/main/README.md

A batch script to automate the installation of Unique3D on Windows with Python 3.11 and CUDA 12.1. This script requires Visual Studio Build Tools and a specific triton wheel file. It will prompt to uninstall and reinstall onnxruntime and onnxruntime-gpu.

```bat
@echo off

REM Create conda env and activate it
call conda create -n unique3d-py311 python=3.11 -y
call conda activate unique3d-py311

REM Download triton whl for py311 and put it into this project.
REM Example: triton-2.1.0-cp311-cp311-win_amd64.whl

REM Install triton
pip install triton-2.1.0-cp311-cp311-win_amd64.whl

REM Install other requirements
pip install ninja diffusers==0.27.2

REM Install mmcv-full
call pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu121/torch2.3.1/index.html

REM Install requirements.txt
pip install -r requirements.txt

REM Answer y while asking you uninstall onnxruntime and onnxruntime-gpu
call pip uninstall onnxruntime onnxruntime-gpu -y
call pip install onnxruntime-gpu

REM Create the output folder tmp\gradio under the driver root
REM Example: F:\tmp\gradio

REM Run the interactive inference locally
call python app/gradio_local.py --port 7860

echo "Installation complete. You can now run the gradio demo."
```

--------------------------------

### Linux System Setup for Unique3D

Source: https://github.com/aiuniai/unique3d/blob/main/README.md

Installs necessary dependencies for Unique3D on a Linux system with Ubuntu 22.04.4 LTS and CUDA 12.1. Ensure you have conda, ninja, and the specified versions of diffusers and mmcv-full installed.

```bash
conda create -n unique3d python=3.11
conda activate unique3d

pip install ninja
pip install diffusers==0.27.2

pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu121/torch2.3.1/index.html

pip install -r requirements.txt
```

--------------------------------

### run_mesh_refine

Source: https://context7.com/aiuniai/unique3d/llms.txt

Fine-detail geometry refinement guided by projected normals. This function refines mesh details at a finer edge resolution by periodically re-projecting multiview normal images onto the current mesh.

```APIDOC
## run_mesh_refine()

### Description
Fine-detail geometry refinement guided by projected normals. A second optimization loop that refines mesh details at a finer edge resolution. Unlike Stage 1, it periodically re-projects multiview normal images onto the current mesh and uses the result as a per-vertex normal target, enabling the mesh to capture fine surface detail.

### Parameters
- **vertices** (type not specified) - Description: Input vertices.
- **faces** (type not specified) - Description: Input faces.
- **pils** (type not specified) - Description: 4 × 512×512 RGBA normal images.
- **steps** (int) - Description: Number of refinement steps.
- **start_edge_len** (float) - Description: Initial edge length for refinement.
- **end_edge_len** (float) - Description: Final edge length for refinement.
- **decay** (float) - Description: Decay factor for edge length.
- **update_normal_interval** (int) - Description: Re-project normals every N steps.
- **update_warmup** (int) - Description: Always re-project for the first N steps.
- **return_mesh** (bool) - Description: Whether to return the mesh object.
- **process_inputs** (bool) - Description: Skip internal coordinate transform.
- **process_outputs** (bool) - Description: Skip internal coordinate transform.

### Request Example
```python
from mesh_reconstruction.refine import run_mesh_refine

vertices, faces = run_mesh_refine(
    vertices=vertices,
    faces=faces,
    pils=rm_normals,
    steps=100,
    start_edge_len=0.02,
    end_edge_len=0.005,
    decay=0.99,
    update_normal_interval=20,
    update_warmup=5,
    return_mesh=False,
    process_inputs=False,
    process_outputs=False,
)
```
```

--------------------------------

### Run Docker Container (First Time)

Source: https://github.com/aiuniai/unique3d/blob/main/docker/README.md

Runs the Docker container for the first time, mapping ports and enabling GPU access.

```bash
docker run -it --name unique3d -p 7860:7860 --gpus all unique3d python app.py
```

--------------------------------

### Initialize All Inference Pipelines

Source: https://context7.com/aiuniai/unique3d/llms.txt

Loads ControlNet + IP-Adapter Stable Diffusion 1.5 pipeline into GPU memory. Call this once before inference. It loads weights from ckpt/controlnet-tile/ and the base runwayml/stable-diffusion-v1-5 model.

```python
import os, sys, torch
os.environ['CUDA_VISIBLE_DEVICES'] = '0'
sys.path.append('.')
torch.set_float32_matmul_precision('medium')
torch.backends.cuda.matmul.allow_tf32 = True
torch.set_grad_enabled(False)

from app.all_models import model_zoo

# Loads controlnet-tile + IP-Adapter pipeline onto GPU
model_zoo.init_models()

# Access the loaded pipeline directly if needed
pipe = model_zoo.pipe_disney_controlnet_tile_ipadapter_i2i
print(type(pipe))
```

--------------------------------

### Run Local Gradio Demo for Unique3D

Source: https://github.com/aiuniai/unique3d/blob/main/README.md

Launches the interactive inference demo locally using Gradio. Ensure you have downloaded the model weights and extracted them into the 'ckpt' directory before running this command.

```bash
python app/gradio_local.py --port 7860
```

--------------------------------

### MyModelZoo.init_models()

Source: https://context7.com/aiuniai/unique3d/llms.txt

Loads all inference pipelines, including ControlNet + IP-Adapter Stable Diffusion 1.5, into GPU memory. This should be called once before any inference.

```APIDOC
## MyModelZoo.init_models()

### Description
Loads all inference pipelines into GPU memory. This includes the ControlNet + IP-Adapter Stable Diffusion 1.5 pipeline used for texture refinement. It loads weights from `ckpt/controlnet-tile/` and the base `runwayml/stable-diffusion-v1-5` model.

### Method
`MyModelZoo.init_models()`

### Parameters
None

### Request Example
```python
import os, sys, torch
os.environ['CUDA_VISIBLE_DEVICES'] = '0'
sys.path.append('.')
torch.set_float32_matmul_precision('medium')
torch.backends.cuda.matmul.allow_tf32 = True
torch.set_grad_enabled(False)

from app.all_models import model_zoo

# Loads controlnet-tile + IP-Adapter pipeline onto GPU
model_zoo.init_models()

# Access the loaded pipeline directly if needed
pipe = model_zoo.pipe_disney_controlnet_tile_ipadapter_i2i
print(type(pipe))
```

### Response
None (modifies global state by loading models).
```

--------------------------------

### Build Docker Image

Source: https://github.com/aiuniai/unique3d/blob/main/docker/README.md

Builds the Docker image for Unique3D. Ensure you are in the correct directory.

```bash
docker build -t unique3d -f Dockerfile .
```

--------------------------------

### simple_preprocess / expand2square

Source: https://context7.com/aiuniai/unique3d/llms.txt

Crop and pad input images. This function thumbnails the image, optionally removes the background, crops to the bounding box, and pads to a square.

```APIDOC
## simple_preprocess() / expand2square()

### Description
Crop and pad input images. `simple_preprocess` thumbnails the image to 2048px, optionally removes the background, then crops to the tight alpha bounding box and pads to a square with the specified background color — ensuring the object occupies the full image frame.

### Parameters
- **image** (PIL.Image.Image) - Description: The input image.
- **background_color** (tuple or str) - Description: The background color for padding.

### Request Example
```python
from PIL import Image
from scripts.utils import simple_preprocess

raw = Image.open("app/examples/bag.png")

# Example usage (assuming background_color is defined)
# processed_image = simple_preprocess(raw, background_color=(255, 255, 255))
```
```

--------------------------------

### Initialize Coarse Geometry from Normal Maps

Source: https://context7.com/aiuniai/unique3d/llms.txt

Builds an initial rough watertight mesh from front, back, and side normal maps using depth-from-normals and Poisson surface reconstruction. The `init_type` parameter controls depth scaling.

```python
from PIL import Image
from scripts.multiview_inference import fast_geo

front_normal = Image.open("/tmp/front_normal.png").resize((192, 192))
back_normal  = Image.open("/tmp/back_normal.png").resize((192, 192))
side_normal  = Image.open("/tmp/side_normal.png").resize((192, 192))

coarse_meshes = fast_geo(
    front_normal,
    back_normal,
    side_normal,
    clamp=0.,
    init_type="std",   # "std" | "thin" — controls depth scaling heuristic
)

from scripts.utils import from_py3d_mesh
verts, faces, _ = from_py3d_mesh(coarse_meshes)
print(verts.shape)   # e.g., torch.Size([N, 3]) on cuda
print(faces.shape)   # e.g., torch.Size([F, 3]) on cuda
```

--------------------------------

### Preprocess Images for 3D Generation

Source: https://context7.com/aiuniai/unique3d/llms.txt

Utility functions for cropping and padding input images to ensure the object occupies the full frame. `simple_preprocess` thumbnails, removes background, crops to bounding box, and pads to a square.

```python
from PIL import Image
from scripts.utils import simple_preprocess

raw = Image.open("app/examples/bag.png")


```

--------------------------------

### Preprocess Image for 3D Asset Creation

Source: https://context7.com/aiuniai/unique3d/llms.txt

Preprocesses a raw image to an RGBA format with a specified background color. Ensures the output image is square-cropped. Use this for initial image preparation before 3D reconstruction.

```python
preprocessed = simple_preprocess(raw, background_color=255)
print(preprocessed.mode)   # 'RGBA'
print(preprocessed.size)   # square, e.g., (512, 512)
```

--------------------------------

### run_mvprediction()

Source: https://context7.com/aiuniai/unique3d/llms.txt

Generates 4 orthographic RGB views from a single input image using a diffusion model. Optionally removes the background and preprocesses the image.

```APIDOC
## run_mvprediction()

### Description
Generates 4 orthographic RGB views (front, right, back, left) from a single input PIL image. The process includes optional background removal, image preprocessing to a square crop, and 30-step diffusion inference. It returns a list of 4 RGB PIL images and the preprocessed front view PIL image.

### Method
`run_mvprediction(input_image: Image.Image, remove_bg: bool = False, guidance_scale: float = 1.5, seed: int = -1) -> tuple[list[Image.Image], Image.Image]`

### Parameters
- **input_image** (PIL.Image.Image) - Required - The input image (RGB or RGBA).
- **remove_bg** (bool) - Optional - If True, automatically removes the background using `rembg`. Defaults to False.
- **guidance_scale** (float) - Optional - Guidance scale for diffusion inference. Defaults to 1.5.
- **seed** (int) - Optional - Random seed for reproducibility. Set to a positive integer for reproducible results, -1 for random. Defaults to -1.

### Request Example
```python
from PIL import Image
from app.custom_models.mvimg_prediction import run_mvprediction

input_image = Image.open("app/examples/anya.png")

# remove_bg=True: auto background removal via rembg
# seed=-1: random seed; set to a positive int for reproducibility
rgb_pils, front_pil = run_mvprediction(
    input_image,
    remove_bg=True,
    guidance_scale=1.5,
    seed=42,
)

print(len(rgb_pils))        # 4
print(rgb_pils[0].size)     # (256, 256)  — front view
print(front_pil.size)       # preprocessed input (square-cropped, RGBA with white bg)

# Save the multiview grid
from app.utils import make_image_grid
grid = make_image_grid(rgb_pils, rows=1)
grid.save("/tmp/multiview_grid.png")
```

### Response
- **rgb_pils** (list[PIL.Image.Image]) - A list containing 4 generated RGB PIL images (256x256) representing front, right, back, and left views.
- **front_pil** (PIL.Image.Image) - The preprocessed input image (square-cropped, RGBA with white background).
```

--------------------------------

### save_glb_and_video / save_py3dmesh_with_trimesh_fast

Source: https://context7.com/aiuniai/unique3d/llms.txt

Exports a textured mesh to a .glb file using trimesh. This function converts a PyTorch3D Meshes object to a .glb file, applying optional sRGB-to-linear color conversion and fixing vertex color metadata.

```APIDOC
## save_glb_and_video() / save_py3dmesh_with_trimesh_fast()

### Description
Exports a textured GLB file. Converts a PyTorch3D `Meshes` object to a `.glb` file using trimesh, applying optional sRGB-to-linear color conversion and fixing vertex color metadata for proper display in 3D viewers.

### Parameters
- **save_mesh_prefix** (str) - Description: Prefix for the saved GLB file.
- **meshes** (Meshes) - Description: The PyTorch3D Meshes object with textures.
- **with_timestamp** (bool) - Description: Appends Unix timestamp to the filename.
- **dist** (float) - Description: Camera distance for preview.
- **fov_in_degrees** (float) - Description: Field of view in degrees for preview.
- **cam_type** (str) - Description: Camera type for preview (e.g., 'ortho').
- **export_video** (bool) - Description: Whether to export a video.

### Request Example
```python
from scripts.utils import save_glb_and_video
from pytorch3d.structures import Meshes

# textured_mesh is a Py3D Meshes with TexturesVertex
glb_path, _ = save_glb_and_video(
    save_mesh_prefix="/tmp/gradio/my_object",
    meshes=textured_mesh,
    with_timestamp=True,
    dist=3.5,
    fov_in_degrees=2 / 1.35,
    cam_type="ortho",
    export_video=False,
)

print(glb_path)   # e.g., /tmp/gradio/my_object_1716000000.glb
```
```

--------------------------------

### Programmatic Gradio Launch

Source: https://context7.com/aiuniai/unique3d/llms.txt

Launches the Gradio application programmatically using the fire library.

```python
import fire
from gradio_app import launch
fire.Fire(launch)
```

--------------------------------

### Run Mesh Refinement with Projected Normals

Source: https://context7.com/aiuniai/unique3d/llms.txt

Fine-detail geometry refinement using projected normals as per-vertex targets. Re-projects multiview normal images periodically to capture fine surface detail.

```python
from mesh_reconstruction.refine import run_mesh_refine

vertices, faces = run_mesh_refine(
    vertices=vertices,
    faces=faces,
    pils=rm_normals,             # 4 × 512×512 RGBA normal images
    steps=100,
    start_edge_len=0.02,
    end_edge_len=0.005,
    decay=0.99,
    update_normal_interval=20,   # reproject normals every N steps
    update_warmup=5,             # always reproject for first N steps
    return_mesh=False,
    process_inputs=False,        # skip internal coordinate transform
    process_outputs=False,
)
```

--------------------------------

### Generate Multiview RGB Images

Source: https://context7.com/aiuniai/unique3d/llms.txt

Generates 4 orthographic RGB views (front, right, back, left) from a single input image. Optionally removes the background and preprocesses the image. Returns a list of PIL images for each view and the preprocessed front view.

```python
from PIL import Image
from app.custom_models.mvimg_prediction import run_mvprediction

input_image = Image.open("app/examples/anya.png")

# remove_bg=True: auto background removal via rembg
# seed=-1: random seed; set to a positive int for reproducibility
rgb_pils, front_pil = run_mvprediction(
    input_image,
    remove_bg=True,
    guidance_scale=1.5,
    seed=42,
)

print(len(rgb_pils))        # 4
print(rgb_pils[0].size)     # (256, 256)  — front view
print(front_pil.size)       # preprocessed input (square-cropped, RGBA with white bg)

# Save the multiview grid
from app.utils import make_image_grid
grid = make_image_grid(rgb_pils, rows=1)
grid.save("/tmp/multiview_grid.png")
```

--------------------------------

### Save Textured Mesh as GLB

Source: https://context7.com/aiuniai/unique3d/llms.txt

Converts a PyTorch3D Meshes object to a .glb file using trimesh, with options for sRGB-to-linear color conversion and vertex color metadata fixing.

```python
from scripts.utils import save_glb_and_video
from pytorch3d.structures import Meshes

# textured_mesh is a Py3D Meshes with TexturesVertex
glb_path, _ = save_glb_and_video(
    save_mesh_prefix="/tmp/gradio/my_object",
    meshes=textured_mesh,
    with_timestamp=True,    # appends Unix timestamp to filename
    dist=3.5,
    fov_in_degrees=2 / 1.35,
    cam_type="ortho",
    export_video=False,
)

print(glb_path)   # e.g., /tmp/gradio/my_object_1716000000.glb
```

--------------------------------

### run_sr_fast

Source: https://context7.com/aiuniai/unique3d/llms.txt

Upscales a list of PIL images by 4× using a cached RealESRGAN ONNX model. Accepts both PIL.Image and np.ndarray inputs.

```APIDOC
## run_sr_fast

### Description
Upscales a list of PIL images by 4× using a cached RealESRGAN ONNX model. The upsampler is cached globally after the first call. Accepts both `PIL.Image` and `np.ndarray` inputs.

### Parameters
- **pil_image_list** (list[PIL.Image] | list[np.ndarray]) - Required - A list of images to upscale.
- **scale** (int) - Optional - The scaling factor. Defaults to 4.

### Request Example
```python
from PIL import Image
from scripts.refine_lr_to_sr import run_sr_fast

low_res_images = [Image.open("app/examples/ex1.png")]  # e.g., 256×256

high_res_images = run_sr_fast(low_res_images, scale=4)

print(high_res_images[0].size)   # (1024, 1024) for a 256×256 input
```

### Response
#### Success Response (200)
- **high_res_images** (list[PIL.Image]) - A list of upscaled PIL images.
```

--------------------------------

### fast_geo

Source: https://context7.com/aiuniai/unique3d/llms.txt

Builds an initial front/back mesh from normal maps using depth-from-normals estimation and Poisson surface reconstruction.

```APIDOC
## fast_geo

### Description
Converts front, back, and side normal maps into a rough watertight mesh using depth-from-normals estimation and Poisson surface reconstruction via PyMeshLab. The result is the starting geometry for Stage 1 optimization.

### Parameters
- **front_normal** (PIL.Image) - Required - The front normal map.
- **back_normal** (PIL.Image) - Required - The back normal map.
- **side_normal** (PIL.Image) - Required - The side normal map.
- **clamp** (float) - Optional - Clamping value for depth estimation. Defaults to 0.0.
- **init_type** (str) - Optional - Controls depth scaling heuristic. Options: "std" | "thin". Defaults to "std".

### Request Example
```python
from PIL import Image
from scripts.multiview_inference import fast_geo

front_normal = Image.open("/tmp/front_normal.png").resize((192, 192))
back_normal  = Image.open("/tmp/back_normal.png").resize((192, 192))
side_normal  = Image.open("/tmp/side_normal.png").resize((192, 192))

coarse_meshes = fast_geo(
    front_normal,
    back_normal,
    side_normal,
    clamp=0.,
    init_type="std",   # "std" | "thin" — controls depth scaling heuristic
)

from scripts.utils import from_py3d_mesh
verts, faces, _ = from_py3d_mesh(coarse_meshes)
print(verts.shape)   # e.g., torch.Size([N, 3]) on cuda
print(faces.shape)   # e.g., torch.Size([F, 3]) on cuda
```

### Response
#### Success Response (200)
- **coarse_meshes** (object) - The resulting coarse mesh object.
```

--------------------------------

### Super-Resolution Upsampling with RealESRGAN-x4 ONNX

Source: https://context7.com/aiuniai/unique3d/llms.txt

Upscales a list of PIL images by 4x using a cached RealESRGAN ONNX model. Accepts PIL.Image and np.ndarray inputs. The upsampler is cached globally.

```python
from PIL import Image
from scripts.refine_lr_to_sr import run_sr_fast

low_res_images = [Image.open("app/examples/ex1.png")]  # e.g., 256×256

high_res_images = run_sr_fast(low_res_images, scale=4)

print(high_res_images[0].size)   # (1024, 1024) for a 256×256 input
```

--------------------------------

### generate3dv2

Source: https://context7.com/aiuniai/unique3d/llms.txt

Complete single-image-to-3D pipeline. This is the top-level function exposed as the Gradio API endpoint. It accepts a PIL image and runs the necessary steps to generate a 3D model.

```APIDOC
## generate3dv2()

### Description
Complete single-image-to-3D pipeline. The top-level function exposed as the Gradio API endpoint (`api_name="generate3dv2"`). Accepts a PIL image, runs SR if needed, calls `run_mvprediction`, `geo_reconstruct`, and `save_glb_and_video` in sequence. Can be called programmatically via the Gradio Python client.

### Parameters
- **preview_img** (PIL.Image.Image) - Description: The input image.
- **input_processing** (bool) - Description: Automatically remove background.
- **seed** (int) - Description: Random seed for generation.
- **render_video** (bool) - Description: Whether to render a video.
- **do_refine** (bool) - Description: Run SD-based multiview texture refinement.
- **expansion_weight** (float) - Description: Mesh expansion loss weight.
- **init_type** (str) - Description: Initialization type ('std', 'thin', or 'ball').

### Request Example
```python
from PIL import Image
from app.gradio_3dgen import generate3dv2
from app.all_models import model_zoo

# Must initialize models first
model_zoo.init_models()

input_image = Image.open("app/examples/hatsune_miku.png")

glb_path, video_path = generate3dv2(
    preview_img=input_image,
    input_processing=True,
    seed=42,
    render_video=False,
    do_refine=True,
    expansion_weight=0.1,
    init_type="std",
)

print(glb_path)   # /tmp/gradio/generated_<timestamp>.glb
```

### Remote Call Example (Gradio Client)
```python
# Remote call via Gradio Python client (server must be running)
from gradio_client import Client

client = Client("http://localhost:7860")
result = client.predict(
    Image.open("app/examples/anya.png"),
    True,    # remove_bg
    42,      # seed
    False,   # render_video
    True,    # do_refine
    0.1,     # expansion_weight
    "std",   # init_type
    api_name="/generate3dv2"
)
gl_path, video_path = result
```
```

--------------------------------

### refine_lr_with_sd

Source: https://context7.com/aiuniai/unique3d/llms.txt

Refines multiview textures using Stable Diffusion img2img, conditioned on ControlNet and IP-Adapter, to enhance texture quality.

```APIDOC
## refine_lr_with_sd

### Description
Refines multiview textures using a Stable Diffusion img2img pass conditioned on a ControlNet tile image and an IP-Adapter concept image to enhance texture quality across the multiview grid. Used internally by `refine_rgb()` within `geo_reconstruct`.

### Parameters
- **pil_image_list** (list[PIL.Image]) - Required - A list containing a single PIL image representing the grid of low-resolution RGB views.
- **concept_img_list** (list[PIL.Image]) - Required - A list containing a single preprocessed front image (RGBA).
- **control_image_list** (list[PIL.Image]) - Required - A list containing a single control image (e.g., tiled ControlNet image).
- **prompt_list** (list[str]) - Required - A list of prompts to guide the refinement.
- **neg_prompt_list** (list[str]) - Required - A list of negative prompts to guide the refinement.
- **pipe** (object) - Required - The Stable Diffusion pipeline to use (e.g., `model_zoo.pipe_disney_controlnet_tile_ipadapter_i2i`).
- **strength** (float) - Optional - The strength of the diffusion process. Defaults to 0.2.
- **output_size** (tuple[int, int]) - Optional - The desired output size of the refined grid. Defaults to (1024, 1024).

### Request Example
```python
from PIL import Image
from scripts.refine_lr_to_sr import refine_lr_with_sd
from app.all_models import model_zoo
from app.utils import make_image_grid, rgba_to_rgb, split_image

# model_zoo must already be initialized
rgb_pils_256 = [...]          # 4 × 256×256 PIL images from run_mvprediction
front_pil    = [...]          # preprocessed front image (RGBA)

rgb_grid = make_image_grid(rgb_pils_256, rows=2)         # 512×512 grid
control  = rgb_grid.resize((1024, 1024))

refined_grid = refine_lr_with_sd(
    pil_image_list=[rgb_grid],
    concept_img_list=[rgba_to_rgb(front_pil)],
    control_image_list=[control],
    prompt_list=["4views, multiview"],
    neg_prompt_list=["sketch, lowres, bad anatomy, worst quality"],
    pipe=model_zoo.pipe_disney_controlnet_tile_ipadapter_i2i,
    strength=0.2,
    output_size=(1024, 1024),
)[0]

refined_views = split_image(refined_grid, rows=2)        # back to 4 × 512×512
```

### Response
#### Success Response (200)
- **refined_grid** (PIL.Image) - The refined image grid.
```

--------------------------------

### Predict Normals from Multiview Images

Source: https://context7.com/aiuniai/unique3d/llms.txt

Resizes input images to 512x512 and predicts surface normals using a specified model. Ensure the model is loaded and input images are in PIL format.

```python
view_images = [img.resize((512, 512)) for img in rgb_pils]

normals = predict_normals(
    view_images,
    guidance_scale=1.5,
    do_rotate=True,          # rotate normals back to world coords per view
    num_inference_steps=30,
)

print(len(normals))          # 4
print(normals[0].mode)       # 'RGBA'
print(normals[0].size)       # (512, 512)

# Inspect the front normal map
normals[0].save("/tmp/front_normal.png")
```

--------------------------------

### Expand Image to Square with Custom Background

Source: https://context7.com/aiuniai/unique3d/llms.txt

Expands an image to a square aspect ratio while filling the added space with a specified background color. This function can be called independently. Ensure the input image is converted to 'RGB' if it's not already.

```python
from scripts.utils import expand2square
padded = expand2square(raw.convert("RGB"), background_color=(255, 255, 255))
print(padded.size[0] == padded.size[1])  # True
```

--------------------------------

### Refine Multiview Textures with Stable Diffusion

Source: https://context7.com/aiuniai/unique3d/llms.txt

Enhances texture quality across multiview images using a Stable Diffusion img2img pass conditioned on ControlNet and IP-Adapter. Requires pre-initialized models and specific image preprocessing.

```python
from PIL import Image
from scripts.refine_lr_to_sr import refine_lr_with_sd
from app.all_models import model_zoo
from app.utils import make_image_grid, rgba_to_rgb, split_image

# model_zoo must already be initialized
rgb_pils_256 = [...]          # 4 × 256×256 PIL images from run_mvprediction
front_pil    = [...]          # preprocessed front image (RGBA)

rgb_grid = make_image_grid(rgb_pils_256, rows=2)         # 512×512 grid
control  = rgb_grid.resize((1024, 1024))

refined_grid = refine_lr_with_sd(
    pil_image_list=[rgb_grid],
    concept_img_list=[rgba_to_rgb(front_pil)],
    control_image_list=[control],
    prompt_list=["4views, multiview"],
    neg_prompt_list=["sketch, lowres, bad anatomy, worst quality"],
    pipe=model_zoo.pipe_disney_controlnet_tile_ipadapter_i2i,
    strength=0.2,
    output_size=(1024, 1024),
)[0]

refined_views = split_image(refined_grid, rows=2)        # back to 4 × 512×512
```

--------------------------------

### Multiview Color Projection for Vertex Colors

Source: https://context7.com/aiuniai/unique3d/llms.txt

Projects pixel colors from orthographic view images onto a 3D mesh's vertices, handling occlusion and blending contributions. Optionally fills unseen vertices using Laplacian color diffusion.

```python
from scripts.project_mesh import multiview_color_projection, get_cameras_list
from scripts.utils import simple_clean_mesh, to_pyml_mesh

# Clean and subdivide the optimized mesh
clean = simple_clean_mesh(
    to_pyml_mesh(vertices, faces),
    apply_smooth=True,
    stepsmoothnum=1,
    apply_sub_divide=True,
    sub_divide_threshold=0.25,
).to("cuda")

cameras = get_cameras_list([0, 90, 180, 270], device="cuda", focal=1)

textured_mesh = multiview_color_projection(
    meshes=clean,
    image_list=img_list,              # 4 × PIL images (high-res RGBA)
    cameras_list=cameras,
    resolution=1024,
    device="cuda",
    complete_unseen=True,             # fill unseen verts via Laplacian diffusion
    confidence_threshold=0.2,
    reweight_with_cosangle="square",  # down-weight grazing-angle projections
)
```

--------------------------------

### Execute Command in Docker Container

Source: https://github.com/aiuniai/unique3d/blob/main/docker/README.md

Executes a Python script within a running Docker container.

```bash
docker exec unique3d python app.py
```

--------------------------------

### Stop Docker Container

Source: https://github.com/aiuniai/unique3d/blob/main/docker/README.md

Stops a running Docker container.

```bash
docker stop unique3d
```

--------------------------------

### End-to-End 3D Generation Pipeline

Source: https://context7.com/aiuniai/unique3d/llms.txt

The main pipeline function that accepts a PIL image and orchestrates SR, multiview prediction, geometry reconstruction, and mesh saving. Can be called programmatically or via Gradio API.

```python
from PIL import Image
from app.gradio_3dgen import generate3dv2
from app.all_models import model_zoo

# Must initialize models first
model_zoo.init_models()

input_image = Image.open("app/examples/hatsune_miku.png")

glb_path, video_path = generate3dv2(
    preview_img=input_image,
    input_processing=True,  # remove background automatically
    seed=42,
    render_video=False,
    do_refine=True,          # run SD-based multiview texture refinement
    expansion_weight=0.1,    # mesh expansion loss weight
    init_type="std",         # "std" | "thin" | "ball"
)

print(glb_path)   # /tmp/gradio/generated_<timestamp>.glb
```

```python
# Remote call via Gradio Python client (server must be running)
from gradio_client import Client

client = Client("http://localhost:7860")
result = client.predict(
    Image.open("app/examples/anya.png"),
    True,    # remove_bg
    42,      # seed
    False,   # render_video
    True,    # do_refine
    0.1,     # expansion_weight
    "std",   # init_type
    api_name="/generate3dv2"
)
glb_path, video_path = result
```

--------------------------------

### reconstruct_stage1

Source: https://context7.com/aiuniai/unique3d/llms.txt

Optimizes mesh geometry over specified iterations using a differentiable normal renderer and MeshOptimizer.

```APIDOC
## reconstruct_stage1

### Description
Optimizes mesh geometry over `steps` iterations using a differentiable normal renderer (`NormalsRenderer`) and `MeshOptimizer`. Minimizes L2 loss between rendered normals and target normal images, plus an expansion loss and out-of-bounds penalty. Automatic remeshing is applied each iteration to maintain well-formed geometry.

### Parameters
- **pils** (list[PIL.Image]) - Required - A list of RGBA normal PIL images (e.g., 4 × 512×512).
- **steps** (int) - Required - The number of optimization iterations.
- **vertices** (torch.Tensor) - Optional - Initial mesh vertices. Defaults to None.
- **faces** (torch.Tensor) - Optional - Initial mesh faces. Defaults to None.
- **start_edge_len** (float) - Optional - The starting edge length for remeshing. Defaults to 0.1.
- **end_edge_len** (float) - Optional - The ending edge length for remeshing. Defaults to 0.02.
- **gain** (float) - Optional - Gain parameter for optimization. Defaults to 0.05.
- **return_mesh** (bool) - Optional - If True, returns Py3D Meshes; otherwise, returns (verts, faces). Defaults to False.
- **loss_expansion_weight** (float) - Optional - Weight for the expansion loss to prevent mesh collapse. Defaults to 0.1.

### Request Example
```python
from mesh_reconstruction.recon import reconstruct_stage1

# verts/faces from fast_geo, already on CUDA
vertices, faces = reconstruct_stage1(
    pils=normal_stg1,           # list of 4 × 512×512 RGBA normal PIL images
    steps=200,
    vertices=verts,
    faces=faces,
    start_edge_len=0.1,
    end_edge_len=0.02,
    gain=0.05,
    return_mesh=False,          # True → returns Py3D Meshes; False → (verts, faces)
    loss_expansion_weight=0.1,  # weight on expansion loss to prevent mesh collapse
)
# vertices: torch.Tensor [N, 3], faces: torch.Tensor [F, 3]
```

### Response
#### Success Response (200)
- **vertices** (torch.Tensor) - The optimized mesh vertices.
- **faces** (torch.Tensor) - The optimized mesh faces.
```

--------------------------------

### Predict Surface Normal Maps

Source: https://context7.com/aiuniai/unique3d/llms.txt

Predicts surface normal maps for each of the 4 multiview RGB images. Outputs are RGBA images encoding surface normals in world coordinates, with automatic Y-axis rotation applied.

```python
from PIL import Image
from app.custom_models.normal_prediction import predict_normals

```

--------------------------------

### predict_normals()

Source: https://context7.com/aiuniai/unique3d/llms.txt

Predicts surface normal maps for each of the 4 multiview RGB images.

```APIDOC
## predict_normals()

### Description
Predicts surface normal maps for a given list of 4 multiview RGB images (512x512). This function uses a diffusion-based normal estimator and outputs RGBA images where the RGB channels encode surface normals in world coordinates. It includes automatic per-view Y-axis rotation.

### Method
`predict_normals(rgb_pils: list[Image.Image]) -> list[Image.Image]`

### Parameters
- **rgb_pils** (list[PIL.Image.Image]) - Required - A list containing 4 multiview RGB PIL images (512x512) generated by `run_mvprediction`.

### Request Example
```python
from PIL import Image
from app.custom_models.normal_prediction import predict_normals

# Assuming rgb_pils is a list of 4 PIL images (512x512) from run_mvprediction
# For example:
# rgb_pils, _ = run_mvprediction(input_image, remove_bg=True)
# For demonstration, let's assume rgb_pils is already populated
# rgb_pils = [Image.new('RGB', (512, 512), color = 'red') for _ in range(4)] # Placeholder

# normal_maps = predict_normals(rgb_pils)
# print(len(normal_maps)) # Should be 4
# print(normal_maps[0].size) # Should be (512, 512)
```

### Response
- **normal_maps** (list[Image.Image]) - A list containing 4 RGBA PIL images, where each image represents the predicted surface normal map for the corresponding input view.
```

--------------------------------

### multiview_color_projection

Source: https://context7.com/aiuniai/unique3d/llms.txt

Projects pixel colors from a list of orthographic view images onto a 3D mesh's vertices. Handles occlusion, blends contributions, and optionally fills unseen vertices.

```APIDOC
## multiview_color_projection()

### Description
Projects pixel colors from a list of orthographic view images onto a 3D mesh's vertices. Handles occlusion via `nvdiffrast` rasterization, blends contributions weighted by view angle and confidence, and optionally fills unseen vertices using Laplacian color diffusion.

### Parameters
- **meshes** (type not specified) - Description: The input mesh object.
- **image_list** (list) - Description: A list of PIL images (high-res RGBA).
- **cameras_list** (list) - Description: A list of camera objects.
- **resolution** (int) - Description: The resolution for projection.
- **device** (str) - Description: The device to use (e.g., 'cuda').
- **complete_unseen** (bool) - Description: Fill unseen vertices via Laplacian diffusion.
- **confidence_threshold** (float) - Description: Confidence threshold for blending.
- **reweight_with_cosangle** (str) - Description: Reweighting method for view angle (e.g., 'square').

### Request Example
```python
from scripts.project_mesh import multiview_color_projection, get_cameras_list
from scripts.utils import simple_clean_mesh, to_pyml_mesh

# Clean and subdivide the optimized mesh
clean = simple_clean_mesh(
    to_pyml_mesh(vertices, faces),
    apply_smooth=True,
    stepsmoothnum=1,
    apply_sub_divide=True,
    sub_divide_threshold=0.25,
).to("cuda")

cameras = get_cameras_list([0, 90, 180, 270], device="cuda", focal=1)

textured_mesh = multiview_color_projection(
    meshes=clean,
    image_list=img_list,
    cameras_list=cameras,
    resolution=1024,
    device="cuda",
    complete_unseen=True,
    confidence_threshold=0.2,
    reweight_with_cosangle="square",
)
```
```

--------------------------------

### Stage 1 Differentiable Mesh Optimization

Source: https://context7.com/aiuniai/unique3d/llms.txt

Optimizes mesh geometry over a specified number of iterations using a differentiable normal renderer and optimizer. Includes expansion loss and out-of-bounds penalty, with automatic remeshing.

```python
from mesh_reconstruction.recon import reconstruct_stage1

# verts/faces from fast_geo, already on CUDA
vertices, faces = reconstruct_stage1(
    pils=normal_stg1,           # list of 4 × 512×512 RGBA normal PIL images
    steps=200,
    vertices=verts,
    faces=faces,
    start_edge_len=0.1,
    end_edge_len=0.02,
    gain=0.05,
    return_mesh=False,          # True → returns Py3D Meshes; False → (verts, faces)
    loss_expansion_weight=0.1,  # weight on expansion loss to prevent mesh collapse
)
# vertices: torch.Tensor [N, 3], faces: torch.Tensor [F, 3]
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.