PixText: Efficient Scene-Text Refinement via Pixel-Space Grouped Image Generation

English | 简体中文

PixText fixes words and characters in images. Give it an image, boxes around the text you want to change, and the target text. It refines the selected regions together in pixel space, using the surrounding image as context. Pixels outside the actual edit areas stay unchanged.

Model	Default sampling	Glyph guidance
PixText-Teacher	25-step Euler	3.3
PixText-MeanFlow	4-step interval Euler	3.3

Start with MeanFlow. Each model package includes weights, configuration, fonts and SHA-256 checksums. MeanFlow runs without an additional text encoder, OCR model, VAE or teacher.

Example

The two examples in examples/ include the input images and target text. Cyan boxes mark the edits. Click an image to view it full size.

Input	MeanFlow · 4 steps	Teacher · 25 steps

#	Input	MeanFlow · 4 steps	Teacher · 25 steps	#	Input	MeanFlow · 4 steps	Teacher · 25 steps
1 喜				8 给
2 发				9 解
3 甜				10 馋
4 初				11 满
5 恋				12 满
6 鞭				13 畜
7 炮

The English example in examples/english_case repairs four damaged words in a printed caption, including a misspelled name.

Input	MeanFlow · 4 steps	Teacher · 25 steps

Word	Input	MeanFlow · 4 steps	Teacher · 25 steps
Nayeen → Nayeon
Nicola
crossbody
fashionable

To run either example, install PixText and place the complete MeanFlow model package in models/PixText-MeanFlow (see Model packages). Then run:

python examples/run_pipeline.py                  # pipeline_case
python examples/run_pipeline.py --case english   # english_case

The script saves the result to outputs/<case>/meanflow.png and writes reproduction metadata to a JSON file beside it. For Teacher, prepare models/PixText-Teacher and add --variant teacher. Use --model PATH if your model package is elsewhere, or --output-dir PATH to change where results are saved. Both examples use seed 42.

Full-size images: pipeline input, MeanFlow, Teacher; caption input, MeanFlow, Teacher. To regenerate the annotated SVG and PNG images, run python examples/annotate_pipeline.py --case <pipeline|english>.

ComfyUI

Draw boxes around the text to fix, enter the correct words, and view each repair in ComfyUI.

Install nodes

1. Clone the nodes and install their dependencies in ComfyUI's Python environment:

   cd ComfyUI/custom_nodes
   git clone https://github.com/ATH-MaaS/PixText.git
   python -m pip install -r PixText/requirements.txt

2. Restart ComfyUI and refresh your browser. Open Templates → PixText, or drag one of the workflow files below onto the canvas. If its weights are missing, ComfyUI shows the model and download link. Configuration and fonts come with the nodes. Refinement requires an NVIDIA CUDA GPU.

3. Use Download in the missing-model dialog. Desktop handles the download; in a browser or Portable installation, save the file as ComfyUI/models/diffusion_models/PixText-MeanFlow.safetensors or ComfyUI/models/diffusion_models/PixText-Teacher.safetensors. When connected to a remote server, place it on that server. Refresh the model list after saving. Existing complete model packages in ComfyUI/models/pixtext/ or ComfyUI/models/ also work.

Chinese · Draw and refine

Download workflow · MeanFlow · Teacher variant

1. Choose a model in Load PixText Model. The example comes with an image and 13 text regions. MeanFlow defaults to 4 steps; Teacher defaults to 25.
2. Click Open Region Editor to draw or adjust the boxes and enter the target text. Click Apply regions when you are done.
3. Click Run, then check each repair in Compare Regions. Click Open comparison for the full gallery. Saving the workflow keeps your boxes and target text.

English · Detect, adjust and refine

Download workflow · Auto Detect

Install the OCR dependencies once in ComfyUI's Python environment:

cd ComfyUI/custom_nodes/PixText
python -m pip install -r requirements-ocr.txt

Restart ComfyUI, then open the English workflow:

1. Follow the OCR model downloads note on the canvas to download the three OCR files and save them in the listed folders. Then click Run to detect word boxes and read their text. The same links and a local checksum command are in OCR setup.
2. Open Region Editor and adjust the boxes and target words. The example targets are Nayeon, Nicola, crossbody and fashionable. Enable the regions you want to repair, then click Apply regions.
3. Click Run again to repair the selected words and compare the results. To try another image, upload it in Detect Words.

