The Problem Real‑estate video creation today requires manual camera planning, 3‑D reconstruction, and separate language models for description. The workflow is fragmented, error‑prone, and does not guarantee geometric consistency across the generated tour.

What This Does HouseTour combines three self‑contained components:

  • diffuser/ – a residual diffusion planner that refines sparse camera poses into smooth trajectories (diffuser/models/diffusion.py, diffuser/models/helpers.py).
  • qwen2_vl_3d/ – a vision‑language‑3D adapter that fuses image, text, and 3‑D tokens for real‑estate style summarisation (qwen2_vl_3d/modeling_qwen2_vl_3d.py).
  • scripts / eval_qwen2_vl_3d.py – inference utilities that load the trained models, render a 3‑D Gaussian‑splatting video, and produce the final description.

The dataset and model checkpoints are hosted externally (HouseTour Dataset, Hugging Face Space), while the code provides the pipeline to train or run inference on a local machine.

How It Is Wired Execution starts at eval_qwen2_vl_3d.py:main (line 253). The flow is:

  1. Argument parsing → parse_args (same file).
  2. Configuration → load_config (via diffuser/utils/setup.py) reads config/residual_diffuser.py.
  3. Model loading → load_qwen_with_diffuser calls the Qwen2‑VL‑3D class (qwen2_vl_3d/modeling_qwen2_vl_3d.py) and the diffusion planner (diffuser/models/diffusion.py).
  4. Trajectory generation → forward in diffuser/models/diffusion.py invokes helper functions (q_normalize, quaternion_matrix, catmull_rom_spline_with_rotation) defined in the same module and in diffuser/utils/transformations.py. These functions have the highest fan‑in (e.g., vector_norm, unit_vector called from 8 places each).
  5. Rendering → the generated pose sequence is passed to the 3‑D Gaussian splatter (external to the repo) and to the VLM for captioning.
  6. Output → the script writes the video and text files via standard open calls in diffuser/utils/config.py and diffuser/utils/serialization.py.

Key wiring observations:

  • The import cycle among diffuser/utils/__init__.py, diffuser/models/helpers.py, and diffuser/utils/training.py creates a circular dependency that can cause import‑time failures.
  • Functions such as vector_norm and unit_vector are hot spots (called from 8 distinct locations), so changes here have a wide blast radius.
  • qwen2_vl_3d/modeling_qwen2_vl_3d.py is an oversized module (≈1,600 lines) with deep nesting (max indentation depth 10), making it hard to reason about and maintain.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/HouseTour
cd HouseTour

# Install Python dependencies
pip install -r requirements.txt

# (Optional) Install the package in editable mode
python setup.py develop

The repository does not ship a setup.cfg or pyproject.toml; the only build artefacts are setup.py and requirements.txt. After installation, run inference on a local checkpoint:

python eval_qwen2_vl_3d.py \
  --config config/residual_diffuser.py \
  --output_dir ./results \
  --dataset_path data/trajectories.jsonl

The --config flag points to the diffusion planner configuration; --dataset_path supplies the JSON‑L file with sparse poses. No environment variables or secret keys are required by the code itself.

Real‑World Use A property‑listing platform could integrate the pipeline as a nightly batch job: ingest newly uploaded 360° image sets, call eval_qwen2_vl_3d.py to generate a smooth walkthrough video and a concise natural‑language summary, then store the artefacts in the platform’s media CDN. The only external dependency is the pre‑trained model checkpoint, which can be cached locally to avoid repeated downloads.

Code Health & Issues

  • HIGH – Missing license – no LICENSE file; default is all‑rights‑reserved, blocking reuse.
  • HIGH – No CI – repository lacks any GitHub Actions or other CI configuration; changes are not automatically built or tested.
  • MEDIUM – No dependency bot – only requirements.txt is present; without Dependabot or Renovate security patches are manual.
  • MEDIUM – Sparse test coverage – 2 test files cover ~4 % of source files; many critical modules are untested.

Additional static findings:

  • HIGH – Import cycles in diffuser/utils/__init__.py, diffuser/models/helpers.py, diffuser/utils/training.py.
  • HIGH – Deep nesting (max depth 10) in diffuser/datasets/cam_traj.py, diffuser/models/helpers.py, qwen2_vl_3d/modeling_qwen2_vl_3d.py.
  • HIGH – Oversized modules (>1,500 lines) in the same three files, increasing cognitive load.
  • MEDIUM – Files opened without a context manager (open(...) used directly) in diffuser/models/diffusion.py, diffuser/utils/serialization.py, diffuser/utils/config.py.
  • HIGH – Duplicated code blocks across helper and training utilities; DRY violations increase maintenance risk.

The Bottom Line HouseTour delivers a functional end‑to‑end pipeline for 3‑D‑aware real‑estate video generation, with clear entry points and modular code. However, the codebase suffers from import cycles, large monolithic files, and minimal test/CI infrastructure, which raise maintenance and reliability concerns. It is suitable for research or internal prototyping; production adoption will require refactoring, licensing clarification, and a robust CI/test process.