Skip to content

[SIGGRAPH Asia 2026] 4DAnyone: Create Anyone in 4D from a Casual Monocular Video

Route multi-layer cameras on a global TCR ring (#23)

Yudong Jin6675d29468a6
diff --git a/fdanyone/model/distributed.py b/fdanyone/model/distributed.py
index a393e17..e1358c9 100644
--- a/fdanyone/model/distributed.py
+++ b/fdanyone/model/distributed.py
@@ -21,6 +21,7 @@ from pathlib import Path
from typing import TYPE_CHECKING, TypedDict
from fdanyone.errors import FourDAnyoneError
+from fdanyone.model.routing import CameraGroup, Routes, StepGroups, validate_routes
if TYPE_CHECKING:
from torch import Tensor
@@ -31,10 +32,6 @@ if TYPE_CHECKING:
LOGGER = logging.getLogger("fdanyone")
-CameraGroup = tuple[int, ...]
-StepGroups = tuple[CameraGroup, ...]
-Routes = tuple[StepGroups, ...]
-
class WorkerReport(TypedDict):
"""Per-rank measurements published by a distributed denoising worker."""
@@ -90,28 +87,6 @@ def group_waves(groups: Sequence[CameraGroup], num_workers: int) -> tuple[StepGr
return tuple(tuple(groups[start : start + num_workers]) for start in range(0, len(groups), num_workers))
-def validate_routes(routes: Routes, num_views: int) -> None:
- """Require every routing step to be a disjoint canonical camera partition."""
-
- expected = list(range(num_views))
- if not routes:
- raise ValueError("Distributed denoising requires at least one routing step.")
- if not routes[0] or not routes[0][0]:
- raise ValueError("Distributed denoising requires non-empty camera groups.")
- num_groups = len(routes[0])
- group_size = len(routes[0][0])
- for step_index, groups in enumerate(routes):
- if len(groups) != num_groups:
- raise ValueError(f"Routing step {step_index} has {len(groups)} groups; every step must have {num_groups}.")
- if any(len(group) != group_size for group in groups):
- raise ValueError(f"Routing step {step_index} contains camera groups with inconsistent sizes.")
- flattened = sorted(camera for group in groups for camera in group)
- if flattened != expected:
- raise ValueError(
- f"Routing step {step_index} is not a disjoint partition of cameras 0..{num_views - 1}: {groups}."
- )
-
-
def _free_local_port() -> int:
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
sock.bind(("127.0.0.1", 0))
diff --git a/fdanyone/model/inference.py b/fdanyone/model/inference.py
index 2b8e6c5..1429acb 100644
--- a/fdanyone/model/inference.py
+++ b/fdanyone/model/inference.py
@@ -28,14 +28,13 @@ from fdanyone.model.conditioning import (
)
from fdanyone.model.denoise import denoise_group
from fdanyone.model.distributed import (
- Routes,
WorkerReport,
denoise_targets_distributed,
select_worker_devices,
)
from fdanyone.model.loader import Denoiser, load_denoiser
from fdanyone.model.metrics import GenerationMetrics
-from fdanyone.model.routing import routing_steps
+from fdanyone.model.routing import Routes, routing_steps, validate_routes
from fdanyone.model.vae import VaeExecutor, load_reference_videos
from fdanyone.skeleton.pipeline import Conditioning
from fdanyone.video import CanonicalClip
@@ -218,6 +217,7 @@ def _denoise_targets_single(
raise FourDAnyoneError(
f"Target generation requires {num_views} pose features, got {pose_features.num_features}."
)
+ validate_routes(routes, num_views)
num_timesteps = len(denoiser.scheduler.timesteps)
if len(routes) != num_timesteps:
raise FourDAnyoneError(
@@ -361,11 +361,8 @@ def _merge_view_stage_peak(metrics: GenerationMetrics, stage: str, vae: VaeExecu
def _target_routes(*, view_plan: ViewPlan, profile: DenoisingProfile) -> Routes:
return routing_steps(
- views_per_layer=view_plan.views_per_layer,
- num_layers=view_plan.num_layers,
- group_size=view_plan.views_per_group,
+ view_plan=view_plan,
num_steps=profile.num_inference_steps,
- enable_tcr=view_plan.enable_tcr,
tcr_stride=profile.tcr_stride,
freeze_after_one_cycle=profile.freeze_tcr_after_one_cycle,
)
diff --git a/fdanyone/model/routing.py b/fdanyone/model/routing.py
index 3621411..7bfa089 100644
--- a/fdanyone/model/routing.py
+++ b/fdanyone/model/routing.py
@@ -1,65 +1,126 @@
-"""Target-context routing across view groups."""
+"""Map canonical target cameras onto cyclic denoising groups."""
from __future__ import annotations
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
-def _validate_grouping(num_views: int, group_size: int) -> int:
- if num_views <= 0 or group_size <= 0 or num_views % group_size:
- raise ValueError(f"num_views={num_views} must be divisible by positive group_size={group_size}.")
- return num_views // group_size
+if TYPE_CHECKING:
+ from fdanyone.views import ViewPlan
+
+CameraOrder = tuple[int, ...]
+CameraGroup = tuple[int, ...]
+StepGroups = tuple[CameraGroup, ...]
+Routes = tuple[StepGroups, ...]
+
+
+def denoising_camera_order(view_plan: ViewPlan) -> CameraOrder:
+ """Return one deterministic cycle over the plan's canonical camera IDs.
+
+ A single layer keeps its public yaw order. Multiple layers form a
+ Hamiltonian cycle in the open pitch-by-yaw grid, so partial yaw layouts do
+ not need a false edge between their horizontal endpoints.
+ """
+
+ views_per_layer = view_plan.views_per_layer
+ num_layers = view_plan.num_layers
+ if views_per_layer <= 0 or num_layers <= 0:
+ raise ValueError("A denoising camera order requires a non-empty resolved view plan.")
+ if len(set(view_plan.layer_pitches)) != num_layers:
+ raise ValueError("A denoising camera order requires distinct pitch layers.")
+ if num_layers == 1:
+ return tuple(range(views_per_layer))
+ if views_per_layer % 2:
+ raise ValueError("A multi-layer camera ring requires an even number of views per layer.")
+
+ # Public IDs follow input layer order. Physical vertical neighbors follow
+ # pitch order, so this mapping changes traversal without changing identity.
+ layers_by_pitch = tuple(sorted(range(num_layers), key=view_plan.layer_pitches.__getitem__))
+
+ def camera_id(pitch_rank: int, yaw_index: int) -> int:
+ return layers_by_pitch[pitch_rank] * views_per_layer + yaw_index
+
+ # Reserve the lowest-pitch row as the return lane: descend the first yaw
+ # column, snake through the remaining rows, then traverse that row backward.
+ order = [camera_id(pitch_rank, 0) for pitch_rank in range(num_layers)]
+ for yaw_index in range(1, views_per_layer):
+ pitch_ranks = range(num_layers - 1, 0, -1) if yaw_index % 2 else range(1, num_layers)
+ order.extend(camera_id(pitch_rank, yaw_index) for pitch_rank in pitch_ranks)
+ order.extend(camera_id(0, yaw_index) for yaw_index in range(views_per_layer - 1, 0, -1))
+ return tuple(order)
-def view_groups(
- num_views: int,
+
+def cyclic_groups(
+ camera_order: Sequence[int],
group_size: int,
offset: int = 0,
-) -> tuple[tuple[int, ...], ...]:
- """Partition one camera layer into cyclically shifted groups."""
+) -> StepGroups:
+ """Partition a cyclic camera order into equally sized consecutive groups."""
- num_groups = _validate_grouping(num_views, group_size)
+ order = tuple(camera_order)
+ num_views = len(order)
+ if num_views <= 0 or group_size <= 0 or num_views % group_size:
+ raise ValueError(f"{num_views} cameras must be divisible by positive group_size={group_size}.")
return tuple(
- tuple((group_index * group_size + offset + local_index) % num_views for local_index in range(group_size))
- for group_index in range(num_groups)
+ tuple(order[(group_start + offset + local_index) % num_views] for local_index in range(group_size))
+ for group_start in range(0, num_views, group_size)
)
def routing_steps(
*,
- views_per_layer: int,
- num_layers: int,
- group_size: int,
+ view_plan: ViewPlan,
num_steps: int,
- enable_tcr: bool,
tcr_stride: int = 1,
freeze_after_one_cycle: bool = False,
-) -> tuple[tuple[tuple[int, ...], ...], ...]:
- """Return layer-local target groups for every denoising step."""
+) -> Routes:
+ """Return fixed or TCR-shifted partitions of one global camera ring."""
if num_steps <= 0:
raise ValueError(f"num_steps must be positive, got {num_steps}.")
- if num_layers <= 0:
- raise ValueError(f"num_layers must be positive, got {num_layers}.")
if tcr_stride <= 0:
raise ValueError(f"tcr_stride must be positive, got {tcr_stride}.")
- _validate_grouping(views_per_layer, group_size)
+ camera_order = denoising_camera_order(view_plan)
def step_offset(step_index: int) -> int:
- if not enable_tcr:
+ if not view_plan.enable_tcr:
return 0
offset = step_index * tcr_stride
- if freeze_after_one_cycle and offset >= group_size:
+ if freeze_after_one_cycle and offset >= view_plan.views_per_group:
return 0
return offset
return tuple(
- tuple(
- tuple(layer_index * views_per_layer + view_index for view_index in group)
- for layer_index in range(num_layers)
- for group in view_groups(
- views_per_layer,
- group_size,
- step_offset(step_index),
- )
+ cyclic_groups(
+ camera_order,
+ view_plan.views_per_group,
+ step_offset(step_index),
)
for step_index in range(num_steps)
)
+
+
+def validate_routes(routes: Routes, num_views: int) -> None:
+ """Require every routing step to be an equal partition of canonical IDs."""
+
+ if num_views <= 0:
+ raise ValueError(f"Target denoising requires a positive camera count, got {num_views}.")
+ if not routes:
+ raise ValueError("Target denoising requires at least one routing step.")
+ if not routes[0] or not routes[0][0]:
+ raise ValueError("Target denoising requires non-empty camera groups.")
+
+ num_groups = len(routes[0])
+ group_size = len(routes[0][0])
+ expected_ids = list(range(num_views))
+ for step_index, groups in enumerate(routes):
+ if len(groups) != num_groups:
+ raise ValueError(f"Routing step {step_index} has {len(groups)} groups; every step must have {num_groups}.")
+ if any(len(group) != group_size for group in groups):
+ raise ValueError(f"Routing step {step_index} contains camera groups with inconsistent sizes.")
+ camera_ids = sorted(camera_id for group in groups for camera_id in group)
+ if camera_ids != expected_ids:
+ raise ValueError(
+ f"Routing step {step_index} is not a disjoint partition of cameras 0..{num_views - 1}: {groups}."
+ )
diff --git a/fdanyone/output.py b/fdanyone/output.py
index ea77fde..3e7fa55 100644
--- a/fdanyone/output.py
+++ b/fdanyone/output.py
@@ -162,7 +162,7 @@ def export_result(
**view_plan.to_dict(),
"num_layers": view_plan.num_layers,
"num_target_views": view_plan.num_target_views,
- "groups_per_layer": view_plan.groups_per_layer,
+ "num_groups": view_plan.num_groups,
},
"attention_backend": attention_backend,
"inference_steps": generated.denoising_profile.num_inference_steps,
diff --git a/fdanyone/vendor/diffsynth/models/wan_video_dit.py b/fdanyone/vendor/diffsynth/models/wan_video_dit.py
index 6b29440..cb78f25 100644
--- a/fdanyone/vendor/diffsynth/models/wan_video_dit.py
+++ b/fdanyone/vendor/diffsynth/models/wan_video_dit.py
@@ -1,7 +1,7 @@
"""Wan/SpaTem DiT graph used by the released 4DAnyone checkpoint.
This module intentionally contains one inference architecture. The public
-method always uses video self-attention, layer-local multiview attention,
+method always uses video self-attention, routed multiview attention,
ViewPack source tokens, frozen text context, and precomputed RGB-pose features.
Training-only adapters and alternate Wan model families are outside the reader
runtime.
diff --git a/fdanyone/views.py b/fdanyone/views.py
index f810d78..af5742b 100644
--- a/fdanyone/views.py
+++ b/fdanyone/views.py
@@ -47,13 +47,9 @@ class ViewPlan:
def num_target_views(self) -> int:
return self.views_per_layer * self.num_layers
- @property
- def groups_per_layer(self) -> int:
- return self.views_per_layer // self.views_per_group
-
@property
def num_groups(self) -> int:
- return self.groups_per_layer * self.num_layers
+ return self.num_target_views // self.views_per_group
@property
def target_views(self) -> tuple[TargetView, ...]: