Skip to content

The most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. The fastest local inference engine in the world.

feat: Support Pixal3d and TRELLIS2 (CORE-278) (CORE-199) (CORE-236) (CORE-312) (#14718)

Jukka Seppänen0e65cb907193
diff --git a/comfy/clip_vision.py b/comfy/clip_vision.py
index ce8924a11..c7d4f56b5 100644
--- a/comfy/clip_vision.py
+++ b/comfy/clip_vision.py
@@ -10,6 +10,7 @@ import comfy.utils
import comfy.clip_model
import comfy.image_encoders.dino2
import comfy.image_encoders.dino3
+from comfy.image_encoders.naf import NAF
class Output:
def __getitem__(self, key):
@@ -53,6 +54,7 @@ class ClipVisionModel():
self.model.eval()
self.patcher = comfy.model_patcher.CoreModelPatcher(self.model, load_device=self.load_device, offload_device=offload_device)
+ self.naf = None
def load_sd(self, sd):
return self.model.load_state_dict(sd, strict=False, assign=self.patcher.is_dynamic())
@@ -141,6 +143,8 @@ def load_clipvision_from_sd(sd, prefix="", convert_keys=False):
json_config = os.path.join(os.path.join(os.path.dirname(os.path.realpath(__file__)), "image_encoders"), "dino2_large.json")
elif 'layer.0.mlp.gate_proj.weight' in sd and 'layer.31.norm1.weight' in sd: # Dinov3 ViT-H/16+ (SwiGLU gated MLP, 32 layers)
json_config = comfy.image_encoders.dino3.DINOV3_VITH_CONFIG
+ elif 'layer.23.attention.o_proj.bias' in sd: # dinov3 large (24 layers)
+ json_config = os.path.join(os.path.join(os.path.dirname(os.path.realpath(__file__)), "image_encoders"), "dino3_large.json")
else:
return None
@@ -153,6 +157,14 @@ def load_clipvision_from_sd(sd, prefix="", convert_keys=False):
for k in keys:
if k not in u:
sd.pop(k)
+ # NAF feature upsampler bundled into the DINOv3 file under the `naf.` prefix.
+ naf_keys = [k for k in sd if k.startswith("naf.")]
+ if naf_keys:
+ naf_sd = {k[len("naf."):]: sd.pop(k) for k in naf_keys}
+ naf = NAF(operations=comfy.ops.manual_cast).eval()
+ naf.load_state_dict(naf_sd)
+ naf.to(comfy.model_management.text_encoder_dtype(clip.load_device))
+ clip.naf = comfy.model_patcher.CoreModelPatcher(naf, load_device=clip.load_device, offload_device=comfy.model_management.text_encoder_offload_device())
return clip
def load(ckpt_path):
diff --git a/comfy/image_encoders/dino3_large.json b/comfy/image_encoders/dino3_large.json
new file mode 100644
index 000000000..b37b61dc8
--- /dev/null
+++ b/comfy/image_encoders/dino3_large.json
@@ -0,0 +1,23 @@
+{
+ "model_type": "dinov3",
+ "hidden_size": 1024,
+ "image_size": 224,
+ "initializer_range": 0.02,
+ "intermediate_size": 4096,
+ "key_bias": false,
+ "layer_norm_eps": 1e-05,
+ "mlp_bias": true,
+ "num_attention_heads": 16,
+ "num_channels": 3,
+ "num_hidden_layers": 24,
+ "num_register_tokens": 4,
+ "patch_size": 16,
+ "pos_embed_rescale": 2.0,
+ "proj_bias": true,
+ "query_bias": true,
+ "rope_theta": 100.0,
+ "use_gated_mlp": false,
+ "value_bias": true,
+ "image_mean": [0.485, 0.456, 0.406],
+ "image_std": [0.229, 0.224, 0.225]
+}
diff --git a/comfy/image_encoders/naf.py b/comfy/image_encoders/naf.py
new file mode 100644
index 000000000..9d18c87df
--- /dev/null
+++ b/comfy/image_encoders/naf.py
@@ -0,0 +1,282 @@
+"""NAF (Neighborhood Attention Filtering) feature upsampler.
+
+Vendored from valeoai/NAF (Apache-2.0):
+ https://github.com/valeoai/NAF — src/model/naf.py + src/layers/{convolutions,attentions,rope}.py
+Used by Pixal3D's shape/texture conditioning to produce
+the 2x-upsampled half of the 2048-channel proj feature map.
+"""
+
+import math
+from typing import Tuple
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+import comfy.ops
+
+
+# Pure-torch neighborhood attention (replaces natten.na2d / na2d_qk + na2d_av).
+
+def upsample_lr_slice(src_lr: torch.Tensor, lr_dh: int, lr_dw: int,
+ hr_h_range: Tuple[int, int], hr_w_range: Tuple[int, int]) -> torch.Tensor:
+ """Slice a LR-layout tensor [B, h_lr, w_lr, n, C], permute to BCHW, and
+ nearest-exact upsample only the region covering [hr_h_range, hr_w_range].
+ Returns BCHW at hr_h_end-hr_h_start x hr_w_end-hr_w_start (no padding for
+ out-of-bounds regions)."""
+ B = src_lr.shape[0]
+ n = src_lr.shape[-2]
+ C = src_lr.shape[-1]
+ h_hr_start, h_hr_end = hr_h_range
+ w_hr_start, w_hr_end = hr_w_range
+ # LR positions covering [h_hr_start, h_hr_end). Nearest-exact maps HR p → p // D.
+ lr_h_start = h_hr_start // lr_dh
+ lr_h_end = (h_hr_end - 1) // lr_dh + 1
+ lr_w_start = w_hr_start // lr_dw
+ lr_w_end = (w_hr_end - 1) // lr_dw + 1
+ lr_slice = src_lr[:, lr_h_start:lr_h_end, lr_w_start:lr_w_end]
+ lh, lw = lr_slice.shape[1], lr_slice.shape[2]
+ lr_bcd = lr_slice.permute(0, 3, 4, 1, 2).reshape(B * n, C, lh, lw).contiguous()
+ up = F.interpolate(lr_bcd, scale_factor=(lr_dh, lr_dw), mode="nearest-exact")
+ offset_h = h_hr_start - lr_h_start * lr_dh
+ offset_w = w_hr_start - lr_w_start * lr_dw
+ return up[:, :, offset_h:offset_h + (h_hr_end - h_hr_start),
+ offset_w:offset_w + (w_hr_end - w_hr_start)]
+
+
+def na2d_pure(
+ q: torch.Tensor, # [B, H, W, n_heads, d_qk] at HR.
+ k_lr: torch.Tensor, # [B, h_lr, w_lr, n_heads, d_qk] at LR
+ v_lr: torch.Tensor, # [B, h_lr, w_lr, n_heads, d_v] at LR
+ kernel_size: Tuple[int, int], # (Kh, Kw) attention window.
+ dilation: Tuple[int, int], # (Dh, Dw) stride within the unrolled K/V grid; also the LR→HR upsample factor.
+ scale: float, # 1 / sqrt(d_qk) scaling for the Q·K scores.
+ tile: int = 128, # Spatial tile size (output positions per tile)
+ v_chunk: int = 64, # Sub-divide d_v into chunks of this size when computing attn·V. None disables chunking.
+ output: torch.Tensor = None, # Pre-allocated [B, n_heads, d_v, H, W] buffer (may be on CPU).
+ ) -> torch.Tensor: # [B, n_heads, d_v, H, W] (caller views as BCHW).
+ """Neighborhood attention in pure torch via F.unfold + per-tile slicing.
+
+ K and V are passed at LR resolution and upsampled (nearest-exact) per-tile only
+ for the slice the unfold needs. Avoids the [B, n*d, H, W] HR allocations for K
+ (512 MB) and V (2 GB) at tex_1024 fp16. Spatial tiling bounds the per-tile
+ F.unfold blob; `v_chunk` further slices d_v so attn·V is computed in C-sized
+ chunks (attn is reused, computed once from Q/K).
+
+ """
+ B, H, W, n, d_qk = q.shape
+ d_v = v_lr.shape[-1]
+ Kh, Kw = kernel_size
+ Dh, Dw = dilation
+ pad_h, pad_w = (Kh // 2) * Dh, (Kw // 2) * Dw
+
+ out = output if output is not None else torch.empty((B, n, d_v, H, W), device=q.device, dtype=q.dtype)
+
+ th = min(tile, H) if tile else H
+ tw = min(tile, W) if tile else W
+ chunk = v_chunk if (v_chunk and v_chunk < d_v) else d_v
+
+ for h0 in range(0, H, th):
+ for w0 in range(0, W, tw):
+ h1, w1 = min(h0 + th, H), min(w0 + tw, W)
+ t_h, t_w = h1 - h0, w1 - w0
+
+ # Padded HR region the unfold needs (kernel span = (K-1)*D + 1).
+ h_src_start = max(0, h0 - pad_h)
+ h_src_end = min(H, h1 + pad_h)
+ w_src_start = max(0, w0 - pad_w)
+ w_src_end = min(W, w1 + pad_w)
+ pad_top = max(0, pad_h - h0)
+ pad_bot = max(0, (h1 + pad_h) - H)
+ pad_lft = max(0, pad_w - w0)
+ pad_rgt = max(0, (w1 + pad_w) - W)
+
+ # Upsample only the tile region from k_lr / v_lr.
+ k_tile = upsample_lr_slice(k_lr, Dh, Dw,
+ (h_src_start, h_src_end),
+ (w_src_start, w_src_end))
+ v_tile = upsample_lr_slice(v_lr, Dh, Dw,
+ (h_src_start, h_src_end),
+ (w_src_start, w_src_end))
+ if pad_top or pad_bot or pad_lft or pad_rgt:
+ k_tile = F.pad(k_tile, [pad_lft, pad_rgt, pad_top, pad_bot])
+ v_tile = F.pad(v_tile, [pad_lft, pad_rgt, pad_top, pad_bot])
+
+ # Q·K → attention weights (small: KK=81 per output position).
+ KK = Kh * Kw
+ k_w = F.unfold(k_tile, kernel_size=(Kh, Kw), dilation=(Dh, Dw), padding=0)
+ k_w = k_w.view(B, n, d_qk, KK, t_h * t_w).permute(0, 1, 4, 3, 2) # [B, n, t, KK, d_qk]
+ # q is [B, H, W, n, d_qk]; per-tile slice + permute -> [B, n, t_h*t_w, 1, d_qk].
+ q_tile = q[:, h0:h1, w0:w1].permute(0, 3, 1, 2, 4).reshape(B, n, t_h * t_w, 1, d_qk)
+ scores = torch.matmul(q_tile, k_w.transpose(-1, -2)) * scale
+ attn = scores.softmax(dim=-1)
+ del k_w, scores, q_tile, k_tile
+
+ # attn · V, chunked over d_v.
+ for c0 in range(0, d_v, chunk):
+ c1 = min(c0 + chunk, d_v)
+ v_w = F.unfold(v_tile[:, c0:c1], kernel_size=(Kh, Kw),dilation=(Dh, Dw), padding=0) # [B*n, (c1-c0)*KK, t]
+ v_w = v_w.view(B, n, c1 - c0, KK, t_h * t_w).permute(0, 1, 4, 3, 2)
+ out_chunk = torch.matmul(attn, v_w).squeeze(-2) # [B, n, t, c1-c0]
+ out_chunk = out_chunk.view(B, n, t_h, t_w, c1 - c0).permute(0, 1, 4, 2, 3)
+ out[:, :, c0:c1, h0:h1, w0:w1] = out_chunk
+ del v_w, out_chunk
+ del attn, v_tile
+
+ return out # [B, n, d_v, H, W] — sole caller (CrossAttention) views it as BCHW directly.
+
+
+class CrossAttention(nn.Module):
+ """Window-restricted cross-attention. No learnable parameters; the model's
+ capacity lives entirely in the ImageEncoder convs."""
+
+ def __init__(self, dim: int, num_heads: int, kernel_size: Tuple[int, int] = (9, 9)):
+ super().__init__()
+ assert dim % num_heads == 0, "dim must be divisible by num_heads"
+ self.num_heads = num_heads
+ self.kernel_size = kernel_size
+ self.scale = (dim // num_heads) ** -0.5
+
+ @staticmethod
+ def _split_heads_lr(x: torch.Tensor, num_heads: int) -> torch.Tensor:
+ """[B, n*d, h, w] -> [B, h, w, n, d] at the input resolution (no upsample)."""
+ B, C, H, W = x.shape
+ return x.view(B, num_heads, C // num_heads, H, W).permute(0, 3, 4, 1, 2).contiguous()
+
+ def forward(self, q: torch.Tensor, k: torch.Tensor, v: torch.Tensor,
+ output=None) -> torch.Tensor:
+ hq, wq = q.shape[-2:]
+ hk, wk = k.shape[-2:]
+ dilation = (hq // hk, wq // wk)
+ B, C, _, _ = q.shape
+ q = q.view(B, self.num_heads, C // self.num_heads, hq, wq).permute(0, 3, 4, 1, 2).contiguous()
+ k_lr = self._split_heads_lr(k, self.num_heads).to(q.dtype)
+ v_lr = self._split_heads_lr(v, self.num_heads).to(q.dtype)
+ out_buf = output.view(B, self.num_heads, v.shape[1] // self.num_heads, hq, wq) if output is not None else None
+ out = na2d_pure(q, k_lr, v_lr, self.kernel_size, dilation, self.scale, output=out_buf)
+ return out.view(B, -1, hq, wq)
+
+
+# RoPE positional embedding
+
+def rope_rotate_half(x: torch.Tensor) -> torch.Tensor:
+ x1, x2 = x.chunk(2, dim=-1)
+ return torch.cat([-x2, x1], dim=-1)
+
+
+class RoPE(nn.Module):
+ def __init__(self, embed_dim: int, num_heads: int, base: float = 100.0):
+ super().__init__()
+ assert embed_dim % (4 * num_heads) == 0
+ self.num_heads = num_heads
+ self.D_head = embed_dim // num_heads
+ self.base = base
+ self.register_buffer("periods", torch.empty(self.D_head // 4), persistent=True) # loaded from the checkpoint
+
+ def _cos_sin(self, H: int, W: int, x: torch.Tensor):
+ """cos/sin depend only on (H, W, dtype) and the checkpoint-fixed periods; recomputed per forward."""
+ periods = comfy.ops.cast_to_input(self.periods, x)
+ coords_h = torch.arange(0.5, H, device=x.device, dtype=torch.float32) / H
+ coords_w = torch.arange(0.5, W, device=x.device, dtype=torch.float32) / W
+ coords = torch.stack(torch.meshgrid(coords_h, coords_w, indexing="ij"), dim=-1) # [H, W, 2]
+ coords = coords.flatten(0, 1) * 2.0 - 1.0 # [HW, 2]
+ angles = 2 * math.pi * coords[:, :, None] / periods.to(coords.dtype)[None, None, :] # [HW, 2, D//4]
+ angles = angles.flatten(1, 2).tile(2) # [HW, D]
+ cos = torch.cos(angles).to(x.dtype)
+ sin = torch.sin(angles).to(x.dtype)
+ return cos, sin
+
+ def forward(self, x: torch.Tensor) -> torch.Tensor:
+ # x: [B, n*D_head, H, W]
+ B, C, H, W = x.shape
+ n = self.num_heads
+ D = C // n
+ x = x.view(B, n, D, H, W).permute(0, 1, 3, 4, 2).reshape(B, n, H * W, D)
+ cos, sin = self._cos_sin(H, W, x)
+ x = (x * cos) + (rope_rotate_half(x) * sin)
+ x = x.view(B, n, H, W, D).permute(0, 1, 4, 2, 3).reshape(B, n * D, H, W)
+ return x
+
+
+# Image encoder
+
+class EncBlock(nn.Module):
+ def __init__(self, channels: int, kernel_size: int, operations, num_groups: int = 8):
+ super().__init__()
+ self.norm1 = operations.GroupNorm(num_groups=num_groups, num_channels=channels)
+ self.conv1 = operations.Conv2d(channels, channels, kernel_size=kernel_size,
+ padding=kernel_size // 2, padding_mode="reflect", bias=True)
+ self.norm2 = operations.GroupNorm(num_groups=num_groups, num_channels=channels)
+ self.conv2 = operations.Conv2d(channels, channels, kernel_size=kernel_size,
+ padding=kernel_size // 2, padding_mode="reflect", bias=True)
+ self.activation_fn = nn.SiLU()
+
+ def forward(self, x):
+ x = self.norm1(x)
+ x = self.activation_fn(x)
+ x = self.conv1(x)
+ x = self.norm2(x)
+ x = self.activation_fn(x)
+ x = self.conv2(x)
+ return x # no skip connection
+
+
+def _encoder(in_dim: int, hidden_dim: int, operations, kernel_size: int = 1, ks_res: int = 1, num_layers: int = 2) -> nn.Sequential:
+ return nn.Sequential(
+ operations.Conv2d(in_dim, hidden_dim, kernel_size=kernel_size, padding=kernel_size // 2, padding_mode="reflect", bias=True),
+ *[EncBlock(hidden_dim, kernel_size=ks_res, operations=operations) for _ in range(num_layers)],
+ )
+
+
+class ImageEncoder(nn.Module):
+ """Two parallel conv stacks (1x1 + 3x3) producing dim/2 channels each, then concat,
+ spatial average-pool to target size, RoPE-embed positions."""
+
+ def __init__(self, operations, in_channels: int = 3, out_channels: int = 256,
+ heads_rope: int = 4, rope_base: float = 100.0, img_layers: int = 2):
+ super().__init__()
+ half = out_channels // 2
+ self.encoder = _encoder(in_channels, half, operations=operations, kernel_size=1, ks_res=1, num_layers=img_layers)
+ self.sem_encoder = _encoder(in_channels, half, operations=operations, kernel_size=3, ks_res=3, num_layers=img_layers)
+ self.rope = RoPE(embed_dim=out_channels, num_heads=heads_rope, base=rope_base)
+
+ def forward(self, x: torch.Tensor, output_size: Tuple[int, int]) -> torch.Tensor:
+ # Avoid running the conv stacks on >4× the target resolution.
+ out_h, out_w = output_size
+ if x.shape[-2] > 4 * out_h or x.shape[-1] > 4 * out_w:
+ x = F.interpolate(x, size=(min(x.shape[-2], 4 * out_h),
+ min(x.shape[-1], 4 * out_w)),
+ mode="bilinear", align_corners=False)
+ x = torch.cat([self.encoder(x), self.sem_encoder(x)], dim=1)
+ x = F.adaptive_avg_pool2d(x, output_size=output_size)
+ x = self.rope(x)
+ return x
+
+
+class NAF(nn.Module):
+ """NAF feature upsampler."""
+
+ def __init__(
+ self, operations,
+ dim: int = 256, # internal channel dimension of the ImageEncoder
+ heads_attn: int = 4, # attention heads in the windowed cross-attn
+ heads_rope: int = 4, # heads for RoPE position encoding (must divide dim)
+ kernel_size: int = 9, # square kernel for the neighborhood attention window
+ rope_base: float = 100.0, # base for RoPE frequency periods
+ img_layers: int = 2, # number of EncBlocks in each conv stack
+ ):
+ super().__init__()
+ self.image_encoder = ImageEncoder(operations=operations, in_channels=3, out_channels=dim, heads_rope=heads_rope, rope_base=rope_base, img_layers=img_layers)
+ self.upsampler = CrossAttention(dim=dim, num_heads=heads_attn, kernel_size=(kernel_size, kernel_size))
+
+ def forward(
+ self,
+ image: torch.Tensor, # [B, 3, H_img, W_img] in [0, 1].
+ features: torch.Tensor, # [B, C, H_feat, W_feat] low-resolution features (any C).
+ output_size: Tuple[int, int], # (H_out, W_out) target spatial resolution for the upsampled features.
+ output=None,
+ ) -> torch.Tensor: # [B, C, H_out, W_out] upsampled features.
+ """Upsample low-res feature map to output_size, guided by the image."""
+ q = self.image_encoder(image, output_size=output_size)
+ k = F.adaptive_avg_pool2d(q, output_size=features.shape[-2:])
+ return self.upsampler(q, k, features, output=output)
diff --git a/comfy/latent_formats.py b/comfy/latent_formats.py
index 34c6d700c..6a60a7630 100644
--- a/comfy/latent_formats.py
+++ b/comfy/latent_formats.py
@@ -253,6 +253,53 @@ class TripoSplat(LatentFormat):
def process_out(self, latent):
return latent
+class Trellis2(LatentFormat):
+ latent_channels = 32
+
+class Trellis2SLAT(Trellis2):
+ # Sparse structured latent: per-token feats [N, 32]. process_out denormalizes
+ # the decoded feats (latent * std + mean); subclasses carry each space's stats.
+ latents_mean = None
+ latents_std = None
+
+ def process_in(self, latent):
+ mean = self.latents_mean.to(latent.device, latent.dtype)
+ std = self.latents_std.to(latent.device, latent.dtype)
+ return (latent - mean) / std
+
+ def process_out(self, latent):
+ mean = self.latents_mean.to(latent.device, latent.dtype)
+ std = self.latents_std.to(latent.device, latent.dtype)
+ return latent * std + mean
+
+class Trellis2ShapeSLAT(Trellis2SLAT):
+ latents_mean = torch.tensor([
+ 0.781296, 0.018091, -0.495192, -0.558457, 1.060530, 0.093252, 1.518149, -0.933218,
+ -0.732996, 2.604095, -0.118341, -2.143904, 0.495076, -2.179512, -2.130751, -0.996944,
+ 0.261421, -2.217463, 1.260067, -0.150213, 3.790713, 1.481266, -1.046058, -1.523667,
+ -0.059621, 2.220780, 1.621212, 0.877230, 0.567247, -3.175944, -3.186688, 1.578665
+ ])[None]
+ latents_std = torch.tensor([
+ 5.972266, 4.706852, 5.445010, 5.209927, 5.320220, 4.547237, 5.020802, 5.444004,
+ 5.226681, 5.683095, 4.831436, 5.286469, 5.652043, 5.367606, 5.525084, 4.730578,
+ 4.805265, 5.124013, 5.530808, 5.619001, 5.103930, 5.417670, 5.269677, 5.547194,
+ 5.634698, 5.235274, 6.110351, 5.511298, 6.237273, 4.879207, 5.347008, 5.405691
+ ])[None]
+
+class Trellis2TexSLAT(Trellis2SLAT):
+ latents_mean = torch.tensor([
+ 3.501659, 2.212398, 2.226094, 0.251093, -0.026248, -0.687364, 0.439898, -0.928075,
+ 0.029398, -0.339596, -0.869527, 1.038479, -0.972385, 0.126042, -1.129303, 0.455149,
+ -1.209521, 2.069067, 0.544735, 2.569128, -0.323407, 2.293000, -1.925608, -1.217717,
+ 1.213905, 0.971588, -0.023631, 0.106750, 2.021786, 0.250524, -0.662387, -0.768862
+ ])[None]
+ latents_std = torch.tensor([
+ 2.665652, 2.743913, 2.765121, 2.595319, 3.037293, 2.291316, 2.144656, 2.911822,
+ 2.969419, 2.501689, 2.154811, 3.163343, 2.621215, 2.381943, 3.186697, 3.021588,
+ 2.295916, 3.234985, 3.233086, 2.260140, 2.874801, 2.810596, 3.292720, 2.674999,
+ 2.680878, 2.372054, 2.451546, 2.353556, 2.995195, 2.379849, 2.786195, 2.775190
+ ])[None]
+
class Mochi(LatentFormat):
latent_channels = 12
latent_dimensions = 3
diff --git a/comfy/ldm/moge/model.py b/comfy/ldm/moge/model.py
index 1695626bc..8dd280c63 100644
--- a/comfy/ldm/moge/model.py
+++ b/comfy/ldm/moge/model.py
@@ -69,7 +69,7 @@ class MoGeModelV1(nn.Module):
resize = ((num_tokens * 14 ** 2) / (H * W)) ** 0.5
rh, rw = int(H * resize), int(W * resize)
x = F.interpolate(image, (rh, rw), mode="bicubic", align_corners=False, antialias=True)
- x = (x - self.image_mean) / self.image_std
+ x = (x - comfy.ops.cast_to_input(self.image_mean, x, copy=False)) / comfy.ops.cast_to_input(self.image_std, x, copy=False)
x14 = F.interpolate(x, (rh // 14 * 14, rw // 14 * 14), mode="bilinear", align_corners=False, antialias=True)
n_layers = len(self.backbone.encoder.layer)
@@ -268,7 +268,6 @@ class MoGeModel:
"""Loaded MoGe model + ComfyUI memory management."""
def __init__(self, state_dict: dict):
- # text encoder dtype closest match
self.load_device = comfy.model_management.text_encoder_device()
offload_device = comfy.model_management.text_encoder_offload_device()
self.dtype = comfy.model_management.text_encoder_dtype(self.load_device)
@@ -287,7 +286,7 @@ class MoGeModel:
) -> Dict[str, torch.Tensor]:
"""Run a single MoGe forward + post-process pass. image is (B, 3, H, W) in [0, 1]."""
comfy.model_management.load_model_gpu(self.patcher)
- image = image.to(device=self.load_device, dtype=self.dtype)
+ image = image.to(device=self.load_device, dtype=torch.float32)
H, W = image.shape[-2:]
aspect_ratio = W / H
diff --git a/comfy/ldm/moge/modules.py b/comfy/ldm/moge/modules.py
index f6443d65a..366411120 100644
--- a/comfy/ldm/moge/modules.py
+++ b/comfy/ldm/moge/modules.py
@@ -136,7 +136,7 @@ class DINOv2Encoder(nn.Module):
def forward(self, image: torch.Tensor, token_rows: int, token_cols: int,
return_class_token: bool = False) -> Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor]]:
image_14 = F.interpolate(image, (token_rows * 14, token_cols * 14), mode="bilinear", align_corners=False, antialias=True)
- image_14 = (image_14 - self.image_mean) / self.image_std
+ image_14 = (image_14 - comfy.ops.cast_to_input(self.image_mean, image_14, copy=False)) / comfy.ops.cast_to_input(self.image_std, image_14, copy=False)
feats = self.backbone.get_intermediate_layers(image_14, self.intermediate_layers, apply_norm=True)
x = torch.stack([
proj(feat.permute(0, 2, 1).unflatten(2, (token_rows, token_cols)).contiguous())
diff --git a/comfy/ldm/trellis2/flexgemm.py b/comfy/ldm/trellis2/flexgemm.py
new file mode 100644
index 000000000..8fb6d56f7
--- /dev/null
+++ b/comfy/ldm/trellis2/flexgemm.py
@@ -0,0 +1,154 @@
+from typing import Optional, Tuple
+import torch
+
+import comfy.model_management
+
+
+def compute_kernel_offsets(Kw, Kh, Kd, Dw, Dh, Dd, device):
+ """Kernel spatial offsets in the same order as the CUDA/Triton kernels."""
+ offsets = []
+ for vx in range(Kw):
+ for vy in range(Kh):
+ for vz in range(Kd):
+ offsets.append((vx * Dw, vy * Dh, vz * Dd))
+ return torch.tensor(offsets, device=device, dtype=torch.int32)
+
+
+class TorchHashMap:
+ """Sorted-array hashmap backed by torch.searchsorted."""
+
+ def __init__(self, keys: torch.Tensor, values: torch.Tensor):
+ self.sorted_keys, order = torch.sort(keys.to(torch.long))
+ self.sorted_vals = values.to(torch.long)[order]
+ self._n = self.sorted_keys.numel()
+
+ # Chunk size for lookup_flat, caps each transient to ~CHUNK rows.
+ _LOOKUP_CHUNK = 1 << 23 # 8M rows ≈ 64 MB per int64 temp
+
+ def lookup_flat(self, flat_keys: torch.Tensor) -> torch.Tensor:
+ N = flat_keys.shape[0]
+ out = torch.full((N,), -1, device=flat_keys.device, dtype=torch.int32)
+ if self._n == 0 or N == 0:
+ return out
+ for s in range(0, N, self._LOOKUP_CHUNK):
+ e = min(s + self._LOOKUP_CHUNK, N)
+ flat_chunk = flat_keys[s:e].to(torch.long)
+ idx = torch.searchsorted(self.sorted_keys, flat_chunk)
+ in_range = idx < self._n
+ idx.clamp_(max=self._n - 1) # reuse idx as the "safe" index
+ found = in_range & (self.sorted_keys[idx] == flat_chunk)
+ if found.any():
+ found_idx = found.nonzero(as_tuple=True)[0]
+ out[s + found_idx] = self.sorted_vals[idx[found_idx]].to(torch.int32)
+ return out
+
+
+def build_submanifold_neighbor_map(
+ hashmap,
+ coords: torch.Tensor,
+ W, H, D,
+ Kw, Kh, Kd,
+ Dw, Dh, Dd,
+):
+ # neighbor[i, v] = index of the voxel at voxel i's coord + kernel-offset v, or -1.
+ # Chunked over voxels so the [chunk, V, 3] candidate transient stays bounded.
+ device = coords.device
+ M = coords.shape[0]
+ offsets = compute_kernel_offsets(Kw, Kh, Kd, Dw, Dh, Dd, device).long() # [V, 3]
+ V = offsets.shape[0]
+ center = torch.tensor([(Kw // 2) * Dw, (Kh // 2) * Dh, (Kd // 2) * Dd], device=device)
+ WHD, HD = W * H * D, H * D
+
+ neighbor = torch.empty((M, V), dtype=torch.int32, device=device)
+ # ~V*40 bytes/voxel of transient (int64 cand + flat + masks); cap at ~0.5 GB.
+ chunk = max(1, min(M, int(0.5 * (1024 ** 3) / (V * 40))))
+
+ for s in range(0, M, chunk):
+ e = min(s + chunk, M)
+ b = coords[s:e, 0].long()
+ cand = coords[s:e, 1:4].long()[:, None, :] + offsets[None, :, :] - center # [c, V, 3]
+ x, y, z = cand[..., 0], cand[..., 1], cand[..., 2]
+ in_bounds = (x >= 0) & (x < W) & (y >= 0) & (y < H) & (z >= 0) & (z < D) # [c, V]
+ flat = b[:, None] * WHD + x * HD + y * D + z # [c, V]
+ flat = torch.where(in_bounds, flat, torch.full_like(flat, -1)) # OOB -> guaranteed miss
+ neighbor[s:e] = hashmap.lookup_flat(flat.reshape(-1)).view(e - s, V)
+ return neighbor
+
+def get_recommended_chunk_mem(
+ device=None,
+ safety_fraction: float = 0.2,
+ min_gb: float = 0.25,
+ max_gb: float = 2.0,
+):
+ """Pick a chunk-memory budget (in GB) for sparse conv batching."""
+ free_gb = comfy.model_management.get_free_memory(device) / (1024 ** 3)
+ return max(min_gb, min(free_gb * safety_fraction, max_gb))
+
+def sparse_submanifold_conv3d(
+ feats: torch.Tensor,
+ coords: torch.Tensor,
+ shape: tuple,
+ weight: torch.Tensor,
+ bias: Optional[torch.Tensor],
+ neighbor_cache: Optional[torch.Tensor],
+ dilation: tuple,
+) -> Tuple[torch.Tensor, Optional[torch.Tensor]]:
+ if feats.shape[0] == 0:
+ Co = weight.shape[0]
+ return torch.empty((0, Co), device=feats.device, dtype=feats.dtype), None
+
+ W, H, D = shape
+
+ Co, Kw, Kh, Kd, Ci = weight.shape
+ V = Kw * Kh * Kd
+ device = feats.device
+
+ if neighbor_cache is None:
+ b_stride = W * H * D
+ x_stride = H * D
+ y_stride = D
+ z_stride = 1
+
+ flat_keys = (coords[:, 0].long() * b_stride +
+ coords[:, 1].long() * x_stride +
+ coords[:, 2].long() * y_stride +
+ coords[:, 3].long() * z_stride)
+ vals = torch.arange(coords.shape[0], dtype=torch.int32, device=device)
+ hashmap = TorchHashMap(flat_keys, vals)
+
+ neighbor = build_submanifold_neighbor_map(
+ hashmap, coords, W, H, D, Kw, Kh, Kd,
+ dilation[0], dilation[1], dilation[2]
+ )
+ else:
+ neighbor = neighbor_cache
+
+ N_pts = feats.shape[0]
+
+ weight_T = weight.view(Co, V * Ci).T
+
+ output = torch.empty(N_pts, Co, device=device, dtype=feats.dtype)
+
+ # Zero row at index N_pts; missing neighbors (-1) gather it -> no separate masking.
+ feats_padded = torch.cat([feats, feats.new_zeros(1, Ci)], dim=0)
+
+ # Chunk over voxels to bound the (chunk, V, Ci) gather.
+ max_chunk_mem_gb = get_recommended_chunk_mem(device)
+ mem_per_row = V * Ci * feats.element_size()
+ max_chunk_mem = max_chunk_mem_gb * (1024 ** 3)
+ chunk_size = max(1, int(max_chunk_mem / mem_per_row))
+ chunk_size = min(chunk_size, N_pts)
+
+ for start in range(0, N_pts, chunk_size):
+ end = min(start + chunk_size, N_pts)
+ actual_chunk = end - start
+
+ chunk_idx = torch.where(neighbor[start:end] < 0, N_pts, neighbor[start:end]) # -1 -> zero row
+ gathered = feats_padded[chunk_idx] # (chunk, V, Ci)
+ gathered_flat = gathered.view(actual_chunk, V * Ci)
+ output[start:end] = torch.matmul(gathered_flat, weight_T) # (chunk, V*Ci) @ (V*Ci, Co)
+
+ if bias is not None:
+ output += bias.unsqueeze(0).to(output.dtype)
+
+ return output, neighbor
diff --git a/comfy/ldm/trellis2/model.py b/comfy/ldm/trellis2/model.py
new file mode 100644
index 000000000..042e94aa0
--- /dev/null
+++ b/comfy/ldm/trellis2/model.py
@@ -0,0 +1,1151 @@
+import torch
+import torch.nn.functional as F
+import torch.nn as nn
+import comfy.model_management
+import comfy.ops
+from comfy.ldm.trellis2.vae import SparseTensor, SparseLinear, sparse_cat, VarLenTensor
+from typing import Optional, Tuple, Literal, Union, List
+from comfy.ldm.modules.attention import optimized_attention
+from comfy.ldm.genmo.joint_model.layers import TimestepEmbedder
+from comfy.ldm.flux.math import apply_rope, apply_rope1
+
+
+def dense_attention(q, k, v, **kwargs):
+ heads = q.shape[2]
+ q = q.permute(0, 2, 1, 3)
+ k = k.permute(0, 2, 1, 3)
+ v = v.permute(0, 2, 1, 3)
+ out = optimized_attention(q, k, v, heads, skip_output_reshape=True, skip_reshape=True, **kwargs)
+ return out.permute(0, 2, 1, 3)
+
+
+def _to_padded(t):
+ if not isinstance(t, VarLenTensor):
+ return t, None
+ seqlens = [item.stop - item.start for item in t.layout]
+ if len(set(seqlens)) == 1:
+ return t.feats.view(len(t.layout), seqlens[0], *t.feats.shape[1:]), None
+ max_seqlen = max(seqlens)
+ padded = t.feats.new_zeros((len(t.layout), max_seqlen, *t.feats.shape[1:]))
+ valid = torch.zeros((len(t.layout), max_seqlen), dtype=torch.bool, device=t.device)
+ for i, (item, seqlen) in enumerate(zip(t.layout, seqlens)):
+ padded[i, :seqlen] = t.feats[item]
+ valid[i, :seqlen] = True
+ return padded, valid
+
+
+def sparse_attention(q, k, v, **kwargs):
+ q_padded, q_valid = _to_padded(q)
+ k_padded, k_valid = _to_padded(k)
+ v_padded, _ = _to_padded(v)
+ if k_valid is not None:
+ mask = torch.zeros((k_valid.shape[0], 1, 1, k_valid.shape[1]),
+ dtype=q_padded.dtype, device=q_padded.device)
+ mask.masked_fill_(~k_valid[:, None, None, :], -torch.finfo(q_padded.dtype).max)
+ kwargs["mask"] = mask
+ out = dense_attention(q_padded, k_padded, v_padded, **kwargs)
+ if isinstance(q, VarLenTensor):
+ if q_valid is not None:
+ return q.replace(out[q_valid])
+ return q.replace(out.reshape(-1, *out.shape[2:]))
+ return out
+
+
+class SparseGELU(nn.GELU):
+ def forward(self, input: VarLenTensor) -> VarLenTensor:
+ return input.replace(super().forward(input.feats))
+
+class SparseFeedForwardNet(nn.Module):
+ def __init__(self, channels: int, mlp_ratio: float = 4.0, device=None, dtype=None, operations=None):
+ super().__init__()
+ self.mlp = nn.Sequential(
+ SparseLinear(channels, int(channels * mlp_ratio), device=device, dtype=dtype, operations=operations),
+ SparseGELU(approximate="tanh"),
+ SparseLinear(int(channels * mlp_ratio), channels, device=device, dtype=dtype, operations=operations),
+ )
+
+ def forward(self, x: VarLenTensor) -> VarLenTensor:
+ return self.mlp(x)
+
+class MultiHeadRMSNorm(nn.Module):
+ # Per-head qk-norm for both sparse (VarLenTensor) and dense inputs. gamma is [heads, dim]
+ # (per-head), so it's a broadcast multiply rather than F.rms_norm's 1-D weight
+ def __init__(self, dim: int, heads: int, device=None, dtype=None):
+ super().__init__()
+ self.gamma = nn.Parameter(torch.empty(heads, dim, device=device, dtype=dtype))
+
+ def forward(self, x: Union[VarLenTensor, torch.Tensor]) -> Union[VarLenTensor, torch.Tensor]:
+ if isinstance(x, VarLenTensor):
+ return x.replace(F.rms_norm(x.feats, (x.feats.shape[-1],)) * comfy.ops.cast_to_input(self.gamma, x.feats))
+ return F.rms_norm(x, (x.shape[-1],)) * comfy.ops.cast_to_input(self.gamma, x)
+
+class SparseRotaryPositionEmbedder(nn.Module):
+ def __init__(self, head_dim: int, dim: int = 3, rope_freq: Tuple[float, float] = (1.0, 10000.0), device=None):
+ super().__init__()
+ self.head_dim = head_dim
+ self.dim = dim
+ self.rope_freq = rope_freq
+ self.freq_dim = head_dim // 2 // dim
+ self.freqs = torch.arange(self.freq_dim, dtype=torch.float32, device=device) / self.freq_dim
+ self.freqs = rope_freq[0] / (rope_freq[1] ** self.freqs)
+
+ def _get_freqs_cis(self, coords: torch.Tensor) -> torch.Tensor:
+ phases_list = []
+ for i in range(self.dim):
+ phases_list.append(torch.outer(coords[..., i], self.freqs.to(coords.device)))
+
+ phases = torch.cat(phases_list, dim=-1)
+
+ if phases.shape[-1] < self.head_dim // 2:
+ padn = self.head_dim // 2 - phases.shape[-1]
+ phases = torch.cat([phases, torch.zeros(*phases.shape[:-1], padn, device=phases.device)], dim=-1)
+
+ cos = torch.cos(phases)
+ sin = torch.sin(phases)
+
+ f_cis_0 = torch.stack([cos, sin], dim=-1)
+ f_cis_1 = torch.stack([-sin, cos], dim=-1)
+ freqs_cis = torch.stack([f_cis_0, f_cis_1], dim=-1)
+
+ return freqs_cis
+
+ def forward(self, q, k=None):
+ cache_name = f'rope_cis_{self.dim}d_f{self.rope_freq[1]}_hd{self.head_dim}'
+ freqs_cis = q.get_spatial_cache(cache_name)
+
+ if freqs_cis is None:
+ coords = q.coords[..., 1:].to(torch.float32)
+ freqs_cis = self._get_freqs_cis(coords)
+ q.register_spatial_cache(cache_name, freqs_cis)
+
+ if q.feats.ndim == 3:
+ f_cis = freqs_cis.unsqueeze(1)
+ else:
+ f_cis = freqs_cis
+
+ if k is None:
+ return q.replace(apply_rope1(q.feats, f_cis))
+
+ q_feats, k_feats = apply_rope(q.feats, k.feats, f_cis)
+ return q.replace(q_feats), k.replace(k_feats)
+
+
+class RotaryPositionEmbedder(SparseRotaryPositionEmbedder):
+ def forward(self, coords: torch.Tensor) -> torch.Tensor:
+ return self._get_freqs_cis(coords) # [L, head_dim/2, 2, 2]
+
+class SparseMultiHeadAttention(nn.Module):
+ def __init__(
+ self,
+ channels: int,
+ num_heads: int,
+ ctx_channels: Optional[int] = None,
+ type: Literal["self", "cross"] = "self",
+ qkv_bias: bool = True,
+ qk_rms_norm: bool = False,
+ device=None, dtype=None, operations=None
+ ):
+ super().__init__()
+
+ self.channels = channels
+ self.head_dim = channels // num_heads
+ self.ctx_channels = ctx_channels if ctx_channels is not None else channels
+ self.num_heads = num_heads
+ self._type = type
+ self.qk_rms_norm = qk_rms_norm
+
+ if self._type == "self":
+ self.to_qkv = operations.Linear(channels, channels * 3, bias=qkv_bias, device=device, dtype=dtype)
+ else:
+ self.to_q = operations.Linear(channels, channels, bias=qkv_bias, device=device, dtype=dtype)
+ self.to_kv = operations.Linear(self.ctx_channels, channels * 2, bias=qkv_bias, device=device, dtype=dtype)
+
+ if self.qk_rms_norm:
+ self.q_rms_norm = MultiHeadRMSNorm(self.head_dim, num_heads, device=device, dtype=dtype)
+ self.k_rms_norm = MultiHeadRMSNorm(self.head_dim, num_heads, device=device, dtype=dtype)
+
+ self.to_out = operations.Linear(channels, channels, device=device, dtype=dtype)
+
+ if self._type == "self":
+ self.rope = SparseRotaryPositionEmbedder(self.head_dim, device=device)
+
+ @staticmethod
+ def _linear(module: nn.Linear, x: Union[VarLenTensor, torch.Tensor]) -> Union[VarLenTensor, torch.Tensor]:
+ if isinstance(x, VarLenTensor):
+ return x.replace(module(x.feats))
+ else:
+ return module(x)
+
+ @staticmethod
+ def _reshape_chs(x: Union[VarLenTensor, torch.Tensor], shape: Tuple[int, ...]) -> Union[VarLenTensor, torch.Tensor]:
+ if isinstance(x, VarLenTensor):
+ return x.reshape(*shape)
+ else:
+ return x.reshape(*x.shape[:2], *shape)
+
+ def _fused_pre(self, x: Union[VarLenTensor, torch.Tensor], num_fused: int) -> Union[VarLenTensor, torch.Tensor]:
+ if isinstance(x, VarLenTensor):
+ x_feats = x.feats.unsqueeze(0)
+ else:
+ x_feats = x
+ x_feats = x_feats.reshape(*x_feats.shape[:2], num_fused, self.num_heads, -1)
+ return x.replace(x_feats.squeeze(0)) if isinstance(x, VarLenTensor) else x_feats
+
+ def forward(self, x: SparseTensor, context: Optional[Union[VarLenTensor, torch.Tensor]] = None, transformer_options=None) -> SparseTensor:
+ if self._type == "self":
+ qkv = self._linear(self.to_qkv, x)
+ qkv = self._fused_pre(qkv, num_fused=3)
+ q, k, v = qkv.unbind(dim=-3)
+ if self.qk_rms_norm:
+ q = self.q_rms_norm(q)
+ k = self.k_rms_norm(k)
+ q, k = self.rope(q, k)
+ h = sparse_attention(q, k, v, transformer_options=transformer_options)
+ else:
+ q = self._linear(self.to_q, x)
+ q = self._reshape_chs(q, (self.num_heads, -1))
+ kv = self._linear(self.to_kv, context)
+ kv = self._fused_pre(kv, num_fused=2)
+ k, v = kv.unbind(dim=-3)
+ if self.qk_rms_norm:
+ q = self.q_rms_norm(q)
+ k = self.k_rms_norm(k)
+ h = sparse_attention(q, k, v, transformer_options=transformer_options)
+ h = self._reshape_chs(h, (-1,))
+ h = self._linear(self.to_out, h)
+ return h
+
+def _split_proj_context(context):
+ if not isinstance(context, dict):
+ return context, None
+ global_ctx = context["global"]
+ if "proj" in context:
+ return global_ctx, context["proj"]
+ if "proj_semantic" in context and "proj_color" in context:
+ return global_ctx, (context["proj_semantic"], context["proj_color"])
+ return global_ctx, None
+
+
+class ProjectAttentionSparse(nn.Module):
+ def __init__(self, cross_attn_block: nn.Module, channels: int, proj_in_channels: int,
+ device=None, dtype=None, operations=None):
+ super().__init__()
+ self.cross_attn_block = cross_attn_block
+ self.proj_linear = operations.Linear(proj_in_channels, channels, bias=True,
+ device=device, dtype=dtype)
+
+ def forward(self, x: SparseTensor, context, transformer_options=None) -> SparseTensor:
+ global_ctx, proj_in = _split_proj_context(context)
+ global_out = self.cross_attn_block(x, global_ctx, transformer_options=transformer_options)
+ if isinstance(proj_in, tuple):
+ proj_in = torch.cat([proj_in[0], proj_in[1]], dim=-1)
+ proj_out = self.proj_linear(proj_in)
+ return global_out.replace(global_out.feats + proj_out.to(global_out.feats.dtype))
+
+
+class ProjectAttentionDense(nn.Module):
+ def __init__(self, cross_attn_block: nn.Module, channels: int, proj_in_channels: int,
+ device=None, dtype=None, operations=None):
+ super().__init__()
+ self.cross_attn_block = cross_attn_block
+ self.proj_linear = operations.Linear(proj_in_channels, channels, bias=True,
+ device=device, dtype=dtype)
+
+ def forward(self, x: torch.Tensor, context, transformer_options=None) -> torch.Tensor:
+ global_ctx, proj_in = _split_proj_context(context)
+ global_out = self.cross_attn_block(x, global_ctx, transformer_options=transformer_options)
+ if isinstance(proj_in, tuple):
+ proj_in = torch.cat([proj_in[0], proj_in[1]], dim=-1)
+ proj_out = self.proj_linear(proj_in)
+ return global_out + proj_out.to(global_out.dtype)
+
+
+class ModulatedSparseTransformerCrossBlock(nn.Module):
+ """
+ Sparse Transformer cross-attention block (MSA + MCA + FFN) with adaptive layer norm conditioning.
+ """
+ def __init__(
+ self,
+ channels: int,
+ ctx_channels: int,
+ num_heads: int,
+ mlp_ratio: float = 4.0,
+ qk_rms_norm: bool = False,
+ qk_rms_norm_cross: bool = False,
+ qkv_bias: bool = True,
+ share_mod: bool = False,
+ image_attn_mode: Literal["global", "proj"] = "global",
+ proj_in_channels: Optional[int] = None,
+ device=None, dtype=None, operations=None
+ ):
+ super().__init__()
+ self.share_mod = share_mod
+ self.image_attn_mode = image_attn_mode
+ self.norm1 = operations.LayerNorm(channels, elementwise_affine=False, eps=1e-6, device=device, dtype=dtype)
+ self.norm2 = operations.LayerNorm(channels, elementwise_affine=True, eps=1e-6, device=device, dtype=dtype)
+ self.norm3 = operations.LayerNorm(channels, elementwise_affine=False, eps=1e-6, device=device, dtype=dtype)
+ self.self_attn = SparseMultiHeadAttention(
+ channels,
+ num_heads=num_heads,
+ type="self",
+ qkv_bias=qkv_bias,
+ qk_rms_norm=qk_rms_norm,
+ device=device, dtype=dtype, operations=operations
+ )
+ cross_inner = SparseMultiHeadAttention(
+ channels,
+ ctx_channels=ctx_channels,
+ num_heads=num_heads,
+ type="cross",
+ qkv_bias=qkv_bias,
+ qk_rms_norm=qk_rms_norm_cross,
+ device=device, dtype=dtype, operations=operations
+ )
+ if image_attn_mode == "global":
+ self.cross_attn = cross_inner
+ else:
+ if proj_in_channels is None:
+ raise ValueError("proj_in_channels must be set when image_attn_mode != 'global'")
+ self.cross_attn = ProjectAttentionSparse(
+ cross_inner, channels, proj_in_channels,
+ device=device, dtype=dtype, operations=operations,
+ )
+ self.mlp = SparseFeedForwardNet(
+ channels,
+ mlp_ratio=mlp_ratio,
+ device=device, dtype=dtype, operations=operations
+ )
+ if not share_mod:
+ self.adaLN_modulation = nn.Sequential(
+ nn.SiLU(),
+ operations.Linear(channels, 6 * channels, bias=True, device=device, dtype=dtype)
+ )
+ else:
+ self.modulation = nn.Parameter(torch.empty(6 * channels, device=device, dtype=dtype))
+
+ def _forward(self, x: SparseTensor, mod: torch.Tensor, context, transformer_options=None) -> SparseTensor:
+ if self.share_mod:
+ modulation = comfy.ops.cast_to_input(self.modulation, mod)
+ shift_msa, scale_msa, gate_msa, shift_mlp, scale_mlp, gate_mlp = (modulation + mod).chunk(6, dim=1)
+ else:
+ shift_msa, scale_msa, gate_msa, shift_mlp, scale_mlp, gate_mlp = self.adaLN_modulation(mod).chunk(6, dim=1)
+ # Fuse the (mul + add) and (mul + residual) pairs into addcmul
+ b_map = x.batch_boardcast_map
+
+ h_feats = self.norm1(x.feats)
+ h_feats = torch.addcmul(shift_msa[b_map], h_feats, (1 + scale_msa)[b_map])
+ h = self.self_attn(x.replace(h_feats), transformer_options=transformer_options)
+ x = x.replace(torch.addcmul(x.feats, h.feats, gate_msa[b_map]))
+
+ h = x.replace(self.norm2(x.feats))
+ if self.image_attn_mode == "global":
+ global_ctx, _ = _split_proj_context(context)
+ h = self.cross_attn(h, global_ctx, transformer_options=transformer_options)
+ else:
+ h = self.cross_attn(h, context, transformer_options=transformer_options)
+ x = x + h
+
+ h_feats = self.norm3(x.feats)
+ h_feats = torch.addcmul(shift_mlp[b_map], h_feats, (1 + scale_mlp)[b_map])
+ h = self.mlp(x.replace(h_feats))
+ x = x.replace(torch.addcmul(x.feats, h.feats, gate_mlp[b_map]))
+ return x
+
+ def forward(self, x: SparseTensor, mod: torch.Tensor, context, transformer_options=None) -> SparseTensor:
+ return self._forward(x, mod, context, transformer_options=transformer_options)
+
+
+class SLatFlowModel(nn.Module):
+ def __init__(
+ self,
+ resolution: int,
+ in_channels: int,
+ model_channels: int,
+ cond_channels: int,
+ out_channels: int,
+ num_blocks: int,
+ num_heads: Optional[int] = None,
+ num_head_channels: Optional[int] = 64,
+ mlp_ratio: float = 4,
+ share_mod: bool = False,
+ qk_rms_norm: bool = False,
+ qk_rms_norm_cross: bool = False,
+ image_attn_mode: Literal["global", "proj"] = "global",
+ proj_in_channels: Optional[int] = None,
+ dtype = None, device = None, operations = None,
+ ):
+ super().__init__()
+ self.resolution = resolution
+ self.in_channels = in_channels
+ self.model_channels = model_channels
+ self.cond_channels = cond_channels
+ self.out_channels = out_channels
+ self.num_blocks = num_blocks
+ self.num_heads = num_heads or model_channels // num_head_channels
+ self.mlp_ratio = mlp_ratio
+ self.share_mod = share_mod
+ self.qk_rms_norm = qk_rms_norm
+ self.qk_rms_norm_cross = qk_rms_norm_cross
+ self.image_attn_mode = image_attn_mode
+ self.proj_in_channels = proj_in_channels
+ self.dtype = dtype
+
+ self.t_embedder = TimestepEmbedder(model_channels, device=device, dtype=dtype, operations=operations)
+ if share_mod:
+ self.adaLN_modulation = nn.Sequential(
+ nn.SiLU(),
+ operations.Linear(model_channels, 6 * model_channels, bias=True, device=device, dtype=dtype)
+ )
+
+ self.input_layer = SparseLinear(in_channels, model_channels, device=device, dtype=dtype, operations=operations)
+
+ self.blocks = nn.ModuleList([
+ ModulatedSparseTransformerCrossBlock(
+ model_channels,
+ cond_channels,
+ num_heads=self.num_heads,
+ mlp_ratio=self.mlp_ratio,
+ share_mod=self.share_mod,
+ qk_rms_norm=self.qk_rms_norm,
+ qk_rms_norm_cross=self.qk_rms_norm_cross,
+ image_attn_mode=image_attn_mode,
+ proj_in_channels=proj_in_channels,
+ device=device, dtype=dtype, operations=operations
+ )
+ for _ in range(num_blocks)
+ ])
+
+ self.out_layer = SparseLinear(model_channels, out_channels, device=device, dtype=dtype, operations=operations)
+
+ @property
+ def device(self) -> torch.device:
+ return next(self.parameters()).device
+
+ def forward(
+ self,
+ x: SparseTensor,
+ t: torch.Tensor,
+ cond: Union[torch.Tensor, List[torch.Tensor]],
+ concat_cond: Optional[SparseTensor] = None,
+ transformer_options=None,
+ **kwargs,
+ ) -> SparseTensor:
+ if concat_cond is not None:
+ x = sparse_cat([x, concat_cond], dim=-1)
+ if isinstance(cond, list):
+ cond = VarLenTensor.from_tensor_list(cond)
+
+ h = self.input_layer(x)
+ t_emb = self.t_embedder(t, out_dtype=t.dtype)
+ if self.share_mod:
+ t_emb = self.adaLN_modulation(t_emb)
+
+ for block in self.blocks:
+ h = block(h, t_emb, cond, transformer_options=transformer_options)
+
+ h = h.replace(F.layer_norm(h.feats, h.feats.shape[-1:]))
+ h = self.out_layer(h)
+ return h
+
+class FeedForwardNet(nn.Module):
+ def __init__(self, channels: int, mlp_ratio: float = 4.0, device=None, dtype=None, operations=None):
+ super().__init__()
+ self.mlp = nn.Sequential(
+ operations.Linear(channels, int(channels * mlp_ratio), device=device, dtype=dtype),
+ nn.GELU(approximate="tanh"),
+ operations.Linear(int(channels * mlp_ratio), channels, device=device, dtype=dtype),
+ )
+
+ def forward(self, x: torch.Tensor) -> torch.Tensor:
+ return self.mlp(x)
+
+class MultiHeadAttention(nn.Module):
+ def __init__(
+ self,
+ channels: int,
+ num_heads: int,
+ ctx_channels: Optional[int]=None,
+ type: Literal["self", "cross"] = "self",
+ qkv_bias: bool = True,
+ qk_rms_norm: bool = False,
+ device=None, dtype=None, operations=None
+ ):
+ super().__init__()
+
+ self.channels = channels
+ self.head_dim = channels // num_heads
+ self.ctx_channels = ctx_channels if ctx_channels is not None else channels
+ self.num_heads = num_heads
+ self._type = type
+ self.qk_rms_norm = qk_rms_norm
+
+ if self._type == "self":
+ self.to_qkv = operations.Linear(channels, channels * 3, bias=qkv_bias, dtype=dtype, device=device)
+ else:
+ self.to_q = operations.Linear(channels, channels, bias=qkv_bias, device=device, dtype=dtype)
+ self.to_kv = operations.Linear(self.ctx_channels, channels * 2, bias=qkv_bias, device=device, dtype=dtype)
+
+ if self.qk_rms_norm:
+ self.q_rms_norm = MultiHeadRMSNorm(self.head_dim, num_heads, device=device, dtype=dtype)
+ self.k_rms_norm = MultiHeadRMSNorm(self.head_dim, num_heads, device=device, dtype=dtype)
+
+ self.to_out = operations.Linear(channels, channels, device=device, dtype=dtype)
+
+ def forward(self, x: torch.Tensor, context: Optional[torch.Tensor] = None,
+ phases: Optional[torch.Tensor] = None, transformer_options=None) -> torch.Tensor:
+ B, L, C = x.shape
+ if self._type == "self":
+ qkv = self.to_qkv(x)
+ qkv = qkv.reshape(B, L, 3, self.num_heads, -1)
+ q, k, v = qkv.unbind(dim=2)
+ if self.qk_rms_norm:
+ q = self.q_rms_norm(q)
+ k = self.k_rms_norm(k)
+ assert phases is not None, "Phases must be provided for RoPE"
+ # phases is [L, head_dim/2, 2, 2]; broadcast to [1, L, 1, ...]
+ # to align with q/k of shape [B, L, H, head_dim].
+ f_cis = comfy.model_management.cast_to(phases, device=q.device).unsqueeze(0).unsqueeze(2)
+ q, k = apply_rope(q, k, f_cis)
+ h = dense_attention(q, k, v, transformer_options=transformer_options)
+ else:
+ Lkv = context.shape[1]
+ q = self.to_q(x)
+ kv = self.to_kv(context)
+ q = q.reshape(B, L, self.num_heads, -1)
+ kv = kv.reshape(B, Lkv, 2, self.num_heads, -1)
+ k, v = kv.unbind(dim=2)
+ if self.qk_rms_norm:
+ q = self.q_rms_norm(q)
+ k = self.k_rms_norm(k)
+ h = dense_attention(q, k, v, transformer_options=transformer_options)
+ h = h.reshape(B, L, -1)
+ h = self.to_out(h)
+ return h
+
+class ModulatedTransformerCrossBlock(nn.Module):
+ def __init__(
+ self,
+ channels: int,
+ ctx_channels: int,
+ num_heads: int,
+ mlp_ratio: float = 4.0,
+ qk_rms_norm: bool = False,
+ qk_rms_norm_cross: bool = False,
+ qkv_bias: bool = True,
+ share_mod: bool = False,
+ image_attn_mode: Literal["global", "proj"] = "global",
+ proj_in_channels: Optional[int] = None,
+ device=None, dtype=None, operations=None
+ ):
+ super().__init__()
+ self.share_mod = share_mod
+ self.image_attn_mode = image_attn_mode
+ self.norm1 = operations.LayerNorm(channels, elementwise_affine=False, eps=1e-6, device=device, dtype=dtype)
+ self.norm2 = operations.LayerNorm(channels, elementwise_affine=True, eps=1e-6, device=device, dtype=dtype)
+ self.norm3 = operations.LayerNorm(channels, elementwise_affine=False, eps=1e-6, device=device, dtype=dtype)
+ self.self_attn = MultiHeadAttention(
+ channels,
+ num_heads=num_heads,
+ type="self",
+ qkv_bias=qkv_bias,
+ qk_rms_norm=qk_rms_norm,
+ device=device, dtype=dtype, operations=operations
+ )
+ cross_inner = MultiHeadAttention(
+ channels,
+ ctx_channels=ctx_channels,
+ num_heads=num_heads,
+ type="cross",
+ qkv_bias=qkv_bias,
+ qk_rms_norm=qk_rms_norm_cross,
+ device=device, dtype=dtype, operations=operations
+ )
+ if image_attn_mode == "global":
+ self.cross_attn = cross_inner
+ else:
+ if proj_in_channels is None:
+ raise ValueError("proj_in_channels must be set when image_attn_mode != 'global'")
+ self.cross_attn = ProjectAttentionDense(
+ cross_inner, channels, proj_in_channels,
+ device=device, dtype=dtype, operations=operations,
+ )
+ self.mlp = FeedForwardNet(
+ channels,
+ mlp_ratio=mlp_ratio,
+ device=device, dtype=dtype, operations=operations
+ )
+ if not share_mod:
+ self.adaLN_modulation = nn.Sequential(nn.SiLU(), operations.Linear(channels, 6 * channels, bias=True, dtype=dtype, device=device))
+ else:
+ self.modulation = nn.Parameter(torch.empty(6 * channels, device=device, dtype=dtype))
+
+ def _forward(self, x: torch.Tensor, mod: torch.Tensor, context,
+ phases: Optional[torch.Tensor] = None, transformer_options=None) -> torch.Tensor:
+ if self.share_mod:
+ mod = comfy.ops.cast_to_input(self.modulation, mod) + mod
+ else:
+ mod = self.adaLN_modulation(mod)
+ shift_msa, scale_msa, gate_msa, shift_mlp, scale_mlp, gate_mlp = mod.unsqueeze(1).chunk(6, dim=-1)
+
+ h = torch.addcmul(shift_msa, self.norm1(x), 1 + scale_msa)
+ h = self.self_attn(h, phases=phases, transformer_options=transformer_options)
+ x = torch.addcmul(x, h, gate_msa)
+
+ h = self.norm2(x)
+ if self.image_attn_mode == "global":
+ global_ctx, _ = _split_proj_context(context)
+ h = self.cross_attn(h, global_ctx, transformer_options=transformer_options)
+ else:
+ h = self.cross_attn(h, context, transformer_options=transformer_options)
+ x = x + h
+
+ h = torch.addcmul(shift_mlp, self.norm3(x), 1 + scale_mlp)
+ h = self.mlp(h)
+ x = torch.addcmul(x, h, gate_mlp)
+ return x
+
+ def forward(self, x: torch.Tensor, mod: torch.Tensor, context,
+ phases: Optional[torch.Tensor] = None, transformer_options=None) -> torch.Tensor:
+ return self._forward(x, mod, context, phases, transformer_options=transformer_options)
+
+
+class SparseStructureFlowModel(nn.Module):
+ def __init__(
+ self,
+ resolution: int,
+ in_channels: int,
+ model_channels: int,
+ cond_channels: int,
+ out_channels: int,
+ num_blocks: int,
+ num_heads: Optional[int] = None,
+ num_head_channels: Optional[int] = 64,
+ mlp_ratio: float = 4,
+ share_mod: bool = False,
+ qk_rms_norm: bool = False,
+ qk_rms_norm_cross: bool = False,
+ image_attn_mode: Literal["global", "proj"] = "global",
+ proj_in_channels: Optional[int] = None,
+ operations=None,
+ device = None,
+ dtype = None,
+ **kwargs
+ ):
+ super().__init__()
+ self.device = device
+ self.resolution = resolution
+ self.in_channels = in_channels
+ self.model_channels = model_channels
+ self.cond_channels = cond_channels
+ self.out_channels = out_channels
+ self.num_blocks = num_blocks
+ self.num_heads = num_heads or model_channels // num_head_channels
+ self.mlp_ratio = mlp_ratio
+ self.share_mod = share_mod
+ self.qk_rms_norm = qk_rms_norm
+ self.qk_rms_norm_cross = qk_rms_norm_cross
+ self.image_attn_mode = image_attn_mode
+ self.proj_in_channels = proj_in_channels
+ self.dtype = dtype
+ self.device = device
+
+ self.t_embedder = TimestepEmbedder(model_channels, dtype=dtype, device=device, operations=operations)
+ if share_mod:
+ self.adaLN_modulation = nn.Sequential(
+ nn.SiLU(),
+ operations.Linear(model_channels, 6 * model_channels, bias=True, device=device, dtype=dtype)
+ )
+
+ pos_embedder = RotaryPositionEmbedder(self.model_channels // self.num_heads, 3, device=device)
+ coords = torch.meshgrid(*[torch.arange(res, device=self.device, dtype=dtype) for res in [resolution] * 3], indexing='ij')
+ coords = torch.stack(coords, dim=-1).reshape(-1, 3)
+ rope_phases = pos_embedder(coords)
+ self.register_buffer("rope_phases", rope_phases, persistent=False)
+
+ self.input_layer = operations.Linear(in_channels, model_channels, device=device, dtype=dtype)
+
+ self.blocks = nn.ModuleList([
+ ModulatedTransformerCrossBlock(
+ model_channels,
+ cond_channels,
+ num_heads=self.num_heads,
+ mlp_ratio=self.mlp_ratio,
+ share_mod=share_mod,
+ qk_rms_norm=self.qk_rms_norm,
+ qk_rms_norm_cross=self.qk_rms_norm_cross,
+ image_attn_mode=image_attn_mode,
+ proj_in_channels=proj_in_channels,
+ device=device, dtype=dtype, operations=operations
+ )
+ for _ in range(num_blocks)
+ ])
+
+ self.out_layer = operations.Linear(model_channels, out_channels, device=device, dtype=dtype)
+
+ def forward(self, x: torch.Tensor, t: torch.Tensor, cond: torch.Tensor,
+ transformer_options=None) -> torch.Tensor:
+ x = x.view(x.shape[0], self.in_channels, *[self.resolution] * 3)
+
+ h = x.view(*x.shape[:2], -1).permute(0, 2, 1).contiguous()
+
+ h = self.input_layer(h)
+ t_emb = self.t_embedder(t, out_dtype=t.dtype)
+ if self.share_mod:
+ t_emb = self.adaLN_modulation(t_emb)
+ for block in self.blocks:
+ h = block(h, t_emb, cond, self.rope_phases, transformer_options=transformer_options)
+ h = F.layer_norm(h, h.shape[-1:])
+ h = self.out_layer(h)
+
+ h = h.permute(0, 2, 1).view(h.shape[0], h.shape[2], *[self.resolution] * 3).contiguous()
+
+ return h
+
+
+# Pixal3D ProjGrid math
+# World frame uses world Y as depth, camera looks along -Z local
+# transform_matrix is camera-to-world (inverted internally). Intrinsics: fx = 16 / tan(fov/2) with sensor_width = 32mm.
+
+_PROJ_GRID_ROTATION = torch.tensor(
+ [[1.0, 0.0, 0.0],
+ [0.0, 0.0, -1.0],
+ [0.0, 1.0, 0.0]]
+)
+
+_PROJ_FRONT_VIEW_TRANSFORM = torch.tensor(
+ [[1.0, 0.0, 0.0, 0.0],
+ [0.0, 0.0, -1.0, -2.0],
+ [0.0, 1.0, 0.0, 0.0],
+ [0.0, 0.0, 0.0, 1.0]]
+)
+
+
+def build_proj_transform_matrix(distance: torch.Tensor, batch_size: int,
+ device, dtype=torch.float32) -> torch.Tensor:
+ T = _PROJ_FRONT_VIEW_TRANSFORM.to(device=device, dtype=dtype)
+ T = T.unsqueeze(0).expand(batch_size, -1, -1).clone()
+ if distance.ndim == 0:
+ distance = distance.expand(batch_size)
+ T[:, 1, 3] = -distance.to(device=device, dtype=dtype)
+ return T
+
+
+def _project_points_to_image(points_world: torch.Tensor, transform_matrix: torch.Tensor,
+ camera_angle_x: torch.Tensor, resolution: int):
+ B, N, _ = points_world.shape
+ ones = torch.ones((B, N, 1), device=points_world.device, dtype=points_world.dtype)
+ homo = torch.cat([points_world, ones], dim=-1)
+ world_to_camera = torch.linalg.inv(transform_matrix.float()).to(transform_matrix.dtype)
+ p_cam = torch.bmm(homo, world_to_camera.transpose(-2, -1))[..., :3]
+ x_cam, y_cam, z_cam = p_cam.unbind(dim=-1)
+ depth = -z_cam
+ sensor_width = 32.0
+ focal_length = 16.0 / torch.tan(camera_angle_x / 2.0)
+ focal_px = focal_length * resolution / sensor_width
+ focal_px = focal_px.to(p_cam.dtype).unsqueeze(1)
+ denom = (-z_cam + 1e-8)
+ x_pix = focal_px * x_cam / denom + resolution / 2.0
+ y_pix = -focal_px * y_cam / denom + resolution / 2.0
+ valid = ((x_pix >= 0) & (x_pix < resolution) &
+ (y_pix >= 0) & (y_pix < resolution) & (depth > 0))
+ return torch.stack([x_pix, y_pix], dim=-1), depth, valid
+
+
+def _sample_features(feature_map: torch.Tensor, uv_ndc: torch.Tensor) -> torch.Tensor:
+ B, C, _, _ = feature_map.shape
+ grid = uv_ndc.view(B, -1, 1, 2).to(feature_map.dtype)
+ feat = F.grid_sample(feature_map, grid, mode="bilinear", padding_mode="border", align_corners=False)
+ return feat.squeeze(-1)
+
+
+def _coords_to_proj_world(coords: torch.Tensor, resolution: int, mesh_scale: torch.Tensor):
+ if resolution < 1:
+ raise ValueError(f"resolution must be positive, got {resolution}")
+ batch_ids = coords[:, 0].long()
+ if resolution == 1:
+ norm = coords[:, 1:].to(torch.float32) * 0.0
+ else:
+ norm = coords[:, 1:].to(torch.float32) / (resolution - 1) * 2.0 - 1.0
+ R = _PROJ_GRID_ROTATION.to(device=coords.device, dtype=torch.float32)
+ rotated = norm @ R.T
+ if mesh_scale.ndim == 0:
+ scale_per_voxel = mesh_scale.expand(coords.shape[0])
+ else:
+ scale_per_voxel = mesh_scale.to(coords.device)[batch_ids]
+ world = rotated / scale_per_voxel.unsqueeze(-1) / 2.0
+ return world, batch_ids
+
+
+def _dense_grid_proj_world(resolution: int, mesh_scale: torch.Tensor,
+ batch_size: int, device, dtype=torch.float32) -> torch.Tensor:
+ one = torch.linspace(-1.0, 1.0, resolution, device=device, dtype=dtype)
+ x, y, z = torch.meshgrid(one, one, one, indexing="ij")
+ grid = torch.stack([x, y, z], dim=-1).reshape(-1, 3)
+ R_rot = _PROJ_GRID_ROTATION.to(device=device, dtype=dtype)
+ grid = grid @ R_rot.T
+ grid = grid.unsqueeze(0).expand(batch_size, -1, -1).clone()
+ if mesh_scale.ndim == 0:
+ mesh_scale = mesh_scale.expand(batch_size)
+ grid = grid / mesh_scale.to(device=device, dtype=dtype).view(-1, 1, 1) / 2.0
+ return grid
+
+
+def _back_project_to_tokens(
+ coords_world: torch.Tensor,
+ feature_map: torch.Tensor,
+ transform_matrix: torch.Tensor,
+ camera_angle_x: torch.Tensor,
+ image_resolution: int,
+ batch_ids: Optional[torch.Tensor] = None,
+) -> torch.Tensor:
+ if coords_world.dim() == 2:
+ assert batch_ids is not None
+ B = transform_matrix.shape[0]
+ out = torch.zeros((coords_world.shape[0], feature_map.shape[1]),
+ device=feature_map.device, dtype=feature_map.dtype)
+ for b in range(B):
+ mask = batch_ids == b
+ if not mask.any():
+ continue
+ p = coords_world[mask].unsqueeze(0)
+ uv, _, _ = _project_points_to_image(
+ p, transform_matrix[b:b+1], camera_angle_x[b:b+1], image_resolution)
+ uv_ndc = (uv + 0.5) / image_resolution * 2.0 - 1.0
+ # padding_mode='border' is load-bearing: masking out-of-frame voxels confuses
+ # the SS DiT (~half the voxels go to zero, producing low poly + rotation drift).
+ sampled = _sample_features(feature_map[b:b+1], uv_ndc)
+ sampled = sampled.squeeze(0).transpose(0, 1)
+ out[mask] = sampled
+ return out
+ else:
+ uv, _, _ = _project_points_to_image(
+ coords_world, transform_matrix, camera_angle_x, image_resolution)
+ uv_ndc = (uv + 0.5) / image_resolution * 2.0 - 1.0
+ sampled = _sample_features(feature_map, uv_ndc)
+ out = sampled.transpose(1, 2)
+ return out
+
+
+def _select_stage_entry(proj_pack: dict, stage: Optional[str]):
+ """Returns (feature_map_lr, feature_map_hr_or_None, image_resolution)."""
+ stages = proj_pack.get("stages")
+ if stages is not None and stage is not None and stage in stages:
+ entry = stages[stage]
+ return entry["feature_map"], entry.get("feature_map_hr"), int(entry.get("image_resolution", 1024))
+ if "feature_map" in proj_pack:
+ return proj_pack["feature_map"], proj_pack.get("feature_map_hr"), int(proj_pack.get("image_resolution", 1024))
+ raise ValueError(f"proj_feat_pack has no usable feature_map (stage={stage!r})")
+
+
+def compute_stage_proj_feats(
+ proj_pack: dict,
+ stage: str,
+ coords: Optional[torch.Tensor] = None,
+ coord_resolution: Optional[int] = None,
+ dense_grid_resolution: Optional[int] = None,
+ batch_size: Optional[int] = None,
+ device=None,
+) -> torch.Tensor:
+ """Back-project a Pixal3D stage's feature maps onto its target voxel/grid coords.
+
+ For sparse (shape / texture) stages: pass ``coords`` (with ``coord_resolution``).
+ Returns ``[N_voxels, C]`` per-voxel features with channel count =
+ LR channels + optional HR channels.
+
+ For the dense SS stage: pass ``dense_grid_resolution`` (16) + ``batch_size``.
+ Returns ``[B, R^3, C]`` features for the dense grid.
+
+ """
+ if device is None:
+ device = coords.device if coords is not None else proj_pack["mesh_scale"].device
+ mesh_scale = proj_pack["mesh_scale"].to(device)
+ T = proj_pack["transform_matrix"].to(device)
+ cam_angle = proj_pack["camera_angle_x"].to(device)
+ feat_map_lr, feat_map_hr, image_resolution = _select_stage_entry(proj_pack, stage)
+ feat_map_lr = feat_map_lr.to(device)
+ if feat_map_hr is not None:
+ feat_map_hr = feat_map_hr.to(device)
+
+ if coords is not None:
+ if coord_resolution is None:
+ raise ValueError("compute_stage_proj_feats: coord_resolution required when coords is given")
+ coords_world, batch_ids = _coords_to_proj_world(coords, coord_resolution, mesh_scale)
+ else:
+ if dense_grid_resolution is None or batch_size is None:
+ raise ValueError("compute_stage_proj_feats: dense_grid_resolution + batch_size required for dense path")
+ coords_world = _dense_grid_proj_world(dense_grid_resolution, mesh_scale, batch_size,
+ device=device, dtype=torch.float32)
+ batch_ids = None
+
+ proj_lr = _back_project_to_tokens(coords_world, feat_map_lr, T, cam_angle,
+ image_resolution=image_resolution, batch_ids=batch_ids)
+ if feat_map_hr is not None:
+ proj_hr = _back_project_to_tokens(coords_world, feat_map_hr, T, cam_angle,
+ image_resolution=image_resolution, batch_ids=batch_ids)
+ return torch.cat([proj_lr, proj_hr], dim=-1)
+ return proj_lr
+
+
+def _shape_proj_cond(global_cond: torch.Tensor, image_attn_mode: str,
+ proj_feats: Optional[torch.Tensor],
+ batch_ids: Optional[torch.Tensor] = None,
+ eval_batch: Optional[int] = None,
+ logical_batch: Optional[int] = None,
+ proj_in_channels: Optional[int] = None,
+ stage: Optional[str] = None,
+ cond_or_uncond: Optional[list] = None):
+ """Take pre-computed per-token proj features (from compute_stage_proj_feats),
+ apply CFG-batch duplication + uncond-slot zeroing, and wrap into the
+ ``{"global", "proj"}`` context dict consumed by ProjectAttention.
+
+ proj_feats shape:
+ sparse (shape/texture): [N_voxels, C] (batch_ids gives per-voxel batch)
+ dense (SS): [B, N, C]
+ """
+ if image_attn_mode == "global":
+ return global_cond
+ if proj_feats is None:
+ raise ValueError(f"image_attn_mode={image_attn_mode!r} but trellis2_proj_feats is missing — "
+ f"the stage setup node (or Pixal3DConditioning for SS) should have computed it.")
+ if proj_in_channels is not None and proj_feats.shape[-1] != proj_in_channels:
+ hint = ""
+ if proj_feats.shape[-1] < proj_in_channels:
+ hint = (" — the shape/texture stages need the NAF-upsampled feature map from "
+ "a Pixal3D DINOv3 checkpoint containing naf. weights.")
+ raise ValueError(
+ f"proj_feats for stage {stage!r} has {proj_feats.shape[-1]} channels, "
+ f"sub-model expects {proj_in_channels}.{hint}"
+ )
+
+ # CFG-duplicate proj_feats to match the model's eval batch.
+ if eval_batch is not None and logical_batch is not None and eval_batch > logical_batch:
+ repeats = eval_batch // logical_batch
+ if batch_ids is None:
+ proj_feats = proj_feats.repeat((repeats,) + (1,) * (proj_feats.ndim - 1))
+ else:
+ proj_feats = proj_feats.repeat((repeats, 1))
+
+ # zero proj for any uncond batch slot
+ if cond_or_uncond is not None and eval_batch is not None:
+ uncond_slots = [i for i, v in enumerate(cond_or_uncond) if v == 1]
+ if uncond_slots:
+ uncond_batches = [batch_idx
+ for slot in uncond_slots
+ for batch_idx in range(slot * logical_batch,
+ min((slot + 1) * logical_batch, eval_batch))]
+ uncond_idx = torch.tensor(uncond_batches, device=proj_feats.device, dtype=torch.long)
+ if batch_ids is None:
+ proj_feats = proj_feats.clone()
+ proj_feats[uncond_idx] = 0
+ else:
+ neg_mask = torch.isin(batch_ids, uncond_idx).unsqueeze(-1).to(proj_feats.dtype)
+ proj_feats = proj_feats * (1.0 - neg_mask)
+ return {"global": global_cond, "proj": proj_feats}
+
+class Trellis2(nn.Module):
+ def __init__(self, resolution,
+ in_channels = 32,
+ out_channels = 32,
+ model_channels = 1536,
+ cond_channels = 1024,
+ num_blocks = 30,
+ num_heads = 12,
+ mlp_ratio = 5.3334,
+ share_mod = True,
+ qk_rms_norm = True,
+ qk_rms_norm_cross = True,
+ init_txt_model=False, # for now
+ image_attn_mode_structure: str = "global",
+ proj_in_channels_structure: Optional[int] = None,
+ image_attn_mode_shape: str = "global",
+ proj_in_channels_shape: Optional[int] = None,
+ image_attn_mode_texture: str = "global",
+ proj_in_channels_texture: Optional[int] = None,
+ dtype=None, device=None, operations=None, **kwargs):
+
+ super().__init__()
+ self.dtype = dtype
+ args = {
+ "out_channels":out_channels, "num_blocks":num_blocks, "cond_channels" :cond_channels,
+ "model_channels":model_channels, "num_heads":num_heads, "mlp_ratio": mlp_ratio, "share_mod": share_mod,
+ "qk_rms_norm": qk_rms_norm, "qk_rms_norm_cross": qk_rms_norm_cross, "device": device, "dtype": dtype, "operations": operations
+ }
+ self.image_attn_mode_structure = image_attn_mode_structure
+ self.image_attn_mode_shape = image_attn_mode_shape
+ self.image_attn_mode_texture = image_attn_mode_texture
+ shape_proj_kwargs = {"image_attn_mode": image_attn_mode_shape, "proj_in_channels": proj_in_channels_shape}
+ tex_proj_kwargs = {"image_attn_mode": image_attn_mode_texture, "proj_in_channels": proj_in_channels_texture}
+ struct_proj_kwargs = {"image_attn_mode": image_attn_mode_structure, "proj_in_channels": proj_in_channels_structure}
+ txt_only = kwargs.get("txt_only", False)
+ if not txt_only:
+ self.img2shape = SLatFlowModel(resolution=resolution, in_channels=in_channels, **shape_proj_kwargs, **args)
+ self.shape2txt = None
+ if init_txt_model:
+ self.shape2txt = SLatFlowModel(resolution=resolution, in_channels=in_channels*2, **tex_proj_kwargs, **args)
+ self.img2shape_512 = SLatFlowModel(resolution=32, in_channels=in_channels, **shape_proj_kwargs, **args)
+ args.pop("out_channels")
+ self.structure_model = SparseStructureFlowModel(resolution=16, in_channels=8, out_channels=8, **struct_proj_kwargs, **args)
+ else:
+ self.shape2txt = SLatFlowModel(resolution=resolution, in_channels=in_channels*2, **tex_proj_kwargs, **args)
+
+ def forward(self, x, timestep, context, **kwargs):
+ transformer_options = kwargs.get("transformer_options", {})
+ cond_or_uncond = transformer_options.get("cond_or_uncond")
+ timestep = timestep.to(x.dtype)
+ embeds = kwargs.get("embeds")
+ if embeds is None:
+ raise ValueError("Trellis2.forward requires 'embeds' in kwargs")
+
+ # Per-stage cascade metadata
+ coords = kwargs.get("trellis2_coords")
+ coord_counts = kwargs.get("trellis2_coord_counts")
+ mode = kwargs.get("trellis2_generation_mode", "structure_generation")
+ # Pre-computed per-stage back-projected features
+ proj_feats = kwargs.get("trellis2_proj_feats")
+
+ is_first_shape_pass = False
+ if mode == "shape_generation_512":
+ is_first_shape_pass = True
+ mode = "shape_generation"
+
+ if coords is not None:
+ x = x.squeeze(-1).transpose(1, 2)
+ is_sparse_mode = True
+ else:
+ mode = "structure_generation"
+ is_sparse_mode = False
+
+ if x.size(-1) == 16 and x.size(-2) == 16:
+ mode = "structure_generation"
+ is_sparse_mode = False
+
+ if not is_sparse_mode:
+ bsz = x.size(0)
+ x = x[:, :8]
+ x = x.view(bsz, 8, 16, 16, 16)
+
+ if is_sparse_mode and not is_first_shape_pass:
+ context = embeds
+
+ if is_sparse_mode:
+ t_eval = timestep
+ c_eval = context
+
+ B, N, C = x.shape
+
+ # Vectorized SparseTensor Construction
+ if mode in ["shape_generation", "texture_generation"]:
+ if coord_counts is not None:
+ logical_batch = coord_counts.shape[0]
+ # Duplicate sparse coords when the sampler asks for >1 cond
+ # (CFG or otherwise). Each duplicate is offset along col 0
+ # so SparseTensor sees a fresh logical batch.
+ if B > logical_batch:
+ reps = B // logical_batch
+ c_copies = []
+ for i in range(reps):
+ c = coords.clone()
+ c[:, 0] += i * logical_batch
+ c_copies.append(c)
+ batched_coords = torch.cat(c_copies, dim=0)
+ counts_eval = coord_counts.repeat(reps)
+ else:
+ batched_coords = coords
+ counts_eval = coord_counts
+
+ # Boolean mask [B, N] to drop the padded zeros instantly
+ mask = torch.arange(N, device=x.device).unsqueeze(0) < counts_eval.unsqueeze(1)
+ feats_flat = x[mask]
+ else:
+ feats_flat = x.reshape(-1, C)
+ coords_list = []
+ for i in range(B):
+ c = coords.clone()
+ c[:, 0] = i
+ coords_list.append(c)
+ batched_coords = torch.cat(coords_list, dim=0)
+ mask = None
+ else:
+ batched_coords = coords
+ feats_flat = x
+ mask = None
+
+ x_st = SparseTensor(
+ feats=feats_flat,
+ coords=batched_coords.to(device=x.device, dtype=torch.int32),
+ shape=torch.Size([B] + list(feats_flat.shape[1:])),
+ )
+
+ if mode == "shape_generation":
+ shape_attn = self.image_attn_mode_shape
+ if shape_attn != "global":
+ sub_model = self.img2shape_512 if is_first_shape_pass else self.img2shape
+ stage_name = "shape_512" if is_first_shape_pass else "shape_1024"
+ # batched_coords carries CFG-doubled batch ids in col 0; per-voxel
+ # batch_ids drive uncond-slot masking inside _shape_proj_cond.
+ batch_ids = batched_coords[:, 0].long()
+ logical_batch = coord_counts.shape[0] if coord_counts is not None else B
+ c_eval = _shape_proj_cond(c_eval, shape_attn, proj_feats,
+ batch_ids=batch_ids,
+ eval_batch=B, logical_batch=logical_batch,
+ proj_in_channels=sub_model.proj_in_channels,
+ stage=stage_name,
+ cond_or_uncond=cond_or_uncond)
+ if is_first_shape_pass:
+ out = self.img2shape_512(x_st, t_eval, c_eval, transformer_options=transformer_options)
+ else:
+ out = self.img2shape(x_st, t_eval, c_eval, transformer_options=transformer_options)
+
+ elif mode == "texture_generation":
+ if self.shape2txt is None:
+ raise ValueError("Checkpoint for Trellis2 doesn't include texture generation!")
+ slat = kwargs.get("trellis2_shape_slat")
+ if slat is None:
+ raise ValueError("shape_slat can't be None")
+
+ slat_feats = slat
+ # Duplicate shape context if CFG is active
+ if coord_counts is not None and B > coord_counts.shape[0]:
+ slat_feats = slat_feats.repeat(B // coord_counts.shape[0], 1)
+ elif coord_counts is None:
+ slat_feats = slat_feats[:N].repeat(B, 1)
+
+ x_st = x_st.replace(feats=torch.cat([x_st.feats, slat_feats.to(x_st.feats.device)], dim=-1))
+ tex_attn = self.image_attn_mode_texture
+ if tex_attn != "global":
+ batch_ids = batched_coords[:, 0].long()
+ logical_batch = coord_counts.shape[0] if coord_counts is not None else B
+ c_eval = _shape_proj_cond(c_eval, tex_attn, proj_feats,
+ batch_ids=batch_ids,
+ eval_batch=B, logical_batch=logical_batch,
+ proj_in_channels=self.shape2txt.proj_in_channels,
+ stage="tex_1024",
+ cond_or_uncond=cond_or_uncond)
+ out = self.shape2txt(x_st, t_eval, c_eval, transformer_options=transformer_options)
+
+ else: # structure
+ struct_attn = self.image_attn_mode_structure
+ logical_batch_ss = proj_feats.shape[0] if proj_feats is not None else x.shape[0]
+ struct_cond = context
+ if struct_attn != "global":
+ struct_cond = _shape_proj_cond(context, struct_attn, proj_feats,
+ batch_ids=None,
+ eval_batch=x.shape[0], logical_batch=logical_batch_ss,
+ proj_in_channels=self.structure_model.proj_in_channels,
+ stage="ss",
+ cond_or_uncond=cond_or_uncond)
+ out = self.structure_model(x, timestep, struct_cond, transformer_options=transformer_options)
+
+ if is_sparse_mode:
+ if mask is not None:
+ # Instantly scatter the valid tokens back into a padded rectangular tensor
+ padded_out = torch.zeros((B, N, out.feats.shape[-1]), device=x.device, dtype=out.feats.dtype)
+ padded_out[mask] = out.feats
+ out_tensor = padded_out.transpose(1, 2).unsqueeze(-1)
+ else:
+ out_tensor = out.feats.view(B, N, -1).transpose(1, 2).unsqueeze(-1)
+ return out_tensor
+ else:
+ out = torch.nn.functional.pad(out, (0, 0, 0, 0, 0, 0, 0, 24))
+
+ return out
diff --git a/comfy/ldm/trellis2/vae.py b/comfy/ldm/trellis2/vae.py
new file mode 100644
index 000000000..d0d00ce04
--- /dev/null
+++ b/comfy/ldm/trellis2/vae.py
@@ -0,0 +1,1092 @@
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from fractions import Fraction
+from typing import List, Any, Dict, Optional, overload, Union
+import comfy.ops
+from comfy.ldm.trellis2.flexgemm import TorchHashMap, sparse_submanifold_conv3d
+
+ops = comfy.ops.disable_weight_init
+
+
+def pixel_shuffle_3d(x: torch.Tensor, scale_factor: int) -> torch.Tensor:
+ B, C, H, W, D = x.shape
+ C_ = C // scale_factor**3
+ x = x.reshape(B, C_, scale_factor, scale_factor, scale_factor, H, W, D)
+ x = x.permute(0, 1, 5, 2, 6, 3, 7, 4)
+ x = x.reshape(B, C_, H*scale_factor, W*scale_factor, D*scale_factor)
+ return x
+
+class SparseConv3d(nn.Module):
+ def __init__(self, in_channels, out_channels, kernel_size, stride=1, dilation=1, padding=None, bias=True, indice_key=None):
+ super(SparseConv3d, self).__init__()
+ sparse_conv3d_init(self, in_channels, out_channels, kernel_size, stride, dilation, padding, bias, indice_key)
+
+ def forward(self, x):
+ return sparse_conv3d_forward(self, x)
+
+
+def sparse_conv3d_init(self, in_channels, out_channels, kernel_size, stride=1, dilation=1, padding=None, bias=True, indice_key=None):
+
+ self.in_channels = in_channels
+ self.out_channels = out_channels
+ self.kernel_size = tuple(kernel_size) if isinstance(kernel_size, (list, tuple)) else (kernel_size, ) * 3
+ self.stride = tuple(stride) if isinstance(stride, (list, tuple)) else (stride, ) * 3
+ self.dilation = tuple(dilation) if isinstance(dilation, (list, tuple)) else (dilation, ) * 3
+
+ self.weight = nn.Parameter(torch.empty((out_channels, in_channels, *self.kernel_size)))
+ if bias:
+ self.bias = nn.Parameter(torch.empty(out_channels))
+ else:
+ self.register_parameter("bias", None)
+
+ # Permute weight (Co, Ci, Kd, Kh, Kw) -> (Co, Kd, Kh, Kw, Ci)
+ self.weight = nn.Parameter(self.weight.permute(0, 2, 3, 4, 1).contiguous())
+
+
+def sparse_conv3d_forward(self, x):
+ # check if neighbor map is already computed
+ Co, Kd, Kh, Kw, Ci = self.weight.shape
+ neighbor_cache_key = f'SubMConv3d_neighbor_cache_{Kw}x{Kh}x{Kd}_dilation{self.dilation}'
+ neighbor_cache = x.get_spatial_cache(neighbor_cache_key)
+ feats = x.feats
+ weight = comfy.ops.cast_to(self.weight, feats.dtype, feats.device)
+ bias = comfy.ops.cast_to(self.bias, feats.dtype, feats.device) if self.bias is not None else None
+
+ out, neighbor_cache_ = sparse_submanifold_conv3d(
+ x.feats,
+ x.coords,
+ x.spatial_shape,
+ weight,
+ bias,
+ neighbor_cache,
+ self.dilation
+ )
+
+ if neighbor_cache is None:
+ x.register_spatial_cache(neighbor_cache_key, neighbor_cache_)
+
+ out = x.replace(out)
+ return out
+
+class SparseConvNeXtBlock3d(nn.Module):
+ def __init__(self, channels: int, mlp_ratio: float = 4.0):
+ super().__init__()
+ self.channels = channels
+
+ self.norm = ops.LayerNorm(channels, elementwise_affine=True, eps=1e-6)
+ self.conv = SparseConv3d(channels, channels, 3)
+ self.mlp = nn.Sequential(
+ ops.Linear(channels, int(channels * mlp_ratio)),
+ nn.SiLU(inplace=True),
+ ops.Linear(int(channels * mlp_ratio), channels),
+ )
+
+ def _forward(self, x):
+ h = self.conv(x)
+ h = h.replace(self.norm(h.feats))
+ h = h.replace(self.mlp(h.feats))
+ h.feats.add_(x.feats.to(h.feats))
+ return h
+
+ def forward(self, x):
+ return self._forward(x)
+
+class SparseSpatial2Channel(nn.Module):
+ def __init__(self, factor: int = 2):
+ super(SparseSpatial2Channel, self).__init__()
+ self.factor = factor
+
+ def forward(self, x):
+ DIM = x.coords.shape[-1] - 1
+ cache = x.get_spatial_cache(f'spatial2channel_{self.factor}')
+ if cache is None:
+ coord = list(x.coords.unbind(dim=-1))
+ for i in range(DIM):
+ coord[i+1] = coord[i+1] // self.factor
+ subidx = x.coords[:, 1:] % self.factor
+ subidx = sum([subidx[..., i] * self.factor ** i for i in range(DIM)])
+
+ MAX = [(s + self.factor - 1) // self.factor for s in x.spatial_shape]
+ OFFSET = [1]
+ for size in reversed(MAX):
+ OFFSET.append(OFFSET[-1] * size)
+ OFFSET.reverse()
+ code = sum([c * o for c, o in zip(coord, OFFSET)])
+ code, idx = code.unique(return_inverse=True)
+
+ new_coords = torch.stack(
+ [code // OFFSET[0]] +
+ [(code // OFFSET[i+1]) % MAX[i] for i in range(DIM)],
+ dim=-1
+ )
+ else:
+ new_coords, idx, subidx = cache
+
+ new_feats = torch.zeros(new_coords.shape[0] * self.factor ** DIM, x.feats.shape[1], device=x.feats.device, dtype=x.feats.dtype)
+ new_feats[idx * self.factor ** DIM + subidx] = x.feats
+
+ out = SparseTensor(new_feats.reshape(new_coords.shape[0], -1), new_coords, None if x._shape is None else torch.Size([x._shape[0], x._shape[1] * self.factor ** DIM]))
+ out._scale = tuple([s * self.factor for s in x._scale])
+ out._spatial_cache = dict(x._spatial_cache)
+
+ if cache is None:
+ x.register_spatial_cache(f'spatial2channel_{self.factor}', (new_coords, idx, subidx))
+ out.register_spatial_cache(f'channel2spatial_{self.factor}', (x.coords, idx, subidx))
+ out.register_spatial_cache('shape', torch.Size(MAX))
+
+ return out
+
+class SparseChannel2Spatial(nn.Module):
+ def __init__(self, factor: int = 2):
+ super(SparseChannel2Spatial, self).__init__()
+ self.factor = factor
+
+ def forward(self, x, subdivision = None):
+ DIM = x.coords.shape[-1] - 1
+
+ cache = x.get_spatial_cache(f'channel2spatial_{self.factor}')
+ if cache is None:
+ if subdivision is None:
+ raise ValueError('Cache not found. Provide subdivision tensor or pair SparseChannel2Spatial with SparseSpatial2Channel.')
+ else:
+ sub = subdivision.feats # [N, self.factor ** DIM]
+ N_leaf = sub.sum(dim=-1) # [N]
+ subidx = sub.nonzero()[:, -1]
+ new_coords = x.coords.clone().detach()
+ new_coords[:, 1:] *= self.factor
+ new_coords = torch.repeat_interleave(new_coords, N_leaf, dim=0, output_size=subidx.shape[0])
+ for i in range(DIM):
+ new_coords[:, i+1] += subidx // self.factor ** i % self.factor
+ idx = torch.repeat_interleave(torch.arange(x.coords.shape[0], device=x.device), N_leaf, dim=0, output_size=subidx.shape[0])
+ else:
+ new_coords, idx, subidx = cache
+
+ x_feats = x.feats.reshape(x.feats.shape[0] * self.factor ** DIM, -1)
+ new_feats = x_feats[idx * self.factor ** DIM + subidx]
+ out = SparseTensor(new_feats, new_coords, None if x._shape is None else torch.Size([x._shape[0], x._shape[1] // self.factor ** DIM]))
+ out._scale = tuple([s / self.factor for s in x._scale])
+ if cache is not None: # only keep cache when subdiv following it
+ out._spatial_cache = dict(x._spatial_cache)
+ return out
+
+class SparseResBlockC2S3d(nn.Module):
+ def __init__(self, channels: int, out_channels: Optional[int] = None, pred_subdiv: bool = True):
+ super().__init__()
+ self.channels = channels
+ self.out_channels = out_channels or channels
+ self.pred_subdiv = pred_subdiv
+
+ self.norm1 = ops.LayerNorm(channels, elementwise_affine=True, eps=1e-6)
+ self.norm2 = ops.LayerNorm(self.out_channels, elementwise_affine=False, eps=1e-6)
+ self.conv1 = SparseConv3d(channels, self.out_channels * 8, 3)
+ self.conv2 = SparseConv3d(self.out_channels, self.out_channels, 3)
+ if pred_subdiv:
+ self.to_subdiv = SparseLinear(channels, 8)
+ self.updown = SparseChannel2Spatial(2)
+
+ def forward(self, x, subdiv = None):
+ if self.pred_subdiv:
+ subdiv = self.to_subdiv(x)
+ h = x.replace(self.norm1(x.feats))
+ h = h.replace(F.silu(h.feats, inplace=True))
+ h = self.conv1(h)
+ subdiv_binarized = subdiv.replace(subdiv.feats > 0) if subdiv is not None else None
+ h = self.updown(h, subdiv_binarized)
+ x = self.updown(x, subdiv_binarized)
+ h = h.replace(self.norm2(h.feats))
+ h = h.replace(F.silu(h.feats, inplace=True))
+ h = self.conv2(h)
+ skip_repeat = self.out_channels // (self.channels // 8)
+ h.feats.view(h.feats.shape[0], x.feats.shape[1], skip_repeat).add_(x.feats.to(h.feats.dtype).unsqueeze(-1))
+ if self.pred_subdiv:
+ return h, subdiv
+ else:
+ return h
+
+
+class VarLenTensor:
+
+ def __init__(self, feats: torch.Tensor, layout: List[slice]=None):
+ self.feats = feats
+ self.layout = layout if layout is not None else [slice(0, feats.shape[0])]
+ self._cache = {}
+
+ @staticmethod
+ def from_tensor_list(tensor_list: List[torch.Tensor]) -> 'VarLenTensor':
+ """
+ Create a VarLenTensor from a list of tensors.
+ """
+ feats = torch.cat(tensor_list, dim=0)
+ layout = []
+ start = 0
+ for tensor in tensor_list:
+ layout.append(slice(start, start + tensor.shape[0]))
+ start += tensor.shape[0]
+ return VarLenTensor(feats, layout)
+
+ def __len__(self) -> int:
+ return len(self.layout)
+
+ @property
+ def shape(self) -> torch.Size:
+ return torch.Size([len(self.layout), *self.feats.shape[1:]])
+
+ def dim(self) -> int:
+ return len(self.shape)
+
+ @property
+ def ndim(self) -> int:
+ return self.dim()
+
+ @property
+ def dtype(self):
+ return self.feats.dtype
+
+ @property
+ def device(self):
+ return self.feats.device
+
+ @property
+ def seqlen(self) -> torch.LongTensor:
+ if 'seqlen' not in self._cache:
+ self._cache['seqlen'] = torch.tensor([l.stop - l.start for l in self.layout], dtype=torch.long, device=self.device)
+ return self._cache['seqlen']
+
+ @property
+ def batch_boardcast_map(self) -> torch.LongTensor:
+ """
+ Get the broadcast map for the varlen tensor.
+ """
+ if 'batch_boardcast_map' not in self._cache:
+ self._cache['batch_boardcast_map'] = torch.repeat_interleave(
+ torch.arange(len(self.layout), device=self.device),
+ self.seqlen,
+ )
+ return self._cache['batch_boardcast_map']
+
+ @overload
+ def to(self, dtype: torch.dtype, *, non_blocking: bool = False, copy: bool = False) -> 'VarLenTensor': ...
+
+ @overload
+ def to(self, device: Optional[Union[str, torch.device]] = None, dtype: Optional[torch.dtype] = None, *, non_blocking: bool = False, copy: bool = False) -> 'VarLenTensor': ...
+
+ def to(self, *args, **kwargs) -> 'VarLenTensor':
+ device = None
+ dtype = None
+ if len(args) == 2:
+ device, dtype = args
+ elif len(args) == 1:
+ if isinstance(args[0], torch.dtype):
+ dtype = args[0]
+ else:
+ device = args[0]
+ if 'dtype' in kwargs:
+ assert dtype is None, "to() received multiple values for argument 'dtype'"
+ dtype = kwargs['dtype']
+ if 'device' in kwargs:
+ assert device is None, "to() received multiple values for argument 'device'"
+ device = kwargs['device']
+ non_blocking = kwargs.get('non_blocking', False)
+ copy = kwargs.get('copy', False)
+
+ new_feats = self.feats.to(device=device, dtype=dtype, non_blocking=non_blocking, copy=copy)
+ return self.replace(new_feats)
+
+ def type(self, dtype):
+ new_feats = self.feats.type(dtype)
+ return self.replace(new_feats)
+
+ def cpu(self) -> 'VarLenTensor':
+ new_feats = self.feats.cpu()
+ return self.replace(new_feats)
+
+ def cuda(self) -> 'VarLenTensor':
+ new_feats = self.feats.cuda()
+ return self.replace(new_feats)
+
+ def half(self) -> 'VarLenTensor':
+ new_feats = self.feats.half()
+ return self.replace(new_feats)
+
+ def float(self) -> 'VarLenTensor':
+ new_feats = self.feats.float()
+ return self.replace(new_feats)
+
+ def detach(self) -> 'VarLenTensor':
+ new_feats = self.feats.detach()
+ return self.replace(new_feats)
+
+ def reshape(self, *shape) -> 'VarLenTensor':
+ new_feats = self.feats.reshape(self.feats.shape[0], *shape)
+ return self.replace(new_feats)
+
+ def unbind(self, dim: int) -> List['VarLenTensor']:
+ return varlen_unbind(self, dim)
+
+ def replace(self, feats: torch.Tensor) -> 'VarLenTensor':
+ new_tensor = VarLenTensor(
+ feats=feats,
+ layout=self.layout,
+ )
+ # Shallow-copy so derived tensors don't share-by-reference the cache
+ # dict — see SparseTensor.replace for rationale.
+ new_tensor._cache = dict(self._cache)
+ return new_tensor
+
+ def __neg__(self) -> 'VarLenTensor':
+ return self.replace(-self.feats)
+
+ def __elemwise__(self, other: Union[torch.Tensor, 'VarLenTensor'], op: callable) -> 'VarLenTensor':
+ if isinstance(other, torch.Tensor):
+ can_broadcast_batch = other.ndim <= self.ndim and all(
+ source == 1 or source == target
+ for source, target in zip(reversed(other.shape), reversed(self.shape))
+ )
+ if can_broadcast_batch:
+ other = torch.broadcast_to(other, self.shape)
+ other = other[self.batch_boardcast_map]
+ if isinstance(other, VarLenTensor):
+ other = other.feats
+ new_feats = op(self.feats, other)
+ new_tensor = self.replace(new_feats)
+ return new_tensor
+
+ def __add__(self, other: Union[torch.Tensor, 'VarLenTensor', float]) -> 'VarLenTensor':
+ return self.__elemwise__(other, torch.add)
+
+ def __radd__(self, other: Union[torch.Tensor, 'VarLenTensor', float]) -> 'VarLenTensor':
+ return self.__elemwise__(other, torch.add)
+
+ def __sub__(self, other: Union[torch.Tensor, 'VarLenTensor', float]) -> 'VarLenTensor':
+ return self.__elemwise__(other, torch.sub)
+
+ def __rsub__(self, other: Union[torch.Tensor, 'VarLenTensor', float]) -> 'VarLenTensor':
+ return self.__elemwise__(other, lambda x, y: torch.sub(y, x))
+
+ def __mul__(self, other: Union[torch.Tensor, 'VarLenTensor', float]) -> 'VarLenTensor':
+ return self.__elemwise__(other, torch.mul)
+
+ def __rmul__(self, other: Union[torch.Tensor, 'VarLenTensor', float]) -> 'VarLenTensor':
+ return self.__elemwise__(other, torch.mul)
+
+ def __truediv__(self, other: Union[torch.Tensor, 'VarLenTensor', float]) -> 'VarLenTensor':
+ return self.__elemwise__(other, torch.div)
+
+ def __rtruediv__(self, other: Union[torch.Tensor, 'VarLenTensor', float]) -> 'VarLenTensor':
+ return self.__elemwise__(other, lambda x, y: torch.div(y, x))
+
+ def __getitem__(self, idx):
+ if isinstance(idx, int):
+ idx = [idx]
+ elif isinstance(idx, slice):
+ idx = range(*idx.indices(self.shape[0]))
+ elif isinstance(idx, list):
+ assert all(isinstance(i, int) for i in idx), f"Only integer indices are supported: {idx}"
+ elif isinstance(idx, torch.Tensor):
+ if idx.dtype == torch.bool:
+ assert idx.shape == (self.shape[0],), f"Invalid index shape: {idx.shape}"
+ idx = idx.nonzero().squeeze(1)
+ elif idx.dtype in [torch.int32, torch.int64]:
+ assert len(idx.shape) == 1, f"Invalid index shape: {idx.shape}"
+ else:
+ raise ValueError(f"Unknown index type: {idx.dtype}")
+ else:
+ raise ValueError(f"Unknown index type: {type(idx)}")
+
+ new_feats = []
+ new_layout = []
+ start = 0
+ for new_idx, old_idx in enumerate(idx):
+ new_feats.append(self.feats[self.layout[old_idx]])
+ new_layout.append(slice(start, start + len(new_feats[-1])))
+ start += len(new_feats[-1])
+ new_feats = torch.cat(new_feats, dim=0).contiguous()
+ new_tensor = VarLenTensor(feats=new_feats, layout=new_layout)
+ return new_tensor
+
+ def __repr__(self) -> str:
+ return f"VarLenTensor(shape={self.shape}, dtype={self.dtype}, device={self.device})"
+
+def varlen_unbind(input: VarLenTensor, dim: int) -> Union[List[VarLenTensor]]:
+
+ if dim == 0:
+ return [input[i] for i in range(len(input))]
+ else:
+ feats = input.feats.unbind(dim)
+ return [input.replace(f) for f in feats]
+
+
+class SparseTensor(VarLenTensor):
+
+ @overload
+ def __init__(self, feats: torch.Tensor, coords: torch.Tensor, shape: Optional[torch.Size] = None, **kwargs): ...
+
+ @overload
+ def __init__(self, data, shape: Optional[torch.Size] = None, **kwargs): ...
+
+ def __init__(self, *args, **kwargs):
+ method_id = 0
+ if len(args) != 0:
+ method_id = 0 if isinstance(args[0], torch.Tensor) else 1
+ else:
+ method_id = 1 if 'data' in kwargs else 0
+
+ if method_id == 0:
+ feats, coords, shape = args + (None,) * (3 - len(args))
+ if 'feats' in kwargs:
+ feats = kwargs['feats']
+ del kwargs['feats']
+ if 'coords' in kwargs:
+ coords = kwargs['coords']
+ del kwargs['coords']
+ if 'shape' in kwargs:
+ shape = kwargs['shape']
+ del kwargs['shape']
+
+ self.data = {
+ 'feats': feats,
+ 'coords': coords,
+ }
+ elif method_id == 1:
+ data, shape = args + (None,) * (2 - len(args))
+ if 'data' in kwargs:
+ data = kwargs['data']
+ del kwargs['data']
+ if 'shape' in kwargs:
+ shape = kwargs['shape']
+ del kwargs['shape']
+
+ self.data = data
+
+ self._shape = shape
+ self._scale = kwargs.get('scale', (Fraction(1, 1), Fraction(1, 1), Fraction(1, 1)))
+ self._spatial_cache = kwargs.get('spatial_cache', {})
+
+ @staticmethod
+ def from_tensor_list(feats_list: List[torch.Tensor], coords_list: List[torch.Tensor]) -> 'SparseTensor':
+ """
+ Create a SparseTensor from a list of tensors.
+ """
+ feats = torch.cat(feats_list, dim=0)
+ coords = []
+ for i, coord in enumerate(coords_list):
+ coord = torch.cat([torch.full_like(coord[:, :1], i), coord[:, 1:]], dim=1)
+ coords.append(coord)
+ coords = torch.cat(coords, dim=0)
+ return SparseTensor(feats, coords)
+
+ def __len__(self) -> int:
+ return len(self.layout)
+
+ def __cal_shape(self, feats, coords):
+ shape = []
+ shape.append(coords[:, 0].max().item() + 1)
+ shape.extend([*feats.shape[1:]])
+ return torch.Size(shape)
+
+ def __cal_layout(self, coords, batch_size):
+ seq_len = torch.bincount(coords[:, 0], minlength=batch_size)
+ offset = torch.cumsum(seq_len, dim=0)
+ layout = [slice((offset[i] - seq_len[i]).item(), offset[i].item()) for i in range(batch_size)]
+ return layout
+
+ def __cal_spatial_shape(self, coords):
+ return torch.Size((coords[:, 1:].max(0)[0] + 1).tolist())
+
+ @property
+ def shape(self) -> torch.Size:
+ if self._shape is None:
+ self._shape = self.__cal_shape(self.feats, self.coords)
+ return self._shape
+
+ @property
+ def layout(self) -> List[slice]:
+ layout = self.get_spatial_cache('layout')
+ if layout is None:
+ layout = self.__cal_layout(self.coords, self.shape[0])
+ self.register_spatial_cache('layout', layout)
+ return layout
+
+ @property
+ def spatial_shape(self) -> torch.Size:
+ spatial_shape = self.get_spatial_cache('shape')
+ if spatial_shape is None:
+ spatial_shape = self.__cal_spatial_shape(self.coords)
+ self.register_spatial_cache('shape', spatial_shape)
+ return spatial_shape
+
+ @property
+ def feats(self) -> torch.Tensor:
+ return self.data['feats']
+
+ @feats.setter
+ def feats(self, value: torch.Tensor):
+ self.data['feats'] = value
+
+ @property
+ def coords(self) -> torch.Tensor:
+ return self.data['coords']
+
+ @coords.setter
+ def coords(self, value: torch.Tensor):
+ self.data['coords'] = value
+
+ @property
+ def dtype(self):
+ return self.feats.dtype
+
+ @property
+ def device(self):
+ return self.feats.device
+
+ @property
+ def seqlen(self) -> torch.LongTensor:
+ seqlen = self.get_spatial_cache('seqlen')
+ if seqlen is None:
+ seqlen = torch.tensor([l.stop - l.start for l in self.layout], dtype=torch.long, device=self.device)
+ self.register_spatial_cache('seqlen', seqlen)
+ return seqlen
+
+ @property
+ def batch_boardcast_map(self) -> torch.LongTensor:
+ """
+ Get the broadcast map for the varlen tensor.
+ """
+ batch_boardcast_map = self.get_spatial_cache('batch_boardcast_map')
+ if batch_boardcast_map is None:
+ batch_boardcast_map = torch.repeat_interleave(
+ torch.arange(len(self.layout), device=self.device),
+ self.seqlen,
+ )
+ self.register_spatial_cache('batch_boardcast_map', batch_boardcast_map)
+ return batch_boardcast_map
+
+ @overload
+ def to(self, dtype: torch.dtype, *, non_blocking: bool = False, copy: bool = False) -> 'SparseTensor': ...
+
+ @overload
+ def to(self, device: Optional[Union[str, torch.device]] = None, dtype: Optional[torch.dtype] = None, *, non_blocking: bool = False, copy: bool = False) -> 'SparseTensor': ...
+
+ def to(self, *args, **kwargs) -> 'SparseTensor':
+ device = None
+ dtype = None
+ if len(args) == 2:
+ device, dtype = args
+ elif len(args) == 1:
+ if isinstance(args[0], torch.dtype):
+ dtype = args[0]
+ else:
+ device = args[0]
+ if 'dtype' in kwargs:
+ assert dtype is None, "to() received multiple values for argument 'dtype'"
+ dtype = kwargs['dtype']
+ if 'device' in kwargs:
+ assert device is None, "to() received multiple values for argument 'device'"
+ device = kwargs['device']
+ non_blocking = kwargs.get('non_blocking', False)
+ copy = kwargs.get('copy', False)
+
+ new_feats = self.feats.to(device=device, dtype=dtype, non_blocking=non_blocking, copy=copy)
+ new_coords = self.coords.to(device=device, non_blocking=non_blocking, copy=copy)
+ return self.replace(new_feats, new_coords)
+
+ def type(self, dtype):
+ new_feats = self.feats.type(dtype)
+ return self.replace(new_feats)
+
+ def cpu(self) -> 'SparseTensor':
+ new_feats = self.feats.cpu()
+ new_coords = self.coords.cpu()
+ return self.replace(new_feats, new_coords)
+
+ def cuda(self) -> 'SparseTensor':
+ new_feats = self.feats.cuda()
+ new_coords = self.coords.cuda()
+ return self.replace(new_feats, new_coords)
+
+ def half(self) -> 'SparseTensor':
+ new_feats = self.feats.half()
+ return self.replace(new_feats)
+
+ def float(self) -> 'SparseTensor':
+ new_feats = self.feats.float()
+ return self.replace(new_feats)
+
+ def detach(self) -> 'SparseTensor':
+ new_coords = self.coords.detach()
+ new_feats = self.feats.detach()
+ return self.replace(new_feats, new_coords)
+
+ def reshape(self, *shape) -> 'SparseTensor':
+ new_feats = self.feats.reshape(self.feats.shape[0], *shape)
+ return self.replace(new_feats)
+
+ def unbind(self, dim: int) -> List['SparseTensor']:
+ return sparse_unbind(self, dim)
+
+ def replace(self, feats: torch.Tensor, coords: Optional[torch.Tensor] = None) -> 'SparseTensor':
+ new_data = {
+ 'feats': feats,
+ 'coords': self.data['coords'] if coords is None else coords,
+ }
+ return SparseTensor(
+ new_data,
+ shape=torch.Size([self._shape[0]] + list(feats.shape[1:])) if self._shape is not None else None,
+ scale=self._scale,
+ # Shallow-copy the cache: each derived tensor gets its own dict, so
+ # adding/overwriting entries on one doesn't leak to siblings.
+ # Cached tensors themselves are still shared by reference (safe
+ # because they're read-only after populate).
+ spatial_cache=dict(self._spatial_cache),
+ )
+
+ def __getitem__(self, idx):
+ if isinstance(idx, int):
+ idx = [idx]
+ elif isinstance(idx, slice):
+ idx = range(*idx.indices(self.shape[0]))
+ elif isinstance(idx, list):
+ assert all(isinstance(i, int) for i in idx), f"Only integer indices are supported: {idx}"
+ elif isinstance(idx, torch.Tensor):
+ if idx.dtype == torch.bool:
+ assert idx.shape == (self.shape[0],), f"Invalid index shape: {idx.shape}"
+ idx = idx.nonzero().squeeze(1)
+ elif idx.dtype in [torch.int32, torch.int64]:
+ assert len(idx.shape) == 1, f"Invalid index shape: {idx.shape}"
+ else:
+ raise ValueError(f"Unknown index type: {idx.dtype}")
+ else:
+ raise ValueError(f"Unknown index type: {type(idx)}")
+
+ new_coords = []
+ new_feats = []
+ new_layout = []
+ new_shape = torch.Size([len(idx)] + list(self.shape[1:]))
+ start = 0
+ for new_idx, old_idx in enumerate(idx):
+ new_coords.append(self.coords[self.layout[old_idx]].clone())
+ new_coords[-1][:, 0] = new_idx
+ new_feats.append(self.feats[self.layout[old_idx]])
+ new_layout.append(slice(start, start + len(new_coords[-1])))
+ start += len(new_coords[-1])
+ new_coords = torch.cat(new_coords, dim=0).contiguous()
+ new_feats = torch.cat(new_feats, dim=0).contiguous()
+ new_tensor = SparseTensor(feats=new_feats, coords=new_coords, shape=new_shape)
+ new_tensor.register_spatial_cache('layout', new_layout)
+ return new_tensor
+
+ def register_spatial_cache(self, key, value) -> None:
+ """
+ Register a spatial cache.
+ The spatial cache can be any thing you want to cache.
+ The registery and retrieval of the cache is based on current scale.
+ """
+ scale_key = str(self._scale)
+ if scale_key not in self._spatial_cache:
+ self._spatial_cache[scale_key] = {}
+ self._spatial_cache[scale_key][key] = value
+
+ def get_spatial_cache(self, key=None):
+ """
+ Get a spatial cache.
+ """
+ scale_key = str(self._scale)
+ cur_scale_cache = self._spatial_cache.get(scale_key, {})
+ if key is None:
+ return cur_scale_cache
+ return cur_scale_cache.get(key, None)
+
+ def __repr__(self) -> str:
+ return f"SparseTensor(shape={self.shape}, dtype={self.dtype}, device={self.device})"
+
+def sparse_cat(inputs: List[SparseTensor], dim: int = 0) -> SparseTensor:
+ if dim == 0:
+ start = 0
+ coords = []
+ for input in inputs:
+ coords.append(input.coords.clone())
+ coords[-1][:, 0] += start
+ start += input.shape[0]
+ coords = torch.cat(coords, dim=0)
+ feats = torch.cat([input.feats for input in inputs], dim=0)
+ output = SparseTensor(
+ coords=coords,
+ feats=feats,
+ )
+ else:
+ feats = torch.cat([input.feats for input in inputs], dim=dim)
+ output = inputs[0].replace(feats)
+
+ return output
+
+
+def sparse_unbind(input: SparseTensor, dim: int) -> List[SparseTensor]:
+ if dim == 0:
+ return [input[i] for i in range(input.shape[0])]
+ else:
+ feats = input.feats.unbind(dim)
+ return [input.replace(f) for f in feats]
+
+# allow operations.Linear inheritance
+class SparseLinear:
+ def __new__(cls, in_features, out_features, bias=True, device=None, dtype=None, operations=ops, *args, **kwargs):
+ class _SparseLinear(operations.Linear):
+ def __init__(self, in_features, out_features, bias=True, device=None, dtype=None):
+ super().__init__(in_features, out_features, bias=bias, device=device, dtype=dtype)
+
+ def forward(self, input: VarLenTensor) -> VarLenTensor:
+ return input.replace(super().forward(input.feats))
+
+ return _SparseLinear(in_features, out_features, bias=bias, device=device, dtype=dtype, *args, **kwargs)
+
+class SparseUnetVaeDecoder(nn.Module):
+ def __init__(
+ self,
+ out_channels: int,
+ model_channels: List[int],
+ latent_channels: int,
+ num_blocks: List[int],
+ block_type: List[str],
+ up_block_type: List[str],
+ block_args: List[Dict[str, Any]],
+ pred_subdiv: bool = True,
+ ):
+ super().__init__()
+ self.out_channels = out_channels
+ self.model_channels = model_channels
+ self.num_blocks = num_blocks
+ self.pred_subdiv = pred_subdiv
+
+ self.output_layer = SparseLinear(model_channels[-1], out_channels)
+ self.from_latent = SparseLinear(latent_channels, model_channels[0])
+
+ self.blocks = nn.ModuleList([])
+ for i in range(len(num_blocks)):
+ self.blocks.append(nn.ModuleList([]))
+ for j in range(num_blocks[i]):
+ self.blocks[-1].append(
+ globals()[block_type[i]](
+ model_channels[i],
+ **block_args[i],
+ )
+ )
+ if i < len(num_blocks) - 1:
+ self.blocks[-1].append(
+ globals()[up_block_type[i]](
+ model_channels[i],
+ model_channels[i+1],
+ pred_subdiv=pred_subdiv,
+ **block_args[i],
+ )
+ )
+
+ def forward(self, x: SparseTensor, guide_subs: Optional[List[SparseTensor]] = None, return_subs: bool = False) -> SparseTensor:
+ h = self.from_latent(x)
+ subs = []
+ for i, res in enumerate(self.blocks):
+ for j, block in enumerate(res):
+ if i < len(self.blocks) - 1 and j == len(res) - 1:
+ if self.pred_subdiv:
+ h, sub = block(h)
+ subs.append(sub)
+ else:
+ h = block(h, subdiv=guide_subs[i] if guide_subs is not None else None)
+ else:
+ h = block(h)
+ h = h.replace(F.layer_norm(h.feats, h.feats.shape[-1:]))
+ h = self.output_layer(h)
+ if return_subs:
+ return h, subs
+ else:
+ return h
+
+ def upsample(self, x: SparseTensor, upsample_times: int) -> torch.Tensor:
+ h = self.from_latent(x)
+ for i, res in enumerate(self.blocks):
+ if i == upsample_times:
+ return h.coords
+ for j, block in enumerate(res):
+ if i < len(self.blocks) - 1 and j == len(res) - 1:
+ h, sub = block(h)
+ else:
+ h = block(h)
+
+class FlexiDualGridVaeDecoder(SparseUnetVaeDecoder):
+ def __init__(
+ self,
+ resolution: int,
+ model_channels: List[int],
+ latent_channels: int,
+ num_blocks: List[int],
+ block_type: List[str],
+ up_block_type: List[str],
+ block_args: List[Dict[str, Any]],
+ voxel_margin: float = 0.5,
+ ):
+ self.resolution = resolution
+ self.voxel_margin = voxel_margin
+ super().__init__(
+ 7,
+ model_channels,
+ latent_channels,
+ num_blocks,
+ block_type,
+ up_block_type,
+ block_args,
+ )
+
+ def set_resolution(self, resolution: int) -> None:
+ self.resolution = resolution
+
+ def forward(self, x: SparseTensor, gt_intersected: SparseTensor = None, **kwargs):
+ decoded = super().forward(x, **kwargs)
+ out_list = list(decoded) if isinstance(decoded, tuple) else [decoded]
+ h = out_list[0]
+ vertices = h.replace((1 + 2 * self.voxel_margin) * F.sigmoid(h.feats[..., 0:3]) - self.voxel_margin)
+ intersected = h.replace(h.feats[..., 3:6] > 0)
+ quad_lerp = h.replace(F.softplus(h.feats[..., 6:7]))
+ mesh = [flexible_dual_grid_to_mesh(
+ v.coords[:, 1:], v.feats, i.feats, q.feats,
+ aabb=[[-0.5, -0.5, -0.5], [0.5, 0.5, 0.5]],
+ grid_size=self.resolution,
+ ) for v, i, q in zip(vertices, intersected, quad_lerp)]
+ out_list[0] = mesh
+ return out_list[0] if len(out_list) == 1 else tuple(out_list)
+
+def flexible_dual_grid_to_mesh(
+ coords: torch.Tensor,
+ dual_vertices: torch.Tensor,
+ intersected_flag: torch.Tensor,
+ split_weight: Union[torch.Tensor, None],
+ aabb: Union[list, tuple, torch.Tensor],
+ voxel_size: Union[float, list, tuple, torch.Tensor] = None,
+ grid_size: Union[int, list, tuple, torch.Tensor] = None,
+):
+
+ device = coords.device
+ # Small constant index tables — built per call (stateless), not cached on the function.
+ edge_neighbor_voxel_offset = torch.tensor([
+ [[0, 0, 0], [0, 0, 1], [0, 1, 1], [0, 1, 0]], # x-axis
+ [[0, 0, 0], [1, 0, 0], [1, 0, 1], [0, 0, 1]], # y-axis
+ [[0, 0, 0], [0, 1, 0], [1, 1, 0], [1, 0, 0]], # z-axis
+ ], dtype=torch.int, device=device).unsqueeze(0)
+ quad_split_1 = torch.tensor([0, 1, 2, 0, 2, 3], dtype=torch.long, device=device)
+ quad_split_2 = torch.tensor([0, 1, 3, 3, 1, 2], dtype=torch.long, device=device)
+
+ aabb = torch.tensor(aabb, dtype=torch.float32, device=device)
+
+ if voxel_size is not None:
+ if isinstance(voxel_size, float):
+ voxel_size = [voxel_size] * 3
+ voxel_size = torch.tensor(voxel_size, dtype=torch.float32, device=device)
+ grid_size = ((aabb[1] - aabb[0]) / voxel_size).round().int()
+ else:
+ if isinstance(grid_size, int):
+ grid_size = [grid_size] * 3
+ grid_size = torch.tensor(grid_size, dtype=torch.int32, device=device)
+ voxel_size = (aabb[1] - aabb[0]) / grid_size
+
+ # Extract mesh
+ N = dual_vertices.shape[0]
+ _, H, D = int(grid_size[0].item()), int(grid_size[1].item()), int(grid_size[2].item())
+ flat_keys = coords[:, 0].long() * (H * D)
+ flat_keys.add_(coords[:, 1].long() * D)
+ flat_keys.add_(coords[:, 2].long())
+ values = torch.arange(N, dtype=torch.int32, device=device)
+ torch_hashmap = TorchHashMap(flat_keys, values)
+
+ # Find connected voxels — direct gather instead of materializing the full [N, 3, 4, 3]
+ n_idx, axis_idx = intersected_flag.nonzero(as_tuple=True) # (M,), (M,)
+ offsets_per_axis = edge_neighbor_voxel_offset[0] # (3, 4, 3)
+ connected_voxel = coords[n_idx].unsqueeze(1) + offsets_per_axis[axis_idx] # (M, 4, 3)
+ M = connected_voxel.shape[0]
+ # flatten connected voxel coords and lookup. In-place to avoid extra memory allocation.
+ H, D = int(grid_size[1].item()), int(grid_size[2].item())
+ cv = connected_voxel.reshape(-1, 3)
+ conn_flat = cv[:, 0].long() * (H * D)
+ conn_flat.add_(cv[:, 1].long() * D)
+ conn_flat.add_(cv[:, 2].long())
+
+ conn_indices = torch_hashmap.lookup_flat(conn_flat).reshape(M, 4).int()
+ connected_voxel_valid = (conn_indices >= 0).all(dim=1) # -1 = missing neighbor
+ quad_indices = conn_indices[connected_voxel_valid].int() # (L, 4)
+
+ # Chain in-place — each op in the original allocated a fresh N*3 fp32 tensor.
+ mesh_vertices = coords.float()
+ mesh_vertices.add_(dual_vertices).mul_(voxel_size).add_(aabb[0].reshape(1, 3))
+ if split_weight is None:
+ # if split 1
+ atempt_triangles_0 = quad_indices[:, quad_split_1]
+ normals0 = torch.cross(mesh_vertices[atempt_triangles_0[:, 1]] - mesh_vertices[atempt_triangles_0[:, 0]], mesh_vertices[atempt_triangles_0[:, 2]] - mesh_vertices[atempt_triangles_0[:, 0]])
+ normals1 = torch.cross(mesh_vertices[atempt_triangles_0[:, 2]] - mesh_vertices[atempt_triangles_0[:, 1]], mesh_vertices[atempt_triangles_0[:, 3]] - mesh_vertices[atempt_triangles_0[:, 1]])
+ align0 = (normals0 * normals1).sum(dim=1, keepdim=True).abs()
+ # if split 2
+ atempt_triangles_1 = quad_indices[:, quad_split_2]
+ normals0 = torch.cross(mesh_vertices[atempt_triangles_1[:, 1]] - mesh_vertices[atempt_triangles_1[:, 0]], mesh_vertices[atempt_triangles_1[:, 2]] - mesh_vertices[atempt_triangles_1[:, 0]])
+ normals1 = torch.cross(mesh_vertices[atempt_triangles_1[:, 2]] - mesh_vertices[atempt_triangles_1[:, 1]], mesh_vertices[atempt_triangles_1[:, 3]] - mesh_vertices[atempt_triangles_1[:, 1]])
+ align1 = (normals0 * normals1).sum(dim=1, keepdim=True).abs()
+ # select split
+ mesh_triangles = torch.where(align0 > align1, atempt_triangles_0, atempt_triangles_1).reshape(-1, 3)
+ else:
+ split_weight_ws = split_weight[quad_indices]
+ split_weight_ws_02 = split_weight_ws[:, 0] * split_weight_ws[:, 2]
+ split_weight_ws_13 = split_weight_ws[:, 1] * split_weight_ws[:, 3]
+ mesh_triangles = torch.where(
+ split_weight_ws_02 > split_weight_ws_13,
+ quad_indices[:, quad_split_1],
+ quad_indices[:, quad_split_2]
+ ).reshape(-1, 3)
+
+ return mesh_vertices, mesh_triangles
+
+class ChannelLayerNorm32(ops.LayerNorm):
+ def forward(self, x: torch.Tensor) -> torch.Tensor:
+ DIM = x.dim()
+ x = x.permute(0, *range(2, DIM), 1).contiguous()
+ x = super().forward(x)
+ x = x.permute(0, DIM-1, *range(1, DIM-1)).contiguous()
+ return x
+
+class UpsampleBlock3d(nn.Module):
+ def __init__(self, in_channels: int, out_channels: int):
+ super().__init__()
+ self.in_channels = in_channels
+ self.out_channels = out_channels
+ self.conv = ops.Conv3d(in_channels, out_channels * 8, 3, padding=1)
+
+ def forward(self, x: torch.Tensor) -> torch.Tensor:
+ return pixel_shuffle_3d(self.conv(x), 2)
+
+class ResBlock3d(nn.Module):
+ def __init__(
+ self,
+ channels: int,
+ out_channels: Optional[int] = None,
+ ):
+ super().__init__()
+ self.channels = channels
+ self.out_channels = out_channels or channels
+
+ self.norm1 = ChannelLayerNorm32(channels)
+ self.norm2 = ChannelLayerNorm32(self.out_channels)
+ self.conv1 = ops.Conv3d(channels, self.out_channels, 3, padding=1)
+ self.conv2 = ops.Conv3d(self.out_channels, self.out_channels, 3, padding=1)
+ self.skip_connection = ops.Conv3d(channels, self.out_channels, 1) if channels != self.out_channels else nn.Identity()
+
+ def forward(self, x: torch.Tensor) -> torch.Tensor:
+ h = self.norm1(x)
+ h = F.silu(h)
+ h = self.conv1(h)
+ h = self.norm2(h)
+ h = F.silu(h)
+ h = self.conv2(h)
+ h = h + self.skip_connection(x)
+ return h
+
+
+class SparseStructureDecoder(nn.Module):
+ def __init__(
+ self,
+ out_channels: int,
+ latent_channels: int,
+ num_res_blocks: int,
+ channels: List[int],
+ num_res_blocks_middle: int = 2,
+ ):
+ super().__init__()
+ self.out_channels = out_channels
+ self.latent_channels = latent_channels
+ self.num_res_blocks = num_res_blocks
+ self.channels = channels
+ self.num_res_blocks_middle = num_res_blocks_middle
+
+ self.input_layer = ops.Conv3d(latent_channels, channels[0], 3, padding=1)
+
+ self.middle_block = nn.Sequential(*[
+ ResBlock3d(channels[0], channels[0])
+ for _ in range(num_res_blocks_middle)
+ ])
+
+ self.blocks = nn.ModuleList([])
+ for i, ch in enumerate(channels):
+ self.blocks.extend([
+ ResBlock3d(ch, ch)
+ for _ in range(num_res_blocks)
+ ])
+ if i < len(channels) - 1:
+ self.blocks.append(
+ UpsampleBlock3d(ch, channels[i+1])
+ )
+
+ self.out_layer = nn.Sequential(
+ ChannelLayerNorm32(channels[-1]),
+ nn.SiLU(),
+ ops.Conv3d(channels[-1], out_channels, 3, padding=1)
+ )
+
+ def forward(self, x: torch.Tensor) -> torch.Tensor:
+ h = self.input_layer(x)
+ h = self.middle_block(h)
+ for block in self.blocks:
+ h = block(h)
+ h = self.out_layer(h)
+ return h
+
+
+class ShapeVae(nn.Module):
+ """Decoder bundle from the Trellis2 shape checkpoint: structure decoder
+ (32^3 SS latent → 64^3 dense occupancy) and shape decoder (sparse latent →
+ mesh + per-stage subdivisions)."""
+
+ def __init__(self):
+ super().__init__()
+ self.shape_dec = FlexiDualGridVaeDecoder(
+ resolution=256,
+ model_channels=[1024, 512, 256, 128, 64],
+ latent_channels=32,
+ num_blocks=[4, 16, 8, 4, 0],
+ block_type=["SparseConvNeXtBlock3d"] * 5,
+ up_block_type=["SparseResBlockC2S3d"] * 4,
+ block_args=[{}, {}, {}, {}, {}],
+ )
+ self.struct_dec = SparseStructureDecoder(
+ out_channels=1,
+ latent_channels=8,
+ num_res_blocks=2,
+ num_res_blocks_middle=2,
+ channels=[512, 128, 32],
+ )
+ self.register_buffer("resolution", torch.tensor(1024.0), persistent=False)
+
+ def decode_structure(self, x: torch.Tensor) -> torch.Tensor:
+ return self.struct_dec(x)
+
+ def decode_shape_slat(self, slat: 'SparseTensor', resolution: int):
+ self.shape_dec.set_resolution(resolution)
+ return self.shape_dec(slat, return_subs=True)
+
+ def upsample_shape(self, slat: 'SparseTensor', upsample_times: int) -> torch.Tensor:
+ return self.shape_dec.upsample(slat, upsample_times)
+
+
+class TextureVae(nn.Module):
+ """Decoder bundle from the Trellis2 texture checkpoint: sparse 3D
+ per-voxel color decoder, guided by subdivisions from a prior shape decode."""
+
+ def __init__(self):
+ super().__init__()
+ self.txt_dec = SparseUnetVaeDecoder(
+ out_channels=6,
+ model_channels=[1024, 512, 256, 128, 64],
+ latent_channels=32,
+ num_blocks=[4, 16, 8, 4, 0],
+ block_type=["SparseConvNeXtBlock3d"] * 5,
+ up_block_type=["SparseResBlockC2S3d"] * 4,
+ block_args=[{}, {}, {}, {}, {}],
+ pred_subdiv=False,
+ )
+ self.register_buffer("resolution", torch.tensor(1024.0), persistent=False)
+
+ def decode_tex_slat(self, slat: 'SparseTensor', subs):
+ return self.txt_dec(slat, guide_subs=subs) * 0.5 + 0.5
diff --git a/comfy/model_base.py b/comfy/model_base.py
index 79f711e92..ba59d2705 100644
--- a/comfy/model_base.py
+++ b/comfy/model_base.py
@@ -68,6 +68,7 @@ import comfy.ldm.ideogram4.model
import comfy.ldm.krea2.model
import comfy.ldm.kandinsky5.model
import comfy.ldm.anima.model
+import comfy.ldm.trellis2.model
import comfy.ldm.ace.ace_step15
import comfy.ldm.cogvideo.model
import comfy.ldm.rt_detr.rtdetr_v4
@@ -1920,6 +1921,23 @@ class WAN22(WAN21):
def scale_latent_inpaint(self, sigma, noise, latent_image, **kwargs):
return latent_image
+class Trellis2(BaseModel):
+ def __init__(self, model_config, model_type=ModelType.FLOW, device=None, unet_model=comfy.ldm.trellis2.model.Trellis2):
+ super().__init__(model_config, model_type, device, unet_model)
+
+ def extra_conds(self, **kwargs):
+ out = super().extra_conds(**kwargs)
+ embeds = kwargs.get("embeds")
+ out["embeds"] = comfy.conds.CONDRegular(embeds)
+ # CONDConstant: shared across pos/neg
+ for k in ("trellis2_coords", "trellis2_coord_counts",
+ "trellis2_generation_mode", "trellis2_shape_slat",
+ "trellis2_proj_feats", "trellis2_model_frame"):
+ v = kwargs.get(k)
+ if v is not None:
+ out[k] = comfy.conds.CONDConstant(v)
+ return out
+
class WAN21_FlowRVS(WAN21):
def __init__(self, model_config, model_type=ModelType.IMG_TO_IMG_FLOW, image_to_video=False, device=None):
model_config.unet_config["model_type"] = "t2v"
diff --git a/comfy/model_detection.py b/comfy/model_detection.py
index e4bf30b78..3bfc20a36 100644
--- a/comfy/model_detection.py
+++ b/comfy/model_detection.py
@@ -120,6 +120,27 @@ def detect_unet_config(state_dict, key_prefix, metadata=None):
unet_config['block_repeat'] = [[1, 1, 1, 1], [2, 2, 2, 2]]
return unet_config
+ shape_key = '{}img2shape.t_embedder.mlp.0.weight'.format(key_prefix)
+ tex_key = '{}shape2txt.t_embedder.mlp.0.weight'.format(key_prefix)
+ if shape_key in state_dict_keys or tex_key in state_dict_keys: # trellis2 / pixal3d
+ has_shape = shape_key in state_dict_keys
+ has_tex = tex_key in state_dict_keys
+ unet_config = {
+ "image_model": "trellis2",
+ "resolution": 32 if (metadata or {}).get("is_512") else 64,
+ "init_txt_model": has_tex,
+ "txt_only": has_tex and not has_shape,
+ }
+ # Per-submodel projection head (Pixal3D adds `proj_linear`; Trellis2 doesn't).
+ for sub, name, proj_in_channels in (("img2shape", "shape", 2048),
+ ("shape2txt", "texture", 2048),
+ ("structure_model", "structure", 1024)):
+ key = '{}{}.blocks.0.cross_attn.proj_linear.weight'.format(key_prefix, sub)
+ if key in state_dict_keys:
+ unet_config["image_attn_mode_{}".format(name)] = "proj"
+ unet_config["proj_in_channels_{}".format(name)] = proj_in_channels
+ return unet_config
+
if '{}transformer.rotary_pos_emb.inv_freq'.format(key_prefix) in state_dict_keys: #stable audio dit
unet_config = {}
unet_config["audio_model"] = "dit1.0"
diff --git a/comfy/sd.py b/comfy/sd.py
index 06679c6fb..a73607cb0 100644
--- a/comfy/sd.py
+++ b/comfy/sd.py
@@ -15,6 +15,7 @@ import comfy.ldm.lightricks.vae.na_diffusion_decoder
import comfy.ldm.lightricks.vae.audio_vae
import comfy.ldm.cosmos.vae
import comfy.ldm.wan.vae
+import comfy.ldm.trellis2.vae
import comfy.ldm.wan.vae2_2
import comfy.ldm.hunyuan3d.vae
import comfy.ldm.seedvr.vae
@@ -575,6 +576,16 @@ class VAE:
self.first_stage_model = StageC_coder()
self.downscale_ratio = 32
self.latent_channels = 16
+ elif "shape_dec.blocks.1.16.to_subdiv.weight" in sd: # trellis2 shape vae (struct_dec + shape_dec)
+ self.working_dtypes = [torch.float16, torch.bfloat16, torch.float32]
+ self.memory_used_decode = lambda shape, dtype: (2500 * math.prod(shape[2:])) * model_management.dtype_size(dtype)
+ self.memory_used_encode = lambda shape, dtype: (2500 * math.prod(shape[2:])) * model_management.dtype_size(dtype)
+ self.first_stage_model = comfy.ldm.trellis2.vae.ShapeVae()
+ elif "txt_dec.blocks.3.4.conv2.weight" in sd: # trellis2 texture vae
+ self.working_dtypes = [torch.float16, torch.bfloat16, torch.float32]
+ self.memory_used_decode = lambda shape, dtype: (2500 * math.prod(shape[2:])) * model_management.dtype_size(dtype)
+ self.memory_used_encode = lambda shape, dtype: (2500 * math.prod(shape[2:])) * model_management.dtype_size(dtype)
+ self.first_stage_model = comfy.ldm.trellis2.vae.TextureVae()
elif "decoder.up_blocks.2.upsamplers.0.upscale_conv.weight" in sd: # seedvr2
self.first_stage_model = comfy.ldm.seedvr.vae.VideoAutoencoderKLWrapper()
self.latent_channels = comfy.ldm.seedvr.vae.SEEDVR2_LATENT_CHANNELS
@@ -1284,6 +1295,15 @@ class VAE:
pixel_samples = pixel_samples.to(self.output_device).movedim(1,-1)
return pixel_samples
+ def prepare_decode(self, sample_shape, memory_required=None):
+ """For VAEs whose real decode entry point bypasses decode()"""
+ if memory_required is None:
+ memory_required = self.memory_used_decode(sample_shape, self.vae_dtype)
+ memory_required = max(1, int(memory_required))
+ model_management.load_models_gpu([self.patcher], memory_required=memory_required, force_full_load=self.disable_offload)
+ free_memory = self.patcher.get_free_memory(self.device)
+ return max(1, int(free_memory / memory_required))
+
def _tile_bounded_shape(self, shape, tile_x, tile_y, tile_t):
"""Clamp a latent shape to one tile for memory estimates: peak memory of a tiled decode is per-tile. Only caller-provided tile dims are clamped."""
s = list(shape)
diff --git a/comfy/supported_models.py b/comfy/supported_models.py
index 33c378435..1dc06c9cc 100644
--- a/comfy/supported_models.py
+++ b/comfy/supported_models.py
@@ -1478,6 +1478,31 @@ class WAN22_T2V(WAN21_T2V):
out = model_base.WAN22(self, image_to_video=True, device=device)
return out
+class Trellis2(supported_models_base.BASE):
+ unet_config = {
+ "image_model": "trellis2"
+ }
+
+ unet_extra_config = {"num_heads": 12}
+
+ sampling_settings = {
+ "shift": 3.0,
+ }
+
+ memory_usage_factor = 3.5
+
+ latent_format = latent_formats.Trellis2
+ vae_key_prefix = ["vae."]
+ clip_vision_prefix = "conditioner.main_image_encoder.model."
+ # this is only needed for the texture model
+ supported_inference_dtypes = [torch.bfloat16, torch.float32]
+
+ def get_model(self, state_dict, prefix="", device=None):
+ return model_base.Trellis2(self, device=device)
+
+ def clip_target(self, state_dict={}):
+ return None
+
class WAN21_FlowRVS(WAN21_T2V):
unet_config = {
"image_model": "wan2.1",
@@ -2538,5 +2563,6 @@ models = [
CogVideoX_I2V,
CogVideoX_T2V,
SVD_img2vid,
+ Trellis2,
DepthAnything3,
]
diff --git a/comfy_api/latest/_util/geometry_types.py b/comfy_api/latest/_util/geometry_types.py
index 84a18d69a..64f49a97b 100644
--- a/comfy_api/latest/_util/geometry_types.py
+++ b/comfy_api/latest/_util/geometry_types.py
@@ -7,9 +7,10 @@ import torch
class VOXEL:
- def __init__(self, data: torch.Tensor):
+ def __init__(self, data: torch.Tensor, voxel_colors=None, resolution=None):
self.data = data
-
+ self.voxel_colors = voxel_colors
+ self.resolution = resolution # each 3d model has its own resolution
class SPLAT:
"""A batch of 3D Gaussian splats in render-ready (activated, world-space) form.
@@ -34,9 +35,16 @@ class MESH:
uvs: torch.Tensor | None = None,
vertex_colors: torch.Tensor | None = None,
texture: torch.Tensor | None = None,
+ metallic_roughness: torch.Tensor | None = None,
vertex_counts: torch.Tensor | None = None,
face_counts: torch.Tensor | None = None,
- unlit: bool = False):
+ unlit: bool = False,
+ normals: torch.Tensor | None = None,
+ tangents: torch.Tensor | None = None,
+ normal_map: torch.Tensor | None = None,
+ occlusion_in_mr: bool = False,
+ material: dict | None = None,
+ emissive: torch.Tensor | None = None):
assert (vertex_counts is None) == (face_counts is None), \
"vertex_counts and face_counts must be provided together (both or neither)"
@@ -44,13 +52,25 @@ class MESH:
self.faces = faces # faces: (B, M, 3)
self.uvs = uvs # uvs: (B, N, 2)
self.vertex_colors = vertex_colors # vertex_colors: (B, N, 3 or 4)
- self.texture = texture # texture: (B, H, W, 3)
+ # Optional per-vertex normals: (B, N, 3). When None, SaveGLB computes smooth
+ # area-weighted normals so viewers don't fall back to flat (per-face) shading.
+ self.normals = normals
+ self.texture = texture # texture (baseColor): (B, H, W, 3)
+ # glTF metallicRoughness texture: (B, H, W, 3), R unused, G=roughness, B=metallic
+ self.metallic_roughness = metallic_roughness
# When vertices/faces are zero-padded to a common N/M across the batch (variable-size mesh batch),
# these hold the real per-item lengths (B,). None means rows are uniform and no slicing is needed.
self.vertex_counts = vertex_counts
self.face_counts = face_counts
# Render flat / emissive (no scene lighting) when saved, e.g. for gaussian-splat-derived meshes.
self.unlit = unlit
+ # Extra maps / material overrides attached by bake, normal/AO, and SetMeshMaterial nodes;
+ # consumed by SaveGLB. Declared here (with defaults) so consumers read them directly.
+ self.tangents = tangents # (B, N, 4) per-vertex tangents for normal mapping
+ self.normal_map = normal_map # tangent-space normal map: (B, H, W, 3)
+ self.occlusion_in_mr = occlusion_in_mr # True = R channel of metallic_roughness holds AO (ORM)
+ self.material = material # SetMeshMaterial scalar/factor overrides
+ self.emissive = emissive # emissive map: (B, H, W, 3)
class File3D:
diff --git a/comfy_extras/mesh3d/postprocess/qem_decimate.py b/comfy_extras/mesh3d/postprocess/qem_decimate.py
new file mode 100644
index 000000000..157364aaa
--- /dev/null
+++ b/comfy_extras/mesh3d/postprocess/qem_decimate.py
@@ -0,0 +1,1705 @@
+"""
+Pure-PyTorch GPU-parallel QEM mesh simplification.
+
+ - Parallel greedy edge-matching collapse loop
+ - Plane/line/feature-edge/boundary quadrics, memoryless accumulation
+ - Normal-flip prevention, link-condition, skinny penalties
+ - Non-manifold/sliver handling without dropping faces
+ - Pre/post-clean pipeline (weld, degenerates, small components)
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+import math
+
+import numpy as _np
+import torch
+from scipy.sparse import coo_matrix
+from scipy.sparse.csgraph import connected_components
+from tqdm import tqdm as _tqdm
+import comfy.utils as _comfy_utils
+
+
+@dataclass
+class QEMConfig:
+ # Precision
+ dtype: torch.dtype = torch.float32 # float64 much slower on consumer GPUs
+
+ # Numerical conditioning
+ stabilizer_scale: float = 1e-3 # Tikhonov reg: stabilizer = mesh_scale^2 * this
+ wander_threshold: float = 2.0 # fall back to midpoint if v* lands > N×edge_length from an endpoint
+ clamp_v_to_edge: bool = True # project v* onto the edge segment (qem mode only)
+
+ # Placement mode (also selects collapse driver):
+ # "midpoint" = threshold-schedule driver, most stable (defaults below match it);
+ # "qem" = sharpest, QEM-optimum placement + ratio driver.
+ placement_mode: str = "midpoint"
+
+ flip_reject_hard: bool = True # hard-reject (err=+inf) top-K collapses that flip any 1-ring normal
+
+ # Per-iteration batch sizing
+ sampling_cap: int = 10_000_000 # max edges processed per outer iter
+ max_collapses_fraction: float = 0.25 # of remaining faces-to-remove
+ max_collapses_floor: int = 10_000
+ max_collapses_ceiling: int = 1_000_000
+ max_collapses_relative_cap: float = 0.10 # cap per-iter collapses as fraction of current faces; 0 disables
+
+ # Loop control
+ max_iterations: int = 5_000
+ compaction_period: int = 5
+ compaction_threshold: float = 0.85 # compact when alive_frac < this
+
+ # Quality knobs
+ boundary_quadrics: bool = True
+ boundary_weight: float = 1000.0
+ recompute_normals_post: bool = True
+ line_quadric_weight: float = 0.0 # penalise deviation ⟂ to edge dir → more uniform verts; 0 disables
+ line_quadric_skip_opposite_normals_cos: float = 0.0 # skip line quadrics on edges with endpoint cos < this
+
+ # Feature-edge quadrics on sharp interior edges (dihedral > min); 0 disables.
+ feature_edge_quadric_weight: float = 0.0
+ feature_edge_min_dihedral_deg: float = 30.0
+
+ # Flip check (FA-QEM §3.3)
+ quality_topk_multiplier: int = 4 # quality-check band size = this * max_collapses_per_iter
+ flip_cos_threshold: float = 0.0 # 0 = count any sign reversal (dihedral > 90°)
+ flip_check_max_degree: int = 16 # cap on vertex degree for the flip-check table
+
+ # Triangle shape penalty
+ skinny_weight: float = 1e-3 # penalise top-K collapses producing needle/sliver tris; 0 disables
+
+ # Topology preservation
+ enforce_link_condition: bool = True # reject collapses that violate the link condition
+
+ # Quadric area weighting
+ area_weighted_quadrics: bool = False # True: Garland-Heckbert area-weighted; False: un-weighted
+
+ # edge-length cost regularizer
+ lambda_edge_length: float = 1e-2 # add λ*len² to bias toward short edges; 0 disables
+ lambda_edge_length_absolute: bool = True # apply λ absolutely vs relative-to-QEM-median
+
+ # Threshold-schedule driver (placement_mode == "midpoint"):
+ # each round collapses a disjoint set with cost <= thresh, ×10 when < 1% removed.
+ threshold_start: float = 1e-8
+ memoryless_qem: bool = True # rebuild quadrics each round vs accumulate
+ repair_nonmanifold: bool = True # final repair_non_manifold_edges pass
+
+ # Pre-clean (input mesh)
+ preclean: bool = True # weld coincident verts, drop degenerate/duplicate/unused
+
+ # Post-clean (output mesh)
+ postclean: bool = True # remove slivers, tiny components, unused verts left by collapse
+ postclean_min_angle_deg: float = 0.5
+ postclean_max_aspect_ratio: float = 100.0
+ postclean_min_component_faces: int = 8 # drop components with fewer faces than this
+
+ # Preclean tuning
+ preclean_weld_epsilon_rel: float = 1e-5 # weld tolerance as fraction of bbox diagonal
+ preclean_min_component_faces: int = 0 # 0 = keep all components
+
+
+ @property
+ def threshold_driver(self) -> bool:
+ """The cost-threshold collapse driver is used by the midpoint placement mode."""
+ return self.placement_mode == "midpoint"
+
+
+def _sorted_edge_halfedges(
+ faces: torch.Tensor, num_verts: int,
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+ """3F half-edges sorted by key min(a,b)*(V+1)+max(a,b); returns (sorted_keys, face_ids, slot_ids)."""
+ device = faces.device
+ F = faces.shape[0]
+ e_all = torch.cat([faces[:, [0, 1]], faces[:, [1, 2]], faces[:, [2, 0]]], dim=0)
+ e_sorted, _ = torch.sort(e_all, dim=1)
+ P = num_verts + 1
+ key = e_sorted[:, 0].long() * P + e_sorted[:, 1].long()
+ face_per_he = torch.arange(F, device=device, dtype=torch.long).repeat(3)
+ slot_per_he = torch.arange(3, device=device, dtype=torch.long).repeat_interleave(F)
+ sort_idx = torch.argsort(key)
+ return key[sort_idx], face_per_he[sort_idx], slot_per_he[sort_idx]
+
+
+def _vert_is_boundary_mask(faces: torch.Tensor, num_verts: int) -> torch.Tensor:
+ """(V,) bool mask: True for verts incident to any boundary edge."""
+ device = faces.device
+ out = torch.zeros(num_verts, dtype=torch.bool, device=device)
+ bedges = _detect_boundary_edges(faces, num_verts)
+ if bedges.numel() == 0:
+ return out
+ out[bedges[:, 0]] = True
+ out[bedges[:, 1]] = True
+ return out
+
+
+def _detect_boundary_edges(faces: torch.Tensor, num_verts: int) -> torch.Tensor:
+ """Boundary edges as [N, 2] of vertex indices (each appearing in exactly one face)."""
+ if faces.numel() == 0:
+ return torch.empty((0, 2), dtype=torch.int64, device=faces.device)
+ sorted_keys, _, _ = _sorted_edge_halfedges(faces, num_verts)
+ unique_key, counts = torch.unique(sorted_keys, return_counts=True)
+ boundary_key = unique_key[counts == 1]
+ if boundary_key.numel() == 0:
+ return torch.empty((0, 2), dtype=torch.int64, device=faces.device)
+ P = num_verts + 1
+ bv0 = boundary_key // P
+ bv1 = boundary_key % P
+ return torch.stack([bv0, bv1], dim=1)
+
+
+def _manifold_edge_pairs(
+ sorted_keys: torch.Tensor, sorted_faces: torch.Tensor,
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+ """Edges shared by exactly 2 faces (filters >2-incident groups); returns (pair_keys, fa, fb)."""
+ if sorted_keys.shape[0] < 2:
+ empty = sorted_keys.new_empty(0)
+ return empty, empty, empty
+ pair_mask = sorted_keys[:-1] == sorted_keys[1:]
+ if not pair_mask.any():
+ empty = sorted_keys.new_empty(0)
+ return empty, empty, empty
+ pair_starts = torch.nonzero(pair_mask, as_tuple=True)[0]
+ # manifold iff neither neighbour half-edge shares the key
+ cur = sorted_keys[pair_starts]
+ prev_ok = (pair_starts == 0) | (sorted_keys[(pair_starts - 1).clamp_min(0)] != cur)
+ nxt_idx = (pair_starts + 2).clamp(max=sorted_keys.shape[0] - 1)
+ nxt_ok = (pair_starts + 2 >= sorted_keys.shape[0]) | (sorted_keys[nxt_idx] != cur)
+ pair_starts = pair_starts[prev_ok & nxt_ok]
+ return (sorted_keys[pair_starts],
+ sorted_faces[pair_starts],
+ sorted_faces[pair_starts + 1])
+
+
+def _line_quadric_planes(
+ pa: torch.Tensor, pb: torch.Tensor
+) -> Tuple[torch.Tensor, torch.Tensor]:
+ """Two plane equations (E,4) per edge whose squared-dist sum = squared ⟂ distance to the edge line."""
+ e = pb - pa # (E, 3)
+ elen = torch.norm(e, dim=-1, keepdim=True).clamp_min(1e-12)
+ e_unit = e / elen # (E, 3)
+ m = 0.5 * (pa + pb) # (E, 3)
+ # helper axis not parallel to e_unit, then Gram-Schmidt against e_unit
+ helper = torch.zeros_like(e_unit)
+ helper.scatter_(-1, e_unit.abs().argmin(dim=-1, keepdim=True), 1.0)
+ u = helper - (helper * e_unit).sum(-1, keepdim=True) * e_unit
+ u = u / torch.norm(u, dim=-1, keepdim=True).clamp_min(1e-12)
+ w = torch.cross(e_unit, u, dim=-1)
+ d_u = -(u * m).sum(-1, keepdim=True)
+ d_w = -(w * m).sum(-1, keepdim=True)
+ p_u = torch.cat([u, d_u], dim=-1) # (E, 4)
+ p_w = torch.cat([w, d_w], dim=-1)
+ return p_u, p_w, elen.squeeze(-1)
+
+
+def _add_line_quadrics(
+ verts: torch.Tensor,
+ faces: torch.Tensor,
+ face_areas: torch.Tensor,
+ Q_flat: torch.Tensor,
+ weight: float,
+ skip_he_mask: Optional[torch.Tensor] = None,
+) -> torch.Tensor:
+ """Add line quadrics for all 3F half-edges, weighted by face_area*weight; skip_he_mask zeroes True positions."""
+ a_all = torch.cat([faces[:, 0], faces[:, 1], faces[:, 2]], dim=0).long()
+ b_all = torch.cat([faces[:, 1], faces[:, 2], faces[:, 0]], dim=0).long()
+ pa = verts[a_all]
+ pb = verts[b_all]
+ p_u, p_w, _ = _line_quadric_planes(pa, pb)
+ area_per_edge = face_areas.repeat(3)
+ w_per_edge = area_per_edge * weight
+ if skip_he_mask is not None:
+ w_per_edge = torch.where(skip_he_mask, torch.zeros_like(w_per_edge), w_per_edge)
+ w_per_edge = w_per_edge.unsqueeze(-1).unsqueeze(-1)
+ K_line = (
+ p_u.unsqueeze(-1) * p_u.unsqueeze(-2)
+ + p_w.unsqueeze(-1) * p_w.unsqueeze(-2)
+ ) * w_per_edge
+ K_flat = K_line.reshape(-1, 16)
+ Q_flat.scatter_add_(0, a_all.unsqueeze(1).expand(-1, 16), K_flat) # scatter to both endpoints
+ Q_flat.scatter_add_(0, b_all.unsqueeze(1).expand(-1, 16), K_flat)
+ return Q_flat
+
+
+def _build_quadrics(
+ verts: torch.Tensor,
+ faces: torch.Tensor,
+ cfg: QEMConfig,
+) -> torch.Tensor:
+ """Per-vertex area-weighted quadric (V, 4, 4)."""
+ V = verts.shape[0]
+ dtype = verts.dtype
+ device = verts.device
+
+ Q_flat = torch.zeros((V, 16), dtype=dtype, device=device)
+
+ if faces.numel() > 0:
+ v0 = verts[faces[:, 0]]
+ v1 = verts[faces[:, 1]]
+ v2 = verts[faces[:, 2]]
+ e1 = v1 - v0
+ e2 = v2 - v0
+ n = torch.cross(e1, e2, dim=-1)
+ area = torch.norm(n, dim=-1)
+ mask = area > 1e-12
+ # where() avoids boolean-index gather+scatter (fewer index kernels)
+ n_norm = torch.where(mask.unsqueeze(-1),
+ n / area.unsqueeze(-1).clamp_min(1e-12),
+ n.new_zeros(()))
+ d = -(n_norm * v0).sum(dim=-1, keepdim=True)
+ p = torch.cat([n_norm, d], dim=-1) # (F, 4)
+ K = torch.einsum("fi,fj->fij", p, p) # (F, 4, 4)
+
+ if cfg.area_weighted_quadrics:
+ K.mul_(area[:, None, None])
+ K_flat = K.reshape(-1, 16)
+ for corner in range(3):
+ idx = faces[:, corner].unsqueeze(1).expand(-1, 16)
+ Q_flat.scatter_add_(0, idx, K_flat)
+
+ # Line quadrics: squared ⟂ distance from v to the edge-midpoint line, all 3F half-edges in one pass.
+ if cfg.line_quadric_weight > 0 and faces.numel() > 0:
+ # skip thin-shell rim edges (endpoint normals oppose)
+ skip_he_sharp = None
+ if cfg.line_quadric_skip_opposite_normals_cos < 1.0:
+ v_norm = torch.zeros((V, 3), dtype=dtype, device=device)
+ n_weighted = n_norm * area.unsqueeze(-1) # normal * 2× area
+ for corner in range(3):
+ v_norm.scatter_add_(0, faces[:, corner].unsqueeze(-1).expand(-1, 3),
+ n_weighted)
+ v_norm = torch.nn.functional.normalize(v_norm, p=2, dim=-1, eps=1e-12)
+ a_he = torch.cat([faces[:, 0], faces[:, 1], faces[:, 2]], dim=0).long()
+ b_he = torch.cat([faces[:, 1], faces[:, 2], faces[:, 0]], dim=0).long()
+ cos_endpoints = (v_norm[a_he] * v_norm[b_he]).sum(dim=-1)
+ skip_he_sharp = cos_endpoints < cfg.line_quadric_skip_opposite_normals_cos
+ if not skip_he_sharp.any():
+ skip_he_sharp = None
+ Q_flat = _add_line_quadrics(verts, faces, area, Q_flat,
+ cfg.line_quadric_weight,
+ skip_he_mask=skip_he_sharp)
+
+ # Boundary line quadrics: pin boundary-edge endpoints to the boundary line.
+ if cfg.boundary_quadrics and faces.numel() > 0:
+ b_edges = _detect_boundary_edges(faces, V)
+ if b_edges.shape[0] > 0:
+ ba = b_edges[:, 0]
+ bb = b_edges[:, 1]
+ pa = verts[ba]
+ pb = verts[bb]
+ p_u, p_w, _ = _line_quadric_planes(pa, pb)
+ K_b = (torch.einsum("ei,ej->eij", p_u, p_u)
+ + torch.einsum("ei,ej->eij", p_w, p_w)) * cfg.boundary_weight
+ K_b_flat = K_b.reshape(-1, 16)
+ Q_flat.scatter_add_(0, ba.unsqueeze(1).expand(-1, 16), K_b_flat)
+ Q_flat.scatter_add_(0, bb.unsqueeze(1).expand(-1, 16), K_b_flat)
+
+ # Feature-edge quadrics: line quadric on sharp interior edges weighted by (1 - cos(dihedral)).
+ if cfg.feature_edge_quadric_weight > 0 and faces.numel() > 0:
+ v0 = verts[faces[:, 0]]
+ v1 = verts[faces[:, 1]]
+ v2 = verts[faces[:, 2]]
+ fn = torch.cross(v1 - v0, v2 - v0, dim=-1)
+ fn = torch.nn.functional.normalize(fn, p=2, dim=-1, eps=1e-12)
+ sorted_keys_fe, sorted_faces_fe, _ = _sorted_edge_halfedges(faces, V)
+ pair_keys, f1_idx, f2_idx = _manifold_edge_pairs(sorted_keys_fe, sorted_faces_fe)
+ if pair_keys.numel() > 0:
+ P = V + 1
+ edge_a = pair_keys // P
+ edge_b = pair_keys % P
+ cos_dihedral = (fn[f1_idx] * fn[f2_idx]).sum(dim=-1)
+ cos_thresh = math.cos(math.radians(cfg.feature_edge_min_dihedral_deg))
+ sharp = cos_dihedral < cos_thresh
+ if sharp.any():
+ fa = edge_a[sharp]
+ fb = edge_b[sharp]
+ p_u, p_w, _ = _line_quadric_planes(verts[fa], verts[fb])
+ sharpness = (1.0 - cos_dihedral[sharp]).clamp_min(0.0)
+ avg_area = 0.5 * (area[f1_idx[sharp]] + area[f2_idx[sharp]])
+ w = (avg_area * sharpness * cfg.feature_edge_quadric_weight) \
+ .unsqueeze(-1).unsqueeze(-1)
+ K_feat = (
+ p_u.unsqueeze(-1) * p_u.unsqueeze(-2)
+ + p_w.unsqueeze(-1) * p_w.unsqueeze(-2)
+ ) * w
+ K_flat = K_feat.reshape(-1, 16)
+ Q_flat.scatter_add_(0, fa.unsqueeze(1).expand(-1, 16), K_flat)
+ Q_flat.scatter_add_(0, fb.unsqueeze(1).expand(-1, 16), K_flat)
+
+ return Q_flat.reshape(V, 4, 4)
+
+
+def _edge_errors(
+ verts: torch.Tensor,
+ Q: torch.Tensor,
+ edges: torch.Tensor,
+ stabilizer: float,
+ max_edge_length_sq: float,
+ mesh_scale_sq: float,
+ cfg: QEMConfig,
+ vert_is_boundary: Optional[torch.Tensor] = None,
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+ """Returns (optimal_pos, error, valid_mask); vert_is_boundary enables boundary-aware midpoint."""
+ n_edges = edges.shape[0]
+ dtype = verts.dtype
+ device = verts.device
+
+ if n_edges == 0:
+ return (
+ torch.empty((0, 3), dtype=dtype, device=device),
+ torch.empty((0,), dtype=dtype, device=device),
+ torch.zeros((0,), dtype=torch.bool, device=device),
+ )
+
+ verts_pair = verts[edges] # (E, 2, 3)
+ pa = verts_pair[:, 0]
+ pb = verts_pair[:, 1]
+ edge_vec = pb - pa
+ el = torch.norm(edge_vec, dim=-1)
+
+ # boundary-aware midpoint: snap to the boundary endpoint when exactly one is boundary
+ if vert_is_boundary is not None:
+ ba = vert_is_boundary[edges[:, 0]]
+ bb = vert_is_boundary[edges[:, 1]]
+ w_a = torch.where(ba & ~bb, torch.ones_like(el),
+ torch.where(~ba & bb, torch.zeros_like(el),
+ torch.full_like(el, 0.5)))
+ midpoint = pa * w_a.unsqueeze(-1) + pb * (1.0 - w_a).unsqueeze(-1)
+ else:
+ midpoint = torch.lerp(pa, pb, 0.5)
+
+ Qe = Q[edges].sum(dim=1) # (E, 4, 4) — sum of Q[va] and Q[vb]
+
+ if cfg.placement_mode == "midpoint":
+ opt = midpoint
+ else:
+ A = Qe[:, :3, :3] + torch.eye(3, device=device, dtype=dtype) * stabilizer
+ b = -Qe[:, :3, 3].unsqueeze(-1)
+
+ # stabilizer keeps A invertible; full-batch solve, midpoint fallback via where (no sync)
+ sol = torch.linalg.solve(A, b)
+ dets = torch.det(A)
+ good = (dets.abs() > 1e-12).unsqueeze(-1)
+ opt = torch.where(good, sol.squeeze(-1), midpoint)
+
+ if cfg.clamp_v_to_edge:
+ # project v* onto the edge segment (subsumes the wander check)
+ edge_len_sq = (edge_vec * edge_vec).sum(dim=-1) + 1e-20
+ t = ((opt - pa) * edge_vec).sum(dim=-1) / edge_len_sq
+ t = t.clamp(0.0, 1.0).unsqueeze(-1)
+ opt = torch.lerp(pa, pb, t)
+ else:
+ # fall back to midpoint when v* wanders from both endpoints
+ dist_a = torch.norm(opt - pa, dim=-1)
+ dist_b = torch.norm(opt - pb, dim=-1)
+ wander_bad = ((dist_a > cfg.wander_threshold * el) |
+ (dist_b > cfg.wander_threshold * el)).unsqueeze(-1)
+ opt = torch.where(wander_bad, midpoint, opt)
+
+ v4 = torch.cat([opt, torch.ones((n_edges, 1), device=device, dtype=dtype)], dim=1)
+ err = torch.abs(torch.einsum("ei,eij,ej->e", v4, Qe, v4))
+
+ # mesh_scale_sq: Python float or 0-d tensor
+ if torch.is_tensor(mesh_scale_sq):
+ length_ok = el * el > mesh_scale_sq * 1e-10
+ else:
+ length_ok = el > math.sqrt(mesh_scale_sq) * 1e-5
+ error_ok = err < max_edge_length_sq
+ nan_ok = ~torch.isnan(opt).any(dim=-1) & ~torch.isnan(err)
+ valid = length_ok & error_ok & nan_ok
+
+ # edge-length regularizer: bias collapse order toward short edges (uniform sizing)
+ if cfg.lambda_edge_length > 0.0 and valid.any():
+ el2 = el * el
+ if cfg.lambda_edge_length_absolute:
+ err = err + cfg.lambda_edge_length * el2
+ else:
+ qem_med = err[valid].median()
+ len_med = el2[valid].median().clamp_min(1e-30)
+ err = err + cfg.lambda_edge_length * el2 * (qem_med / len_med)
+ return opt, err, valid
+
+
+def _greedy_matching(
+ edges: torch.Tensor,
+ err: torch.Tensor,
+ v_alive: torch.Tensor,
+ max_select: int,
+) -> torch.Tensor:
+ """Vectorised independent edge-set selection: an edge wins iff it is the min-key edge at both endpoints."""
+ device = edges.device
+ n_edges = edges.shape[0]
+ if n_edges == 0:
+ return torch.empty(0, dtype=torch.int64, device=device)
+
+ va = edges[:, 0]
+ vb = edges[:, 1]
+ num_verts = v_alive.shape[0]
+
+ err32 = err.to(torch.float32).clamp(min=0).contiguous()
+ err_bits = err32.view(torch.int32).to(torch.int64) & 0xFFFFFFFF
+ edge_idx = torch.arange(n_edges, device=device, dtype=torch.int64)
+ key = (err_bits << 32) | edge_idx
+
+ INT64_MAX = torch.iinfo(torch.int64).max
+ best_key = torch.full((num_verts,), INT64_MAX, dtype=torch.int64, device=device)
+ best_key.scatter_reduce_(0, va, key, reduce="amin", include_self=True)
+ best_key.scatter_reduce_(0, vb, key, reduce="amin", include_self=True)
+
+ is_winner = (key == best_key[va]) & (key == best_key[vb]) & v_alive[va] & v_alive[vb]
+ sel = torch.nonzero(is_winner, as_tuple=True)[0]
+
+ if sel.numel() > max_select:
+ sel_err = err[sel]
+ top = torch.topk(sel_err, max_select, largest=False).indices
+ sel = sel[top]
+ return sel
+
+
+def _build_vert_to_faces_pad(
+ faces: torch.Tensor,
+ num_verts: int,
+ max_deg: int,
+) -> torch.Tensor:
+ """Pad-CSR vertex-to-incident-faces table (V, max_deg) of face indices, -1 padded, degree truncated."""
+ device = faces.device
+ F = faces.shape[0]
+ if F == 0:
+ return torch.full((num_verts, max_deg), -1, dtype=torch.int64, device=device)
+ v_rep = faces.flatten().long()
+ f_rep = torch.arange(F, device=device, dtype=torch.int64).repeat_interleave(3)
+ sort_idx = v_rep.argsort()
+ sorted_v = v_rep[sort_idx]
+ sorted_f = f_rep[sort_idx]
+ offsets = torch.searchsorted(
+ sorted_v, torch.arange(num_verts + 1, device=device, dtype=sorted_v.dtype)
+ )
+ slot = torch.arange(sorted_v.shape[0], device=device, dtype=torch.int64) - offsets[sorted_v]
+ keep = slot < max_deg
+ table = torch.full((num_verts, max_deg), -1, dtype=torch.int64, device=device)
+ table[sorted_v[keep], slot[keep]] = sorted_f[keep]
+ return table
+
+
+def _normal_flip_mask(
+ verts: torch.Tensor, # (V, 3)
+ faces: torch.Tensor, # (F, 3) — must be alive faces only
+ edges: torch.Tensor, # (E, 2) candidate collapse edges
+ opt: torch.Tensor, # (E, 3) proposed collapse positions
+ vert_to_faces: torch.Tensor, # (V, max_deg) face indices or -1
+ cos_threshold: float = 0.0,
+ chunk_size: int = 100_000,
+ return_count: bool = False,
+) -> torch.Tensor:
+ """(E,) bool mask (no adjacent-face flip), or int count of would-flip faces per edge if return_count."""
+ E = edges.shape[0]
+ device = verts.device
+ if return_count:
+ out = torch.zeros(E, dtype=torch.int32, device=device)
+ else:
+ out = torch.ones(E, dtype=torch.bool, device=device)
+ if E == 0:
+ return out
+
+ max_deg = vert_to_faces.shape[1]
+ a_all = edges[:, 0]
+ b_all = edges[:, 1]
+
+ for start in range(0, E, chunk_size):
+ stop = min(start + chunk_size, E)
+ Ec = stop - start
+ a = a_all[start:stop]
+ b = b_all[start:stop]
+ oc = opt[start:stop]
+
+ fa = vert_to_faces[a] # (Ec, max_deg)
+ fb = vert_to_faces[b]
+ all_f = torch.cat([fa, fb], dim=1) # (Ec, 2*max_deg)
+ valid_f = all_f >= 0
+ all_f_safe = all_f.clamp(min=0)
+ fv = faces[all_f_safe] # (Ec, 2*max_deg, 3)
+
+ a_b = a.view(Ec, 1)
+ b_b = b.view(Ec, 1)
+ s0_a = fv[..., 0] == a_b
+ s0_b = fv[..., 0] == b_b
+ s1_a = fv[..., 1] == a_b
+ s1_b = fv[..., 1] == b_b
+ s2_a = fv[..., 2] == a_b
+ s2_b = fv[..., 2] == b_b
+ contains_a = s0_a | s1_a | s2_a
+ contains_b = s0_b | s1_b | s2_b
+ # affected: face contains exactly one of {a, b} and slot is non-pad
+ affected = (contains_a ^ contains_b) & valid_f
+ if not affected.any():
+ continue
+
+ p0 = verts[fv[..., 0]] # (Ec, 2*max_deg, 3)
+ p1 = verts[fv[..., 1]]
+ p2 = verts[fv[..., 2]]
+ n_old = torch.cross(p1 - p0, p2 - p0, dim=-1)
+
+ opt_b = oc.view(Ec, 1, 3).expand(-1, 2 * max_deg, -1)
+ rep0 = (s0_a | s0_b).unsqueeze(-1)
+ rep1 = (s1_a | s1_b).unsqueeze(-1)
+ rep2 = (s2_a | s2_b).unsqueeze(-1)
+ p0n = torch.where(rep0, opt_b, p0)
+ p1n = torch.where(rep1, opt_b, p1)
+ p2n = torch.where(rep2, opt_b, p2)
+ n_new = torch.cross(p1n - p0n, p2n - p0n, dim=-1)
+
+ nlen_old = torch.norm(n_old, dim=-1)
+ nlen_new = torch.norm(n_new, dim=-1)
+ # degenerate-before faces can't flip; treat as OK
+ denom = nlen_old * nlen_new
+ safe = denom > 1e-20
+ cos = torch.where(safe, (n_old * n_new).sum(dim=-1) / denom.clamp_min(1e-20),
+ torch.ones_like(denom))
+ flip = (cos < cos_threshold) & affected & safe
+ if return_count:
+ out[start:stop] = flip.sum(dim=-1).to(torch.int32)
+ else:
+ out[start:stop] = ~flip.any(dim=-1)
+
+ return out
+
+
+def _link_condition_mask(
+ faces: torch.Tensor, # (F, 3) alive faces only
+ edges: torch.Tensor, # (E, 2) candidate collapse edges
+ vert_to_faces: torch.Tensor, # (V, max_deg) face idx or -1
+ chunk_size: int = 100_000,
+) -> torch.Tensor:
+ """(E,) bool mask — True where the collapse is topology-safe (link condition: common neighbours <= edge faces)."""
+ E = edges.shape[0]
+ device = faces.device
+ out = torch.ones(E, dtype=torch.bool, device=device)
+ if E == 0:
+ return out
+ D = vert_to_faces.shape[1]
+ a_all = edges[:, 0]
+ b_all = edges[:, 1]
+
+ for s in range(0, E, chunk_size):
+ e = min(s + chunk_size, E)
+ a = a_all[s:e]
+ b = b_all[s:e]
+ Ec = a.shape[0]
+
+ fa = vert_to_faces[a] # (Ec, D)
+ fb = vert_to_faces[b]
+ fa_ok = fa >= 0
+ fb_ok = fb >= 0
+ fav = faces[fa.clamp(min=0)] # (Ec, D, 3)
+ fbv = faces[fb.clamp(min=0)]
+
+ # neighbour verts of a/b: take the 2 non-anchor verts per incident face → (Ec, 2D)
+ a_b = a[:, None]
+ b_b = b[:, None]
+ an1 = torch.where(fav[..., 0] == a_b, fav[..., 1], fav[..., 0])
+ an2 = torch.where(fav[..., 2] == a_b, fav[..., 1], fav[..., 2])
+ bn1 = torch.where(fbv[..., 0] == b_b, fbv[..., 1], fbv[..., 0])
+ bn2 = torch.where(fbv[..., 2] == b_b, fbv[..., 1], fbv[..., 2])
+ na = torch.stack([an1, an2], dim=-1).reshape(Ec, 2 * D)
+ nb = torch.stack([bn1, bn2], dim=-1).reshape(Ec, 2 * D)
+ fa_okx = fa_ok.repeat_interleave(2, dim=1)
+ fb_okx = fb_ok.repeat_interleave(2, dim=1)
+ na[(na == a_b) | (na == b_b) | ~fa_okx] = -1
+ nb[(nb == a_b) | (nb == b_b) | ~fb_okx] = -1
+
+ # common neighbours: na entries also appearing in nb
+ in_b = (na[:, :, None] == nb[:, None, :]) & (na[:, :, None] >= 0)
+ na_common = torch.where(in_b.any(dim=2), na, torch.full_like(na, -1))
+ # distinct count of common neighbours per edge (sort + count transitions)
+ cs, _ = na_common.sort(dim=1)
+ count_common = ((cs[:, 1:] != cs[:, :-1]) & (cs[:, 1:] >= 0)).sum(dim=1) \
+ + (cs[:, :1] >= 0).sum(dim=1)
+
+ # faces on the edge = a's faces also containing b
+ count_faces = ((fav == b[:, None, None]).any(dim=2) & fa_ok).sum(dim=1)
+
+ out[s:e] = count_common <= count_faces
+
+ return out
+
+
+def _skinny_penalty(
+ verts: torch.Tensor, # (V, 3)
+ faces: torch.Tensor, # (F, 3) — alive faces only
+ edges: torch.Tensor, # (E, 2) candidate collapse edges
+ opt: torch.Tensor, # (E, 3) proposed collapse positions
+ vert_to_faces: torch.Tensor, # (V, max_deg)
+ chunk_size: int = 100_000,
+) -> torch.Tensor:
+ """Per-edge post-collapse triangle-shape penalty (lambda_skinny); mean of 1 - clamp(shape,0,1) over the 1-ring."""
+ E = edges.shape[0]
+ device = verts.device
+ out = torch.zeros(E, dtype=verts.dtype, device=device)
+ if E == 0:
+ return out
+
+ max_deg = vert_to_faces.shape[1]
+ a_all = edges[:, 0]
+ b_all = edges[:, 1]
+ sqrt3_4 = 4.0 * math.sqrt(3.0)
+
+ for start in range(0, E, chunk_size):
+ stop = min(start + chunk_size, E)
+ Ec = stop - start
+ a = a_all[start:stop]
+ b = b_all[start:stop]
+ oc = opt[start:stop]
+
+ fa = vert_to_faces[a]
+ fb = vert_to_faces[b]
+ all_f = torch.cat([fa, fb], dim=1)
+ valid_f = all_f >= 0
+ all_f_safe = all_f.clamp(min=0)
+ fv = faces[all_f_safe]
+
+ a_b = a.view(Ec, 1)
+ b_b = b.view(Ec, 1)
+ s0_a = fv[..., 0] == a_b
+ s0_b = fv[..., 0] == b_b
+ s1_a = fv[..., 1] == a_b
+ s1_b = fv[..., 1] == b_b
+ s2_a = fv[..., 2] == a_b
+ s2_b = fv[..., 2] == b_b
+ contains_a = s0_a | s1_a | s2_a
+ contains_b = s0_b | s1_b | s2_b
+ # affected: face contains exactly one of {a, b} and slot is non-pad
+ affected = (contains_a ^ contains_b) & valid_f
+ if not affected.any():
+ continue
+
+ p0 = verts[fv[..., 0]]
+ p1 = verts[fv[..., 1]]
+ p2 = verts[fv[..., 2]]
+ opt_b = oc.view(Ec, 1, 3).expand(-1, 2 * max_deg, -1)
+ rep0 = (s0_a | s0_b).unsqueeze(-1)
+ rep1 = (s1_a | s1_b).unsqueeze(-1)
+ rep2 = (s2_a | s2_b).unsqueeze(-1)
+ p0n = torch.where(rep0, opt_b, p0)
+ p1n = torch.where(rep1, opt_b, p1)
+ p2n = torch.where(rep2, opt_b, p2)
+
+ e01 = p1n - p0n
+ e02 = p2n - p0n
+ e12 = p2n - p1n
+ two_area = torch.cross(e01, e02, dim=-1).norm(dim=-1)
+ edge_sum_sq = ((e01 * e01).sum(-1)
+ + (e02 * e02).sum(-1)
+ + (e12 * e12).sum(-1))
+ shape = (sqrt3_4 * 0.5 * two_area) / edge_sum_sq.clamp_min(1e-20)
+ term = 1.0 - shape.clamp(0.0, 1.0)
+ term = torch.where(affected, term, torch.zeros_like(term))
+ n_affected = affected.sum(dim=-1).clamp_min(1).to(term.dtype)
+ out[start:stop] = term.sum(dim=-1) / n_affected
+
+ return out
+
+
+def _quality_checks_fused(
+ verts: torch.Tensor,
+ faces: torch.Tensor,
+ edges: torch.Tensor,
+ opt: torch.Tensor,
+ vert_to_faces: torch.Tensor,
+ cos_threshold: float = 0.0,
+ want_flip: bool = True,
+ want_skinny: bool = True,
+ want_link: bool = False,
+ chunk_size: int = 100_000,
+) -> Tuple[Optional[torch.Tensor], Optional[torch.Tensor], Optional[torch.Tensor]]:
+ """Fused 1-ring checks (flip count / skinny / link) sharing one faces gather.
+ Returns (flip_count|None, skinny|None, link_safe|None)."""
+ E = edges.shape[0]
+ device = verts.device
+ flip_out = torch.zeros(E, dtype=torch.int32, device=device) if want_flip else None
+ skinny_out = torch.zeros(E, dtype=verts.dtype, device=device) if want_skinny else None
+ link_out = torch.ones(E, dtype=torch.bool, device=device) if want_link else None
+ if E == 0:
+ return flip_out, skinny_out, link_out
+
+ D = vert_to_faces.shape[1]
+ a_all = edges[:, 0]
+ b_all = edges[:, 1]
+ sqrt3_4 = 4.0 * math.sqrt(3.0)
+ need_geom = want_flip or want_skinny
+
+ for start in range(0, E, chunk_size):
+ stop = min(start + chunk_size, E)
+ Ec = stop - start
+ a = a_all[start:stop]
+ b = b_all[start:stop]
+
+ # shared gather of a's and b's incident faces (the expensive part)
+ fa = vert_to_faces[a]
+ fb = vert_to_faces[b]
+ all_f = torch.cat([fa, fb], dim=1) # (Ec, 2D)
+ valid_f = all_f >= 0
+ fv = faces[all_f.clamp(min=0)] # (Ec, 2D, 3)
+ a_b = a.view(Ec, 1)
+ b_b = b.view(Ec, 1)
+
+ if need_geom:
+ oc = opt[start:stop]
+ s0_a = fv[..., 0] == a_b
+ s0_b = fv[..., 0] == b_b
+ s1_a = fv[..., 1] == a_b
+ s1_b = fv[..., 1] == b_b
+ s2_a = fv[..., 2] == a_b
+ s2_b = fv[..., 2] == b_b
+ contains_a = s0_a | s1_a | s2_a
+ contains_b = s0_b | s1_b | s2_b
+ affected = (contains_a ^ contains_b) & valid_f
+ if affected.any():
+ p0 = verts[fv[..., 0]]
+ p1 = verts[fv[..., 1]]
+ p2 = verts[fv[..., 2]]
+ opt_b = oc.view(Ec, 1, 3).expand(-1, 2 * D, -1)
+ rep0 = (s0_a | s0_b).unsqueeze(-1)
+ rep1 = (s1_a | s1_b).unsqueeze(-1)
+ rep2 = (s2_a | s2_b).unsqueeze(-1)
+ p0n = torch.where(rep0, opt_b, p0)
+ p1n = torch.where(rep1, opt_b, p1)
+ p2n = torch.where(rep2, opt_b, p2)
+
+ # post-collapse normal (skinny's two_area == flip's ‖n_new‖)
+ e01 = p1n - p0n
+ e02 = p2n - p0n
+ n_new = torch.cross(e01, e02, dim=-1)
+ nlen_new = torch.norm(n_new, dim=-1)
+
+ if want_flip:
+ n_old = torch.cross(p1 - p0, p2 - p0, dim=-1)
+ nlen_old = torch.norm(n_old, dim=-1)
+ denom = nlen_old * nlen_new
+ safe = denom > 1e-20
+ cos = torch.where(safe, (n_old * n_new).sum(dim=-1) / denom.clamp_min(1e-20),
+ torch.ones_like(denom))
+ flip = (cos < cos_threshold) & affected & safe
+ flip_out[start:stop] = flip.sum(dim=-1).to(torch.int32)
+
+ if want_skinny:
+ e12 = p2n - p1n
+ edge_sum_sq = ((e01 * e01).sum(-1) + (e02 * e02).sum(-1) + (e12 * e12).sum(-1))
+ shape = (sqrt3_4 * 0.5 * nlen_new) / edge_sum_sq.clamp_min(1e-20)
+ term = 1.0 - shape.clamp(0.0, 1.0)
+ term = torch.where(affected, term, torch.zeros_like(term))
+ n_affected = affected.sum(dim=-1).clamp_min(1).to(term.dtype)
+ skinny_out[start:stop] = term.sum(dim=-1) / n_affected
+
+ if want_link:
+ # reuses fv / valid_f; matches _link_condition_mask
+ fa_ok = valid_f[:, :D]
+ fb_ok = valid_f[:, D:]
+ fav = fv[:, :D]
+ fbv = fv[:, D:]
+ an1 = torch.where(fav[..., 0] == a_b, fav[..., 1], fav[..., 0])
+ an2 = torch.where(fav[..., 2] == a_b, fav[..., 1], fav[..., 2])
+ bn1 = torch.where(fbv[..., 0] == b_b, fbv[..., 1], fbv[..., 0])
+ bn2 = torch.where(fbv[..., 2] == b_b, fbv[..., 1], fbv[..., 2])
+ na = torch.stack([an1, an2], dim=-1).reshape(Ec, 2 * D)
+ nb = torch.stack([bn1, bn2], dim=-1).reshape(Ec, 2 * D)
+ fa_okx = fa_ok.repeat_interleave(2, dim=1)
+ fb_okx = fb_ok.repeat_interleave(2, dim=1)
+ na[(na == a_b) | (na == b_b) | ~fa_okx] = -1
+ nb[(nb == a_b) | (nb == b_b) | ~fb_okx] = -1
+ in_b = (na[:, :, None] == nb[:, None, :]) & (na[:, :, None] >= 0)
+ na_common = torch.where(in_b.any(dim=2), na, torch.full_like(na, -1))
+ cs, _ = na_common.sort(dim=1)
+ count_common = ((cs[:, 1:] != cs[:, :-1]) & (cs[:, 1:] >= 0)).sum(dim=1) \
+ + (cs[:, :1] >= 0).sum(dim=1)
+ count_faces = ((fav == b[:, None, None]).any(dim=2) & fa_ok).sum(dim=1)
+ link_out[start:stop] = count_common <= count_faces
+
+ return flip_out, skinny_out, link_out
+
+
+def _compute_vertex_normals(verts: torch.Tensor, faces: torch.Tensor, weld: bool = True) -> torch.Tensor:
+ """Area-weighted smooth vertex normals. `weld` averages face normals across vertices that
+ share a position (UV-seam duplicates from unwrapping) so both sides of a seam get one
+ identical normal — otherwise a visible shading seam appears in the exported GLB."""
+ if faces.numel() == 0:
+ return torch.zeros_like(verts)
+ faces_long = faces.to(torch.int64)
+ i0, i1, i2 = faces_long[:, 0], faces_long[:, 1], faces_long[:, 2]
+ v0, v1, v2 = verts[i0], verts[i1], verts[i2]
+ fn = torch.cross(v1 - v0, v2 - v0, dim=-1)
+ if weld and verts.shape[0]:
+ # Group coincident positions (quantized to ~1e-5 of the bbox) into one shared normal.
+ lo = verts.min(0).values
+ inv_tol = 1.0 / (float((verts.max(0).values - lo).max().clamp_min(1e-9)) * 1e-5)
+ q = ((verts - lo) * inv_tol).round().to(torch.int64)
+ _, group = torch.unique(q, dim=0, return_inverse=True)
+ acc = torch.zeros((int(group.max()) + 1, 3), dtype=verts.dtype, device=verts.device)
+ acc.scatter_add_(0, group[i0].unsqueeze(-1).expand_as(fn), fn)
+ acc.scatter_add_(0, group[i1].unsqueeze(-1).expand_as(fn), fn)
+ acc.scatter_add_(0, group[i2].unsqueeze(-1).expand_as(fn), fn)
+ vn = acc[group]
+ else:
+ vn = torch.zeros_like(verts)
+ vn.scatter_add_(0, i0.unsqueeze(-1).expand_as(fn), fn)
+ vn.scatter_add_(0, i1.unsqueeze(-1).expand_as(fn), fn)
+ vn.scatter_add_(0, i2.unsqueeze(-1).expand_as(fn), fn)
+ return torch.nn.functional.normalize(vn, p=2, dim=-1, eps=1e-6)
+
+
+# Public API
+
+@dataclass
+class CleanStats:
+ in_verts: int = 0
+ in_faces: int = 0
+ out_verts: int = 0
+ out_faces: int = 0
+ welded_verts: int = 0 # how many vertex IDs collapsed during welding
+ degenerate_faces: int = 0 # zero-area or repeated-index faces removed
+ duplicate_faces: int = 0 # same vertex-set removed
+ unused_verts: int = 0 # verts not in any face removed
+ components_dropped: int = 0 # disconnected components below threshold
+
+ def __str__(self):
+ return (f"clean: in={self.in_verts}v/{self.in_faces}f -> "
+ f"out={self.out_verts}v/{self.out_faces}f "
+ f"(welded {self.welded_verts}v, degen {self.degenerate_faces}f, "
+ f"dup {self.duplicate_faces}f, unused {self.unused_verts}v, "
+ f"comps {self.components_dropped})")
+
+
+def _weld_vertices(
+ verts: torch.Tensor, faces: torch.Tensor, epsilon,
+ colors: Optional[torch.Tensor] = None,
+ normals: Optional[torch.Tensor] = None,
+) -> Tuple[torch.Tensor, torch.Tensor, Optional[torch.Tensor], Optional[torch.Tensor], int]:
+ """Merge vertices closer than epsilon (L_inf grid), cluster-averaging attributes; returns (v, f, colors, normals, n_welded)."""
+ if verts.shape[0] == 0:
+ return verts, faces, colors, normals, 0
+ device = verts.device
+ scale = 1.0 / epsilon
+ bbox_min = verts.min(dim=0)[0]
+ q = ((verts - bbox_min) * scale).round().to(torch.int64)
+ bbox = (verts.max(dim=0)[0] - bbox_min)
+ extent = (bbox * scale).round().to(torch.int64) + 2
+ key = (q[:, 0] * extent[1] + q[:, 1]) * extent[2] + q[:, 2] # pack 3D quantized pos to 1D key
+ unique_key, inv = torch.unique(key, return_inverse=True)
+ n_unique = unique_key.shape[0]
+ if n_unique == verts.shape[0]:
+ return verts, faces, colors, normals, 0
+ counts = torch.zeros(n_unique, dtype=verts.dtype, device=device)
+ counts.scatter_add_(0, inv, torch.ones(verts.shape[0], dtype=verts.dtype, device=device))
+ counts_div = counts.unsqueeze(-1).clamp_min(1.0)
+
+ new_verts = torch.zeros((n_unique, 3), dtype=verts.dtype, device=device)
+ new_verts.scatter_add_(0, inv.unsqueeze(-1).expand_as(verts), verts)
+ new_verts = new_verts / counts_div
+
+ new_colors = None
+ if colors is not None:
+ new_colors = torch.zeros((n_unique, colors.shape[1]), dtype=colors.dtype, device=device)
+ new_colors.scatter_add_(0, inv.unsqueeze(-1).expand_as(colors), colors)
+ new_colors = new_colors / counts_div.to(colors.dtype)
+
+ new_normals = None
+ if normals is not None:
+ new_normals = torch.zeros((n_unique, normals.shape[1]), dtype=normals.dtype, device=device)
+ new_normals.scatter_add_(0, inv.unsqueeze(-1).expand_as(normals), normals)
+ new_normals = torch.nn.functional.normalize(new_normals, p=2, dim=-1, eps=1e-6)
+
+ new_faces = inv[faces.long()] if faces.numel() > 0 else faces
+ return new_verts, new_faces, new_colors, new_normals, int(verts.shape[0] - n_unique)
+
+
+def _drop_degenerate_faces(
+ verts: torch.Tensor, faces: torch.Tensor,
+ min_area: float = 1e-14,
+) -> Tuple[torch.Tensor, int]:
+ """Drop degenerate-by-construction faces (repeated indices or zero-area); slivers go to _collapse_slivers."""
+ if faces.numel() == 0:
+ return faces, 0
+ idx_bad = (faces[:, 0] == faces[:, 1]) | (faces[:, 1] == faces[:, 2]) | (faces[:, 0] == faces[:, 2])
+ f_good = faces[~idx_bad]
+ v0 = verts[f_good[:, 0]]
+ v1 = verts[f_good[:, 1]]
+ v2 = verts[f_good[:, 2]]
+ e0 = v1 - v0
+ e2 = v0 - v2
+ area = 0.5 * torch.norm(torch.cross(e0, -e2, dim=-1), dim=-1)
+ bad = area < min_area
+ kept = f_good[~bad]
+ n_dropped = idx_bad.sum() + bad.sum() # tensor-scalar; caller .item()s once
+ return kept, n_dropped
+
+
+def _collapse_slivers(
+ verts: torch.Tensor, faces: torch.Tensor,
+ min_angle_deg: float = 0.0,
+ max_aspect_ratio: float = 0.0,
+) -> Tuple[torch.Tensor, int]:
+ """Resolve sliver triangles by collapsing each sliver's shortest edge (no holes); returns (faces, n_collapsed)."""
+ if faces.numel() == 0 or (min_angle_deg <= 0 and max_aspect_ratio <= 0):
+ return faces, 0
+
+ fl = faces.long()
+ v0 = verts[fl[:, 0]]
+ v1 = verts[fl[:, 1]]
+ v2 = verts[fl[:, 2]]
+ e0 = v1 - v0
+ e1 = v2 - v1
+ e2 = v0 - v2
+ l0 = torch.norm(e0, dim=-1)
+ l1 = torch.norm(e1, dim=-1)
+ l2 = torch.norm(e2, dim=-1)
+ area = 0.5 * torch.norm(torch.cross(e0, -e2, dim=-1), dim=-1)
+
+ bad = torch.zeros(faces.shape[0], dtype=torch.bool, device=verts.device)
+ if max_aspect_ratio > 0:
+ max_edge = torch.maximum(torch.maximum(l0, l1), l2)
+ aspect = max_edge * max_edge / (2.0 * area + 1e-12)
+ bad = bad | (aspect > max_aspect_ratio)
+ if min_angle_deg > 0:
+ cos_a = (l1 * l1 + l2 * l2 - l0 * l0) / (2 * l1 * l2 + 1e-12)
+ cos_b = (l0 * l0 + l2 * l2 - l1 * l1) / (2 * l0 * l2 + 1e-12)
+ cos_c = (l0 * l0 + l1 * l1 - l2 * l2) / (2 * l0 * l1 + 1e-12)
+ cos_all = torch.stack([cos_a, cos_b, cos_c], dim=-1)
+ angles_deg = torch.acos(torch.clamp(cos_all, -1, 1)) * (180.0 / math.pi)
+ bad = bad | (angles_deg.min(dim=-1).values < min_angle_deg)
+
+ if not bad.any():
+ return faces, 0
+
+ # per sliver pick its shortest edge to collapse
+ edge_lens = torch.stack([l0, l1, l2], dim=-1) # (F, 3)
+ shortest_slot = edge_lens.argmin(dim=-1) # (F,) ∈ {0,1,2}
+
+ V = verts.shape[0]
+ # collapse higher-index endpoint into lower (min/max ordering avoids cycles)
+ merge_map = torch.arange(V, device=verts.device, dtype=torch.int64)
+ bad_idx = torch.nonzero(bad, as_tuple=True)[0]
+ for slot in range(3):
+ sel = bad_idx[shortest_slot[bad_idx] == slot]
+ if sel.numel() == 0:
+ continue
+ a = fl[sel, slot]
+ b = fl[sel, (slot + 1) % 3]
+ lo = torch.minimum(a, b)
+ hi = torch.maximum(a, b)
+ merge_map[hi] = lo # last-write-wins on conflict
+
+ # path-compress until stable
+ for _ in range(10):
+ new_map = merge_map[merge_map]
+ if torch.equal(new_map, merge_map):
+ break
+ merge_map = new_map
+
+ new_faces = merge_map[fl]
+ nondeg = ((new_faces[:, 0] != new_faces[:, 1]) &
+ (new_faces[:, 1] != new_faces[:, 2]) &
+ (new_faces[:, 0] != new_faces[:, 2]))
+ new_faces = new_faces[nondeg].to(dtype=faces.dtype)
+ return new_faces, bad.sum()
+
+
+def _drop_duplicate_faces(faces: torch.Tensor, num_verts: int) -> Tuple[torch.Tensor, int]:
+ """Remove duplicate faces (same vertex set), keeping the first occurrence (winding-preserving)."""
+ if faces.shape[0] <= 1:
+ return faces, 0
+ key_sorted = torch.sort(faces, dim=1)[0]
+ P = num_verts + 1
+ packed = (key_sorted[:, 0].long() * P + key_sorted[:, 1].long()) * P + key_sorted[:, 2].long()
+ unique_packed, inv = torch.unique(packed, return_inverse=True)
+ if unique_packed.shape[0] == faces.shape[0]:
+ return faces, 0
+ # first-occurrence index per unique key
+ arange = torch.arange(packed.shape[0], device=packed.device)
+ first = torch.full((unique_packed.shape[0],), packed.shape[0],
+ dtype=torch.int64, device=packed.device)
+ first.scatter_reduce_(0, inv, arange, reduce="amin", include_self=True)
+ kept = faces[first]
+ return kept, int(faces.shape[0] - kept.shape[0])
+
+
+def _drop_unused_verts(
+ verts: torch.Tensor, faces: torch.Tensor,
+ colors: Optional[torch.Tensor] = None,
+ normals: Optional[torch.Tensor] = None,
+) -> Tuple[torch.Tensor, torch.Tensor, Optional[torch.Tensor], Optional[torch.Tensor], int]:
+ """Remove vertices not referenced by any face; remap faces and filter attributes."""
+ if verts.shape[0] == 0 or faces.numel() == 0:
+ return verts, faces, colors, normals, 0
+ used = torch.zeros(verts.shape[0], dtype=torch.bool, device=verts.device)
+ used[faces[:, 0]] = True
+ used[faces[:, 1]] = True
+ used[faces[:, 2]] = True
+ # cumsum compact remap: 0..N-1 to used verts in order
+ remap = used.long().cumsum(0) - 1
+ new_verts = verts[used]
+ new_faces = remap[faces.long()]
+ new_colors = colors[used] if colors is not None else None
+ new_normals = normals[used] if normals is not None else None
+ n_dropped = verts.shape[0] - used.sum()
+ return new_verts, new_faces, new_colors, new_normals, n_dropped
+
+
+def _repair_nonmanifold_edges(
+ verts: torch.Tensor, faces: torch.Tensor,
+) -> Tuple[torch.Tensor, torch.Tensor]:
+ """repair_non_manifold_edges: explode corners, re-merge only across manifold edges; returns (verts, faces, src)."""
+ if faces.numel() == 0:
+ return verts, faces
+ dev, vdt, fdt = verts.device, verts.dtype, faces.dtype
+ F = faces.detach().cpu().numpy().astype(_np.int64)
+ V = verts.detach().cpu().numpy()
+ nf = F.shape[0]
+ nv = V.shape[0]
+ corner_vert = F.reshape(-1) # (3F,) original vertex per corner
+
+ # per-face edges keyed by (vmin,vmax)
+ keys_l, ca_l, cb_l = [], [], []
+ for (i, j) in ((0, 1), (1, 2), (2, 0)):
+ va, vb = F[:, i], F[:, j]
+ ci = 3 * _np.arange(nf) + i
+ cj = 3 * _np.arange(nf) + j
+ amin = _np.where(va <= vb, ci, cj) # corner of the smaller-id endpoint
+ amax = _np.where(va <= vb, cj, ci)
+ vmin = _np.minimum(va, vb).astype(_np.int64)
+ vmax = _np.maximum(va, vb).astype(_np.int64)
+ keys_l.append(vmin * (nv + 1) + vmax)
+ ca_l.append(amin)
+ cb_l.append(amax)
+ keys = _np.concatenate(keys_l)
+ ca = _np.concatenate(ca_l)
+ cb = _np.concatenate(cb_l)
+ order = _np.argsort(keys, kind="stable")
+ keys = keys[order]
+ ca = ca[order]
+ cb = cb[order]
+ uniq, start, cnt = _np.unique(keys, return_index=True, return_counts=True)
+ man = start[cnt == 2] # manifold edges (exactly 2 incident faces)
+ # union both endpoints' corners across each manifold edge
+ rows = _np.concatenate([ca[man], cb[man]])
+ cols = _np.concatenate([ca[man + 1], cb[man + 1]])
+
+ n = 3 * nf
+ g = coo_matrix((_np.ones(rows.shape[0], dtype=_np.int8), (rows, cols)), shape=(n, n))
+ _ncomp, labels = connected_components(g, directed=False)
+
+ new_faces = labels[3 * _np.arange(nf)[:, None] + _np.array([0, 1, 2])[None, :]]
+ nnv = int(labels.max()) + 1
+ # source original-vertex index per new vertex
+ src = _np.zeros(nnv, dtype=_np.int64)
+ src[labels] = corner_vert
+ new_verts = V[src]
+ src_t = torch.from_numpy(src).to(device=dev)
+ return (torch.from_numpy(new_verts).to(device=dev, dtype=vdt),
+ torch.from_numpy(new_faces.astype(_np.int64)).to(device=dev, dtype=fdt),
+ src_t)
+
+
+def _drop_small_components(
+ verts: torch.Tensor, faces: torch.Tensor, min_faces: int,
+ max_propagation_iters: int = 200,
+) -> Tuple[torch.Tensor, torch.Tensor, int]:
+ """Label-propagation connected components; drop components below min_faces."""
+ if faces.numel() == 0 or min_faces <= 1:
+ return verts, faces, 0
+ device = verts.device
+ V = verts.shape[0]
+ labels = torch.arange(V, device=device, dtype=torch.int64)
+ for _ in range(max_propagation_iters):
+ v0, v1, v2 = faces[:, 0], faces[:, 1], faces[:, 2]
+ face_min = torch.minimum(torch.minimum(labels[v0], labels[v1]), labels[v2])
+ new_labels = labels.clone()
+ new_labels.scatter_reduce_(0, v0, face_min, reduce="amin", include_self=True)
+ new_labels.scatter_reduce_(0, v1, face_min, reduce="amin", include_self=True)
+ new_labels.scatter_reduce_(0, v2, face_min, reduce="amin", include_self=True)
+ new_labels = new_labels[new_labels] # path-compress
+ if torch.equal(new_labels, labels):
+ break
+ labels = new_labels
+ face_label = labels[faces[:, 0]]
+ unique_labels, counts = torch.unique(face_label, return_counts=True)
+ big_labels = unique_labels[counts >= min_faces]
+ if big_labels.shape[0] == unique_labels.shape[0]:
+ return verts, faces, 0
+ # safety: never drop every component (return the small mesh, not an empty one)
+ if big_labels.shape[0] == 0:
+ return verts, faces, 0
+ keep_face = torch.isin(face_label, big_labels)
+ kept_faces = faces[keep_face]
+ n_dropped = int(unique_labels.shape[0] - big_labels.shape[0])
+ return verts, kept_faces, n_dropped
+
+
+def clean_mesh(
+ verts: torch.Tensor, faces: torch.Tensor,
+ colors: Optional[torch.Tensor] = None,
+ normals: Optional[torch.Tensor] = None,
+ weld_epsilon: float = 0.0,
+ weld_epsilon_rel: float = 1e-6,
+ drop_degenerate: bool = True,
+ drop_duplicates: bool = True,
+ drop_unused: bool = True,
+ min_component_faces: int = 0,
+ min_angle_deg: float = 0.0,
+ max_aspect_ratio: float = 0.0,
+) -> Tuple[torch.Tensor, torch.Tensor, Optional[torch.Tensor], Optional[torch.Tensor], CleanStats]:
+ """Mesh hygiene pipeline; preserves per-vertex attributes through welding. Returns (v, f, colors, normals, stats)."""
+ stats = CleanStats(in_verts=verts.shape[0], in_faces=faces.shape[0])
+ v = verts
+ f = faces.long() if faces.numel() > 0 else faces
+ c = colors
+ n = normals
+
+ if weld_epsilon != 0.0 or weld_epsilon_rel > 0:
+ # eps stays a 0-d tensor (no sync)
+ if weld_epsilon > 0:
+ eps = torch.as_tensor(weld_epsilon, dtype=v.dtype, device=v.device)
+ else:
+ eps = torch.norm(v.max(dim=0)[0] - v.min(dim=0)[0]) * weld_epsilon_rel
+ v, f, c, n, n_welded = _weld_vertices(v, f, eps, c, n)
+ stats.welded_verts = n_welded
+
+ if drop_degenerate:
+ f_new, n_drop = _drop_degenerate_faces(v, f)
+ stats.degenerate_faces = n_drop
+ f = f_new
+ # slivers get collapse-merged instead of dropped (preserves topology)
+ if min_angle_deg > 0 or max_aspect_ratio > 0:
+ f_new, n_sliv = _collapse_slivers(
+ v, f, min_angle_deg=min_angle_deg, max_aspect_ratio=max_aspect_ratio,
+ )
+ stats.degenerate_faces += n_sliv
+ f = f_new
+
+ if drop_duplicates:
+ f_new, n_dup = _drop_duplicate_faces(f, v.shape[0])
+ stats.duplicate_faces = n_dup
+ f = f_new
+
+ if min_component_faces > 1:
+ v, f, n_comp = _drop_small_components(v, f, min_component_faces)
+ stats.components_dropped = n_comp
+
+ if drop_unused:
+ v, f, c, n, n_unused = _drop_unused_verts(v, f, c, n)
+ stats.unused_verts = n_unused
+
+ stats.out_verts = v.shape[0]
+ stats.out_faces = f.shape[0]
+ # materialize tensor-scalar counts to plain ints once at exit
+ for field in ("welded_verts", "degenerate_faces", "duplicate_faces",
+ "unused_verts", "components_dropped"):
+ val = getattr(stats, field)
+ if torch.is_tensor(val):
+ setattr(stats, field, int(val.item()))
+ return v, f, c, n, stats
+
+
+@dataclass
+class SimplifyStats:
+ input_verts: int = 0
+ input_faces: int = 0
+ output_verts: int = 0
+ output_faces: int = 0
+ iterations: int = 0
+ total_collapses: int = 0
+
+
+def qem_simplify(
+ vertices: torch.Tensor,
+ faces: torch.Tensor,
+ target_faces: int,
+ colors: Optional[torch.Tensor] = None,
+ normals: Optional[torch.Tensor] = None,
+ max_edge_length: Optional[float] = None,
+ config: Optional[QEMConfig] = None,
+) -> Tuple[torch.Tensor, torch.Tensor, Optional[torch.Tensor], Optional[torch.Tensor], SimplifyStats]:
+ """Single-mesh QEM simplification. Returns (v, f, colors, normals, stats)."""
+ cfg = config or QEMConfig()
+
+ device = vertices.device
+ in_v_dtype = vertices.dtype
+ in_f_dtype = faces.dtype
+ in_c_dtype = colors.dtype if colors is not None else None
+ in_n_dtype = normals.dtype if normals is not None else None
+
+ verts = vertices.to(device=device, dtype=cfg.dtype, copy=True)
+ faces = faces.to(device=device, dtype=torch.int64).clone()
+ colors_w = colors.to(device=device, dtype=cfg.dtype, copy=True) if colors is not None else None
+ normals_w = normals.to(device=device, dtype=cfg.dtype, copy=True) if normals is not None else None
+
+ # preclean: weld + drop degenerate/duplicate, attributes cluster-averaged
+ if cfg.preclean:
+ verts, faces, colors_w, normals_w, _cs = clean_mesh(
+ verts, faces, colors_w, normals_w,
+ weld_epsilon_rel=cfg.preclean_weld_epsilon_rel,
+ min_component_faces=cfg.preclean_min_component_faces,
+ )
+
+ num_verts = verts.shape[0]
+ num_faces = faces.shape[0]
+
+ stats = SimplifyStats(input_verts=num_verts, input_faces=num_faces)
+
+ if num_faces <= target_faces or num_verts < 4:
+ stats.output_verts = num_verts
+ stats.output_faces = num_faces
+ return verts.to(in_v_dtype), faces.to(in_f_dtype), \
+ (colors_w.to(in_c_dtype) if colors_w is not None else None), \
+ (normals_w.to(in_n_dtype) if normals_w is not None else None), \
+ stats
+
+ v_alive = torch.ones(num_verts, dtype=torch.bool, device=device)
+ f_alive = torch.ones(num_faces, dtype=torch.bool, device=device)
+
+ Q = _build_quadrics(verts, faces, cfg)
+
+ bbox = verts.max(dim=0)[0] - verts.min(dim=0)[0]
+ mesh_scale = torch.norm(bbox) # 0-d tensor; never .item()'d
+ if max_edge_length is None or max_edge_length <= 0:
+ max_edge_length = mesh_scale * 2.0
+ else:
+ max_edge_length = torch.as_tensor(max_edge_length, dtype=cfg.dtype, device=device)
+ # tiny-bbox guard (tensor-side, no sync)
+ max_edge_length = torch.where(
+ max_edge_length < 1e-6,
+ torch.ones((), dtype=max_edge_length.dtype, device=device),
+ max_edge_length,
+ )
+
+ stabilizer = mesh_scale * mesh_scale * cfg.stabilizer_scale
+ max_edge_length_sq = max_edge_length * max_edge_length
+ mesh_scale_sq = mesh_scale * mesh_scale
+
+ # threshold scaled by mesh_scale² so the 1e-8 start is scale-robust
+ thresh = float(cfg.threshold_start) * float(mesh_scale_sq) if cfg.threshold_driver else 0.0
+
+ # pre-allocated merge_map, reused each iter
+ merge_map = torch.arange(num_verts, device=device)
+
+ # py_n_faces: Python-int face count (no host sync in hot loop), re-synced at compaction
+ py_n_faces = num_faces
+
+ iteration = 0
+ total_collapses = 0
+
+ # progress bars (tqdm + comfy ProgressBar)
+ _start_faces = num_faces
+ _prog_total = max(1, _start_faces - int(target_faces))
+ _qtq = _tqdm(total=100, desc="QEM simplify", leave=False)
+ _qpbar = _comfy_utils.ProgressBar(100)
+
+ def _qreport():
+ pct = min(100, max(0, int(100 * (_start_faces - py_n_faces) / _prog_total)))
+ _qtq.n = pct
+ _qtq.refresh()
+ _qpbar.update_absolute(pct, 100)
+
+ while True:
+ if py_n_faces <= target_faces:
+ break
+ _qreport()
+
+ alive_f = torch.nonzero(f_alive, as_tuple=True)[0]
+ if alive_f.numel() == 0:
+ break
+
+ active_faces = faces[alive_f]
+
+ # memoryless QEM: rebuild Q from current geometry each iter
+ if cfg.threshold_driver and cfg.memoryless_qem and iteration > 0:
+ Q = _build_quadrics(verts, active_faces, cfg)
+
+ Q_for_iter = Q
+ # edge extraction: pack (min*V + max) so unique dedups in one pass
+ af_roll = torch.roll(active_faces, shifts=-1, dims=1)
+ mn = torch.minimum(active_faces, af_roll)
+ mx = torch.maximum(active_faces, af_roll)
+ packed = torch.add(mx, mn, alpha=num_verts).flatten()
+ packed = torch.unique(packed)
+ edges_orig = torch.stack([packed // num_verts, packed % num_verts], dim=1)
+
+ # filter by edge length
+ pab = verts[edges_orig] # (E, 2, 3)
+ el = torch.norm(pab[:, 1] - pab[:, 0], dim=-1)
+ edges_orig = edges_orig[el < max_edge_length]
+ if edges_orig.shape[0] == 0:
+ break
+
+ # sampling cap
+ n_edges_total = edges_orig.shape[0]
+ if n_edges_total > cfg.sampling_cap:
+ perm = torch.randperm(n_edges_total, device=device)[: cfg.sampling_cap]
+ edges_orig = edges_orig[perm]
+
+ # boundary mask only needed for non-qem placement
+ if cfg.placement_mode != "qem":
+ vib = _vert_is_boundary_mask(active_faces, num_verts)
+ else:
+ vib = None
+ optimal, err, valid = _edge_errors(
+ verts, Q_for_iter, edges_orig, stabilizer, max_edge_length_sq,
+ mesh_scale_sq, cfg, vert_is_boundary=vib,
+ )
+ valid_idx = torch.nonzero(valid, as_tuple=True)[0]
+ edges_orig = edges_orig[valid_idx]
+ optimal = optimal[valid_idx]
+ err = err[valid_idx]
+
+ faces_to_remove = py_n_faces - target_faces
+ n_faces_round_start = py_n_faces
+ # ~2 faces removed per collapse, so cap the round at faces_to_remove//2
+ cap_to_target = max(1, faces_to_remove // 2)
+
+ if cfg.threshold_driver:
+ # band = cost <= thresh (×10 until non-empty), quality-check, then collapse a disjoint set
+ cand = err <= thresh
+ esc = 0
+ while not bool(cand.any()) and esc < 50:
+ thresh *= 10.0
+ cand = err <= thresh
+ esc += 1
+ cand_idx = torch.nonzero(cand, as_tuple=True)[0]
+ ce = edges_orig[cand_idx]
+ copt = optimal[cand_idx]
+ cerr = err[cand_idx].clone()
+ need_flip = cfg.flip_reject_hard
+ if ((need_flip or cfg.skinny_weight > 0 or cfg.enforce_link_condition)
+ and ce.shape[0] > 0):
+ afq = faces[alive_f]
+ v_to_f = _build_vert_to_faces_pad(afq, num_verts, cfg.flip_check_max_degree)
+ # link + flip + skinny share one fused 1-ring pass
+ fc, sk, link_safe = _quality_checks_fused(
+ verts, afq, ce, copt, v_to_f, cos_threshold=cfg.flip_cos_threshold,
+ want_flip=need_flip, want_skinny=(cfg.skinny_weight > 0),
+ want_link=cfg.enforce_link_condition)
+ if link_safe is not None:
+ cerr[~link_safe] = float("inf")
+ if fc is not None:
+ cerr = torch.where(fc > 0, torch.full_like(cerr, float("inf")), cerr)
+ if sk is not None:
+ el_sq = (verts[ce[:, 1]] - verts[ce[:, 0]]).pow(2).sum(dim=-1)
+ cerr = cerr + cfg.skinny_weight * sk * el_sq
+ del v_to_f, afq
+ # penalties may push edges above thresh — re-gate the band
+ keep = cerr <= thresh
+ ce = ce[keep]
+ copt = copt[keep]
+ cerr = cerr[keep]
+ edges_orig = ce
+ optimal = copt
+ sel = _greedy_matching(ce, cerr, v_alive, cap_to_target)
+ if sel.numel() == 0:
+ # band fully rejected → raise thresh and retry
+ thresh *= 10.0
+ iteration += 1
+ if iteration >= cfg.max_iterations:
+ break
+ continue
+ else:
+ max_collapses = min(
+ cfg.max_collapses_ceiling,
+ max(cfg.max_collapses_floor, int(faces_to_remove * cfg.max_collapses_fraction)),
+ )
+ if cfg.max_collapses_relative_cap > 0:
+ # cap to a fraction of current mesh size (anti cascade-overshoot)
+ rel_cap = max(1, int(py_n_faces * cfg.max_collapses_relative_cap))
+ max_collapses = min(max_collapses, rel_cap)
+ max_collapses = min(max_collapses, cap_to_target)
+
+ # soft quality penalties on top-K: flip + skinny, sharing one v_to_f build
+ need_flip = cfg.flip_reject_hard
+ need_quality = ((need_flip or cfg.skinny_weight > 0 or cfg.enforce_link_condition)
+ and edges_orig.shape[0] > 0)
+ if need_quality:
+ n_check = min(edges_orig.shape[0],
+ max(1, cfg.quality_topk_multiplier * max_collapses))
+ if n_check < edges_orig.shape[0]:
+ topk = torch.topk(err, n_check, largest=False).indices
+ else:
+ topk = torch.arange(edges_orig.shape[0], device=device)
+ active_for_quality = faces[alive_f]
+ v_to_f = _build_vert_to_faces_pad(active_for_quality, num_verts,
+ cfg.flip_check_max_degree)
+ err = err.clone()
+ if cfg.enforce_link_condition:
+ # reject link-condition violations on ALL candidate edges, not just top-K
+ link_safe = _link_condition_mask(active_for_quality, edges_orig, v_to_f)
+ err[~link_safe] = float("inf")
+ e_tk = edges_orig[topk]
+ o_tk = optimal[topk]
+ _do_flip = need_flip
+ _do_skinny = cfg.skinny_weight > 0
+ if _do_flip and _do_skinny:
+ flip_count, skinny, _ = _quality_checks_fused(
+ verts, active_for_quality, e_tk, o_tk, v_to_f,
+ cos_threshold=cfg.flip_cos_threshold, want_link=False)
+ elif _do_flip:
+ flip_count = _normal_flip_mask(
+ verts, active_for_quality, e_tk, o_tk, v_to_f,
+ cos_threshold=cfg.flip_cos_threshold, return_count=True)
+ skinny = None
+ else:
+ skinny = _skinny_penalty(verts, active_for_quality, e_tk, o_tk, v_to_f)
+ flip_count = None
+ if _do_flip:
+ # hard reject: any flipping top-K edge → +inf
+ flips = flip_count > 0
+ if flips.any():
+ err[topk] = torch.where(
+ flips, torch.full_like(err[topk], float("inf")),
+ err[topk],
+ )
+ if _do_skinny:
+ # skinny_cost * len² (match QEM's length² scaling)
+ elen_sq = (verts[e_tk[:, 1]] - verts[e_tk[:, 0]]).pow(2).sum(dim=-1)
+ err[topk] = torch.add(err[topk], skinny * elen_sq,
+ alpha=cfg.skinny_weight)
+ del v_to_f, active_for_quality
+
+ sel = _greedy_matching(edges_orig, err, v_alive, max_collapses)
+
+ if sel.numel() == 0:
+ break
+
+ ed_sel = edges_orig[sel]
+ v_a = ed_sel[:, 0]
+ v_b = ed_sel[:, 1]
+ new_pos = optimal[sel]
+
+ # interpolate attributes by new_pos's position along [pa, pb]
+ if colors_w is not None or normals_w is not None:
+ pa_sel = verts[v_a]
+ pb_sel = verts[v_b]
+ edge_vec = pb_sel - pa_sel
+ edge_len_sq = (edge_vec * edge_vec).sum(dim=-1) + 1e-20
+ t = ((new_pos - pa_sel) * edge_vec).sum(dim=-1) / edge_len_sq
+ t = t.clamp(0.0, 1.0).unsqueeze(-1)
+ if colors_w is not None:
+ colors_w[v_a] = torch.lerp(colors_w[v_a], colors_w[v_b], t)
+ if normals_w is not None:
+ normals_w[v_a] = torch.lerp(normals_w[v_a], normals_w[v_b], t)
+
+ # apply collapse
+ verts[v_a] = new_pos
+ v_alive[v_b] = False
+ if not (cfg.threshold_driver and cfg.memoryless_qem):
+ Q[v_a] += Q[v_b]
+
+ merge_map[v_b] = v_a
+ faces = merge_map[faces]
+ merge_map[v_b] = v_b # restore identity for next iter
+
+ bad = (faces[:, 0] == faces[:, 1]) | (faces[:, 1] == faces[:, 2]) | (faces[:, 2] == faces[:, 0])
+ f_alive.masked_fill_(bad, False)
+ py_n_faces -= 2 * v_a.numel() # ~2 faces/collapse estimate; re-synced at compaction
+
+ # schedule: round removed < 1% → raise thresh ×10
+ if cfg.threshold_driver:
+ removed = n_faces_round_start - py_n_faces
+ if removed < 0.01 * n_faces_round_start:
+ thresh *= 10.0
+
+ total_collapses += int(v_a.numel())
+ iteration += 1
+
+ # periodic compaction (resyncs py_n_faces exactly)
+ if iteration % cfg.compaction_period == 0:
+ alive_frac = py_n_faces / max(1, num_faces)
+ if alive_frac < cfg.compaction_threshold:
+ faces = faces[f_alive]
+ num_faces = faces.shape[0]
+ f_alive = torch.ones(num_faces, dtype=torch.bool, device=device)
+ py_n_faces = num_faces
+
+ if iteration >= cfg.max_iterations:
+ break
+
+ _qreport()
+ _qtq.close()
+
+ # finalize: compact verts and faces
+ final_v = verts[v_alive]
+ final_c = colors_w[v_alive] if colors_w is not None else None
+ final_n = normals_w[v_alive] if normals_w is not None else None
+
+ remap = torch.full((num_verts,), -1, dtype=torch.int64, device=device)
+ remap[v_alive] = v_alive.long().cumsum(0)[v_alive] - 1 # compact remap, no sync
+
+ final_f_raw = faces[f_alive]
+ alive_mask = v_alive[final_f_raw].all(dim=1)
+ final_f_raw = final_f_raw[alive_mask]
+ final_f = remap[final_f_raw]
+ valid_faces = (final_f >= 0).all(dim=1)
+ final_f = final_f[valid_faces]
+
+ # drop degenerate faces (two indices equal)
+ if final_f.numel() > 0:
+ nondeg = (final_f[:, 0] != final_f[:, 1]) & (final_f[:, 1] != final_f[:, 2]) & (final_f[:, 0] != final_f[:, 2])
+ final_f = final_f[nondeg]
+
+ # dedup duplicate faces, winding-preserving
+ if final_f.numel() > 0:
+ key = torch.sort(final_f, dim=1)[0]
+ packed = (key[:, 0].long() * (final_v.shape[0] + 1) + key[:, 1].long()) \
+ * (final_v.shape[0] + 1) + key[:, 2].long()
+ unique_packed, inv = torch.unique(packed, return_inverse=True)
+ arange = torch.arange(packed.shape[0], device=packed.device)
+ first = torch.full((unique_packed.shape[0],), packed.shape[0],
+ dtype=torch.int64, device=packed.device)
+ first.scatter_reduce_(0, inv, arange, reduce="amin", include_self=True)
+ final_f = final_f[first]
+
+ # split back fused surface sheets (after dedup, before pruning)
+ if cfg.repair_nonmanifold and final_f.numel() > 0:
+ final_v, final_f, _src = _repair_nonmanifold_edges(final_v, final_f)
+ if final_c is not None:
+ final_c = final_c[_src]
+ if final_n is not None:
+ final_n = final_n[_src]
+
+ # post-clean: drop slivers, tiny components, unused verts
+ if cfg.postclean and final_f.numel() > 0:
+ comp_threshold = cfg.postclean_min_component_faces
+ final_v, final_f, final_c, final_n, _ps = clean_mesh(
+ final_v, final_f, final_c, final_n,
+ weld_epsilon=0.0, weld_epsilon_rel=0.0, # already welded
+ drop_degenerate=True,
+ drop_duplicates=False, # already done above
+ drop_unused=True,
+ min_component_faces=comp_threshold,
+ min_angle_deg=cfg.postclean_min_angle_deg,
+ max_aspect_ratio=cfg.postclean_max_aspect_ratio,
+ )
+
+ # post-simplify normals
+ if cfg.recompute_normals_post and final_f.numel() > 0:
+ final_n = _compute_vertex_normals(final_v, final_f)
+ elif final_n is not None and final_f.numel() > 0:
+ # keep supplied normals; flip face winding where it disagrees
+ v0 = final_v[final_f[:, 0]]
+ v1 = final_v[final_f[:, 1]]
+ v2 = final_v[final_f[:, 2]]
+ fn = torch.cross(v1 - v0, v2 - v0, dim=-1)
+ ref = (final_n[final_f[:, 0]] + final_n[final_f[:, 1]]
+ + final_n[final_f[:, 2]]) / 3.0
+ wrong = (fn * ref).sum(dim=-1) < 0
+ final_f[wrong] = final_f[wrong][:, [0, 2, 1]]
+
+ stats.iterations = iteration
+ stats.total_collapses = total_collapses
+ stats.output_verts = final_v.shape[0]
+ stats.output_faces = final_f.shape[0]
+
+ return (
+ final_v.to(in_v_dtype),
+ final_f.to(in_f_dtype),
+ final_c.to(in_c_dtype) if final_c is not None else None,
+ final_n.to(in_n_dtype) if (final_n is not None and in_n_dtype is not None) else final_n,
+ stats,
+ )
+
+
+def qem_decimate_simplify(
+ vertices: torch.Tensor,
+ faces: torch.Tensor,
+ target: int,
+ colors: Optional[torch.Tensor] = None,
+ normals: Optional[torch.Tensor] = None,
+ max_edge_length: Optional[float] = None,
+ config: Optional[QEMConfig] = None,
+):
+ """Batched wrapper. Accepts (V,3)/(F,3) or (B,V,3)/(B,F,3)."""
+ if vertices.ndim == 3:
+ out_v, out_f, out_c, out_n, out_s = [], [], [], [], []
+ for i in range(vertices.shape[0]):
+ c_in = colors[i] if colors is not None else None
+ n_in = normals[i] if normals is not None else None
+ v, f, c, n, s = qem_simplify(vertices[i], faces[i], target, c_in, n_in, max_edge_length, config)
+ out_v.append(v)
+ out_f.append(f)
+ out_s.append(s)
+ if c is not None:
+ out_c.append(c)
+ if n is not None:
+ out_n.append(n)
+ return (out_v, out_f,
+ out_c if out_c else None,
+ out_n if out_n else None,
+ out_s)
+ return qem_simplify(vertices, faces, target, colors, normals, max_edge_length, config)
+
+
+def qem_cluster_decimate(
+ vertices: torch.Tensor, faces: torch.Tensor,
+ target_verts: int = 1_000_000,
+ colors: Optional[torch.Tensor] = None,
+ face_chunk: int = 4_000_000,
+) -> Tuple[torch.Tensor, torch.Tensor, Optional[torch.Tensor]]:
+ """Vertex-cluster decimation (Rossignac-Borrel): grid-bin/average verts, remap faces,
+ drop degenerate/duplicate. Fast O(V+F) prepass for huge meshes. Returns (verts, faces, colors)."""
+ if vertices.shape[0] == 0 or faces.shape[0] == 0:
+ return vertices, faces, colors
+
+ device = vertices.device
+ bbox = vertices.max(dim=0)[0] - vertices.min(dim=0)[0]
+ bbox_min = vertices.min(dim=0)[0]
+ # cell size so the bbox holds ~3× target_verts cells (surface occupancy ~1/3)
+ cell_count_target = max(target_verts * 3, 1000)
+ extent_max = float(bbox.max().item())
+ cells_per_axis = (cell_count_target ** (1 / 3))
+ cell_size = extent_max / max(1.0, cells_per_axis)
+ scale = 1.0 / max(cell_size, 1e-20)
+
+ q = ((vertices - bbox_min) * scale).floor().to(torch.int64)
+ extent = (bbox * scale).floor().to(torch.int64) + 2
+ Wy = extent[1]
+ Wz = extent[2]
+ key = (q[:, 0] * Wy + q[:, 1]) * Wz + q[:, 2]
+
+ unique_key, inv = torch.unique(key, return_inverse=True)
+ n_unique = unique_key.shape[0]
+ counts = torch.zeros(n_unique, dtype=vertices.dtype, device=device)
+ counts.scatter_add_(0, inv, torch.ones(vertices.shape[0], dtype=vertices.dtype, device=device))
+ counts_div = counts.unsqueeze(-1).clamp_min(1.0)
+
+ new_verts = torch.zeros((n_unique, 3), dtype=vertices.dtype, device=device)
+ new_verts.scatter_add_(0, inv.unsqueeze(-1).expand_as(vertices), vertices)
+ new_verts = new_verts / counts_div
+
+ new_colors = None
+ if colors is not None:
+ new_colors = torch.zeros((n_unique, colors.shape[1]), dtype=colors.dtype, device=device)
+ new_colors.scatter_add_(0, inv.unsqueeze(-1).expand_as(colors), colors)
+ new_colors = new_colors / counts_div.to(colors.dtype)
+
+ # remap faces in chunks (face tensor can be huge), drop degenerates per chunk
+ out_chunks = []
+ F = faces.shape[0]
+ for fs in range(0, F, face_chunk):
+ fe = min(fs + face_chunk, F)
+ cf = inv[faces[fs:fe].long()]
+ nondeg = ((cf[:, 0] != cf[:, 1]) & (cf[:, 1] != cf[:, 2]) & (cf[:, 0] != cf[:, 2]))
+ if nondeg.any():
+ out_chunks.append(cf[nondeg])
+ if out_chunks:
+ new_faces = torch.cat(out_chunks, dim=0)
+ else:
+ new_faces = torch.empty((0, 3), dtype=faces.dtype, device=device)
+
+ # drop duplicate faces (same vertex set after clustering)
+ if new_faces.numel() > 0:
+ key_sorted = torch.sort(new_faces, dim=1)[0]
+ P = n_unique + 1
+ packed = (key_sorted[:, 0].long() * P + key_sorted[:, 1].long()) * P + key_sorted[:, 2].long()
+ _, first = torch.unique(packed, return_inverse=True)
+ arange = torch.arange(packed.shape[0], device=device, dtype=torch.int64)
+ first_idx = torch.full((int(first.max().item()) + 1,), packed.shape[0],
+ dtype=torch.int64, device=device)
+ first_idx.scatter_reduce_(0, first, arange, reduce="amin", include_self=True)
+ new_faces = new_faces[first_idx]
+
+ return new_verts.to(vertices.dtype), new_faces.to(faces.dtype), new_colors
diff --git a/comfy_extras/mesh3d/postprocess/remesh.py b/comfy_extras/mesh3d/postprocess/remesh.py
new file mode 100644
index 000000000..fc09b05ec
--- /dev/null
+++ b/comfy_extras/mesh3d/postprocess/remesh.py
@@ -0,0 +1,1147 @@
+"""Narrow-band Dual Contouring remeshing.
+
+Re-extracts a mesh from a sparse narrow-band voxel grid around the input
+surface (pure-PyTorch approximation of CuMesh's remesh_narrow_band_dc).
+Coarse-to-fine voxelise the band, sample SDF/UDF at voxel corners, dual
+contour (optionally QEF / Manifold DC), then optionally project back,
+filter components, fix poles, smooth, and interpolate vertex colors.
+"""
+from __future__ import annotations
+
+import functools
+import math
+from typing import Optional, Tuple
+
+import numpy as np
+import torch
+import scipy.spatial
+import comfy.utils
+from tqdm import tqdm as _tqdm
+from comfy.model_management import throw_exception_if_processing_interrupted
+
+from .qem_decimate import _sorted_edge_halfedges
+
+
+# Point-to-triangle distance (exact, vectorised)
+
+def _point_tri_closest(points: torch.Tensor, tris: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]:
+ """Exact closest point + squared distance per (point, triangle) pair; points (N,3), tris (N,3,3)."""
+ a = tris[:, 0]
+ b = tris[:, 1]
+ c = tris[:, 2]
+ ab = b - a
+ ac = c - a
+ ap = points - a
+
+ d1 = (ab * ap).sum(-1)
+ d2 = (ac * ap).sum(-1)
+
+ region_A = (d1 <= 0) & (d2 <= 0)
+
+ bp = points - b
+ d3 = (ab * bp).sum(-1)
+ d4 = (ac * bp).sum(-1)
+ region_B = (d3 >= 0) & (d4 <= d3)
+
+ cp = points - c
+ d5 = (ab * cp).sum(-1)
+ d6 = (ac * cp).sum(-1)
+ region_C = (d6 >= 0) & (d5 <= d6)
+
+ # Edge AB
+ vc = d1 * d4 - d3 * d2
+ region_AB = (vc <= 0) & (d1 >= 0) & (d3 <= 0)
+ v_ab = d1 / (d1 - d3 + 1e-20)
+ closest_AB = a + v_ab.unsqueeze(-1) * ab
+
+ # Edge AC
+ vb = d5 * d2 - d1 * d6
+ region_AC = (vb <= 0) & (d2 >= 0) & (d6 <= 0)
+ v_ac = d2 / (d2 - d6 + 1e-20)
+ closest_AC = a + v_ac.unsqueeze(-1) * ac
+
+ # Edge BC
+ va = d3 * d6 - d5 * d4
+ region_BC = (va <= 0) & ((d4 - d3) >= 0) & ((d5 - d6) >= 0)
+ v_bc = (d4 - d3) / ((d4 - d3) + (d5 - d6) + 1e-20)
+ closest_BC = b + v_bc.unsqueeze(-1) * (c - b)
+
+ # Face interior (barycentric)
+ denom = va + vb + vc + 1e-20
+ v_face = vb / denom
+ w_face = vc / denom
+ closest_face = a + v_face.unsqueeze(-1) * ab + w_face.unsqueeze(-1) * ac
+
+ # Combine by mask via in-place where (out= aliases input, no per-step alloc)
+ closest = closest_face # fresh; safe to mutate
+ torch.where(region_BC.unsqueeze(-1), closest_BC, closest, out=closest)
+ torch.where(region_AC.unsqueeze(-1), closest_AC, closest, out=closest)
+ torch.where(region_AB.unsqueeze(-1), closest_AB, closest, out=closest)
+ torch.where(region_C .unsqueeze(-1), c, closest, out=closest)
+ torch.where(region_B .unsqueeze(-1), b, closest, out=closest)
+ torch.where(region_A .unsqueeze(-1), a, closest, out=closest)
+
+ diff = points - closest
+ return closest, (diff * diff).sum(-1)
+
+
+def _build_centroid_tree(tri_verts: torch.Tensor):
+ """scipy cKDTree over triangle centroids; build once and reuse across _udf_exact calls.
+ balanced_tree/compact_nodes off: ~2.4x faster build (and faster queries on near-uniform
+ centroid clouds) with identical exact-kNN results."""
+ return scipy.spatial.cKDTree(tri_verts.mean(dim=1).detach().cpu().numpy(),
+ balanced_tree=False, compact_nodes=False)
+
+
+def _udf_exact(query_points: torch.Tensor, tri_verts: torch.Tensor,
+ k: int = 8, chunk: int = 262144, tree=None):
+ """Exact UDF (no max_dist cap) via centroid kNN; returns (dist [N], closest [N,3], tri_idx [N]). Pass prebuilt `tree` to skip rebuild.
+
+ k=8 nearest centroids before the exact point-triangle test: on dense meshes the true
+ closest triangle is essentially always within the first few neighbours. Measured vs k=16:
+ bit-identical topology, ~0.003-voxel RMS sub-voxel drift, ~15% faster overall."""
+ device = query_points.device
+ F = tri_verts.shape[0]
+ kq = int(min(k, F))
+ if tree is None:
+ tree = _build_centroid_tree(tri_verts)
+ _, cand = tree.query(query_points.detach().cpu().numpy(), k=kq, workers=-1)
+ if cand.ndim == 1:
+ cand = cand[:, None]
+ cand = np.ascontiguousarray(cand)
+
+ N = query_points.shape[0]
+ out_d = torch.empty(N, device=device, dtype=query_points.dtype)
+ out_c = torch.empty(N, 3, device=device, dtype=query_points.dtype)
+ out_t = torch.empty(N, dtype=torch.long, device=device)
+ for s in range(0, N, chunk):
+ e = min(s + chunk, N)
+ n = e - s
+ ci = torch.from_numpy(cand[s:e]).to(device).long()
+ tri = tri_verts[ci].reshape(n * kq, 3, 3)
+ P = query_points[s:e][:, None, :].expand(-1, kq, -1).reshape(n * kq, 3)
+ closest, d2 = _point_tri_closest(P, tri)
+ d2 = d2.reshape(n, kq)
+ closest = closest.reshape(n, kq, 3)
+ best = d2.argmin(dim=1)
+ ar = torch.arange(n, device=device)
+ out_d[s:e] = d2[ar, best].sqrt()
+ out_c[s:e] = closest[ar, best]
+ out_t[s:e] = ci[ar, best]
+ return out_d, out_c, out_t
+
+
+# UDF query via spatial hash on triangle AABBs
+
+def _build_tri_spatial_hash(centroids: torch.Tensor, tri_radii: torch.Tensor,
+ cell_size: torch.Tensor):
+ """Bucket triangles into `cell_size` cells (each tri into every cell its AABB touches); returns hash tuple."""
+ device = centroids.device
+ aabb_lo = (centroids - tri_radii.unsqueeze(-1))
+ aabb_hi = (centroids + tri_radii.unsqueeze(-1))
+ origin = aabb_lo.min(0)[0]
+ extent = aabb_hi.max(0)[0] - origin
+ dims = (extent / cell_size).long() + 2
+
+ cell_lo = ((aabb_lo - origin) / cell_size).long().clamp(min=0)
+ cell_hi = ((aabb_hi - origin) / cell_size).long()
+ cell_hi = torch.minimum(cell_hi, dims - 1)
+
+ # Cap span at 3 cells/axis to bound memory
+ spans = (cell_hi - cell_lo + 1).clamp(max=3)
+ n_per_tri = spans.prod(dim=-1)
+ total = int(n_per_tri.sum().item())
+
+ # Per-insertion local offset within each tri's cell box
+ rep = torch.repeat_interleave(torch.arange(centroids.shape[0], device=device), n_per_tri)
+ cum = torch.cat([torch.zeros(1, device=device, dtype=n_per_tri.dtype),
+ n_per_tri.cumsum(0)[:-1]])
+ local = torch.arange(total, device=device) - cum[rep]
+ sx = spans[rep, 0]
+ sy = spans[rep, 1]
+
+ lx = local % sx
+ ly = (local // sx) % sy
+ lz = local // (sx * sy)
+ cx = cell_lo[rep, 0] + lx
+ cy = cell_lo[rep, 1] + ly
+ cz = cell_lo[rep, 2] + lz
+ keys = (cx * dims[1] + cy) * dims[2] + cz
+
+ sort_idx = keys.argsort()
+ sorted_keys = keys[sort_idx]
+ tri_per_cell = rep[sort_idx]
+
+ unique_keys, counts = torch.unique_consecutive(sorted_keys, return_counts=True)
+ cell_starts = torch.cat([torch.zeros(1, dtype=counts.dtype, device=device),
+ counts.cumsum(0)])
+ return origin, dims, unique_keys, tri_per_cell, cell_starts, centroids, tri_radii
+
+
+def _udf_query(query_points: torch.Tensor,
+ tri_verts: torch.Tensor,
+ hash_data,
+ cell_size: torch.Tensor,
+ max_dist: float,
+ chunk_max: int = 4096,
+ return_closest: bool = False,
+ return_tri_idx: bool = False):
+ """Capped UDF to nearest triangle (<= max_dist), optionally with closest point and/or tri index; chunk size is adaptive to hash density."""
+ origin, dims, unique_keys, tri_per_cell, cell_starts, tri_centroids, tri_radii = hash_data
+ device = query_points.device
+ Q = query_points.shape[0]
+ # Adaptive chunk: bound per-chunk candidate-gather memory by hash density
+ avg_per_cell = tri_per_cell.numel() / max(1, unique_keys.numel())
+ est_cands_per_query = max(1.0, avg_per_cell * 27)
+ chunk = max(256, min(chunk_max, int(50_000_000 / est_cands_per_query)))
+ out_d2 = torch.full((Q,), float(max_dist) ** 2, dtype=query_points.dtype, device=device)
+ # Default closest_pt = query_pt itself, so a missed query's lerp is a no-op
+ out_closest = (query_points.clone() if return_closest else None)
+ out_tri = (torch.full((Q,), -1, dtype=torch.long, device=device)
+ if return_tri_idx else None)
+
+ rng = torch.tensor([-1, 0, 1], device=device, dtype=torch.long)
+ offs = torch.stack(torch.meshgrid(rng, rng, rng, indexing="ij"), dim=-1).reshape(-1, 3) # (27, 3)
+
+ for cs in range(0, Q, chunk):
+ ce = min(cs + chunk, Q)
+ qp = query_points[cs:ce]
+ q_cell = ((qp - origin) / cell_size).long()
+ # Look up 27 neighbour cells per query
+ n_cell = q_cell.unsqueeze(1) + offs.unsqueeze(0) # (q, 27, 3)
+ n_valid = ((n_cell >= 0) & (n_cell < dims)).all(-1)
+ n_key = (n_cell[..., 0] * dims[1] + n_cell[..., 1]) * dims[2] + n_cell[..., 2]
+ flat_key = n_key.reshape(-1).contiguous()
+ ins = torch.searchsorted(unique_keys, flat_key)
+ ins_c = ins.clamp(max=unique_keys.numel() - 1)
+ found = (ins < unique_keys.numel()) & (unique_keys[ins_c] == flat_key) & n_valid.reshape(-1)
+ cell_idx = torch.where(found, ins_c, torch.zeros_like(ins_c))
+ c_starts = cell_starts[cell_idx]
+ c_ends = cell_starts[cell_idx + 1]
+ c_counts = (c_ends - c_starts) * found.long()
+ rep_q = torch.repeat_interleave(
+ torch.arange(qp.shape[0] * 27, device=device) // 27, c_counts)
+ if rep_q.numel() == 0:
+ continue
+ total = rep_q.numel()
+ slot_starts_per_pair = torch.cumsum(c_counts, dim=0) - c_counts
+ per_pair_start = torch.repeat_interleave(c_starts, c_counts)
+ slot_within = torch.arange(total, device=device) - torch.repeat_interleave(slot_starts_per_pair, c_counts)
+ tri_indices = tri_per_cell[per_pair_start + slot_within]
+
+ pts = qp[rep_q]
+ # Centroid pre-cull (squared): drop where ||pts-centroid||-radius > max_dist
+ diff = pts - tri_centroids[tri_indices]
+ d2_cand = (diff * diff).sum(-1)
+ thresh = max_dist + tri_radii[tri_indices]
+ cull_keep = d2_cand < thresh * thresh
+ rep_q = rep_q[cull_keep]
+ pts = pts[cull_keep]
+ tri_indices = tri_indices[cull_keep]
+ if rep_q.numel() == 0:
+ continue
+ tri = tri_verts[tri_indices]
+ closest, d2 = _point_tri_closest(pts, tri)
+
+ # Min per query for this chunk.
+ local_min = torch.full((qp.shape[0],), float(max_dist) ** 2,
+ dtype=query_points.dtype, device=device)
+ local_min.scatter_reduce_(0, rep_q, d2, reduce="amin", include_self=True)
+ # Only update where this chunk improved; ties may overwrite (any is valid)
+ better = local_min < out_d2[cs:ce]
+ out_d2[cs:ce] = torch.where(better, local_min, out_d2[cs:ce])
+ if return_closest or return_tri_idx:
+ ties = (d2 == local_min[rep_q]) & better[rep_q]
+ if return_closest:
+ out_closest[cs + rep_q[ties]] = closest[ties]
+ if return_tri_idx:
+ out_tri[cs + rep_q[ties]] = tri_indices[ties]
+
+ out_d = out_d2.sqrt()
+ extras = []
+ if return_closest:
+ extras.append(out_closest)
+ if return_tri_idx:
+ extras.append(out_tri)
+ if extras:
+ return (out_d, *extras)
+ return out_d
+
+
+# Sparse coarse-to-fine voxel grid in narrow band
+
+def _build_narrow_band_voxels(verts: torch.Tensor, faces: torch.Tensor,
+ center: torch.Tensor, scale: float,
+ resolution: int, eps: float,
+ progress_callback=None) -> torch.Tensor:
+ """Voxel coords (Nv,3) in 0..resolution-1 whose centre is within ~0.87 cell_size of the surface; also returns the kept cKDTree."""
+ device = verts.device
+ tri_verts = verts[faces.long()]
+ # Exact UDF; build the centroid cKDTree once and reuse across refinement levels
+ tree = _build_centroid_tree(tri_verts)
+
+ base_resolution = resolution
+ while base_resolution > 32 and base_resolution % 2 == 0:
+ base_resolution //= 2
+
+ rng = torch.arange(base_resolution, device=device, dtype=torch.long)
+ coords = torch.stack(torch.meshgrid(rng, rng, rng, indexing="ij"), dim=-1).reshape(-1, 3)
+
+ OFFSETS = torch.tensor([
+ [0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0],
+ [0, 0, 1], [1, 0, 1], [0, 1, 1], [1, 1, 1],
+ ], dtype=torch.long, device=device)
+
+ current_res = base_resolution
+ while True:
+ throw_exception_if_processing_interrupted()
+ cell_size = scale / current_res
+ pts = ((coords.float() + 0.5) / current_res - 0.5) * scale + center
+ dists, _, _ = _udf_exact(pts, tri_verts, tree=tree)
+ keep = dists < 0.87 * cell_size + eps
+ coords = coords[keep]
+ if progress_callback is not None:
+ progress_callback()
+ if current_res >= resolution:
+ break
+ current_res *= 2
+ coords = coords * 2
+ coords = (coords.unsqueeze(1) + OFFSETS.unsqueeze(0)).reshape(-1, 3)
+
+ return coords, tree
+
+
+# Dual Contouring
+
+def _dual_contour(voxel_coords: torch.Tensor, corner_udf: torch.Tensor,
+ corner_keys: torch.Tensor,
+ resolution: int, scale: float, center: torch.Tensor,
+ tri_face_normals: Optional[torch.Tensor] = None,
+ qef_query=None,
+ corner_valid: Optional[torch.Tensor] = None,
+ ) -> Tuple[torch.Tensor, torch.Tensor]:
+ """Dual contour active voxels; returns (Nv,3) dual verts and (M,3) faces into them. QEF placement when tri_face_normals+qef_query given, else centroid of crossings."""
+ device = voxel_coords.device
+ Nv = voxel_coords.shape[0]
+ # 8 corners per voxel, packed into a 1d key
+ CORNER_OFFS = torch.tensor([
+ [0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0],
+ [0, 0, 1], [1, 0, 1], [0, 1, 1], [1, 1, 1],
+ ], dtype=torch.long, device=device)
+
+ corner_pos_per_voxel = voxel_coords.unsqueeze(1) + CORNER_OFFS.unsqueeze(0) # (Nv, 8, 3)
+ R1 = resolution + 1
+ keys_per_voxel = (corner_pos_per_voxel[..., 0] * R1
+ + corner_pos_per_voxel[..., 1]) * R1 + corner_pos_per_voxel[..., 2]
+ # Look up SDF index per corner; missing corners default to +1 (outside)
+ idx_per_voxel = torch.searchsorted(corner_keys, keys_per_voxel.reshape(-1))
+ idx_clamped = idx_per_voxel.clamp(max=corner_keys.numel() - 1)
+ found = (idx_per_voxel < corner_keys.numel()) & (corner_keys[idx_clamped] == keys_per_voxel.reshape(-1))
+ sd = torch.where(found, corner_udf[idx_clamped], torch.full_like(corner_udf[idx_clamped], 1.0))
+ sd = sd.reshape(Nv, 8) # surface at sign = 0
+
+ # 12 voxel edges as (corner_a, corner_b) pairs (indices into the 8 corners above)
+ EDGES = torch.tensor([
+ [0, 1], [2, 3], [4, 5], [6, 7], # x-axis edges
+ [0, 2], [1, 3], [4, 6], [5, 7], # y-axis
+ [0, 4], [1, 5], [2, 6], [3, 7], # z-axis
+ ], dtype=torch.long, device=device)
+
+ a_sd = sd[:, EDGES[:, 0]] # (Nv, 12)
+ b_sd = sd[:, EDGES[:, 1]]
+ crosses = (a_sd * b_sd) < 0 # (Nv, 12) bool
+ # Skip crossings touching an invalid corner (avoids fake faces at band edge)
+ if corner_valid is not None:
+ cv_per_voxel = torch.where(found, corner_valid[idx_clamped],
+ torch.zeros_like(found)).reshape(Nv, 8)
+ edge_valid = cv_per_voxel[:, EDGES[:, 0]] & cv_per_voxel[:, EDGES[:, 1]]
+ crosses = crosses & edge_valid
+ # Zero-crossing interp factor per edge
+ t = a_sd / (a_sd - b_sd + 1e-20)
+ t = t.clamp(0.0, 1.0).unsqueeze(-1)
+
+ corner_world = (corner_pos_per_voxel.float() / resolution - 0.5) * scale + center.unsqueeze(0).unsqueeze(0) # (Nv, 8, 3)
+ a_pos = corner_world[:, EDGES[:, 0]] # (Nv, 12, 3)
+ b_pos = corner_world[:, EDGES[:, 1]]
+ crossing_pts = torch.lerp(a_pos, b_pos, t) # (Nv, 12, 3)
+
+ # Default dual vert: centroid of crossings (also QEF/no-crossing fallback)
+ crosses_f = crosses.float().unsqueeze(-1)
+ crossing_sum = (crossing_pts * crosses_f).sum(dim=1)
+ n_cross = crosses.float().sum(dim=1, keepdim=True).clamp_min(1.0)
+ centroid_verts = crossing_sum / n_cross
+ centre_world = ((voxel_coords.float() + 0.5) / resolution - 0.5) * scale + center.unsqueeze(0)
+ has_cross = crosses.any(dim=1, keepdim=True)
+ dual_verts = torch.where(has_cross, centroid_verts, centre_world)
+
+ # QEF placement: minimise sum_i (n_i·(x-p_i))² via Tikhonov-regularised
+ # normal equations (A+reg I)x=b; clamp to voxel bbox, else fall back to centroid.
+ if tri_face_normals is not None and qef_query is not None:
+ Nv = voxel_coords.shape[0]
+ flat_pts = crossing_pts.reshape(-1, 3)
+ flat_mask = crosses.reshape(-1)
+ if flat_mask.any():
+ query_pts = flat_pts[flat_mask]
+ _, _, qef_tri_idx = qef_query(query_pts)
+ # Missed queries get a zero normal (null constraint, ignored by solver)
+ valid_q = qef_tri_idx >= 0
+ normals_at_q = torch.zeros_like(query_pts)
+ normals_at_q[valid_q] = tri_face_normals[qef_tri_idx[valid_q]]
+ full_normals = torch.zeros((Nv * 12, 3), dtype=query_pts.dtype, device=device)
+ full_normals[flat_mask] = normals_at_q
+ n_per_edge = full_normals.reshape(Nv, 12, 3)
+
+ # einsum sums into the 3x3 directly, skipping a big intermediate
+ A = torch.einsum('vec,ved->vcd', n_per_edge, n_per_edge) # (Nv, 3, 3)
+ n_dot_p = (n_per_edge * crossing_pts).sum(dim=-1) # (Nv, 12)
+ b = torch.einsum('ve,vec->vc', n_dot_p, n_per_edge) # (Nv, 3)
+
+ # Tikhonov regularisation in-place (A, b are fresh einsum outputs)
+ reg = 1e-2
+ A.diagonal(dim1=-2, dim2=-1).add_(reg)
+ b.add_(centroid_verts, alpha=reg)
+ try:
+ qef_solution = torch.linalg.solve(A, b.unsqueeze(-1)).squeeze(-1)
+ except torch.linalg.LinAlgError:
+ qef_solution = centroid_verts
+
+ # Clamp QEF output to the voxel bbox
+ lo = corner_world[:, 0] # (Nv, 3) min corner
+ hi = corner_world[:, 7] # (Nv, 3) max corner
+ in_box = (qef_solution >= lo).all(dim=-1) & (qef_solution <= hi).all(dim=-1)
+ qef_solution = torch.where(in_box.unsqueeze(-1), qef_solution, centroid_verts)
+
+ dual_verts = torch.where(has_cross, qef_solution, centre_world)
+
+ # Topology: each crossing grid edge is shared by 4 voxels -> quad -> 2 tris.
+ # NEIGHBOUR_OFFS lays out the 4 sharing voxels per axis; y-axis order is
+ # reversed vs x/z to keep manifold winding around each shared edge.
+ NEIGHBOUR_OFFS = torch.tensor([
+ [[0, 0, 0], [0, -1, 0], [0, -1, -1], [0, 0, -1]],
+ [[0, 0, 0], [0, 0, -1], [-1, 0, -1], [-1, 0, 0]],
+ [[0, 0, 0], [-1, 0, 0], [-1, -1, 0], [0, -1, 0]],
+ ], dtype=torch.long, device=device)
+
+ # Min-corner +axis edge index per axis (slots 0/4/8 in EDGES)
+ EDGE_OF_AXIS = torch.tensor([0, 4, 8], dtype=torch.long, device=device)
+
+ # Sorted voxel-coord keys for neighbour lookup
+ vox_dims = voxel_coords.max(dim=0)[0] + 2
+ vox_key = (voxel_coords[:, 0] * vox_dims[1] + voxel_coords[:, 1]) * vox_dims[2] + voxel_coords[:, 2]
+ sort_v = vox_key.argsort()
+ sorted_vox_key = vox_key[sort_v]
+
+ tris = []
+ for axis in range(3):
+ edge_idx = EDGE_OF_AXIS[axis]
+ owner_mask = crosses[:, edge_idx] # (Nv,) bool
+ if not owner_mask.any():
+ continue
+ owner_voxels = voxel_coords[owner_mask] # (No, 3)
+ a_sign = a_sd[owner_mask, edge_idx] # (No,) sign at corner a
+ nbrs = owner_voxels.unsqueeze(1) + NEIGHBOUR_OFFS[axis].unsqueeze(0) # (No, 4, 3)
+ nbr_keys = (nbrs[..., 0] * vox_dims[1] + nbrs[..., 1]) * vox_dims[2] + nbrs[..., 2]
+ flat = nbr_keys.reshape(-1).contiguous()
+ ins = torch.searchsorted(sorted_vox_key, flat)
+ ins_c = ins.clamp(max=sorted_vox_key.numel() - 1)
+ valid = (ins < sorted_vox_key.numel()) & (sorted_vox_key[ins_c] == flat)
+ valid = valid.reshape(-1, 4).all(dim=1)
+ if not valid.any():
+ continue
+ dual_indices = sort_v[ins_c].reshape(-1, 4)[valid] # (Mv, 4)
+ sign_a = a_sign[valid]
+ # Winding: flip when corner a is outside (sign_a > 0) so normal points out
+ d0 = dual_indices[:, 0]
+ d1 = dual_indices[:, 1]
+ d2 = dual_indices[:, 2]
+ d3 = dual_indices[:, 3]
+ flip = sign_a > 0
+ t1a = torch.stack([d0, d1, d2], dim=1)
+ t2a = torch.stack([d0, d2, d3], dim=1)
+ t1b = torch.stack([d0, d2, d1], dim=1)
+ t2b = torch.stack([d0, d3, d2], dim=1)
+ t1 = torch.where(flip.unsqueeze(-1), t1b, t1a)
+ t2 = torch.where(flip.unsqueeze(-1), t2b, t2a)
+ tris.append(t1)
+ tris.append(t2)
+
+ if not tris:
+ return dual_verts, torch.empty((0, 3), dtype=torch.long, device=device)
+ new_faces = torch.cat(tris, dim=0)
+ return dual_verts, new_faces
+
+
+# Manifold Dual Contouring (Schaefer, Ju, Warren 2007)
+
[email protected]_cache(maxsize=None)
+def _build_mdc_lut() -> Tuple[torch.Tensor, torch.Tensor]:
+ """Per 8-corner sign pattern: K (256,) patch count and group (256,12) patch id per edge (-1 if non-crossing)."""
+ EDGE_PAIRS = [
+ (0, 1), (2, 3), (4, 5), (6, 7), # x-axis edges
+ (0, 2), (1, 3), (4, 6), (5, 7), # y-axis edges
+ (0, 4), (1, 5), (2, 6), (3, 7), # z-axis edges
+ ]
+ K = torch.zeros(256, dtype=torch.int64)
+ group = torch.full((256, 12), -1, dtype=torch.int64)
+
+ for pat in range(256):
+ signs = [(pat >> i) & 1 for i in range(8)] # 1=outside, 0=inside
+
+ parent = list(range(8))
+
+ def find(x: int) -> int:
+ r = x
+ while parent[r] != r:
+ r = parent[r]
+ while parent[x] != r:
+ nxt = parent[x]
+ parent[x] = r
+ x = nxt
+ return r
+
+ # Union same-sign corners (not separated by the surface)
+ for a, b in EDGE_PAIRS:
+ if signs[a] == signs[b]:
+ ra, rb = find(a), find(b)
+ if ra != rb:
+ parent[ra] = rb
+
+ # Distinct (interior_root, exterior_root) pairs are distinct patches
+ group_map: dict[tuple[int, int], int] = {}
+ for ei, (a, b) in enumerate(EDGE_PAIRS):
+ if signs[a] == signs[b]:
+ continue
+ in_c = a if signs[a] == 0 else b
+ ex_c = b if signs[a] == 0 else a
+ key = (find(in_c), find(ex_c))
+ if key not in group_map:
+ group_map[key] = len(group_map)
+ group[pat, ei] = group_map[key]
+ K[pat] = len(group_map)
+
+ return K, group
+
+
+def _mdc_lut(device: torch.device) -> Tuple[torch.Tensor, torch.Tensor]:
+ K, g = _build_mdc_lut()
+ return K.to(device), g.to(device)
+
+
+def _dual_contour_manifold(voxel_coords: torch.Tensor, corner_udf: torch.Tensor,
+ corner_keys: torch.Tensor,
+ resolution: int, scale: float, center: torch.Tensor,
+ corner_valid: Optional[torch.Tensor] = None,
+ ) -> Tuple[torch.Tensor, torch.Tensor]:
+ """Manifold DC: like _dual_contour but emits 1-4 dual verts per voxel via the patch LUT (centroid placement only)."""
+ device = voxel_coords.device
+ Nv = voxel_coords.shape[0]
+
+ CORNER_OFFS = torch.tensor([
+ [0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0],
+ [0, 0, 1], [1, 0, 1], [0, 1, 1], [1, 1, 1],
+ ], dtype=torch.long, device=device)
+ corner_pos = voxel_coords.unsqueeze(1) + CORNER_OFFS.unsqueeze(0) # (Nv, 8, 3)
+ R1 = resolution + 1
+ keys = (corner_pos[..., 0] * R1 + corner_pos[..., 1]) * R1 + corner_pos[..., 2]
+ flat_keys = keys.reshape(-1)
+ idx = torch.searchsorted(corner_keys, flat_keys)
+ idx_c = idx.clamp(max=corner_keys.numel() - 1)
+ found = (idx < corner_keys.numel()) & (corner_keys[idx_c] == flat_keys)
+ sd = torch.where(found, corner_udf[idx_c],
+ torch.full_like(corner_udf[idx_c], 1.0)).reshape(Nv, 8)
+
+ # Sign pattern: bit i = (sd[i] > 0), matching the LUT convention
+ sign_bits = (sd > 0).to(torch.int64) # (Nv, 8)
+ weights = (1 << torch.arange(8, device=device, dtype=torch.int64))
+ pat_per_voxel = (sign_bits * weights).sum(dim=-1) # (Nv,) in 0..255
+
+ K_lut, group_lut = _mdc_lut(device)
+ K_per_voxel = K_lut[pat_per_voxel] # (Nv,)
+ total_verts = int(K_per_voxel.sum().item())
+ if total_verts == 0:
+ return (torch.empty((0, 3), dtype=voxel_coords.dtype, device=device),
+ torch.empty((0, 3), dtype=torch.long, device=device))
+
+ vert_offset = (torch.cumsum(K_per_voxel, dim=0) - K_per_voxel) # (Nv,)
+ voxel_per_subvol = torch.repeat_interleave(
+ torch.arange(Nv, device=device), K_per_voxel) # (total_verts,)
+
+ EDGES = torch.tensor([
+ [0, 1], [2, 3], [4, 5], [6, 7],
+ [0, 2], [1, 3], [4, 6], [5, 7],
+ [0, 4], [1, 5], [2, 6], [3, 7],
+ ], dtype=torch.long, device=device)
+ sb_a = sign_bits[:, EDGES[:, 0]] # (Nv, 12)
+ sb_b = sign_bits[:, EDGES[:, 1]]
+ crosses = sb_a != sb_b # (Nv, 12)
+
+ if corner_valid is not None:
+ cv = torch.where(found, corner_valid[idx_c],
+ torch.zeros_like(found)).reshape(Nv, 8)
+ edge_valid = cv[:, EDGES[:, 0]] & cv[:, EDGES[:, 1]]
+ crosses = crosses & edge_valid
+
+ edge_group_per_voxel = group_lut[pat_per_voxel] # (Nv, 12), -1 if not crossing
+ # LUT already gives -1 for non-crossing edges; only re-mask for corner_valid
+ if corner_valid is not None:
+ edge_group_per_voxel = torch.where(crosses, edge_group_per_voxel,
+ torch.full_like(edge_group_per_voxel, -1))
+
+ a_sd = sd[:, EDGES[:, 0]] # (Nv, 12)
+ b_sd = sd[:, EDGES[:, 1]]
+ denom = a_sd - b_sd
+ t = torch.where(denom.abs() > 1e-20, a_sd / denom, torch.zeros_like(a_sd))
+ t = t.clamp(0.0, 1.0).unsqueeze(-1)
+ corner_world = (corner_pos.float() / resolution - 0.5) * scale + center.unsqueeze(0).unsqueeze(0)
+ a_pos = corner_world[:, EDGES[:, 0]]
+ b_pos = corner_world[:, EDGES[:, 1]]
+ crossing_pts = torch.lerp(a_pos, b_pos, t) # (Nv, 12, 3)
+
+ # Aggregate crossing positions per (voxel, subvolume) into global dual verts
+ flat_group = edge_group_per_voxel.reshape(-1)
+ valid_mask = flat_group >= 0
+ flat_voxel = torch.arange(Nv, device=device).unsqueeze(-1).expand(Nv, 12).reshape(-1)
+ flat_pos = crossing_pts.reshape(-1, 3)
+ v_idx = flat_voxel[valid_mask]
+ g_idx = flat_group[valid_mask]
+ pos = flat_pos[valid_mask]
+ global_idx = vert_offset[v_idx] + g_idx # (Nvalid,)
+
+ pos_dtype = crossing_pts.dtype
+ sums = torch.zeros((total_verts, 3), dtype=pos_dtype, device=device)
+ counts = torch.zeros(total_verts, dtype=pos_dtype, device=device)
+ sums.scatter_add_(0, global_idx.unsqueeze(-1).expand(-1, 3), pos)
+ counts.scatter_add_(0, global_idx, torch.ones_like(g_idx, dtype=pos_dtype))
+ # Fully-masked subvolumes default to the voxel centre (unreferenced)
+ voxel_centre = ((voxel_coords.float() + 0.5) / resolution - 0.5) * scale + center.unsqueeze(0)
+ dual_verts = torch.where(
+ counts.unsqueeze(-1) > 0,
+ sums / counts.clamp_min(1.0).unsqueeze(-1),
+ voxel_centre[voxel_per_subvol].to(pos_dtype),
+ )
+
+ # Face emission. SHARED_LOCAL_EDGE[axis,k] = the k-th neighbour's local edge
+ # slot corresponding to the shared grid edge (owner's slot = EDGE_OF_AXIS[axis]).
+ NEIGHBOUR_OFFS = torch.tensor([
+ [[0, 0, 0], [0, -1, 0], [0, -1, -1], [0, 0, -1]],
+ [[0, 0, 0], [0, 0, -1], [-1, 0, -1], [-1, 0, 0]],
+ [[0, 0, 0], [-1, 0, 0], [-1, -1, 0], [0, -1, 0]],
+ ], dtype=torch.long, device=device)
+ SHARED_LOCAL_EDGE = torch.tensor([
+ [0, 1, 3, 2], # x-axis
+ [4, 6, 7, 5], # y-axis
+ [8, 9, 11, 10], # z-axis
+ ], dtype=torch.long, device=device)
+ EDGE_OF_AXIS = torch.tensor([0, 4, 8], dtype=torch.long, device=device)
+
+ vox_dims = voxel_coords.max(dim=0)[0] + 2
+ vox_key = (voxel_coords[:, 0] * vox_dims[1] + voxel_coords[:, 1]) * vox_dims[2] + voxel_coords[:, 2]
+ sort_v = vox_key.argsort()
+ sorted_vox_key = vox_key[sort_v]
+
+ tris_out = []
+ for axis in range(3):
+ edge_idx = EDGE_OF_AXIS[axis]
+ owner_mask = crosses[:, edge_idx]
+ if not owner_mask.any():
+ continue
+ owner_voxels = voxel_coords[owner_mask]
+ sign_a_at_owner = sb_a[owner_mask, edge_idx] # (No,) — 0 inside, 1 outside
+
+ nbrs = owner_voxels.unsqueeze(1) + NEIGHBOUR_OFFS[axis].unsqueeze(0) # (No, 4, 3)
+ nbr_keys = (nbrs[..., 0] * vox_dims[1] + nbrs[..., 1]) * vox_dims[2] + nbrs[..., 2]
+ flat = nbr_keys.reshape(-1).contiguous()
+ ins = torch.searchsorted(sorted_vox_key, flat)
+ ins_c = ins.clamp(max=sorted_vox_key.numel() - 1)
+ valid_nbr = (ins < sorted_vox_key.numel()) & (sorted_vox_key[ins_c] == flat)
+ valid_quad = valid_nbr.reshape(-1, 4).all(dim=1)
+ if not valid_quad.any():
+ continue
+
+ nbr_orig = sort_v[ins_c].reshape(-1, 4)[valid_quad] # (Mv, 4) voxel idx
+ nbr_pat = pat_per_voxel[nbr_orig] # (Mv, 4)
+ local_e = SHARED_LOCAL_EDGE[axis].unsqueeze(0).expand_as(nbr_pat)
+ nbr_subvol = group_lut[nbr_pat, local_e] # (Mv, 4)
+ # Every neighbour must agree the shared edge is crossing
+ ok = (nbr_subvol >= 0).all(dim=1)
+ if not ok.any():
+ continue
+ nbr_subvol = nbr_subvol[ok]
+ nbr_orig = nbr_orig[ok]
+ dual_indices = vert_offset[nbr_orig] + nbr_subvol # (Mv', 4)
+ sign_a = sign_a_at_owner[valid_quad][ok] # 0 = inside, 1 = outside
+
+ # Winding: flip when corner a is outside (same as _dual_contour)
+ flip = sign_a > 0
+ d0, d1, d2, d3 = dual_indices.unbind(dim=1)
+ t1a = torch.stack([d0, d1, d2], dim=1)
+ t2a = torch.stack([d0, d2, d3], dim=1)
+ t1b = torch.stack([d0, d2, d1], dim=1)
+ t2b = torch.stack([d0, d3, d2], dim=1)
+ tris_out.append(torch.where(flip.unsqueeze(-1), t1b, t1a))
+ tris_out.append(torch.where(flip.unsqueeze(-1), t2b, t2a))
+
+ if not tris_out:
+ return dual_verts, torch.empty((0, 3), dtype=torch.long, device=device)
+ return dual_verts, torch.cat(tris_out, dim=0)
+
+
+# Main entry
+
+def _filter_components(verts: torch.Tensor, faces: torch.Tensor,
+ min_fraction: float = 0.01,
+ drop_inverted: bool = True,
+ drop_enclosed: bool = True) -> torch.Tensor:
+ """Drop tiny / inverted-volume / bbox-enclosed connected components; returns filtered faces."""
+ device = faces.device
+ V = verts.shape[0]
+
+ # Connected components via min-label propagation across faces (200-iter max)
+ label = torch.arange(V, dtype=torch.long, device=device)
+ for _ in range(200):
+ f_min = torch.minimum(torch.minimum(label[faces[:, 0]], label[faces[:, 1]]),
+ label[faces[:, 2]])
+ new_label = label.clone()
+ new_label.scatter_reduce_(0, faces[:, 0], f_min, reduce="amin", include_self=True)
+ new_label.scatter_reduce_(0, faces[:, 1], f_min, reduce="amin", include_self=True)
+ new_label.scatter_reduce_(0, faces[:, 2], f_min, reduce="amin", include_self=True)
+ new_label = new_label[new_label] # path compression
+ if torch.equal(new_label, label):
+ break
+ label = new_label
+
+ face_label = label[faces[:, 0]] # (F,)
+ unique_labels, inv = torch.unique(face_label, return_inverse=True)
+ C = unique_labels.shape[0]
+ counts = torch.bincount(inv, minlength=C)
+ max_count = int(counts.max().item())
+ keep = torch.ones(C, dtype=torch.bool, device=device)
+
+ if min_fraction > 0:
+ threshold = max(1, int(max_count * min_fraction))
+ keep = keep & (counts >= threshold)
+
+ if drop_inverted:
+ # Drop components with negative signed volume, but always keep the largest
+ v0 = verts[faces[:, 0]]
+ v1 = verts[faces[:, 1]]
+ v2 = verts[faces[:, 2]]
+ face_vol = (v0 * torch.cross(v1, v2, dim=-1)).sum(dim=-1) # (F,)
+ comp_vol = torch.zeros(C, dtype=face_vol.dtype, device=device)
+ comp_vol.scatter_add_(0, inv, face_vol)
+ if C > 1:
+ large = counts.argmax()
+ vol_ok = (comp_vol >= 0)
+ vol_ok[large] = True
+ keep = keep & vol_ok
+
+ if drop_enclosed and C > 1:
+ # Two-pass: (1) bbox-inside-largest test, then (2) +X raycast point-in-mesh
+ large = counts.argmax()
+ face_v = verts[faces]
+ face_min = face_v.min(dim=1).values
+ face_max = face_v.max(dim=1).values
+ comp_min = torch.full((C, 3), float("inf"), dtype=verts.dtype, device=device)
+ comp_max = torch.full((C, 3), float("-inf"), dtype=verts.dtype, device=device)
+ comp_min.scatter_reduce_(0, inv[:, None].expand(-1, 3), face_min,
+ reduce="amin", include_self=True)
+ comp_max.scatter_reduce_(0, inv[:, None].expand(-1, 3), face_max,
+ reduce="amax", include_self=True)
+ big_min = comp_min[large]
+ big_max = comp_max[large]
+ enclosed = ((comp_min >= big_min).all(dim=-1)
+ & (comp_max <= big_max).all(dim=-1))
+ enclosed[large] = False
+
+ # Per-component centroid for the raycast test
+ face_centroid = face_v.mean(dim=1) # (F, 3)
+ comp_centroid = torch.zeros((C, 3), dtype=verts.dtype, device=device)
+ comp_centroid.scatter_add_(0, inv[:, None].expand(-1, 3), face_centroid)
+ comp_centroid = comp_centroid / counts.to(verts.dtype).unsqueeze(-1).clamp_min(1.0)
+
+ # Raycast surviving non-largest candidates (small loop)
+ big_faces = faces[inv == large]
+ bv0 = verts[big_faces[:, 0]]
+ bv1 = verts[big_faces[:, 1]]
+ bv2 = verts[big_faces[:, 2]]
+ candidates = torch.nonzero((keep & ~enclosed)
+ & (torch.arange(C, device=device) != large),
+ as_tuple=True)[0]
+ for ci in candidates.tolist():
+ origin = comp_centroid[ci]
+ # 2D point-in-triangle in YZ for the ray origin's (y, z)
+ oy, oz = origin[1], origin[2]
+ s12 = (bv1[:, 1] - oy) * (bv2[:, 2] - oz) - (bv1[:, 2] - oz) * (bv2[:, 1] - oy)
+ s20 = (bv2[:, 1] - oy) * (bv0[:, 2] - oz) - (bv2[:, 2] - oz) * (bv0[:, 1] - oy)
+ s01 = (bv0[:, 1] - oy) * (bv1[:, 2] - oz) - (bv0[:, 2] - oz) * (bv1[:, 1] - oy)
+ total = s12 + s20 + s01
+ inside_yz = (((s12 >= 0) & (s20 >= 0) & (s01 >= 0))
+ | ((s12 <= 0) & (s20 <= 0) & (s01 <= 0)))
+ inside_yz = inside_yz & (total.abs() > 1e-20)
+ inv_t = 1.0 / total.where(total.abs() > 1e-20, torch.ones_like(total))
+ hit_x = (s12 * bv0[:, 0] + s20 * bv1[:, 0] + s01 * bv2[:, 0]) * inv_t
+ crossings = int((inside_yz & (hit_x > origin[0])).sum().item())
+ if crossings % 2 == 1:
+ enclosed[ci] = True
+ keep = keep & ~enclosed
+
+ if keep.all():
+ return faces
+ face_keep = keep[inv]
+ return faces[face_keep]
+
+
+def _taubin_smooth(verts: torch.Tensor, faces: torch.Tensor,
+ iters: int, lam: float = 0.5, mu: float = -0.53,
+ progress_callback=None) -> torch.Tensor:
+ """Taubin lambda|mu low-pass smoothing (volume-preserving); boundary verts are no-ops."""
+ if iters <= 0 or verts.numel() == 0 or faces.numel() == 0:
+ return verts
+ device = verts.device
+ V = verts.shape[0]
+ sorted_keys, _, _ = _sorted_edge_halfedges(faces, V)
+ uniq_keys, _ = torch.unique_consecutive(sorted_keys, return_counts=True)
+ P = V + 1
+ a = uniq_keys // P
+ b = uniq_keys % P
+ ones = torch.ones_like(a, dtype=verts.dtype)
+ counts = torch.zeros(V, dtype=verts.dtype, device=device)
+ counts.scatter_add_(0, a, ones)
+ counts.scatter_add_(0, b, ones)
+ counts_safe = counts.clamp_min(1.0).unsqueeze(-1)
+ has_nb = (counts > 0).unsqueeze(-1)
+ a_exp = a.unsqueeze(-1).expand(-1, 3)
+ b_exp = b.unsqueeze(-1).expand(-1, 3)
+
+ out = verts
+ for _ in range(iters):
+ throw_exception_if_processing_interrupted()
+ for w in (lam, mu):
+ sums = torch.zeros_like(out)
+ sums.scatter_add_(0, a_exp, out[b])
+ sums.scatter_add_(0, b_exp, out[a])
+ delta = (sums / counts_safe - out) * has_nb
+ out = out + w * delta
+ if progress_callback is not None:
+ progress_callback()
+ return out
+
+
+def _fix_poles(verts: torch.Tensor, faces: torch.Tensor,
+ colors: Optional[torch.Tensor] = None
+ ) -> Tuple[torch.Tensor, torch.Tensor, Optional[torch.Tensor]]:
+ """Midpoint-collapse edge-sharing valence-3 vertex pairs (DC T-junction poles); boundary verts excluded."""
+ device = verts.device
+ V = verts.shape[0]
+ if V == 0 or faces.numel() == 0:
+ return verts, faces, colors
+
+ sorted_keys, _, _ = _sorted_edge_halfedges(faces, V)
+ uniq_keys, key_counts = torch.unique_consecutive(sorted_keys, return_counts=True)
+ P = V + 1
+ a = uniq_keys // P
+ b = uniq_keys % P
+ # Boundary verts (endpoints of single-face edges) are excluded from poles
+ boundary_v = torch.zeros(V, dtype=torch.bool, device=device)
+ bnd_mask = key_counts == 1
+ if bnd_mask.any():
+ boundary_v[a[bnd_mask]] = True
+ boundary_v[b[bnd_mask]] = True
+ ones = torch.ones_like(a)
+ valence = torch.zeros(V, dtype=torch.long, device=device)
+ valence.scatter_add_(0, a, ones)
+ valence.scatter_add_(0, b, ones)
+ is_pole = (valence == 3) & ~boundary_v
+ if int(is_pole.sum().item()) < 2:
+ return verts, faces, colors
+
+ pp_edge = is_pole[a] & is_pole[b]
+ if not pp_edge.any():
+ return verts, faces, colors
+ cand_a = a[pp_edge]
+ cand_b = b[pp_edge]
+
+ # Greedy maximal matching: accept candidates whose endpoints are still free
+ used = torch.zeros(V, dtype=torch.bool, device="cpu")
+ cand_a_cpu = cand_a.cpu().tolist()
+ cand_b_cpu = cand_b.cpu().tolist()
+ pairs: list[tuple[int, int]] = []
+ for ai, bi in zip(cand_a_cpu, cand_b_cpu):
+ if not used[ai] and not used[bi]:
+ pairs.append((ai, bi))
+ used[ai] = True
+ used[bi] = True
+ if not pairs:
+ return verts, faces, colors
+
+ pairs_t = torch.tensor(pairs, dtype=torch.long, device=device) # (P, 2)
+ keep_i = torch.minimum(pairs_t[:, 0], pairs_t[:, 1])
+ drop_i = torch.maximum(pairs_t[:, 0], pairs_t[:, 1])
+
+ new_verts = verts.clone()
+ new_verts[keep_i] = 0.5 * (verts[pairs_t[:, 0]] + verts[pairs_t[:, 1]])
+ new_colors = None
+ if colors is not None:
+ new_colors = colors.clone()
+ new_colors[keep_i] = 0.5 * (colors[pairs_t[:, 0]] + colors[pairs_t[:, 1]])
+
+ remap = torch.arange(V, dtype=torch.long, device=device)
+ remap[drop_i] = keep_i
+ new_faces = remap[faces.long()]
+ degen = ((new_faces[:, 0] == new_faces[:, 1])
+ | (new_faces[:, 1] == new_faces[:, 2])
+ | (new_faces[:, 0] == new_faces[:, 2]))
+ new_faces = new_faces[~degen]
+
+ used_mask = torch.zeros(V, dtype=torch.bool, device=device)
+ used_mask[new_faces.reshape(-1)] = True
+ if not used_mask.all():
+ compact = used_mask.long().cumsum(0) - 1
+ new_verts = new_verts[used_mask]
+ if new_colors is not None:
+ new_colors = new_colors[used_mask]
+ new_faces = compact[new_faces]
+ return new_verts, new_faces.to(faces.dtype), new_colors
+
+
+def remesh_narrow_band_dc(
+ vertices: torch.Tensor,
+ faces: torch.Tensor,
+ resolution: int = 256,
+ target_faces: int = 0, # 0 = use `resolution`; >0 = auto-derive resolution
+ band: float = 1.0,
+ project_back: float = 0.0,
+ qef: bool = True,
+ sign_mode: str = "udf", # "sdf" | "udf"
+ drop_small_components: float = 0.01, # drop components below this fraction of max
+ drop_inverted_components: bool = True, # drop closed components with negative signed volume
+ drop_enclosed_components: bool = True, # drop components whose bbox is inside the largest's bbox
+ fix_poles: bool = False, # collapse 3-3 valence vertex pairs (DC T-junction artifact)
+ smooth_iters: int = 0, # Taubin smoothing iterations (low-pass, volume-preserving)
+ smooth_lambda: float = 0.5,
+ smooth_mu: float = -0.53,
+ manifold: bool = False, # Manifold DC: emit 1-4 dual verts per voxel for multi-sheet cases
+ colors: Optional[torch.Tensor] = None,
+ scale: Optional[float] = None,
+ center: Optional[torch.Tensor] = None,
+):
+ """Narrow-band Dual Contouring re-extraction; returns (new_vertices, new_faces, new_colors), new_colors None unless `colors` given.
+
+ Key params: target_faces>0 auto-derives resolution; sign_mode sdf/udf
+ (UDF disables qef and may need component filters); project_back lerps verts
+ toward the closest surface point; scale/center default to bbox.
+ """
+ assert vertices.ndim == 2 and vertices.shape[1] == 3
+ assert faces.ndim == 2 and faces.shape[1] == 3
+ device = vertices.device
+
+ if center is None:
+ center = 0.5 * (vertices.max(dim=0)[0] + vertices.min(dim=0)[0])
+ else:
+ center = center.to(device=device, dtype=vertices.dtype)
+ if scale is None:
+ bbox = vertices.max(dim=0)[0] - vertices.min(dim=0)[0]
+ scale = float(bbox.max().item()) * 1.1
+
+ # Auto-derive resolution from target_faces (~3 tris/crossing-voxel; +-30%)
+ if target_faces > 0:
+ tv = vertices[faces.long()]
+ cross_v = torch.cross(tv[:, 1] - tv[:, 0], tv[:, 2] - tv[:, 0], dim=-1)
+ surface_area = 0.5 * cross_v.norm(dim=-1).sum().item()
+ relative_area = max(surface_area / (scale * scale), 1e-6)
+ derived = int(math.sqrt(target_faces / (3.0 * relative_area)))
+ # Round to a multiple of 32 (builder doubles from a <=32 base)
+ derived = ((derived + 31) // 32) * 32
+ derived = max(32, min(1024, derived))
+ resolution = derived
+
+ eps = band * scale / resolution
+
+ # progress: one tick per narrow-band level + 3 stages (SDF/DC/post) + each smoothing iter
+ n_levels, _b = 1, resolution
+ while _b > 32 and _b % 2 == 0:
+ _b //= 2
+ while _b < resolution:
+ _b *= 2
+ n_levels += 1
+ _total_ticks = n_levels + 3 + int(smooth_iters)
+ _pbar = comfy.utils.ProgressBar(_total_ticks)
+ _tq = _tqdm(total=_total_ticks, desc="Remesh DC", leave=False)
+
+ def tick():
+ _pbar.update(1)
+ _tq.update(1)
+
+ # Step 1: sparse narrow-band voxel grid (coarse-to-fine)
+ voxel_coords, _band_tree = _build_narrow_band_voxels(
+ vertices, faces, center, scale, resolution, eps,
+ progress_callback=tick)
+ if voxel_coords.numel() == 0:
+ return (torch.empty((0, 3), dtype=vertices.dtype, device=device),
+ torch.empty((0, 3), dtype=faces.dtype, device=device),
+ None if colors is None else torch.empty((0, colors.shape[1]),
+ dtype=colors.dtype, device=device))
+
+ # Step 2: collect unique corner positions of all active voxels
+ CORNER_OFFS = torch.tensor([
+ [0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0],
+ [0, 0, 1], [1, 0, 1], [0, 1, 1], [1, 1, 1],
+ ], dtype=torch.long, device=device)
+ corners = (voxel_coords.unsqueeze(1) + CORNER_OFFS.unsqueeze(0)).reshape(-1, 3)
+ R1 = resolution + 1
+ corner_keys = (corners[:, 0] * R1 + corners[:, 1]) * R1 + corners[:, 2]
+ unique_corner_keys, corner_inv = torch.unique(corner_keys, return_inverse=True)
+ unique_corners = torch.zeros((unique_corner_keys.shape[0], 3), dtype=torch.long, device=device)
+ unique_corners[corner_inv] = corners
+
+ if sign_mode == "sdf":
+ use_sdf = True
+ elif sign_mode == "udf":
+ use_sdf = False
+ else:
+ raise ValueError(f"sign_mode must be 'sdf'|'udf', got {sign_mode!r}")
+
+ # Step 3: distance field at every unique corner.
+ tri_verts_g = vertices[faces.long()]
+ centroids = tri_verts_g.mean(dim=1)
+ tri_radii = (tri_verts_g - centroids.unsqueeze(1)).norm(dim=-1).max(dim=-1).values
+ # face normals: needed for the SDF sign AND for QEF placement (QEF is sign-agnostic,
+ # so it works in UDF mode too — (n·(x-p))² is unchanged by normal orientation)
+ if use_sdf or qef:
+ tri_face_normals_all = torch.nn.functional.normalize(
+ torch.cross(tri_verts_g[:, 1] - tri_verts_g[:, 0],
+ tri_verts_g[:, 2] - tri_verts_g[:, 0], dim=-1),
+ p=2, dim=-1, eps=1e-12)
+ cell_size = scale / resolution
+ corner_world = (unique_corners.float() / resolution - 0.5) * scale + center.unsqueeze(0)
+ # Exact corner UDF (no max_dist cap) so DC crossings keep fine detail
+ udf, corner_closest, corner_tri = _udf_exact(corner_world, tri_verts_g, tree=_band_tree)
+ corner_valid = corner_tri >= 0
+ if use_sdf:
+ sign = torch.ones_like(udf)
+ n_for_corner = tri_face_normals_all[corner_tri.clamp(min=0)]
+ offset = corner_world - corner_closest
+ sign_dot = (offset * n_for_corner).sum(-1)
+ sign = torch.where(corner_valid & (sign_dot < 0), -sign, sign)
+ sdf = sign * udf
+ else:
+ # UDF mode: iso at UDF=eps; double surface on closed meshes, weld after
+ sdf = udf - eps
+ tick() # SDF done
+
+ # Short-range hash reused by project_back / colors sampling (max_dist up to 4*cell)
+ short_hash_cell_t = torch.tensor(2.0 * cell_size, dtype=vertices.dtype, device=device)
+ short_hash = _build_tri_spatial_hash(centroids, tri_radii, short_hash_cell_t)
+
+ # Step 4 + 5: dual contouring + topology. QEF works in both modes (sign-agnostic);
+ # in UDF it pulls the ±eps crossing back onto the triangle planes → sharper edges.
+ if qef:
+ tri_face_normals = tri_face_normals_all
+ # QEF needs the nearest triangle per crossing point. The centroid cKDTree
+ # (_band_tree) is already built, and its exact k-NN query is markedly faster
+ # here than a spatial-hash gather (which builds ~100-triangle candidate lists
+ # per query on a dense input) — and it's exact. So reuse it directly.
+ def _qef_query(pts):
+ return _udf_exact(pts, tri_verts_g, tree=_band_tree)
+ else:
+ tri_face_normals = None
+ _qef_query = None
+
+ if manifold and use_sdf:
+ # MDC ignores qef / tri_face_normals — centroid placement only.
+ dual_verts, new_faces = _dual_contour_manifold(
+ voxel_coords, sdf, unique_corner_keys,
+ resolution, scale, center,
+ corner_valid=corner_valid)
+ else:
+ dual_verts, new_faces = _dual_contour(
+ voxel_coords, sdf, unique_corner_keys,
+ resolution, scale, center,
+ tri_face_normals=tri_face_normals, qef_query=_qef_query,
+ # corner_valid filter only matters in SDF mode
+ corner_valid=corner_valid if use_sdf else None)
+ tick() # DC done
+
+ # Step 6: project_back and / or color sampling share one closest-point query
+ need_query = (project_back > 0 or colors is not None) and dual_verts.numel() > 0
+ out_colors = None
+ if need_query:
+ result = _udf_query(
+ dual_verts, tri_verts_g, short_hash, short_hash_cell_t,
+ max_dist=4.0 * cell_size,
+ return_closest=True,
+ return_tri_idx=(colors is not None))
+ if colors is not None:
+ _, closest_pts, closest_tri = result
+ else:
+ _, closest_pts = result
+
+ if project_back > 0:
+ dual_verts = torch.lerp(dual_verts, closest_pts, float(project_back))
+
+ if colors is not None:
+ # Barycentric-interpolate input colors at the closest point
+ safe_tri = closest_tri.clamp(min=0)
+ tri_v_idx = faces[safe_tri].long() # (N, 3)
+ tri_v = vertices[tri_v_idx] # (N, 3, 3)
+ v0 = tri_v[:, 0]
+ v1 = tri_v[:, 1]
+ v2 = tri_v[:, 2]
+ e0 = v1 - v0
+ e1 = v2 - v0
+ e2 = closest_pts - v0
+ d00 = (e0 * e0).sum(-1)
+ d01 = (e0 * e1).sum(-1)
+ d11 = (e1 * e1).sum(-1)
+ d20 = (e2 * e0).sum(-1)
+ d21 = (e2 * e1).sum(-1)
+ denom = d00 * d11 - d01 * d01 + 1e-20
+ bv = ((d11 * d20 - d01 * d21) / denom).clamp(0.0, 1.0)
+ bw = ((d00 * d21 - d01 * d20) / denom).clamp(0.0, 1.0)
+ bu = (1.0 - bv - bw).clamp(0.0, 1.0)
+ tri_c = colors[tri_v_idx] # (N, 3, C)
+ out_colors = (bu.unsqueeze(-1) * tri_c[:, 0]
+ + bv.unsqueeze(-1) * tri_c[:, 1]
+ + bw.unsqueeze(-1) * tri_c[:, 2])
+ # Zero out failed-query rows (their barycentric used bogus triangle 0)
+ invalid = closest_tri < 0
+ if invalid.any():
+ out_colors[invalid] = 0
+
+ # Filter spurious components (tiny pieces, inverted inner shells)
+ if (new_faces.numel() > 0
+ and (drop_small_components > 0 or drop_inverted_components
+ or drop_enclosed_components)):
+ new_faces = _filter_components(
+ dual_verts, new_faces,
+ min_fraction=drop_small_components if drop_small_components > 0 else 0.0,
+ drop_inverted=drop_inverted_components,
+ drop_enclosed=drop_enclosed_components)
+
+ if fix_poles and new_faces.numel() > 0:
+ dual_verts, new_faces, out_colors = _fix_poles(
+ dual_verts, new_faces, out_colors)
+ tick() # post-process done
+
+ if smooth_iters > 0 and dual_verts.numel() > 0 and new_faces.numel() > 0:
+ dual_verts = _taubin_smooth(dual_verts, new_faces,
+ iters=int(smooth_iters),
+ lam=float(smooth_lambda),
+ mu=float(smooth_mu),
+ progress_callback=tick)
+
+ # Drop unused verts (non-crossing voxels' dual verts) and compact faces
+ if dual_verts.numel() > 0 and new_faces.numel() > 0:
+ used = torch.zeros(dual_verts.shape[0], dtype=torch.bool, device=device)
+ used[new_faces[:, 0]] = True
+ used[new_faces[:, 1]] = True
+ used[new_faces[:, 2]] = True
+ remap = used.long().cumsum(0) - 1
+ dual_verts = dual_verts[used]
+ new_faces = remap[new_faces.long()]
+ if out_colors is not None:
+ out_colors = out_colors[used]
+
+ return (dual_verts.to(vertices.dtype),
+ new_faces.to(faces.dtype),
+ out_colors.to(colors.dtype) if (out_colors is not None and colors is not None) else None)
diff --git a/comfy_extras/mesh3d/uv_unwrap/mesh.py b/comfy_extras/mesh3d/uv_unwrap/mesh.py
new file mode 100644
index 000000000..3ad79e6ea
--- /dev/null
+++ b/comfy_extras/mesh3d/uv_unwrap/mesh.py
@@ -0,0 +1,162 @@
+"""Mesh container, edge/face adjacency, manifold cleanup."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List
+
+import numpy as np
+import torch
+from scipy.sparse import csr_matrix
+from scipy.sparse.csgraph import connected_components
+from torch import Tensor
+
+
+# ---- Per-face / per-vertex geometry ----
+
+def face_normals(vertices: Tensor, faces: Tensor) -> Tensor:
+ """[F,3] unit face normals (degenerate faces -> zero)."""
+ v0 = vertices[faces[:, 0]]
+ v1 = vertices[faces[:, 1]]
+ v2 = vertices[faces[:, 2]]
+ n = torch.linalg.cross(v1 - v0, v2 - v0)
+ return n / n.norm(dim=1, keepdim=True).clamp_min(1e-20)
+
+
+def face_areas(vertices: Tensor, faces: Tensor) -> Tensor:
+ """[F] triangle areas."""
+ v0 = vertices[faces[:, 0]]
+ v1 = vertices[faces[:, 1]]
+ v2 = vertices[faces[:, 2]]
+ return 0.5 * torch.linalg.cross(v1 - v0, v2 - v0).norm(dim=1)
+
+
+def face_centroids(vertices: Tensor, faces: Tensor) -> Tensor:
+ """[F,3] triangle centroids."""
+ return vertices[faces].mean(dim=1)
+
+
+def face_edge_lengths(vertices: Tensor, faces: Tensor) -> Tensor:
+ """[F,3] edge lengths; column e = |v[faces[:,e]] - v[faces[:,(e+1)%3]]|."""
+ va = vertices[faces]
+ vb = vertices[faces.roll(shifts=-1, dims=1)]
+ return (vb - va).norm(dim=-1).to(torch.float32)
+
+
+def chart_3d_areas(face_area: Tensor, face_chart: Tensor, n_charts: int) -> Tensor:
+ """[n_charts] sum of face areas per chart."""
+ out = torch.zeros(n_charts, dtype=face_area.dtype, device=face_area.device)
+ out.scatter_add_(0, face_chart, face_area)
+ return out
+
+
+@dataclass
+class MeshData:
+ """Cleaned mesh with adjacency; face_face[f, i] = face sharing edge (faces[f,i], faces[f,(i+1)%3]) or -1 if boundary."""
+
+ vertices: Tensor # [V, 3] float
+ faces: Tensor # [F, 3] long
+ face_face: Tensor # [F, 3] long, neighbor face id or -1
+ face_normal: Tensor # [F, 3] float
+ face_area: Tensor # [F] float
+ face_centroid: Tensor # [F, 3] float
+ component: Tensor # [F] long, connected-component id
+ n_components: int
+
+
+def build_mesh(vertices: Tensor, faces: Tensor) -> MeshData:
+ """Build adjacency; non-manifold edges (>2 incident faces) get no neighbor and act as boundary."""
+ if vertices.dtype != torch.float32:
+ vertices = vertices.to(torch.float32)
+ if faces.dtype != torch.long:
+ faces = faces.to(torch.long)
+
+ device = faces.device
+ V = vertices.shape[0]
+ F = faces.shape[0]
+
+ # Per directed face-edge; flat layout p = f*3+i.
+ a = faces.flatten()
+ b = faces.roll(shifts=-1, dims=1).flatten()
+ lo = torch.minimum(a, b)
+ hi = torch.maximum(a, b)
+ edge_key = lo * (V + 1) + hi
+
+ # Pair manifold (count==2) face-edges; others get no neighbor.
+ _, inverse, counts = torch.unique(edge_key, return_inverse=True, return_counts=True)
+ edge_count = counts[inverse]
+ manifold_mask = edge_count == 2
+
+ sort_idx = torch.argsort(edge_key, stable=True)
+ sorted_manifold = manifold_mask[sort_idx]
+ pair_positions = sort_idx[sorted_manifold]
+ pair_a = pair_positions[0::2]
+ pair_b = pair_positions[1::2]
+
+ face_id_flat = torch.arange(F, device=device).repeat_interleave(3)
+ face_face_flat = torch.full((3 * F,), -1, dtype=torch.long, device=device)
+ face_face_flat[pair_a] = face_id_flat[pair_b]
+ face_face_flat[pair_b] = face_id_flat[pair_a]
+ face_face = face_face_flat.view(F, 3)
+
+ face_face_np = face_face.cpu().numpy()
+ rows_mask = face_face_np >= 0
+ if rows_mask.any():
+ rows = np.broadcast_to(np.arange(F)[:, None], (F, 3))[rows_mask]
+ cols = face_face_np[rows_mask]
+ adj = csr_matrix(
+ (np.ones(rows.size, dtype=np.int8), (rows, cols)),
+ shape=(F, F),
+ )
+ else:
+ adj = csr_matrix((F, F), dtype=np.int8)
+ n_components, labels = connected_components(adj, directed=False)
+
+ face_normal = face_normals(vertices, faces)
+ face_area = face_areas(vertices, faces)
+ face_centroid = face_centroids(vertices, faces)
+
+ return MeshData(
+ vertices=vertices,
+ faces=faces,
+ face_face=face_face,
+ face_normal=face_normal,
+ face_area=face_area,
+ face_centroid=face_centroid,
+ component=torch.from_numpy(labels.astype(np.int64)).to(device),
+ n_components=int(n_components),
+ )
+
+
+def chart_boundary_loops(
+ faces_subset: Tensor, face_face_subset: Tensor
+) -> List[List[int]]:
+ """Return ordered boundary vertex loops for a chart submesh (face_face_subset[f,i]==-1 marks a boundary edge)."""
+ F = faces_subset.shape[0]
+ faces_np = faces_subset.cpu().numpy()
+ ff = face_face_subset.cpu().numpy()
+
+ next_v: Dict[int, int] = {}
+ for f in range(F):
+ for i in range(3):
+ if ff[f, i] == -1:
+ a = int(faces_np[f, i])
+ b = int(faces_np[f, (i + 1) % 3])
+ next_v[a] = b
+
+ loops: List[List[int]] = []
+ visited = set()
+ for start in list(next_v.keys()):
+ if start in visited:
+ continue
+ loop = [start]
+ visited.add(start)
+ cur = next_v.get(start)
+ while cur is not None and cur != start:
+ if cur in visited:
+ break
+ loop.append(cur)
+ visited.add(cur)
+ cur = next_v.get(cur)
+ if len(loop) >= 3:
+ loops.append(loop)
+ return loops
diff --git a/comfy_extras/mesh3d/uv_unwrap/pack.py b/comfy_extras/mesh3d/uv_unwrap/pack.py
new file mode 100644
index 000000000..44103f8b6
--- /dev/null
+++ b/comfy_extras/mesh3d/uv_unwrap/pack.py
@@ -0,0 +1,867 @@
+"""Atlas packing via bitmap rasterize-and-place."""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Tuple
+
+import numpy as np
+import torch
+from torch import Tensor
+from torch.nn.functional import max_pool1d
+
+import comfy.model_management
+
+# Numba is optional, but ~5x faster than torch on these operations, potential TODO: comfy-kitchen cuda/triton kernels as even faster alternative
+try:
+ from numba import njit as _njit, prange as _prange, get_num_threads as _nb_threads
+ _HAVE_NUMBA_PACK = True
+except ImportError:
+ _HAVE_NUMBA_PACK = False
+ _prange = range
+ def _nb_threads(): return 1
+ def _njit(*args, **kwargs):
+ def deco(fn): return fn
+ return deco if not args else args[0]
+
+
+# Cap on deterministic sweep density: tiny charts on a large atlas would otherwise enumerate every texel column.
+_SWEEP_CAP = 1024
+
+
+@dataclass
+class ChartPlacement:
+ chart_id: int
+ offset: Tuple[float, float] # in texels
+ scale: float # texels per UV unit
+ rotation: float = 0.0 # radians
+ swap_xy: bool = False # extra 90° bitmap rotation chosen at place time
+ chart_h: float = 0.0 # unswapped bitmap height in texels (rotation pivot)
+
+
+@_njit(cache=True, boundscheck=False, parallel=True)
+def _prepare_dims_jit(uvs, uv_off, a3, auv, tpu, padding, theta, scale, bw, bh, rot_uv):
+ """Pass 1: per-chart best rotation, texel scale, rotated/scaled UVs, padded bitmap dims."""
+ n = uv_off.shape[0] - 1
+ half_pi = math.pi * 0.5
+ for c in _prange(n):
+ v0, v1 = uv_off[c], uv_off[c + 1]
+ best_area = 1e30
+ best_t = 0.0
+ for k in range(36):
+ th = half_pi * k / 36.0
+ co = math.cos(th)
+ si = math.sin(th)
+ xmin = 1e30
+ xmax = -1e30
+ ymin = 1e30
+ ymax = -1e30
+ for i in range(v0, v1):
+ xr = uvs[i, 0] * co - uvs[i, 1] * si
+ yr = uvs[i, 0] * si + uvs[i, 1] * co
+ if xr < xmin:
+ xmin = xr
+ if xr > xmax:
+ xmax = xr
+ if yr < ymin:
+ ymin = yr
+ if yr > ymax:
+ ymax = yr
+ area = (xmax - xmin) * (ymax - ymin)
+ if area < best_area:
+ best_area = area
+ best_t = th
+ theta[c] = best_t
+ co = math.cos(best_t)
+ si = math.sin(best_t)
+ xmin = 1e30
+ xmax = -1e30
+ ymin = 1e30
+ ymax = -1e30
+ for i in range(v0, v1):
+ xr = uvs[i, 0] * co - uvs[i, 1] * si
+ yr = uvs[i, 0] * si + uvs[i, 1] * co
+ rot_uv[i, 0] = xr
+ rot_uv[i, 1] = yr
+ if xr < xmin:
+ xmin = xr
+ if xr > xmax:
+ xmax = xr
+ if yr < ymin:
+ ymin = yr
+ if yr > ymax:
+ ymax = yr
+ if v1 == v0:
+ xmin = 0.0
+ xmax = 0.0
+ ymin = 0.0
+ ymax = 0.0
+ s = math.sqrt(max(a3[c], 1e-12) / max(auv[c], 1e-12)) * tpu
+ nominal = math.sqrt(max(a3[c], 1e-12)) * tpu
+ max_bbox = max(8.0, 4.0 * nominal)
+ bbox_max = max(max(xmax - xmin, ymax - ymin), 1e-12)
+ if s * bbox_max > max_bbox:
+ s = max_bbox / bbox_max
+ scale[c] = s
+ wmax = 0.0
+ hmax = 0.0
+ for i in range(v0, v1):
+ rot_uv[i, 0] = (rot_uv[i, 0] - xmin) * s
+ rot_uv[i, 1] = (rot_uv[i, 1] - ymin) * s
+ if rot_uv[i, 0] > wmax:
+ wmax = rot_uv[i, 0]
+ if rot_uv[i, 1] > hmax:
+ hmax = rot_uv[i, 1]
+ bw[c] = int(math.ceil(wmax)) + padding + 1
+ bh[c] = int(math.ceil(hmax)) + padding + 1
+
+
+@_njit(cache=True, boundscheck=False, parallel=True)
+def _raster_all_jit(rot_uv, uv_off, faces, f_off, bw, bh, boff, buf, padding,
+ tw, th_out, perim):
+ """Pass 2: rasterize + dilate each chart into the flat buffer; records trimmed dims
+ (origin kept) and the perimeter used for placement ordering."""
+ n = uv_off.shape[0] - 1
+ eps = 1e-7
+ for c in _prange(n):
+ f0, f1 = f_off[c], f_off[c + 1]
+ v0 = uv_off[c]
+ V = uv_off[c + 1] - v0
+ w = bw[c]
+ h = bh[c]
+ o = boff[c]
+ for fi in range(f0, f1):
+ i0 = faces[fi, 0] + v0
+ i1 = faces[fi, 1] + v0
+ i2 = faces[fi, 2] + v0
+ x0 = rot_uv[i0, 0]
+ y0 = rot_uv[i0, 1]
+ x1 = rot_uv[i1, 0]
+ y1 = rot_uv[i1, 1]
+ x2 = rot_uv[i2, 0]
+ y2 = rot_uv[i2, 1]
+ xmin_f = min(x0, min(x1, x2))
+ xmax_f = max(x0, max(x1, x2))
+ ymin_f = min(y0, min(y1, y2))
+ ymax_f = max(y0, max(y1, y2))
+ xmin = max(int(math.floor(xmin_f)), 0)
+ xmax = min(int(math.ceil(xmax_f)), w - 1)
+ ymin = max(int(math.floor(ymin_f)), 0)
+ ymax = min(int(math.ceil(ymax_f)), h - 1)
+ if xmax < xmin or ymax < ymin:
+ continue
+ denom = (y1 - y2) * (x0 - x2) + (x2 - x1) * (y0 - y2)
+ if abs(denom) < 1e-20:
+ continue
+ inv_denom = 1.0 / denom
+ for py in range(ymin, ymax + 1):
+ yc = py + 0.5
+ for px in range(xmin, xmax + 1):
+ xc = px + 0.5
+ aa = ((y1 - y2) * (xc - x2) + (x2 - x1) * (yc - y2)) * inv_denom
+ bb = ((y2 - y0) * (xc - x2) + (x0 - x2) * (yc - y2)) * inv_denom
+ cc = 1.0 - aa - bb
+ if aa >= -eps and bb >= -eps and cc >= -eps:
+ buf[o + py * w + px] = True
+ # Manhattan dilation by `padding` steps (ping-pong on a scratch copy)
+ if padding > 0 and f1 > f0:
+ tmp = np.empty(h * w, dtype=np.bool_)
+ for _ in range(padding):
+ for j in range(h * w):
+ tmp[j] = buf[o + j]
+ for py in range(h):
+ for px in range(w):
+ if tmp[py * w + px]:
+ continue
+ hit = False
+ if py > 0 and tmp[(py - 1) * w + px]:
+ hit = True
+ elif py < h - 1 and tmp[(py + 1) * w + px]:
+ hit = True
+ elif px > 0 and tmp[py * w + px - 1]:
+ hit = True
+ elif px < w - 1 and tmp[py * w + px + 1]:
+ hit = True
+ if hit:
+ buf[o + py * w + px] = True
+ # trimmed dims (keep origin; 1x1 empty bitmap when nothing was rasterized)
+ rmax = -1
+ cmax = -1
+ for py in range(h):
+ for px in range(w):
+ if buf[o + py * w + px]:
+ if py > rmax:
+ rmax = py
+ if px > cmax:
+ cmax = px
+ if rmax < 0:
+ for j in range(h * w):
+ buf[o + j] = False
+ tw[c] = 1
+ th_out[c] = 1
+ else:
+ tw[c] = cmax + 1
+ th_out[c] = rmax + 1
+ # unique-edge perimeter via sorted int64 keys
+ Fc = f1 - f0
+ if Fc > 0 and V > 0:
+ keys = np.empty(Fc * 3, dtype=np.int64)
+ for fi in range(f0, f1):
+ for j in range(3):
+ a = faces[fi, j]
+ b = faces[fi, (j + 1) % 3]
+ if a < b:
+ keys[(fi - f0) * 3 + j] = a * V + b
+ else:
+ keys[(fi - f0) * 3 + j] = b * V + a
+ keys = np.sort(keys)
+ p = 0.0
+ for i in range(keys.shape[0]):
+ if i > 0 and keys[i] == keys[i - 1]:
+ continue
+ a = keys[i] // V + v0
+ b = keys[i] % V + v0
+ dx = rot_uv[a, 0] - rot_uv[b, 0]
+ dy = rot_uv[a, 1] - rot_uv[b, 1]
+ p += math.sqrt(dx * dx + dy * dy)
+ perim[c] = p
+
+
+@_njit(cache=True, boundscheck=False, parallel=True)
+def _place_all_jit(buf, boff, stride_w, tw, th, order, start, stop,
+ atlas, skyline, pool, attempts, sweep_cap, margin,
+ n_threads, cur_wh, out_x, out_y, out_sw):
+ """Place charts order[start:stop]; returns the first index NOT processed (== stop when
+ done, earlier when the atlas must grow — the caller resizes and resumes). The candidate
+ scan is striped with a (score, index) min-reduction: deterministic for any thread count,
+ and no thread intrinsics (dynamic globals would defeat cache=True)."""
+ aw = atlas.shape[1]
+ ah = atlas.shape[0]
+ cur_w = cur_wh[0]
+ cur_h = cur_wh[1]
+ n_pool = pool.shape[0]
+ big = np.int64(1) << 62
+ nt = n_threads
+ t_score = np.empty(nt, dtype=np.int64)
+ t_k = np.empty(nt, dtype=np.int64)
+ t_x = np.empty(nt, dtype=np.int64)
+ t_y = np.empty(nt, dtype=np.int64)
+ t_sw = np.empty(nt, dtype=np.int64)
+ for oi in range(start, stop):
+ ci = order[oi]
+ if cur_h + margin > ah or cur_w + margin > aw:
+ cur_wh[0] = cur_w
+ cur_wh[1] = cur_h
+ return oi
+ w0 = tw[ci] # unswapped trimmed dims
+ h0 = th[ci]
+ W = stride_w[ci] # row stride of the untrimmed block
+ o = boff[ci]
+ step = min(w0, h0) // 8
+ if step < 1:
+ step = 1
+ cap_step = max(cur_w, cur_h) // sweep_cap
+ if cap_step > step:
+ step = cap_step
+
+ poff = (oi * attempts) % (n_pool - attempts + 1)
+ x_range = cur_w + 1 if cur_w > 0 else 1
+ y_range = cur_h + 1 if cur_h > 0 else 1
+ # candidate groups per orientation: skyline-flush sweep, y=0 / y=cur_h sweeps,
+ # x=0 / x=cur_w sweeps; then the shared random pool
+ nx = max(cur_w, 1) // step + 2
+ ny = max(cur_h, 1) // step + 2
+ n_det = nx * 3 + ny * 2
+ total = n_det * 2 + attempts
+ for t in range(nt):
+ t_score[t] = big
+ t_k[t] = big
+ for t2 in _prange(nt):
+ for k in range(t2, total, nt):
+ x = 0 # int inits and no body-level continue:
+ y = 0 # parfor lowering types undef-path
+ swap = 0 # variables as f64
+ valid = True
+ if k < 2 * n_det:
+ if k >= n_det:
+ swap = 1
+ kk = k - n_det if swap == 1 else k
+ cw = w0 if swap == 0 else h0
+ if kk < nx: # skyline-flush sweep
+ x = kk * step
+ if x > cur_w:
+ valid = False
+ else:
+ x_end = x + cw
+ if x_end > skyline.shape[0]:
+ x_end = skyline.shape[0]
+ for xs in range(x, x_end):
+ if skyline[xs] > y:
+ y = int(skyline[xs])
+ elif kk < 3 * nx: # y=0 and y=cur_h sweeps
+ kk2 = kk - nx
+ x = (kk2 % nx) * step
+ if x > cur_w:
+ valid = False
+ elif kk2 >= nx:
+ y = cur_h
+ else: # x=0 and x=cur_w sweeps
+ kk2 = kk - 3 * nx
+ if kk2 >= 2 * ny:
+ valid = False
+ else:
+ y = (kk2 % ny) * step
+ if y > cur_h:
+ valid = False
+ elif kk2 >= ny:
+ x = cur_w
+ else:
+ r = k - 2 * n_det
+ x = int(pool[poff + r, 0] % x_range)
+ y = int(pool[poff + r, 1] % y_range)
+ swap = int(r & 1)
+
+ if valid:
+ ch = h0 if swap == 0 else w0
+ cw = w0 if swap == 0 else h0
+ nw = cur_w if cur_w > x + cw else x + cw
+ nh = cur_h if cur_h > y + ch else y + ch
+ ext = nw if nw > nh else nh
+ score = ext * ext + nw * nh
+ if score < t_score[t2] or (score == t_score[t2] and k < t_k[t2]):
+ ok = True
+ for j in range(ch):
+ yy = int(y + j)
+ if yy >= ah:
+ continue
+ for i in range(cw):
+ if swap == 0:
+ bit = buf[o + j * W + i]
+ else:
+ # 90deg rotation: bm_rot[j, i] = bm[h0-1-i, j]
+ bit = buf[o + (h0 - 1 - i) * W + j]
+ if not bit:
+ continue
+ xx = int(x + i)
+ if xx >= aw:
+ continue
+ if atlas[yy, xx]:
+ ok = False
+ break
+ if not ok:
+ break
+ if ok:
+ t_score[t2] = score
+ t_k[t2] = k
+ t_x[t2] = x
+ t_y[t2] = y
+ t_sw[t2] = swap
+
+ best_x = -1
+ best_y = -1
+ best_swap = 0
+ bs = big
+ bk = big
+ for t in range(nt):
+ if t_score[t] < bs or (t_score[t] == bs and t_k[t] < bk):
+ bs = t_score[t]
+ bk = t_k[t]
+ best_x = t_x[t]
+ best_y = t_y[t]
+ best_swap = t_sw[t]
+
+ if best_x < 0: # fallback: extension corner
+ best_x = cur_w
+ best_y = 0
+ best_swap = 0
+ bh_ = h0 if best_swap == 0 else w0
+ bw_ = w0 if best_swap == 0 else h0
+ # blit + extents + skyline lift
+ for j in range(bh_):
+ for i in range(bw_):
+ if best_swap == 0:
+ bit = buf[o + j * W + i]
+ else:
+ bit = buf[o + (h0 - 1 - i) * W + j]
+ if bit:
+ atlas[best_y + j, best_x + i] = True
+ if best_x + bw_ > cur_w:
+ cur_w = best_x + bw_
+ if best_y + bh_ > cur_h:
+ cur_h = best_y + bh_
+ for i in range(bw_):
+ col_x = best_x + i
+ if col_x >= skyline.shape[0]:
+ continue
+ col_top = -1
+ for j in range(bh_ - 1, -1, -1):
+ if best_swap == 0:
+ bit = buf[o + j * W + i]
+ else:
+ bit = buf[o + (h0 - 1 - i) * W + j]
+ if bit:
+ col_top = j
+ break
+ if col_top >= 0:
+ nh2 = best_y + col_top + 1
+ if nh2 > skyline[col_x]:
+ skyline[col_x] = nh2
+ out_x[ci] = best_x
+ out_y[ci] = best_y
+ out_sw[ci] = best_swap
+ cur_wh[0] = cur_w
+ cur_wh[1] = cur_h
+ return stop
+
+
+# Torch fallback (used when numba is unavailable; runs on GPU if present)
+
+def _dilate_local(x: Tensor, p: int) -> Tensor:
+ """4-connectivity dilation by p over a batch of (cnt,g,g) bitmaps. Dilation distributes
+ over union, so dilating per-triangle then OR-scattering equals dilating the chart."""
+ for _ in range(p):
+ y = x.clone()
+ y[:, 1:, :] |= x[:, :-1, :]
+ y[:, :-1, :] |= x[:, 1:, :]
+ y[:, :, 1:] |= x[:, :, :-1]
+ y[:, :, :-1] |= x[:, :, 1:]
+ x = y
+ return x
+
+
+def _raster_all_torch(uvs_tex_pad, faces_pad, fmask, bw_t, bh_t, padding, device):
+ """Rasterize every chart into one flat bool buffer; buf[cbase[i]:cbase[i+1]].view(bh,bw)
+ is chart i's bitmap. Triangles are bucketed by next-pow2 bbox size to bound memory."""
+ n = uvs_tex_pad.shape[0]
+ fmax = faces_pad.shape[1]
+ bwL, bhL = bw_t.long(), bh_t.long()
+ cbase = torch.zeros(n + 1, dtype=torch.long, device=device)
+ torch.cumsum(bwL * bhL, 0, out=cbase[1:])
+ buf = torch.zeros(int(cbase[-1].item()), dtype=torch.bool, device=device)
+
+ # gather all triangle coords, keep only valid faces -> (Ttot,3,2) + chart id per triangle
+ fp = faces_pad.reshape(n, fmax * 3)
+ tri = torch.gather(uvs_tex_pad, 1, fp[..., None].expand(-1, -1, 2)).reshape(n * fmax, 3, 2)
+ fm = fmask.reshape(-1)
+ tri_f = tri[fm]
+ if tri_f.shape[0] == 0:
+ return buf, cbase
+ cid = torch.arange(n, device=device).repeat_interleave(fmax)[fm]
+
+ # per-triangle pixel bbox, inflated by padding (origin >= 0); bucket by next-pow2 max-dim
+ tmin = tri_f.amin(1)
+ tmax = tri_f.amax(1)
+ x0 = (tmin[:, 0].floor().long() - padding).clamp_min(0)
+ y0 = (tmin[:, 1].floor().long() - padding).clamp_min(0)
+ bbw = (tmax[:, 0].ceil().long() + padding) - x0 + 1
+ bbh = (tmax[:, 1].ceil().long() + padding) - y0 + 1
+ mxd = torch.maximum(bbw, bbh).clamp_min(1)
+ bsz = (2 ** torch.ceil(torch.log2(mxd.float())).long()).long()
+
+ a = tri_f[:, 0]
+ b = tri_f[:, 1]
+ c = tri_f[:, 2]
+ v0 = b - a
+ v1 = c - a
+ d00 = (v0 * v0).sum(-1)
+ d01 = (v0 * v1).sum(-1)
+ d11 = (v1 * v1).sum(-1)
+ den = (d00 * d11 - d01 * d01).clamp(min=1e-20)
+
+
+ free = comfy.model_management.get_free_memory(device)
+ budget = int(min(1 << 23, max(1 << 20, (free * 0.25) / 56)))
+ for g in sorted(set(bsz.tolist())): # one batch per pow2 grid
+ sel_g = (bsz == g).nonzero(as_tuple=True)[0]
+ per = max(1, budget // (g * g))
+ for cs in range(0, sel_g.shape[0], per):
+ sel = sel_g[cs:cs + per]
+ m = sel.shape[0]
+ xs0 = x0[sel].view(m, 1, 1)
+ ys0 = y0[sel].view(m, 1, 1)
+ cc = cid[sel]
+ bwp = bwL[cc].view(m, 1, 1)
+ bhp = bhL[cc].view(m, 1, 1)
+ gi = torch.arange(g, device=device)
+ px = xs0 + gi.view(1, 1, g)
+ py = ys0 + gi.view(1, g, 1) # (m,g,g) int
+ pxf = px.float() + 0.5
+ pyf = py.float() + 0.5
+ v2x = pxf - a[sel, 0].view(m, 1, 1)
+ v2y = pyf - a[sel, 1].view(m, 1, 1)
+ d20 = v2x * v0[sel, 0].view(m, 1, 1) + v2y * v0[sel, 1].view(m, 1, 1)
+ d21 = v2x * v1[sel, 0].view(m, 1, 1) + v2y * v1[sel, 1].view(m, 1, 1)
+ idn = den[sel].view(m, 1, 1).reciprocal()
+ vv = torch.addcmul(d11[sel].view(m, 1, 1) * d20, d01[sel].view(m, 1, 1), d21, value=-1) * idn
+ ww = torch.addcmul(d00[sel].view(m, 1, 1) * d21, d01[sel].view(m, 1, 1), d20, value=-1) * idn
+ uu = 1.0 - vv - ww
+ inside = (uu >= -1e-6) & (vv >= -1e-6) & (ww >= -1e-6)
+ if padding > 0:
+ inside = _dilate_local(inside, padding)
+ valid = inside & (px < bwp) & (py < bhp)
+ flat = (cbase[cc].view(m, 1, 1) + py * bwp + px)[valid]
+ buf[flat] = True
+ return buf, cbase
+
+
+def _build_candidates_gpu(sky_t, ar, cur_w, cur_h, bw0, bw1, step, rand01, device):
+ """Candidate (x, y) positions as a (2, M, 2) tensor (dim 0 = orientation). The first
+ n_sky rows per orientation are skyline-flush and collision-free by construction.
+ rand01 is (2, rand_n, 2) pre-drawn uniforms; ar a preallocated arange."""
+ hi_x = max(cur_w, 1) + 1
+ hi_y = max(cur_h, 1) + 1
+ xs = ar[0:hi_x:step]
+ ys = ar[0:hi_y:step]
+ n_sky = (hi_x + step - 1) // step
+ zx = torch.zeros_like(xs)
+ zy = torch.zeros_like(ys)
+ common = torch.cat([
+ torch.stack([xs, zx], 1), torch.stack([xs, zx + cur_h], 1),
+ torch.stack([zy, ys], 1), torch.stack([zy + cur_w, ys], 1)])
+ wm = []
+ for cw in (bw0, bw1):
+ span = (n_sky - 1) * step + cw
+ wm.append(max_pool1d(sky_t[:span].view(1, 1, -1).float(), kernel_size=cw,
+ stride=step).view(-1))
+ sky = torch.stack([torch.stack([xs, wm[0].long()], 1),
+ torch.stack([xs, wm[1].long()], 1)])
+ lim = torch.tensor([hi_x, hi_y], dtype=rand01.dtype, device=device)
+ rnd = (rand01 * lim).long()
+ return torch.cat([sky, common.expand(2, -1, -1), rnd], 1), n_sky
+
+
+def _best_placement_torch(atlas, pix0, dim0, dim1, cands, n_sky, cur_w, cur_h, device):
+ """Lowest-score non-colliding placement as a (3,) int tensor [x, y, swap]. The best
+ skyline candidate bounds the score; only strictly better candidates are pixel-tested."""
+ m = cands.shape[1]
+ chw = torch.tensor([[dim0[0], dim0[1]], [dim1[0], dim1[1]]], device=device)
+ nw = torch.clamp(cands[..., 0] + chw[:, 1:], min=cur_w) # (2,M)
+ nh = torch.clamp(cands[..., 1] + chw[:, :1], min=cur_h)
+ ext = torch.maximum(nw, nh)
+ sc = ext * ext + nw * nh
+ js = sc[:, :n_sky].reshape(-1).argmin() # best skyline candidate
+ sky_o = js // n_sky
+ s_star = sc[:, :n_sky].reshape(-1)[js]
+ sky = torch.cat([cands[sky_o, js % n_sky], sky_o.reshape(1)])
+ cflat = cands.reshape(-1, 2)
+ surv = (sc.reshape(-1) < s_star).nonzero(as_tuple=True)[0] # compact once
+ total = surv.shape[0]
+ if total == 0:
+ return sky
+
+ k = pix0.shape[0]
+ if k == 0: # empty chart: anywhere free
+ j = surv[sc.reshape(-1)[surv].argmin()]
+ return torch.cat([cflat[j], (j // m).reshape(1)])
+ ordr = surv[torch.argsort(sc.reshape(-1)[surv], stable=True)]
+
+ # flattened-index collision test: one int32 gather index instead of two int64 rows/cols
+ aw = atlas.shape[1]
+ idt = torch.int32 if atlas.numel() < (1 << 31) else torch.long
+ lin0 = (pix0[:, 0] * aw + pix0[:, 1]).to(idt) # (y, x)
+ lin1 = (pix0[:, 1] * aw + (dim0[0] - 1 - pix0[:, 0])).to(idt) # rotated: (x, h-1-y)
+ linp = torch.stack([lin0, lin1])
+ aflat = atlas.view(-1)
+ og = (ordr >= m).long()
+ base = (cflat[ordr, 1] * aw + cflat[ordr, 0]).to(idt)
+
+ # prescreen survivors on ~128 strided pixels: a sampled hit proves collision, so only
+ # subsample-clean candidates need the exact test
+ stride = (k + 127) // 128
+ linp_sub = linp[:, ::stride].contiguous()
+ maybe = ~aflat[base[:, None] + linp_sub[og]].any(1)
+ passers = maybe.nonzero(as_tuple=True)[0] # ascending = score-sorted
+ npass = passers.shape[0]
+ if npass == 0:
+ return sky
+ if stride == 1: # prescreen was already exact
+ j = ordr[passers[0]]
+ return torch.cat([cflat[j], (j // m).reshape(1)])
+
+ budget = 1 << 22 # pixel-tests per chunk
+ start = 0
+ while start < npass:
+ take = max(1, budget // k)
+ pi = passers[start:start + take]
+ free = ~aflat[base[pi][:, None] + linp[og[pi]]].any(1) # (t,k) True-pixel gather
+ # single host read per chunk: whether a free hit exists and where
+ has, first = torch.stack([free.any().long(), free.long().argmax()]).tolist()
+ if has:
+ j = ordr[pi[first]] # lowest score: sorted order
+ return torch.cat([cflat[j], (j // m).reshape(1)])
+ start += take
+ budget = min(budget * 4, 1 << 25)
+ return sky
+
+
+def _pack_bitmap_torch(chart_uvs, chart_3d_areas, chart_uv_areas, chart_faces,
+ texels_per_unit, padding_texels, attempts=4096, rng_seed=0,
+ progress_callback=None):
+ """Torch rasterize-and-place packer (numba-free fallback). Returns (placements, atlas_w, atlas_h)."""
+ n = len(chart_uvs)
+ if n == 0:
+ return [], 1, 1
+ device = comfy.model_management.get_torch_device()
+ ang = torch.linspace(0.0, math.pi / 2.0, 37, device=device)[:-1]
+ cos_a, sin_a = ang.cos(), ang.sin()
+
+ # ---- Prepare pass 1: best-rotation + scale + bbox for ALL charts at once (batched) ----
+ vcount = [int(u.shape[0]) for u in chart_uvs]
+ fcount = [int(f.shape[0]) for f in chart_faces]
+ vmax = max(vcount)
+ fmax = max(fcount)
+ uvs_pad = torch.zeros(n, vmax, 2, device=device)
+ vmask = torch.zeros(n, vmax, dtype=torch.bool, device=device)
+ faces_pad = torch.zeros(n, fmax, 3, dtype=torch.long, device=device)
+ fmask = torch.zeros(n, fmax, dtype=torch.bool, device=device)
+ for i in range(n):
+ uvs_pad[i, :vcount[i]] = chart_uvs[i].to(device=device, dtype=torch.float32)
+ vmask[i, :vcount[i]] = True
+ if fcount[i]:
+ faces_pad[i, :fcount[i]] = chart_faces[i].to(device=device, dtype=torch.long)
+ fmask[i, :fcount[i]] = True
+ u0, u1 = uvs_pad[..., 0], uvs_pad[..., 1] # (N,Vmax)
+ BIG = 1e30
+ mlo = torch.where(vmask, torch.zeros_like(u0), u0.new_full((), BIG))
+ mhi = torch.where(vmask, torch.zeros_like(u0), u0.new_full((), -BIG))
+ xr = torch.addcmul(u0[:, :, None] * cos_a, u1[:, :, None], sin_a, value=-1) # (N,Vmax,A)
+ yr = torch.addcmul(u0[:, :, None] * sin_a, u1[:, :, None], cos_a)
+ xsp = (xr + mhi[:, :, None]).amax(1) - (xr + mlo[:, :, None]).amin(1) # (N,A) masked span
+ ysp = (yr + mhi[:, :, None]).amax(1) - (yr + mlo[:, :, None]).amin(1)
+ ti = (xsp * ysp).argmin(1) # (N,) best angle per chart
+ cc, ss = cos_a[ti][:, None], sin_a[ti][:, None] # (N,1)
+ rx = torch.addcmul(u0 * cc, u1, ss, value=-1) # (N,Vmax)
+ ry = torch.addcmul(u0 * ss, u1, cc)
+ rxmin = (rx + mlo).amin(1) # (N,)
+ rxmax = (rx + mhi).amax(1)
+ rymin = (ry + mlo).amin(1)
+ rymax = (ry + mhi).amax(1)
+ a3 = torch.tensor([max(a, 1e-12) for a in chart_3d_areas], device=device)
+ au = torch.tensor([max(a, 1e-12) for a in chart_uv_areas], device=device)
+ base = (a3 / au).sqrt() * texels_per_unit
+ maxb = (4.0 * a3.sqrt() * texels_per_unit).clamp_min(8.0)
+ bbm = torch.maximum(rxmax - rxmin, rymax - rymin).clamp_min(1e-12)
+ scale = torch.minimum(base, maxb / bbm) # (N,)
+ uvs_tex_pad = torch.stack([(rx - rxmin[:, None]) * scale[:, None],
+ (ry - rymin[:, None]) * scale[:, None]], dim=-1) # (N,Vmax,2)
+ bw_t = ((rxmax - rxmin) * scale).ceil().int() + padding_texels + 1
+ bh_t = ((rymax - rymin) * scale).ceil().int() + padding_texels + 1
+
+ # one sync: pull all per-chart scalars
+ thetas = ang[ti].cpu().tolist()
+ scales = scale.cpu().tolist()
+
+ # ---- Prepare pass 2: rasterize ALL charts at once, then derive per-chart sparse data ----
+ buf, cbase = _raster_all_torch(uvs_tex_pad, faces_pad, fmask, bw_t, bh_t, padding_texels, device)
+
+ # nonzero over the flat buffer is ascending, so pixels come out grouped by chart
+ nz = buf.nonzero(as_tuple=True)[0]
+ del buf
+ cid = torch.searchsorted(cbase, nz, right=True) - 1
+ bwl = bw_t.long()
+ local = nz - cbase[cid]
+ py = local // bwl[cid]
+ px = local - py * bwl[cid]
+ del nz, local
+ counts = torch.bincount(cid, minlength=n)
+ rmax = torch.full((n,), -1, dtype=torch.long, device=device)
+ cmax = torch.full((n,), -1, dtype=torch.long, device=device)
+ rmax.scatter_reduce_(0, cid, py, reduce="amax")
+ cmax.scatter_reduce_(0, cid, px, reduce="amax")
+ ht = (rmax + 1).clamp_min(1) # trimmed bitmap dims (1x1 when empty)
+ wt = (cmax + 1).clamp_min(1)
+ pix_all = torch.stack([py, px], 1) # True-pixel (row, col) offsets, sparse
+ pixr_all = torch.stack([px, rmax[cid] - py], 1) # 90deg rotation: (y, x) -> (x, h-1-y)
+ meta = torch.stack([ht, wt, counts.cumsum(0)], 1).cpu().tolist() # one sync for all charts
+ dim_l = [(m[0], m[1]) for m in meta]
+ dimr_l = [(w, h) for (h, w) in dim_l]
+ offs = [0] + [m[2] for m in meta]
+ pix_l = [pix_all[offs[i]:offs[i + 1]] for i in range(n)]
+ pixr_l = [pixr_all[offs[i]:offs[i + 1]] for i in range(n)]
+
+ # column tops (skyline lift), batched via flat scatter-amax over (chart, column) keys
+ wmax = max(max(h, w) for (h, w) in dim_l)
+ ct_pad = torch.full((n * wmax,), -1, dtype=torch.long, device=device)
+ ctr_pad = torch.full((n * wmax,), -1, dtype=torch.long, device=device)
+ ct_pad.scatter_reduce_(0, cid * wmax + px, py, reduce="amax")
+ ctr_pad.scatter_reduce_(0, cid * wmax + (rmax[cid] - py), px, reduce="amax")
+ ct_pad = ct_pad.view(n, wmax)
+ ctr_pad = ctr_pad.view(n, wmax)
+ del cid, py, px, rmax, cmax
+
+ # ---- Placement: skyline bin-pack on GPU ----
+ order = sorted(range(n), key=lambda i: -(dim_l[i][0] * dim_l[i][1])) # biggest bitmap first
+ max_b = max(max(d) for d in dim_l)
+ margin = max_b + 8
+ side_guess = int(math.sqrt(sum(d[0] * d[1] for d in dim_l)) * 2) + 16
+ cap = side_guess + margin
+ atlas = torch.zeros((cap, cap), dtype=torch.bool, device=device)
+ sky_t = torch.zeros(cap, dtype=torch.long, device=device)
+ ar = torch.arange(cap + 1, device=device)
+ cur_w = cur_h = 0
+ placements = [None] * n
+ gen = torch.Generator(device=device).manual_seed(rng_seed)
+ rand_n = min(512, attempts) # random samples per orientation
+ # no _SWEEP_CAP here: the skyline-bound pruning depends on the dense sweep
+ rand01 = torch.rand(n, 2, rand_n, 2, generator=gen, device=device) # all draws upfront
+
+ for t_i, ci in enumerate(order):
+ if progress_callback is not None and (t_i & 255) == 0:
+ progress_callback(n + t_i, 2 * n)
+ if cur_h + margin > atlas.shape[0] or cur_w + margin > atlas.shape[1]:
+ ns = max(atlas.shape[0], cur_h + margin, cur_w + margin)
+ na = torch.zeros((ns, ns), dtype=torch.bool, device=device)
+ na[:atlas.shape[0], :atlas.shape[1]] = atlas
+ atlas = na
+ nsk = torch.zeros(ns, dtype=torch.long, device=device)
+ nsk[:sky_t.shape[0]] = sky_t
+ sky_t = nsk
+ ar = torch.arange(ns + 1, device=device)
+ dim, dimr = dim_l[ci], dimr_l[ci]
+ step = max(1, min(dim[0], dim[1]) // 8)
+ cands, n_sky = _build_candidates_gpu(
+ sky_t, ar, cur_w, cur_h, dim[1], dimr[1], step, rand01[t_i], device)
+ res = _best_placement_torch(atlas, pix_l[ci], dim, dimr,
+ cands, n_sky, cur_w, cur_h, device)
+ bx, by, swap = (int(v) for v in res.tolist())
+ if bx < 0:
+ bx, by, swap = cur_w, 0, 0
+ pix = pixr_l[ci] if swap else pix_l[ci]
+ bh_, bw_ = (dimr if swap else dim)
+ atlas[by + pix[:, 0], bx + pix[:, 1]] = True # sparse blit
+ cur_w = max(cur_w, bx + bw_)
+ cur_h = max(cur_h, by + bh_)
+ ct = (ctr_pad if swap else ct_pad)[ci, :bw_] # GPU skyline lift
+ ix = ar[bx:bx + bw_]
+ sky_t[ix] = torch.where(ct >= 0, torch.maximum(sky_t[ix], by + ct + 1), sky_t[ix])
+ placements[ci] = ChartPlacement(chart_id=ci, offset=(float(bx), float(by)),
+ scale=scales[ci], rotation=thetas[ci], swap_xy=bool(swap),
+ chart_h=float(dim_l[ci][0]))
+ return placements, cur_w, cur_h
+
+
+def pack_bitmap_concat(
+ uvs_cat: np.ndarray, # (sumV, 2) per-chart concatenated UVs
+ uv_offsets: np.ndarray, # (n+1,)
+ faces_cat: np.ndarray, # (sumF, 3) local vert ids per chart
+ face_offsets: np.ndarray, # (n+1,)
+ chart_3d_areas: np.ndarray,
+ chart_uv_areas: np.ndarray,
+ texels_per_unit: float = 256.0,
+ padding_texels: int = 2,
+ attempts: int = 4096,
+ rng_seed: int = 0,
+ progress_callback=None,
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, int, int]:
+ """Rasterize-and-place packer over concatenated chart arrays (no per-chart python).
+ Returns (x, y, swap, rotation, scale, chart_h, atlas_w, atlas_h) with one entry per chart.
+ progress_callback(done, total) is invoked periodically; total is 2*n_charts."""
+ n = int(uv_offsets.shape[0]) - 1
+ empty = np.zeros(n, dtype=np.int64)
+ if n == 0:
+ return empty, empty, empty, empty.astype(np.float64), empty.astype(np.float64), empty, 1, 1
+ if not _HAVE_NUMBA_PACK:
+ chart_uvs = [torch.from_numpy(np.ascontiguousarray(uvs_cat[uv_offsets[c]:uv_offsets[c + 1]]))
+ for c in range(n)]
+ chart_faces = [torch.from_numpy(np.ascontiguousarray(faces_cat[face_offsets[c]:face_offsets[c + 1]]))
+ for c in range(n)]
+ placements, w, h = _pack_bitmap_torch(
+ chart_uvs, [float(a) for a in chart_3d_areas], [float(a) for a in chart_uv_areas],
+ chart_faces, texels_per_unit, padding_texels, attempts=attempts,
+ rng_seed=rng_seed, progress_callback=progress_callback)
+ px = np.array([p.offset[0] for p in placements], dtype=np.int64)
+ py = np.array([p.offset[1] for p in placements], dtype=np.int64)
+ sw = np.array([1 if p.swap_xy else 0 for p in placements], dtype=np.int64)
+ th = np.array([p.rotation for p in placements], dtype=np.float64)
+ sc = np.array([p.scale for p in placements], dtype=np.float64)
+ chh = np.array([p.chart_h for p in placements], dtype=np.int64)
+ return px, py, sw, th, sc, chh, w, h
+
+ uvs64 = np.ascontiguousarray(uvs_cat, dtype=np.float64)
+ faces64 = np.ascontiguousarray(faces_cat, dtype=np.int64)
+ uv_off = np.ascontiguousarray(uv_offsets, dtype=np.int64)
+ f_off = np.ascontiguousarray(face_offsets, dtype=np.int64)
+ a3 = np.ascontiguousarray(chart_3d_areas, dtype=np.float64)
+ auv = np.ascontiguousarray(chart_uv_areas, dtype=np.float64)
+
+ theta = np.zeros(n, dtype=np.float64)
+ scale = np.zeros(n, dtype=np.float64)
+ bw = np.zeros(n, dtype=np.int64)
+ bh = np.zeros(n, dtype=np.int64)
+ rot_uv = np.empty_like(uvs64)
+ _prepare_dims_jit(uvs64, uv_off, a3, auv, float(texels_per_unit), int(padding_texels),
+ theta, scale, bw, bh, rot_uv)
+ boff = np.zeros(n + 1, dtype=np.int64)
+ np.cumsum(bw * bh, out=boff[1:])
+ buf = np.zeros(int(boff[-1]), dtype=np.bool_)
+ tw = np.zeros(n, dtype=np.int64)
+ th_arr = np.zeros(n, dtype=np.int64)
+ perim = np.zeros(n, dtype=np.float64)
+ _raster_all_jit(rot_uv, uv_off, faces64, f_off, bw, bh, boff, buf,
+ int(padding_texels), tw, th_arr, perim)
+ if progress_callback is not None:
+ progress_callback(n, 2 * n)
+
+ order = np.argsort(-perim, kind="stable")
+ max_b = int(max(int(tw.max()), int(th_arr.max())))
+ margin = max_b + 8
+ side_guess = int(math.sqrt(float((tw * th_arr).sum()))) * 2 + 16
+ cap = side_guess + margin
+ atlas = np.zeros((cap, cap), dtype=np.bool_)
+ skyline = np.zeros(cap, dtype=np.int64)
+ rng = np.random.default_rng(rng_seed)
+ # shared random pool, sliced at a rotating offset per chart
+ pool = rng.integers(0, 1 << 31, size=(attempts * 8, 2)).astype(np.int64)
+ out_x = np.full(n, -1, dtype=np.int64)
+ out_y = np.full(n, -1, dtype=np.int64)
+ out_sw = np.zeros(n, dtype=np.int64)
+ cur_wh = np.zeros(2, dtype=np.int64)
+ start = 0
+ while start < n:
+ stop = min(n, start + 1024)
+ nxt = _place_all_jit(buf, boff, bw, tw, th_arr, order, start, stop,
+ atlas, skyline, pool, int(attempts), int(_SWEEP_CAP),
+ int(margin), int(_nb_threads()), cur_wh, out_x, out_y, out_sw)
+ if nxt < stop: # atlas must grow before this chart fits
+ ns = max(atlas.shape[0], int(cur_wh[1]) + margin, int(cur_wh[0]) + margin)
+ na = np.zeros((ns, ns), dtype=np.bool_)
+ na[:atlas.shape[0], :atlas.shape[1]] = atlas
+ atlas = na
+ nsk = np.zeros(ns, dtype=np.int64)
+ nsk[:skyline.shape[0]] = skyline
+ skyline = nsk
+ start = nxt
+ if progress_callback is not None:
+ progress_callback(n + start, 2 * n)
+ return out_x, out_y, out_sw, theta, scale, th_arr, int(cur_wh[0]), int(cur_wh[1])
+
+
+def apply_placements_concat(
+ uvs_cat: np.ndarray, uv_offsets: np.ndarray,
+ px: np.ndarray, py: np.ndarray, sw: np.ndarray,
+ theta: np.ndarray, scale: np.ndarray, chart_h: np.ndarray,
+ atlas_w: int, atlas_h: int,
+) -> np.ndarray:
+ """apply_placements over concatenated charts, fully vectorized. Returns (sumV, 2) float32."""
+ n = int(uv_offsets.shape[0]) - 1
+ side = float(max(atlas_w, atlas_h, 1))
+ cov = np.repeat(np.arange(n), np.diff(uv_offsets))
+ u_in = uvs_cat[:, 0].astype(np.float64)
+ v_in = uvs_cat[:, 1].astype(np.float64)
+ c = np.cos(theta)[cov]
+ s = np.sin(theta)[cov]
+ u = u_in * c - v_in * s
+ v = u_in * s + v_in * c
+ umin = np.full(n, np.inf)
+ vmin = np.full(n, np.inf)
+ np.minimum.at(umin, cov, u)
+ np.minimum.at(vmin, cov, v)
+ u = (u - umin[cov]) * scale[cov]
+ v = (v - vmin[cov]) * scale[cov]
+ swv = sw[cov].astype(bool)
+ # 90 deg rotation matching the rotated-bitmap access: (u, v) -> (chart_h - v, u)
+ u2 = np.where(swv, chart_h[cov] - v, u) + px[cov]
+ v2 = np.where(swv, u, v) + py[cov]
+ out = np.stack([u2, v2], axis=1) / side
+ np.clip(out, 0.0, 1.0, out=out) # slivers can stick sub-texel past extents
+ return out.astype(np.float32)
diff --git a/comfy_extras/mesh3d/uv_unwrap/parameterize.py b/comfy_extras/mesh3d/uv_unwrap/parameterize.py
new file mode 100644
index 000000000..383d21d8d
--- /dev/null
+++ b/comfy_extras/mesh3d/uv_unwrap/parameterize.py
@@ -0,0 +1,565 @@
+"""Chart parameterization: ortho PCA projection, falling back to ABF/LSCM."""
+from __future__ import annotations
+
+import warnings
+from typing import List, Tuple
+
+import numpy as np
+import scipy.sparse as sp
+import scipy.sparse.linalg as spla
+import torch
+from torch import Tensor
+
+from . import mesh as _mesh
+
+LSCM_BATCH_MAX_VERTS = 256 # charts above this solve per-chart sparse (lscm_chart)
+
+
+def solve_least_squares(A: sp.csr_matrix, b: np.ndarray) -> np.ndarray:
+ """Solve ||Ax - b||^2 by factorizing AtA."""
+ At = A.T.tocsr()
+ AtA = (At @ A).tocsc()
+ Atb = At @ b
+ return spla.spsolve(AtA, Atb)
+
+
+def _triangle_local_2d(verts_3d: np.ndarray, faces: np.ndarray) -> np.ndarray:
+ """Per-triangle 2D coords [F, 3, 2] with v0 at origin, v1 along +x."""
+ v0 = verts_3d[faces[:, 0]]
+ v1 = verts_3d[faces[:, 1]]
+ v2 = verts_3d[faces[:, 2]]
+ e01 = v1 - v0
+ e02 = v2 - v0
+ L01 = np.linalg.norm(e01, axis=1).clip(min=1e-20)
+ x_axis = e01 / L01[:, None]
+ n = np.cross(e01, e02)
+ n /= np.linalg.norm(n, axis=1, keepdims=True).clip(min=1e-20)
+ y_axis = np.cross(n, x_axis)
+
+ out = np.zeros((faces.shape[0], 3, 2), dtype=np.float64)
+ out[:, 1, 0] = L01
+ out[:, 2, 0] = (e02 * x_axis).sum(axis=1)
+ out[:, 2, 1] = (e02 * y_axis).sum(axis=1)
+ return out
+
+
+def _pick_pins(loops: List[List[int]], verts_3d: np.ndarray) -> Tuple[int, int]:
+ """Pick the longest-diameter axis-extremal boundary vertex pair across all boundary verts."""
+ if not loops:
+ # Closed surface: two far verts via two-pass farthest.
+ d2 = np.sum((verts_3d - verts_3d[0]) ** 2, axis=1)
+ a = int(np.argmax(d2))
+ d2 = np.sum((verts_3d - verts_3d[a]) ** 2, axis=1)
+ b = int(np.argmax(d2))
+ return a, b
+ boundary_verts: List[int] = []
+ for loop in loops:
+ boundary_verts.extend(loop)
+ seen = set()
+ uniq = []
+ for v in boundary_verts:
+ if v not in seen:
+ seen.add(v)
+ uniq.append(v)
+ bv = np.asarray(uniq, dtype=np.int64)
+ pts = verts_3d[bv]
+ pin_pairs = []
+ for axis in range(3):
+ i_min = int(bv[int(np.argmin(pts[:, axis]))])
+ i_max = int(bv[int(np.argmax(pts[:, axis]))])
+ d = float(np.linalg.norm(verts_3d[i_min] - verts_3d[i_max]))
+ pin_pairs.append((d, i_min, i_max))
+ d0, _, _ = pin_pairs[0]
+ d1, _, _ = pin_pairs[1]
+ d2, _, _ = pin_pairs[2]
+ if d0 > d1 and d0 > d2:
+ _, a, b = pin_pairs[0]
+ elif d1 > d2:
+ _, a, b = pin_pairs[1]
+ else:
+ _, a, b = pin_pairs[2]
+ return a, b
+
+
+def _ortho_project(verts_3d: np.ndarray) -> np.ndarray:
+ """PCA-fit plane normal, axis-aligned tangent, project verts to 2D."""
+ centroid = verts_3d.mean(axis=0)
+ pts = verts_3d - centroid
+ cov = pts.T @ pts
+ _w, ev = np.linalg.eigh(cov)
+ normal = ev[:, 0]
+ a = np.abs(normal)
+ if a[0] < a[1] and a[0] < a[2]:
+ t = np.array([1.0, 0.0, 0.0])
+ elif a[1] < a[2]:
+ t = np.array([0.0, 1.0, 0.0])
+ else:
+ t = np.array([0.0, 0.0, 1.0])
+ t = t - normal * float(np.dot(normal, t))
+ t /= max(float(np.linalg.norm(t)), 1e-20)
+ b = np.cross(normal, t)
+ return np.stack([verts_3d @ t, verts_3d @ b], axis=1)
+
+
+def ortho_project_concat(verts: np.ndarray, chart_of_vert: np.ndarray, n_charts: int) -> np.ndarray:
+ """_ortho_project for every chart at once over concatenated per-chart vertices."""
+ cnt = np.bincount(chart_of_vert, minlength=n_charts).clip(min=1).astype(np.float64)
+ cen = np.stack([np.bincount(chart_of_vert, weights=verts[:, i], minlength=n_charts)
+ for i in range(3)], axis=1) / cnt[:, None]
+ d = verts - cen[chart_of_vert]
+ cov = np.zeros((n_charts, 3, 3), dtype=np.float64)
+ for i in range(3):
+ for j in range(i, 3):
+ s = np.bincount(chart_of_vert, weights=d[:, i] * d[:, j], minlength=n_charts)
+ cov[:, i, j] = s
+ cov[:, j, i] = s
+ _w, ev = np.linalg.eigh(cov)
+ normal = ev[:, :, 0]
+ t = np.eye(3, dtype=np.float64)[np.argmin(np.abs(normal), axis=1)]
+ t = t - normal * (normal * t).sum(axis=1, keepdims=True)
+ t /= np.linalg.norm(t, axis=1, keepdims=True).clip(min=1e-20)
+ b = np.cross(normal, t)
+ tt, bb = t[chart_of_vert], b[chart_of_vert]
+ return np.stack([(verts * tt).sum(1), (verts * bb).sum(1)], axis=1)
+
+
+def stretch_metrics_concat(
+ verts: np.ndarray, uvs: np.ndarray, faces: np.ndarray,
+ chart_of_face: np.ndarray, n_charts: int,
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+ """Per-chart Sander stretch metrics (rms, max, n_flipped, n_zero_area); rms/max inf where undefined."""
+ p = verts[faces]
+ t = uvs[faces]
+ pa_signed = 0.5 * (
+ (t[:, 1, 1] - t[:, 0, 1]) * (t[:, 2, 0] - t[:, 0, 0])
+ - (t[:, 2, 1] - t[:, 0, 1]) * (t[:, 1, 0] - t[:, 0, 0]))
+ n_flip = np.bincount(chart_of_face[pa_signed < -1e-12], minlength=n_charts)
+ n_zero = np.bincount(chart_of_face[np.abs(pa_signed) < 1e-12], minlength=n_charts)
+ pa = np.abs(pa_signed).clip(min=1e-20)
+ ga = 0.5 * np.linalg.norm(np.cross(p[:, 1] - p[:, 0], p[:, 2] - p[:, 0]), axis=1)
+ keep = (ga > 1e-12) & (np.abs(pa_signed) > 1e-12)
+ t1, s1 = t[:, 0, 0], t[:, 0, 1]
+ t2, s2 = t[:, 1, 0], t[:, 1, 1]
+ t3, s3 = t[:, 2, 0], t[:, 2, 1]
+ inv_2pa = 1.0 / (2.0 * pa)
+ Ss = (p[:, 0] * (t2 - t3)[:, None] + p[:, 1] * (t3 - t1)[:, None]
+ + p[:, 2] * (t1 - t2)[:, None]) * inv_2pa[:, None]
+ St = (p[:, 0] * (s3 - s2)[:, None] + p[:, 1] * (s1 - s3)[:, None]
+ + p[:, 2] * (s2 - s1)[:, None]) * inv_2pa[:, None]
+ a = (Ss * Ss).sum(axis=1)
+ bb = (Ss * St).sum(axis=1)
+ c = (St * St).sum(axis=1)
+ sigma2_sq = 0.5 * (a + c + np.sqrt(np.maximum(0.0, (a - c) ** 2 + 4 * bb ** 2)))
+ rms_sq = (a + c) * 0.5
+ cf = chart_of_face[keep]
+ tg = np.bincount(cf, weights=ga[keep], minlength=n_charts)
+ tp = np.bincount(cf, weights=pa[keep], minlength=n_charts)
+ rs = np.bincount(cf, weights=(rms_sq * ga)[keep], minlength=n_charts)
+ smax = np.zeros(n_charts, dtype=np.float64)
+ np.maximum.at(smax, cf, sigma2_sq[keep])
+ ok = tg > 0.0
+ tg_safe = np.where(ok, tg, 1.0)
+ norm = np.sqrt(tp / tg_safe)
+ rms = np.where(ok, np.sqrt(rs / tg_safe) * norm, np.inf)
+ mx = np.where(ok, np.sqrt(smax) * norm, np.inf)
+ return rms, mx, n_flip, n_zero
+
+
+def _segment_argmax(vals: np.ndarray, seg: np.ndarray, n: int) -> np.ndarray:
+ """Index of the (first) max element per segment; -1 for empty segments."""
+ amax = np.full(n, -np.inf)
+ np.maximum.at(amax, seg, vals)
+ hit = vals == amax[seg]
+ out = np.full(n, np.iinfo(np.int64).max, dtype=np.int64)
+ np.minimum.at(out, seg[hit], np.nonzero(hit)[0])
+ return np.where(out == np.iinfo(np.int64).max, -1, out)
+
+
+def lscm_charts_batch(
+ verts: np.ndarray, # (sumV, 3) float64, per-chart concatenated
+ uv_pins: np.ndarray, # (sumV, 2) float64, ortho UVs (pin values + fallback)
+ faces_gl: np.ndarray, # (sumF, 3) global-local ids into verts
+ face_pos: np.ndarray, # (sumF,) row index of each face within its chart
+ chart_of_face: np.ndarray, # (sumF,)
+ chart_of_vert: np.ndarray, # (sumV,)
+ vert_offsets: np.ndarray, # (n_charts+1,)
+ chart_ids: np.ndarray, # charts to solve (each with >=3 verts, >=1 face)
+ n_charts: int,
+ max_bucket_verts: int = LSCM_BATCH_MAX_VERTS,
+ device: "torch.device | None" = None,
+) -> dict:
+ """Batched dense ABF/LSCM; returns {chart_id: (Vc, 2) float32}. Charts larger than
+ max_bucket_verts are left out (the caller solves those sparse)."""
+ out: dict = {}
+ if chart_ids.size == 0:
+ return out
+ sel = np.zeros(n_charts, dtype=bool)
+ sel[chart_ids] = True
+ vcounts = np.diff(vert_offsets)
+
+ # ABF coefficients for all selected faces in one shot
+ fmask = sel[chart_of_face]
+ f_ids = np.nonzero(fmask)[0]
+ abf_ids, abf_cos, abf_sin, abf_valid = _abf_face_coefficients(verts, faces_gl[f_ids])
+
+ # farthest-point pin pair per chart (two passes)
+ vmask = sel[chart_of_vert]
+ v_ids = np.nonzero(vmask)[0]
+ cv = chart_of_vert[v_ids]
+ first = vert_offsets[:-1]
+ d0 = ((verts[v_ids] - verts[first[cv]]) ** 2).sum(1)
+ pin_a = _segment_argmax(d0, cv, n_charts) # global vert index (into v_ids space)
+ pin_a = np.where(pin_a >= 0, v_ids[pin_a.clip(min=0)], -1)
+ d1 = ((verts[v_ids] - verts[pin_a.clip(min=0)[cv]]) ** 2).sum(1)
+ pin_b = _segment_argmax(d1, cv, n_charts)
+ pin_b = np.where(pin_b >= 0, v_ids[pin_b.clip(min=0)], -1)
+ # degenerate (all verts coincide): any distinct vert within the chart (Vc >= 3 guaranteed)
+ alt = np.where(pin_a == first, first + 1, first)
+ pin_b = np.where(pin_a == pin_b, alt, pin_b)
+
+ fcounts = np.bincount(chart_of_face[f_ids], minlength=n_charts)
+ # size-sorted chunks padded to their own max, bounded by an element budget so one
+ # face-heavy chart can't inflate a whole chunk
+ small = chart_ids[vcounts[chart_ids] <= max_bucket_verts]
+ sorted_ids = small[np.argsort(vcounts[small], kind="stable")]
+ budget = (96 << 20) // 8 # float64 elements in a chunk's A
+ chunks = []
+ cs = 0
+ fmax_r = vmax_r = 0
+ for idx in range(sorted_ids.size):
+ c2 = sorted_ids[idx]
+ fm2 = max(fmax_r, int(fcounts[c2]))
+ vm2 = max(vmax_r, int(vcounts[c2]))
+ nb = idx - cs + 1
+ if nb > 1 and (nb > 128 or nb * 4 * fm2 * vm2 > budget):
+ chunks.append((cs, idx))
+ cs = idx
+ fmax_r, vmax_r = int(fcounts[c2]), int(vcounts[c2])
+ else:
+ fmax_r, vmax_r = fm2, vm2
+ if sorted_ids.size:
+ chunks.append((cs, sorted_ids.size))
+ for s, e in chunks:
+ cids = sorted_ids[s:e]
+ B = cids.size
+ Vmax = int(vcounts[cids].max())
+ Fmax = int(fcounts[cids].max())
+ N = 2 * Vmax
+ R = 2 * Fmax
+ compact = np.full(n_charts, -1, dtype=np.int64)
+ compact[cids] = np.arange(B)
+ fm = compact[chart_of_face[f_ids]] >= 0
+ fi = f_ids[fm] # face rows for this chunk
+ bi = compact[chart_of_face[fi]] # chart slot per face
+ frow = face_pos[fi]
+ v0 = vert_offsets[chart_of_face[fi]] # local id = global-local - v0
+ am = fm.nonzero()[0] # index into abf_* arrays
+
+ pieces_i: list = []
+ pieces_v: list = []
+
+ def scatter(rows, cols, vals, bsel):
+ pieces_i.append((bsel * R + rows) * N + cols)
+ pieces_v.append(vals)
+
+ val = abf_valid[am]
+ ii = am[val]
+ ids = abf_ids[ii] - v0[val, None] # local vert ids, reordered
+ cosf, sinf = abf_cos[ii], abf_sin[ii]
+ rr, bsel = frow[val] * 2, bi[val]
+ ones = np.ones(ii.size)
+ for cc2, vv in ((ids[:, 0], cosf - 1.0), (ids[:, 0] + Vmax, -sinf),
+ (ids[:, 1], -cosf), (ids[:, 1] + Vmax, sinf), (ids[:, 2], ones)):
+ scatter(rr, cc2, vv, bsel)
+ for cc2, vv in ((ids[:, 0], sinf), (ids[:, 0] + Vmax, cosf - 1.0),
+ (ids[:, 1], -sinf), (ids[:, 1] + Vmax, -cosf), (ids[:, 2] + Vmax, ones)):
+ scatter(rr + 1, cc2, vv, bsel)
+
+ inv = ~val
+ if inv.any():
+ jj = fi[inv]
+ tri2d = _triangle_local_2d(verts, faces_gl[jj])
+ twice = tri2d[:, 1, 0] * tri2d[:, 2, 1] - tri2d[:, 1, 1] * tri2d[:, 2, 0]
+ w = 1.0 / np.sqrt(2.0 * np.abs(twice).clip(min=1e-20))
+ rr2, bs2 = frow[inv] * 2, bi[inv]
+ lids = faces_gl[jj] - v0[inv, None]
+ for j in range(3):
+ jp1, jp2 = (j + 1) % 3, (j + 2) % 3
+ aj = (tri2d[:, jp1, 0] - tri2d[:, jp2, 0]) * w
+ bj = (tri2d[:, jp1, 1] - tri2d[:, jp2, 1]) * w
+ vc2 = lids[:, j]
+ scatter(rr2, vc2, aj, bs2)
+ scatter(rr2, vc2 + Vmax, -bj, bs2)
+ scatter(rr2 + 1, vc2, bj, bs2)
+ scatter(rr2 + 1, vc2 + Vmax, aj, bs2)
+
+ flat = np.concatenate(pieces_i)
+ A = np.bincount(flat, weights=np.concatenate(pieces_v),
+ minlength=B * R * N).reshape(B, R, N)
+
+ # pins: move their columns to the RHS, then constrain via identity rows
+ voff = vert_offsets[cids]
+ pa_l = pin_a[cids] - voff
+ pb_l = pin_b[cids] - voff
+ pin_cols = np.stack([pa_l, pb_l, pa_l + Vmax, pb_l + Vmax], 1) # (B,4)
+ pin_vals = np.stack([uv_pins[pin_a[cids], 0], uv_pins[pin_b[cids], 0],
+ uv_pins[pin_a[cids], 1], uv_pins[pin_b[cids], 1]], 1)
+ rhs = np.zeros((B, R), dtype=np.float64)
+ barange = np.arange(B)
+ for k in range(4):
+ rhs -= A[barange, :, pin_cols[:, k]] * pin_vals[:, k, None]
+ A[barange, :, pin_cols[:, k]] = 0.0
+
+ # constrained columns: the 4 pins + padding beyond each chart's vert count
+ vcs = vcounts[cids]
+ padm = np.arange(Vmax)[None, :] >= vcs[:, None]
+ con = np.concatenate([padm, padm], axis=1) # (B,N)
+ np.put_along_axis(con, pin_cols, True, axis=1)
+ cval = np.zeros((B, N), dtype=np.float64)
+ np.put_along_axis(cval, pin_cols, pin_vals, axis=1)
+
+ # normal equations + batched solve; the fp64 dense algebra goes to the GPU when available
+ use_gpu = device is not None and device.type == "cuda"
+ if use_gpu:
+ A_t = torch.from_numpy(A).to(device)
+ At = A_t.transpose(1, 2)
+ AtA = At @ A_t
+ Atb = (At @ torch.from_numpy(rhs).to(device).unsqueeze(2)).squeeze(2)
+ con_t = torch.from_numpy(con).to(device)
+ free2 = (~con_t[:, :, None]) & (~con_t[:, None, :])
+ AtA = AtA * free2
+ diag = torch.diagonal(AtA, dim1=1, dim2=2)
+ # median (not max) positive diagonal: a degenerate face's ~1e19 squared row
+ # weight would blow a max-scaled eps past the unit ABF rows
+ dpos = torch.where(diag > 0, diag, torch.full_like(diag, float("nan")))
+ dsc = 1e-12 * torch.nan_to_num(dpos.nanmedian(dim=1).values, nan=1e-8).clamp_min(1e-20)
+ diag += torch.where(con_t, torch.ones_like(diag), dsc[:, None].expand_as(diag))
+ Atb = torch.where(con_t, torch.from_numpy(cval).to(device), Atb)
+ x = torch.linalg.solve(AtA, Atb).cpu().numpy()
+ else:
+ At = A.transpose(0, 2, 1)
+ AtA = At @ A # batched BLAS dgemm
+ Atb = (At @ rhs[:, :, None])[:, :, 0]
+ AtA *= (~con[:, :, None]) & (~con[:, None, :])
+ dg = AtA.reshape(B, -1)[:, ::N + 1]
+ # median positive diagonal (see GPU branch): robust to degenerate-face weights
+ dpos = np.where(dg > 0, dg, np.nan)
+ with np.errstate(all="ignore"):
+ dsc = 1e-12 * np.nan_to_num(np.nanmedian(dpos, axis=1), nan=1e-8).clip(min=1e-20)
+ dg += np.where(con, 1.0, dsc[:, None])
+ Atb2 = np.where(con, cval, Atb)
+ x = np.linalg.solve(AtA, Atb2[..., None])[..., 0]
+ for i2, c2 in enumerate(cids):
+ vc3 = int(vcs[i2])
+ out[int(c2)] = np.stack([x[i2, :vc3], x[i2, Vmax:Vmax + vc3]], 1).astype(np.float32)
+ return out
+
+
+def _uv_boundary_self_intersects(
+ uvs: np.ndarray, faces: np.ndarray, face_face: np.ndarray, eps: float = 1e-9
+) -> bool:
+ """True if any chart-boundary edge pair crosses in 2D (ortho folded the chart)."""
+ fi, ei = np.nonzero(face_face < 0)
+ n = fi.size
+ if n < 2:
+ return False
+ a = uvs[faces[fi, ei]].astype(np.float64)
+ b = uvs[faces[fi, (ei + 1) % 3]].astype(np.float64)
+ d = b - a
+ # Pairwise segment crossings, row-chunked to bound memory at chunk*n.
+ chunk = max(1, min(n, 1_000_000 // max(n, 1)))
+ for s in range(0, n, chunk):
+ e = min(s + chunk, n)
+ d1 = d[s:e, None, :]
+ denom = d1[:, :, 0] * d[None, :, 1] - d1[:, :, 1] * d[None, :, 0]
+ rx = a[None, :, 0] - a[s:e, None, 0]
+ ry = a[None, :, 1] - a[s:e, None, 1]
+ with np.errstate(divide="ignore", invalid="ignore"):
+ t = (rx * d[None, :, 1] - ry * d[None, :, 0]) / denom
+ u = (rx * d1[:, :, 1] - ry * d1[:, :, 0]) / denom
+ cross = (
+ (np.abs(denom) >= eps)
+ & (t > eps) & (t < 1.0 - eps)
+ & (u > eps) & (u < 1.0 - eps)
+ )
+ if bool(cross.any()):
+ return True
+ return False
+
+
+def _abf_face_coefficients(
+ verts_3d: np.ndarray, faces: np.ndarray
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+ """Per-face ABF constraint (largest-sine vertex at local index 2); returns (faces_reordered, cosine, sine, valid_mask) with valid_mask False for degenerate tris."""
+ p0 = verts_3d[faces[:, 0]]
+ p1 = verts_3d[faces[:, 1]]
+ p2 = verts_3d[faces[:, 2]]
+ e01 = p1 - p0
+ e12 = p2 - p1
+ e20 = p0 - p2
+ L01 = np.linalg.norm(e01, axis=1).clip(min=1e-20)
+ L12 = np.linalg.norm(e12, axis=1).clip(min=1e-20)
+ L20 = np.linalg.norm(e20, axis=1).clip(min=1e-20)
+ cos_a0 = ((-e20) * e01).sum(axis=1) / (L20 * L01)
+ cos_a1 = ((-e01) * e12).sum(axis=1) / (L01 * L12)
+ cos_a2 = ((-e12) * e20).sum(axis=1) / (L12 * L20)
+ cos_a0 = cos_a0.clip(-1.0, 1.0)
+ cos_a1 = cos_a1.clip(-1.0, 1.0)
+ cos_a2 = cos_a2.clip(-1.0, 1.0)
+ a = np.arccos(cos_a0)
+ b_ang = np.arccos(cos_a1)
+ c_ang = np.arccos(cos_a2)
+ angles = np.stack([a, b_ang, c_ang], axis=1)
+ sines = np.stack([np.sin(a), np.sin(b_ang), np.sin(c_ang)], axis=1)
+ valid = (angles > 1e-12).all(axis=1)
+ ids = faces.astype(np.int64).copy()
+
+ s0, s1, s2 = sines[:, 0], sines[:, 1], sines[:, 2]
+ pattA = (s1 > s0) & (s1 > s2)
+ pattB = (~pattA) & (s0 > s1) & (s0 > s2)
+
+ if pattA.any():
+ old_a = angles[pattA].copy()
+ old_s = sines[pattA].copy()
+ old_id = ids[pattA].copy()
+ angles[pattA] = old_a[:, [2, 0, 1]]
+ sines[pattA] = old_s[:, [2, 0, 1]]
+ ids[pattA] = old_id[:, [2, 0, 1]]
+ if pattB.any():
+ old_a = angles[pattB].copy()
+ old_s = sines[pattB].copy()
+ old_id = ids[pattB].copy()
+ angles[pattB] = old_a[:, [1, 2, 0]]
+ sines[pattB] = old_s[:, [1, 2, 0]]
+ ids[pattB] = old_id[:, [1, 2, 0]]
+
+ a0 = angles[:, 0]
+ s0 = sines[:, 0]
+ s1 = sines[:, 1]
+ s2 = sines[:, 2]
+ c0 = np.cos(a0)
+ ratio = np.where(s2 > 0.0, s1 / s2.clip(min=1e-20), 1.0)
+ cosine = c0 * ratio
+ sine = s0 * ratio
+ return ids, cosine, sine, valid
+
+
+def lscm_chart(
+ local_verts: Tensor,
+ local_faces: Tensor,
+ local_face_face: Tensor,
+ pin_positions: "np.ndarray | None" = None,
+) -> Tensor:
+ """ABF parameterization on one chart (degenerate faces use plain LSCM rows; two pins fix gauge at pin_positions)."""
+ verts_np = local_verts.detach().cpu().numpy().astype(np.float64)
+ faces_np = local_faces.detach().cpu().numpy().astype(np.int64)
+ Vc = verts_np.shape[0]
+ Fc = faces_np.shape[0]
+
+ if Vc < 3 or Fc == 0:
+ return torch.zeros((Vc, 2), dtype=torch.float32, device=local_verts.device)
+
+ loops = _mesh.chart_boundary_loops(local_faces, local_face_face)
+ pin_a, pin_b = _pick_pins(loops, verts_np)
+
+ if pin_positions is not None and pin_positions.shape == (Vc, 2):
+ pa = pin_positions[pin_a]
+ pb = pin_positions[pin_b]
+ u_a, v_a = float(pa[0]), float(pa[1])
+ u_b, v_b = float(pb[0]), float(pb[1])
+ else:
+ u_a, v_a = 0.0, 0.0
+ u_b, v_b = 1.0, 0.0
+
+ abf_ids, abf_cos, abf_sin, abf_valid = _abf_face_coefficients(verts_np, faces_np)
+
+ rows_list: List[np.ndarray] = []
+ cols_list: List[np.ndarray] = []
+ vals_list: List[np.ndarray] = []
+
+ # ABF rows for valid faces.
+ valid_idx = np.nonzero(abf_valid)[0]
+ if valid_idx.size:
+ Nv = valid_idx.size
+ id0 = abf_ids[valid_idx, 0]
+ id1 = abf_ids[valid_idx, 1]
+ id2 = abf_ids[valid_idx, 2]
+ cosf = abf_cos[valid_idx]
+ sinf = abf_sin[valid_idx]
+ r_real = valid_idx * 2
+ r_imag = valid_idx * 2 + 1
+ ones = np.ones(Nv, dtype=np.float64)
+ rows_list.extend([r_real] * 5)
+ cols_list.extend([id0, id0 + Vc, id1, id1 + Vc, id2])
+ vals_list.extend([cosf - 1.0, -sinf, -cosf, sinf, ones])
+ rows_list.extend([r_imag] * 5)
+ cols_list.extend([id0, id0 + Vc, id1, id1 + Vc, id2 + Vc])
+ vals_list.extend([sinf, cosf - 1.0, -sinf, -cosf, ones])
+
+ # Plain-LSCM rows for invalid (degenerate) faces.
+ invalid_idx = np.nonzero(~abf_valid)[0]
+ if invalid_idx.size:
+ tri2d_inv = _triangle_local_2d(verts_np, faces_np[invalid_idx])
+ twice_area_inv = (
+ tri2d_inv[:, 1, 0] * tri2d_inv[:, 2, 1]
+ - tri2d_inv[:, 1, 1] * tri2d_inv[:, 2, 0]
+ )
+ weight_inv = 1.0 / np.sqrt(2.0 * np.abs(twice_area_inv).clip(min=1e-20))
+ r_real_inv = invalid_idx * 2
+ r_imag_inv = invalid_idx * 2 + 1
+ for j in range(3):
+ jp1 = (j + 1) % 3
+ jp2 = (j + 2) % 3
+ a_j = (tri2d_inv[:, jp1, 0] - tri2d_inv[:, jp2, 0]) * weight_inv
+ b_j = (tri2d_inv[:, jp1, 1] - tri2d_inv[:, jp2, 1]) * weight_inv
+ v_idx = faces_np[invalid_idx, j]
+ rows_list.extend([r_real_inv, r_real_inv, r_imag_inv, r_imag_inv])
+ cols_list.extend([v_idx, v_idx + Vc, v_idx, v_idx + Vc])
+ vals_list.extend([a_j, -b_j, b_j, a_j])
+
+ rows = np.concatenate(rows_list) if rows_list else np.empty(0, dtype=np.int64)
+ cols = np.concatenate(cols_list) if cols_list else np.empty(0, dtype=np.int64)
+ vals = np.concatenate(vals_list) if vals_list else np.empty(0, dtype=np.float64)
+
+ A_full = sp.csr_matrix((vals, (rows, cols)), shape=(2 * Fc, 2 * Vc))
+
+ pin_cols = np.array([pin_a, pin_b, pin_a + Vc, pin_b + Vc], dtype=np.int64)
+ pin_vals = np.array([u_a, u_b, v_a, v_b], dtype=np.float64)
+
+ free_mask = np.ones(2 * Vc, dtype=bool)
+ free_mask[pin_cols] = False
+ free_cols = np.nonzero(free_mask)[0]
+
+ A_pinned = A_full[:, pin_cols]
+ A_free = A_full[:, free_cols]
+ b = -(A_pinned @ pin_vals)
+
+ # Singular system (under-constrained chart) falls back to ortho.
+ fallback_to_ortho = False
+ try:
+ with warnings.catch_warnings():
+ warnings.simplefilter("error", category=sp.linalg.MatrixRankWarning)
+ x_free = solve_least_squares(A_free, b)
+ if not np.all(np.isfinite(x_free)):
+ fallback_to_ortho = True
+ except (sp.linalg.MatrixRankWarning, RuntimeError):
+ fallback_to_ortho = True # singular / under-constrained system
+
+ if fallback_to_ortho:
+ if pin_positions is not None and pin_positions.shape == (Vc, 2):
+ uvs = pin_positions.astype(np.float32)
+ else:
+ uvs = _ortho_project(verts_np).astype(np.float32)
+ return torch.from_numpy(uvs).to(local_verts.device)
+
+ full = np.zeros(2 * Vc, dtype=np.float64)
+ full[free_cols] = x_free
+ full[pin_cols] = pin_vals
+ uvs = np.stack([full[:Vc], full[Vc:]], axis=1).astype(np.float32)
+ if not np.all(np.isfinite(uvs)):
+ if pin_positions is not None and pin_positions.shape == (Vc, 2):
+ uvs = pin_positions.astype(np.float32)
+ else:
+ uvs = _ortho_project(verts_np).astype(np.float32)
+
+ return torch.from_numpy(uvs).to(local_verts.device)
diff --git a/comfy_extras/mesh3d/uv_unwrap/segment.py b/comfy_extras/mesh3d/uv_unwrap/segment.py
new file mode 100644
index 000000000..8789b65d9
--- /dev/null
+++ b/comfy_extras/mesh3d/uv_unwrap/segment.py
@@ -0,0 +1,414 @@
+"""Adaptive cost-grow chart segmentation (vectorized torch, CPU or GPU)."""
+from __future__ import annotations
+
+from typing import Tuple
+
+import torch
+from torch import Tensor
+from tqdm import tqdm
+
+from .mesh import MeshData, face_edge_lengths
+
+
+DEFAULT_W_NORMAL_DEVIATION = 2.0
+DEFAULT_W_ROUNDNESS = 0.01
+DEFAULT_W_STRAIGHTNESS = 6.0
+DEFAULT_MAX_COST = 2.0
+NORMAL_DEVIATION_HARD_CUTOFF = 0.707 # ~75°
+
+
+def _grow_iter(face_chart, frontier, ff, fn, fa, fel, basis, nsum, area, perim, K,
+ nd_cutoff, tau, w_nd, w_round, w_straight):
+ """One grow pass: each frontier face joins its lowest-cost adjacent chart if cost <= tau;
+ returns the number of faces assigned."""
+ u = frontier.nonzero(as_tuple=True)[0]
+ if u.numel() == 0:
+ return 0
+ nb = ff[u] # (U,3) neighbor face ids
+ nbc = torch.where(nb >= 0, face_chart[nb.clamp_min(0)], nb.new_full((), -1))
+ valid = nbc >= 0
+ d = (fn[u][:, None, :] * basis[nbc.clamp_min(0)]).sum(-1)
+ nd = (1.0 - d).clamp(0.0, 1.0)
+ valid &= nd < nd_cutoff
+ el = fel[u] # (U,3)
+ # l_in per candidate chart j: edge k counts if its (assigned) neighbor is in chart j
+ inm = (nbc[:, :, None] == nbc[:, None, :]) & valid[:, None, :]
+ l_in = (el[:, None, :] * inm).sum(-1) # (U,3)
+ tot = el.sum(-1, keepdim=True)
+ l_out = tot - l_in
+ ca = area[nbc.clamp_min(0)]
+ cp = perim[nbc.clamp_min(0)]
+ new_perim = cp - l_in + l_out
+ new_r = new_perim * new_perim / (ca + fa[u][:, None]).clamp_min(1e-20)
+ round_cost = torch.where((cp <= 1e-20) | (ca <= 1e-20) | (new_r <= 1e-20),
+ torch.zeros_like(new_r),
+ 1.0 - (cp * cp / ca.clamp_min(1e-20)) / new_r.clamp_min(1e-20))
+ straight_cost = ((l_out - l_in) / tot.clamp_min(1e-20)).clamp(max=0.0)
+ cost = w_nd * nd + w_round * round_cost + w_straight * straight_cost
+ cost = torch.where(valid, cost, cost.new_full((), float("inf")))
+ best_cost, best_j = cost.min(1)
+ acc = best_cost <= tau
+ n_acc = int(acc.sum())
+ if n_acc == 0:
+ return 0
+
+ f_acc = u[acc]
+ c_acc = nbc.gather(1, best_j[:, None]).squeeze(1)[acc]
+ nbc_old = nbc[acc] # neighbor charts before this commit
+ face_chart[f_acc] = c_acc
+ nb_acc = nb[acc]
+ nbs_acc = nb_acc.clamp_min(0)
+ nbc_post = torch.where(nb_acc >= 0, face_chart[nbs_acc], nb_acc.new_full((), -1))
+ # frontier update: committed faces leave; their still-unassigned neighbors enter
+ frontier[f_acc] = False
+ grow_nb = nbs_acc[(nb_acc >= 0) & (nbc_post < 0)]
+ frontier[grow_nb] = True
+ el_acc = el[acc]
+ cx = c_acc[:, None]
+ dper = torch.where(nbc_old == cx, -el_acc, # was member: edge turns interior
+ torch.where(nbc_post == cx, torch.zeros_like(el_acc), # co-committer
+ el_acc)).sum(1) # boundary / other chart
+ perim.scatter_add_(0, c_acc, dper)
+ area.scatter_add_(0, c_acc, fa[f_acc])
+ nsum.index_add_(0, c_acc, fn[f_acc] * fa[f_acc, None])
+ nl = nsum[:K].norm(dim=1, keepdim=True)
+ basis[:K] = torch.where(nl > 1e-20, nsum[:K] / nl.clamp_min(1e-20), basis[:K])
+ return n_acc
+
+
+def segment_charts(
+ mesh: MeshData,
+ max_cost: float = DEFAULT_MAX_COST,
+ w_normal_deviation: float = DEFAULT_W_NORMAL_DEVIATION,
+ w_roundness: float = DEFAULT_W_ROUNDNESS,
+ w_straightness: float = DEFAULT_W_STRAIGHTNESS,
+ progress_callback=None,
+) -> Tensor:
+ """Segment mesh into charts (parallel batch cost-grow). Returns face -> chart_id."""
+ F = mesh.faces.shape[0]
+ device = mesh.faces.device
+ if F == 0:
+ return torch.zeros(0, dtype=torch.long, device=device)
+
+ fn = mesh.face_normal.detach().to(torch.float32)
+ fa = mesh.face_area.detach().to(torch.float32)
+ fc = mesh.face_centroid.detach().to(torch.float32)
+ ff = mesh.face_face.detach().long()
+ fel = face_edge_lengths(mesh.vertices, mesh.faces).detach().to(torch.float32)
+ nd_cutoff = NORMAL_DEVIATION_HARD_CUTOFF
+
+ # one seed per connected component (first face of each)
+ comp = mesh.component.detach().long().to(device)
+ ncomp = int(comp.max()) + 1 if comp.numel() else 0
+ if ncomp:
+ seeds = torch.full((ncomp,), F, dtype=torch.long, device=device)
+ seeds.scatter_reduce_(0, comp, torch.arange(F, device=device), reduce="amin")
+ else:
+ seeds = torch.zeros(1, dtype=torch.long, device=device)
+ K = seeds.shape[0]
+
+ max_total_charts = max(F, 8000)
+ cap = K + F + 1 # every re-seed assigns a face, so K < K0 + F
+ face_chart = torch.full((F,), -1, dtype=torch.long, device=device)
+ basis = torch.zeros(cap, 3, dtype=torch.float32, device=device)
+ nsum = torch.zeros(cap, 3, dtype=torch.float32, device=device)
+ area = torch.zeros(cap, dtype=torch.float32, device=device)
+ perim = torch.zeros(cap, dtype=torch.float32, device=device)
+ face_chart[seeds] = torch.arange(K, device=device)
+ basis[:K] = fn[seeds]
+ nsum[:K] = fn[seeds] * fa[seeds, None]
+ area[:K] = fa[seeds]
+ perim[:K] = fel[seeds].sum(1)
+ frontier = torch.zeros(F, dtype=torch.bool, device=device)
+ seed_nb = ff[seeds]
+ seed_nb = seed_nb[seed_nb >= 0]
+ frontier[seed_nb] = True
+ frontier &= face_chart < 0
+
+ min_d2 = torch.full((F,), float("inf"), dtype=torch.float32, device=device)
+ for i in range(0, K, 32): # chunked: (F, <=32, 3) stays small
+ d2 = ((fc[:, None, :] - fc[seeds[i:i + 32]][None, :, :]) ** 2).sum(-1)
+ min_d2 = torch.minimum(min_d2, d2.amin(1))
+
+ # Multi-pass threshold schedule (low-cost first); tau cap 0.5 keeps cones ~30deg.
+ tau_final = min(max_cost * 0.25, 0.5)
+ thresholds = [t for t in (0.05, 0.1, 0.25) if t < tau_final] + [tau_final]
+ max_inner = max(64, int(F ** 0.5) * 2)
+ outer_iter = 0
+ assigned = 0
+ tq = tqdm(total=F, desc="unwrap: segment (adaptive)", unit="face", leave=False)
+ while True:
+ outer_iter += 1
+ if outer_iter > F + 16:
+ break
+ for tau in thresholds:
+ for _ in range(max_inner):
+ n_added = _grow_iter(face_chart, frontier, ff, fn, fa, fel, basis, nsum,
+ area, perim, K, nd_cutoff, tau, w_normal_deviation,
+ w_roundness, w_straightness)
+ if n_added == 0:
+ break
+ tq.update(n_added)
+ assigned += n_added
+ if progress_callback is not None:
+ progress_callback(assigned, F)
+ unassigned = face_chart < 0
+ if int(unassigned.sum()) == 0:
+ break
+ if K >= max_total_charts:
+ break
+ # re-seed at the unassigned face farthest from every existing seed
+ new_seed = int(torch.where(unassigned, min_d2,
+ min_d2.new_full((), float("-inf"))).argmax())
+ face_chart[new_seed] = K
+ basis[K] = fn[new_seed]
+ nsum[K] = fn[new_seed] * fa[new_seed]
+ area[K] = fa[new_seed]
+ perim[K] = fel[new_seed].sum()
+ K += 1
+ min_d2 = torch.minimum(min_d2, ((fc - fc[new_seed]) ** 2).sum(-1))
+ tq.update(1)
+ frontier[new_seed] = False
+ ns_nb = ff[new_seed]
+ ns_nb = ns_nb[ns_nb >= 0]
+ frontier[ns_nb[face_chart[ns_nb] < 0]] = True
+
+ tq.close()
+
+ # Orphan cleanup: leftover faces join their best-matching neighbor's chart.
+ while True:
+ orphans = (face_chart < 0).nonzero(as_tuple=True)[0]
+ if orphans.numel() == 0:
+ break
+ nb = ff[orphans]
+ nbc = torch.where(nb >= 0, face_chart[nb.clamp_min(0)], nb.new_full((), -1))
+ valid = nbc >= 0
+ assignable = valid.any(1)
+ if not bool(assignable.any()):
+ break
+ d = (fn[orphans][:, None, :] * basis[nbc.clamp_min(0)]).sum(-1)
+ ndv = torch.where(valid, 1.0 - d, d.new_full((), float("inf")))
+ best_c = nbc.gather(1, ndv.argmin(1, keepdim=True)).squeeze(1)
+ face_chart[orphans[assignable]] = best_c[assignable]
+ leftover = (face_chart < 0).nonzero(as_tuple=True)[0]
+ if leftover.numel(): # isolated faces become singleton charts
+ face_chart[leftover] = K + torch.arange(leftover.numel(), device=device)
+
+ _, inverse = torch.unique(face_chart, sorted=True, return_inverse=True)
+ return inverse
+
+
+# Parallel edge-collapse (PEC) chart clustering (GPU)
+def _combine_normal_cones(
+ axis_a: Tensor, half_a: Tensor,
+ axis_b: Tensor, half_b: Tensor,
+) -> Tuple[Tensor, Tensor, Tensor]:
+ """Merge two normal cones along the great circle from axis_a; returns (combined_axis, combined_half_angle, axis_angle)."""
+ cos_angle = (axis_a * axis_b).sum(dim=-1).clamp(-1.0, 1.0)
+ axis_angle = torch.acos(cos_angle)
+ new_low = torch.minimum(-half_a, axis_angle - half_b)
+ new_high = torch.maximum(half_a, axis_angle + half_b)
+ new_half = (new_high - new_low) * 0.5
+ rot_angle = (new_high + new_low) * 0.5
+ b_perp = axis_b - axis_a * cos_angle.unsqueeze(-1)
+ b_perp_norm = b_perp.norm(dim=-1, keepdim=True).clamp_min(1e-12)
+ b_perp_unit = b_perp / b_perp_norm
+ new_axis = (
+ axis_a * torch.cos(rot_angle).unsqueeze(-1)
+ + b_perp_unit * torch.sin(rot_angle).unsqueeze(-1)
+ )
+ new_axis_norm = new_axis.norm(dim=-1, keepdim=True).clamp_min(1e-12)
+ new_axis = new_axis / new_axis_norm
+ return new_axis, new_half, axis_angle
+
+
+def _build_chart_edges(
+ face_face: Tensor,
+ chart_id: Tensor,
+ face_edge_len: Tensor,
+) -> Tuple[Tensor, Tensor]:
+ """Build chart-edge list (chart_pairs[E,2] with a<b, edge_length[E]); same-chart edges dropped, duplicates summed."""
+ F = face_face.shape[0]
+ device = face_face.device
+ f_idx = torch.arange(F, device=device).repeat_interleave(3)
+ nb = face_face.flatten()
+ valid = nb >= 0
+ f_idx = f_idx[valid]
+ nb = nb[valid]
+ el = face_edge_len.flatten()[valid]
+
+ ca = chart_id[f_idx]
+ cb = chart_id[nb]
+ diff = ca != cb
+ ca = ca[diff]
+ cb = cb[diff]
+ el = el[diff]
+ if ca.numel() == 0:
+ return (
+ torch.empty((0, 2), dtype=torch.long, device=device),
+ torch.empty(0, device=device),
+ )
+
+ lo = torch.minimum(ca, cb)
+ hi = torch.maximum(ca, cb)
+ V = int(chart_id.max().item()) + 1
+ key = lo * V + hi
+ sort_idx = torch.argsort(key)
+ sorted_key = key[sort_idx]
+ sorted_lo = lo[sort_idx]
+ sorted_hi = hi[sort_idx]
+ sorted_el = el[sort_idx]
+ unique_key, inverse, counts = torch.unique(
+ sorted_key, return_inverse=True, return_counts=True
+ )
+ n_unique = unique_key.shape[0]
+ reduced_el = torch.zeros(n_unique, device=device, dtype=el.dtype)
+ reduced_el.scatter_add_(0, inverse, sorted_el)
+ first_idx = torch.cat([
+ torch.zeros(1, dtype=torch.long, device=device),
+ counts.cumsum(0)[:-1],
+ ])
+ pair_lo = sorted_lo[first_idx]
+ pair_hi = sorted_hi[first_idx]
+ chart_pairs = torch.stack([pair_lo, pair_hi], dim=1)
+ return chart_pairs, reduced_el
+
+
+def _merge_small_charts(
+ chart_id: Tensor, face_normal: Tensor, face_area: Tensor,
+ face_face: Tensor, face_edge_len: Tensor,
+ min_faces: int, cost_cap: float,
+) -> Tensor:
+ """Absorb charts under min_faces faces into their lowest-cone-cost neighbor (capped at cost_cap)."""
+ if chart_id.numel() == 0:
+ return chart_id
+ device = chart_id.device
+ for _ in range(16):
+ N = int(chart_id.max().item()) + 1
+ sizes = torch.bincount(chart_id, minlength=N)
+ # recompute cones from scratch: area-weighted mean axis, max deviation as half-angle
+ axis = torch.zeros(N, 3, dtype=torch.float32, device=device)
+ axis.index_add_(0, chart_id, face_normal * face_area[:, None])
+ axis = axis / axis.norm(dim=1, keepdim=True).clamp_min(1e-12)
+ dev = torch.acos((face_normal * axis[chart_id]).sum(1).clamp(-1.0, 1.0))
+ half = torch.zeros(N, dtype=torch.float32, device=device)
+ half.scatter_reduce_(0, chart_id, dev, reduce="amax")
+
+ edges, _ = _build_chart_edges(face_face, chart_id, face_edge_len)
+ if edges.shape[0] == 0:
+ break
+ a, b = edges[:, 0], edges[:, 1]
+ _, new_half, _ = _combine_normal_cones(axis[a], half[a], axis[b], half[b])
+ ok = new_half <= cost_cap
+ E = edges.shape[0]
+ key = (torch.clamp(new_half * 1e6, max=2e9).to(torch.int64) << 32) \
+ | torch.arange(E, dtype=torch.long, device=device)
+ best = torch.full((N,), 1 << 62, dtype=torch.long, device=device)
+ va = (sizes[a] < min_faces) & ok
+ vb = (sizes[b] < min_faces) & ok
+ best.scatter_reduce_(0, a[va], key[va], reduce="amin")
+ best.scatter_reduce_(0, b[vb], key[vb], reduce="amin")
+ src = (best < (1 << 62)).nonzero(as_tuple=True)[0]
+ if src.numel() == 0:
+ break
+ eid = best[src] & 0xFFFFFFFF
+ ea, eb = a[eid], b[eid]
+ tgt = torch.where(ea == src, eb, ea)
+ # cycle break: keep src->tgt only if tgt merges nowhere itself or src > tgt;
+ # the kept graph is then a DAG, so the pointer-doubling below terminates
+ prop = torch.arange(N, dtype=torch.long, device=device)
+ prop[src] = tgt
+ keepm = (prop[tgt] == tgt) | (src > tgt)
+ remap = torch.arange(N, dtype=torch.long, device=device)
+ remap[src[keepm]] = tgt[keepm]
+ for _ in range(32):
+ nr = remap[remap]
+ if torch.equal(nr, remap):
+ break
+ remap = nr
+ chart_id = remap[chart_id]
+ _, chart_id = torch.unique(chart_id, return_inverse=True)
+ return chart_id
+
+
+def cluster_charts_pec(
+ mesh: MeshData,
+ max_cost: float = 0.7,
+ max_iters: int = 1024,
+ min_faces: int = 8,
+ progress_callback=None,
+) -> Tensor:
+ """Parallel edge-collapse clustering; returns face_chart [F]. max_cost is the per-merge
+ cutoff (~0.7 rad ~ 40deg); charts under min_faces are then absorbed at a relaxed 2x cutoff."""
+ device = mesh.faces.device
+ F = mesh.faces.shape[0]
+ faces = mesh.faces.to(torch.long)
+ vertices = mesh.vertices.to(torch.float32)
+ face_normal = mesh.face_normal.to(torch.float32)
+ face_face = mesh.face_face.to(torch.long)
+
+ face_edge_len = face_edge_lengths(vertices, faces)
+
+ chart_id = torch.arange(F, dtype=torch.long, device=device)
+ chart_axis = face_normal.clone()
+ chart_half = torch.zeros(F, dtype=torch.float32, device=device)
+
+ for it in range(max_iters):
+ edges, _ = _build_chart_edges(face_face, chart_id, face_edge_len)
+ if edges.shape[0] == 0:
+ break
+
+ a = edges[:, 0]
+ b = edges[:, 1]
+ axis_a = chart_axis[a]
+ axis_b = chart_axis[b]
+ half_a = chart_half[a]
+ half_b = chart_half[b]
+ _, new_half, _ = _combine_normal_cones(axis_a, half_a, axis_b, half_b)
+ cost = new_half.clone()
+
+ # Pack (cost, edge_id) so scatter_reduce amin picks the right edge.
+ E = edges.shape[0]
+ N = int(chart_id.max().item()) + 1
+ edge_ids = torch.arange(E, dtype=torch.long, device=device)
+ cost_i32 = torch.clamp(cost * 1e6, max=2e9).to(torch.int64)
+ key = (cost_i32 << 32) | edge_ids
+ chart_min = torch.full((N,), (2**62), dtype=torch.long, device=device)
+ chart_min.scatter_reduce_(0, a, key, reduce="amin", include_self=True)
+ chart_min.scatter_reduce_(0, b, key, reduce="amin", include_self=True)
+
+ # Mutual-min collapse: each chart in at most one merge per iter (winners are disjoint pairs).
+ is_a_min = chart_min[a] == key
+ is_b_min = chart_min[b] == key
+ mutual = is_a_min & is_b_min
+ within = cost <= max_cost
+ winners = mutual & within
+
+ n_merge = int(winners.sum().item())
+ if n_merge == 0:
+ break
+ if progress_callback is not None:
+ progress_callback(F - N + n_merge, F) # saturating: charts remaining vs faces
+
+ win_a = a[winners]
+ win_b = b[winners]
+
+ axis_a_w = chart_axis[win_a]
+ half_a_w = chart_half[win_a]
+ axis_b_w = chart_axis[win_b]
+ half_b_w = chart_half[win_b]
+ new_axis, new_half_w, _ = _combine_normal_cones(
+ axis_a_w, half_a_w, axis_b_w, half_b_w,
+ )
+ chart_axis[win_a] = new_axis
+ chart_half[win_a] = new_half_w
+
+ remap = torch.arange(N, dtype=torch.long, device=device)
+ remap[win_b] = win_a
+ chart_id = remap[chart_id]
+
+ if min_faces > 1:
+ chart_id = _merge_small_charts(chart_id, face_normal, mesh.face_area.to(torch.float32),
+ face_face, face_edge_len, min_faces, 2.0 * max_cost)
+ _, inverse = torch.unique(chart_id, sorted=True, return_inverse=True)
+ return inverse
diff --git a/comfy_extras/nodes_images.py b/comfy_extras/nodes_images.py
index 7011d9c13..46d1eb79b 100644
--- a/comfy_extras/nodes_images.py
+++ b/comfy_extras/nodes_images.py
@@ -10,6 +10,7 @@ import math
import numpy as np
import struct
import torch
+import logging
import zlib
import comfy.utils
@@ -89,6 +90,149 @@ class ImageCropV2(IO.ComfyNode):
return IO.NodeOutput(img, ui=UI.PreviewImage(img))
+def _crop_image_with_mask(item_image, item_mask, max_image_size=1024, pad_factor=1.1,
+ mask_offset=0, mask_threshold=0.05, bg_rgb=(0.0, 0.0, 0.0),
+ aspect_ratio=1.0):
+ img = item_image.permute(2, 0, 1).unsqueeze(0).cpu().float().clamp(0, 1)
+ mask = item_mask.unsqueeze(0).unsqueeze(0).cpu().float().clamp(0, 1)
+
+ # Detect and correct an inverted mask, only when border and center have opposite polarity.
+ m2d = mask[0, 0]
+ h, w = m2d.shape
+ border = torch.cat([m2d[0, :], m2d[-1, :], m2d[:, 0], m2d[:, -1]])
+ center = m2d[h // 4:h - h // 4, w // 4:w - w // 4]
+ if float(border.mean()) > 0.5 and float(center.mean()) < 0.5:
+ mask = 1.0 - mask
+
+ if mask_offset > 0:
+ r = mask_offset
+ mask = torch.nn.functional.max_pool2d(mask, kernel_size=2 * r + 1, stride=1, padding=r)
+ elif mask_offset < 0:
+ r = -mask_offset
+ mask = 1.0 - torch.nn.functional.max_pool2d(1.0 - mask, kernel_size=2 * r + 1, stride=1, padding=r)
+
+ if mask_threshold > 0.0:
+ mask = torch.where(mask < mask_threshold, torch.zeros_like(mask), mask)
+
+ H, W = img.shape[-2:]
+ if max(H, W) > max_image_size:
+ scale = max_image_size / max(H, W)
+ new_w, new_h = int(W * scale), int(H * scale)
+ img = comfy.utils.common_upscale(img, new_w, new_h, "lanczos", "disabled")
+ mask = comfy.utils.common_upscale(mask, new_w, new_h, "lanczos", "disabled")
+ # common_upscale's lanczos path drops the singleton channel dim for masks (utils.py:1062).
+ if mask.ndim == 3:
+ mask = mask.unsqueeze(1)
+ H, W = new_h, new_w
+ scene_size = (W, H)
+
+ alpha_u8 = (mask[0, 0].clamp(0, 1) * 255.0).to(torch.uint8)
+ fg_pixels = (alpha_u8 > 204).nonzero()
+ if fg_pixels.numel() == 0:
+ # Try the inverted mask — auto-invert above may have been too conservative.
+ inv_fg = ((255 - alpha_u8) > 204).nonzero()
+ if inv_fg.numel() > 0:
+ logging.info("Trellis2 preprocess: mask bbox empty, using inverted mask.")
+ mask = 1.0 - mask
+ fg_pixels = inv_fg
+ if fg_pixels.numel() > 0:
+ y_min, x_min = fg_pixels.min(dim=0).values.tolist()
+ y_max, x_max = fg_pixels.max(dim=0).values.tolist()
+ center_y, center_x = (y_min + y_max) / 2.0, (x_min + x_max) / 2.0
+ bw = x_max - x_min + 1
+ bh = y_max - y_min + 1
+ # Grow the bbox so its aspect matches `aspect_ratio` (width/height),
+ # anchored on the max side. Then apply pad_factor.
+ if bw / max(bh, 1) >= aspect_ratio:
+ crop_w = int(bw * pad_factor)
+ crop_h = int(bw / aspect_ratio * pad_factor)
+ else:
+ crop_h = int(bh * pad_factor)
+ crop_w = int(bh * aspect_ratio * pad_factor)
+ half_w, half_h = math.ceil(crop_w / 2), math.ceil(crop_h / 2)
+ crop_x1 = int(center_x - half_w)
+ crop_y1 = int(center_y - half_h)
+ crop_x2 = crop_x1 + 2 * half_w
+ crop_y2 = crop_y1 + 2 * half_h
+ else:
+ logging.warning("Mask for the image is empty; a clean foreground mask is required for best quality.")
+ crop_x1, crop_y1, crop_x2, crop_y2 = 0, 0, W, H
+ crop_bbox = (crop_x1, crop_y1, crop_x2, crop_y2)
+
+ # Zero-pad out-of-bounds slice (PIL.crop semantics).
+ pad_l = max(0, -crop_x1)
+ pad_t = max(0, -crop_y1)
+ pad_r = max(0, crop_x2 - W)
+ pad_b = max(0, crop_y2 - H)
+ if pad_l or pad_t or pad_r or pad_b:
+ img = torch.nn.functional.pad(img, (pad_l, pad_r, pad_t, pad_b), value=0.0)
+ mask = torch.nn.functional.pad(mask, (pad_l, pad_r, pad_t, pad_b), value=0.0)
+ crop_x1 += pad_l
+ crop_x2 += pad_l
+ crop_y1 += pad_t
+ crop_y2 += pad_t
+ cropped_img = img [..., crop_y1:crop_y2, crop_x1:crop_x2]
+ cropped_mask = mask[..., crop_y1:crop_y2, crop_x1:crop_x2]
+
+ bg = torch.tensor(bg_rgb, dtype=cropped_img.dtype, device=cropped_img.device).view(1, 3, 1, 1)
+ composite = (cropped_img * cropped_mask + bg * (1.0 - cropped_mask)).clamp(0, 1)
+ return composite, crop_bbox, scene_size
+
+
+class ImageCropToMask(IO.ComfyNode):
+ """Crop an image to its mask's bounding box (centered square, with pad_factor
+ margin), then composite `img * mask` and resize to a square. Handles OOB crops
+ with zero-padding. Useful for 3D pipelines that expect a centered, background-free
+ subject at a fixed input resolution (Trellis2, Pixal3D, Hunyuan3D, TripoSR, etc.)."""
+
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="ImageCropToMask",
+ display_name="Crop Image to Mask",
+ category="image/transform",
+ search_aliases=["crop to mask", "mask crop", "crop mask", "mask crop resize", "crop mask resize", "trellis2", "pixal3d"],
+ inputs=[
+ IO.Image.Input("images"),
+ IO.Mask.Input("masks"),
+ IO.Int.Input("width", default=1024, min=64, max=4096, step=8, tooltip="Output width in pixels."),
+ IO.Int.Input("height", default=1024, min=64, max=4096, step=8, tooltip="Output height in pixels."),
+ IO.Float.Input("pad_factor", default=1.0, min=1.0, max=2.0, step=0.01, tooltip="Extra margin around the mask bounding box as a multiplier."),
+ IO.Int.Input("grow_mask", default=0, min=-32, max=32, step=1, tooltip="Grow or shrink the mask by this many pixels before cropping."),
+ IO.Color.Input("background", default="#000000", tooltip="Background color behind the masked subject."),
+ ],
+ outputs=[IO.Image.Output(display_name="images")],
+ )
+
+ @classmethod
+ def execute(cls, images, masks, width, height, pad_factor, grow_mask, background) -> IO.NodeOutput:
+ h = background.lstrip("#")
+ bg_rgb = (int(h[0:2], 16) / 255.0, int(h[2:4], 16) / 255.0, int(h[4:6], 16) / 255.0) if len(h) == 6 else (0.0, 0.0, 0.0)
+ images = images[..., :3]
+ batch_size = images.shape[0]
+ if masks.shape[0] == 1 and batch_size > 1:
+ masks = masks.expand(batch_size, -1, -1)
+ elif masks.shape[0] != batch_size:
+ raise ValueError(f"Mask batch {masks.shape[0]} does not match image batch {batch_size}")
+ if masks.shape[-2:] != images.shape[1:3]:
+ masks = comfy.utils.common_upscale(masks.unsqueeze(1).float(), images.shape[2], images.shape[1], "bilinear", "disabled").squeeze(1)
+
+ out_images = []
+ for b in range(batch_size):
+ composite, _, _ = _crop_image_with_mask(
+ images[b], masks[b], max_image_size=max(width, height), pad_factor=pad_factor,
+ mask_offset=grow_mask, bg_rgb=bg_rgb, aspect_ratio=width / height,
+ )
+ composite = comfy.utils.common_upscale(composite, width, height, "lanczos", "disabled")
+ out_images.append(composite.movedim(-3, -1))
+
+ result = torch.cat(out_images, dim=0).to(
+ device=comfy.model_management.intermediate_device(),
+ dtype=comfy.model_management.intermediate_dtype(),
+ )
+ return IO.NodeOutput(result)
+
+
class BoundingBox(IO.ComfyNode):
@classmethod
def define_schema(cls):
@@ -1244,6 +1388,7 @@ class ImagesExtension(ComfyExtension):
return [
ImageCrop,
ImageCropV2,
+ ImageCropToMask,
BoundingBox,
RepeatImageBatch,
ImageFromBatch,
diff --git a/comfy_extras/nodes_mesh_postprocess.py b/comfy_extras/nodes_mesh_postprocess.py
new file mode 100644
index 000000000..99725efd5
--- /dev/null
+++ b/comfy_extras/nodes_mesh_postprocess.py
@@ -0,0 +1,3114 @@
+import torch
+import numpy as np
+import math
+from typing_extensions import override
+from comfy_api.latest import ComfyExtension, IO, Types
+import copy
+import comfy.utils
+import comfy.model_management
+from server import PromptServer
+from comfy_extras.mesh3d.postprocess.qem_decimate import QEMConfig, qem_decimate_simplify, qem_cluster_decimate, _compute_vertex_normals
+from comfy_extras.mesh3d.postprocess.remesh import remesh_narrow_band_dc, _point_tri_closest
+from comfy_extras.nodes_save_3d import get_mesh_batch_item, pack_variable_mesh_batch
+from comfy_extras.mesh3d.uv_unwrap import mesh as _uv_mesh
+from comfy_extras.mesh3d.uv_unwrap import segment as _uv_seg
+from comfy_extras.mesh3d.uv_unwrap import parameterize as _uv_param
+from comfy_extras.mesh3d.uv_unwrap import pack as _uv_pack
+import logging
+import time
+from tqdm import tqdm
+from scipy.sparse import csr_matrix
+from scipy.sparse.csgraph import connected_components
+from scipy.spatial import cKDTree
+import scipy.ndimage as ndi
+
+
+def paint_mesh_with_voxels(mesh, voxel_coords, voxel_colors, resolution):
+ """Paint a mesh using nearest-neighbor colors from a sparse voxel field."""
+ device = comfy.model_management.vae_offload_device()
+
+ origin = torch.tensor([-0.5, -0.5, -0.5], device=device)
+ voxel_size = 1.0 / resolution
+
+ voxel_pos = voxel_coords.to(device).float() * voxel_size + origin
+ verts = mesh.vertices.to(device).squeeze(0)
+ voxel_colors = voxel_colors.to(device)
+
+ voxel_pos_np = voxel_pos.cpu().numpy()
+ verts_np = verts.cpu().numpy()
+
+ tree = cKDTree(voxel_pos_np)
+ _, nearest_idx_np = tree.query(verts_np, k=1, workers=-1)
+
+ nearest_idx = torch.from_numpy(nearest_idx_np).long().to(voxel_colors.device)
+ v_colors = voxel_colors[nearest_idx]
+ # Voxel field may carry full PBR; vertex colors use only base_color RGB.
+ if v_colors.shape[-1] > 3:
+ v_colors = v_colors[:, :3]
+
+ srgb_colors = v_colors.clamp(0, 1)
+
+ # to Linear RGB (required for GLTF)
+ linear_colors = torch.pow(srgb_colors, 2.2)
+
+ final_colors = linear_colors.unsqueeze(0)
+
+ out_mesh = copy.deepcopy(mesh)
+ out_mesh.vertex_colors = final_colors
+
+ return out_mesh
+
+
+def paint_mesh_default_colors(mesh):
+ out_mesh = copy.copy(mesh)
+ vertex_count = mesh.vertices.shape[1]
+ out_mesh.vertex_colors = mesh.vertices.new_zeros((1, vertex_count, 3))
+ return out_mesh
+
+
+class PaintMesh(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="PaintMesh",
+ display_name="Paint Mesh",
+ category="3d/mesh",
+ description="Paints each mesh vertex with its nearest voxel color from the input voxel field.",
+ inputs=[
+ IO.Mesh.Input("mesh"),
+ IO.Voxel.Input("voxel_colors")
+ ],
+ outputs=[
+ IO.Mesh.Output("mesh"),
+ ]
+ )
+
+ @classmethod
+ def execute(cls, mesh, voxel_colors):
+ voxels = voxel_colors
+ coords = voxels.data
+ colors = voxels.voxel_colors
+ resolution = voxels.resolution
+
+ if coords.shape[0] == 0:
+ return IO.NodeOutput(paint_mesh_default_colors(mesh))
+
+ mesh_batch_size = mesh.vertices.shape[0]
+
+ if coords.shape[-1] == 4 and mesh_batch_size > 1:
+ batch_idx = coords[:, 0].long()
+ voxel_coords = coords[:, 1:]
+ mesh_batch_size = mesh.vertices.shape[0]
+
+ out_verts, out_faces, out_colors = [], [], []
+ for i in range(mesh_batch_size):
+ sel = batch_idx == i
+ item_coords = voxel_coords[sel]
+ item_colors = colors[sel]
+ item_vertices, item_faces, *_ = get_mesh_batch_item(mesh, i)
+ item_mesh = Types.MESH(vertices=item_vertices.unsqueeze(0), faces=item_faces.unsqueeze(0))
+
+ if item_coords.shape[0] == 0:
+ painted = paint_mesh_default_colors(item_mesh)
+ else:
+ painted = paint_mesh_with_voxels(item_mesh, item_coords, item_colors, resolution=resolution)
+
+ out_verts.append(painted.vertices.squeeze(0))
+ out_faces.append(painted.faces.squeeze(0))
+ out_colors.append(painted.vertex_colors.squeeze(0))
+
+ out_mesh = pack_variable_mesh_batch(out_verts, out_faces, out_colors)
+ return IO.NodeOutput(out_mesh)
+
+ if coords.shape[-1] == 4:
+ coords = coords[:, 1:]
+
+ out_mesh = paint_mesh_with_voxels(mesh, coords, colors, resolution=resolution)
+ return IO.NodeOutput(out_mesh)
+
+
+def _rasterize_uv_barycentric(faces_np, uvs_np, texture_size):
+ """Rasterize the mesh in UV space (tiled point-in-triangle, pure torch). Returns per-texel
+ face index [H,W], barycentric coords [H,W,3] and coverage mask [H,W], on the torch device.
+ Interpolate any per-vertex attribute from these with _interp_vertex_attr."""
+ dev = comfy.model_management.get_torch_device()
+ H = W = int(texture_size)
+ face_idx = torch.zeros((H, W), dtype=torch.long, device=dev)
+ bary = torch.zeros((H, W, 3), device=dev)
+ cov = torch.zeros((H, W), dtype=torch.bool, device=dev)
+ if faces_np.shape[0] == 0:
+ return face_idx, bary, cov
+
+ uvs = torch.from_numpy(np.ascontiguousarray(uvs_np, dtype=np.float32)).to(dev)
+ faces = torch.from_numpy(np.ascontiguousarray(faces_np).astype(np.int64)).to(dev)
+
+ # GL convention: window coord = uv * resolution, coverage tested at texel centre.
+ tri_uv = (uvs * float(W))[faces] # [F,3,2]
+ x0, y0 = tri_uv[:, 0, 0], tri_uv[:, 0, 1]
+ x1, y1 = tri_uv[:, 1, 0], tri_uv[:, 1, 1]
+ x2, y2 = tri_uv[:, 2, 0], tri_uv[:, 2, 1]
+ denom = (y1 - y2) * (x0 - x2) + (x2 - x1) * (y0 - y2)
+ nondegen = denom.abs() > 1e-20
+
+ xmin = torch.minimum(torch.minimum(x0, x1), x2).floor().clamp_(0, W - 1).long()
+ xmax = torch.maximum(torch.maximum(x0, x1), x2).ceil().clamp_(0, W - 1).long()
+ ymin = torch.minimum(torch.minimum(y0, y1), y2).floor().clamp_(0, H - 1).long()
+ ymax = torch.maximum(torch.maximum(y0, y1), y2).ceil().clamp_(0, H - 1).long()
+
+ # Tile so point-in-triangle only runs over the triangles whose bbox hits the tile.
+ TILE = 64
+ eps = 1e-6
+ for ty in range(0, H, TILE):
+ ty_end = min(ty + TILE, H)
+ for tx in range(0, W, TILE):
+ tx_end = min(tx + TILE, W)
+ tri_mask = (nondegen & (xmin < tx_end) & (xmax >= tx)
+ & (ymin < ty_end) & (ymax >= ty))
+ if not tri_mask.any():
+ continue
+ idx = torch.nonzero(tri_mask, as_tuple=True)[0]
+ ys = torch.arange(ty, ty_end, dtype=torch.float32, device=dev) + 0.5
+ xs = torch.arange(tx, tx_end, dtype=torch.float32, device=dev) + 0.5
+ yy, xx = torch.meshgrid(ys, xs, indexing="ij") # [th,tw]
+ sx0, sy0 = x0[idx][:, None, None], y0[idx][:, None, None]
+ sx1, sy1 = x1[idx][:, None, None], y1[idx][:, None, None]
+ sx2, sy2 = x2[idx][:, None, None], y2[idx][:, None, None]
+ sden = denom[idx][:, None, None]
+ b0 = ((sy1 - sy2) * (xx - sx2) + (sx2 - sx1) * (yy - sy2)) / sden
+ b1 = ((sy2 - sy0) * (xx - sx2) + (sx0 - sx2) * (yy - sy2)) / sden
+ b2 = 1.0 - b0 - b1
+ inside = (b0 >= -eps) & (b1 >= -eps) & (b2 >= -eps) # [K,th,tw]
+ if not inside.any():
+ continue
+ hit = inside.any(dim=0) # [th,tw]
+ sel = inside.int().argmax(dim=0) # [th,tw] first covering local tri
+ bsel = torch.stack([b0.gather(0, sel[None]).squeeze(0),
+ b1.gather(0, sel[None]).squeeze(0),
+ b2.gather(0, sel[None]).squeeze(0)], dim=-1) # [th,tw,3]
+ face_idx[ty:ty_end, tx:tx_end][hit] = idx[sel][hit] # slice is a view → writes through
+ bary[ty:ty_end, tx:tx_end][hit] = bsel[hit]
+ cov[ty:ty_end, tx:tx_end] |= hit
+
+ return face_idx, bary, cov
+
+
+def _interp_vertex_attr(attr_v, faces, face_idx, bary, mask):
+ """Interpolate a per-vertex attribute [N,C] into a [H,W,C] map via a rasterized
+ (face_idx, bary, mask). Uncovered texels stay zero."""
+ H, W = mask.shape
+ out = torch.zeros((H, W, attr_v.shape[1]), device=attr_v.device, dtype=attr_v.dtype)
+ if mask.any():
+ vtri = attr_v[faces[face_idx[mask]]] # [K,3,C]
+ out[mask] = (bary[mask][:, :, None] * vtri).sum(1)
+ return out
+
+
+def _bake_position_map(verts_np, faces_np, uvs_np, texture_size):
+ """Barycentric-interpolate a per-vertex vec3 (world position, or any vec3 e.g. normals)
+ at each covered texel. Returns (attr_map [H,W,3] float32, mask [H,W] bool)."""
+ dev = comfy.model_management.get_torch_device()
+ H = W = int(texture_size)
+ if faces_np.shape[0] == 0:
+ return np.zeros((H, W, 3), dtype=np.float32), np.zeros((H, W), dtype=bool)
+
+ face_idx, bary, mask = _rasterize_uv_barycentric(faces_np, uvs_np, texture_size)
+ verts = torch.from_numpy(np.ascontiguousarray(verts_np, dtype=np.float32)).to(dev)
+ faces = torch.from_numpy(np.ascontiguousarray(faces_np).astype(np.int64)).to(dev)
+ attr = _interp_vertex_attr(verts, faces, face_idx, bary, mask)
+ return attr.cpu().numpy(), mask.cpu().numpy()
+
+
+def _trilinear_sample_sparse(positions, voxel_coords_np, color_np, resolution):
+ """Normalized trilinear over a SPARSE voxel field (only occupied corners of the 8,
+ renormalized; matches official o_voxel.to_glb but without dense-volume zero-bleed).
+ Returns (vals [K,C] float64, ok [K] bool); ok=False where no corner is occupied."""
+ R = int(resolution)
+ origin = -0.5
+ voxel_size = 1.0 / R
+ # Cell-CENTER convention: coord c sits at origin+(c+0.5)*voxel_size (matches
+ # official grid_sample_3d); the -0.5 puts integer gc on centres so the 8 corners
+ # bracket the query (omitting it bleeds colour at boundaries/thin features).
+ gc = (positions.astype(np.float64) - origin) / voxel_size - 0.5
+ base = np.floor(gc).astype(np.int64)
+ frac = gc - base
+
+ vc = voxel_coords_np.astype(np.int64)
+ occ_keys = (vc[:, 0] * R + vc[:, 1]) * R + vc[:, 2]
+ order = np.argsort(occ_keys)
+ occ_sorted = occ_keys[order]
+
+ K = positions.shape[0]
+ C = color_np.shape[1]
+ acc = np.zeros((K, C), dtype=np.float64)
+ wsum = np.zeros((K, 1), dtype=np.float64)
+ for dx in (0, 1):
+ wx = frac[:, 0] if dx else 1.0 - frac[:, 0]
+ for dy in (0, 1):
+ wy = frac[:, 1] if dy else 1.0 - frac[:, 1]
+ for dz in (0, 1):
+ wz = frac[:, 2] if dz else 1.0 - frac[:, 2]
+ cx = base[:, 0] + dx
+ cy = base[:, 1] + dy
+ cz = base[:, 2] + dz
+ inb = (cx >= 0) & (cx < R) & (cy >= 0) & (cy < R) & (cz >= 0) & (cz < R)
+ key = (cx * R + cy) * R + cz
+ ins = np.clip(np.searchsorted(occ_sorted, key), 0, len(occ_sorted) - 1)
+ matched = inb & (occ_sorted[ins] == key)
+ idx = order[ins] # garbage where !matched
+ w = np.where(matched, wx * wy * wz, 0.0)[:, None]
+ acc += w * color_np[idx] # w=0 cancels garbage rows
+ wsum += w
+ ok = wsum[:, 0] > 1e-8
+ vals = np.zeros((K, C), dtype=np.float64)
+ vals[ok] = acc[ok] / wsum[ok]
+ return vals, ok
+
+
+def _trilinear_sample_sparse_gpu(positions, voxel_coords_np, color_np, resolution):
+ """GPU port of `_trilinear_sample_sparse`. Returns (vals [K,C] float32, ok [K] bool)."""
+ dev = comfy.model_management.get_torch_device()
+ R = int(resolution)
+ origin = -0.5
+ voxel_size = 1.0 / R
+ P = torch.from_numpy(np.ascontiguousarray(positions)).to(dev).float()
+ VC = torch.from_numpy(np.ascontiguousarray(voxel_coords_np)).to(dev).long()
+ col = torch.from_numpy(np.ascontiguousarray(color_np)).to(dev).float()
+ K, C = P.shape[0], col.shape[1]
+ M = VC.shape[0]
+ # Cell-CENTER convention (see NumPy path): -0.5 to bracket the query.
+ gc = (P - origin) / voxel_size - 0.5
+ base = torch.floor(gc).long()
+ frac = gc - base.float()
+ key = (VC[:, 0] * R + VC[:, 1]) * R + VC[:, 2]
+ skey, order = key.sort()
+ acc = torch.zeros((K, C), device=dev)
+ wsum = torch.zeros((K, 1), device=dev)
+ for dx in (0, 1):
+ wx = frac[:, 0] if dx else 1.0 - frac[:, 0]
+ for dy in (0, 1):
+ wy = frac[:, 1] if dy else 1.0 - frac[:, 1]
+ for dz in (0, 1):
+ wz = frac[:, 2] if dz else 1.0 - frac[:, 2]
+ cx = base[:, 0] + dx
+ cy = base[:, 1] + dy
+ cz = base[:, 2] + dz
+ inb = (cx >= 0) & (cx < R) & (cy >= 0) & (cy < R) & (cz >= 0) & (cz < R)
+ qk = (cx * R + cy) * R + cz
+ ins = torch.searchsorted(skey, qk).clamp(max=M - 1)
+ matched = inb & (skey[ins] == qk)
+ idx = order[ins] # garbage where !matched
+ w = torch.where(matched, wx * wy * wz, torch.zeros_like(wx))[:, None]
+ acc += w * col[idx] # w=0 cancels garbage rows
+ wsum += w
+ ok = wsum[:, 0] > 1e-8
+ vals = torch.zeros((K, C), device=dev)
+ vals[ok] = acc[ok] / wsum[ok].clamp_min(1e-8)
+ return vals.cpu().numpy(), ok.cpu().numpy()
+
+
+# Above this many grid-scan stragglers, the O(N·M) GPU brute force (and its chunk loop)
+# is slower than a one-off cKDTree build, so the nearest fallback defers them to cKDTree.
+_BRUTE_NEAREST_MAX = 8192
+
+
+def _nearest_voxel_sample_gpu(positions, voxel_coords_np, color_np, resolution):
+ """GPU nearest-occupied-voxel lookup via sorted-key grid scan. Returns (vals [K,C]
+ float32, found [K] bool); `found` is False for stragglers left to the caller's cKDTree."""
+ dev = comfy.model_management.get_torch_device()
+ R = int(resolution)
+ P = torch.from_numpy(np.ascontiguousarray(positions)).to(dev).float()
+ VC = torch.from_numpy(np.ascontiguousarray(voxel_coords_np)).to(dev).long()
+ col = torch.from_numpy(np.ascontiguousarray(color_np)).to(dev).float()
+ M, K = VC.shape[0], P.shape[0]
+ key = (VC[:, 0] * R + VC[:, 1]) * R + VC[:, 2]
+ skey, order = key.sort()
+
+ def _search(idx, radius):
+ """Nearest occupied voxel within ±radius cells, for query subset P[idx]."""
+ Ps = P[idx]
+ # Cell-CENTER convention: nearest coord = round((p+0.5)*R-0.5) (matches official).
+ rc = ((Ps + 0.5) * R - 0.5).round().long()
+ n = idx.shape[0]
+ bd = torch.full((n,), 1e30, device=dev)
+ bi = torch.zeros(n, dtype=torch.long, device=dev)
+ fnd = torch.zeros(n, dtype=torch.bool, device=dev)
+ rng = range(-radius, radius + 1)
+ for dx in rng:
+ for dy in rng:
+ for dz in rng:
+ cc = rc + torch.tensor([dx, dy, dz], device=dev)
+ inb = ((cc >= 0) & (cc < R)).all(1)
+ qk = (cc[:, 0] * R + cc[:, 1]) * R + cc[:, 2]
+ ins = torch.searchsorted(skey, qk).clamp(max=M - 1)
+ match = inb & (skey[ins] == qk)
+ dd = (((cc.float() + 0.5) / R - 0.5 - Ps) ** 2).sum(1)
+ upd = match & (dd < bd)
+ bd = torch.where(upd, dd, bd)
+ bi = torch.where(upd, order[ins], bi)
+ fnd |= match
+ return bi, fnd
+
+ def _brute_nearest(idx):
+ """Exact nearest occupied voxel for the few grid-scan stragglers, chunked GPU
+ brute force (avoids a seconds-long cKDTree build over all M voxels)."""
+ Ps = P[idx] # [N,3] world
+ N = Ps.shape[0]
+ vox_pos = (VC.float() + 0.5) / R - 0.5 # [M,3] voxel centres
+ best_d = torch.full((N,), 1e30, device=dev)
+ best_j = torch.zeros(N, dtype=torch.long, device=dev)
+ # Bound the N×chunk matrix to ~64M elements.
+ chunk = max(1, (1 << 26) // max(1, N))
+ for s in range(0, M, chunk):
+ vc = vox_pos[s:s + chunk] # [B,3]
+ dd = (Ps[:, None, :] - vc[None, :, :]).pow(2).sum(-1) # [N,B]
+ md, mj = dd.min(1)
+ upd = md < best_d
+ best_d = torch.where(upd, md, best_d)
+ best_j = torch.where(upd, mj + s, best_j)
+ return best_j
+
+ all_idx = torch.arange(K, device=dev)
+ best_i = torch.zeros(K, dtype=torch.long, device=dev)
+ found = torch.zeros(K, dtype=torch.bool, device=dev)
+ # Pass 1: radius 1 over everything; Pass 2: radius 4 on misses; Pass 3: brute force.
+ bi1, fnd1 = _search(all_idx, 1)
+ best_i[all_idx] = bi1
+ found[all_idx] = fnd1
+ miss = torch.nonzero(~found, as_tuple=True)[0]
+ if miss.numel() > 0:
+ bi2, fnd2 = _search(miss, 4)
+ best_i[miss] = bi2
+ found[miss] = fnd2
+ # Pass 3: stragglers >4 cells from any voxel. A handful → GPU brute force; many
+ # (coarse mesh, texels far from the voxel shell) → leave unfound for the caller's
+ # cKDTree, since brute force is O(N·M) and its chunk loop blows up at large N.
+ miss2 = torch.nonzero(~found, as_tuple=True)[0]
+ if 0 < miss2.numel() <= _BRUTE_NEAREST_MAX:
+ best_i[miss2] = _brute_nearest(miss2)
+ found[miss2] = True
+ vals = col[best_i]
+ return vals.cpu().numpy(), found.cpu().numpy()
+
+
+def _sample_voxel_attrs_per_texel(position_map, mask, voxel_coords, voxel_colors, resolution):
+ """Sample all voxel attribute channels at every masked texel. Returns (H,W,C)
+ float32 in [0,1] (C = feature width: 3 color, 6 PBR). Normalized trilinear over
+ occupied voxels (matches official), nearest fallback where all 8 corners empty."""
+ H, W, _ = position_map.shape
+ color_np = voxel_colors.detach().cpu().numpy().astype(np.float32)
+ C = color_np.shape[-1]
+ out = np.zeros((H, W, C), dtype=np.float32)
+ if not mask.any():
+ return out
+
+ origin = np.array([-0.5, -0.5, -0.5], dtype=np.float32)
+ voxel_size = 1.0 / float(resolution)
+ coords_np = voxel_coords.detach().cpu().numpy()
+ # Cell-CENTER convention (+0.5 voxel) — same world mapping as the sampling paths; these
+ # voxel centres serve the rare cKDTree nearest fallback below.
+ voxel_pos = (coords_np.astype(np.float32) + 0.5) * voxel_size + origin
+ valid_positions = position_map[mask]
+
+ def _nearest(query):
+ # Grid scan + small-N brute tail (on the compute device). Only a large count of far
+ # stragglers (coarse mesh, or a surface off the voxel shell) is left unfound → resolve
+ # those with one cKDTree, since GPU brute force is O(N·M) and blows up at large N.
+ vals, found = _nearest_voxel_sample_gpu(query, coords_np, color_np, resolution)
+ if not found.all():
+ tree = cKDTree(voxel_pos)
+ _, nearest_idx = tree.query(query[~found], k=1, workers=-1)
+ vals[~found] = color_np[nearest_idx]
+ return vals
+
+ try:
+ vals, ok = _trilinear_sample_sparse_gpu(valid_positions, coords_np, color_np, resolution)
+ except Exception as e:
+ comfy.model_management.raise_non_oom(e) # only fall back on OOM; surface real errors
+ logging.warning(f"[BakeTextureFromVoxel] GPU trilinear ran out of memory ({e}); falling back to CPU")
+ vals, ok = _trilinear_sample_sparse(valid_positions, coords_np, color_np, resolution)
+ if not ok.all():
+ vals[~ok] = _nearest(valid_positions[~ok]) # no occupied neighbour
+ out[mask] = np.clip(vals, 0.0, 1.0).astype(np.float32)
+ return out
+
+
+def _msb_int64(x):
+ """floor(log2(x)) elementwise for int64 x >= 1 (bit-search, no float)."""
+ r = torch.zeros_like(x)
+ xx = x.clone()
+ for s in (32, 16, 8, 4, 2, 1):
+ sh = xx >> s
+ m = sh > 0
+ r = torch.where(m, r + s, r)
+ xx = torch.where(m, sh, xx)
+ return r
+
+
+def _morton_expand21(v):
+ """Spread the low 21 bits of v across every 3rd bit (for a 63-bit Morton code)."""
+ v = v & 0x1fffff
+ v = (v | (v << 32)) & 0x1f00000000ffff
+ v = (v | (v << 16)) & 0x1f0000ff0000ff
+ v = (v | (v << 8)) & 0x100f00f00f00f00f
+ v = (v | (v << 4)) & 0x10c30c30c30c30c3
+ v = (v | (v << 2)) & 0x1249249249249249
+ return v
+
+
+def _build_triangle_bvh(tri):
+ """Linear BVH (Karras 2012) over triangle AABBs, pure torch, no external deps
+ (the cuMesh approach, in torch). Internal nodes 0..T-2; leaves encoded LEAF+i,
+ leaf i holds triangle order[i]. Returns dict(LEAF, left, right, nmin, nmax over
+ 2T entries, order, T)."""
+ dev = tri.device
+ T = tri.shape[0]
+ amin = tri.amin(1)
+ amax = tri.amax(1)
+ cent = (amin + amax) * 0.5
+ lo = cent.amin(0)
+ hi = cent.amax(0)
+ span = (hi - lo).clamp_min(1e-12)
+ q = (((cent - lo) / span).clamp(0, 1) * float((1 << 21) - 1)).long()
+ morton = (_morton_expand21(q[:, 0]) << 2 | _morton_expand21(q[:, 1]) << 1 | _morton_expand21(q[:, 2])).long()
+ order = torch.argsort(morton)
+ msort = morton[order]
+
+ # delta(i,j): common-prefix length of (morton, index) keys of leaves i,j (index
+ # breaks ties so duplicate codes still split); -1 if OOB.
+ def delta(i, j):
+ ok = (j >= 0) & (j < T)
+ jj = j.clamp(0, T - 1)
+ x = msort[i] ^ msort[jj]
+ same = x == 0
+ cp = torch.where(same, torch.full_like(x, 63), 62 - _msb_int64(x.clamp_min(1)))
+ xi = i ^ jj
+ cpi = torch.where(xi == 0, torch.full_like(x, 32), 31 - _msb_int64(xi.clamp_min(1)))
+ return torch.where(ok, cp + torch.where(same, cpi, torch.zeros_like(cp)), torch.full_like(x, -1))
+
+ I = torch.arange(T - 1, device=dev)
+ dplus = delta(I, I + 1)
+ dminus = delta(I, I - 1)
+ direction = torch.where(dplus >= dminus, torch.ones_like(I), -torch.ones_like(I))
+ dmin = torch.minimum(dplus, dminus)
+ # range length: exponential probe then binary search
+ lmax = torch.full_like(I, 2)
+ while True:
+ cond = delta(I, I + lmax * direction) > dmin
+ if not bool(cond.any()):
+ break
+ lmax = torch.where(cond, lmax * 2, lmax)
+ if int(lmax.max()) > 2 * T:
+ break
+ l = torch.zeros_like(I)
+ t = lmax.clone()
+ while True:
+ t = t // 2
+ if int(t.max()) == 0:
+ break
+ cond = delta(I, I + (l + t) * direction) > dmin
+ l = torch.where(cond, l + t, l)
+ j = I + l * direction
+ first = torch.minimum(I, j)
+ last = torch.maximum(I, j)
+ # split position: binary search on delta within [first, last]
+ dnode = delta(first, last)
+ s = torch.zeros_like(I)
+ div = torch.full_like(I, 2)
+ rng = last - first
+ while True:
+ step = (rng + div - 1) // div
+ cond = delta(first, (first + s + step).clamp(max=T - 1)) > dnode
+ s = torch.where(cond, s + step, s)
+ if int(step.max()) <= 1:
+ cond1 = delta(first, (first + s + 1).clamp(max=T - 1)) > dnode
+ s = torch.where(cond1, s + 1, s)
+ break
+ div = div * 2
+ gamma = first + s
+ LEAF = T
+ left = torch.where(gamma == first, LEAF + gamma, gamma)
+ right = torch.where(gamma + 1 == last, LEAF + gamma + 1, gamma + 1)
+
+ # node AABBs: leaves seeded, internal unioned bottom-up (~log2(T) passes; cap is a backstop).
+ nmin = torch.empty((2 * T, 3), device=dev)
+ nmax = torch.empty((2 * T, 3), device=dev)
+ nmin[LEAF:] = amin[order]
+ nmax[LEAF:] = amax[order]
+ setm = torch.zeros(2 * T, dtype=torch.bool, device=dev)
+ setm[LEAF:] = True
+ for _ in range(128):
+ need = ~setm[:T - 1]
+ if not bool(need.any()):
+ break
+ idx = torch.nonzero(need, as_tuple=True)[0]
+ ii = idx[setm[left[idx]] & setm[right[idx]]]
+ if ii.numel() == 0:
+ break
+ nmin[ii] = torch.minimum(nmin[left[ii]], nmin[right[ii]])
+ nmax[ii] = torch.maximum(nmax[left[ii]], nmax[right[ii]])
+ setm[ii] = True
+ return dict(LEAF=LEAF, left=left, right=right, nmin=nmin, nmax=nmax, order=order, T=T)
+
+
+def _closest_points_on_mesh_bvh(Q, tri, bvh, max_stack=64, return_face=False):
+ """Exact closest surface point per query via per-query BVH stack traversal
+ (nearest-child-first), pure torch. Returns [N,3], or (points [N,3], face_idx [N])
+ when return_face=True (face_idx indexes `tri`). `max_stack` bounds the stack
+ (= tree height); overflow is counted+warned, not silently wrong."""
+ dev = Q.device
+ N = Q.shape[0]
+ LEAF = bvh['LEAF']
+ nmin = bvh['nmin']
+ nmax = bvh['nmax']
+ left = bvh['left']
+ right = bvh['right']
+ order = bvh['order']
+ stack = torch.full((N, max_stack), -1, dtype=torch.long, device=dev)
+ sp = torch.ones(N, dtype=torch.long, device=dev)
+ stack[:, 0] = 0
+ best = torch.full((N,), 1e30, device=dev)
+ bestp = Q.clone()
+ bestf = torch.full((N,), -1, dtype=torch.long, device=dev)
+ active = torch.arange(N, device=dev)
+ overflow = 0
+
+ def aabb_d2(node, q):
+ d = (nmin[node] - q).clamp_min(0) + (q - nmax[node]).clamp_min(0)
+ return (d * d).sum(-1)
+
+ while active.numel() > 0:
+ a = active
+ qa = Q[a]
+ node = stack[a, sp[a] - 1]
+ sp[a] = sp[a] - 1
+ within = aabb_d2(node, qa) < best[a]
+ isleaf = node >= LEAF
+ lv = within & isleaf
+ if bool(lv.any()):
+ ga = a[lv]
+ fidx = order[node[lv] - LEAF] # triangle index of each leaf
+ tt = tri[fidx]
+ cp, d2 = _point_tri_closest(qa[lv], tt)
+ upd = d2 < best[ga]
+ gu = ga[upd]
+ best[gu] = d2[upd]
+ bestp[gu] = cp[upd]
+ bestf[gu] = fidx[upd]
+ iv = within & ~isleaf
+ if bool(iv.any()):
+ gi = a[iv]
+ qi = qa[iv]
+ lc = left[node[iv]]
+ rc = right[node[iv]]
+ dl = aabb_d2(lc, qi)
+ dr = aabb_d2(rc, qi)
+ near = torch.where(dl <= dr, lc, rc)
+ far = torch.where(dl <= dr, rc, lc)
+ s0 = sp[gi]
+ stack[gi, s0.clamp(max=max_stack - 1)] = far
+ sp[gi] = (s0 + 1).clamp(max=max_stack)
+ s1 = sp[gi]
+ overflow += int((s1 >= max_stack).sum())
+ stack[gi, s1.clamp(max=max_stack - 1)] = near
+ sp[gi] = (s1 + 1).clamp(max=max_stack)
+ active = a[sp[a] > 0]
+ if overflow:
+ logging.warning(f"[back-project] BVH stack overflow on {overflow} pushes "
+ f"(max_stack={max_stack}); a few texels may be slightly off — "
+ f"raise max_stack if this is large.")
+ if return_face:
+ return bestp, bestf
+ return bestp
+
+
+def _back_project_positions(position_map, mask, ref_v, ref_f, max_query_res=1024):
+ """Snap covered texels onto the reference mesh's true surface (pure-torch BVH, no
+ cumesh/scipy/trimesh) so the voxel field is sampled at full detail, not along flat
+ triangle chords. Returns a new position_map.
+"""
+ if not mask.any():
+ return position_map
+
+ dev = comfy.model_management.get_torch_device()
+ rv = ref_v.detach().to(dev).float()
+ rf = ref_f.detach().to(dev).long()
+ tri = rv[rf]
+ bvh = _build_triangle_bvh(tri)
+
+ def _closest(pts_np):
+ return _closest_points_on_mesh_bvh(
+ torch.from_numpy(np.ascontiguousarray(pts_np.astype(np.float32))).to(dev), tri, bvh
+ ).detach().cpu().numpy().astype(np.float32)
+
+ H, W, _ = position_map.shape
+ stride = max(1, int(math.ceil(max(H, W) / float(max_query_res))))
+ if stride == 1 or not mask[::stride, ::stride].any():
+ out = position_map.copy()
+ out[mask] = _closest(position_map[mask]).astype(position_map.dtype)
+ return out
+
+ # Low-res correction, then bilinear upsample to full resolution.
+ pos_lo = position_map[::stride, ::stride]
+ mask_lo = mask[::stride, ::stride]
+ Hl, Wl = mask_lo.shape
+ corr_lo = np.zeros((Hl, Wl, 3), dtype=np.float32)
+ corr_lo[mask_lo] = _closest(pos_lo[mask_lo]) - pos_lo[mask_lo].astype(np.float32)
+ inds = ndi.distance_transform_edt(~mask_lo, return_distances=False, return_indices=True)
+ corr_lo = corr_lo[tuple(inds)] # extrapolate into gutter (nearest)
+ corr = torch.nn.functional.interpolate(
+ torch.from_numpy(np.ascontiguousarray(corr_lo)).permute(2, 0, 1)[None].to(dev),
+ size=(H, W), mode="bilinear", align_corners=False,
+ )[0].permute(1, 2, 0).cpu().numpy()
+ out = position_map.copy()
+ out[mask] = position_map[mask] + corr[mask]
+ return out
+
+
+def _ray_tri_hit(o, d, tri, tmin, tmax):
+ """Möller-Trumbore any-hit per (ray, triangle) pair, double-sided. Returns bool [N]."""
+ a, b, c = tri[:, 0], tri[:, 1], tri[:, 2]
+ e1, e2 = b - a, c - a
+ p = torch.cross(d, e2, dim=-1)
+ det = (e1 * p).sum(-1)
+ inv = 1.0 / torch.where(det.abs() < 1e-20, torch.full_like(det, 1e-20), det)
+ tvec = o - a
+ u = (tvec * p).sum(-1) * inv
+ q = torch.cross(tvec, e1, dim=-1)
+ v = (d * q).sum(-1) * inv
+ t = (e2 * q).sum(-1) * inv
+ return (det.abs() > 1e-20) & (u >= 0) & (v >= 0) & (u + v <= 1) & (t > tmin) & (t < tmax)
+
+
+def _any_hit_rays_bvh(orig, dirs, tri, bvh, tmin=0.0, tmax=1e30, max_stack=64):
+ """Any-hit ray test over the BVH (slab cull + Möller-Trumbore), pure torch. Returns bool
+ [N]: True if the ray hits any triangle in (tmin, tmax). Rays early-out once they hit."""
+ dev = orig.device
+ N = orig.shape[0]
+ LEAF = bvh['LEAF']
+ nmin, nmax = bvh['nmin'], bvh['nmax']
+ left, right, order = bvh['left'], bvh['right'], bvh['order']
+ inv = 1.0 / torch.where(dirs.abs() < 1e-20, torch.full_like(dirs, 1e-20), dirs)
+ tmaxN = tmax if torch.is_tensor(tmax) else torch.full((N,), float(tmax), device=dev) # per-ray far bound
+ hit = torch.zeros(N, dtype=torch.bool, device=dev)
+ # int32 stack: node indices fit in 31 bits and this [N, max_stack] array dominates memory.
+ stack = torch.full((N, max_stack), -1, dtype=torch.int32, device=dev)
+ sp = torch.ones(N, dtype=torch.long, device=dev)
+ stack[:, 0] = 0
+ active = torch.arange(N, device=dev)
+
+ def slab(node, o, i, tmx):
+ t1 = (nmin[node] - o) * i
+ t2 = (nmax[node] - o) * i
+ tnear = torch.minimum(t1, t2).amax(-1)
+ tfar = torch.maximum(t1, t2).amin(-1)
+ return (tfar >= tnear.clamp_min(tmin)) & (tnear <= tmx) & (tfar >= tmin)
+
+ while active.numel() > 0:
+ a = active
+ node = stack[a, sp[a] - 1]
+ sp[a] = sp[a] - 1
+ within = slab(node, orig[a], inv[a], tmaxN[a])
+ isleaf = node >= LEAF
+ lv = within & isleaf
+ if bool(lv.any()):
+ ga = a[lv]
+ tt = tri[order[node[lv] - LEAF]]
+ h = _ray_tri_hit(orig[ga], dirs[ga], tt, tmin, tmaxN[ga])
+ hit[ga[h]] = True
+ iv = within & ~isleaf
+ if bool(iv.any()):
+ gi = a[iv]
+ s0 = sp[gi]
+ stack[gi, s0.clamp(max=max_stack - 1)] = left[node[iv]].to(torch.int32)
+ sp[gi] = (s0 + 1).clamp(max=max_stack)
+ s1 = sp[gi]
+ stack[gi, s1.clamp(max=max_stack - 1)] = right[node[iv]].to(torch.int32)
+ sp[gi] = (s1 + 1).clamp(max=max_stack)
+ active = a[(sp[a] > 0) & ~hit[a]] # drop finished + already-hit rays
+ return hit
+
+
+def _ray_tri_intersect(o, d, tri, tmin, tmax, cull_backface=False):
+ """Möller-Trumbore per (ray, triangle) pair. Returns (hit [N], t [N]) where t is the ray
+ parameter and hit means the meeting is in (tmin, tmax). With cull_backface, drops faces whose
+ outward (winding) normal points along the ray — i.e. only keep surfaces facing the origin."""
+ a, b, c = tri[:, 0], tri[:, 1], tri[:, 2]
+ e1, e2 = b - a, c - a
+ p = torch.cross(d, e2, dim=-1)
+ det = (e1 * p).sum(-1)
+ inv = 1.0 / torch.where(det.abs() < 1e-20, torch.full_like(det, 1e-20), det)
+ tvec = o - a
+ u = (tvec * p).sum(-1) * inv
+ q = torch.cross(tvec, e1, dim=-1)
+ v = (d * q).sum(-1) * inv
+ t = (e2 * q).sum(-1) * inv
+ hit = (det.abs() > 1e-20) & (u >= 0) & (v >= 0) & (u + v <= 1) & (t > tmin) & (t < tmax)
+ if cull_backface:
+ hit = hit & ((torch.cross(e1, e2, dim=-1) * d).sum(-1) < 0) # keep only front-facing
+ return hit, t
+
+
+def _closest_hit_rays_bvh(orig, dirs, tri, bvh, tmin=0.0, tmax=1e30, max_stack=64, cull_backface=False):
+ """Nearest-hit ray cast over the BVH, pure torch. Returns (t [N], face [N] long, -1 on
+ miss; hit [N] bool) — the closest intersection in (tmin, tmax), pruning nodes past best_t."""
+ dev = orig.device
+ N = orig.shape[0]
+ LEAF = bvh['LEAF']
+ nmin, nmax = bvh['nmin'], bvh['nmax']
+ left, right, order = bvh['left'], bvh['right'], bvh['order']
+ inv = 1.0 / torch.where(dirs.abs() < 1e-20, torch.full_like(dirs, 1e-20), dirs)
+ best_t = torch.full((N,), float(tmax), device=dev)
+ best_f = torch.full((N,), -1, dtype=torch.long, device=dev)
+ stack = torch.full((N, max_stack), -1, dtype=torch.int32, device=dev)
+ sp = torch.ones(N, dtype=torch.long, device=dev)
+ stack[:, 0] = 0
+ active = torch.arange(N, device=dev)
+
+ while active.numel() > 0:
+ a = active
+ node = stack[a, sp[a] - 1]
+ sp[a] = sp[a] - 1
+ t1 = (nmin[node] - orig[a]) * inv[a]
+ t2 = (nmax[node] - orig[a]) * inv[a]
+ tnear = torch.minimum(t1, t2).amax(-1)
+ tfar = torch.maximum(t1, t2).amin(-1)
+ within = (tfar >= tnear.clamp_min(tmin)) & (tfar >= tmin) & (tnear < best_t[a]) # prune past best
+ isleaf = node >= LEAF
+ lv = within & isleaf
+ if bool(lv.any()):
+ ga = a[lv]
+ fidx = order[node[lv] - LEAF]
+ h, t = _ray_tri_intersect(orig[ga], dirs[ga], tri[fidx], tmin, tmax, cull_backface)
+ upd = h & (t < best_t[ga])
+ gu = ga[upd]
+ best_t[gu] = t[upd]
+ best_f[gu] = fidx[upd]
+ iv = within & ~isleaf
+ if bool(iv.any()):
+ gi = a[iv]
+ s0 = sp[gi]
+ stack[gi, s0.clamp(max=max_stack - 1)] = left[node[iv]].to(torch.int32)
+ sp[gi] = (s0 + 1).clamp(max=max_stack)
+ s1 = sp[gi]
+ stack[gi, s1.clamp(max=max_stack - 1)] = right[node[iv]].to(torch.int32)
+ sp[gi] = (s1 + 1).clamp(max=max_stack)
+ active = a[sp[a] > 0]
+ return best_t, best_f, best_f >= 0
+
+
+def _onb(n):
+ """Branchless orthonormal basis (t, b) around unit normals n [N,3]."""
+ up = torch.where(n[..., 2:3].abs() < 0.999,
+ torch.tensor([0.0, 0.0, 1.0], device=n.device).expand_as(n),
+ torch.tensor([1.0, 0.0, 0.0], device=n.device).expand_as(n))
+ t = torch.nn.functional.normalize(torch.cross(up, n, dim=-1), dim=-1, eps=1e-6)
+ return t, torch.cross(n, t, dim=-1)
+
+
+def _bake_ambient_occlusion(high_v, high_f, low_v_np, low_f_np, low_uv_np, low_n, resolution,
+ num_samples=64, max_distance=0.5, strength=1.0, bias=0.01,
+ ray_chunk=None, pbar=None, pbar_range=None):
+ """Bake high-poly ambient occlusion into the low-poly's UV layout: per texel, cosine-weight
+ a hemisphere of rays around the normal and cast them at the high-poly. AO = 1 - hit-fraction
+ (cosine weighting makes the hit-fraction the estimator). Returns ao_img [H,W,3] in [0,1].
+
+ ray_chunk caps rays cast at once (the per-chunk BVH stack is its dominant transient VRAM);
+ None auto-sizes it to a slice of free VRAM — big chunks (fast) on large GPUs, small (safe)
+ on small ones."""
+ dev = comfy.model_management.get_torch_device()
+ H = W = int(resolution)
+ S = int(num_samples)
+ if ray_chunk is None:
+ # ~376 B/ray (int32 stack max_stack*4 + a few [N,3] ray buffers); spend a quarter of free
+ # device memory. Speed saturates around 4M rays/chunk, so cap there (≈2 GB peak) rather than
+ # grow memory for no gain; floor keeps tiny GPUs from thrashing into too many chunks.
+ free = comfy.model_management.get_free_memory(dev)
+ ray_chunk = int(min(1 << 22, max(1 << 20, (free * 0.25) / (num_samples * 4 + 200))))
+ face_idx, bary_uv, mask = _rasterize_uv_barycentric(low_f_np, low_uv_np, resolution)
+ if not mask.any():
+ return np.ones((H, W, 3), dtype=np.float32)
+ lf = torch.from_numpy(np.ascontiguousarray(low_f_np).astype(np.int64)).to(dev)
+ lv = torch.from_numpy(np.ascontiguousarray(low_v_np, dtype=np.float32)).to(dev)
+ low_n = low_n.to(dev).float()
+ m = mask
+ vtri = lf[face_idx[m]] # [K,3] vertex ids
+ bsel = bary_uv[m] # [K,3]
+ P = (bsel[:, :, None] * lv[vtri]).sum(1) # [K,3]
+ Nl = torch.nn.functional.normalize((bsel[:, :, None] * low_n[vtri]).sum(1), dim=-1, eps=1e-6)
+
+ hv = high_v.to(dev).float()
+ hf = high_f.to(dev).long()
+ tri = hv[hf]
+ bvh = _build_triangle_bvh(tri)
+ diag = float((hv.amax(0) - hv.amin(0)).norm().clamp_min(1e-6))
+ biasw = max(1e-5, float(bias) * diag)
+ tmax = float(max_distance) * diag
+
+ # Back-project onto the high surface, then lift along the normal: the low-poly chord can sit
+ # below the high surface, and casting from below floods false self-occlusion (dark blotches).
+ bp = _closest_points_on_mesh_bvh(P, tri, bvh)
+ origins = bp + Nl * biasw
+
+ K = P.shape[0]
+ T, B = _onb(Nl)
+ occ = torch.zeros(K, device=dev)
+ tex_per_chunk = max(1, int(ray_chunk) // max(1, S))
+ n_chunks = max(1, (K + tex_per_chunk - 1) // tex_per_chunk)
+ for ci, s in enumerate(range(0, K, tex_per_chunk)):
+ e = min(s + tex_per_chunk, K)
+ kk = e - s
+ o, n, t, b = origins[s:e], Nl[s:e], T[s:e], B[s:e]
+ r1 = torch.rand(kk, S, device=dev)
+ r2 = torch.rand(kk, S, device=dev)
+ sr = r1.sqrt()
+ lz = r1.mul_(-1.0).add_(1.0).clamp_min_(0.0).sqrt_() # sqrt(1-r1) (r1 dead after sr)
+ ang = r2.mul_(2.0 * math.pi) # in place (r2 dead)
+ lx = ang.cos().mul_(sr)
+ ly = ang.sin().mul_(sr)
+ d = t[:, None, :] * lx[..., None] # cosine-weighted hemisphere,
+ d.addcmul_(b[:, None, :], ly[..., None]) # fused d += b*ly
+ d.addcmul_(n[:, None, :], lz[..., None]) # fused d += n*lz (no extra temps)
+ d = torch.nn.functional.normalize(d.reshape(-1, 3), dim=-1, eps=1e-6)
+ oo = o[:, None, :].expand(-1, S, -1).reshape(-1, 3)
+ hit = _any_hit_rays_bvh(oo, d, tri, bvh, tmin=biasw, tmax=tmax)
+ occ[s:e] = hit.reshape(kk, S).sum(1, dtype=torch.float32).div_(float(S)) # mean without a float copy
+ if pbar is not None and pbar_range is not None:
+ lo, hi = pbar_range
+ pbar.update_absolute(lo + ((hi - lo) * (ci + 1)) // n_chunks, 1000)
+
+ ao = occ.mul_(-float(strength)).add_(1.0).clamp_(0.0, 1.0) # 1 - occ*strength, in place (occ is dead)
+ out = torch.ones((H, W), device=dev)
+ out[m] = ao
+ out3 = np.repeat(out.cpu().numpy()[..., None], 3, axis=2)
+ return _jfa_fill_gpu(np.ascontiguousarray(out3, dtype=np.float32), mask.cpu().numpy())
+
+
+def _camera_basis(eye, center, up_hint):
+ """Forward/right/up for a camera at `eye` looking at `center` (each [3])."""
+ f = torch.nn.functional.normalize(center - eye, dim=-1, eps=1e-6)
+ # Fall back to +Z up when looking near-vertical (f ∥ +Y would give a degenerate right vector).
+ up = up_hint if float(torch.abs((f * up_hint).sum())) < 0.99 else torch.tensor([0.0, 0.0, 1.0], device=f.device)
+ r = torch.nn.functional.normalize(torch.cross(f, up, dim=-1), dim=-1, eps=1e-6)
+ return f, r, torch.cross(r, f, dim=-1)
+
+
+def _apply_model_transform(values, transform, is_normal=False):
+ def _vec(data):
+ return values.new_tensor([data["x"], data["y"], data["z"]])
+
+ scale = _vec(transform["scale"])
+ position = _vec(transform["position"])
+ quaternion = transform["quaternion"]
+ x, y, z, w = (values.new_tensor(quaternion[key]) for key in ("x", "y", "z", "w"))
+ rotation = torch.stack((
+ torch.stack((1 - 2 * (y * y + z * z), 2 * (x * y - z * w), 2 * (x * z + y * w))),
+ torch.stack((2 * (x * y + z * w), 1 - 2 * (x * x + z * z), 2 * (y * z - x * w))),
+ torch.stack((2 * (x * z - y * w), 2 * (y * z + x * w), 1 - 2 * (x * x + y * y))),
+ ))
+ if is_normal:
+ return torch.nn.functional.normalize((values / scale) @ rotation.T, dim=-1, eps=1e-6)
+ return (values * scale) @ rotation.T + position
+
+
+def _sample_image01(img_hwc, uv01):
+ """Bilinear-sample img [H,W,C] at uv01 [K,2] in [0,1] (u=x/col, v=y/row). Returns [K,C]."""
+ g = (uv01 * 2.0 - 1.0).view(1, 1, -1, 2)
+ s = torch.nn.functional.grid_sample(img_hwc.permute(2, 0, 1)[None].float(), g, mode="bilinear", align_corners=False, padding_mode="border")
+ return s[0, :, 0, :].t()
+
+
+def _render_view(tri, bvh, uv, faces, texture_hwc, eye, f, r, u, fov, H, W, ray_chunk=1 << 22,
+ vertex_colors=None, vertex_normals=None, render_normal=False):
+ """Ray-cast render: per pixel, nearest-hit triangle → colour it. With `render_normal`, output the
+ view-space normal (OpenGL: x=right, y=up, z=toward camera; smooth `vertex_normals` if given, else
+ the face normal). Otherwise colour source in order: `texture_hwc` (sampled via interpolated UVs),
+ else `vertex_colors` (barycentric), else neutral clay shaded by facing angle. Returns
+ (img, hit_mask, depth)."""
+ dev = tri.device
+ ys = 1.0 - (torch.arange(H, device=dev, dtype=torch.float32) + 0.5) / H * 2.0 # row 0 = +up
+ xs = (torch.arange(W, device=dev, dtype=torch.float32) + 0.5) / W * 2.0 - 1.0
+ gy, gx = torch.meshgrid(ys, xs, indexing="ij")
+ tn = math.tan(0.5 * fov)
+ aspect = W / H
+ d = torch.nn.functional.normalize(
+ (r * (gx * tn * aspect)[..., None] + u * (gy * tn)[..., None] + f).reshape(-1, 3), dim=-1, eps=1e-6)
+ o = eye[None, :].expand(H * W, 3)
+ img = torch.zeros((H * W, 3), device=dev)
+ depth = torch.full((H * W,), float("inf"), device=dev)
+ hit_all = torch.zeros(H * W, dtype=torch.bool, device=dev)
+ for s in range(0, H * W, ray_chunk):
+ e = min(s + ray_chunk, H * W)
+ t_hit, face, hit = _closest_hit_rays_bvh(o[s:e], d[s:e], tri, bvh, tmin=1e-5, tmax=1e30)
+ if bool(hit.any()):
+ fh = face[hit].clamp_min(0)
+ P = o[s:e][hit] + t_hit[hit, None] * d[s:e][hit]
+ bary = _barycentric(P, tri[fh])
+ local = torch.zeros((e - s, 3), device=dev)
+ if render_normal:
+ if vertex_normals is not None:
+ nrm = torch.nn.functional.normalize(
+ (bary[:, :, None] * vertex_normals[faces[fh]]).sum(1), dim=-1, eps=1e-6)
+ else: # face normal, oriented toward camera
+ nrm = torch.nn.functional.normalize(
+ torch.cross(tri[fh][:, 1] - tri[fh][:, 0], tri[fh][:, 2] - tri[fh][:, 0], dim=-1),
+ dim=-1, eps=1e-6)
+ nrm = torch.where((nrm * -d[s:e][hit]).sum(-1, keepdim=True) < 0, -nrm, nrm)
+ nv = torch.stack([(nrm * r).sum(-1), (nrm * u).sum(-1), (nrm * -f).sum(-1)], dim=-1)
+ local[hit] = (nv * 0.5 + 0.5).clamp(0.0, 1.0) # view-space OpenGL normal encode
+ elif texture_hwc is not None and uv is not None:
+ uvh = (bary[:, :, None] * uv[faces[fh]]).sum(1)
+ local[hit] = _sample_image01(texture_hwc, uvh)
+ elif vertex_colors is not None:
+ local[hit] = (bary[:, :, None] * vertex_colors[faces[fh]]).sum(1)
+ else:
+ # Neutral clay, headlight-shaded (|n·view|) so silhouette-plus-form reads, not a flat blob.
+ fn = torch.nn.functional.normalize(
+ torch.cross(tri[fh][:, 1] - tri[fh][:, 0], tri[fh][:, 2] - tri[fh][:, 0], dim=-1),
+ dim=-1, eps=1e-6)
+ ndl = (fn * -d[s:e][hit]).sum(-1).abs().clamp(0.15, 1.0)
+ local[hit] = torch.tensor([0.72, 0.72, 0.72], device=dev) * ndl[:, None]
+ img[s:e] = local
+ dloc = torch.full((e - s,), float("inf"), device=dev)
+ dloc[hit] = t_hit[hit]
+ depth[s:e] = dloc
+ hit_all[s:e] = hit
+ img = img.reshape(H, W, 3)
+ depth = depth.reshape(H, W)
+ hit_all = hit_all.reshape(H, W)
+ # Dilate the object color into the background so bilinear sampling near the silhouette doesn't
+ # bleed black (a cross-view seam source) — and gives the upscaler a coherent, edge-free image.
+ if bool(hit_all.any()) and not bool(hit_all.all()):
+ img = torch.from_numpy(_jfa_fill_gpu(img.cpu().numpy(), hit_all.cpu().numpy())).to(dev)
+ return img, hit_all, depth
+
+
+def _smooth_vertex_normals(vertices_np, faces_np, weld=True):
+ """Area-weighted per-vertex normals (unit length), fully smooth, no vertex splitting."""
+ tris = vertices_np[faces_np] # (M, 3, 3)
+ face_n = np.cross(tris[:, 1] - tris[:, 0], tris[:, 2] - tris[:, 0])
+ if weld and vertices_np.shape[0]:
+ # Group coincident positions (quantized to ~1e-5 of the bbox) into one shared normal.
+ lo = vertices_np.min(0)
+ inv_tol = 1.0 / (max(float((vertices_np.max(0) - lo).max()), 1e-9) * 1e-5)
+ q = np.round((vertices_np - lo) * inv_tol).astype(np.int64)
+ _, group = np.unique(q, axis=0, return_inverse=True)
+ acc = np.zeros((int(group.max()) + 1, 3), dtype=np.float64)
+ for k in range(3):
+ np.add.at(acc, group[faces_np[:, k]], face_n)
+ normals = acc[group] # welded normal back to each vertex
+ else:
+ normals = np.zeros((vertices_np.shape[0], 3), dtype=np.float64)
+ for k in range(3):
+ np.add.at(normals, faces_np[:, k], face_n)
+ lens = np.linalg.norm(normals, axis=1, keepdims=True)
+ normals /= np.where(lens > 1e-12, lens, 1.0)
+ return normals.astype(np.float32)
+
+
+def _compute_vertex_face_normals(vertices_np, faces_np, crease_angle=None):
+ """Compute per-vertex normals, returning (vertices, faces_uint32, normals, remap).
+
+ crease_angle is None (or >= 180) -> fully smooth normals; vertices/faces are
+ returned unchanged and remap is None.
+
+ Otherwise vertices are split along edges whose dihedral angle exceeds
+ crease_angle (degrees) so hard creases stay sharp while smooth regions still
+ interpolate. remap maps each output vertex back to its source index, so the
+ caller can duplicate any per-vertex attributes (uvs / colors) to match."""
+ faces_i = faces_np.astype(np.int64)
+ if crease_angle is None or crease_angle >= 180.0:
+ return (vertices_np, faces_i.astype(np.uint32),
+ _smooth_vertex_normals(vertices_np, faces_i), None)
+
+ M = faces_i.shape[0]
+ tris = vertices_np[faces_i]
+ face_n = np.cross(tris[:, 1] - tris[:, 0], tris[:, 2] - tris[:, 0])
+ areas = np.linalg.norm(face_n, axis=1, keepdims=True)
+ face_unit = face_n / np.where(areas > 1e-12, areas, 1.0)
+ cos_thresh = math.cos(math.radians(crease_angle))
+
+ # Union faces that share an edge whose dihedral angle is below the crease
+ # threshold; each connected component becomes one smoothing group.
+ parent = list(range(M))
+
+ def find(x):
+ while parent[x] != x:
+ parent[x] = parent[parent[x]]
+ x = parent[x]
+ return x
+
+ edge_faces = {}
+ for fi in range(M):
+ a, b, c = int(faces_i[fi, 0]), int(faces_i[fi, 1]), int(faces_i[fi, 2])
+ for u, v in ((a, b), (b, c), (c, a)):
+ edge_faces.setdefault((u, v) if u < v else (v, u), []).append(fi)
+ for fl in edge_faces.values():
+ if len(fl) == 2 and float(np.dot(face_unit[fl[0]], face_unit[fl[1]])) >= cos_thresh:
+ ra, rb = find(fl[0]), find(fl[1])
+ if ra != rb:
+ parent[ra] = rb
+
+ # Emit one output vertex per (original vertex, smoothing group) pair.
+ new_index = {}
+ remap = []
+ out_faces = np.empty((M, 3), dtype=np.int64)
+ for fi in range(M):
+ g = find(fi)
+ for k in range(3):
+ ov = int(faces_i[fi, k])
+ key = (ov, g)
+ ni = new_index.get(key)
+ if ni is None:
+ ni = len(remap)
+ new_index[key] = ni
+ remap.append(ov)
+ out_faces[fi, k] = ni
+
+ remap = np.asarray(remap, dtype=np.int64)
+ normals = np.zeros((remap.shape[0], 3), dtype=np.float64)
+ for k in range(3):
+ np.add.at(normals, out_faces[:, k], face_n)
+ lens = np.linalg.norm(normals, axis=1, keepdims=True)
+ normals /= np.where(lens > 1e-12, lens, 1.0)
+ return (vertices_np[remap], out_faces.astype(np.uint32), normals.astype(np.float32), remap)
+
+
+def _compute_vertex_tangents(verts, faces, uvs, normals):
+ """Per-vertex tangents (Lengyel) orthonormalized against `normals`. Returns [N,4]:
+ unit tangent xyz + handedness w (the bitangent is w * cross(N, T)). Pure torch."""
+ N = verts.shape[0]
+ i0, i1, i2 = faces[:, 0].long(), faces[:, 1].long(), faces[:, 2].long()
+ e1, e2 = verts[i1] - verts[i0], verts[i2] - verts[i0]
+ d1, d2 = uvs[i1] - uvs[i0], uvs[i2] - uvs[i0]
+ denom = d1[:, 0] * d2[:, 1] - d2[:, 0] * d1[:, 1]
+ r = 1.0 / torch.where(denom.abs() < 1e-20, torch.full_like(denom, 1e-20), denom)
+ tan = (d2[:, 1:2] * e1 - d1[:, 1:2] * e2) * r[:, None] # [F,3]
+ bit = (d1[:, 0:1] * e2 - d2[:, 0:1] * e1) * r[:, None]
+ tacc = torch.zeros((N, 3), device=verts.device, dtype=verts.dtype)
+ bacc = torch.zeros((N, 3), device=verts.device, dtype=verts.dtype)
+ for idx in (i0, i1, i2):
+ tacc.scatter_add_(0, idx[:, None].expand(-1, 3), tan)
+ bacc.scatter_add_(0, idx[:, None].expand(-1, 3), bit)
+ n = torch.nn.functional.normalize(normals, dim=-1, eps=1e-6)
+ # Gram-Schmidt: drop the normal component, then renormalize.
+ t = torch.nn.functional.normalize(tacc - n * (n * tacc).sum(-1, keepdim=True), dim=-1, eps=1e-6)
+ w = torch.sign((torch.cross(n, t, dim=-1) * bacc).sum(-1))
+ w = torch.where(w == 0, torch.ones_like(w), w) # degenerate → right-handed
+ return torch.cat([t, w[:, None]], dim=-1)
+
+
+def _vertex_tangents_for_item(lv, lf, uv, low_n_attr_i, dev):
+ """Per-item shading normals + tangents. Shared by the bake (BakeNormalMapFromMesh) and the
+ export attach (ApplyTextureToMesh) so their basis can't diverge. `low_n_attr_i` is the
+ mesh's per-item normals or None (then computed). Returns (low_n [N,3], tangents [N,4])."""
+ low_n = low_n_attr_i.to(dev).float() if low_n_attr_i is not None else _compute_vertex_normals(lv, lf)
+ tangents = _compute_vertex_tangents(lv, lf, uv.to(dev).float(), low_n)
+ return low_n, tangents
+
+
+def _barycentric(p, tri):
+ """Barycentric coords [N,3] of points p [N,3] wrt triangles tri [N,3,3] (per-pair)."""
+ a, b, c = tri[:, 0], tri[:, 1], tri[:, 2]
+ v0, v1, v2 = b - a, c - a, p - a
+ d00 = (v0 * v0).sum(-1)
+ d01 = (v0 * v1).sum(-1)
+ d11 = (v1 * v1).sum(-1)
+ d20 = (v2 * v0).sum(-1)
+ d21 = (v2 * v1).sum(-1)
+ denom = d00 * d11 - d01 * d01
+ denom = torch.where(denom.abs() < 1e-20, torch.full_like(denom, 1e-20), denom)
+ v = (d11 * d20 - d01 * d21) / denom
+ w = (d00 * d21 - d01 * d20) / denom
+ return torch.stack([1.0 - v - w, v, w], dim=-1)
+
+
+def _bake_normal_map(high_v, high_f, high_n, low_v_np, low_f_np, low_uv_np, low_n, tangents,
+ resolution, cage_distance=0.05, ignore_backfaces=True):
+ """Tangent-space normal map (glTF/OpenGL +Y) of the high-poly baked into the low-poly's UV
+ layout. Per texel a cage ray (along the normal, over cage_distance * bbox-diagonal) finds the
+ matching high-poly surface, whose normal is projected into the texel's TBN frame.
+ ignore_backfaces skips surfaces facing away (crevices/enclosures); misses fall back to
+ closest-point. Returns [H,W,3] in [0,1]."""
+ dev = comfy.model_management.get_torch_device()
+ H = W = int(resolution)
+ flat = np.array([0.5, 0.5, 1.0], dtype=np.float32)
+
+ # One rasterization, then interpolate position/normal/tangent/handedness by indexing it.
+ face_idx, bary_uv, mask = _rasterize_uv_barycentric(low_f_np, low_uv_np, resolution)
+ if not mask.any():
+ return np.tile(flat, (H, W, 1))
+ lf = torch.from_numpy(np.ascontiguousarray(low_f_np).astype(np.int64)).to(dev)
+ lv = torch.from_numpy(np.ascontiguousarray(low_v_np, dtype=np.float32)).to(dev)
+ low_n = low_n.to(dev).float()
+ tangents = tangents.to(dev).float()
+ m = mask
+ fsel = face_idx[m] # [K] source face per texel
+ bsel = bary_uv[m] # [K,3]
+ vtri = lf[fsel] # [K,3] vertex ids
+
+ def _interp(attr): # attr [N,C] -> [K,C]
+ return (bsel[:, :, None] * attr[vtri]).sum(1)
+
+ P = _interp(lv) # [K,3] world pos
+ Nl = torch.nn.functional.normalize(_interp(low_n), dim=-1, eps=1e-6)
+ Tl = _interp(tangents[:, :3])
+ Wl = _interp(tangents[:, 3:4])[:, 0]
+
+ hv = high_v.to(dev).float()
+ hf = high_f.to(dev).long()
+ tri = hv[hf]
+ bvh = _build_triangle_bvh(tri)
+
+ # Cage ray-cast: from cage outward, march back along -normal and take the nearest (outermost)
+ # hit. Closest-point is the fallback where the ray misses.
+ diag = float((hv.amax(0) - hv.amin(0)).norm().clamp_min(1e-6))
+ cage = max(1e-6, float(cage_distance) * diag)
+ origin = P + Nl * cage
+ t_hit, f_hit, ray_hit = _closest_hit_rays_bvh(origin, -Nl, tri, bvh, tmin=0.0, tmax=2.0 * cage,
+ cull_backface=bool(ignore_backfaces))
+ bface = f_hit.clamp_min(0)
+ hitpoint = origin - t_hit[:, None] * Nl
+ # Closest-point fallback only for texels the ray missed (usually few) — running it over every
+ # texel wastes a full BVH traversal on the ones already resolved by the ray.
+ miss = ~ray_hit
+ if bool(miss.any()):
+ bp_m, bf_m = _closest_points_on_mesh_bvh(P[miss], tri, bvh, return_face=True)
+ bface = bface.clone()
+ hitpoint = hitpoint.clone()
+ bface[miss] = bf_m.clamp_min(0)
+ hitpoint[miss] = bp_m
+
+ htri = tri[bface] # [K,3,3]
+ bary = _barycentric(hitpoint, htri)
+ hn_tri = high_n.to(dev).float()[hf[bface]] # [K,3,3] vertex normals
+ Nh = torch.nn.functional.normalize((bary[:, :, None] * hn_tri).sum(1), dim=-1, eps=1e-6)
+
+ # Per-texel TBN (Gram-Schmidt tangent against the interpolated normal).
+ T = torch.nn.functional.normalize(Tl - Nl * (Nl * Tl).sum(-1, keepdim=True), dim=-1, eps=1e-6)
+ Bn = Wl[:, None] * torch.cross(Nl, T, dim=-1)
+ nz = (Nh * Nl).sum(-1) # reused as z-channel and the back-face test
+ ts = torch.stack([(Nh * T).sum(-1), (Nh * Bn).sum(-1), nz], dim=-1)
+ ts = torch.nn.functional.normalize(ts, dim=-1, eps=1e-6)
+ # Safety net: if the matched high normal faces away from the texel (a back surface the fallback
+ # grabbed in a deep crevice), use the flat base normal rather than a wrong one.
+ ts[nz < 0.0] = torch.tensor([0.0, 0.0, 1.0], device=dev)
+ enc = ts.mul_(0.5).add_(0.5).clamp_(0.0, 1.0) # encode in place (ts is dead)
+
+ out = torch.from_numpy(np.tile(flat, (H, W, 1))).to(dev)
+ out[m] = enc
+ # Dilate into the UV gutter so bilinear/mip sampling at chart edges doesn't bleed flat blue.
+ return _jfa_fill_gpu(out.cpu().numpy(), mask.cpu().numpy())
+
+
+def _jfa_fill_gpu(img01, mask):
+ """Fill uncovered texels with nearest covered value via GPU Jump Flooding
+ (O(log n) passes; replaces cv2.inpaint). img01 [H,W,C] float, mask [H,W] bool."""
+ if not mask.any():
+ return img01
+ dev = comfy.model_management.get_torch_device()
+ it = torch.from_numpy(np.ascontiguousarray(img01)).to(dev).float()
+ mm = torch.from_numpy(np.ascontiguousarray(mask)).to(dev)
+ H, W = mm.shape
+ yy, xx = torch.meshgrid(torch.arange(H, device=dev), torch.arange(W, device=dev), indexing="ij")
+ by = torch.where(mm, yy, torch.full_like(yy, -1))
+ bx = torch.where(mm, xx, torch.full_like(xx, -1))
+ INF = torch.full_like(yy, 1 << 30)
+ step = 1 << ((max(H, W) - 1).bit_length() - 1)
+ while step >= 1:
+ for dy in (-step, 0, step):
+ for dx in (-step, 0, step):
+ if dy == 0 and dx == 0:
+ continue
+ ny = (yy + dy).clamp(0, H - 1)
+ nx = (xx + dx).clamp(0, W - 1)
+ cby = by[ny, nx]
+ cbx = bx[ny, nx]
+ valid = cby >= 0
+ dc = torch.where(valid, (yy - cby) ** 2 + (xx - cbx) ** 2, INF)
+ db = torch.where(by >= 0, (yy - by) ** 2 + (xx - bx) ** 2, INF)
+ take = valid & (dc < db)
+ by = torch.where(take, cby, by)
+ bx = torch.where(take, cbx, bx)
+ step //= 2
+ filled = it[by.clamp(0).long(), bx.clamp(0).long()]
+ return filled.cpu().numpy()
+
+
+def _seam_fill(img01, mask):
+ """Fill UV-gutter texels (so seams don't pull in black) via JFA nearest-coverage."""
+ return _jfa_fill_gpu(img01, mask)
+
+
+def _normalize_uvs_to_unit(uv_np, normalize=True, log_prefix=None):
+ """Uniformly fit a UV bbox into [0,1] when it spills outside (preserves aspect;
+ no-op if already in [0,1]; not a UDIM de-tiler). Shared deterministic helper —
+ bake and ApplyTextureToMesh both call it so UVs agree (keep both paths in sync).
+ Returns float32 [N,2]."""
+ uv_np = uv_np.astype(np.float32)
+ uv_min = uv_np.min(axis=0)
+ uv_max = uv_np.max(axis=0)
+ out_of_unit = (uv_min.min() < -1e-4) or (uv_max.max() > 1.0001)
+ if not (normalize and out_of_unit):
+ return uv_np
+ extent = float((uv_max - uv_min).max())
+ span = max(float(uv_max[0] - uv_min[0]), float(uv_max[1] - uv_min[1]))
+ if span > 1.5 and log_prefix:
+ logging.warning(
+ f"{log_prefix} UV span {span:.2f} looks like a tiled/UDIM layout; "
+ f"uniform-fitting it into [0,1] will overlap tiles. Re-unwrap upstream instead.")
+ if extent > 0:
+ uv_np = ((uv_np - uv_min) / extent).astype(np.float32)
+ if log_prefix:
+ logging.info(f"{log_prefix} normalized UVs into [0,1] (uniform scale 1/{extent:.4f})")
+ return uv_np
+
+
+def bake_texture_from_voxel_fn(vertices, faces, voxel_coords, voxel_colors,
+ resolution, texture_size, uvs,
+ normalize_uvs=True, reference=None, pbar=None):
+ """Bake a baseColor (+ optional metallicRoughness) texture: rasterize in UV space,
+ sample each texel from the sparse voxel volume. `uvs` (N,2) is the existing layout,
+ 1:1 with `vertices` (never unwraps). Returns (v, f, uvs, texture, mr). Ticks `pbar`
+ once per stage; size it 5 per bake."""
+ # _tick fires once per stage boundary, including no-op stages, so the 5-tick pbar stays aligned.
+ _tq = tqdm(total=5, desc="Bake texture", leave=False)
+
+ def _tick(name):
+ _tq.set_postfix_str(name)
+ _tq.update(1)
+ if pbar is not None:
+ pbar.update(1)
+
+ v_np = vertices.detach().cpu().numpy().astype(np.float32)
+ f_np = faces.detach().cpu().numpy().astype(np.uint32)
+
+ uv_np = uvs.detach().cpu().numpy().astype(np.float32)
+ if uv_np.shape[0] != v_np.shape[0]:
+ raise ValueError(
+ f"BakeTextureFromVoxel: UVs ({uv_np.shape[0]}) must be 1:1 "
+ f"with vertices ({v_np.shape[0]})."
+ )
+ uv_np = _normalize_uvs_to_unit(uv_np, normalize_uvs, log_prefix="[BakeTextureFromVoxel] ")
+ new_verts, new_faces, new_uvs = v_np, f_np, uv_np
+
+ _tick("uvs")
+
+ position_map, mask = _bake_position_map(new_verts, new_faces, new_uvs, texture_size)
+ _tick("rasterize")
+
+ if reference is not None:
+ # Back-project onto the dense surface before sampling (smooth bake on coarse
+ # meshes, not along flat triangle chords).
+ position_map = _back_project_positions(position_map, mask, reference[0], reference[1])
+ _tick("back-project")
+
+ attrs = _sample_voxel_attrs_per_texel(
+ position_map, mask, voxel_coords, voxel_colors, resolution,
+ )
+ _tick("sample")
+
+ # PBR layout (upstream pbr_attr_layout): 0:3 base_color, 3 metallic, 4 roughness, 5 alpha.
+ C = attrs.shape[-1]
+ base_color = attrs[..., 0:3]
+ has_pbr = C >= 5
+ metallic = attrs[..., 3:4] if C >= 4 else None
+ roughness = attrs[..., 4:5] if C >= 5 else None
+ # alpha (idx 5) ignored — meshes kept opaque (upstream OPAQUE alpha_mode).
+
+ base_color = _seam_fill(np.ascontiguousarray(base_color), mask)
+ mr_image = None
+ if has_pbr:
+ # glTF metallicRoughness: R unused, G=roughness, B=metallic.
+ mr = np.concatenate([np.zeros_like(roughness), roughness, metallic], axis=-1)
+ mr_image = _seam_fill(np.ascontiguousarray(mr), mask)
+
+ device = vertices.device
+ out_v = torch.from_numpy(new_verts).to(device=device, dtype=torch.float32)
+ out_f = torch.from_numpy(new_faces.astype(np.int32)).to(device=device, dtype=torch.int32)
+ out_uvs = torch.from_numpy(new_uvs).to(device=device, dtype=torch.float32)
+ out_tex = torch.from_numpy(np.ascontiguousarray(base_color)).to(device=device, dtype=torch.float32)
+ out_mr = (torch.from_numpy(np.ascontiguousarray(mr_image)).to(device=device, dtype=torch.float32)
+ if mr_image is not None else None)
+ _tick("finalize")
+ _tq.close()
+ return out_v, out_f, out_uvs, out_tex, out_mr
+
+
+def _mr_channel(packed_mr, ch, ref):
+ """Pull one channel (G=roughness idx 1, B=metallic idx 2) from a packed glTF MR map
+ as 3-channel grayscale [H,W,3] in [0,1]. Black sized like `ref` if no MR map."""
+ if packed_mr is None:
+ return torch.zeros_like(ref.float().cpu())
+ m = packed_mr.float().clamp(0.0, 1.0).cpu()
+ return m[..., ch:ch + 1].expand(-1, -1, 3).contiguous()
+
+
+class BakeTextureFromVoxel(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="BakeTextureFromVoxel",
+ display_name="Bake Texture From Voxel",
+ category="3d/texturing",
+ description=(
+ "Bakes PBR textures onto the mesh's existing UV layout (trilinear-sample the "
+ "sparse voxel volume). Does NOT unwrap — connect a UV unwrap node upstream. Outputs "
+ "base_color + metallic/roughness grayscale IMAGEs (black if no PBR); feed them to "
+ "ApplyTextureToMesh (SAME mesh) for SaveGLB."
+ ),
+ inputs=[
+ IO.Mesh.Input("mesh"),
+ IO.Voxel.Input("voxel_colors"),
+ IO.Int.Input("texture_size", display_name="resolution", default=2048, min=64, max=8192,
+ tooltip="Square UV atlas resolution."),
+ IO.Mesh.Input("reference_mesh", optional=True,
+ tooltip=(
+ "Optional dense pre-decimation mesh; back-projects each texel onto its "
+ "true surface before sampling, removing faceted baking on coarse meshes.")),
+ ],
+ outputs=[
+ IO.Image.Output(display_name="base_color"),
+ IO.Image.Output(display_name="metallic"),
+ IO.Image.Output(display_name="roughness"),
+ ],
+ )
+
+ @classmethod
+ def execute(cls, mesh, voxel_colors, texture_size, reference_mesh=None):
+ voxels = voxel_colors
+ coords = voxels.data
+ colors = voxels.voxel_colors
+ resolution = voxels.resolution
+ mesh_uvs = mesh.uvs
+ if mesh_uvs is None:
+ raise ValueError(
+ "BakeTextureFromVoxel: input mesh has no UVs. This node bakes onto the "
+ "mesh's existing UV layout and never unwraps — connect a UV unwrap node "
+ "(e.g. Trellis2OfficialUnwrap or TorchXatlasUVWrap) before it.")
+
+ if coords.shape[-1] == 4:
+ # Sparse coords have a batch column; bake per-item.
+ batch_idx = coords[:, 0].long()
+ voxel_xyz = coords[:, 1:]
+ mesh_batch_size = int(mesh.vertices.shape[0])
+ out_tex, out_mr = [], []
+ # 5 ticks per item; skipped items tick all 5 to stay aligned.
+ pbar = comfy.utils.ProgressBar(mesh_batch_size * 5)
+ for i in range(mesh_batch_size):
+ sel = batch_idx == i
+ item_coords = voxel_xyz[sel]
+ item_colors = colors[sel]
+ v_i, f_i, *_ = get_mesh_batch_item(mesh, i)
+ if item_coords.shape[0] == 0 or f_i.numel() == 0:
+ logging.warning(f"BakeTextureFromVoxel: skipping batch {i} (empty voxel/mesh)")
+ pbar.update(5)
+ out_tex.append(torch.zeros((texture_size, texture_size, 3)))
+ out_mr.append(None)
+ continue
+ ev_i = mesh_uvs[i, :v_i.shape[0]]
+ ref_i = None
+ if reference_mesh is not None:
+ ref_index = i if reference_mesh.vertices.shape[0] > 1 else 0
+ rv_i, rf_i, *_ = get_mesh_batch_item(reference_mesh, ref_index)
+ ref_i = (rv_i, rf_i)
+ _bv, _bf, _bu, bt, bmr = bake_texture_from_voxel_fn(
+ v_i, f_i, item_coords, item_colors,
+ resolution=resolution, texture_size=texture_size,
+ uvs=ev_i,
+ reference=ref_i, pbar=pbar,
+ )
+ out_tex.append(bt)
+ out_mr.append(bmr)
+ if not out_tex:
+ # All items skipped — emit one black map so IMAGE outputs stay valid.
+ black = torch.zeros((1, texture_size, texture_size, 3))
+ return IO.NodeOutput(black, black, black)
+ # Stack [B,H,W,3]; split packed MR (G=roughness, B=metallic) into grayscale maps.
+ base_img = torch.stack([t.float().clamp(0.0, 1.0).cpu() for t in out_tex], dim=0)
+ metallic_img = torch.stack([_mr_channel(m, 2, out_tex[0]) for m in out_mr], dim=0)
+ roughness_img = torch.stack([_mr_channel(m, 1, out_tex[0]) for m in out_mr], dim=0)
+ return IO.NodeOutput(base_img, metallic_img, roughness_img)
+
+ # Single-item path.
+ v0 = mesh.vertices.squeeze(0)
+ f0 = mesh.faces.squeeze(0)
+ ev0 = mesh_uvs.squeeze(0)
+ ref0 = None
+ if reference_mesh is not None:
+ ref0 = (reference_mesh.vertices.squeeze(0), reference_mesh.faces.squeeze(0))
+ pbar = comfy.utils.ProgressBar(5) # 5 stage ticks
+ _bv, _bf, _bu, bt, bmr = bake_texture_from_voxel_fn(
+ v0, f0, coords, colors,
+ resolution=resolution, texture_size=texture_size,
+ uvs=ev0,
+ reference=ref0, pbar=pbar,
+ )
+ base_img = bt.float().clamp(0.0, 1.0).cpu().unsqueeze(0)
+ metallic_img = _mr_channel(bmr, 2, bt).unsqueeze(0)
+ roughness_img = _mr_channel(bmr, 1, bt).unsqueeze(0)
+ return IO.NodeOutput(base_img, metallic_img, roughness_img)
+
+
+class MeshTextureToImage(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="MeshTextureToImage",
+ display_name="Mesh Texture to Image",
+ category="3d/texturing",
+ description=(
+ "Extracts a mesh's baked textures as individual IMAGEs: base_color, metallic, "
+ "roughness, occlusion and normal_map. Channels with nothing baked come back "
+ "neutral (occlusion white, normal flat)."
+ ),
+ inputs=[IO.Mesh.Input("mesh")],
+ outputs=[
+ IO.Image.Output(display_name="base_color"),
+ IO.Image.Output(display_name="metallic"),
+ IO.Image.Output(display_name="roughness"),
+ IO.Image.Output(display_name="occlusion"),
+ IO.Image.Output(display_name="normal_map"),
+ ],
+ )
+
+ @classmethod
+ def execute(cls, mesh):
+ def _as_image(tex):
+ # Mesh textures are (B,H,W,3) float [0,1] — already IMAGE layout.
+ if tex is None:
+ return None
+ t = tex.float().clamp(0.0, 1.0).cpu()
+ if t.ndim == 3:
+ t = t.unsqueeze(0)
+ return t
+
+ base = _as_image(mesh.texture)
+ mr = _as_image(mesh.metallic_roughness)
+ normal_map = _as_image(mesh.normal_map)
+
+ if base is None:
+ raise ValueError(
+ "MeshTextureToImage: mesh has no baseColor texture. Run "
+ "BakeTextureFromVoxel first (PaintMesh only sets vertex colors, not a texture)."
+ )
+ if mr is None:
+ mr = torch.zeros_like(base)
+ if normal_map is None:
+ normal_map = torch.ones_like(base) * torch.tensor([0.5, 0.5, 1.0]) # neutral flat normal
+ # Unpack the ORM map (R=occlusion, G=roughness, B=metallic) to 3-channel grayscale.
+ metallic = mr[..., 2:3].expand(-1, -1, -1, 3).contiguous()
+ roughness = mr[..., 1:2].expand(-1, -1, -1, 3).contiguous()
+ # R is real occlusion only if AO was baked; else it's the unused zero channel, which as
+ # "occlusion" would read fully-dark — so report white unless occlusion_in_mr is set.
+ if mesh.occlusion_in_mr:
+ occlusion = mr[..., 0:1].expand(-1, -1, -1, 3).contiguous()
+ else:
+ occlusion = torch.ones_like(base)
+ return IO.NodeOutput(base, metallic, roughness, occlusion, normal_map)
+
+
+class ApplyTextureToMesh(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="ApplyTextureToMesh",
+ display_name="Apply Texture to Mesh",
+ category="3d/texturing",
+ description=(
+ "Attaches baked texture IMAGEs to a mesh's UV layout for SaveGLB. Feed the SAME mesh you baked"
+ ),
+ inputs=[
+ IO.Mesh.Input("mesh"),
+ IO.Image.Input("base_color"),
+ IO.Image.Input("metallic", optional=True),
+ IO.Image.Input("roughness", optional=True),
+ IO.Image.Input("occlusion", optional=True),
+ IO.Image.Input("normal_map", optional=True),
+ ],
+ outputs=[IO.Mesh.Output("mesh")],
+ )
+
+ @classmethod
+ def execute(cls, mesh, base_color, metallic=None, roughness=None, occlusion=None, normal_map=None):
+ mesh_uvs = mesh.uvs
+ if mesh_uvs is None:
+ raise ValueError(
+ "ApplyTextureToMesh: mesh has no UVs. Connect the same UV-unwrapped mesh "
+ "you fed to BakeTextureFromVoxel.")
+
+ # Re-derive the exact UVs the bake used (shared _normalize_uvs_to_unit), per item.
+ if mesh_uvs.ndim == 3:
+ new_uvs = mesh_uvs.clone()
+ for i in range(mesh_uvs.shape[0]):
+ v_i, _f_i, *_ = get_mesh_batch_item(mesh, i)
+ n = v_i.shape[0]
+ norm = _normalize_uvs_to_unit(mesh_uvs[i, :n].detach().cpu().numpy())
+ new_uvs[i, :n] = torch.from_numpy(norm).to(new_uvs)
+ else:
+ norm = _normalize_uvs_to_unit(mesh_uvs.detach().cpu().numpy())
+ new_uvs = torch.from_numpy(norm).to(mesh_uvs)
+
+ out_mesh = copy.copy(mesh)
+ out_mesh.uvs = new_uvs
+ out_mesh.texture = base_color.float().clamp(0.0, 1.0).cpu()
+ if normal_map is not None:
+ # Recompute tangents (shared helper, same normalized UVs → same basis as the bake)
+ # and export the smooth normals the TBN was built on — without a NORMAL attribute the
+ # viewer shades flat and the tangent-space detail fights the faceting.
+ dev = comfy.model_management.get_torch_device()
+ low_n_attr = mesh.normals
+ B = int(mesh.vertices.shape[0])
+ Nmax = int(mesh.vertices.shape[1]) if mesh.vertices.ndim == 3 else int(mesh.vertices.shape[0])
+ tangents_padded = torch.zeros((B, Nmax, 4), dtype=torch.float32)
+ normals_padded = torch.zeros((B, Nmax, 3), dtype=torch.float32)
+ for i in range(B):
+ v_i, f_i, *_ = get_mesh_batch_item(mesh, i)
+ n = int(v_i.shape[0])
+ if f_i.numel() == 0:
+ continue
+ lv, lf = v_i.to(dev).float(), f_i.to(dev).long()
+ uv_i = new_uvs[i, :n] if new_uvs.ndim == 3 else new_uvs[:n]
+ n_attr_i = low_n_attr[i, :n] if low_n_attr is not None else None
+ low_n, tangents = _vertex_tangents_for_item(lv, lf, uv_i, n_attr_i, dev)
+ tangents_padded[i, :n] = tangents.cpu()
+ normals_padded[i, :n] = low_n.cpu()
+ out_mesh.normal_map = normal_map.float().clamp(0.0, 1.0).cpu()
+ out_mesh.tangents = tangents_padded
+ out_mesh.normals = normals_padded
+ if metallic is not None or roughness is not None or occlusion is not None:
+ # Pack glTF ORM (R=occlusion, G=roughness, B=metallic); missing → 1/1/0. Maps may
+ # arrive at different resolutions, so resize each channel to a common H×W first.
+ provided = [x for x in (metallic, roughness, occlusion) if x is not None]
+ B = int(provided[0].shape[0])
+ H = max(int(x.shape[1]) for x in provided)
+ W = max(int(x.shape[2]) for x in provided)
+
+ def _chan(img, default):
+ if img is None:
+ return torch.full((B, H, W, 1), float(default))
+ t = img.float().clamp(0.0, 1.0).cpu()[..., 0:1]
+ if int(t.shape[1]) != H or int(t.shape[2]) != W:
+ t = torch.nn.functional.interpolate(t.permute(0, 3, 1, 2), size=(H, W),
+ mode="bilinear", align_corners=False).permute(0, 2, 3, 1)
+ return t
+
+ out_mesh.metallic_roughness = torch.cat(
+ [_chan(occlusion, 1.0), _chan(roughness, 1.0), _chan(metallic, 0.0)], dim=-1)
+ if occlusion is not None:
+ # Tells SaveGLB to also point occlusionTexture at the MR image (R = AO).
+ out_mesh.occlusion_in_mr = True
+ return IO.NodeOutput(out_mesh)
+
+
+class BakeNormalMapFromMesh(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="BakeNormalMapFromMesh",
+ display_name="Bake Normal Map from Mesh",
+ category="3d/texturing",
+ description=(
+ "Bakes a tangent-space normal map (glTF/OpenGL +Y) from a high-poly mesh into a "
+ "low-poly's UV layout, capturing detail lost during decimation. Feed the UV-unwrapped "
+ "low_poly and the high_poly it was decimated from. Outputs an image for "
+ "Apply Texture To Mesh's normal_map input."
+ ),
+ inputs=[
+ IO.Mesh.Input("low_poly"),
+ IO.Mesh.Input("high_poly"),
+ IO.Int.Input("resolution", default=1024, min=64, max=8192, step=64,
+ display_name="resolution"),
+ IO.Float.Input("cage_distance", default=0.05, min=0.001, max=0.5, step=0.001,
+ tooltip="Surface search band, as a fraction of the bounding box diagonal. "
+ "Raise for wrong/missing patches under heavy decimation; "
+ "lower if it grabs across gaps."),
+ IO.Boolean.Input("ignore_backfaces", default=True,
+ tooltip="Skip high-poly surfaces facing away from the texel, so "
+ "crevices/enclosed spaces don't grab the opposite wall. "
+ "Disable only if the high-poly winding is inconsistent."),
+ ],
+ outputs=[IO.Image.Output(display_name="normal_map")],
+ )
+
+ @classmethod
+ def execute(cls, low_poly, high_poly, resolution, cage_distance=0.05, ignore_backfaces=True):
+ low_uvs = low_poly.uvs
+ if low_uvs is None:
+ raise ValueError(
+ "BakeNormalMapFromMesh: low_poly has no UVs. Connect the UV-unwrapped "
+ "low-poly (the same one you fed to BakeTextureFromVoxel); this node bakes "
+ "onto existing UVs and never unwraps.")
+ dev = comfy.model_management.get_torch_device()
+
+ low_n_attr = low_poly.normals
+ high_n_attr = high_poly.normals
+ B = int(low_poly.vertices.shape[0])
+ h_batch = int(high_poly.vertices.shape[0])
+
+ imgs = []
+ for i in range(B):
+ v_i, f_i, *_ = get_mesh_batch_item(low_poly, i)
+ n = int(v_i.shape[0])
+ if f_i.numel() == 0:
+ logging.warning(f"BakeNormalMapFromMesh: skipping batch {i} (empty mesh)")
+ imgs.append(torch.full((int(resolution), int(resolution), 3), 0.5))
+ continue
+
+ uv_i = low_uvs[i, :n] if low_uvs.ndim == 3 else low_uvs[:n]
+ uv_np = _normalize_uvs_to_unit(uv_i.detach().cpu().numpy(), log_prefix="[BakeNormalMapFromMesh] ")
+
+ lv = v_i.to(dev).float()
+ lf = f_i.to(dev).long()
+ # Tangents build the per-texel TBN; ApplyTextureToMesh recomputes the same basis on export.
+ n_attr_i = low_n_attr[i, :n] if low_n_attr is not None else None
+ low_n, tangents = _vertex_tangents_for_item(lv, lf, torch.from_numpy(uv_np).to(dev), n_attr_i, dev)
+
+ hv_i, hf_i, *_ = get_mesh_batch_item(high_poly, i if h_batch > 1 else 0)
+ hv = hv_i.to(dev).float()
+ hf = hf_i.to(dev).long()
+ high_n = (high_n_attr[i, :hv.shape[0]].to(dev).float() if high_n_attr is not None
+ else _compute_vertex_normals(hv, hf))
+
+ img = _bake_normal_map(
+ hv, hf, high_n,
+ lv.detach().cpu().numpy(), lf.detach().cpu().numpy().astype(np.uint32), uv_np,
+ low_n, tangents, resolution, cage_distance=float(cage_distance),
+ ignore_backfaces=bool(ignore_backfaces),
+ )
+ imgs.append(torch.from_numpy(np.ascontiguousarray(img)).float())
+
+ normal_img = torch.stack([t.clamp(0.0, 1.0) for t in imgs], dim=0)
+ return IO.NodeOutput(normal_img)
+
+
+class BakeAmbientOcclusion(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="BakeAmbientOcclusion",
+ display_name="Bake Ambient Occlusion",
+ category="3d/texturing",
+ description=(
+ "Bakes an ambient-occlusion map from a high-poly mesh into a low-poly's UV "
+ "layout (white = open, dark = crevices). Feed the UV-unwrapped low_poly and the "
+ "high_poly it was decimated from. Outputs a grayscale image for "
+ "Apply Texture To Mesh's occlusion input (packed into the ORM map / occlusionTexture)."
+ ),
+ inputs=[
+ IO.Mesh.Input("low_poly"),
+ IO.Mesh.Input("high_poly"),
+ IO.Int.Input("resolution", default=1024, min=64, max=8192, step=64),
+ IO.Int.Input("samples", default=64, min=4, max=1024, step=4,
+ tooltip="Rays per texel. More = smoother, slower. Raise if grainy."),
+ IO.Float.Input("max_distance", default=0.5, min=0.01, max=2.0, step=0.01,
+ tooltip="Ray length, as a fraction of the bounding box diagonal. "
+ "Smaller = tighter, more local occlusion."),
+ IO.Float.Input("strength", default=1.0, min=0.0, max=2.0, step=0.05,
+ tooltip="Scales the occlusion. >1 darkens, <1 lightens."),
+ IO.Float.Input("bias", default=0.01, min=0.0001, max=0.2, step=0.0005,
+ tooltip="Ray origin lift off the surface, as a fraction of the bounding box "
+ "diagonal. Raise if even surfaces show dark blotches/holes."),
+ ],
+ outputs=[IO.Image.Output(display_name="occlusion")],
+ )
+
+ @classmethod
+ def execute(cls, low_poly, high_poly, resolution, samples, max_distance, strength, bias):
+ low_uvs = low_poly.uvs
+ if low_uvs is None:
+ raise ValueError(
+ "BakeAmbientOcclusion: low_poly has no UVs. Connect the UV-unwrapped low-poly "
+ "(the same one used for the other bakes); this node never unwraps.")
+ dev = comfy.model_management.get_torch_device()
+ low_n_attr = low_poly.normals
+ B = int(low_poly.vertices.shape[0])
+ h_batch = int(high_poly.vertices.shape[0])
+
+ # Absolute 0-1000 bar; each batch item owns a slice, filled as its ray chunks complete.
+ pbar = comfy.utils.ProgressBar(1000)
+ imgs = []
+ for i in range(B):
+ lo, hi = (1000 * i) // B, (1000 * (i + 1)) // B
+ v_i, f_i, *_ = get_mesh_batch_item(low_poly, i)
+ n = int(v_i.shape[0])
+ if f_i.numel() == 0:
+ logging.warning(f"BakeAmbientOcclusion: skipping batch {i} (empty mesh)")
+ imgs.append(torch.ones((int(resolution), int(resolution), 3)))
+ pbar.update_absolute(hi, 1000)
+ continue
+
+ uv_i = low_uvs[i, :n] if low_uvs.ndim == 3 else low_uvs[:n]
+ uv_np = _normalize_uvs_to_unit(uv_i.detach().cpu().numpy(), log_prefix="[BakeAmbientOcclusion] ")
+ lv = v_i.to(dev).float()
+ lf = f_i.to(dev).long()
+ low_n = (low_n_attr[i, :n].to(dev).float() if low_n_attr is not None
+ else _compute_vertex_normals(lv, lf))
+
+ hv_i, hf_i, *_ = get_mesh_batch_item(high_poly, i if h_batch > 1 else 0)
+ img = _bake_ambient_occlusion(
+ hv_i.to(dev).float(), hf_i.to(dev).long(),
+ lv.detach().cpu().numpy(), lf.detach().cpu().numpy().astype(np.uint32), uv_np,
+ low_n, resolution, num_samples=int(samples),
+ max_distance=float(max_distance), strength=float(strength), bias=float(bias),
+ pbar=pbar, pbar_range=(lo, hi),
+ )
+ imgs.append(torch.from_numpy(np.ascontiguousarray(img)).float())
+ pbar.update_absolute(hi, 1000)
+
+ ao_img = torch.stack([t.clamp(0.0, 1.0) for t in imgs], dim=0)
+ return IO.NodeOutput(ao_img)
+
+
+class RenderMesh(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="RenderMesh",
+ display_name="Render Mesh",
+ search_aliases=["mesh to image", "render mesh", "preview textured mesh"],
+ category="3d/mesh",
+ description=(
+ "Ray-casts a single view of a mesh. The camera and optional model transform can come "
+ "from a Load3D / Preview3D viewer."
+ ),
+ inputs=[
+ IO.Mesh.Input("mesh"),
+ IO.Combo.Input("mode", options=["auto", "texture", "vertex colors", "solid", "normal", "depth"],
+ tooltip="What to render. auto: texture if present, else vertex colours, else shaded clay."),
+ IO.Int.Input("width", default=1024, min=64, max=4096, step=8),
+ IO.Int.Input("height", default=1024, min=64, max=4096, step=8),
+ IO.Color.Input("background", default="#000000"),
+ IO.Load3DModelInfo.Input("model_3d_info", optional=True,
+ tooltip="Model transform from the same Load3D / Preview3D viewer. "
+ "Connect it with camera_info to match the viewer framing."),
+ IO.Load3DCamera.Input("camera_info", optional=True,
+ tooltip="Camera from a Load3D / Preview3D viewer or a Create Camera Info "
+ "node. If none is connected, a default front view is auto-framed."),
+ ],
+ outputs=[IO.Image.Output(display_name="image"), IO.Mask.Output(display_name="mask")],
+ )
+
+ @classmethod
+ def execute(cls, mesh, mode, width, height, background, model_3d_info=None, camera_info=None):
+ if int(mesh.vertices.shape[0]) > 1:
+ logging.warning("RenderMesh: one item per batch only; using the first of %d.", int(mesh.vertices.shape[0]))
+ dev = comfy.model_management.get_torch_device()
+ v_i, f_i, *_ = get_mesh_batch_item(mesh, 0)
+ n = int(v_i.shape[0])
+ lv = v_i.to(dev).float()
+ lf = f_i.to(dev).long()
+ model_transform = model_3d_info[0] if model_3d_info else None
+ if model_transform is not None:
+ lv = _apply_model_transform(lv, model_transform)
+
+ def _item(attr): # first-item, length-n view of a mesh attr
+ a = getattr(mesh, attr, None)
+ if a is None:
+ return None
+ return (a[0] if (isinstance(a, list) or a.ndim == 3) else a)[:n].to(dev).float()
+
+ tex, uvs = mesh.texture, mesh.uvs
+ have_tex = tex is not None and uvs is not None
+ have_vc = getattr(mesh, "vertex_colors", None) is not None
+ resolved = mode
+ if resolved == "auto":
+ resolved = "texture" if have_tex else ("vertex colors" if have_vc else "solid")
+
+ uv = texture_hwc = vcols = vnorms = None
+ render_normal = False
+ if resolved == "texture" and have_tex:
+ uv = (uvs[0, :n] if uvs.ndim == 3 else uvs[:n]).to(dev).float()
+ texture_hwc = tex[0].to(dev).float()
+ elif resolved == "vertex colors" and have_vc:
+ # glTF COLOR_0 is linear (PaintMesh stores pow(srgb, 2.2)); to sRGB so it isn't dark.
+ vcols = _item("vertex_colors")[:, :3].clamp(0.0, 1.0).pow(1.0 / 2.2)
+ elif resolved == "normal":
+ render_normal = True
+ vnorms = _item("normals") # smooth if present, else face normals
+ if vnorms is not None and model_transform is not None:
+ vnorms = _apply_model_transform(vnorms, model_transform, is_normal=True)
+
+ tri = lv[lf]
+ bvh = _build_triangle_bvh(tri)
+ center = (lv.amax(0) + lv.amin(0)) * 0.5
+ up_hint = torch.tensor([0.0, 1.0, 0.0], device=dev)
+
+ if camera_info is not None:
+ # Explicit camera from a Load3D / Preview3D viewer (three.js Y-up, same frame as the mesh).
+ def _vec(d):
+ return torch.tensor([float(d.get("x", 0.0)), float(d.get("y", 0.0)), float(d.get("z", 0.0))],
+ device=dev)
+ eye = _vec(camera_info.get("position", {}))
+ tgt = camera_info.get("target")
+ target = _vec(tgt) if tgt else center
+ f, r, u = _camera_basis(eye, target, up_hint) # look-at (roll-free)
+ cam_fov = float(camera_info.get("fov", 0) or 0) or 40.0
+ cam_zoom = float(camera_info.get("zoom", 1.0) or 1.0) # three.js digital zoom scales focal length
+ fov_rad = 2.0 * math.atan(math.tan(math.radians(cam_fov) * 0.5) / max(cam_zoom, 1e-3))
+ else:
+ # No camera connected, auto-framed default front view.
+ fov_rad = math.radians(40.0)
+ r_sphere = float((lv - center).norm(dim=-1).amax().clamp_min(1e-6))
+ radius = r_sphere / math.tan(fov_rad * 0.5) * 1.04
+ eye = center + torch.tensor([0.0, 0.0, 1.0], device=dev) * radius
+ f, r, u = _camera_basis(eye, center, up_hint)
+
+ H, W = int(height), int(width)
+ img, hit, depth = _render_view(tri, bvh, uv, lf, texture_hwc, eye, f, r, u, fov_rad, H, W,
+ vertex_colors=vcols, vertex_normals=vnorms, render_normal=render_normal)
+
+ if resolved == "depth":
+ img = torch.zeros_like(img)
+ if bool(hit.any()):
+ dh = depth[hit]
+ rng = max(float(dh.max()) - float(dh.min()), 1e-6)
+ norm = ((float(dh.max()) - depth) / rng).clamp(0.0, 1.0) # near (small depth) = white
+ img = torch.where(hit[..., None], norm[..., None].expand(-1, -1, 3), img)
+
+ bg = background.lstrip("#")
+ bg_rgb = torch.tensor([int(bg[i:i + 2], 16) / 255.0 for i in (0, 2, 4)], device=dev)
+ out = torch.where(hit[..., None], img.clamp(0.0, 1.0), bg_rgb)
+ idev, idtype = comfy.model_management.intermediate_device(), comfy.model_management.intermediate_dtype()
+ return IO.NodeOutput(out[None].to(idev, idtype), hit.float()[None].to(idev, idtype))
+
+
+def _fill_holes_v2_gpu(verts, faces, max_perimeter, colors=None, fill_chains=False, max_verts=16):
+ # Bidirectional (not pointer-doubling) CC labeling so low-id chains propagate
+ # backward. Cycles-only by default; fill_chains=True opts into noisy chain fills.
+ device = verts.device
+ V = verts.shape[0]
+ dtype = verts.dtype
+
+ e_all = torch.cat([faces[:, [0, 1]], faces[:, [1, 2]], faces[:, [2, 0]]], dim=0)
+ e_sorted, _ = e_all.sort(dim=1)
+ packed = e_sorted[:, 0].long() * V + e_sorted[:, 1].long()
+ unique_packed, counts = torch.unique(packed, return_counts=True)
+ boundary_packed = unique_packed[counts == 1]
+ if boundary_packed.numel() == 0:
+ return verts, faces, colors, 0
+ is_b = torch.isin(packed, boundary_packed)
+
+ b_directed = e_all[is_b]
+ src = b_directed[:, 0].long()
+ tgt = b_directed[:, 1].long()
+
+ # Undirected bidirectional min-prop with path compression.
+ labels = torch.arange(V, dtype=torch.long, device=device)
+ for _ in range(64):
+ edge_min = torch.minimum(labels[src], labels[tgt])
+ new_labels = labels.clone()
+ new_labels.scatter_reduce_(0, src, edge_min, reduce="amin", include_self=True)
+ new_labels.scatter_reduce_(0, tgt, edge_min, reduce="amin", include_self=True)
+ new_labels = new_labels[new_labels] # path compression
+ if torch.equal(new_labels, labels):
+ break
+ labels = new_labels
+
+ # After bidir-prop, labels[src] == labels[tgt], so labels[src] is the edge's component.
+ edge_component = labels[src]
+ unique_components, component_idx = torch.unique(edge_component, return_inverse=True)
+ L = unique_components.shape[0]
+ edge_count = torch.bincount(component_idx, minlength=L)
+ edge_len = (verts[src] - verts[tgt]).norm(dim=-1)
+ perim = torch.zeros(L, dtype=dtype, device=device)
+ perim.scatter_add_(0, component_idx, edge_len)
+
+ # Unique boundary verts per component, via packed (comp,vert) keys.
+ pair_keys = torch.cat([
+ component_idx.long() * V + src,
+ component_idx.long() * V + tgt,
+ ])
+ pair_keys = torch.unique(pair_keys)
+ pair_v = pair_keys % V
+ pair_c = pair_keys // V
+ vert_count = torch.bincount(pair_c, minlength=L)
+
+ centroids = torch.zeros((L, 3), dtype=dtype, device=device)
+ centroids.scatter_add_(0, pair_c[:, None].expand(-1, 3), verts[pair_v])
+ centroids = centroids / vert_count.clamp_min(1).to(dtype).unsqueeze(-1)
+
+ # Closed cycle ⇔ every boundary vert has degree 2 ⇔ vert_count == edge_count.
+ is_cycle_component = (vert_count == edge_count) & (vert_count > 0)
+
+ # Keep cycles (and chains if fill_chains) under perim/vert limits; centroid-fan
+ # only works for small near-planar holes (else centroid lands off-surface → overlap).
+ size_ok = (vert_count >= 3) & (vert_count <= max_verts) & (perim < max_perimeter)
+ if fill_chains:
+ keep_component = size_ok
+ else:
+ keep_component = is_cycle_component & size_ok
+ if not keep_component.any():
+ return verts, faces, colors, 0
+ # Only centroid-fan components allocate a new vertex (threshold mirrored below).
+ use_centroid_per_comp_pre = keep_component & (vert_count > 8)
+ centroid_long = use_centroid_per_comp_pre.long()
+ centroid_idx_per_comp = V + centroid_long.cumsum(0) - 1
+
+ # vertex-fan (small cycles): boundary vert as apex, on-surface. centroid-fan (large):
+ # insert centroid (near-planar only, but avoids skinny tris on big holes).
+ CENTROID_FAN_THRESHOLD = 8
+
+ edge_kept = keep_component[component_idx]
+ edge_comp = component_idx[edge_kept]
+ kept_src = src[edge_kept]
+ kept_tgt = tgt[edge_kept]
+
+ use_centroid_per_comp = keep_component & (vert_count > CENTROID_FAN_THRESHOLD)
+ use_centroid_per_edge = use_centroid_per_comp[edge_comp]
+
+ fan_pieces = []
+ # Centroid-fan branch
+ if use_centroid_per_edge.any():
+ kept_centroid = centroid_idx_per_comp[edge_comp[use_centroid_per_edge]]
+ fan_pieces.append(torch.stack([
+ kept_tgt[use_centroid_per_edge],
+ kept_src[use_centroid_per_edge],
+ kept_centroid,
+ ], dim=1).to(faces.dtype))
+
+ # Vertex-fan branch (small cycles)
+ use_vertex_fan_per_comp = keep_component & (vert_count <= CENTROID_FAN_THRESHOLD)
+ if use_vertex_fan_per_comp.any():
+ # Apex = smallest-id boundary vert; fan (apex, src, tgt) skipping apex-incident edges.
+ apex_per_comp = labels[unique_components]
+ vf_mask = use_vertex_fan_per_comp[edge_comp]
+ if vf_mask.any():
+ vf_src = kept_src[vf_mask]
+ vf_tgt = kept_tgt[vf_mask]
+ vf_comp = edge_comp[vf_mask]
+ vf_apex = apex_per_comp[vf_comp]
+ non_apex = (vf_src != vf_apex) & (vf_tgt != vf_apex)
+ fan_pieces.append(torch.stack([
+ vf_tgt[non_apex], vf_src[non_apex], vf_apex[non_apex],
+ ], dim=1).to(faces.dtype))
+
+ fan_faces = torch.cat(fan_pieces, dim=0) if fan_pieces else torch.empty((0, 3), dtype=faces.dtype, device=device)
+
+ # Close open chains (centroid-fan only; no-op when fill_chains=False).
+ if fill_chains:
+ vert_degree = torch.zeros(V, dtype=torch.long, device=device)
+ vert_degree.scatter_add_(0, src, torch.ones_like(src))
+ vert_degree.scatter_add_(0, tgt, torch.ones_like(tgt))
+ is_endpoint = (vert_degree[pair_v] == 1) & use_centroid_per_comp_pre[pair_c]
+ if is_endpoint.any():
+ ep_v = pair_v[is_endpoint]
+ ep_c = pair_c[is_endpoint]
+ order = torch.argsort(ep_c, stable=True)
+ ep_v_sorted = ep_v[order]
+ ep_c_sorted = ep_c[order]
+ ep_count_per_c = torch.bincount(ep_c_sorted, minlength=L)
+ is_chain_comp = ep_count_per_c == 2
+ ep_is_chain = is_chain_comp[ep_c_sorted]
+ if ep_is_chain.any():
+ chain_ep_v = ep_v_sorted[ep_is_chain]
+ chain_ep_c = ep_c_sorted[ep_is_chain]
+ assert chain_ep_v.numel() % 2 == 0
+ chain_ep_v = chain_ep_v.view(-1, 2)
+ chain_ep_c = chain_ep_c.view(-1, 2)[:, 0]
+ close_centroid = centroid_idx_per_comp[chain_ep_c]
+ close_faces = torch.stack(
+ [chain_ep_v[:, 0], chain_ep_v[:, 1], close_centroid], dim=1
+ ).to(faces.dtype)
+ fan_faces = torch.cat([fan_faces, close_faces], dim=0)
+
+ # Only centroid-fan components contribute a new vertex; vertex-fan reuses existing.
+ new_centroids_v = centroids[use_centroid_per_comp_pre]
+ out_v = torch.cat([verts, new_centroids_v], dim=0)
+ out_f = torch.cat([faces, fan_faces], dim=0)
+
+ out_c = colors
+ if colors is not None:
+ c_sum = torch.zeros((L, colors.shape[1]), dtype=colors.dtype, device=device)
+ c_sum.scatter_add_(
+ 0, pair_c[:, None].expand(-1, colors.shape[1]), colors[pair_v])
+ c_avg = c_sum / vert_count.clamp_min(1).to(colors.dtype).unsqueeze(-1)
+ out_c = torch.cat([colors, c_avg[use_centroid_per_comp_pre]], dim=0)
+
+ return out_v, out_f, out_c, int(keep_component.sum().item())
+
+
+def weld_vertices_fn(vertices, faces, epsilon=None, epsilon_rel=1e-5, colors=None):
+ """Merge coincident vertices via L_inf grid quantization. `epsilon` absolute (None →
+ epsilon_rel*bbox_diag); colors averaged per cluster. Returns (v, f, colors, n_welded)."""
+ if vertices.ndim == 3:
+ v_out, f_out, c_out = [], [], [] if colors is not None else None
+ total = 0
+ for i in range(vertices.shape[0]):
+ ci = colors[i] if colors is not None else None
+ v_i, f_i, c_i, n = weld_vertices_fn(vertices[i], faces[i], epsilon, epsilon_rel, ci)
+ v_out.append(v_i)
+ f_out.append(f_i)
+ total += n
+ if c_out is not None:
+ c_out.append(c_i)
+ max_v = max(v.shape[0] for v in v_out)
+ for i in range(len(v_out)):
+ pad_n = max_v - v_out[i].shape[0]
+ if pad_n > 0:
+ v_out[i] = torch.cat([v_out[i],
+ torch.zeros(pad_n, 3, device=v_out[i].device, dtype=v_out[i].dtype)], dim=0)
+ if c_out is not None:
+ c_out[i] = torch.cat([c_out[i],
+ torch.zeros(pad_n, c_out[i].shape[1], device=c_out[i].device, dtype=c_out[i].dtype)], dim=0)
+ c_stack = torch.stack(c_out) if c_out is not None else None
+ return torch.stack(v_out), torch.stack(f_out), c_stack, total
+
+ if vertices.shape[0] == 0:
+ return vertices, faces, colors, 0
+ device = vertices.device
+ if epsilon is None:
+ bbox = vertices.max(dim=0)[0] - vertices.min(dim=0)[0]
+ eps = torch.norm(bbox) * float(epsilon_rel)
+ eps = max(float(eps.item()), 1e-12)
+ else:
+ eps = float(epsilon)
+ if eps <= 0:
+ return vertices, faces, colors, 0
+
+ scale = 1.0 / eps
+ bbox_min = vertices.min(dim=0)[0]
+ q = ((vertices - bbox_min) * scale).round().to(torch.int64)
+ extent = ((vertices.max(dim=0)[0] - bbox_min) * scale).round().to(torch.int64) + 2
+ key = (q[:, 0] * extent[1] + q[:, 1]) * extent[2] + q[:, 2]
+ unique_key, inv = torch.unique(key, return_inverse=True)
+ n_unique = unique_key.shape[0]
+ if n_unique == vertices.shape[0]:
+ return vertices, faces, colors, 0
+
+ counts = torch.zeros(n_unique, dtype=vertices.dtype, device=device)
+ counts.scatter_add_(0, inv, torch.ones(vertices.shape[0], dtype=vertices.dtype, device=device))
+ counts_div = counts.unsqueeze(-1).clamp_min(1.0)
+
+ new_verts = torch.zeros((n_unique, 3), dtype=vertices.dtype, device=device)
+ new_verts.scatter_add_(0, inv.unsqueeze(-1).expand_as(vertices), vertices)
+ new_verts = new_verts / counts_div
+
+ new_colors = None
+ if colors is not None:
+ new_colors = torch.zeros((n_unique, colors.shape[1]), dtype=colors.dtype, device=device)
+ new_colors.scatter_add_(0, inv.unsqueeze(-1).expand_as(colors), colors)
+ new_colors = new_colors / counts_div.to(colors.dtype)
+
+ new_faces = inv[faces.long()].to(faces.dtype) if faces.numel() > 0 else faces
+ return new_verts, new_faces, new_colors, int(vertices.shape[0] - n_unique)
+
+
+def fill_holes_v2_fn(vertices, faces, max_perimeter=0.03, colors=None, weld_epsilon_rel=1e-5, fill_chains=False, max_verts=16):
+ """Batched v2 GPU hole-filler. Pre-welds verts first as boundary detection needs shared edges"""
+ if vertices.ndim == 3:
+ v_list, f_list, c_list = [], [], [] if colors is not None else None
+ pbar = comfy.utils.ProgressBar(vertices.shape[0])
+ for i in range(vertices.shape[0]):
+ ci = colors[i] if colors is not None else None
+ v_i, f_i, c_i = fill_holes_v2_fn(vertices[i], faces[i], max_perimeter, ci, weld_epsilon_rel, fill_chains, max_verts)
+ v_list.append(v_i)
+ f_list.append(f_i)
+ if c_list is not None:
+ c_list.append(c_i)
+ pbar.update(1)
+ max_v = max(v.shape[0] for v in v_list)
+ for i in range(len(v_list)):
+ pad_n = max_v - v_list[i].shape[0]
+ if pad_n > 0:
+ v_list[i] = torch.cat([v_list[i],
+ torch.zeros(pad_n, 3, device=v_list[i].device, dtype=v_list[i].dtype)], dim=0)
+ if c_list is not None:
+ c_list[i] = torch.cat([c_list[i],
+ torch.zeros(pad_n, c_list[i].shape[1], device=c_list[i].device, dtype=c_list[i].dtype)], dim=0)
+ c_out = torch.stack(c_list) if c_list is not None else None
+ return torch.stack(v_list), torch.stack(f_list), c_out
+
+ if faces.numel() == 0:
+ return vertices, faces, colors
+ # Adaptive weld: welded surfaces have V/F ≈ 0.5-1.0; V/F > 1 means unwelded (hole-fill
+ # would emit a bogus tri per face). Double epsilon until V/F < WELDED_THRESHOLD or WELD_CAP.
+ if weld_epsilon_rel > 0:
+ eps = float(weld_epsilon_rel)
+ WELD_CAP = 1e-2 # ≈ 10 voxels at 1024-res
+ WELDED_THRESHOLD = 1.0 # V/F below this is welded enough
+ total_welded = 0
+ n_escalations = 0
+ while True:
+ vertices, faces, colors, n = weld_vertices_fn(
+ vertices, faces, epsilon=None, epsilon_rel=eps, colors=colors,
+ )
+ total_welded += n
+ ratio = vertices.shape[0] / max(faces.shape[0], 1)
+ if ratio < WELDED_THRESHOLD or eps >= WELD_CAP:
+ break
+ eps = min(eps * 2.0, WELD_CAP)
+ n_escalations += 1
+ if total_welded > 0 or n_escalations > 0:
+ tag = f" (escalated weld epsilon_rel→{eps:.1e} after {n_escalations} step{'s' if n_escalations != 1 else ''})" if n_escalations > 0 else ""
+ logging.info(f"[FillHoles] pre-welded {total_welded} verts, V/F={ratio:.2f}{tag}")
+ if ratio >= WELDED_THRESHOLD:
+ logging.warning(
+ f"[FillHoles] even at weld epsilon_rel={WELD_CAP} the mesh stays "
+ f"unwelded (V/F={ratio:.2f}, want < {WELDED_THRESHOLD}). Source mesh has "
+ f"duplicate verts at distances >{WELD_CAP}× bbox; fix upstream "
+ f"(decimate node settings) or run WeldVertices manually with a larger epsilon."
+ )
+ dev = comfy.model_management.get_torch_device()
+ out_v, out_f, out_c, _ = _fill_holes_v2_gpu(
+ vertices.to(dev), faces.to(dev), max_perimeter,
+ colors.to(dev) if colors is not None else None, fill_chains, max_verts)
+ return out_v, out_f, out_c
+
+
+def _process_mesh_batch(mesh, per_item_fn):
+ """Dispatch list/batched/single mesh, extract colors, stack results."""
+ mesh = copy.deepcopy(mesh)
+
+ def process_single(v, f, c, bar):
+ v, f, c = per_item_fn(v, f, c)
+ bar.update(1)
+ return v, f, c
+
+ is_list = isinstance(mesh.vertices, list)
+ is_batched_tensor = not is_list and mesh.vertices.ndim == 3
+
+ if is_list or is_batched_tensor:
+ out_v, out_f, out_c = [], [], []
+ bsz = len(mesh.vertices) if is_list else mesh.vertices.shape[0]
+ bar = comfy.utils.ProgressBar(bsz)
+
+ for i in range(bsz):
+ if is_batched_tensor:
+ v_i, f_i, c_i, _, _ = get_mesh_batch_item(mesh, i)
+ else:
+ v_i = mesh.vertices[i]
+ f_i = mesh.faces[i]
+ c_i = None
+ if mesh.vertex_colors is not None:
+ c_i = mesh.vertex_colors[i] if isinstance(mesh.vertex_colors, list) else mesh.vertex_colors
+
+ v_i, f_i, c_i = process_single(v_i, f_i, c_i, bar)
+
+ out_v.append(v_i)
+ out_f.append(f_i)
+ if c_i is not None:
+ out_c.append(c_i)
+
+ if is_batched_tensor:
+ packed = pack_variable_mesh_batch(out_v, out_f, out_c if len(out_c) == bsz else None)
+ mesh.vertices = packed.vertices
+ mesh.faces = packed.faces
+ mesh.vertex_colors = packed.vertex_colors
+ mesh.vertex_counts = packed.vertex_counts
+ mesh.face_counts = packed.face_counts
+ mesh.uvs = None
+ mesh.normals = None
+ mesh.tangents = None
+ elif all(v.shape == out_v[0].shape for v in out_v) and all(f.shape == out_f[0].shape for f in out_f):
+ mesh.vertices = torch.stack(out_v)
+ mesh.faces = torch.stack(out_f)
+ if out_c:
+ mesh.vertex_colors = torch.stack(out_c)
+ else:
+ mesh.vertices = out_v
+ mesh.faces = out_f
+ if out_c:
+ mesh.vertex_colors = out_c
+ else:
+ c = mesh.vertex_colors if hasattr(mesh, 'vertex_colors') and mesh.vertex_colors is not None else None
+ bar = comfy.utils.ProgressBar(1)
+ v, f, c = process_single(mesh.vertices, mesh.faces, c, bar)
+ mesh.vertices = v
+ mesh.faces = f
+ if c is not None:
+ mesh.vertex_colors = c
+
+ return IO.NodeOutput(mesh)
+
+
+def _fmt_count(n) -> str:
+ """Compact integer for status lines, e.g. 853, 12.3K, 1.23M."""
+ n = int(n)
+ if n >= 1_000_000:
+ return f"{n / 1_000_000:.2f}".rstrip("0").rstrip(".") + "M"
+ if n >= 1_000:
+ return f"{n / 1_000:.1f}".rstrip("0").rstrip(".") + "K"
+ return str(n)
+
+
+def _fmt_face_change(n_in, n_out) -> str:
+ """'faces: 1.23M → 200K (-84%)' — the count delta for decimate/remesh status."""
+ n_in, n_out = int(n_in), int(n_out)
+ pct = f" ({(n_out - n_in) / n_in * 100:+.0f}%)" if n_in else ""
+ return f"faces: {_fmt_count(n_in)} → {_fmt_count(n_out)}{pct}"
+
+
+class DecimateMesh(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ # qem sub-widgets show only when 'qem' is selected (DynamicCombo).
+ placement_options = [
+ IO.DynamicCombo.Option(key="midpoint", inputs=[]),
+ IO.DynamicCombo.Option(key="qem", inputs=[
+ IO.Float.Input("line_quadric_weight", default=0.0, min=0.0, max=100.0, step=0.1,
+ tooltip="Per-edge line-quadric weight; preserves sharp ridges/valleys. 0 = off."),
+ IO.Float.Input("feature_edge_quadric_weight", default=0.0, min=0.0, max=1000.0, step=1.0,
+ tooltip="Extra quadric weight on dihedral feature edges (creases). 0 = off."),
+ IO.Float.Input("feature_edge_min_dihedral_deg", default=30.0, min=0.0, max=180.0, step=1.0,
+ tooltip="Minimum dihedral angle (degree) to count an edge as a feature edge."),
+ IO.Boolean.Input("clamp_v_to_edge", default=True,
+ tooltip="Project the QEM-optimal position onto the collapsed edge segment."),
+ ]),
+ ]
+ return IO.Schema(
+ node_id="DecimateMesh",
+ display_name="Decimate Mesh",
+ category="3d/mesh",
+ description=(
+ "Simplifies a mesh to a target face count using QEM, on the active compute "
+ "device. 'midpoint' is the cumesh-faithful preset (best quality, preserves thin "
+ "features / hair); 'qem' places vertices at the QEM optimum with line/feature-edge "
+ "controls. Output stays welded."
+ ),
+ inputs=[
+ IO.Mesh.Input("mesh"),
+ IO.Int.Input("target_face_count", default=200_000, min=0, max=50_000_000,
+ tooltip="Target max faces. 0 disables."),
+ IO.DynamicCombo.Input("placement_mode", options=placement_options,
+ display_name="placement_mode",
+ tooltip="midpoint: cumesh-faithful (recommended). qem: QEM-optimal placement."),
+ ],
+ outputs=[IO.Mesh.Output("mesh")],
+ hidden=[IO.Hidden.unique_id],
+ )
+
+ @classmethod
+ def execute(cls, mesh, target_face_count, placement_mode):
+ mode = placement_mode.get("placement_mode", "midpoint")
+ if mode == "qem":
+ # QEM-optimum placement; rest inherit defaults.
+ cfg = QEMConfig(
+ placement_mode="qem",
+ line_quadric_weight=float(placement_mode.get("line_quadric_weight", 0.0)),
+ feature_edge_quadric_weight=float(placement_mode.get("feature_edge_quadric_weight", 0.0)),
+ feature_edge_min_dihedral_deg=float(placement_mode.get("feature_edge_min_dihedral_deg", 30.0)),
+ clamp_v_to_edge=bool(placement_mode.get("clamp_v_to_edge", True)),
+ )
+ else:
+ cfg = QEMConfig() # midpoint defaults
+
+ # ComfyUI passes meshes on CPU (QEM much slower there); compute on device, return on original.
+ compute_device = comfy.model_management.get_torch_device()
+
+ counts = {"in": 0, "out": 0}
+
+ def _fn(v, f, c):
+ counts["in"] += int(f.shape[0])
+ if target_face_count > 0 and f.shape[0] > target_face_count:
+ src_device = v.device
+ rv, rf, rc, _rn, _rs = qem_decimate_simplify(
+ v.to(compute_device), f.to(compute_device), int(target_face_count),
+ colors=(c.to(compute_device) if c is not None else None),
+ config=cfg)
+ v = rv.to(src_device)
+ f = rf.to(src_device)
+ if rc is not None:
+ c = rc.to(src_device)
+ counts["out"] += int(f.shape[0])
+ return v, f, c
+
+ result = _process_mesh_batch(mesh, _fn)
+
+ # Display the face reduction on the node
+ if cls.hidden.unique_id:
+ PromptServer.instance.send_progress_text(
+ _fmt_face_change(counts["in"], counts["out"]), cls.hidden.unique_id)
+
+ return result
+
+
+class RemeshMesh(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ # sub-widgets show per sign_mode (DynamicCombo).
+ sign_mode_options = [
+ IO.DynamicCombo.Option(key="udf", inputs=[
+ IO.Boolean.Input("qef", default=False, advanced=True,
+ tooltip="QEF (Quadratic Error Function) dual-vertex placement for sharper edges."),
+ IO.Boolean.Input("drop_inverted_components", default=False, advanced=True,
+ tooltip="Drop inward-normal (negative-volume) closed components — the UDF inner shell."),
+ IO.Boolean.Input("drop_enclosed_components", default=False, advanced=True,
+ tooltip="Drop components inside the largest's bbox that fail a point-in-mesh raycast. Disable for legitimate nested parts."),
+ ]),
+ IO.DynamicCombo.Option(key="sdf", inputs=[
+ IO.Boolean.Input("qef", default=True,
+ tooltip="QEF (Quadratic Error Function) dual-vertex placement (recovers sharp features) vs edge-crossing centroid."),
+ IO.Boolean.Input("manifold", default=False,
+ tooltip="Manifold Dual Contouring: 1-4 dual verts/voxel for multi-sheet cases. Slower."),
+ ]),
+ ]
+ return IO.Schema(
+ node_id="RemeshMesh",
+ display_name="Remesh Mesh (Narrow-Band DC)",
+ category="3d/mesh",
+ description=(
+ "Re-extracts a uniformly tessellated mesh via a narrow-band distance field + Dual "
+ "Contouring, on the active compute device. Normalizes messy / non-manifold / "
+ "self-intersecting topology; run before Decimate Mesh to hit an exact face count. "
+ "Output stays welded."
+ ),
+ inputs=[
+ IO.Mesh.Input("mesh"),
+ IO.Int.Input("resolution", default=512, min=32, max=2048,
+ tooltip="Voxel grid resolution (output density). 256 ~ 100k faces, 512 ~ 1M. "
+ "For an exact face count, follow with Decimate Mesh."),
+ IO.DynamicCombo.Input("sign_mode", options=sign_mode_options, display_name="sign_mode",
+ tooltip="udf: robust to messy/non-manifold input. sdf: clean single "
+ "surface with QEF (Quadratic Error Function) sharp-feature recovery, but needs consistent winding."),
+ IO.Float.Input("band", default=1.0, min=0.5, max=4.0, step=0.1, advanced=True,
+ tooltip="Narrow-band width in voxel units. In UDF mode also offsets the surface."),
+ IO.Float.Input("project_back", default=0.0, min=0.0, max=1.0, step=0.05, advanced=True,
+ tooltip="Linearly interpolate vertices toward the original surface (0 = pure DC, 1 = snapped)."),
+ IO.Boolean.Input("fix_poles", default=False, advanced=True,
+ tooltip="Collapse valence-3 vertex pairs (DC T-junction artifact)."),
+ IO.Int.Input("smooth_iters", default=0, min=0, max=20,
+ tooltip="Taubin smoothing iterations (0 = off). 2-3 cleans DC staircase-like artifacts; higher over-smooth QEF edges."),
+ IO.Float.Input("drop_small_components", default=0.01, min=0.0, max=0.5, step=0.005, advanced=True,
+ tooltip="Drop components below this fraction of the largest's face count. 0 disables."),
+ IO.Int.Input("precluster_max_verts", default=20_000_000, min=0, max=100_000_000, advanced=True,
+ tooltip="Cap input vertex count before the field queries, inputs above this are cluster-decimated to it first. Prevents OOM on huge meshes."),
+ ],
+ outputs=[IO.Mesh.Output("mesh")],
+ hidden=[IO.Hidden.unique_id],
+ )
+
+ @classmethod
+ def execute(cls, mesh, resolution, sign_mode, band,
+ project_back, fix_poles, smooth_iters,
+ drop_small_components, precluster_max_verts):
+ mode = sign_mode.get("sign_mode", "udf")
+ # mode-specific sub-widgets (absent → defaults)
+ qef = bool(sign_mode.get("qef", True))
+ manifold = bool(sign_mode.get("manifold", False))
+ drop_inverted_components = bool(sign_mode.get("drop_inverted_components", False))
+ drop_enclosed_components = bool(sign_mode.get("drop_enclosed_components", False))
+
+ # ComfyUI passes meshes on CPU (remesh far faster on GPU); compute on device, return on original.
+ compute_device = comfy.model_management.get_torch_device()
+ counts = {"in": 0, "out": 0}
+
+ def _fn(v, f, c):
+ counts["in"] += int(f.shape[0])
+ src_device = v.device
+ vv = v.to(compute_device).float()
+ ff = f.to(compute_device).to(torch.int64)
+ cc = c.to(compute_device).float() if c is not None else None
+
+ # cluster-decimate very large inputs before field queries
+ if precluster_max_verts > 0 and vv.shape[0] > precluster_max_verts:
+ vv, ff, cc = qem_cluster_decimate(
+ vv, ff, target_verts=int(precluster_max_verts), colors=cc)
+
+ # Fixed [-0.5,0.5] cube domain (matches cumesh/TRELLIS2); scale ≈ 1.0 any resolution.
+ rs_scale = (resolution + 3.0 * band) / resolution
+ rs_center = torch.zeros(3, dtype=vv.dtype, device=compute_device)
+
+ rv, rf, rc = remesh_narrow_band_dc(
+ vv, ff,
+ resolution=int(resolution),
+ band=float(band), project_back=float(project_back),
+ qef=qef, sign_mode=mode,
+ manifold=manifold, fix_poles=bool(fix_poles),
+ smooth_iters=int(smooth_iters),
+ drop_small_components=float(drop_small_components),
+ drop_inverted_components=drop_inverted_components,
+ drop_enclosed_components=drop_enclosed_components,
+ scale=rs_scale, center=rs_center, colors=cc)
+
+ v = rv.to(src_device)
+ f = rf.to(src_device)
+ c = rc.to(src_device) if rc is not None else None
+ counts["out"] += int(f.shape[0])
+ return v, f, c
+
+ result = _process_mesh_batch(mesh, _fn)
+
+ # Display the face change on the node
+ if cls.hidden.unique_id:
+ PromptServer.instance.send_progress_text(
+ _fmt_face_change(counts["in"], counts["out"]), cls.hidden.unique_id)
+
+ return result
+
+
+def _pack_uv_meshes(vs, fs, uvs, colors):
+ """Pack per-item (verts, faces, uvs[, colors]) into a MESH; stack if single, else pad."""
+ if len(vs) == 1:
+ m = Types.MESH(vertices=vs[0].unsqueeze(0), faces=fs[0].unsqueeze(0), uvs=uvs[0].unsqueeze(0))
+ if colors is not None:
+ m.vertex_colors = colors[0].unsqueeze(0)
+ return m
+ bsz = len(vs)
+ dev = vs[0].device
+ maxv = max(v.shape[0] for v in vs)
+ maxf = max(f.shape[0] for f in fs)
+ pv = vs[0].new_zeros((bsz, maxv, 3))
+ pf = fs[0].new_zeros((bsz, maxf, 3))
+ pu = uvs[0].new_zeros((bsz, maxv, 2))
+ for i, (v, f, u) in enumerate(zip(vs, fs, uvs)):
+ pv[i, :v.shape[0]] = v
+ pf[i, :f.shape[0]] = f
+ pu[i, :u.shape[0]] = u
+ vc = torch.tensor([v.shape[0] for v in vs], device=dev, dtype=torch.int64)
+ fc = torch.tensor([f.shape[0] for f in fs], device=dev, dtype=torch.int64)
+ m = Types.MESH(vertices=pv, faces=pf, uvs=pu, vertex_counts=vc, face_counts=fc)
+ if colors is not None:
+ pc = colors[0].new_zeros((bsz, maxv, colors[0].shape[1]))
+ for i, c in enumerate(colors):
+ pc[i, :c.shape[0]] = c
+ m.vertex_colors = pc
+ return m
+
+
+def _uv_weld_vertices(v, f, weld_distance):
+ """Merge coincident verts; returns (welded_v, welded_f, welded_to_orig); last None if no welding."""
+ v_np = v.cpu().numpy()
+ f_np = f.cpu().numpy()
+ if v_np.size == 0:
+ return v, f, None
+ extent = float(np.linalg.norm(v_np.max(axis=0) - v_np.min(axis=0)))
+ tol = weld_distance if weld_distance > 0.0 else 1e-5 * extent
+ if tol <= 0.0:
+ return v, f, None
+ keys = np.round(v_np / tol).astype(np.int64)
+ _, inv = np.unique(keys, axis=0, return_inverse=True)
+ n_unique = int(inv.max()) + 1
+ if n_unique >= v_np.shape[0]:
+ return v, f, None
+ v_welded = np.zeros((n_unique, 3), dtype=np.float32)
+ counts = np.zeros(n_unique, dtype=np.int64)
+ np.add.at(v_welded, inv, v_np)
+ np.add.at(counts, inv, 1)
+ v_welded /= counts[:, None]
+ welded_to_orig = np.empty(n_unique, dtype=np.int64)
+ welded_to_orig[inv] = np.arange(v_np.shape[0], dtype=np.int64)
+ v_new = torch.from_numpy(v_welded).to(v.dtype).to(v.device)
+ f_new = torch.from_numpy(inv[f_np]).to(f.dtype).to(f.device)
+ return v_new, f_new, welded_to_orig
+
+
+def _uv_unwrap(positions, indices, segmenter, resolution, padding, weld_distance):
+ """UV-unwrap a single mesh; returns (vmapping, indices, uvs); vmapping maps each output
+ vertex to an input vertex (seam verts duplicated)."""
+ t_start = time.perf_counter()
+ # phase-weighted node progress: weld/mesh 2%, segment 33%, extract 5%, param 25%, pack 33%
+ pbar = comfy.utils.ProgressBar(1000)
+ v_in = positions.to(torch.float32)
+ f_in = indices.to(torch.long).reshape(-1, 3)
+ v_in, f_in, welded_to_orig = _uv_weld_vertices(v_in, f_in, weld_distance)
+
+ # drop degenerate faces (repeated index; corrupt edge adjacency)
+ degen = ((f_in[:, 0] == f_in[:, 1]) | (f_in[:, 1] == f_in[:, 2]) | (f_in[:, 2] == f_in[:, 0]))
+ if bool(degen.any()):
+ f_in = f_in[~degen]
+
+ mesh = _uv_mesh.build_mesh(v_in, f_in)
+ ff = mesh.face_face
+ if ff.numel() and float((ff >= 0).float().mean().item()) < 0.25:
+ logging.warning("[uv_unwrap] mesh face-adjacency < 25% — vertices appear un-welded "
+ "(triangle soup); UV charts will be per-face. Raise weld_distance.")
+
+ pbar.update_absolute(20, 1000)
+ def _seg_progress(done, total):
+ pbar.update_absolute(20 + (330 * done) // max(total, 1), 1000)
+ if segmenter == "pec":
+ face_chart = _uv_seg.cluster_charts_pec(mesh, max_cost=1.0, progress_callback=_seg_progress)
+ elif segmenter == "adaptive":
+ face_chart = _uv_seg.segment_charts(mesh, max_cost=2.0, progress_callback=_seg_progress)
+ else:
+ raise ValueError(f"unknown segmenter '{segmenter}'. valid: pec, adaptive")
+ pbar.update_absolute(350, 1000)
+
+ n_charts = int(face_chart.max().item()) + 1 if face_chart.numel() else 0
+ areas_cpu = _uv_mesh.chart_3d_areas(mesh.face_area, face_chart, n_charts).detach().cpu()
+
+ if n_charts == 0:
+ return (np.empty(0, dtype=np.int64), np.zeros((0, 3), dtype=np.int64),
+ np.empty((0, 2), dtype=np.float32))
+
+ # vectorized chart extraction: one global sort/unique replaces per-chart unique/searchsorted
+ face_chart_np = face_chart.cpu().numpy()
+ faces_np = mesh.faces.cpu().numpy()
+ vertices_np = mesh.vertices.cpu().numpy()
+ face_face_np = mesh.face_face.cpu().numpy()
+ order = np.argsort(face_chart_np, kind="stable")
+ chart_counts_np = np.bincount(face_chart_np, minlength=n_charts)
+ chart_offsets_np = np.zeros(n_charts + 1, dtype=np.int64)
+ np.cumsum(chart_counts_np, out=chart_offsets_np[1:])
+ faces_sorted = faces_np[order]
+ chart_sorted = face_chart_np[order]
+ n_verts_in = max(vertices_np.shape[0], 1)
+ chart_of_slot = np.repeat(chart_sorted, 3)
+ uniq_keys, local_flat = np.unique(chart_of_slot * n_verts_in + faces_sorted.reshape(-1),
+ return_inverse=True)
+ used_verts_all = uniq_keys % n_verts_in # per-chart sorted unique verts, concatenated
+ vert_counts = np.bincount(uniq_keys // n_verts_in, minlength=n_charts)
+ vert_offsets = np.zeros(n_charts + 1, dtype=np.int64)
+ np.cumsum(vert_counts, out=vert_offsets[1:])
+ local_faces_all = (local_flat - vert_offsets[chart_of_slot]).reshape(-1, 3)
+ pos_in_chart = np.empty(order.size, dtype=np.int64)
+ pos_in_chart[order] = np.arange(order.size) - chart_offsets_np[chart_sorted]
+ ff_sorted = face_face_np[order]
+ ff_safe = np.maximum(ff_sorted, 0)
+ keep = (ff_sorted >= 0) & (face_chart_np[ff_safe] == chart_sorted[:, None])
+ local_ff_all = np.where(keep, pos_in_chart[ff_safe], -1)
+
+ pbar.update_absolute(400, 1000)
+
+ # parameterize (batched): ortho-project every chart at once, batched stretch metrics
+ # decide acceptance, rejected charts solve ABF/LSCM in dense per-size-bucket batches
+ chart_of_vert = (uniq_keys // n_verts_in).astype(np.int64)
+ verts_concat = vertices_np[used_verts_all].astype(np.float64)
+ gl_faces = local_faces_all + vert_offsets[chart_sorted][:, None]
+ face_pos = pos_in_chart[order] # row of each (sorted) face in its chart
+ uv0 = _uv_param.ortho_project_concat(verts_concat, chart_of_vert, n_charts)
+ rms, mx, n_flip, n_zero = _uv_param.stretch_metrics_concat(
+ verts_concat, uv0, gl_faces, chart_sorted, n_charts)
+ valid_chart = (vert_counts >= 3) & (chart_counts_np > 0)
+ auto = valid_chart & (chart_counts_np <= 5) # tiny charts always keep ortho
+ flip_ok = (n_flip == 0) | (n_flip == chart_counts_np)
+ cand = valid_chart & ~auto & flip_ok & (n_zero == 0) & (rms <= 1.5) & (mx <= 2.0)
+ param_done = int(auto.sum())
+ pbar.update_absolute(400 + (250 * param_done) // n_charts, 1000)
+
+ ortho_ok = auto.copy()
+ cand_ids = np.nonzero(cand)[0]
+ for c in tqdm(cand_ids, desc="unwrap: ortho checks", unit="chart", leave=False):
+ f0, f1 = chart_offsets_np[c], chart_offsets_np[c + 1]
+ v0, v1 = vert_offsets[c], vert_offsets[c + 1]
+ if not _uv_param._uv_boundary_self_intersects(
+ uv0[v0:v1], local_faces_all[f0:f1], local_ff_all[f0:f1]):
+ ortho_ok[c] = True
+ param_done += 1
+ pbar.update_absolute(400 + (250 * param_done) // n_charts, 1000)
+
+ lscm_mask = valid_chart & ~ortho_ok
+ batchable = vert_counts <= _uv_param.LSCM_BATCH_MAX_VERTS
+ lscm_ids = np.nonzero(lscm_mask & batchable)[0]
+ big_ids = np.nonzero(lscm_mask & ~batchable)[0]
+ lscm_uv = _uv_param.lscm_charts_batch(
+ verts_concat, uv0, gl_faces, face_pos, chart_sorted, chart_of_vert,
+ vert_offsets, lscm_ids, n_charts,
+ device=comfy.model_management.get_torch_device())
+ param_done += int(lscm_ids.size)
+ pbar.update_absolute(400 + (250 * param_done) // n_charts, 1000)
+
+ uvs_np_list: list = [None] * n_charts
+ uv0_f32 = uv0.astype(np.float32)
+ for c in tqdm(big_ids, desc="unwrap: LSCM (large charts)", unit="chart", leave=False):
+ f0, f1 = chart_offsets_np[c], chart_offsets_np[c + 1]
+ v0, v1 = vert_offsets[c], vert_offsets[c + 1]
+ uvs_t = _uv_param.lscm_chart(
+ torch.from_numpy(verts_concat[v0:v1]),
+ torch.from_numpy(local_faces_all[f0:f1]),
+ torch.from_numpy(local_ff_all[f0:f1]), pin_positions=uv0[v0:v1])
+ lscm_uv[int(c)] = uvs_t.detach().cpu().numpy().astype(np.float32)
+ param_done += 1
+ pbar.update_absolute(400 + (250 * param_done) // n_charts, 1000)
+ for c in range(n_charts):
+ v0, v1 = vert_offsets[c], vert_offsets[c + 1]
+ if ortho_ok[c]:
+ uvs_np_list[c] = uv0_f32[v0:v1]
+ continue
+ u = lscm_uv.get(int(c))
+ if u is not None and np.all(np.isfinite(u)) and u.size:
+ # collapsed UV island (aspect > 100:1) blows up packing scale; keep ortho instead
+ bbox = u.max(axis=0) - u.min(axis=0)
+ if max(float(bbox.max()), 1e-12) / max(float(bbox.min()), 1e-12) <= 100.0:
+ uvs_np_list[c] = u
+ continue
+ uvs_np_list[c] = (uv0_f32[v0:v1] if valid_chart[c]
+ else np.zeros((v1 - v0, 2), dtype=np.float32))
+
+ # per-chart UV areas in one pass over all faces
+ uvs_all_np = np.concatenate(uvs_np_list)
+ ua, ub, uc = uvs_all_np[gl_faces[:, 0]], uvs_all_np[gl_faces[:, 1]], uvs_all_np[gl_faces[:, 2]]
+ tri_uv_area = 0.5 * np.abs(
+ (ub[:, 0] - ua[:, 0]) * (uc[:, 1] - ua[:, 1])
+ - (uc[:, 0] - ua[:, 0]) * (ub[:, 1] - ua[:, 1]))
+ uv_area_np = np.bincount(chart_sorted, weights=tri_uv_area.astype(np.float64),
+ minlength=n_charts)
+
+ areas_3d_np = areas_cpu.numpy().astype(np.float64)
+
+ # auto-tune texel density toward `resolution` (~0.62 pack fill)
+ total_3d_area = float(areas_3d_np.sum()) or 1.0
+ target_dim = float(resolution) if resolution > 0 else 1024.0
+ tex_per_unit = math.sqrt((target_dim * target_dim) * 0.62 / total_3d_area)
+
+ with tqdm(total=2 * n_charts, desc="unwrap: pack", unit="chart", leave=False) as tq_pack:
+ def _pack_progress(done, total):
+ tq_pack.update(done - tq_pack.n)
+ pbar.update_absolute(650 + (340 * done) // max(total, 1), 1000)
+ p_x, p_y, p_sw, p_th, p_sc, p_chh, atlas_w, atlas_h = _uv_pack.pack_bitmap_concat(
+ uvs_all_np, vert_offsets, local_faces_all, chart_offsets_np,
+ areas_3d_np, uv_area_np,
+ texels_per_unit=tex_per_unit, padding_texels=padding,
+ progress_callback=_pack_progress)
+ pbar.update_absolute(1000, 1000)
+
+ # assembly: output verts are the per-chart used-vert lists concatenated in chart order,
+ # so vert_offsets doubles as the output vertex cursor
+ n_in_faces = mesh.faces.shape[0]
+ out_indices = np.zeros((n_in_faces, 3), dtype=np.int64)
+ out_indices[order] = gl_faces
+ vmapping_out = used_verts_all if welded_to_orig is None else welded_to_orig[used_verts_all]
+ uvs_out = _uv_pack.apply_placements_concat(
+ uvs_all_np, vert_offsets, p_x, p_y, p_sw, p_th, p_sc, p_chh, atlas_w, atlas_h)
+ logging.info(f"[uv_unwrap] {mesh.faces.shape[0]} faces -> {n_charts} charts, "
+ f"atlas {atlas_w}x{atlas_h}, {time.perf_counter() - t_start:.1f}s")
+ return vmapping_out, out_indices, uvs_out
+
+
+class UnwrapMesh(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="UnwrapMesh",
+ display_name="Unwrap Mesh UVs",
+ category="3d/texturing",
+ description=(
+ "Generates a UV atlas: segments the surface into charts, parameterizes each, packs into a [0,1] atlas. "
+ "Vertices on chart seams are duplicated (one copy per chart, same position, own UV), so the output mesh "
+ "has more vertices than the input. Run after Remesh/Decimate, before texture baking."
+ ),
+ inputs=[
+ IO.Mesh.Input("mesh"),
+ IO.Combo.Input("segmenter", options=["pec", "adaptive"], default="pec",
+ tooltip="pec: fast parallel-edge-collapse charting on GPU. adaptive: CPU, slower."),
+ IO.Int.Input("resolution", default=1024, min=0, max=8192, step=256,
+ tooltip="Target atlas resolution for texel-density auto-scale (0 = fit-to-content)."),
+ IO.Int.Input("padding", default=1, min=0, max=16,
+ tooltip="Texel padding between charts."),
+ IO.Float.Input("weld_distance", default=0.0, min=0.0, max=1.0, step=0.0001,
+ tooltip="Coincident-vert merge radius as a fraction of mesh extent (0 = auto). "
+ "Raise to ~0.001 if you get per-triangle charts (unwelded input)."),
+ ],
+ outputs=[IO.Mesh.Output("mesh")],
+ hidden=[IO.Hidden.unique_id],
+ )
+
+ @classmethod
+ def execute(cls, mesh, segmenter, resolution, padding, weld_distance):
+ compute_device = comfy.model_management.get_torch_device()
+ seg_device = compute_device if segmenter == "pec" else torch.device("cpu")
+
+ is_list = isinstance(mesh.vertices, list)
+ is_batched = not is_list and mesh.vertices.ndim == 3
+ bsz = len(mesh.vertices) if is_list else (mesh.vertices.shape[0] if is_batched else 1)
+ bar = comfy.utils.ProgressBar(bsz)
+
+ out_v, out_f, out_uv, out_c = [], [], [], []
+ for i in range(bsz):
+ if is_list or is_batched:
+ vi, fi = mesh.vertices[i], mesh.faces[i]
+ ci = None
+ vc = mesh.vertex_colors
+ if vc is not None:
+ ci = vc[i] if (isinstance(vc, list) or vc.ndim == 3) else vc
+ else:
+ vi, fi = mesh.vertices, mesh.faces
+ ci = mesh.vertex_colors
+
+ src_device = vi.device
+ vnp = vi.detach().cpu().numpy().astype(np.float32)
+ extent = float(np.linalg.norm(vnp.max(0) - vnp.min(0))) if vnp.shape[0] else 0.0
+ weld_abs = weld_distance * extent if weld_distance > 0.0 else 0.0
+
+ vmapping, indices, uvs = _uv_unwrap(
+ vi.to(seg_device).float(), fi.to(seg_device).long(),
+ segmenter, int(resolution), int(padding), weld_abs)
+ uvs = uvs.copy()
+ uvs[:, 1] = 1.0 - uvs[:, 1] # UV y flipped vs trimesh
+
+ out_v.append(torch.from_numpy(vnp[vmapping]).to(src_device))
+ out_f.append(torch.from_numpy(indices).to(device=src_device, dtype=torch.long))
+ out_uv.append(torch.from_numpy(uvs.astype(np.float32)).to(src_device))
+ if ci is not None:
+ cnp = ci.detach().cpu().numpy()
+ out_c.append(torch.from_numpy(np.ascontiguousarray(cnp[vmapping])).to(src_device))
+ bar.update(1)
+
+ out_mesh = _pack_uv_meshes(out_v, out_f, out_uv, out_c if out_c else None)
+ if mesh.texture is not None:
+ out_mesh.texture = mesh.texture
+
+ if cls.hidden.unique_id:
+ PromptServer.instance.send_progress_text(
+ f"UV: {_fmt_count(out_v[0].shape[0])} verts / {_fmt_count(out_f[0].shape[0])} faces"
+ f" · atlas ~{resolution}px",
+ cls.hidden.unique_id)
+ return IO.NodeOutput(out_mesh)
+
+
+def _uv_sorted_edge_keys(indices: np.ndarray):
+ """Sorted undirected edge keys; returns (sorted_keys, face_id, lo, hi, first_mask)."""
+ a = indices.ravel().astype(np.int64)
+ b = np.roll(indices, -1, axis=1).ravel().astype(np.int64)
+ lo = np.minimum(a, b)
+ hi = np.maximum(a, b)
+ V = int(indices.max()) + 1
+ key = lo * V + hi
+ order = np.argsort(key, kind="stable")
+ sk = key[order]
+ fid = (np.arange(a.size, dtype=np.int64) // 3)[order]
+ first = np.ones(sk.size, dtype=bool)
+ first[1:] = sk[1:] != sk[:-1]
+ return sk, fid, lo[order], hi[order], first
+
+
+def _uv_faces_to_chart_ids(indices: np.ndarray) -> np.ndarray:
+ """Chart = connected component of faces sharing a (non-seam-duplicated) UV vertex."""
+ F = indices.shape[0]
+ if F == 0:
+ return np.empty(0, dtype=np.int64)
+ _sk, fid, _lo, _hi, first = _uv_sorted_edge_keys(indices)
+ group_id = np.cumsum(first) - 1
+ starts = np.nonzero(first)[0]
+ rows = fid[starts[group_id[~first]]]
+ cols = fid[~first]
+ if rows.size == 0:
+ return np.arange(F, dtype=np.int64)
+ adj = csr_matrix((np.ones(rows.size, dtype=np.int8), (rows, cols)), shape=(F, F))
+ _, labels = connected_components(adj, directed=False)
+ return labels.astype(np.int64)
+
+
+_UV_TAB20 = np.array([
+ [0.121568627, 0.466666667, 0.705882353], [0.682352941, 0.780392157, 0.909803922],
+ [1.000000000, 0.498039216, 0.054901961], [1.000000000, 0.733333333, 0.470588235],
+ [0.172549020, 0.627450980, 0.172549020], [0.596078431, 0.874509804, 0.541176471],
+ [0.839215686, 0.152941176, 0.156862745], [1.000000000, 0.596078431, 0.588235294],
+ [0.580392157, 0.403921569, 0.741176471], [0.772549020, 0.690196078, 0.835294118],
+ [0.549019608, 0.337254902, 0.294117647], [0.768627451, 0.611764706, 0.580392157],
+ [0.890196078, 0.466666667, 0.760784314], [0.968627451, 0.713725490, 0.823529412],
+ [0.498039216, 0.498039216, 0.498039216], [0.780392157, 0.780392157, 0.780392157],
+ [0.737254902, 0.741176471, 0.133333333], [0.858823529, 0.858823529, 0.552941176],
+ [0.090196078, 0.745098039, 0.811764706], [0.619607843, 0.854901961, 0.898039216],
+], dtype=np.float32)
+
+
+def _uv_palette(n: int) -> np.ndarray:
+ rng = np.random.RandomState(42)
+ perm = rng.permutation(max(1, n))
+ out = np.empty((n, 3), dtype=np.float32)
+ for i in range(n):
+ out[i] = _UV_TAB20[perm[i % len(perm)] % 20]
+ return out
+
+
+def _uv_render_atlas(uvs_np, indices_np, resolution, device,
+ bg=(0.13, 0.13, 0.13), edge=(0.0, 0.0, 0.0)):
+ """Tile-based torch rasterizer of the UV atlas (charts colored, borders outlined); (H,W,3)."""
+ w = h = int(resolution)
+ chart_ids_np = _uv_faces_to_chart_ids(indices_np)
+ uvs = torch.from_numpy(uvs_np).to(device=device, dtype=torch.float32)
+ indices = torch.from_numpy(indices_np).to(device=device, dtype=torch.long)
+ chart_ids = torch.from_numpy(chart_ids_np).to(device=device, dtype=torch.long)
+
+ img = torch.tensor(bg, dtype=torch.float32, device=device).expand(h, w, 3).contiguous()
+ if indices.numel() == 0:
+ return img
+
+ n_charts = int(chart_ids.max().item()) + 1 if chart_ids.numel() else 1
+ colors = torch.from_numpy(_uv_palette(n_charts)).to(device=device, dtype=torch.float32)
+
+ uv_px = uvs.clone()
+ uv_px[:, 0] = uv_px[:, 0].clamp(0.0, 1.0) * (w - 1)
+ uv_px[:, 1] = uv_px[:, 1].clamp(0.0, 1.0) * (h - 1)
+
+ tri = uv_px[indices]
+ x0 = tri[:, 0, 0]
+ y0 = tri[:, 0, 1]
+ x1 = tri[:, 1, 0]
+ y1 = tri[:, 1, 1]
+ x2 = tri[:, 2, 0]
+ y2 = tri[:, 2, 1]
+ denom = (y1 - y2) * (x0 - x2) + (x2 - x1) * (y0 - y2)
+ nondegen = denom.abs() > 1e-20
+
+ xmin = torch.minimum(torch.minimum(x0, x1), x2).floor().clamp_(0, w - 1).long()
+ xmax = torch.maximum(torch.maximum(x0, x1), x2).ceil().clamp_(0, w - 1).long()
+ ymin = torch.minimum(torch.minimum(y0, y1), y2).floor().clamp_(0, h - 1).long()
+ ymax = torch.maximum(torch.maximum(y0, y1), y2).ceil().clamp_(0, h - 1).long()
+
+ # full point-in-tri over all pairs is O(H*W*F); tile and test only bbox-overlapping tris
+ TILE = 64
+ eps = 1e-6
+ for ty in range(0, h, TILE):
+ ty_end = min(ty + TILE, h)
+ for tx in range(0, w, TILE):
+ tx_end = min(tx + TILE, w)
+ tri_mask = (nondegen & (xmin < tx_end) & (xmax >= tx)
+ & (ymin < ty_end) & (ymax >= ty))
+ if not tri_mask.any():
+ continue
+ idx = torch.nonzero(tri_mask, as_tuple=True)[0]
+ ys = torch.arange(ty, ty_end, dtype=torch.float32, device=device) + 0.5
+ xs = torch.arange(tx, tx_end, dtype=torch.float32, device=device) + 0.5
+ yy, xx = torch.meshgrid(ys, xs, indexing="ij")
+ sub_x0 = x0[idx][:, None, None]
+ sub_y0 = y0[idx][:, None, None]
+ sub_x1 = x1[idx][:, None, None]
+ sub_y1 = y1[idx][:, None, None]
+ sub_x2 = x2[idx][:, None, None]
+ sub_y2 = y2[idx][:, None, None]
+ sub_den = denom[idx][:, None, None]
+ bx = ((sub_y1 - sub_y2) * (xx - sub_x2) + (sub_x2 - sub_x1) * (yy - sub_y2)) / sub_den
+ by = ((sub_y2 - sub_y0) * (xx - sub_x2) + (sub_x0 - sub_x2) * (yy - sub_y2)) / sub_den
+ bz = 1.0 - bx - by
+ inside = (bx >= -eps) & (by >= -eps) & (bz >= -eps)
+ if not inside.any():
+ continue
+ hit_any = inside.any(dim=0)
+ best_tri = idx[inside.int().argmax(dim=0)]
+ tile_color = colors[chart_ids[best_tri]]
+ tile_img = img[ty:ty_end, tx:tx_end]
+ tile_img[hit_any] = tile_color[hit_any]
+ img[ty:ty_end, tx:tx_end] = tile_img
+
+ # chart outlines: UV-space borders are open boundaries (edges with 1 incident face)
+ _sk, _fid, lo, hi, first = _uv_sorted_edge_keys(indices_np)
+ starts = np.nonzero(first)[0]
+ counts = np.diff(np.append(starts, first.size))
+ boundary = counts == 1
+ uv_cpu = uv_px.cpu().numpy()
+ px_xs, px_ys = [], []
+ for a, b in zip(lo[starts[boundary]], hi[starts[boundary]]):
+ p0 = uv_cpu[a]
+ p1 = uv_cpu[b]
+ steps = int(max(abs(p1[0] - p0[0]), abs(p1[1] - p0[1])) + 1)
+ if steps <= 1:
+ continue
+ ts = np.linspace(0.0, 1.0, steps)
+ xs = (p0[0] + (p1[0] - p0[0]) * ts).astype(np.int32)
+ ys = (p0[1] + (p1[1] - p0[1]) * ts).astype(np.int32)
+ valid = (xs >= 0) & (xs < w) & (ys >= 0) & (ys < h)
+ px_xs.append(xs[valid])
+ px_ys.append(ys[valid])
+ if px_xs:
+ xs_all = torch.from_numpy(np.concatenate(px_xs)).to(device=device, dtype=torch.long)
+ ys_all = torch.from_numpy(np.concatenate(px_ys)).to(device=device, dtype=torch.long)
+ img[ys_all, xs_all] = torch.tensor(edge, dtype=torch.float32, device=device)
+
+ return img
+
+
+class RenderUVAtlas(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="RenderUVAtlas",
+ display_name="Render UV Atlas",
+ category="3d/texturing",
+ description=("Renders a mesh's UV layout as an image."),
+ inputs=[
+ IO.Mesh.Input("mesh"),
+ IO.Int.Input("resolution", default=1024, min=64, max=4096, step=64),
+ ],
+ outputs=[IO.Image.Output("image")],
+ )
+
+ @classmethod
+ def execute(cls, mesh, resolution):
+ uvs_t = mesh.uvs
+ if uvs_t is None:
+ raise RuntimeError("mesh has no UVs to render. Run UnwrapMesh first.")
+ uvs_np = uvs_t.detach().cpu().numpy()
+ if uvs_np.ndim == 3:
+ uvs_np = uvs_np[0]
+ f = mesh.faces
+ if torch.is_tensor(f):
+ f = f.detach().cpu().numpy()
+ if f.ndim == 3:
+ f = f[0]
+ f = np.ascontiguousarray(f, dtype=np.int64)
+ uvs_np = np.ascontiguousarray(uvs_np, dtype=np.float32)
+ device = comfy.model_management.get_torch_device()
+ img = _uv_render_atlas(uvs_np, f, int(resolution), device)
+ return IO.NodeOutput(img.detach().cpu().unsqueeze(0))
+
+
+class FillHoles(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="FillHoles",
+ display_name="Fill Holes",
+ category="3d/mesh",
+ description=(
+ "Fills holes up to a max perimeter, preserving existing geometry/UVs. GPU-vectorised with auto-corrected winding and loop-averaged centroid colors"
+ ),
+ inputs=[
+ IO.Mesh.Input("mesh"),
+ IO.Float.Input("max_perimeter", default=0.03, min=0.0, step=0.0001,
+ tooltip="Max hole perimeter to fill. 0 disables."),
+ IO.Float.Input("weld_epsilon_rel", default=1e-5, min=0.0, step=1e-6,
+ tooltip="Pre-weld tolerance (fraction of bounding box diagonal); boundary detection "
+ "needs welded vertices. 0 skips."),
+ IO.Int.Input("max_vertices", default=16, min=3, max=1024,
+ tooltip="Cap boundary vertices per cycle; centroid-fan only works for small "
+ "near-planar holes. Keep ≤16."),
+ IO.Boolean.Input("fill_chains", default=False,
+ tooltip="Also fill open chains (not just cycles). Noisy; OFF matches cumesh."),
+ ],
+ outputs=[IO.Mesh.Output("mesh")],
+ )
+
+ @classmethod
+ def execute(cls, mesh, max_perimeter, weld_epsilon_rel, max_vertices, fill_chains):
+ def _fn(v, f, c):
+ if max_perimeter > 0:
+ v, f, c = fill_holes_v2_fn(
+ v, f, max_perimeter=max_perimeter, colors=c,
+ weld_epsilon_rel=weld_epsilon_rel,
+ fill_chains=fill_chains,
+ max_verts=max_vertices,
+ )
+ return v, f, c
+ return _process_mesh_batch(mesh, _fn)
+
+
+class WeldVertices(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="WeldVertices",
+ display_name="Weld Vertices",
+ category="3d/mesh",
+ description=(
+ "Merge coincident vertices via L_inf grid quantization. Use when a mesh comes in "
+ "unwelded (per-face verts, no shared edges) — pre-pass before FillHoles, "
+ "DecimateMesh, or any topology-aware op. Colors averaged per cluster."
+ ),
+ inputs=[
+ IO.Mesh.Input("mesh"),
+ IO.Float.Input("epsilon_rel", default=1e-5, min=0.0, step=1e-6,
+ tooltip="Weld tolerance (fraction of bbox diagonal). 1e-5 for float dedup; "
+ "1e-3 for visibly-close-but-distinct verts."),
+ IO.Float.Input("epsilon_abs", default=0.0, min=0.0, step=1e-6,
+ tooltip="Absolute weld tolerance (overrides epsilon_rel when > 0)."),
+ ],
+ outputs=[IO.Mesh.Output("mesh")],
+ )
+
+ @classmethod
+ def execute(cls, mesh, epsilon_rel, epsilon_abs):
+ eps = epsilon_abs if epsilon_abs > 0 else None
+ def _fn(v, f, c):
+ v, f, c, n = weld_vertices_fn(v, f, epsilon=eps, epsilon_rel=epsilon_rel, colors=c)
+ if n > 0:
+ logging.info(f"[WeldVertices] merged {n} verts ({v.shape[0]} remain)")
+ return v, f, c
+ return _process_mesh_batch(mesh, _fn)
+
+
+class MeshSmoothNormals(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="MeshSmoothNormals",
+ display_name="Smooth Mesh Normals",
+ category="3d/mesh",
+ description=(
+ "Compute smooth per-vertex normals and attach them to the mesh. Meshes "
+ "without normals are shaded flat (per-face) by glTF viewers; this makes "
+ "them shade smoothly. With crease_angle below 180, edges sharper than the "
+ "threshold are kept hard by splitting vertices along them."
+ ),
+ inputs=[
+ IO.Mesh.Input("mesh"),
+ IO.Float.Input("crease_angle", default=180.0, min=0.0, max=180.0, step=1.0,
+ tooltip="Edges whose dihedral angle exceeds this value (degrees) stay "
+ "hard (vertices are split). 180 = fully smooth; lower "
+ "preserves sharp edges (e.g. ~30-60 for hard-surface)."),
+ ],
+ outputs=[IO.Mesh.Output("mesh")],
+ )
+
+ @classmethod
+ def execute(cls, mesh: Types.MESH, crease_angle: float) -> IO.NodeOutput:
+ crease = None if crease_angle >= 180.0 else float(crease_angle)
+ batch_size = mesh.vertices.shape[0]
+
+ if crease is None:
+ # Fully smooth: topology is unchanged, so just attach a normals tensor that
+ # matches the existing (possibly zero-padded) vertex layout and keep all fields.
+ normals_padded = torch.zeros_like(mesh.vertices)
+ for i in range(batch_size):
+ v_i, f_i, _, _, _ = get_mesh_batch_item(mesh, i)
+ if v_i.shape[0] == 0 or f_i.shape[0] == 0:
+ continue
+ n_i = _smooth_vertex_normals(v_i.cpu().numpy().astype(np.float32),
+ f_i.cpu().numpy().astype(np.int64))
+ normals_padded[i, :n_i.shape[0]] = torch.from_numpy(n_i).to(mesh.vertices)
+ out = copy.copy(mesh)
+ out.normals = normals_padded
+ return IO.NodeOutput(out)
+
+ # Crease split changes per-item vertex counts -> rebuild as a variable-size batch.
+ tangents_b = mesh.tangents
+ v_list, f_list, n_list = [], [], []
+ c_list = [] if mesh.vertex_colors is not None else None
+ u_list = [] if mesh.uvs is not None else None
+ t_list = [] if tangents_b is not None else None
+ for i in range(batch_size):
+ v_i, f_i, c_i, u_i, _ = get_mesh_batch_item(mesh, i)
+ if v_i.shape[0] == 0 or f_i.shape[0] == 0:
+ continue
+ dev = v_i.device
+ vo, fo, no, remap = _compute_vertex_face_normals(
+ v_i.cpu().numpy().astype(np.float32),
+ f_i.cpu().numpy().astype(np.int64), crease)
+ remap_t = torch.from_numpy(remap)
+ v_list.append(torch.from_numpy(vo).to(dev, mesh.vertices.dtype))
+ f_list.append(torch.from_numpy(fo.astype(np.int64)).to(dev, mesh.faces.dtype))
+ n_list.append(torch.from_numpy(no).to(dev, mesh.vertices.dtype))
+ if c_list is not None:
+ c_list.append(c_i[remap_t.to(c_i.device)])
+ if u_list is not None:
+ u_list.append(u_i[remap_t.to(u_i.device)])
+ if t_list is not None:
+ # Remap (not recompute) so TANGENT keeps the baked basis; split verts copy theirs.
+ t_i = tangents_b[i, :v_i.shape[0]]
+ t_list.append(t_i[remap_t.to(t_i.device)])
+ if not v_list:
+ return IO.NodeOutput(mesh)
+ out = pack_variable_mesh_batch(
+ v_list, f_list, colors=c_list, uvs=u_list,
+ texture=mesh.texture, unlit=mesh.unlit,
+ normals=n_list, metallic_roughness=mesh.metallic_roughness,
+ tangents=t_list, normal_map=mesh.normal_map,
+ occlusion_in_mr=mesh.occlusion_in_mr,
+ material=mesh.material, emissive=mesh.emissive)
+ return IO.NodeOutput(out)
+
+
+class PostProcessMeshExtension(ComfyExtension):
+ @override
+ async def get_node_list(self) -> list[type[IO.ComfyNode]]:
+ return [
+ FillHoles,
+ WeldVertices,
+ DecimateMesh,
+ RemeshMesh,
+ UnwrapMesh,
+ RenderUVAtlas,
+ PaintMesh,
+ BakeTextureFromVoxel,
+ MeshTextureToImage,
+ ApplyTextureToMesh,
+ BakeNormalMapFromMesh,
+ BakeAmbientOcclusion,
+ RenderMesh,
+ MeshSmoothNormals,
+ ]
+
+
+async def comfy_entrypoint() -> PostProcessMeshExtension:
+ return PostProcessMeshExtension()
diff --git a/comfy_extras/nodes_model_advanced.py b/comfy_extras/nodes_model_advanced.py
index 21ea82148..c73b0ba12 100644
--- a/comfy_extras/nodes_model_advanced.py
+++ b/comfy_extras/nodes_model_advanced.py
@@ -280,13 +280,30 @@ class RescaleCFG:
CATEGORY = "model/patch"
def patch(self, model, multiplier):
+ model_sampling = model.get_model_object("model_sampling")
+ is_flow = isinstance(model_sampling, comfy.model_sampling.CONST)
+
def rescale_cfg(args):
+ x_orig = args["input"]
+ cond_scale = args["cond_scale"]
+
+ if is_flow:
+ # Flow-matching models: cond_denoised/uncond_denoised are x_0 estimates,
+ # so the eps↔v conversion below would be wrong. Rescale directly in x_0 space.
+ x_0_cond = args["cond_denoised"]
+ x_0_uncond = args["uncond_denoised"]
+ x_0_cfg = x_0_uncond + cond_scale * (x_0_cond - x_0_uncond)
+ dims = tuple(range(1, x_0_cond.ndim))
+ ro_pos = x_0_cond.std(dim=dims, keepdim=True)
+ ro_cfg = x_0_cfg.std(dim=dims, keepdim=True).clamp(min=1e-8)
+ x_0_rescaled = x_0_cfg * (ro_pos / ro_cfg)
+ x_0_final = multiplier * x_0_rescaled + (1.0 - multiplier) * x_0_cfg
+ return x_orig - x_0_final
+
cond = args["cond"]
uncond = args["uncond"]
- cond_scale = args["cond_scale"]
sigma = args["sigma"]
sigma = sigma.view(sigma.shape[:1] + (1,) * (cond.ndim - 1))
- x_orig = args["input"]
#rescale cfg has to be done on v-pred model output
x = x_orig / (sigma * sigma + 1.0)
diff --git a/comfy_extras/nodes_moge.py b/comfy_extras/nodes_moge.py
index a63f0414b..819421534 100644
--- a/comfy_extras/nodes_moge.py
+++ b/comfy_extras/nodes_moge.py
@@ -2,6 +2,7 @@
import torch
+import math
import comfy.utils
import folder_paths
@@ -391,10 +392,57 @@ class MoGePointMapToMesh(io.ComfyNode):
return io.NodeOutput(mesh)
+class MoGeGeometryToFOV(io.ComfyNode):
+ """Extract horizontal/vertical FOV from MoGe intrinsics, e.g. fov_y to feed SAM3DBody_Predict."""
+
+ @classmethod
+ def define_schema(cls):
+ return io.Schema(
+ node_id="MoGeGeometryToFOV",
+ search_aliases=["moge", "fov", "geometry", "intrinsics", "field of view"],
+ display_name="Get FoV from MoGe Geometry",
+ description="Derive the field of view and focal length from MoGe intrinsics.",
+ category="image/geometry estimation",
+ inputs=[
+ MoGeGeometry.Input("moge_geometry"),
+ io.Combo.Input("axis", options=["vertical", "horizontal", "diagonal"], default="vertical",
+ tooltip="'vertical' (fov_y), 'horizontal' (fov_x), or 'diagonal'."),
+ io.Combo.Input("unit", options=["degrees", "radians"], default="degrees",
+ tooltip="Output unit for the FOV."),
+ ],
+ outputs=[
+ io.Float.Output(display_name="fov"),
+ io.Float.Output(display_name="focal_pixels"),
+ ],
+ )
+
+ @classmethod
+ def execute(cls, moge_geometry, axis, unit) -> io.NodeOutput:
+ K = moge_geometry.get("intrinsics") if isinstance(moge_geometry, dict) else None
+ if K is None:
+ raise ValueError("moge_geometry has no intrinsics (panorama geometry has none).")
+ if K.ndim == 3:
+ K = K[0]
+ # MoGe normalizes fx by width and fy by height; with cx=cy=0.5 the half-extent
+ # in normalized units is 0.5, so fov = 2*atan(0.5 / f) per axis (hypot for diagonal).
+ hx = 0.5 / float(K[0, 0].item())
+ hy = 0.5 / float(K[1, 1].item())
+ half_tan = {"horizontal": hx, "vertical": hy, "diagonal": math.hypot(hx, hy)}[axis]
+ fov_radians = 2.0 * math.atan(half_tan)
+ fov = fov_radians if unit == "radians" else math.degrees(fov_radians)
+ # Pixels are square here, so fy*H == fx*W is the single lens focal in pixels.
+ src = next((moge_geometry[k] for k in ("image", "points", "depth") if k in moge_geometry), None)
+ if src is None:
+ raise ValueError("moge_geometry has no image/points/depth to read the pixel height from.")
+ H = int(src.shape[1])
+ focal_pixels = float(K[1, 1].item()) * H
+ return io.NodeOutput(fov, focal_pixels)
+
+
class MoGeExtension(ComfyExtension):
@override
async def get_node_list(self) -> list[type[io.ComfyNode]]:
- return [LoadMoGeModel, MoGeInference, MoGePanoramaInference, MoGeRender, MoGePointMapToMesh]
+ return [LoadMoGeModel, MoGeInference, MoGePanoramaInference, MoGeRender, MoGePointMapToMesh, MoGeGeometryToFOV]
async def comfy_entrypoint() -> MoGeExtension:
diff --git a/comfy_extras/nodes_save_3d.py b/comfy_extras/nodes_save_3d.py
index e9fd07326..660ab8fe0 100644
--- a/comfy_extras/nodes_save_3d.py
+++ b/comfy_extras/nodes_save_3d.py
@@ -1,10 +1,13 @@
"""Save-side 3D nodes: mesh packing/slicing helpers + GLB writer + SaveGLB node."""
+import copy
import json
import logging
+import math
import os
import struct
from io import BytesIO
+from typing import TypedDict
import numpy as np
from PIL import Image
@@ -14,13 +17,15 @@ from typing_extensions import override
import folder_paths
from comfy.cli_args import args
from comfy_api.latest import ComfyExtension, IO, Types, UI
+from server import PromptServer
-def pack_variable_mesh_batch(vertices, faces, colors=None, uvs=None, texture=None, unlit=False):
- # Pack lists of (Nᵢ, *) vertex/face/color/uv tensors into padded batched tensors,
- # stashing per-item lengths as runtime attrs so consumers can recover the real slice.
- # colors and uvs are 1:1 with vertices, so they're padded to max_vertices and read with vertex_counts.
- # texture is (B, H, W, 3) — passed through unchanged
+def pack_variable_mesh_batch(vertices, faces, colors=None, uvs=None, texture=None, unlit=False,
+ normals=None, metallic_roughness=None, tangents=None, normal_map=None,
+ occlusion_in_mr=False, material=None, emissive=None):
+ # Pack per-item tensors into padded batches, stashing per-item lengths as runtime attrs.
+ # colors/uvs/normals/tangents are 1:1 with vertices (padded to max_vertices); texture/
+ # metallic_roughness/normal_map are (B,H,W,*) image stacks passed through unchanged.
batch_size = len(vertices)
max_vertices = max(v.shape[0] for v in vertices)
max_faces = max(f.shape[0] for f in faces)
@@ -52,43 +57,86 @@ def pack_variable_mesh_batch(vertices, faces, colors=None, uvs=None, texture=Non
)
packed_uvs[i, :u.shape[0]] = u
+ packed_normals = None
+ if normals is not None:
+ packed_normals = normals[0].new_zeros((batch_size, max_vertices, normals[0].shape[1]))
+ for i, nrm in enumerate(normals):
+ assert nrm.shape[0] == vertices[i].shape[0], (
+ f"normals[{i}] has {nrm.shape[0]} entries, expected {vertices[i].shape[0]} (1:1 with vertices)"
+ )
+ packed_normals[i, :nrm.shape[0]] = nrm
+
+ packed_tangents = None
+ if tangents is not None:
+ packed_tangents = tangents[0].new_zeros((batch_size, max_vertices, tangents[0].shape[1]))
+ for i, tn in enumerate(tangents):
+ assert tn.shape[0] == vertices[i].shape[0], (
+ f"tangents[{i}] has {tn.shape[0]} entries, expected {vertices[i].shape[0]} (1:1 with vertices)"
+ )
+ packed_tangents[i, :tn.shape[0]] = tn
+
return Types.MESH(packed_vertices, packed_faces,
uvs=packed_uvs, vertex_colors=packed_colors, texture=texture,
- vertex_counts=vertex_counts, face_counts=face_counts, unlit=unlit)
+ metallic_roughness=metallic_roughness,
+ vertex_counts=vertex_counts, face_counts=face_counts, unlit=unlit,
+ normals=packed_normals, tangents=packed_tangents,
+ normal_map=normal_map, occlusion_in_mr=occlusion_in_mr,
+ material=material, emissive=emissive)
def get_mesh_batch_item(mesh, index):
# Returns (vertices, faces, colors, uvs) for batch index, slicing to real lengths
# if the mesh carries per-item counts (variable-size batch).
- v_colors = getattr(mesh, "vertex_colors", None)
- v_uvs = getattr(mesh, "uvs", None)
- if getattr(mesh, "vertex_counts", None) is not None:
+ v_colors = mesh.vertex_colors
+ v_uvs = mesh.uvs
+ v_normals = mesh.normals
+ if mesh.vertex_counts is not None:
vertex_count = int(mesh.vertex_counts[index].item())
face_count = int(mesh.face_counts[index].item())
vertices = mesh.vertices[index, :vertex_count]
faces = mesh.faces[index, :face_count]
colors = v_colors[index, :vertex_count] if v_colors is not None else None
uvs = v_uvs[index, :vertex_count] if v_uvs is not None else None
- return vertices, faces, colors, uvs
+ normals = v_normals[index, :vertex_count] if v_normals is not None else None
+ return vertices, faces, colors, uvs, normals
colors = v_colors[index] if v_colors is not None else None
uvs = v_uvs[index] if v_uvs is not None else None
- return mesh.vertices[index], mesh.faces[index], colors, uvs
+ normals = v_normals[index] if v_normals is not None else None
+ return mesh.vertices[index], mesh.faces[index], colors, uvs, normals
-def save_glb(vertices, faces, filepath, metadata=None,
- uvs=None, vertex_colors=None, texture_image=None, unlit=False):
+def save_glb(vertices, faces, filepath=None, metadata=None,
+ uvs=None, vertex_colors=None, texture_image=None,
+ metallic_roughness_image=None, unlit=False,
+ normals=None, normal_map_image=None, tangents=None, occlusion_in_mr=False,
+ material=None, emissive_image=None):
"""
Save PyTorch tensor vertices and faces as a GLB file without external dependencies.
Parameters:
vertices: torch.Tensor of shape (N, 3) - The vertex coordinates
faces: torch.Tensor of shape (M, 3) - The face indices (triangle faces)
- filepath: str - Output filepath (should end with .glb)
+ filepath: str - Output filepath (should end with .glb). None returns the GLB bytes instead of writing.
metadata: dict - Optional asset.extras metadata
uvs: torch.Tensor of shape (N, 2) - Optional per-vertex texture coordinates
vertex_colors: torch.Tensor of shape (N, 3) or (N, 4) - Optional per-vertex colors in [0, 1]
texture_image: PIL.Image - Optional baseColor texture, embedded as PNG
+ metallic_roughness_image: PIL.Image - Optional glTF metallicRoughness texture
+ (R unused, G=roughness, B=metallic), embedded as PNG
+ normals: torch.Tensor of shape (N, 3) - Optional per-vertex normals, written as the
+ glTF NORMAL attribute. When omitted, NO normals are written and viewers fall back
+ to flat (per-face) shading — use the MeshSmoothNormals node to generate them.
+ normal_map_image: PIL.Image - Optional tangent-space normal map (glTF/OpenGL +Y),
+ written as the material normalTexture. Needs TEXCOORD_0.
+ tangents: torch.Tensor of shape (N, 4) - Optional per-vertex tangents (xyz + handedness w),
+ written as the glTF TANGENT attribute. Without it viewers derive tangents in-shader.
+ occlusion_in_mr: bool - When True, R of metallic_roughness_image holds AO (ORM packing) and
+ occlusionTexture is pointed at that same image.
+ material: dict - Optional scalar overrides from SetMeshMaterial (base_color_factor,
+ metallic/roughness_factor with <0 = auto, emissive_factor/strength, normal_scale,
+ occlusion_strength, double_sided).
+ emissive_image: PIL.Image - Optional emissive (glow) texture, written as emissiveTexture.
"""
# Convert tensors to numpy arrays
@@ -117,44 +165,82 @@ def save_glb(vertices, faces, filepath, metadata=None,
raise ValueError(
f"save_glb: vertex_colors has {colors_np.shape[0]} entries but vertex count is {n_verts}"
)
+
+ normals_np = normals.cpu().numpy().astype(np.float32) if normals is not None else None
+ if normals_np is not None and normals_np.shape[0] != n_verts:
+ raise ValueError(
+ f"save_glb: normals has {normals_np.shape[0]} entries but vertex count is {n_verts}"
+ )
+ tangents_np = tangents.cpu().numpy().astype(np.float32) if tangents is not None else None
+ if tangents_np is not None and tangents_np.shape != (n_verts, 4):
+ raise ValueError(
+ f"save_glb: tangents must be (N, 4) with N={n_verts}, got {tuple(tangents_np.shape)}"
+ )
faces_np = faces_signed.astype(np.uint32)
texture_png_bytes = None
if texture_image is not None:
buf = BytesIO()
texture_image.save(buf, format="PNG")
texture_png_bytes = buf.getvalue()
+ mr_png_bytes = None
+ if metallic_roughness_image is not None:
+ buf = BytesIO()
+ metallic_roughness_image.save(buf, format="PNG")
+ mr_png_bytes = buf.getvalue()
+ nm_png_bytes = None
+ if normal_map_image is not None:
+ buf = BytesIO()
+ normal_map_image.save(buf, format="PNG")
+ nm_png_bytes = buf.getvalue()
+ em_png_bytes = None
+ if emissive_image is not None:
+ buf = BytesIO()
+ emissive_image.save(buf, format="PNG")
+ em_png_bytes = buf.getvalue()
vertices_buffer = vertices_np.tobytes()
indices_buffer = faces_np.tobytes()
uvs_buffer = uvs_np.tobytes() if uvs_np is not None else b""
colors_buffer = colors_np.tobytes() if colors_np is not None else b""
+ normals_buffer = normals_np.tobytes() if normals_np is not None else b""
+ tangents_buffer = tangents_np.tobytes() if tangents_np is not None else b""
texture_buffer = texture_png_bytes if texture_png_bytes is not None else b""
+ mr_buffer = mr_png_bytes if mr_png_bytes is not None else b""
+ nm_buffer = nm_png_bytes if nm_png_bytes is not None else b""
+ em_buffer = em_png_bytes if em_png_bytes is not None else b""
def pad_to_4_bytes(buffer):
padding_length = (4 - (len(buffer) % 4)) % 4
return buffer + b'\x00' * padding_length
- vertices_buffer_padded = pad_to_4_bytes(vertices_buffer)
- indices_buffer_padded = pad_to_4_bytes(indices_buffer)
- uvs_buffer_padded = pad_to_4_bytes(uvs_buffer)
- colors_buffer_padded = pad_to_4_bytes(colors_buffer)
- texture_buffer_padded = pad_to_4_bytes(texture_buffer)
-
- buffer_data = b"".join([
- vertices_buffer_padded,
- indices_buffer_padded,
- uvs_buffer_padded,
- colors_buffer_padded,
- texture_buffer_padded,
- ])
+ # Blob order in one place; offsets accumulated in a pass so adding a buffer is one entry.
+ _blobs = [
+ ("vertices", vertices_buffer), ("indices", indices_buffer), ("uvs", uvs_buffer),
+ ("colors", colors_buffer), ("normals", normals_buffer), ("tangents", tangents_buffer),
+ ("texture", texture_buffer), ("mr", mr_buffer), ("nm", nm_buffer), ("em", em_buffer),
+ ]
+ byte_offset = {}
+ acc = 0
+ parts = []
+ for name, b in _blobs:
+ padded = pad_to_4_bytes(b)
+ byte_offset[name] = acc
+ acc += len(padded)
+ parts.append(padded)
+ buffer_data = b"".join(parts)
vertices_byte_length = len(vertices_buffer)
- vertices_byte_offset = 0
indices_byte_length = len(indices_buffer)
- indices_byte_offset = len(vertices_buffer_padded)
- uvs_byte_offset = indices_byte_offset + len(indices_buffer_padded)
- colors_byte_offset = uvs_byte_offset + len(uvs_buffer_padded)
- texture_byte_offset = colors_byte_offset + len(colors_buffer_padded)
+ vertices_byte_offset = byte_offset["vertices"]
+ indices_byte_offset = byte_offset["indices"]
+ uvs_byte_offset = byte_offset["uvs"]
+ colors_byte_offset = byte_offset["colors"]
+ normals_byte_offset = byte_offset["normals"]
+ tangents_byte_offset = byte_offset["tangents"]
+ texture_byte_offset = byte_offset["texture"]
+ mr_byte_offset = byte_offset["mr"]
+ nm_byte_offset = byte_offset["nm"]
+ em_byte_offset = byte_offset["em"]
buffer_views = [
{
@@ -224,6 +310,40 @@ def save_glb(vertices, faces, filepath, metadata=None,
})
primitive_attributes["COLOR_0"] = accessor_idx
+ if normals_np is not None and len(normals_np) > 0:
+ buffer_views.append({
+ "buffer": 0,
+ "byteOffset": normals_byte_offset,
+ "byteLength": len(normals_buffer),
+ "target": 34962
+ })
+ accessor_idx = len(accessors)
+ accessors.append({
+ "bufferView": len(buffer_views) - 1,
+ "byteOffset": 0,
+ "componentType": 5126, # FLOAT
+ "count": len(normals_np),
+ "type": "VEC3",
+ })
+ primitive_attributes["NORMAL"] = accessor_idx
+
+ if tangents_np is not None and len(tangents_np) > 0:
+ buffer_views.append({
+ "buffer": 0,
+ "byteOffset": tangents_byte_offset,
+ "byteLength": len(tangents_buffer),
+ "target": 34962
+ })
+ accessor_idx = len(accessors)
+ accessors.append({
+ "bufferView": len(buffer_views) - 1,
+ "byteOffset": 0,
+ "componentType": 5126, # FLOAT
+ "count": len(tangents_np),
+ "type": "VEC4", # xyz tangent + w handedness (glTF TANGENT)
+ })
+ primitive_attributes["TANGENT"] = accessor_idx
+
primitive = {
"attributes": primitive_attributes,
"indices": 1,
@@ -235,9 +355,24 @@ def save_glb(vertices, faces, filepath, metadata=None,
samplers = []
materials = []
extensions_used = []
+
+ def add_image_texture(png_byte_offset, png_byte_length):
+ """Append an embedded PNG image + a texture referencing it; return the texture index."""
+ buffer_views.append({"buffer": 0, "byteOffset": png_byte_offset, "byteLength": png_byte_length})
+ images.append({"bufferView": len(buffer_views) - 1, "mimeType": "image/png"})
+ if not samplers:
+ samplers.append({"magFilter": 9729, "minFilter": 9729, "wrapS": 33071, "wrapT": 33071})
+ textures.append({"source": len(images) - 1, "sampler": 0})
+ return len(textures) - 1
+
+ has_uv = "TEXCOORD_0" in primitive_attributes
if unlit and texture_png_bytes is None:
# Flat, light-independent shading (KHR_materials_unlit): COLOR_0 is shown as-is, matching how a
# gaussian splat renders (emissive). Without this the viewer lights the mesh and washes the colours.
+ if nm_png_bytes is not None or em_png_bytes is not None or occlusion_in_mr or material is not None:
+ logging.warning(
+ "save_glb: unlit material ignores normal/occlusion/emissive maps and SetMeshMaterial "
+ "overrides — those are PBR-lit features. Disable unlit to export them.")
materials.append({
"pbrMetallicRoughness": {"baseColorFactor": [1.0, 1.0, 1.0, 1.0], "metallicFactor": 0.0, "roughnessFactor": 1.0},
"extensions": {"KHR_materials_unlit": {}},
@@ -245,23 +380,67 @@ def save_glb(vertices, faces, filepath, metadata=None,
})
extensions_used.append("KHR_materials_unlit")
primitive["material"] = 0
- if texture_png_bytes is not None and "TEXCOORD_0" in primitive_attributes:
- buffer_views.append({
- "buffer": 0,
- "byteOffset": texture_byte_offset,
- "byteLength": len(texture_buffer),
- })
- images.append({"bufferView": len(buffer_views) - 1, "mimeType": "image/png"})
- samplers.append({"magFilter": 9729, "minFilter": 9729, "wrapS": 33071, "wrapT": 33071})
- textures.append({"source": 0, "sampler": 0})
- materials.append({
- "pbrMetallicRoughness": {
- "baseColorTexture": {"index": 0, "texCoord": 0},
- "metallicFactor": 0.0,
- "roughnessFactor": 1.0,
- },
- "doubleSided": True,
- })
+ else:
+ pbr = {
+ "metallicFactor": 0.0,
+ "roughnessFactor": 0.5,
+ "baseColorFactor": [0.22, 0.22, 0.22, 1.0], # neutral-gray fallback for bare geometry only
+ }
+ if texture_png_bytes is not None and has_uv:
+ pbr["baseColorTexture"] = {"index": add_image_texture(texture_byte_offset, len(texture_buffer)), "texCoord": 0}
+
+ if (texture_png_bytes is not None and has_uv) or "COLOR_0" in primitive_attributes:
+ pbr["baseColorFactor"] = [1.0, 1.0, 1.0, 1.0]
+ pbr["roughnessFactor"] = 1.0
+
+ if mr_png_bytes is not None and has_uv:
+ mr_texture_index = add_image_texture(mr_byte_offset, len(mr_buffer))
+ pbr["metallicRoughnessTexture"] = {"index": mr_texture_index, "texCoord": 0}
+ # When a metallicRoughness texture is present, the factors scale it; use 1.0
+ # so the texture values pass through unchanged (glTF convention).
+ pbr["metallicFactor"] = 1.0
+ pbr["roughnessFactor"] = 1.0
+
+ mat = material if isinstance(material, dict) else {}
+ # Scalar overrides from SetMeshMaterial (factor < 0 means "leave auto").
+ if mat.get("base_color_factor") is not None:
+ pbr["baseColorFactor"] = [float(x) for x in mat["base_color_factor"]]
+ if mat.get("metallic_factor", -1.0) >= 0.0:
+ pbr["metallicFactor"] = float(mat["metallic_factor"])
+ if mat.get("roughness_factor", -1.0) >= 0.0:
+ pbr["roughnessFactor"] = float(mat["roughness_factor"])
+
+ material = {
+ "pbrMetallicRoughness": pbr,
+ "doubleSided": bool(mat.get("double_sided", True)),
+ }
+ if occlusion_in_mr and mr_png_bytes is not None and has_uv:
+ # ORM packing: occlusionTexture reuses the MR image (glTF reads its R channel).
+ material["occlusionTexture"] = {"index": mr_texture_index, "texCoord": 0,
+ "strength": float(mat.get("occlusion_strength", 1.0))}
+ if nm_png_bytes is not None and has_uv:
+ material["normalTexture"] = {"index": add_image_texture(nm_byte_offset, len(nm_buffer)),
+ "texCoord": 0, "scale": float(mat.get("normal_scale", 1.0))}
+
+ emissive_factor = [float(x) for x in mat.get("emissive_factor", [0.0, 0.0, 0.0])]
+ emissive_strength = float(mat.get("emissive_strength", 1.0))
+ has_em_tex = em_png_bytes is not None and has_uv
+ if any(c > 0.0 for c in emissive_factor) or has_em_tex:
+ # glTF multiplies emissiveFactor × texture, so a texture with no color would go black;
+ # default the factor to white in that case.
+ if has_em_tex and not any(c > 0.0 for c in emissive_factor):
+ emissive_factor = [1.0, 1.0, 1.0]
+ material["emissiveFactor"] = [min(1.0, c) for c in emissive_factor]
+ if has_em_tex:
+ material["emissiveTexture"] = {"index": add_image_texture(em_byte_offset, len(em_buffer)),
+ "texCoord": 0}
+ if emissive_strength != 1.0:
+ material.setdefault("extensions", {})["KHR_materials_emissive_strength"] = {
+ "emissiveStrength": emissive_strength}
+ if "KHR_materials_emissive_strength" not in extensions_used:
+ extensions_used.append("KHR_materials_emissive_strength")
+
+ materials.append(material)
primitive["material"] = 0
gltf = {
@@ -306,17 +485,48 @@ def save_glb(vertices, faces, filepath, metadata=None,
# Create BIN chunk header (chunk type 1)
bin_chunk_header = struct.pack('<II', len(buffer_data), 0x004E4942) # "BIN\0" in little endian
- # Write the GLB file
+ glb = b"".join([glb_header, json_chunk_header, gltf_json_padded, bin_chunk_header, buffer_data])
+ if filepath is None:
+ return glb # in-memory GLB bytes (e.g. for a File3D object)
with open(filepath, 'wb') as f:
- f.write(glb_header)
- f.write(json_chunk_header)
- f.write(gltf_json_padded)
- f.write(bin_chunk_header)
- f.write(buffer_data)
-
+ f.write(glb)
return filepath
+def mesh_item_to_glb_bytes(mesh, index, metadata=None):
+ """Serialize one batch item of a MESH to in-memory GLB bytes, carrying every PBR attribute
+ (uvs, colors, normals, texture, ORM/occlusion, normal map + tangents, emissive, material).
+ Returns None for an empty item. Shared by SaveGLB (per item) and MeshToFile3D."""
+ vertices_i, faces_i, v_colors, uvs_i, normals_i = get_mesh_batch_item(mesh, index)
+ if vertices_i.shape[0] == 0 or faces_i.shape[0] == 0:
+ return None
+
+ def _img(attr):
+ t = getattr(mesh, attr, None)
+ if t is None:
+ return None
+ a = (t[index].clamp(0.0, 1.0).cpu().numpy() * 255).astype(np.uint8)
+ assert a.ndim == 3 and a.shape[-1] == 3, f"{attr} must be (B, H, W, 3), got {tuple(t.shape)}"
+ return Image.fromarray(a, mode="RGB")
+
+ tangents_b = mesh.tangents
+ tangents_i = tangents_b[index, :vertices_i.shape[0]] if tangents_b is not None else None
+ return save_glb(
+ vertices_i, faces_i, None, metadata,
+ uvs=uvs_i,
+ vertex_colors=v_colors,
+ texture_image=_img("texture"),
+ metallic_roughness_image=_img("metallic_roughness"),
+ unlit=mesh.unlit,
+ normals=normals_i,
+ normal_map_image=_img("normal_map"),
+ tangents=tangents_i,
+ occlusion_in_mr=mesh.occlusion_in_mr,
+ material=mesh.material,
+ emissive_image=_img("emissive"),
+ )
+
+
class SaveGLB(IO.ComfyNode):
@classmethod
def define_schema(cls):
@@ -378,25 +588,14 @@ class SaveGLB(IO.ComfyNode):
counter += 1
else:
# Handle Mesh input - save vertices and faces as GLB; carry optional UVs / colors / texture.
- texture_b = getattr(mesh, "texture", None)
- texture_np = None
- if texture_b is not None:
- texture_np = (texture_b.clamp(0.0, 1.0).cpu().numpy() * 255).astype(np.uint8)
- assert texture_np.ndim == 4 and texture_np.shape[-1] == 3, (
- f"texture must be (B, H, W, 3) RGB, got shape {tuple(texture_np.shape)}"
- )
for i in range(mesh.vertices.shape[0]):
- vertices_i, faces_i, v_colors, uvs_i = get_mesh_batch_item(mesh, i)
- if vertices_i.shape[0] == 0 or faces_i.shape[0] == 0:
+ glb = mesh_item_to_glb_bytes(mesh, i, metadata)
+ if glb is None:
logging.warning(f"SaveGLB: skipping empty mesh at batch index {i}")
continue
- tex_img = Image.fromarray(texture_np[i], mode="RGB") if texture_np is not None else None
f = f"{filename}_{counter:05}_.glb"
- save_glb(vertices_i, faces_i, os.path.join(full_output_folder, f), metadata,
- uvs=uvs_i,
- vertex_colors=v_colors,
- texture_image=tex_img,
- unlit=getattr(mesh, "unlit", False))
+ with open(os.path.join(full_output_folder, f), "wb") as fh:
+ fh.write(glb)
results.append({
"filename": f,
"subfolder": subfolder,
@@ -406,6 +605,277 @@ class SaveGLB(IO.ComfyNode):
return IO.NodeOutput(ui={"3d": results})
+class MeshToFile3D(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="MeshToFile3D",
+ display_name="Create 3D File (from Mesh)",
+ search_aliases=["mesh to glb", "mesh to file", "export mesh"],
+ category="3d",
+ description="Serialize a mesh to a GLB File3D object for Save / Preview 3D nodes, "
+ "carrying its UVs, colors, normals, texture, normal/occlusion/emissive "
+ "maps and material. Supports one item per batch only.",
+ inputs=[IO.Mesh.Input("mesh")],
+ outputs=[IO.File3DGLB.Output(display_name="model_3d")],
+ )
+
+ @classmethod
+ def execute(cls, mesh) -> IO.NodeOutput:
+ if mesh.vertices.shape[0] > 1:
+ logging.warning("MeshToFile3D supports one item per batch only. Got %d; using first.",
+ mesh.vertices.shape[0])
+ glb = mesh_item_to_glb_bytes(mesh, 0)
+ if glb is None:
+ raise ValueError("MeshToFile3D: mesh is empty (no vertices/faces).")
+ return IO.NodeOutput(Types.File3D(BytesIO(glb), file_format="glb"))
+
+
+class RotateMesh(IO.ComfyNode):
+ class ModeValues(TypedDict, total=False):
+ mode: str
+ angle_x: float
+ angle_y: float
+ angle_z: float
+ qw: float
+ qx: float
+ qy: float
+ qz: float
+
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="RotateMesh",
+ display_name="Rotate Mesh",
+ category="3d/mesh",
+ description=(
+ "Rotate a mesh. Euler XYZ applies X then Y then Z about the world axes (degrees). "
+ "Quaternion is (w, x, y, z), auto-normalized."
+ ),
+ inputs=[
+ IO.Mesh.Input("mesh"),
+ IO.DynamicCombo.Input(
+ "mode",
+ options=[
+ IO.DynamicCombo.Option("euler_xyz", [
+ IO.Float.Input("angle_x", default=0.0, min=-360.0, max=360.0, step=0.1,
+ tooltip="Rotation around the X axis in degrees."),
+ IO.Float.Input("angle_y", default=0.0, min=-360.0, max=360.0, step=0.1,
+ tooltip="Rotation around the Y axis in degrees."),
+ IO.Float.Input("angle_z", default=0.0, min=-360.0, max=360.0, step=0.1,
+ tooltip="Rotation around the Z axis in degrees."),
+ ]),
+ IO.DynamicCombo.Option("quaternion", [
+ IO.Float.Input("qw", default=1.0, min=-1.0, max=1.0, step=0.001),
+ IO.Float.Input("qx", default=0.0, min=-1.0, max=1.0, step=0.001),
+ IO.Float.Input("qy", default=0.0, min=-1.0, max=1.0, step=0.001),
+ IO.Float.Input("qz", default=0.0, min=-1.0, max=1.0, step=0.001),
+ ]),
+ ],
+ ),
+ ],
+ outputs=[IO.Mesh.Output("mesh")],
+ )
+
+ @classmethod
+ def execute(cls, mesh: Types.MESH, mode: ModeValues) -> IO.NodeOutput:
+ mode_name = mode["mode"]
+ if mode_name == "euler_xyz":
+ ax = math.radians(mode["angle_x"])
+ ay = math.radians(mode["angle_y"])
+ az = math.radians(mode["angle_z"])
+ if ax == 0.0 and ay == 0.0 and az == 0.0:
+ return IO.NodeOutput(mesh)
+ cx, sx = math.cos(ax), math.sin(ax)
+ cy, sy = math.cos(ay), math.sin(ay)
+ cz, sz = math.cos(az), math.sin(az)
+ R_rows = [
+ [cy * cz, sx * sy * cz - cx * sz, cx * sy * cz + sx * sz],
+ [cy * sz, sx * sy * sz + cx * cz, cx * sy * sz - sx * cz],
+ [-sy, sx * cy, cx * cy],
+ ]
+ elif mode_name == "quaternion":
+ qw, qx, qy, qz = mode["qw"], mode["qx"], mode["qy"], mode["qz"]
+ n = math.sqrt(qw * qw + qx * qx + qy * qy + qz * qz)
+ if n < 1e-8:
+ raise ValueError("RotateMesh: quaternion has zero magnitude")
+ qw, qx, qy, qz = qw / n, qx / n, qy / n, qz / n
+ if qw == 1.0 and qx == 0.0 and qy == 0.0 and qz == 0.0:
+ return IO.NodeOutput(mesh)
+ R_rows = [
+ [1 - 2 * (qy * qy + qz * qz), 2 * (qx * qy - qz * qw), 2 * (qx * qz + qy * qw)],
+ [2 * (qx * qy + qz * qw), 1 - 2 * (qx * qx + qz * qz), 2 * (qy * qz - qx * qw)],
+ [2 * (qx * qz - qy * qw), 2 * (qy * qz + qx * qw), 1 - 2 * (qx * qx + qy * qy)],
+ ]
+ else:
+ raise ValueError(f"RotateMesh: unknown mode {mode_name!r}")
+
+ def rotate(v: torch.Tensor) -> torch.Tensor:
+ R = torch.tensor(R_rows, device=v.device, dtype=v.dtype)
+ return v @ R.T
+
+ out = copy.copy(mesh)
+ if isinstance(mesh.vertices, list):
+ out.vertices = [rotate(v) for v in mesh.vertices]
+ else:
+ out.vertices = rotate(mesh.vertices)
+ # Normals are directions, rotate them too (R is orthogonal).
+ nrm = mesh.normals
+ if nrm is not None:
+ out.normals = [rotate(n) for n in nrm] if isinstance(nrm, list) else rotate(nrm)
+ # Tangents (xyz + handedness w) are directions too: rotate xyz, keep w
+ tng = mesh.tangents
+ if tng is not None:
+ def rotate_tangent(t: torch.Tensor) -> torch.Tensor:
+ rt = t.clone()
+ rt[..., :3] = rotate(t[..., :3])
+ return rt
+ out.tangents = ([rotate_tangent(t) for t in tng] if isinstance(tng, list)
+ else rotate_tangent(tng))
+ return IO.NodeOutput(out)
+
+
+class MergeMeshes(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ autogrow_template = IO.Autogrow.TemplatePrefix(
+ IO.Mesh.Input("mesh"), prefix="mesh", min=2, max=50,
+ )
+ return IO.Schema(
+ node_id="MergeMeshes",
+ display_name="Merge Meshes",
+ category="3d/mesh",
+ description=(
+ "Concatenate N meshes into one by offsetting face indices and stacking verts, "
+ "faces, uvs, and colors."
+ ),
+ inputs=[
+ IO.Autogrow.Input("meshes", template=autogrow_template),
+ ],
+ outputs=[IO.Mesh.Output("mesh")],
+ )
+
+ @classmethod
+ def execute(cls, meshes: IO.Autogrow.Type) -> IO.NodeOutput:
+ # Concatenate the input meshes into one (B=1) mesh: cumulative face-index offset,
+ # missing uvs/colors padded (zeros/white), texture from the first input that has one
+ # (later dropped — a single-primitive glb can't carry multiple atlases).
+ meshes = list(meshes.values())
+ if not meshes:
+ raise ValueError("MergeMeshes: need at least one mesh")
+
+ any_uvs = any(m.uvs is not None for m in meshes)
+ any_colors = any(m.vertex_colors is not None for m in meshes)
+ color_channels = max((int(m.vertex_colors.shape[-1]) for m in meshes if m.vertex_colors is not None), default=3)
+
+ verts_list, faces_list, uvs_list, colors_list = [], [], [], []
+ texture = None
+ offset = 0
+ for m in meshes:
+ # Coerce to CPU so CUDA-side (MoGe) meshes merge cleanly with our outputs.
+ v, f, mc, mu, _ = get_mesh_batch_item(m, 0)
+ v = v.cpu()
+ f = f.cpu()
+ verts_list.append(v)
+ faces_list.append(f + offset)
+ offset += v.shape[0]
+ if any_uvs:
+ uvs_list.append(mu.cpu() if mu is not None else v.new_zeros((v.shape[0], 2)))
+ if any_colors:
+ c = mc.cpu() if mc is not None else v.new_ones((v.shape[0], color_channels))
+ if c.shape[-1] < color_channels:
+ c = torch.cat((c, c.new_ones((c.shape[0], color_channels - c.shape[-1]))), dim=-1)
+ colors_list.append(c)
+ mt = m.texture
+ if mt is not None:
+ if texture is None:
+ texture = mt.cpu()
+ else:
+ logging.warning("MergeMeshes: dropping extra texture from input; only one texture is kept.")
+
+ merged_verts = torch.cat(verts_list, dim=0).unsqueeze(0)
+ merged_faces = torch.cat(faces_list, dim=0).unsqueeze(0)
+ merged_uvs = torch.cat(uvs_list, dim=0).unsqueeze(0) if any_uvs else None
+ merged_colors = torch.cat(colors_list, dim=0).unsqueeze(0) if any_colors else None
+
+ return IO.NodeOutput(Types.MESH(
+ vertices=merged_verts,
+ faces=merged_faces,
+ uvs=merged_uvs,
+ vertex_colors=merged_colors,
+ texture=texture,
+ ))
+
+
+class GetMeshInfo(IO.ComfyNode):
+ """Report vertex / face counts and attributes for a MESH, displayed on the
+ node (and as a string output). Counts are comma-formatted since meshes can
+ run into the millions of faces. Passes the mesh through unchanged."""
+
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="GetMeshInfo",
+ display_name="Get Mesh Info",
+ category="3d/mesh",
+ inputs=[IO.Mesh.Input("mesh")],
+ outputs=[
+ IO.Mesh.Output(display_name="mesh"),
+ IO.String.Output(display_name="info"),
+ ],
+ hidden=[IO.Hidden.unique_id],
+ )
+
+ @staticmethod
+ def _fmt(n: int) -> str:
+ # e.g. 1234567 -> "1,234,567 (1.23M)"; small numbers stay plain.
+ s = f"{n:,}"
+ if n >= 1_000_000:
+ s += f" ({n / 1_000_000:.2f}M)"
+ elif n >= 10_000:
+ s += f" ({n / 1_000:.1f}K)"
+ return s
+
+ @classmethod
+ def execute(cls, mesh):
+ B = mesh.vertices.shape[0]
+ # Honour per-item counts when the batch is zero-padded; else use the row sizes.
+ if mesh.vertex_counts is not None:
+ v_counts = [int(x) for x in mesh.vertex_counts.tolist()]
+ f_counts = [int(x) for x in mesh.face_counts.tolist()]
+ else:
+ v_counts = [int(mesh.vertices.shape[1])] * B
+ f_counts = [int(mesh.faces.shape[1])] * B
+
+ attrs = []
+ for name in ("uvs", "vertex_colors", "normals", "tangents", "texture", "metallic_roughness", "normal_map"):
+ t = getattr(mesh, name, None)
+ if t is not None:
+ if name in ("texture", "metallic_roughness", "normal_map"):
+ attrs.append(f"{name} {int(t.shape[-3])}×{int(t.shape[-2])}") # H×W
+ else:
+ attrs.append(name)
+
+ lines = []
+ if B > 1:
+ lines.append(f"Batch: {B} meshes")
+ lines.append(f"Vertices: {cls._fmt(sum(v_counts))} total")
+ lines.append(f"Faces: {cls._fmt(sum(f_counts))} total")
+ for i in range(B):
+ lines.append(f" [{i}] {v_counts[i]:>10,} verts · {f_counts[i]:>10,} faces")
+ else:
+ lines.append(f"Vertices: {cls._fmt(v_counts[0])}")
+ lines.append(f"Faces: {cls._fmt(f_counts[0])}")
+ lines.append(f"Attributes: {', '.join(attrs) if attrs else 'none'}")
+
+ info = "\n".join(lines)
+ logging.info("[GetMeshInfo]\n%s", info)
+
+ if cls.hidden.unique_id:
+ PromptServer.instance.send_progress_text(info, cls.hidden.unique_id)
+ return IO.NodeOutput(mesh, info, ui=UI.PreviewText(info))
+
+
def _save_file3d_to_output(model_3d: Types.File3D, filename_prefix: str) -> str:
full_output_folder, filename, counter, subfolder, filename_prefix = folder_paths.get_save_image_path(
filename_prefix, folder_paths.get_output_directory()
@@ -564,7 +1034,7 @@ class SavePointCloud(IO.ComfyNode):
class Save3DExtension(ComfyExtension):
@override
async def get_node_list(self) -> list[type[IO.ComfyNode]]:
- return [SaveGLB, Save3DAdvanced, SaveGaussianSplat, SavePointCloud]
+ return [SaveGLB, MeshToFile3D, RotateMesh, MergeMeshes, GetMeshInfo, Save3DAdvanced, SaveGaussianSplat, SavePointCloud]
async def comfy_entrypoint() -> Save3DExtension:
diff --git a/comfy_extras/nodes_trellis2.py b/comfy_extras/nodes_trellis2.py
new file mode 100644
index 000000000..57bd2c4cc
--- /dev/null
+++ b/comfy_extras/nodes_trellis2.py
@@ -0,0 +1,781 @@
+from typing_extensions import override
+from comfy_api.latest import ComfyExtension, IO, Types, io
+from comfy.ldm.trellis2.vae import SparseTensor
+from comfy.ldm.trellis2.model import build_proj_transform_matrix, compute_stage_proj_feats
+
+from comfy_extras.nodes_mesh_postprocess import pack_variable_mesh_batch
+import comfy.latent_formats
+import comfy.model_management
+import comfy.utils
+import math
+import torch
+
+ShapeSubdivides = io.Custom("SHAPE_SUBDIVIDES")
+
+
+shape_slat_format = comfy.latent_formats.Trellis2ShapeSLAT()
+tex_slat_format = comfy.latent_formats.Trellis2TexSLAT()
+
+def shape_norm(shape_latent, coords):
+ feats = shape_slat_format.process_out(shape_latent)
+ return SparseTensor(feats=feats, coords=coords)
+
+
+def infer_batched_coord_layout(coords):
+ if coords.ndim != 2 or coords.shape[1] != 4:
+ raise ValueError(f"Expected Trellis2 coords with shape [N, 4], got {tuple(coords.shape)}")
+
+ if coords.shape[0] == 0:
+ raise ValueError("Trellis2 coords can't be empty")
+
+ batch_ids = coords[:, 0].to(torch.int64)
+ if (batch_ids < 0).any():
+ raise ValueError(f"Trellis2 batch ids must be non-negative, got {batch_ids.unique(sorted=True).tolist()}")
+ batch_size = int(batch_ids.max().item()) + 1
+ counts = torch.bincount(batch_ids, minlength=batch_size)
+
+ if (counts == 0).any():
+ raise ValueError(f"Non-contiguous Trellis2 batch ids in coords: {batch_ids.unique(sorted=True).tolist()}")
+
+ max_tokens = int(counts.max().item())
+ return batch_size, counts, max_tokens
+
+
+def split_batched_coords(coords, coord_counts):
+ if coord_counts.ndim != 1:
+ raise ValueError(f"Trellis2 coord_counts must be 1D, got shape {tuple(coord_counts.shape)}")
+ counts = [int(count) for count in coord_counts.tolist()]
+ if any(count < 0 for count in counts):
+ raise ValueError(f"Trellis2 coord_counts must be non-negative, got {counts}")
+ if sum(counts) != coords.shape[0]:
+ raise ValueError(
+ f"Trellis2 coord_counts total {sum(counts)} does not match coords rows {coords.shape[0]}"
+ )
+
+ batch_ids = coords[:, 0].to(torch.int64)
+ order = torch.argsort(batch_ids, stable=True)
+ sorted_coords = coords.index_select(0, order)
+ sorted_batch_ids = batch_ids.index_select(0, order)
+
+ items = []
+ start = 0
+ for i, count in enumerate(counts):
+ coords_i = sorted_coords[start:start + count]
+ ids_i = sorted_batch_ids[start:start + count]
+ if coords_i.shape[0] != count or not torch.all(ids_i == i):
+ raise ValueError(f"Trellis2 coords rows for batch {i} expected {count}, got {coords_i.shape[0]}")
+ items.append(coords_i)
+ start += count
+ return items
+
+def flatten_batched_sparse_latent(samples, coords, coord_counts):
+ samples = samples.squeeze(-1).transpose(1, 2)
+ if coord_counts is None:
+ return samples.reshape(-1, samples.shape[-1]), coords
+
+ coords_items = split_batched_coords(coords, coord_counts)
+ feat_list = []
+ coord_list = []
+ for i, coords_i in enumerate(coords_items):
+ count = coords_i.shape[0]
+ feat_list.append(samples[i, :count])
+ coord_list.append(coords_i)
+
+ return torch.cat(feat_list, dim=0), torch.cat(coord_list, dim=0)
+
+
+def split_batched_sparse_latent(samples, coords, coord_counts):
+ samples = samples.squeeze(-1).transpose(1, 2)
+ if coord_counts is None:
+ return [(samples.reshape(-1, samples.shape[-1]), coords)]
+
+ coords_items = split_batched_coords(coords, coord_counts)
+ items = []
+ for i, coords_i in enumerate(coords_items):
+ count = coords_i.shape[0]
+ items.append((samples[i, :count], coords_i))
+ return items
+
+class VaeDecodeShapeTrellis(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="VaeDecodeShapeTrellis",
+ category="model/latent/trellis",
+ inputs=[
+ IO.Latent.Input("samples"),
+ IO.Vae.Input("vae"),
+ ],
+ outputs=[
+ IO.Mesh.Output("mesh"),
+ ShapeSubdivides.Output(display_name = "shape_subdivides"),
+ ]
+ )
+
+ @classmethod
+ def execute(cls, samples, vae):
+ # Mesh grid_size must match the actual coord resolution the upstream
+ # stage was run at (1024 cascade -> 64, 1536 cascade -> 96). The VAE's
+ # built-in `.resolution` buffer defaults to 1024 and is otherwise stale;
+ # take coord_resolution from the latent dict if the stage node set it.
+ coord_resolution = samples.get("coord_resolution")
+ if coord_resolution is not None:
+ resolution = int(coord_resolution) * 16
+ else:
+ resolution = int(vae.first_stage_model.resolution.item())
+ model_frame = samples.get("model_frame", "y_up")
+ sample_tensor = samples["samples"]
+ device = comfy.model_management.get_torch_device()
+ coords = samples["coords"]
+ vae.prepare_decode(sample_tensor.shape)
+ trellis_vae = vae.first_stage_model
+ coord_counts = samples.get("coord_counts")
+
+ samples = samples["samples"]
+ if coord_counts is None:
+ samples, coords = flatten_batched_sparse_latent(samples, coords, coord_counts)
+ samples = shape_norm(samples.to(device), coords.to(device))
+ mesh, subs = trellis_vae.decode_shape_slat(samples.to(vae.vae_dtype), resolution)
+ else:
+ split_items = split_batched_sparse_latent(samples, coords, coord_counts)
+ mesh = []
+ subs_per_sample = []
+ for feats_i, coords_i in split_items:
+ coords_i = coords_i.to(device).clone()
+ coords_i[:, 0] = 0
+ sample_i = shape_norm(feats_i.to(device), coords_i)
+ mesh_i, subs_i = trellis_vae.decode_shape_slat(sample_i.to(vae.vae_dtype), resolution)
+ mesh.append(mesh_i[0])
+ subs_per_sample.append(subs_i)
+
+ subs = []
+ for stage_index in range(len(subs_per_sample[0])):
+ stage_tensors = [sample_subs[stage_index] for sample_subs in subs_per_sample]
+ feats_list = [stage_tensor.feats for stage_tensor in stage_tensors]
+ coords_list = [stage_tensor.coords for stage_tensor in stage_tensors]
+ subs.append(SparseTensor.from_tensor_list(feats_list, coords_list))
+
+ # Rotate Z-up (Trellis2 training frame) vertices to glTF Y-up. Pixal3D outputs are already Y-up.
+ if model_frame == "z_up":
+ vert_list = [torch.stack([v[..., 0], v[..., 2], -v[..., 1]], dim=-1).float().cpu()
+ for v, _ in mesh]
+ else:
+ vert_list = [v.float().cpu() for v, _ in mesh]
+ face_list = [f.int().cpu() for _, f in mesh]
+ if all(v.shape == vert_list[0].shape for v in vert_list) and all(f.shape == face_list[0].shape for f in face_list):
+ mesh = Types.MESH(vertices=torch.stack(vert_list), faces=torch.stack(face_list))
+ else:
+ mesh = pack_variable_mesh_batch(vert_list, face_list)
+ return IO.NodeOutput(mesh, subs)
+
+class VaeDecodeTextureTrellis(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="VaeDecodeTextureTrellis",
+ category="model/latent/trellis",
+ inputs=[
+ IO.Latent.Input("samples"),
+ IO.Vae.Input("vae"),
+ ShapeSubdivides.Input("shape_subdivides",
+ tooltip=(
+ "Shape information used to guide higher-detail reconstruction during decoding. "
+ "Helps preserve structure consistency at higher resolutions."
+ )),
+ ],
+ outputs=[
+ IO.Voxel.Output("voxel_colors"),
+ ]
+ )
+
+ @classmethod
+ def execute(cls, samples, vae, shape_subdivides):
+ sample_tensor = samples["samples"]
+ device = comfy.model_management.get_torch_device()
+ coords = samples["coords"]
+ vae.prepare_decode(sample_tensor.shape)
+ trellis_vae = vae.first_stage_model
+ coord_counts = samples.get("coord_counts")
+ model_frame = samples.get("model_frame", "y_up")
+ coord_resolution = samples.get("coord_resolution")
+
+ samples = samples["samples"]
+ samples, coords = flatten_batched_sparse_latent(samples, coords, coord_counts)
+ samples = samples.to(device)
+ feats = tex_slat_format.process_out(samples)
+ samples = SparseTensor(feats=feats, coords=coords.to(device))
+
+ voxel = trellis_vae.decode_tex_slat(samples.to(vae.vae_dtype), shape_subdivides)
+ # Keep all decoded channels. The texture VAE emits 6: base_color (0:3),
+ # metallic (3), roughness (4), alpha (5) — all in [0, 1]. Vertex-color
+ # consumers (PaintMesh) slice [:3]
+ color_feats = voxel.feats
+ voxel_coords = voxel.coords
+
+ if coord_resolution is not None:
+ tex_resolution = int(coord_resolution) * 16
+ elif voxel_coords.numel() > 0 and voxel_coords.shape[-1] >= 3:
+ spatial = voxel_coords[:, -3:] if voxel_coords.shape[-1] == 4 else voxel_coords
+ max_idx = int(spatial.max().item()) + 1
+ tex_resolution = next((r for r in (256, 512, 1024, 1536, 2048) if r >= max_idx), max_idx)
+ else:
+ tex_resolution = 1024
+
+ # Remap Z-up voxel coords to Y-up: (x, y, z) -> (x, z, R-1-y), matching the
+ # R_x(-90°) applied to mesh vertices in VaeDecodeShapeTrellis. Keeps PaintMesh's
+ # NN lookup correctly aligned without it needing to know the source frame.
+ if model_frame == "z_up" and voxel_coords.numel() > 0 and voxel_coords.shape[-1] >= 3:
+ R = tex_resolution
+ if voxel_coords.shape[-1] == 4:
+ batch_col = voxel_coords[:, :1]
+ spatial = voxel_coords[:, 1:]
+ spatial_yup = torch.stack(
+ [spatial[:, 0], spatial[:, 2], (R - 1) - spatial[:, 1]], dim=-1
+ )
+ voxel_coords = torch.cat([batch_col, spatial_yup], dim=-1)
+ else:
+ voxel_coords = torch.stack(
+ [voxel_coords[:, 0], voxel_coords[:, 2], (R - 1) - voxel_coords[:, 1]],
+ dim=-1,
+ )
+
+ voxel = Types.VOXEL(voxel_coords, color_feats, tex_resolution)
+ return IO.NodeOutput(voxel)
+
+class VaeDecodeStructureTrellis2(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="VaeDecodeStructureTrellis2",
+ category="model/latent/trellis",
+ inputs=[
+ IO.Latent.Input("samples"),
+ IO.Vae.Input("vae"),
+ IO.Combo.Input("resolution", options=["32", "64"], default="32"),
+ ],
+ outputs=[
+ IO.Voxel.Output("voxel"),
+ ]
+ )
+
+ @classmethod
+ def execute(cls, samples, vae, resolution):
+ resolution = int(resolution)
+ sample_tensor = samples["samples"]
+ sample_tensor = sample_tensor[:, :8]
+ batch_number = vae.prepare_decode(sample_tensor.shape)
+ shape_vae = vae.first_stage_model
+ load_device = comfy.model_management.get_torch_device()
+ decoded_batches = []
+ for start in range(0, sample_tensor.shape[0], batch_number):
+ sample_chunk = sample_tensor[start:start + batch_number].to(load_device)
+ decoded_batches.append(shape_vae.decode_structure(sample_chunk.to(vae.vae_dtype)) > 0)
+ decoded = torch.cat(decoded_batches, dim=0)
+ current_res = decoded.shape[2]
+
+ if current_res != resolution:
+ ratio = current_res // resolution
+ decoded = torch.nn.functional.max_pool3d(decoded.float(), ratio, ratio, 0) > 0.5
+ voxel_data = decoded.squeeze(1).float()
+ return IO.NodeOutput(Types.VOXEL(voxel_data))
+
+class Trellis2UpsampleStage(IO.ComfyNode):
+ """Cascade-upsamples a 512-resolution shape latent into high-resolution
+ sparse coords and sets up the second shape-stage sampling pass at the
+ target resolution, attaching per-stage metadata to the conditioning for
+ the model to consume via extra_conds."""
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="Trellis2UpsampleStage",
+ category="model/conditioning/trellis2",
+ display_name="Trellis2 Upsample Stage",
+ inputs=[
+ IO.Conditioning.Input("positive"),
+ IO.Conditioning.Input("negative"),
+ IO.Latent.Input("shape_latent", tooltip="The 512-resolution shape latent output from the first shape-stage KSampler."),
+ IO.Vae.Input("vae"),
+ IO.Int.Input("target_resolution", default=1024, min=1024, max=2048, step=128,
+ tooltip="Voxel resolution of the upsampled shape. Higher = more detail, more VRAM."),
+ ],
+ outputs=[
+ IO.Conditioning.Output(display_name="positive"),
+ IO.Conditioning.Output(display_name="negative"),
+ IO.Latent.Output(),
+ ]
+ )
+
+ @staticmethod
+ def _quantize_unique(hr_coords: torch.Tensor, lr_resolution: int, hr_resolution: int, pixal3d_mode: bool = False) -> torch.Tensor:
+ # Trellis2 uses `floor((c+0.5) * grid_res / lr_res)
+ # Pixal3D uses `round((c+0.5) * (grid_res-1) / lr_res)`
+ # this is a half-cell spatial shift. Branch so each upstream is matched bit-for-bit.
+ grid_res = hr_resolution // 16
+ spatial = hr_coords[:, 1:].float()
+ if pixal3d_mode:
+ spatial.add_(0.5).mul_((grid_res - 1) / lr_resolution).round_()
+ else:
+ spatial.add_(0.5).mul_(grid_res / lr_resolution)
+ quant = torch.cat([hr_coords[:, :1], spatial.int()], dim=1)
+ return quant.unique(dim=0)
+
+ @classmethod
+ def execute(cls, positive, negative, shape_latent, vae, target_resolution):
+ device = comfy.model_management.get_torch_device()
+ vae.prepare_decode(shape_latent["samples"].shape)
+
+ coord_counts = shape_latent.get("coord_counts")
+ shape_vae = vae.first_stage_model
+ lr_resolution = 512
+ proj_pack = _proj_pack_from_conditioning(positive)
+ pixal3d_mode = proj_pack is not None
+
+ # Decode each sample's HR coords, then search for the largest hr_resolution
+ # that fits under max_tokens across all samples.
+ if coord_counts is None:
+ feats, coords_512 = flatten_batched_sparse_latent(
+ shape_latent["samples"], shape_latent["coords"], coord_counts,
+ )
+ slat = shape_norm(feats.to(device), coords_512.to(device))
+ sample_hr_coords = [shape_vae.upsample_shape(slat.to(vae.vae_dtype), upsample_times=4)]
+ else:
+ items = split_batched_sparse_latent(
+ shape_latent["samples"], shape_latent["coords"], coord_counts,
+ )
+ sample_hr_coords = []
+ for feats_i, coords_i in items:
+ coords_i = coords_i.to(device).clone()
+ coords_i[:, 0] = 0
+ slat_i = shape_norm(feats_i.to(device), coords_i)
+ sample_hr_coords.append(shape_vae.upsample_shape(slat_i.to(vae.vae_dtype), upsample_times=4))
+
+ hr_resolution = target_resolution
+ quant_unique_list = [
+ cls._quantize_unique(hr_coords_i, lr_resolution, hr_resolution, pixal3d_mode)
+ for hr_coords_i in sample_hr_coords
+ ]
+
+ # Rewrite batch column to match per-sample offset and concat.
+ per_sample_counts = []
+ for sample_offset, qu in enumerate(quant_unique_list):
+ qu[:, 0] = sample_offset
+ per_sample_counts.append(int(qu.shape[0]))
+ coords = torch.cat(quant_unique_list, dim=0)
+ counts = torch.tensor(per_sample_counts, dtype=torch.int64)
+ coord_resolution = hr_resolution // 16
+
+ batch_size, _, max_tokens_out = infer_batched_coord_layout(coords)
+ latent = torch.zeros(batch_size, 32, max_tokens_out, 1)
+
+ extras = {
+ "trellis2_generation_mode": "shape_generation",
+ "trellis2_coords": coords,
+ "trellis2_coord_counts": counts,
+ }
+ if proj_pack is not None:
+ extras["trellis2_proj_feats"] = compute_stage_proj_feats(
+ proj_pack, "shape_1024", coords=coords, coord_resolution=coord_resolution,
+ )
+ positive_out = _conditioning_set_extras(positive, extras)
+ negative_out = _conditioning_set_extras(negative, extras)
+ out_latent = {"samples": latent, "coords": coords, "coord_counts": counts,
+ "coord_resolution": coord_resolution, "type": "trellis2",
+ "model_frame": shape_latent.get("model_frame",
+ "y_up" if proj_pack is not None else "z_up")}
+ return IO.NodeOutput(positive_out, negative_out, out_latent)
+
+def _dinov3_encode(model, image_bchw, image_size, want_patches=False):
+ """Run DINOv3 once at the requested resolution.
+
+ image_bchw: [B, 3, H, W] float in [0, 1] (any source resolution; resized here).
+ Returns the full sequence tensor (Trellis2 path) or a dict with the global
+ tokens split out + a 2D patch grid (Pixal3D path) when `want_patches=True`.
+ """
+ model_internal = model.model
+ device = comfy.model_management.get_torch_device()
+ img_t = comfy.utils.common_upscale(image_bchw, image_size, image_size, "lanczos", "disabled").to(device)
+ mean = torch.tensor(model.image_mean or [0.485, 0.456, 0.406], device=device).view(1, 3, 1, 1)
+ std = torch.tensor(model.image_std or [0.229, 0.224, 0.225], device=device).view(1, 3, 1, 1)
+ img_t = (img_t - mean) / std
+ tokens = model_internal(img_t, skip_norm_elementwise=True)[0]
+ if not want_patches:
+ return tokens
+ h_p = w_p = image_size // 16
+ n_reg = tokens.shape[1] - 1 - h_p * w_p
+ return {"tokens": tokens[:, :1 + n_reg], "patches_2d": _dinov3_patches_to_2d(tokens, image_size)}
+
+
+class Trellis2Conditioning(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="Trellis2Conditioning",
+ category="model/conditioning/trellis2",
+ inputs=[
+ IO.ClipVision.Input("clip_vision_model"),
+ IO.Image.Input("image", tooltip="Preprocessed image from ImageCropToMask (pad_factor=1.0 for TRELLIS.2)."),
+ ],
+ outputs=[
+ IO.Conditioning.Output(display_name="positive"),
+ IO.Conditioning.Output(display_name="negative"),
+ ]
+ )
+
+ @classmethod
+ def execute(cls, clip_vision_model, image) -> IO.NodeOutput:
+ out_device = comfy.model_management.intermediate_device()
+ cond = _dino_encode_batch(clip_vision_model, image, out_device)
+ cond_512_batched, cond_1024_batched = cond["global_512"], cond["global_1024"]
+ neg_cond_batched = torch.zeros_like(cond_512_batched)
+ neg_embeds_batched = torch.zeros_like(cond_1024_batched)
+
+ positive = [[cond_512_batched, {"embeds": cond_1024_batched}]]
+ negative = [[neg_cond_batched, {"embeds": neg_embeds_batched}]]
+ return IO.NodeOutput(positive, negative)
+
+def _proj_pack_from_conditioning(conditioning):
+ """Return the proj_feat_pack dict embedded in a Pixal3D conditioning (or None
+ for vanilla Trellis2 / no conditioning connected). Pixal3DConditioning ships
+ the pack in cond[0][1]["proj_feat_pack"]; Trellis2Conditioning doesn't set it."""
+ if not conditioning:
+ return None
+ entry = conditioning[0]
+ if not isinstance(entry, (list, tuple)) or len(entry) < 2 or not isinstance(entry[1], dict):
+ return None
+ return entry[1].get("proj_feat_pack")
+
+
+def _conditioning_set_extras(conditioning, extras: dict):
+ """Return a copy of `conditioning` with `extras` merged into each entry's
+ dict — same shallow-copy pattern ControlNetApplyAdvanced uses. The dicts
+ are copied so we don't mutate upstream conditioning."""
+ out = []
+ for entry in conditioning:
+ if isinstance(entry, (list, tuple)) and len(entry) >= 2 and isinstance(entry[1], dict):
+ new_dict = entry[1].copy()
+ new_dict.update(extras)
+ out.append([entry[0], new_dict])
+ else:
+ out.append(entry)
+ return out
+
+
+class Trellis2ShapeStage(IO.ComfyNode):
+ """Sets up the first shape-stage sampling pass: extracts sparse coords from
+ the dense structure voxel produced by VaeDecodeStructureTrellis2, builds an
+ empty sparse latent, and attaches per-stage metadata to the conditioning so
+ the model reads it via extra_conds at sample time. For the second shape pass
+ (post-upsample), use Trellis2UpsampleStage instead — it combines the cascade
+ and the second-pass stage setup."""
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="Trellis2ShapeStage",
+ category="model/conditioning/trellis2",
+ inputs=[
+ IO.Conditioning.Input("positive"),
+ IO.Conditioning.Input("negative"),
+ IO.Voxel.Input(
+ "voxel",
+ tooltip="Dense structure voxel from VaeDecodeStructureTrellis2.",
+ ),
+ ],
+ outputs=[
+ IO.Conditioning.Output(display_name="positive"),
+ IO.Conditioning.Output(display_name="negative"),
+ IO.Latent.Output(),
+ ]
+ )
+
+ @classmethod
+ def execute(cls, positive, negative, voxel):
+ decoded = voxel.data.unsqueeze(1)
+ coords = torch.argwhere(decoded.bool())[:, [0, 2, 3, 4]].int()
+ coord_resolution = int(decoded.shape[-1])
+
+ # Dispatch based on the upstream voxel resolution, mirroring upstream's
+ # pipeline_type → ss_res table:
+ # coord_res == 32 → first cascade shape pass OR pure-512 pipeline
+ # (img2shape_512 + shape_512 proj stage, 512 DINO).
+ # coord_res > 32 → pure-1024 non-cascade pipeline
+ # (img2shape + shape_1024 proj stage, 1024 DINO).
+ if coord_resolution <= 32:
+ mode = "shape_generation_512"
+ stage = "shape_512"
+ else:
+ mode = "shape_generation"
+ stage = "shape_1024"
+
+ batch_size, counts, max_tokens = infer_batched_coord_layout(coords)
+ latent = torch.zeros(batch_size, 32, max_tokens, 1)
+
+ extras = {
+ "trellis2_generation_mode": mode,
+ "trellis2_coords": coords,
+ "trellis2_coord_counts": counts,
+ }
+ proj_pack = _proj_pack_from_conditioning(positive)
+ if proj_pack is not None:
+ extras["trellis2_proj_feats"] = compute_stage_proj_feats(
+ proj_pack, stage, coords=coords, coord_resolution=coord_resolution,
+ )
+ positive_out = _conditioning_set_extras(positive, extras)
+ negative_out = _conditioning_set_extras(negative, extras)
+ out_latent = {"samples": latent, "coords": coords, "coord_counts": counts,
+ "coord_resolution": coord_resolution, "type": "trellis2",
+ "model_frame": "y_up" if proj_pack is not None else "z_up"}
+ return IO.NodeOutput(positive_out, negative_out, out_latent)
+
+
+class Trellis2TextureStage(IO.ComfyNode):
+ """Sets up the texture-stage sampling pass. Reads coords / coord_counts /
+ coord_resolution and the shape_slat (the per-voxel shape latent) from the
+ incoming shape_latent dict — set there by Trellis2ShapeStage or
+ Trellis2UpsampleStage. Builds an empty sparse latent at the same coord
+ layout and attaches per-stage metadata to the conditioning."""
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="Trellis2TextureStage",
+ category="model/conditioning/trellis2",
+ inputs=[
+ IO.Conditioning.Input("positive"),
+ IO.Conditioning.Input("negative"),
+ IO.Latent.Input("shape_latent"),
+ ],
+ outputs=[
+ IO.Conditioning.Output(display_name="positive"),
+ IO.Conditioning.Output(display_name="negative"),
+ IO.Latent.Output(),
+ ]
+ )
+
+ @classmethod
+ def execute(cls, positive, negative, shape_latent):
+ channels = 32
+ coords = shape_latent["coords"]
+ coord_resolution = shape_latent.get("coord_resolution")
+
+ batch_size, counts, max_tokens = infer_batched_coord_layout(coords)
+
+ shape_slat = shape_latent["samples"]
+ if shape_slat.ndim == 4:
+ shape_slat, _ = flatten_batched_sparse_latent(shape_slat, coords, counts)
+
+ latent = torch.zeros(batch_size, channels, max_tokens, 1)
+ proj_pack = _proj_pack_from_conditioning(positive)
+ model_frame = shape_latent.get("model_frame",
+ "y_up" if proj_pack is not None else "z_up")
+ extras = {
+ "trellis2_generation_mode": "texture_generation",
+ "trellis2_coords": coords,
+ "trellis2_coord_counts": counts,
+ "trellis2_shape_slat": shape_slat,
+ "trellis2_model_frame": model_frame,
+ }
+ if proj_pack is not None and coord_resolution is not None:
+ extras["trellis2_proj_feats"] = compute_stage_proj_feats(
+ proj_pack, "tex_1024", coords=coords, coord_resolution=coord_resolution,
+ )
+
+ positive_out = _conditioning_set_extras(positive, extras)
+ negative_out = _conditioning_set_extras(negative, extras)
+ out_latent = {"samples": latent, "type": "trellis2", "coords": coords, "coord_counts": counts,
+ "model_frame": shape_latent.get("model_frame",
+ "y_up" if proj_pack is not None else "z_up")}
+ if coord_resolution is not None:
+ out_latent["coord_resolution"] = coord_resolution
+ return IO.NodeOutput(positive_out, negative_out, out_latent)
+
+
+class EmptyTrellis2LatentStructure(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="EmptyTrellis2LatentStructure",
+ category="model/latent/trellis",
+ inputs=[
+ IO.Int.Input("batch_size", default=1, min=1, max=4096, tooltip="The number of latent images in the batch."),
+ ],
+ outputs=[
+ IO.Latent.Output(),
+ ]
+ )
+ @classmethod
+ def execute(cls, batch_size):
+ in_channels = 32
+ resolution = 16
+ latent = torch.zeros(batch_size, in_channels, resolution, resolution, resolution)
+ return IO.NodeOutput({"samples": latent, "type": "trellis2"})
+
+def _dinov3_patches_to_2d(tokens, image_size, patch_size=16):
+ h_p = w_p = image_size // patch_size
+ n_patches = h_p * w_p
+ n_reg = tokens.shape[1] - 1 - n_patches
+ if n_reg < 0 or tokens.shape[1] != 1 + n_reg + n_patches:
+ raise ValueError(
+ f"_dinov3_patches_to_2d: got {tokens.shape[1]} tokens, expected "
+ f"1 (CLS) + N_reg + {h_p}*{w_p}={n_patches} patches at image_size={image_size}, "
+ f"patch_size={patch_size}. Inferred N_reg={n_reg} which is invalid."
+ )
+ start = 1 + n_reg
+ patches = tokens[:, start:start + n_patches]
+ return patches.transpose(1, 2).reshape(tokens.shape[0], -1, h_p, w_p).contiguous()
+
+
+def _dino_encode_batch(clip_vision_model, image, out_device, *, want_patches=False):
+ """Encode an already-preprocessed image through DINOv3 at 512 and 1024.
+
+ Expects `image` to be a comfy IMAGE tensor [B, H, W, 3] of squared composites
+ (from ImageCropToMask). Returns batched global tokens; with want_patches also
+ the 2D patch grids and the per-item BCHW composites that the Pixal3D NAF path needs."""
+ image = image[..., :3]
+ batch_size = image.shape[0]
+ comfy.model_management.load_model_gpu(clip_vision_model.patcher)
+
+ cond_512_list, cond_1024_list = [], []
+ patches_512_list, patches_1024_list = [], []
+ composite_list = []
+ for b in range(batch_size):
+ item = image[b].movedim(-1, -3).unsqueeze(0).contiguous().float().clamp(0, 1)
+ c512 = _dinov3_encode(clip_vision_model, item, 512, want_patches=want_patches)
+ c1024 = _dinov3_encode(clip_vision_model, item, 1024, want_patches=want_patches)
+ if want_patches:
+ cond_512_list.append(c512["tokens"].to(out_device))
+ cond_1024_list.append(c1024["tokens"].to(out_device))
+ patches_512_list.append(c512["patches_2d"].to(out_device))
+ patches_1024_list.append(c1024["patches_2d"].to(out_device))
+ composite_list.append(item)
+ else:
+ cond_512_list.append(c512.to(out_device))
+ cond_1024_list.append(c1024.to(out_device))
+
+ out = {
+ "batch_size": batch_size,
+ "global_512": torch.cat(cond_512_list, dim=0),
+ "global_1024": torch.cat(cond_1024_list, dim=0),
+ }
+ if want_patches:
+ out["patches_512"] = torch.cat(patches_512_list, dim=0)
+ out["patches_1024"] = torch.cat(patches_1024_list, dim=0)
+ out["composites"] = composite_list
+ return out
+
+class Pixal3DConditioning(IO.ComfyNode):
+
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="Pixal3DConditioning",
+ category="model/conditioning/trellis2",
+ inputs=[
+ IO.ClipVision.Input("clip_vision_model", tooltip="DINOv3 ViT-L/16 ClipVision."),
+ IO.Image.Input("image", tooltip="Preprocessed image from ImageCropToMask (pad_factor=1.1 for Pixal3D)."),
+ IO.Float.Input(
+ "camera_angle_x", display_name="fov",
+ default=49.13, min=1.0, max=170.0, step=0.01,
+ tooltip="Horizontal FOV in degrees. Wire a MoGeGeometryToFOV "
+ "(axis='horizontal', unit='degrees') for a per-image FoV (matches upstream default).",
+ ),
+ ],
+ outputs=[
+ IO.Conditioning.Output(display_name="positive"),
+ IO.Conditioning.Output(display_name="negative"),
+ ],
+ )
+
+ @classmethod
+ def execute(cls, clip_vision_model, image, camera_angle_x) -> IO.NodeOutput:
+ naf_model = clip_vision_model.naf
+ out_device = comfy.model_management.intermediate_device()
+ compute_device = comfy.model_management.get_torch_device()
+
+ cond = _dino_encode_batch(clip_vision_model, image, out_device, want_patches=True)
+ batch_size = cond["batch_size"]
+ global_512, global_1024 = cond["global_512"], cond["global_1024"]
+ fm_512_dino, fm_1024_dino = cond["patches_512"], cond["patches_1024"]
+ composite_list = cond["composites"]
+
+ # The LR DINO grid AND the NAF HR grid are sampled separately
+ # NAF targets per stage: shape_512=512, shape_1024=512, tex_1024=1024.
+ def _naf_hr(lr_feat, composites, image_size, naf_target):
+ if naf_model is None or naf_target is None:
+ return None
+ comfy.model_management.load_model_gpu(naf_model)
+ inner = naf_model.model
+ model_dtype = next(inner.parameters()).dtype # set at load time (see clip_vision NAF)
+ hrs = []
+ for i, c in enumerate(composites):
+ img_i = comfy.utils.common_upscale(c, image_size, image_size, "lanczos", "disabled")\
+ .to(compute_device).to(model_dtype)
+ lr_i = lr_feat[i:i + 1].to(compute_device).to(model_dtype)
+ output = torch.empty((1, lr_i.shape[1], *naf_target), device=out_device, dtype=model_dtype)
+ hr_i = inner(img_i, lr_i, naf_target, output=output)
+ hrs.append(hr_i)
+ return torch.cat(hrs, dim=0)
+
+ hr_shape_512 = _naf_hr(fm_512_dino, composite_list, 512, (512, 512))
+ hr_shape_1024 = _naf_hr(fm_1024_dino, composite_list, 1024, (512, 512))
+ hr_tex_1024 = _naf_hr(fm_1024_dino, composite_list, 1024, (1024, 1024))
+
+ # distance_from_fov: grid_point (-1, 0, 0) projects to pixel (0, image_resolution-1).
+ # FOV widget is in degrees for UX; trig + downstream projection expect radians.
+ camera_angle_x = math.radians(float(camera_angle_x))
+ distance = 0.5 / math.tan(camera_angle_x / 2.0)
+ cam_angle_t = torch.tensor([camera_angle_x] * batch_size, device=out_device, dtype=torch.float32)
+ dist_t = torch.tensor([distance] * batch_size, device=out_device, dtype=torch.float32)
+ scale_t = torch.ones(batch_size, device=out_device, dtype=torch.float32)
+ T = build_proj_transform_matrix(dist_t, batch_size, device=out_device, dtype=torch.float32)
+
+ proj_pack = {
+ "stages": {
+ "ss": {"feature_map": fm_512_dino, "feature_map_hr": None, "image_resolution": 512},
+ "shape_512": {"feature_map": fm_512_dino, "feature_map_hr": hr_shape_512, "image_resolution": 512},
+ "shape_1024": {"feature_map": fm_1024_dino, "feature_map_hr": hr_shape_1024,"image_resolution": 1024},
+ "tex_1024": {"feature_map": fm_1024_dino, "feature_map_hr": hr_tex_1024, "image_resolution": 1024},
+ },
+ "transform_matrix": T,
+ "camera_angle_x": cam_angle_t,
+ "mesh_scale": scale_t,
+ "distance": dist_t,
+ "patch_size": 16,
+ }
+
+ # global_512 → SS/shape_512 cross-attn; global_1024 → shape_1024/tex_1024.
+ ss_proj_feats = compute_stage_proj_feats(
+ proj_pack, "ss", dense_grid_resolution=16, batch_size=batch_size,
+ device=compute_device,
+ )
+ neg_global = torch.zeros_like(global_512)
+ neg_embeds = torch.zeros_like(global_1024)
+ base_extras = {
+ "embeds": global_1024, "proj_feat_pack": proj_pack,
+ "trellis2_proj_feats": ss_proj_feats,
+ }
+ neg_extras = {
+ "embeds": neg_embeds, "proj_feat_pack": proj_pack,
+ "trellis2_proj_feats": ss_proj_feats,
+ }
+ positive = [[global_512, base_extras]]
+ negative = [[neg_global, neg_extras]]
+ return IO.NodeOutput(positive, negative)
+
+
+class Trellis2Extension(ComfyExtension):
+ @override
+ async def get_node_list(self) -> list[type[IO.ComfyNode]]:
+ return [
+ Trellis2Conditioning,
+ Pixal3DConditioning,
+ Trellis2ShapeStage,
+ EmptyTrellis2LatentStructure,
+ Trellis2TextureStage,
+ VaeDecodeTextureTrellis,
+ VaeDecodeShapeTrellis,
+ VaeDecodeStructureTrellis2,
+ Trellis2UpsampleStage,
+ ]
+
+
+async def comfy_entrypoint() -> Trellis2Extension:
+ return Trellis2Extension()
diff --git a/nodes.py b/nodes.py
index fa3a77949..3366344d5 100644
--- a/nodes.py
+++ b/nodes.py
@@ -2505,6 +2505,8 @@ async def init_builtin_extra_nodes():
"nodes_toolkit.py",
"nodes_replacements.py",
"nodes_nag.py",
+ "nodes_trellis2.py",
+ "nodes_mesh_postprocess.py",
"nodes_sdpose.py",
"nodes_math.py",
"nodes_number_convert.py",
diff --git a/tests-unit/comfy_test/model_detection_test.py b/tests-unit/comfy_test/model_detection_test.py
index b40ea0d4c..94da2fdf6 100644
--- a/tests-unit/comfy_test/model_detection_test.py
+++ b/tests-unit/comfy_test/model_detection_test.py
@@ -289,6 +289,18 @@ class TestModelDetection:
del sd["double_blocks.0.attn.img_attn_q_norm.weight"]
assert detect_unet_config(sd, "") is None
+ def test_pixal3d_projection_detection_ignores_packed_weight_width(self):
+ sd = {
+ "img2shape.t_embedder.mlp.0.weight": torch.empty(8, 8, device="meta"),
+ "img2shape.blocks.0.cross_attn.proj_linear.weight": torch.empty(8, 1024, device="meta"),
+ "structure_model.blocks.0.cross_attn.proj_linear.weight": torch.empty(8, 512, device="meta"),
+ }
+
+ unet_config = detect_unet_config(sd, "")
+
+ assert unet_config["proj_in_channels_shape"] == 2048
+ assert unet_config["proj_in_channels_structure"] == 1024
+
def test_unet_config_and_required_keys_combination_is_unique(self):
"""Each model in the registry must have a unique combination of
``unet_config`` and ``required_keys``. If two models share the same