PixText: repair one word and check what else changed

1. Prepare a compatible environment

Use a fresh folder on a Linux machine with an NVIDIA GPU. The commands select PyTorch’s CUDA 12.8 wheels. They assume Python 3.11 and Git are installed and your driver supports that build. This is an installation recipe checked against the source declarations; it has not been executed in this review.

git clone https://github.com/ATH-MaaS/PixText.git
cd PixText
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install torch==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu128
python -m pip install -e .
python -m pip install huggingface_hub
git rev-parse HEAD > code-revision.txt
python -m pip freeze > environment.txt

On Debian or Ubuntu, install the system text-shaping library with the command below. RAQM is Pillow’s text-layout support; HarfBuzz supplies part of that support. These dependencies let the renderer turn the target string into glyphs, the visible shapes of its letters.

sudo apt-get install libharfbuzz0
python - <<'PY'
import torch
from PIL import features
assert torch.cuda.is_available(), 'CUDA is unavailable; fix the GPU environment before continuing.'
assert features.check_feature('raqm'), 'Pillow lacks RAQM; install a Pillow build with text-layout support.'
print('CUDA and RAQM are available.')
PY

Continue only when both assertions pass. A working CUDA check establishes that Python can reach the GPU. It does not establish that the model fits its memory or that an edit succeeds. On a rented machine, check its hourly rate and stop the instance after the experiment; no runtime or cost estimate has been measured here.

2. Download the complete model package

Run this from the PixText repository folder with the virtual environment active. It selects the MeanFlow directory at the model repository revision inspected on October 24. This pins the downloaded files; code-revision.txt separately records the source checkout you installed.

python - <<'PY'
from huggingface_hub import snapshot_download
snapshot_download(
    repo_id='ATH-MaaS/PixText',
    revision='f0630bd03a83a0b3e9012e306359fbb09a8bc491',
    allow_patterns=['models/PixText-MeanFlow/**'],
    local_dir='.',
)
PY

python - <<'PY'
from pathlib import Path
p = Path('models/PixText-MeanFlow')
for name in ['model.safetensors', 'config.json', 'inference_config.json', 'manifest.json', 'README.md', 'fonts/AlibabaPuHuiTi-3-55-Regular.ttf', 'fonts/GoNotoCJKCore-v7.0.ttf']:
    assert (p / name).is_file(), f'Missing model file: {name}'
print('Required package files are present.')
PY

The public download was accessible without a paid inference service. Storage, bandwidth and GPU time still have costs. PixText’s loader checks its manifest when loading the local package; the presence check above only catches incomplete downloads. Keep the package’s license files with any redistributed assets.

3. Create an image with an obvious mistake

Save the following complete script as fixture.py in the repository folder. With no argument, it writes input.png and edits.json. It creates its own image, so no photograph, font download or private document is needed.

The input is 512 pixels wide and 192 pixels tall. The upper-left label says C0FFEE. KEEP sits to its right, and a blue band lies below both words. The requested text box is [28, 28, 220, 80]. Coordinates start at the upper-left; the right and bottom bounds are excluded.

import json
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont, ImageChops

def make_fixture(path='input.png'):
    image = Image.new('RGB', (512, 192), '#f2ead9')
    draw = ImageDraw.Draw(image)
    font = ImageFont.load_default(size=32)
    draw.text((32, 32), 'C0FFEE', fill='#243824', font=font)
    draw.text((300, 32), 'KEEP', fill='#243824', font=font)
    draw.rectangle((16, 140, 495, 175), fill='#276f8b')
    image.save(path)
    Path('edits.json').write_text(json.dumps([
        {'bbox': [28, 28, 220, 80], 'text': 'COFFEE'}
    ], indent=2))

def check_changes(original, edited):
    before, after = Image.open(original).convert('RGB'), Image.open(edited).convert('RGB')
    if before.size != after.size:
        return {'boundary': 'FAIL', 'reason': 'Image dimensions changed.'}
    diff = ImageChops.difference(before, after)
    mask = Image.new('L', before.size, 255)
    ImageDraw.Draw(mask).rectangle((0, 0, 255, 127), fill=0)
    outside = Image.new('RGB', before.size)
    outside.paste(diff, mask=mask)
    return {'boundary': 'PASS' if outside.getbbox() is None else 'FAIL',
            'changedBounds': diff.getbbox(),
            'text': 'MANUAL CHECK: the repaired word must read COFFEE.',
            'meaning': 'Boundary PASS alone does not establish a successful repair.'}

if __name__ == '__main__':
    import sys
    if len(sys.argv) == 1:
        make_fixture()
        print('Created input.png and edits.json.')
    elif len(sys.argv) == 2:
        print(json.dumps(check_changes('input.png', sys.argv[1]), indent=2))
    else:
        raise SystemExit('Usage: python fixture.py [output.png]')

python fixture.py

Expected message: Created input.png and edits.json. Open input.png and confirm the zero is visible. The permitted change area for this exercise is the upper-left 256 × 128 pixels. KEEP and the blue band are outside it.

That area is our acceptance rule. It is deliberately larger than the text box because PixText aligns its working crops to image patches. The rule does not claim that every model-selected crop will fit. If the result exceeds the area, the check should fail and you must inspect the cause.

4. Request one repair

Keep the original files unchanged. Run one edit with a fixed seed, the number controlling the initial random state. Seed 42 makes repeated comparisons easier to track, but does not promise identical output across different software and hardware.

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

The CLI should write output.png and matching JSON metadata. Keep both beside input.png, edits.json, code-revision.txt and environment.txt. The metadata records the model, sampling settings and crop geometry. If no image is produced, treat the run as failed and save the error before changing anything.

Open input.png and output.png side by side at full size. The intended result is COFFEE with an O, readable letters and no visual damage to KEEP or the band. This simple synthetic label tests a narrow case; success would not establish performance on curved, occluded or multilingual text.

5. Check spelling and pixel preservation separately

python fixture.py output.png

A boundary result of PASS means dimensions stayed the same and every pixel outside the approved area matched the original RGB image. changedBounds describes where any changed pixels were found. It will be null for a completely unchanged image.

Now read the repaired word yourself. Accept the result only if it says COFFEE, the checker reports PASS, the image remains 512 × 192 and the reproduction metadata is saved. An unchanged image passes the boundary check but fails the spelling requirement. The checker does not perform optical character recognition or judge typography.

The helper was tested on October 24 using Python 3.9.6 and Pillow 11.3.0: an unchanged image passed the boundary check; a single change inside the allowed area passed; a change outside it failed; and a resized image failed. Those controlled files were test inputs for the checker, not PixText outputs. The inference environment above uses the project’s newer dependency requirements.

When a check fails

A successful exercise ends with a readable correction and a saved check record. Before applying the workflow to a real design, repeat it on a copy with the same dimensions, language and background complexity. Set the permitted edit area from your design requirements, then inspect the result at its final display size. This review does not establish model speed, accuracy, memory use or suitability for production assets.

Guide history

Revisions preserve the original instructions. A source recheck alone does not create a new revision.

Revision 1 · Added an original one-word image-repair exercise, complete setup and a four-case-tested pixel-boundary checker; GPU inference remains unexecuted.