ComfyUI Node: Add H3 Edit Reference

Add H3 Edit Reference:

The AddH3EditReference node is designed to enhance the process of integrating reference images into your AI art projects, specifically within the context of H3 editing workflows. This node allows you to append reference images in a structured manner, facilitating the creation of complex visual narratives or scenes. By utilizing this node, you can specify how each reference image should be processed, whether through semantic or native transport modes, which affects how the image is interpreted and utilized in the generation process. The node is particularly beneficial for artists looking to maintain consistency across multiple frames or scenes, as it supports the chaining of references, ensuring that each image is considered in the correct order. This capability is crucial for projects that require a coherent visual story or for those that need to maintain specific visual elements across different frames.

Add H3 Edit Reference Input Parameters:

image

This parameter represents the reference image(s) that you want to append in batch order. It is crucial for defining the visual content that will be used as a guide in the editing process. The images are appended as the next <Picture N> entries, allowing for a structured and sequential integration of multiple references.

transport

The transport parameter determines the method by which the reference image is processed. It can be set to either semantic or native, with semantic being the default. Semantic transport skips the guide VAE, focusing on the semantic content of the image, while native transport creates a minimax_refs latent, which involves more detailed processing. This choice impacts how the reference image influences the final output.

semantic_resolution

This integer parameter specifies the resolution used when the transport is set to semantic. It defines the equivalent-square Qwen budget, which affects the level of detail captured from the reference image. The default value is 1024, with a minimum of 256 and a maximum defined by MAX_SEMANTIC_RESOLUTION. Adjusting this value can help balance detail and performance.

native_reference_size

This parameter defines the VAE resize policy used when the transport is native. It determines how the reference image is resized to fit the processing requirements. The default mode is NATIVE_SIZE_MATCH, which ensures that the image is resized appropriately for native transport processing.

previous_references

An optional parameter that allows you to connect the previous AddH3EditReference node. This connection helps in appending references in order, maintaining the sequence and ensuring that each reference is considered in the correct context.

reference_image

This optional parameter allows you to specify an additional guide image. You can choose between semantic or native transport for this image, providing flexibility in how it is integrated into the editing process.

quality_profile

This parameter offers a selection of quality profiles that dictate how the node processes the reference images. The default is QUALITY_RECOMMENDED, which matches Studio's short 5-frame context. Other profiles create sequences for specific decoders, such as character-sheet or scene-coverage profiles, each tailored for different project needs.

reference_stack

An optional parameter that allows you to include ordered guides from chained AddH3EditReference nodes. These guides follow the direct reference_image and become the next <Picture N> entries, ensuring a structured and sequential integration of multiple references.

Add H3 Edit Reference Output Parameters:

reference_specs

This output parameter provides a structured list of reference specifications, detailing how each reference image is processed and integrated into the project. It includes information on the image, transport method, semantic resolution, and native reference size, offering a comprehensive overview of the reference setup.

visual_items

The visual_items output contains processed visual data, including resized or transformed images based on the specified transport method. This output is crucial for visualizing how each reference image is utilized in the editing process, providing insights into the final composition.

reference_notes

This output provides textual notes on the reference setup, including details on the number of references, their types, and any specific processing notes. It serves as a useful summary for understanding the configuration and impact of the references on the project.

Add H3 Edit Reference Usage Tips:

• Ensure that your reference images are of high quality and relevant to the scene you are creating, as this will significantly impact the final output.
• Experiment with different transport modes to see how they affect the integration of your reference images. Semantic transport is useful for capturing the essence of an image, while native transport provides more detailed processing.
• Use the quality_profile parameter to match the processing to your project's needs, whether you require short sequences or longer, more detailed ones.

Add H3 Edit Reference Common Errors and Solutions:

"reference_stack is not a valid H3 Edit reference stack."

• Explanation: This error occurs when the reference_stack parameter is not a tuple or list, which is required for processing.
• Solution: Ensure that the reference_stack is provided as a tuple or list, containing valid reference items.

"reference_stack item {stack_index} is invalid."

• Explanation: This error indicates that an item in the reference_stack is not a dictionary, which is necessary for processing.
• Solution: Check each item in the reference_stack to ensure it is a dictionary with the required keys and values.

"reference_stack item {stack_index} has unknown transport: {transport}"

• Explanation: This error occurs when an item in the reference_stack has a transport method that is not recognized.
• Solution: Verify that the transport method for each item in the reference_stack is valid and listed in REFERENCE_TRANSPORTS.

"reference_stack item {stack_index} has unknown native size mode: {size_mode}"

• Explanation: This error indicates that an item in the reference_stack has a native size mode that is not recognized.
• Solution: Ensure that the native size mode for each item in the reference_stack is valid and listed in NATIVE_SIZE_MODES.