Skip to content

README.md

Latest commit

 

History

History
96 lines (69 loc) · 3.81 KB

README.md

File metadata and controls

96 lines (69 loc) · 3.81 KB

WorldMirror Examples

This directory contains usage examples for HY-WorldMirror-2.0, a single-step multi-head 3D reconstruction model (depth / normal / camera / points / Gaussian splats) served through the LightX2V runner.

Benchmark Results

Qwen-Image-Edit-2511

Model Download

Before using the example scripts, you need to download the corresponding weights. The model can be downloaded from the following address:

3D Reconstruction Model

The downloaded directory should contain a HY-WorldMirror-2.0/ subfolder with model.safetensors and config.json inside.

Usage Method 1: Using Bash Scripts (Highly Recommended)

For environment setup, we recommend using our Docker image. Please refer to the Quick Start Guide.

git clone https://github.com/ModelTC/LightX2V.git
cd LightX2V/scripts/worldmirror

# Before running the scripts below, override MODEL_PATH / INPUT_PATH / SAVE_RESULT_PATH via
# environment variables, or edit the defaults at the top of the script.
# For example: export MODEL_PATH=/home/user/models/HY-World-2.0
# For example: export INPUT_PATH=/home/user/inputs/Workspace

3D Reconstruction Models

# Inference with the fp32 reconstruction model (default precision, 1e-3 MAE vs. upstream reference)
bash run_worldmirror_recon.sh

# Inference with the fp8-pertensor quantized model, saves ~0.6 GB GPU peak at slightly faster speed
# (1e-2 MAE vs. reference). Requires the calibrated input-scale file bundled under
# configs/worldmirror/worldmirror_input_scales.safetensors — already referenced from the config.
bash run_worldmirror_recon_fp8.sh

Both scripts default to RENDER_VIDEO=1, which also renders a Gaussian-splat flythrough video into <SAVE_RESULT_PATH>/<case>/<timestamp>/rendered/rendered_rgb.mp4. Set RENDER_VIDEO=0 to skip it, or RENDER_DEPTH=1 to additionally render a depth flythrough.

Usage Method 2: Install and Use Python Scripts

For environment setup, we recommend using our Docker image. Please refer to the Quick Start Guide.

First, clone the repository and install dependencies:

git clone https://github.com/ModelTC/LightX2V.git
cd LightX2V
pip install -v -e .

Running the Reconstruction Model (fp32)

Run the test_worldmirror.py script, which wraps the LightX2V runner with the default fp32 config:

cd examples/worldmirror/
python test_worldmirror.py \
    --model_path /path/to/HY-World-2.0 \
    --input_path /path/to/scene_dir \
    --output_path /path/to/output

This is the highest-accuracy path (matches the upstream HY-World-2.0 pipeline within 1e-3 MAE on depth / normal and 1% on point cloud bounding volume).

Running the Reconstruction Model + FP8 Quantization

Run the same entry point with the fp8 config to enable per-tensor fp8 quantization on the covered linear layers:

cd examples/worldmirror/
python test_worldmirror.py \
    --config_path /workspace/LightX2V/configs/worldmirror/worldmirror_recon_fp8.json \
    --model_path /path/to/HY-World-2.0 \
    --input_path /path/to/scene_dir \
    --output_path /path/to/output

For the full CLI surface (per-head disable, mask controls, prior camera/depth inputs, Gaussian-splat flythrough rendering, interactive >>> loop), use run_worldmirror.py instead — it mirrors the original python -m hyworld2.worldrecon.pipeline entry point flag-for-flag:

python run_worldmirror.py \
    --input_path /path/to/scene_dir \
    --pretrained_model_name_or_path /path/to/HY-World-2.0 \
    --lightx2v_config /workspace/LightX2V/configs/worldmirror/worldmirror_recon_fp8.json \
    --save_rendered --no_interactive