PixText Region Editor:
PixTextRegionEditor is the region-selection and text-planning stage of a PixText image-text refinement workflow. It lets you open an image, draw rectangular areas around text that needs attention, and specify the text you want those areas to contain. These editing instructions persist in the workflow, making it easier to save your work and return to the same selections later. You can work manually or review suggestions supplied by PixText’s word-detection stage, correcting the suggested areas and text before applying them. The node checks that saved selections belong to the current image and provides an annotated preview so you can inspect your planned changes. It does not repair or generate text itself; instead, it prepares validated instructions for subsequent refinement while preserving the source image.
PixText Region Editor Input Parameters:
image
Required input of type COMBO that selects a source image when no upstream image is connected. Its options consist of the bundled example, represented in the source code by EXAMPLE, followed by the available image files in ComfyUI’s input directory, sorted by filename. The default is the bundled example, which uses the provided Chinese example image; the exact displayed label of that option is not shown in the supplied source. The control supports uploading an image. For file-based images, the node applies EXIF orientation correction and converts the image to RGB before preparing it for editing. If image_in is connected, that upstream image takes priority, and this selection does not determine the working image. Minimum and maximum values do not apply because this is an image-selection control rather than a numeric setting.
region_data
Required STRING input containing the saved region document as JSON. Its default is "`{}`", it supports multiple lines, and dynamic prompt expansion is disabled so the document is treated as literal text. The document records version information, the source image identifier, image dimensions, and the list of regions with their bounding boxes and target text. The supported document version is 1, and the region list can contain from 0 to 256 entries, including disabled entries. A region’s optional enabled field defaults to true; regions marked false are excluded from the editing instructions, while enabled regions retain their listed order. Each enabled region must provide valid bbox and text values accepted by PixText’s text-edit validation, and its box must not extend beyond the image. When detections are connected, the document must also identify the reviewed detection set through a matching detection_id. The default empty object is an initial state, not a valid applied region document: open the editor and apply your selections before refinement. There is no numeric minimum or maximum for the string itself, but the document structure and region-count limit are enforced.
image_in
Optional IMAGE input for using an image from an upstream node instead of the selected file or bundled example. Its execution default is None, meaning no upstream image is supplied; no numeric minimum or maximum is defined. When connected, it becomes the working image, and the node derives its source identifier from a SHA-256 digest of the converted image pixels. This helps associate your saved region selections with the particular image being edited. Run the node once after connecting or changing an upstream image to refresh the editor preview, then review and apply the regions for that image. When using suggestions from Detect Words, connect that node’s matching image here as well as its detections; supplying detections without this image connection causes an error.
detections
Optional input of type PIXTEXT_DETECTIONS that supplies OCR word suggestions from Detect Words. Its execution default is None, and it has no numeric minimum, maximum, or selectable options. When provided, the node makes these suggestions available in the Region Editor and verifies that their source identifier and image dimensions match the connected upstream image. Suggestions are not automatically accepted as final editing instructions: you must review the proposed regions and target text, then use Apply regions so the saved document matches the current detection set. This review step helps prevent accidental refinement based on outdated or uncorrected OCR results. If the image does not match, execution raises an error; if the saved document has not been applied for the current detections, the node displays guidance and blocks the targets needed for refinement.
PixText Region Editor Output Parameters:
image
IMAGE output containing the working source image without region annotations or text refinement. It comes from image_in when connected; otherwise, it comes from the selected file or bundled example. File-based images have their EXIF orientation applied and are converted to RGB before output. Use this output as the original image in the rest of your PixText workflow so that refinement and comparison refer to the same source used to define the regions. When region validation fails in the node’s handled validation path, this image is still returned, allowing you to see the source while correcting the region document.
targets
PIXTEXT_TARGETS output containing the validated instructions for downstream text refinement. Internally, it includes edits, the ordered list of enabled text edits; size, the source image dimensions; and source_digest, a SHA-256 fingerprint of the source pixels. Each edit combines a rectangular area with its intended text. Disabled regions do not appear in this list. The dimensions and fingerprint allow downstream processing to check that the instructions are being used with the correct original image. This output is not an image or a mask. If region parsing fails, saved regions belong to another image, or OCR suggestions have not been reviewed and applied, the node returns an execution blocker here instead of usable targets, preventing refinement from proceeding with invalid instructions.
regions_preview
IMAGE output showing the source image annotated with the validated edit regions. It provides a visual check of where the prepared edits will apply before you continue to refinement; it is not the repaired result. The annotation is generated from the enabled edits, so disabled regions are excluded from the edit list used to create it. Keep this preview separate from the clean image output when wiring the workflow. If the node encounters a handled region-validation error, this output falls back to the unannotated source image rather than providing a valid annotated preview.
PixText Region Editor Usage Tips:
- Begin with the bundled example if you want to explore the editor before uploading your own image. For your own artwork, choose or upload the source image, open the Region Editor, draw the needed rectangles, enter the intended text, and apply the regions before running refinement.
- After connecting or changing
image_in, run the node once to refresh its editor preview. Review and apply your regions again if the image changes; saved coordinates and text instructions must belong to the current source and dimensions. - For an OCR-assisted workflow, connect both the image and detections from the same Detect Words node. Review the suggested rectangles and text, make corrections, and use Apply regions before continuing.
- Treat the text entered for each region as the intended text for that area, not as a general image-generation prompt. Check spelling and characters carefully before applying your regions.
- Keep rectangles within the image boundaries and inspect
regions_previewfor misplaced or overly broad selections. This preview helps you verify the planned editing areas, but it does not show the eventual quality of the refined text. - Disable regions you do not want processed rather than leaving them active. Disabled entries are skipped during target creation, but they still count toward the 256-entry document limit, so remove unnecessary entries if you reach that limit.
- Connect the clean
imageoutput andtargetsto the appropriate downstream refinement inputs. Do not substituteregions_previewfor the original image, because it contains annotations. - When using PixTextCompare, use the original
imagefrom this editor together with the corresponding targets. The comparison stage checks both image dimensions and the original pixel fingerprint. - Prefer the editor’s Apply regions action over manually changing
region_data. If you prepare documents outside the editor, preserve version1, the correct source identifier and dimensions, valid region records, and the current detection identifier when applicable.
PixText Region Editor Common Errors and Solutions:
Upload an image before editing regions
- Explanation: The selected non-example image cannot be found at the expected ComfyUI input location. The file may have been deleted, moved, or referenced by a workflow imported from another installation.
- Solution: Upload the image again or select an available image from the dropdown. Run the node to refresh the preview, then review and apply regions for that image.
Connect the image and detections from the same Detect Words node
- Explanation: Detections were supplied without
image_in, or the detections do not match the connected image’s source identifier or dimensions. The node cannot safely use suggestions associated with a different image. - Solution: Connect both the image and detections from the same Detect Words node. Rerun detection after changing the source image, refresh the editor, and review and apply the new regions.
Expected a PixText region document with version 1
- Explanation: The saved JSON is not a supported region document. For example, the default
"`{}`"has no version information, and a document with a version other than1is rejected. - Solution: Open the Region Editor and apply your regions so it saves a complete document. If you are preparing JSON manually, use a JSON object with version
1and the required image information and region list.
The image changed. Open the region editor and save regions for this image.
- Explanation: The saved document’s source identifier or dimensions do not match the working image. This can happen after choosing another file, changing an upstream image, resizing it, or switching between a file selection and an upstream image connection.
- Solution: Run the node to refresh the current image preview, open the Region Editor, and review or recreate the selections before applying them again. Do not change only the document’s image information to bypass the check without verifying the regions.
The editor supports at most 256 regions
- Explanation: The document’s
regionsfield is not a list, or it contains more than 256 entries. This same message is used for both conditions, and disabled entries still count toward the limit. - Solution: Use the editor to save a valid region list and remove unnecessary entries until there are no more than 256. If editing JSON directly, ensure
regionsis an array rather than an object, string, or null value.
Region N is invalid
- Explanation: Here,
Nis the region’s position in the saved list, starting at 1. That entry is not a valid region object, or itsenabledfield is not a Boolean value. For example, the string"false"is not equivalent to the JSON Booleanfalse. - Solution: Recreate the affected region in the editor. For manually prepared documents, make each entry a JSON object and either omit
enabledor set it totrueorfalsewithout quotation marks.
Region N: validation details
- Explanation: The actual message begins with the region number and then reports the underlying problem while creating its text edit. Possible causes include missing
bboxortextfields, incorrect value types, or bounding-box and text values rejected by PixText’s edit validation. The supplied code does not show every possible underlying validation message. - Solution: Find the numbered entry, check its intended text, and redraw its rectangle in the editor before applying again. If preparing JSON manually, provide both required fields and correct the specific issue described after the region number.
Region N extends beyond the image
- Explanation: An enabled region’s right or bottom boundary exceeds the image width or height. Saved coordinates from a larger image or an incorrectly drawn rectangle can cause this.
- Solution: Adjust the rectangle so it fits inside the current image. If the source was resized or replaced, refresh the preview and review all saved regions before applying them again.
Review OCR suggestions in the Region Editor and Apply regions before refinement.
- Explanation: The saved region document does not contain the identifier of the currently connected detection set. The suggestions may be new or may have changed since you last applied the regions.
- Solution: Open the Region Editor, review the current suggestions and intended text, and use Apply regions. Rerun the workflow after the updated document has been saved.
N words detected. Open Region Editor, review targets and Apply regions.
- Explanation: This guidance appears when detections are available but
region_datais still the default empty object.Nis the number of detected regions. The node has suggestions ready, but no valid applied document for refinement. - Solution: Open the Region Editor, inspect the detected areas, correct the target text and rectangles as needed, and apply the regions. The targets remain blocked until a valid document is saved.
JSON parsing errors, such as “Expecting value” or “Expecting property name enclosed in double quotes”
- Explanation: The contents of
region_dataare not valid JSON. Common causes include single quotation marks, missing commas, trailing commas, or incomplete text pasted into the field. The exact message and character position depend on the malformed document. - Solution: Prefer saving regions through the editor. If editing the document manually, use double-quoted property names and strings, remove trailing commas, and check that all brackets and quotation marks are complete. Apply the corrected document and rerun the node.
