Save 4 hours! We auto-setup your workflow! Free!

Drop your workflow.json — we handle every dependency, custom node, and model. Just open the link and run.

Auto-Setup Workflow Json (Free) Now!
ComfyUI > Nodes > PixText > Refine Text · PixText

ComfyUI Node: Refine Text · PixText

Class Name

PixTextRefine

Category
PixText
Author
ATH-MaaS (Account age: 875days)
Extension
PixText
Latest Updated
2026-10-31
Github Stars
0.03K

How to Install PixText

Install this extension via the ComfyUI Manager by searching for PixText
  • 1. Click the Manager button in the main menu
  • 2. Select Custom Nodes Manager button
  • 3. Enter PixText in the search bar
After installation, click the Restart button to restart ComfyUI. Then, manually refresh your browser to clear the cache and access the updated list of nodes.

Visit ComfyUI Online for ready-to-use ComfyUI environment

  • Free trial available
  • 16GB VRAM to 80GB VRAM GPU machines
  • 400+ preloaded models/nodes
  • Freedom to upload custom models/nodes
  • 200+ ready-to-run workflows
  • 100% private workspace with up to 200GB storage
  • Dedicated Support

Run ComfyUI Online

Refine Text · PixText Description

Refines text in selected image regions using glyph guidance while preserving original resolution.

Refine Text · PixText:

PixTextRefine, displayed as “Refine Text · PixText,” repairs text in selected image regions at the original image resolution. It uses glyph-conditioned local refinement in pixel space, meaning that the intended shapes of written characters guide the repair of targeted areas rather than requiring you to regenerate the whole image. This makes it useful when you want to improve selected lettering while retaining the surrounding composition. Only enabled regions are processed, and larger collections of text targets are automatically divided into processing groups. The node describes automatic grouping for more than 12 targets; the actual group capacity is taken from the loaded model’s configuration. It also provides a preview of the refined image and supports progress reporting and cancellation during sampling.

Refine Text · PixText Input Parameters:

model

A required PIXTEXT_MODEL connection supplying the PixText model used for text refinement, normally provided by PixTextModelLoader. The node loads the associated pipeline when there are enabled regions to process, and the model configuration determines how many targets can be handled in each processing group. Your model choice also affects the appropriate sampling settings: the node recommends 4 steps for MeanFlow and 25 steps for Teacher. This is a connected model object rather than a model-name dropdown or file-path field, so no numerical minimum, maximum, or default is specified.

image

A required IMAGE connection containing the image whose text you want to refine. The node uses this image at its original dimensions and checks that it matches the image used to prepare the target regions. Both the dimensions and the image’s pixel-content digest must match; using a resized, recolored, or otherwise modified version after preparing the regions can cause validation to fail. For a reliable workflow, connect the image supplied by the same PixTextRegionEditor that supplies the targets. There is no numerical range or default for this connection.

targets

A required PIXTEXT_TARGETS connection containing the prepared text edits and the information needed to associate them with the correct image. This data includes the edits, the source image dimensions, and a digest identifying the source image’s pixel content. PixTextRegionEditor prepares this information from the regions you review and apply, allowing refinement to operate on the intended text areas. If the edit list is empty, the node returns the original image, an all-zero footprint mask, and metadata reporting that there are no enabled regions, without loading the refinement pipeline. There is no numerical minimum, maximum, or default for this connection; larger edit lists are automatically grouped according to the model’s configured capacity.

seed

A required INT parameter controlling the random sampling used during refinement. Keeping the seed fixed helps you compare changes to other settings without deliberately changing the random starting conditions; changing it lets you explore alternative refinements of the same text regions. Identical results across different hardware or software environments are not guaranteed by this node. The default is 42, the minimum is 0, and the maximum is 9223372036854775807. The interface enables a control-after-generate option, so check its setting if you want the seed to remain fixed between runs.

steps

A required INT parameter specifying the actual number of sampling steps used for refinement. The default is 4, the minimum is 1, and the maximum is 100. This is an advanced setting, and its tooltip recommends 4 steps for MeanFlow and 25 steps for Teacher. Additional steps increase the sampling work for each processing group, so larger values can increase processing time, especially when many regions require multiple groups. More steps are not a guaranteed improvement; begin with the recommendation for your model and compare results before increasing the value.

guidance

A required FLOAT parameter passed to the refinement pipeline as its guidance scale. It adjusts the guidance strength used during sampling, allowing you to compare how different strengths affect the refined lettering and its appearance within the image. The provided code does not define the underlying guidance formula, so a larger value should not be treated as a guaranteed improvement in accuracy or visual quality. The default is 3.3, the minimum is 0, the maximum is 20, and the interface increment is 0.1. This is an advanced setting; start at the default and make small changes while keeping the seed and other settings fixed.

Refine Text · PixText Output Parameters:

image

An IMAGE containing the refined result at the source image’s dimensions. When enabled edits are present, this is the image returned by the PixText refinement pipeline, converted into ComfyUI’s image format; the node also displays a preview of it. You can connect it to an image-saving node or continue processing it elsewhere in your workflow. If no regions are enabled, the node returns the original image unchanged.

edit_footprint

