Skip to content

Add PiD latent upscale tutorial (EN/ZH/JA/KO) #1069

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
lin-bot23 wants to merge 1 commit into
base: main
Choose a base branch
from
+113 −0
Draft

Add PiD latent upscale tutorial (EN/ZH/JA/KO) #1069

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -395,6 +395,7 @@
"tutorials/utility/remove-background-birefnet",
"tutorials/utility/pose-detection-sdpose",
"tutorials/utility/moge",
"tutorials/utility/pid-latent-upscale/pid-latent-upscale",
"tutorials/utility/depth-anything-3",
{
"group": "Face Detection",
Expand Down
112 changes: 112 additions & 0 deletions tutorials/utility/pid-latent-upscale/pid-latent-upscale.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
---
title: "PiD Latent Upscale ComfyUI Workflow Example"
description: "PiD (Pixel Diffusion Decoder) turns a diffusion latent into a 4x super-resolved image in 4 distilled pixel-space steps. No separate VAE decode needed."
sidebarTitle: "PiD Latent Upscale"
---

import UpdateReminder from '/snippets/tutorials/update-reminder.mdx'

**PiD (Pixel Diffusion Decoder)** turns a diffusion **latent** into a **4x super-resolved image** in 4 distilled pixel-space steps. No separate VAE decode needed. This workflow demonstrates using PiD to upscale a Z-Image-Turbo latent from **1024px to 4096px**.

**Related Links**:
- [Comfy-Org/PixelDiT on Hugging Face](https://huggingface.co/Comfy-Org/PixelDiT)
- [nvidia/PixelDiT-1300M-1024px (official release)](https://huggingface.co/nvidia/PixelDiT-1300M-1024px)

<img src="https://github.com/Comfy-Org/workflow_templates/main/templates/utility_pid_latent_upscale_dit-1.webp" alt="PiD Latent Upscale workflow" />

<UpdateReminder />

<CardGroup cols={1}>
<Card title="Download Workflow" icon="download" href="https://github.com/Comfy-Org/workflow_templates/blob/main/templates/utility_pid_latent_upscale_dit.json">
Download JSON or search "PiD Latent Upscale" in Template Library
</Card>
</CardGroup>

## How PiD works

PiD matches checkpoints by the **VAE / latent space** of the upstream model (the encoder side), not the diffusion model name alone. You need to select the PiD checkpoint that corresponds to the latent space of the model used for initial generation.

This workflow uses **Z-Image-Turbo** (1024px latent to 4096px output) which shares Flux.1's 16-ch VAE.

<Card title="Learn about Subgraph" icon="book-open" href="/interface/features/subgraph">
This workflow uses Subgraph nodes for modular processing. Check out the Subgraph documentation to learn how to customize and extend the workflow.
</Card>

### Available PiD checkpoints

All checkpoints are downloaded from [Comfy-Org/PixelDiT](https://huggingface.co/Comfy-Org/PixelDiT) to `models/diffusion_models/`.

| Checkpoint | Input to Output | Compatible latent (VAE backbone) |
|---|---|---|
| [`pid_flux1_512_to_2048_4step_bf16`](https://huggingface.co/Comfy-Org/PixelDiT/resolve/main/diffusion_models/pid_flux1_512_to_2048_4step_bf16.safetensors) | 512 to 2048 | Flux1-dev 16-ch VAE (Flux.1, Z-Image) |
| [`pid_flux1_1024_to_4096_4step_bf16`](https://huggingface.co/Comfy-Org/PixelDiT/resolve/main/diffusion_models/pid_flux1_1024_to_4096_4step_bf16.safetensors) | 1024 to 4096 | Flux1-dev 16-ch VAE (Flux.1, Z-Image) **(this workflow)** |
| [`pid_flux2_512_to_2048_4step_bf16`](https://huggingface.co/Comfy-Org/PixelDiT/resolve/main/diffusion_models/pid_flux2_512_to_2048_4step_bf16.safetensors) | 512 to 2048 | Flux2-dev 128-ch VAE (Flux.2) |
| [`pid_flux2_1024_to_4096_4step_bf16`](https://huggingface.co/Comfy-Org/PixelDiT/resolve/main/diffusion_models/pid_flux2_1024_to_4096_4step_bf16.safetensors) | 1024 to 4096 | Flux2-dev 128-ch VAE (Flux.2) |
| [`pid_sd3_512_to_2048_4step_bf16`](https://huggingface.co/Comfy-Org/PixelDiT/resolve/main/diffusion_models/pid_sd3_512_to_2048_4step_bf16.safetensors) | 512 to 2048 | SD3 medium 16-ch VAE |
| [`pid_sd3_1024_to_4096_4step_bf16`](https://huggingface.co/Comfy-Org/PixelDiT/resolve/main/diffusion_models/pid_sd3_1024_to_4096_4step_bf16.safetensors) | 1024 to 4096 | SD3 medium 16-ch VAE |

### Subgraph settings

Configure these on the **Latent Upscale Decode (PiD)** subgraph:

| Setting | Value | Description |
|---|---|---|
| `latent_format` | `flux` | `flux` for Flux.1/Flux.2/Z-Image, `sd3` for SD3 (Flux.2 is auto-detected by 128 channels) |
| `degrade_sigma` | `0.0` | How "finished" the input latent is. `0.0` for fully denoised (default), `0.1–0.8` for partially denoised, `1.0` for pure noise |

### Steps to run

1. **Generate a latent**. Use a T2I workflow (e.g., Z-Image-Turbo) to produce a latent image.
2. **Connect to PiD**. Feed the latent into the **Latent Upscale Decode (PiD)** subgraph node.
3. **Select checkpoint**. Choose the PiD checkpoint matching your upstream model's VAE latent space.
4. **Set output size**. Set PiD output size to **4x** the input latent resolution.
5. **Run**. The subgraph decodes and upscales in a single 4-step pass.

## Model downloads

PiD is part of the PixelDiT model family. This workflow also requires the Z-Image-Turbo model for initial generation.

<CardGroup cols={2}>
<Card title="PiD Flux.1 1024 to 4096" icon="download" href="https://huggingface.co/Comfy-Org/PixelDiT/resolve/main/diffusion_models/pid_flux1_1024_to_4096_4step_bf16.safetensors">
pid_flux1_1024_to_4096_4step_bf16.safetensors: PiD checkpoint for Flux.1 / Z-Image latent space
</Card>
<Card title="Z-Image-Turbo diffusion" icon="download" href="https://huggingface.co/Comfy-Org/z_image_turbo/resolve/main/split_files/diffusion_models/z_image_turbo_bf16.safetensors">
z_image_turbo_bf16.safetensors: used for initial generation before PiD upscale
</Card>
</CardGroup>

<CardGroup cols={2}>
<Card title="Text Encoder (Z-Image)" icon="download" href="https://huggingface.co/Comfy-Org/z_image_turbo/resolve/main/split_files/text_encoders/qwen_3_4b.safetensors">
qwen_3_4b.safetensors: text encoder for Z-Image-Turbo
</Card>
<Card title="VAE (Z-Image)" icon="download" href="https://huggingface.co/Comfy-Org/z_image_turbo/resolve/main/split_files/vae/ae.safetensors">
ae.safetensors: VAE for Z-Image-Turbo
</Card>
</CardGroup>

<CardGroup cols={2}>
<Card title="Text Encoder (PiD)" icon="download" href="https://huggingface.co/Comfy-Org/PixelDiT/resolve/main/text_encoders/gemma_2_2b_it_elm_fp8_scaled.safetensors">
gemma_2_2b_it_elm_fp8_scaled.safetensors: text encoder for PiD subgraph CLIPLoader (type: pixeldit)
</Card>
</CardGroup>

> PiD uses a built-in **pixel_space** VAE. No separate VAE file is needed for PiD itself.

### Model storage location

```
📂 ComfyUI/
├── 📂 models/
│ ├── 📂 text_encoders/
│ │ ├── qwen_3_4b.safetensors
│ │ └── gemma_2_2b_it_elm_fp8_scaled.safetensors
│ ├── 📂 diffusion_models/
│ │ ├── pid_flux1_1024_to_4096_4step_bf16.safetensors
│ │ └── z_image_turbo_bf16.safetensors
│ └── 📂 vae/
│ └── ae.safetensors
```

### Sample output

<img src="https://github.com/Comfy-Org/workflow_templates/main/templates/utility_pid_latent_upscale_dit-2.webp" alt="PiD sample output" />
Loading