Installation

PixText requires Python 3.11 or newer and a CUDA GPU. pyproject.toml lists the dependencies, including PyTorch 2.8.0, torchvision 0.23.0 and Pillow 11.3.0 or newer. Install the PyTorch and torchvision builds for your CUDA environment, then install PixText:

pip install -e .

PixText uses Pillow with RAQM to lay out target text and render the glyph images supplied to the model. The system also needs HarfBuzz (libharfbuzz0 on Debian/Ubuntu). Fonts are bundled with the ComfyUI nodes and Python model packages; you do not need to install them as system fonts.

Model packages

Download a complete model package from Hugging Face. For the Python examples, use this directory layout:

models/
  PixText-Teacher/
  PixText-MeanFlow/
    model.safetensors
    config.json
    inference_config.json
    manifest.json
    README.md
    fonts/
      AlibabaPuHuiTi-3-55-Regular.ttf
      GoNotoCJKCore-v7.0.ttf

Teacher uses the same layout. model_index.json lists model identifiers and weight checksums. When from_pretrained loads a local package, it checks the weights, configuration, fonts and other files listed in the manifest.

Python

from pixtext import PixTextPipeline, TextEdit

pipeline = PixTextPipeline.from_pretrained("models/PixText-MeanFlow")
result = pipeline.edit(
    "input.png",
    edits=[TextEdit(bbox=(120, 80, 160, 125), text="鹿")],
    seed=42,
)
result.image.save("output.png")

For Teacher, use models/PixText-Teacher. You can load both models in one process. Each result contains an image and metadata with the model identity, seed, sample identity, sampling settings and crop geometry.

Command line

Create edits.json:

[{"bbox": [120, 80, 160, 125], "text": "鹿"}]

pixtext --model models/PixText-MeanFlow \
  --image input.png --edits edits.json --output output.png --seed 42

The command saves a PNG and a JSON metadata file with the same base name. You can also call it with python -m pixtext. Set --steps and --guidance-scale to override the model package defaults.

Batch editing

results = pipeline.edit_batch(
    ["first.png", "second.png"],
    [
        [TextEdit((120, 80, 160, 125), "鹿")],
        [TextEdit((20, 30, 100, 70), "PixText")],
    ],
    seeds=[42, 43],
    sample_ids=["first", "second"],
)

Each image uses its own noise and blur streams.

Inputs and pixel preservation

• Pass a Pillow image or a local image path. PixText uses EXIF orientation to turn it upright and converts it to RGB. Box coordinates refer to this upright image.
• Specify boxes in original-image pixels as (x0, y0, x1, y1), using half-open intervals.
• Each target can be one character or a line of text.
• Crops align to 16-pixel patches, so the actual edit area may extend beyond the box. Pixels outside that area remain identical to the original RGB image.
• Images can have arbitrary dimensions.
• Targets run in input order, with up to 12 per pass.
• For each target, the renderer uses the first bundled font that covers the whole string: PuHuiTi, then Go Noto.

Glyph guidance combines predictions with and without glyphs on the open interval (0.1, 1.0). With the default guidance setting, four MeanFlow updates take seven model forwards.

Development

pip install -e '.[dev]'
ruff check src tests scripts
ruff format --check src tests scripts
mypy
pytest
python3 scripts/check_secrets.py --tracked

GPU tests need CUDA and local model packages. Set PIXTEXT_TEST_MODELS if your packages are in another directory.

Citation

If you use PixText in your research, please cite:

@misc{liu2026efficientscenetextrefinementpixelspace,
  title={Efficient Scene-Text Refinement via Pixel-Space Grouped Image Generation},
  author={Yaoli Liu and Guo-Hua Wang and Yiyang Chen and Qing-Guo Chen and Zhao Xu and Weihua Luo and Yao-Xiang Ding},
  year={2026},
  eprint={2610.18284},
  archivePrefix={arXiv},
  primaryClass={cs.CV},
  url={https://arxiv.org/abs/2610.18284},
}

License

PixText is released under the Apache License 2.0. See LICENSE.