Anima Ref Latent:
AnimaRefLatent prepares a reference image for use with the Anima Ref Adapter, helping you guide image generation with visual reference material. It resizes the image proportionally and centers it on a padded canvas, preserving the complete composition without stretching or cropping. It then uses a VAE, the component that converts pictures into the compressed representation used by the generation model, to prepare reference information at both full and half resolution. The separate half-resolution encoding supports samplers with a low-resolution stage, such as SPEED, without relying on shrinking an already encoded reference, which the source code identifies as unsuitable for the adapter. The node also prepares a blank generation canvas at the selected dimensions and makes the processed reference available for inspection. It is a preparation step rather than a generator: the adapter and sampling workflow determine how the reference influences your final image.
Anima Ref Latent Input Parameters:
image
A required IMAGE containing the reference picture you want to prepare. Only the first image is processed if you supply a batch; additional images are ignored. The node clamps pixel values to the standard 0–1 interval and converts that first image to an 8-bit image before resizing it. It preserves the original proportions, fits the entire picture within the selected canvas dimensions, and adds centered padding wherever necessary. This helps retain the complete reference rather than cutting off its edges, although a large difference between the source and canvas proportions can leave substantial padding. No numeric default, minimum, maximum, or selectable options are declared for this input.
vae
A required VAE used to convert the prepared reference into latent data, a compressed numerical representation that the model can work with. The same VAE performs two separate encodings: one at the selected canvas size and another at half that width and height. Use the VAE expected by your Anima model and adapter workflow, because an incompatible VAE can produce an unusable latent format even if encoding completes. The source specifically notes that the Wan VAE treats a batch as video frames, which is why this node encodes only one reference image at a time. No default, numeric range, or selectable options are declared for this input.
width
A required INT setting the prepared reference canvas width and the blank generation canvas width in pixels. The default is 896, the minimum is 256, the maximum is 2048, and the adjustment step is 16. The node scales the source proportionally to fit within this width and the selected height, adding padding rather than distorting the image. It also encodes a second reference at half this width and allocates the blank latent with a spatial width of width // 8. Larger widths increase the amount of image data processed and generally increase memory requirements. Keep this setting aligned with the width used by your generation workflow so the adapter can use a reference encoded at the intended resolution.
height
A required INT setting the prepared reference canvas height and the blank generation canvas height in pixels. The default is 1152, the minimum is 256, the maximum is 2048, and the adjustment step is 16. Together with width, it determines the canvas proportions and whether the fitted image receives padding along its sides or above and below it. The second reference encoding uses half this height, while the blank latent has a spatial height of height // 8. Increasing the height generally increases processing and memory demands. Choose dimensions that suit your intended composition and match your sampling workflow.
fill
A required INT controlling the grayscale color of the letterbox padding. The default is 255, the minimum is 0, and the maximum is 255; no explicit adjustment step is declared. A value of 0 creates black padding, 255 creates white padding, and intermediate values create shades of gray, such as 128 for approximately mid-gray. The same value is applied to the red, green, and blue channels and is used for both the full-resolution and half-resolution reference preparations. Padding becomes part of the picture encoded by the VAE, so its appearance can affect the reference information supplied to the adapter. This setting does not recolor the source picture and has no visible effect when the resized picture completely fills the canvas.
Anima Ref Latent Output Parameters:
ref_latent
A LATENT containing the encoded reference information for the Anima Ref Adapter. It includes the full-resolution encoding under samples and a separately encoded half-resolution reference under samples_half. These are two preparations of the same source picture, not two different references or two generated images. The half-resolution version supports workflows with a half-resolution sampling stage, such as SPEED, while avoiding the fidelity problem described in the source comments for shrinking an already encoded latent. Connect this output to the appropriate reference input of a compatible Anima Ref Adapter node. Nodes that only read the usual samples entry may ignore the additional half-resolution encoding.
empty_latent
A LATENT containing a zero-filled starting canvas for generation at the selected dimensions. Its samples tensor has the shape [1, 16, height // 8, width // 8], meaning one image, 16 latent channels, and spatial dimensions reduced by a factor of eight. This canvas contains no encoded reference picture and is not itself random noise; it provides the initial latent structure for a compatible sampling workflow, which handles noise according to its own settings. Using it helps keep the generation dimensions consistent with the prepared reference. Its batch size is fixed at one, and its format must match the model used downstream.
ref_image
An IMAGE showing the full-resolution reference exactly as prepared for encoding: proportionally resized, centered, and padded using the chosen fill value. It has the selected width and height, contains one RGB image, and uses floating-point pixel values in the 0–1 range. You can connect it to an image preview or saving node to check framing, padding, and the visible size of the reference before sampling. It is the processed reference picture, not a generated result, and it does not display the separate half-resolution preparation.
Anima Ref Latent Usage Tips:
- Match width and height to your intended generation dimensions, and use empty_latent as the sampling canvas when appropriate. This keeps the reference preparation and generation canvas aligned.
- Use dimensions in multiples of 16, following the controls’ adjustment step. This keeps both the full-resolution canvas and its half-resolution counterpart aligned to the node’s eight-pixel latent reduction.
- Preview ref_image before running a long sampling job. If the subject appears too small because of extensive padding, choose canvas proportions closer to the source picture or crop the source intentionally before sending it into this node.
- Start with fill set to 255 for white padding, use 0 for black, or try 128 for mid-gray. Choose a value that suits your reference background, and compare results because the padding is included in the encoded reference.
- Connect ref_latent to the compatible adapter’s ref_latent input for a single reference or a character reference. For a two-reference adapter, use a separate preparation for style_latent if you want a different style image, or connect the same prepared latent to both inputs when taking character and style from the same picture.
- Preserve the complete ref_latent output when using a compatible multi-stage sampler such as SPEED. The extra samples_half entry provides a separately encoded low-resolution reference rather than a resized full-resolution latent.
- Supply a single image deliberately. Passing an image batch does not prepare multiple references, because this node selects only its first image.
- If memory is limited, reduce width and height together while preserving the desired proportions. The node performs two VAE encodings, so reference preparation has a greater workload than a single encoding.
Anima Ref Latent Common Errors and Solutions:
Required input is missing
- Explanation: ComfyUI cannot execute the node if a required input is unavailable. Exact validation wording varies, but it may identify a missing image or vae connection.
- Solution: Connect a valid IMAGE and the VAE required by your model, and ensure width, height, and fill have valid values.
Value outside the allowed range
- Explanation: Workflow validation may reject width or height outside 256–2048, or fill outside 0–255. Exact wording depends on your ComfyUI version.
- Solution: Set width and height within 256–2048, preferably in multiples of 16, and use an integer from 0 to 255 for fill.
CUDA out of memory
- Explanation: VAE encoding or a later sampling step may exceed available GPU memory. Large canvas dimensions increase memory demand, and this node prepares both full-resolution and half-resolution encodings.
- Solution: Lower width and height, close other GPU-heavy applications, and use compatible memory-saving or tiled VAE options if your setup provides them. If the failure occurs during sampling, also review the sampler’s resolution and memory requirements.
Latent channel or tensor shape mismatch
- Explanation: Errors mentioning channel counts, incompatible tensor sizes, or shape mismatches can occur when the selected VAE or downstream model expects a different latent format. The exact message depends on where the mismatch occurs; this node always creates empty_latent with 16 channels.
- Solution: Use a VAE, Anima model, adapter, and sampler that are intended to work together. Do not assume that a LATENT connection guarantees compatibility, and verify that the sampling dimensions match the prepared reference.
[Anima Ref Adapter] no reference encoded at latent size …; resizing the … one (lower fidelity)
- Explanation: This is a warning from the adapter’s reference-selection code, not an exception raised by AnimaRefLatent. It means the current target size matches neither available reference encoding, so the adapter resizes the closest one in latent space with potentially lower fidelity.
- Solution: Match your generation dimensions to this node’s width and height. For half-resolution stages, pass the complete ref_latent output without removing samples_half. Other intermediate resolutions may still require fallback resizing.
IndexError: index 0 is out of bounds
- Explanation: A message of this form may occur if the incoming IMAGE batch is empty, because the node directly selects its first image.
- Solution: Check that your image-loading or preprocessing node produces at least one valid image. Preview the upstream image and reconnect it before trying again.
Cannot handle this data type
- Explanation: A PIL image-conversion error of this form may occur if the incoming image has an unsupported channel layout or data shape. Standard ComfyUI IMAGE data is expected; unusual custom-node outputs may not convert correctly.
- Solution: Convert the source to a standard RGB image using a suitable image conversion node, or reload a conventional RGB image through your image loader.
Only the first reference image is processed
- Explanation: This is expected behavior rather than an error message. The node explicitly selects image[0], so the rest of an incoming image batch does not contribute to the reference.
- Solution: Select the desired image before this node. To prepare separate character and style references, use separate AnimaRefLatent nodes and connect their results to the corresponding adapter inputs.
The reference has large borders or the subject looks too small
- Explanation: This is usually a result of letterboxing rather than a failure. When the source picture and selected canvas have different proportions, the node preserves the complete picture and fills the unused area with padding.
- Solution: Inspect ref_image, choose width and height with proportions closer to your source, or crop the source beforehand if losing some outer content is acceptable. Adjust fill if the padding color is visually unsuitable.