A MASK marking the rectangular crop areas used during refinement. The node creates a mask at the original image resolution, with a value of 1 inside the recorded processing crops and 0 elsewhere. Crop coordinates are mapped from the pipeline’s reference dimensions back to the source image dimensions, with boundaries rounded outward and the right and bottom edges limited to the image size. This output helps you understand the spatial extent of the refinement process, but it is not a character-shaped selection or a measurement of which individual pixels actually changed; processing crops may include surrounding background. If there are no enabled edits, the mask is entirely zero.

metadata

A STRING containing JSON-formatted information returned by the refinement pipeline. This can be saved or inspected to understand the processing result; the node explicitly uses its geometry information, including reference dimensions and crop rectangles, to construct the footprint mask. Other fields depend on what the pipeline returns and are not fully specified in the supplied node code. Non-ASCII characters, such as Chinese text, are preserved directly in the JSON string rather than being converted to Unicode escape sequences. If no regions are enabled, this output contains a status field with the value no_enabled_regions.

Refine Text · PixText Usage Tips:

  • Connect both the image and targets from the same PixTextRegionEditor. If you resize, crop, or otherwise change the image, prepare and apply the regions again for that changed image.
  • Review the text and region boundaries in PixTextRegionEditor before applying them. When using OCR suggestions, apply the reviewed regions before attempting refinement.
  • Start with 4 steps for a MeanFlow model or 25 steps for a Teacher model, as recommended by the node. Avoid assuming that the default of 4 is appropriate for every loaded model.
  • Keep the seed fixed while testing steps or guidance, and change one setting at a time. Check the seed’s control-after-generate setting so it does not change unexpectedly during comparisons.
  • Begin with guidance at 3.3 and adjust it in small increments when comparing results. Judge both the lettering and its fit with the surrounding image rather than assuming stronger guidance is always better.
  • Disable regions you do not need to repair. More enabled targets can require additional processing groups, and the sampling workload grows with both the number of groups and the steps setting.
  • Use edit_footprint to inspect the processing coverage, not as a precise text outline or pixel-difference map. Compare the original and refined images to assess actual visual changes.
  • Save the resulting image in a lossless format such as PNG when preserving image detail is important. Lossy formats such as JPEG can introduce additional changes unrelated to the refinement.

Refine Text · PixText Common Errors and Solutions:

Image and target regions have different dimensions

  • Explanation: The image width or height does not match the dimensions recorded in targets. This commonly occurs when regions were prepared before the image was resized or cropped.
  • Solution: Connect the matching image and targets from the same PixTextRegionEditor. If you need a different image size, perform the resizing first, then prepare and apply the regions again.

Connect the image and targets from the same PixText Region Editor

  • Explanation: The dimensions match, but the image’s pixel content does not match the source recorded in targets. Even a same-sized image can fail this check if it has been recolored, edited, or replaced.
  • Solution: Use the image output associated with the same PixTextRegionEditor as the targets output. Move any image-changing operations before the editor and apply the regions again.

Review OCR suggestions in the Region Editor and Apply regions before refinement.

  • Explanation: This message originates in PixTextRegionEditor when the applied region data does not correspond to the current OCR detections. The editor blocks downstream refinement until the suggestions have been reviewed and applied.
  • Solution: Open the Region Editor, review the detected text and region boundaries, make any necessary corrections, and select Apply regions before running the workflow again.

Words detected; open Region Editor, review targets and Apply regions

  • Explanation: PixTextRegionEditor can display a message beginning with the number of detected words when OCR suggestions are available but no regions have been applied. This is an upstream preparation issue rather than a refinement failure.
  • Solution: Open the Region Editor, select and review the text regions you want to repair, then apply them so valid targets can reach PixTextRefine.

No visible changes; metadata status is no_enabled_regions

  • Explanation: This is a normal no-operation result, not an exception. The target edit list is empty, so the node returns the original image and an all-zero footprint mask without running the refinement model.
  • Solution: Enable at least one intended region in PixTextRegionEditor, confirm its text, apply the regions, and run the workflow again.

Missing target data fields: size, source_digest, or edits

  • Explanation: The node accesses these fields directly. An incomplete or manually constructed targets object can therefore produce a missing-key error instead of reaching refinement.
  • Solution: Supply targets through PixTextRegionEditor rather than a plain text or generic JSON connection. If a custom integration creates targets, ensure it follows the editor’s data structure and correctly identifies the source image.

Model loading or refinement pipeline failure

  • Explanation: The node loads the model when enabled edits are present. Loading or sampling errors can propagate from the pipeline, although their exact messages are not shown in the supplied code.
  • Solution: Verify that PixTextModelLoader supplies a valid model and that its required files and dependencies are available. Inspect the ComfyUI console for the underlying error before changing refinement settings.

Processing interrupted before a result is returned

  • Explanation: The node checks for cancellation during sampling and stops if processing has been interrupted. This is expected when you cancel an active run.
  • Solution: Run the workflow again when you are ready. If a large task is taking too long, enable fewer regions or use the recommended step count for your model rather than an unnecessarily high value.

Refine Text · PixText Related Nodes

Go back to the extension to check out more related nodes.
PixText
RunComfy
Copyright 2025 RunComfy. All Rights Reserved.

RunComfy is the premier ComfyUI platform, offering ComfyUI online environment and services, along with ComfyUI workflows featuring stunning visuals. RunComfy also provides AI Models, enabling artists to harness the latest AI tools to create incredible art.

Refine Text · PixText