Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,24 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+docs/assets/pipeline.png filter=lfs diff=lfs merge=lfs -text
+examples/english_case/input.png filter=lfs diff=lfs merge=lfs -text
+examples/english_case/input_boxed.png filter=lfs diff=lfs merge=lfs -text
+examples/english_case/meanflow_output.png filter=lfs diff=lfs merge=lfs -text
+examples/english_case/meanflow_output_boxed.png filter=lfs diff=lfs merge=lfs -text
+examples/english_case/teacher_output.png filter=lfs diff=lfs merge=lfs -text
+examples/english_case/teacher_output_boxed.png filter=lfs diff=lfs merge=lfs -text
+examples/pipeline_case/input.png filter=lfs diff=lfs merge=lfs -text
+examples/pipeline_case/input_boxed.png filter=lfs diff=lfs merge=lfs -text
+examples/pipeline_case/input_preview.png filter=lfs diff=lfs merge=lfs -text
+examples/pipeline_case/meanflow_output.png filter=lfs diff=lfs merge=lfs -text
+examples/pipeline_case/meanflow_output_boxed.png filter=lfs diff=lfs merge=lfs -text
+examples/pipeline_case/meanflow_output_preview.png filter=lfs diff=lfs merge=lfs -text
+examples/pipeline_case/paper_reference.png filter=lfs diff=lfs merge=lfs -text
+examples/pipeline_case/teacher_output.png filter=lfs diff=lfs merge=lfs -text
+examples/pipeline_case/teacher_output_boxed.png filter=lfs diff=lfs merge=lfs -text
+examples/pipeline_case/teacher_output_preview.png filter=lfs diff=lfs merge=lfs -text
+models/PixText-MeanFlow/fonts/AlibabaPuHuiTi-3-55-Regular.ttf filter=lfs diff=lfs merge=lfs -text
+models/PixText-MeanFlow/fonts/GoNotoCJKCore-v7.0.ttf filter=lfs diff=lfs merge=lfs -text
+models/PixText-Teacher/fonts/AlibabaPuHuiTi-3-55-Regular.ttf filter=lfs diff=lfs merge=lfs -text
+models/PixText-Teacher/fonts/GoNotoCJKCore-v7.0.ttf filter=lfs diff=lfs merge=lfs -text

LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 PixText Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -0,0 +1,177 @@
+<div align="center">
+
+# PixText
+
+[![arXiv](https://img.shields.io/badge/arXiv-2610.18284-b31b1b.svg)](https://arxiv.org/abs/2610.18284)
+[![Code](https://img.shields.io/badge/Code-GitHub-181717.svg?logo=github)](https://github.com/ATH-MaaS/PixText)
+[![License](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
+
+**English** | [简体中文](README.zh-CN.md)
+
+</div>
+
+PixText refines local text in pixel space. Provide an image, the regions to edit, and the target text. The model generates those regions using the image as context and preserves pixels outside the actual edited footprints. Multiple targets are generated jointly.
+
+| Model | Default sampling | Glyph guidance |
+| --- | --- | --- |
+| PixText-Teacher | 25-step Euler | 3.3 |
+| PixText-MeanFlow | 4-step interval Euler | 3.3 |
+
+MeanFlow is the default quick-start choice. Each model package contains its weights, configuration, fonts and SHA-256 checksums. MeanFlow needs no additional text encoder, OCR model, VAE, or teacher.
+
+## Example
+
+Two input images and their targets are bundled in [`examples/`](examples). Cyan boxes mark the edited regions. Click an image to enlarge it.
+
+| Input | MeanFlow · 4 steps | Teacher · 25 steps |
+| --- | --- | --- |
+| [<img src="examples/pipeline_case/input_boxed.png" width="220" alt="Input with edit regions">](examples/pipeline_case/input_boxed.png) | [<img src="examples/pipeline_case/meanflow_output_boxed.png" width="220" alt="MeanFlow output with edit regions">](examples/pipeline_case/meanflow_output_boxed.png) | [<img src="examples/pipeline_case/teacher_output_boxed.png" width="220" alt="Teacher output with edit regions">](examples/pipeline_case/teacher_output_boxed.png) |
+
+Each row pairs two targets; every target shows input, MeanFlow output and Teacher output.
+
+| # | Input | MeanFlow · 4 steps | Teacher · 25 steps | # | Input | MeanFlow · 4 steps | Teacher · 25 steps |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 1&nbsp;喜 | <img src="examples/pipeline_case/details/p01_input.png" width="82" alt="喜 input"> | <img src="examples/pipeline_case/details/p01_meanflow.png" width="82" alt="喜 meanflow"> | <img src="examples/pipeline_case/details/p01_teacher.png" width="82" alt="喜 teacher"> | 8&nbsp;给 | <img src="examples/pipeline_case/details/p08_input.png" width="82" alt="给 input"> | <img src="examples/pipeline_case/details/p08_meanflow.png" width="82" alt="给 meanflow"> | <img src="examples/pipeline_case/details/p08_teacher.png" width="82" alt="给 teacher"> |
+| 2&nbsp;发 | <img src="examples/pipeline_case/details/p02_input.png" width="82" alt="发 input"> | <img src="examples/pipeline_case/details/p02_meanflow.png" width="82" alt="发 meanflow"> | <img src="examples/pipeline_case/details/p02_teacher.png" width="82" alt="发 teacher"> | 9&nbsp;解 | <img src="examples/pipeline_case/details/p09_input.png" width="82" alt="解 input"> | <img src="examples/pipeline_case/details/p09_meanflow.png" width="82" alt="解 meanflow"> | <img src="examples/pipeline_case/details/p09_teacher.png" width="82" alt="解 teacher"> |
+| 3&nbsp;甜 | <img src="examples/pipeline_case/details/p03_input.png" width="82" alt="甜 input"> | <img src="examples/pipeline_case/details/p03_meanflow.png" width="82" alt="甜 meanflow"> | <img src="examples/pipeline_case/details/p03_teacher.png" width="82" alt="甜 teacher"> | 10&nbsp;馋 | <img src="examples/pipeline_case/details/p10_input.png" width="82" alt="馋 input"> | <img src="examples/pipeline_case/details/p10_meanflow.png" width="82" alt="馋 meanflow"> | <img src="examples/pipeline_case/details/p10_teacher.png" width="82" alt="馋 teacher"> |
+| 4&nbsp;初 | <img src="examples/pipeline_case/details/p04_input.png" width="82" alt="初 input"> | <img src="examples/pipeline_case/details/p04_meanflow.png" width="82" alt="初 meanflow"> | <img src="examples/pipeline_case/details/p04_teacher.png" width="82" alt="初 teacher"> | 11&nbsp;满 | <img src="examples/pipeline_case/details/p11_input.png" width="82" alt="满 input"> | <img src="examples/pipeline_case/details/p11_meanflow.png" width="82" alt="满 meanflow"> | <img src="examples/pipeline_case/details/p11_teacher.png" width="82" alt="满 teacher"> |
+| 5&nbsp;恋 | <img src="examples/pipeline_case/details/p05_input.png" width="82" alt="恋 input"> | <img src="examples/pipeline_case/details/p05_meanflow.png" width="82" alt="恋 meanflow"> | <img src="examples/pipeline_case/details/p05_teacher.png" width="82" alt="恋 teacher"> | 12&nbsp;满 | <img src="examples/pipeline_case/details/p12_input.png" width="82" alt="满 input"> | <img src="examples/pipeline_case/details/p12_meanflow.png" width="82" alt="满 meanflow"> | <img src="examples/pipeline_case/details/p12_teacher.png" width="82" alt="满 teacher"> |
+| 6&nbsp;鞭 | <img src="examples/pipeline_case/details/p06_input.png" width="82" alt="鞭 input"> | <img src="examples/pipeline_case/details/p06_meanflow.png" width="82" alt="鞭 meanflow"> | <img src="examples/pipeline_case/details/p06_teacher.png" width="82" alt="鞭 teacher"> | 13&nbsp;畜 | <img src="examples/pipeline_case/details/p13_input.png" width="82" alt="畜 input"> | <img src="examples/pipeline_case/details/p13_meanflow.png" width="82" alt="畜 meanflow"> | <img src="examples/pipeline_case/details/p13_teacher.png" width="82" alt="畜 teacher"> |
+| 7&nbsp;炮 | <img src="examples/pipeline_case/details/p07_input.png" width="82" alt="炮 input"> | <img src="examples/pipeline_case/details/p07_meanflow.png" width="82" alt="炮 meanflow"> | <img src="examples/pipeline_case/details/p07_teacher.png" width="82" alt="炮 teacher"> |  |  |  |  |
+
+**English tagline repair.** [`examples/english_case`](examples/english_case) repairs three damaged spots in a printed tagline: a broken letter plus two words, leaving the surrounding logo untouched.
+
+| Input | MeanFlow · 4 steps | Teacher · 25 steps |
+| --- | --- | --- |
+| [<img src="examples/english_case/input_boxed.png" width="220" alt="Tagline input with edit region">](examples/english_case/input_boxed.png) | [<img src="examples/english_case/meanflow_output_boxed.png" width="220" alt="Tagline MeanFlow output with edit region">](examples/english_case/meanflow_output_boxed.png) | [<img src="examples/english_case/teacher_output_boxed.png" width="220" alt="Tagline Teacher output with edit region">](examples/english_case/teacher_output_boxed.png) |
+
+Each row shows one repaired region: input, MeanFlow output and Teacher output.
+
+| Region | Input | MeanFlow · 4 steps | Teacher · 25 steps |
+| --- | --- | --- | --- |
+| Worldwide | <img src="examples/english_case/details/worldwide_input.png" width="180" alt="Worldwide input"> | <img src="examples/english_case/details/worldwide_meanflow.png" width="180" alt="Worldwide MeanFlow"> | <img src="examples/english_case/details/worldwide_teacher.png" width="180" alt="Worldwide Teacher"> |
+| Excellence | <img src="examples/english_case/details/excellence_input.png" width="180" alt="Excellence input"> | <img src="examples/english_case/details/excellence_meanflow.png" width="180" alt="Excellence MeanFlow"> | <img src="examples/english_case/details/excellence_teacher.png" width="180" alt="Excellence Teacher"> |
+| Quality | <img src="examples/english_case/details/quality_input.png" width="180" alt="Quality input"> | <img src="examples/english_case/details/quality_meanflow.png" width="180" alt="Quality MeanFlow"> | <img src="examples/english_case/details/quality_teacher.png" width="180" alt="Quality Teacher"> |
+
+Both cases use seed 42, and the adjacent JSON files record the reproduction metadata. To reproduce them, run the code from [ATH-MaaS/PixText](https://github.com/ATH-MaaS/PixText) with `--model` pointing at the packages in `models/`.
+
+Full-resolution images: [pipeline input](examples/pipeline_case/input.png), [MeanFlow](examples/pipeline_case/meanflow_output.png), [Teacher](examples/pipeline_case/teacher_output.png); [tagline input](examples/english_case/input.png), [MeanFlow](examples/english_case/meanflow_output.png), [Teacher](examples/english_case/teacher_output.png).
+
+## Method
+
+![PixText pipeline](docs/assets/pipeline.png)
+
+## Installation
+
+The inference code is at [github.com/ATH-MaaS/PixText](https://github.com/ATH-MaaS/PixText). Use Python 3.11 or newer and a CUDA GPU. Install a CUDA build of PyTorch and torchvision appropriate for your machine, then install the package:
+
+```bash
+pip install "git+https://github.com/ATH-MaaS/PixText.git"
+```
+
+Pillow must support RAQM. The system must provide HarfBuzz (`libharfbuzz0` on Debian/Ubuntu). Font files are loaded from the model packages in this directory; no system font installation is required.
+
+## What is in this release
+
+This directory contains both model packages, their fonts, example images and checksums. The inference code lives at [github.com/ATH-MaaS/PixText](https://github.com/ATH-MaaS/PixText).
+
+| Path | Contents |
+| --- | --- |
+| `models/PixText-Teacher/` | 25-step teacher weights, configuration, and bundled fonts. |
+| `models/PixText-MeanFlow/` | 4-step MeanFlow weights, configuration, and bundled fonts. |
+| `examples/` | Input and output images for both cases, with reproduction metadata. |
+| `docs/assets/` | Pipeline figure. |
+| `model_index.json` | Model identifiers and weight checksums. |
+| `manifest.sha256` | SHA-256 checksums for every model file, configuration file, and font. |
+
+Verify the release from its root:
+
+```bash
+sha256sum -c manifest.sha256
+```
+
+The benchmark for this model, TextRefinementBench, ships as a separate dataset package with its own card.
+
+## Model packages
+
+Both packages are included under `models/`, laid out as follows:
+
+```text
+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
+      OFL-GoNoto.txt
+      README.md
+```
+
+Teacher uses the same package layout. [`model_index.json`](model_index.json) lists the model identifiers and weight checksums. `from_pretrained` loads a local directory and checks the files listed in its manifest, including the weights, configuration and fonts. A missing or modified bundled font is reported before weights are loaded. Complete packages can be moved without changing their configuration.
+
+## Python
+
+```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")
+```
+
+Use `models/PixText-Teacher` to load Teacher. Both variants can coexist in one process. Results contain `image` and `metadata`, including model identity, seed, sample identity, sampling settings, and crop geometry.
+
+## Command line
+
+Create `edits.json`:
+
+```json
+[{"bbox": [120, 80, 160, 125], "text": "鹿"}]
+```
+
+```bash
+pixtext --model models/PixText-MeanFlow \
+  --image input.png --edits edits.json --output output.png --seed 42
+```
+
+The CLI saves a PNG and a matching JSON metadata file. `python -m pixtext` provides the same command. `--steps` and `--guidance-scale` override the package defaults.
+
+## Batch editing
+
+```python
+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"],
+)
+```
+
+## Inputs and pixel preservation
+
+- Inputs are Pillow images or local image paths, converted to upright RGB using EXIF orientation. Coordinates refer to that upright image.
+- Boxes use original-image pixel coordinates `(x0, y0, x1, y1)` and half-open intervals. Invalid or out-of-image boxes are rejected.
+- Supply one character or a text line per target.
+- Crops align to 16-pixel patches. Pixels outside those footprints remain identical to the original RGB image.
+- Arbitrary image dimensions are supported.
+- Targets are processed in input order, up to 12 per pass. For overlapping aligned crops, the last target written wins. An empty edit list returns the original RGB image.
+- The renderer selects the first bundled font covering the entire target string, using PuHuiTi then Go Noto. Unsupported text produces a coverage error instead of missing-glyph squares.
+- Editing requires CUDA FlexAttention.
+
+Glyph-present and glyph-absent predictions provide guidance on the open interval `(0.1, 1.0)`. At the default guidance setting, four MeanFlow updates use seven model forwards. Initial execution also includes compilation overhead.
+
+## License
+
+Model weights and documentation are released under the Apache License 2.0; see [LICENSE](LICENSE). The inference code is at [ATH-MaaS/PixText](https://github.com/ATH-MaaS/PixText). Bundled fonts keep their own terms, described in each model package's `fonts/` directory.

README.zh-CN.md

@@ -0,0 +1,177 @@
+<div align="center">
+
+# PixText
+
+[![arXiv](https://img.shields.io/badge/arXiv-2610.18284-b31b1b.svg)](https://arxiv.org/abs/2610.18284)
+[![Code](https://img.shields.io/badge/Code-GitHub-181717.svg?logo=github)](https://github.com/ATH-MaaS/PixText)
+[![License](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
+
+[English](README.md) | **简体中文**
+
+</div>
+
+PixText 在像素空间中修复图像中的局部文字。提供图像、待编辑区域和目标文字后，模型会结合图像上下文生成这些区域，并保持实际编辑范围之外的像素不变。多个目标可以联合生成。
+
+| 模型 | 默认采样方式 | 字形引导强度 |
+| --- | --- | --- |
+| PixText-Teacher | 25 步 Euler | 3.3 |
+| PixText-MeanFlow | 4 步区间 Euler | 3.3 |
+
+快速体验默认使用 MeanFlow。每个模型包包含权重、配置、字体和 SHA-256 校验信息。运行 MeanFlow 不需要额外的文本编码器、OCR 模型、VAE 或 Teacher。
+
+## 示例
+
+两个内置示例的输入与目标均位于 [`examples/`](examples)。青色方框标出编辑区域，点击图片可查看大图。
+
+| 输入 | MeanFlow · 4 步 | Teacher · 25 步 |
+| --- | --- | --- |
+| [<img src="examples/pipeline_case/input_boxed.png" width="220" alt="输入图像及编辑区域">](examples/pipeline_case/input_boxed.png) | [<img src="examples/pipeline_case/meanflow_output_boxed.png" width="220" alt="MeanFlow 输出及编辑区域">](examples/pipeline_case/meanflow_output_boxed.png) | [<img src="examples/pipeline_case/teacher_output_boxed.png" width="220" alt="Teacher 输出及编辑区域">](examples/pipeline_case/teacher_output_boxed.png) |
+
+每行并排两个目标，每个目标展示输入、MeanFlow 输出与 Teacher 输出。
+
+| # | Input | MeanFlow · 4 steps | Teacher · 25 steps | # | Input | MeanFlow · 4 steps | Teacher · 25 steps |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 1&nbsp;喜 | <img src="examples/pipeline_case/details/p01_input.png" width="82" alt="喜 input"> | <img src="examples/pipeline_case/details/p01_meanflow.png" width="82" alt="喜 meanflow"> | <img src="examples/pipeline_case/details/p01_teacher.png" width="82" alt="喜 teacher"> | 8&nbsp;给 | <img src="examples/pipeline_case/details/p08_input.png" width="82" alt="给 input"> | <img src="examples/pipeline_case/details/p08_meanflow.png" width="82" alt="给 meanflow"> | <img src="examples/pipeline_case/details/p08_teacher.png" width="82" alt="给 teacher"> |
+| 2&nbsp;发 | <img src="examples/pipeline_case/details/p02_input.png" width="82" alt="发 input"> | <img src="examples/pipeline_case/details/p02_meanflow.png" width="82" alt="发 meanflow"> | <img src="examples/pipeline_case/details/p02_teacher.png" width="82" alt="发 teacher"> | 9&nbsp;解 | <img src="examples/pipeline_case/details/p09_input.png" width="82" alt="解 input"> | <img src="examples/pipeline_case/details/p09_meanflow.png" width="82" alt="解 meanflow"> | <img src="examples/pipeline_case/details/p09_teacher.png" width="82" alt="解 teacher"> |
+| 3&nbsp;甜 | <img src="examples/pipeline_case/details/p03_input.png" width="82" alt="甜 input"> | <img src="examples/pipeline_case/details/p03_meanflow.png" width="82" alt="甜 meanflow"> | <img src="examples/pipeline_case/details/p03_teacher.png" width="82" alt="甜 teacher"> | 10&nbsp;馋 | <img src="examples/pipeline_case/details/p10_input.png" width="82" alt="馋 input"> | <img src="examples/pipeline_case/details/p10_meanflow.png" width="82" alt="馋 meanflow"> | <img src="examples/pipeline_case/details/p10_teacher.png" width="82" alt="馋 teacher"> |
+| 4&nbsp;初 | <img src="examples/pipeline_case/details/p04_input.png" width="82" alt="初 input"> | <img src="examples/pipeline_case/details/p04_meanflow.png" width="82" alt="初 meanflow"> | <img src="examples/pipeline_case/details/p04_teacher.png" width="82" alt="初 teacher"> | 11&nbsp;满 | <img src="examples/pipeline_case/details/p11_input.png" width="82" alt="满 input"> | <img src="examples/pipeline_case/details/p11_meanflow.png" width="82" alt="满 meanflow"> | <img src="examples/pipeline_case/details/p11_teacher.png" width="82" alt="满 teacher"> |
+| 5&nbsp;恋 | <img src="examples/pipeline_case/details/p05_input.png" width="82" alt="恋 input"> | <img src="examples/pipeline_case/details/p05_meanflow.png" width="82" alt="恋 meanflow"> | <img src="examples/pipeline_case/details/p05_teacher.png" width="82" alt="恋 teacher"> | 12&nbsp;满 | <img src="examples/pipeline_case/details/p12_input.png" width="82" alt="满 input"> | <img src="examples/pipeline_case/details/p12_meanflow.png" width="82" alt="满 meanflow"> | <img src="examples/pipeline_case/details/p12_teacher.png" width="82" alt="满 teacher"> |
+| 6&nbsp;鞭 | <img src="examples/pipeline_case/details/p06_input.png" width="82" alt="鞭 input"> | <img src="examples/pipeline_case/details/p06_meanflow.png" width="82" alt="鞭 meanflow"> | <img src="examples/pipeline_case/details/p06_teacher.png" width="82" alt="鞭 teacher"> | 13&nbsp;畜 | <img src="examples/pipeline_case/details/p13_input.png" width="82" alt="畜 input"> | <img src="examples/pipeline_case/details/p13_meanflow.png" width="82" alt="畜 meanflow"> | <img src="examples/pipeline_case/details/p13_teacher.png" width="82" alt="畜 teacher"> |
+| 7&nbsp;炮 | <img src="examples/pipeline_case/details/p07_input.png" width="82" alt="炮 input"> | <img src="examples/pipeline_case/details/p07_meanflow.png" width="82" alt="炮 meanflow"> | <img src="examples/pipeline_case/details/p07_teacher.png" width="82" alt="炮 teacher"> |  |  |  |  |
+
+**英文标语修复。** [`examples/english_case`](examples/english_case) 修复印刷标语中的三处损坏：一个断裂字母和两个单词，周围 logo 保持不变。
+
+| 输入 | MeanFlow · 4 步 | Teacher · 25 步 |
+| --- | --- | --- |
+| [<img src="examples/english_case/input_boxed.png" width="220" alt="标语输入及编辑区域">](examples/english_case/input_boxed.png) | [<img src="examples/english_case/meanflow_output_boxed.png" width="220" alt="标语 MeanFlow 输出及编辑区域">](examples/english_case/meanflow_output_boxed.png) | [<img src="examples/english_case/teacher_output_boxed.png" width="220" alt="标语 Teacher 输出及编辑区域">](examples/english_case/teacher_output_boxed.png) |
+
+每个修复位置一行：输入、MeanFlow 输出与 Teacher 输出。
+
+| 位置 | 输入 | MeanFlow · 4 步 | Teacher · 25 步 |
+| --- | --- | --- | --- |
+| Worldwide | <img src="examples/english_case/details/worldwide_input.png" width="180" alt="Worldwide input"> | <img src="examples/english_case/details/worldwide_meanflow.png" width="180" alt="Worldwide MeanFlow"> | <img src="examples/english_case/details/worldwide_teacher.png" width="180" alt="Worldwide Teacher"> |
+| Excellence | <img src="examples/english_case/details/excellence_input.png" width="180" alt="Excellence input"> | <img src="examples/english_case/details/excellence_meanflow.png" width="180" alt="Excellence MeanFlow"> | <img src="examples/english_case/details/excellence_teacher.png" width="180" alt="Excellence Teacher"> |
+| Quality | <img src="examples/english_case/details/quality_input.png" width="180" alt="Quality input"> | <img src="examples/english_case/details/quality_meanflow.png" width="180" alt="Quality MeanFlow"> | <img src="examples/english_case/details/quality_teacher.png" width="180" alt="Quality Teacher"> |
+
+两个示例均使用随机种子 42，同目录的 JSON 文件记录复现信息。要复现这些结果，请使用 [ATH-MaaS/PixText](https://github.com/ATH-MaaS/PixText) 的代码，并将 `--model` 指向本目录下的模型包。
+
+原始分辨率图片：[pipeline 输入](examples/pipeline_case/input.png)、[MeanFlow 输出](examples/pipeline_case/meanflow_output.png)、[Teacher 输出](examples/pipeline_case/teacher_output.png)；[标语输入](examples/english_case/input.png)、[MeanFlow 输出](examples/english_case/meanflow_output.png)、[Teacher 输出](examples/english_case/teacher_output.png)。
+
+## 方法
+
+![PixText 流程](docs/assets/pipeline.png)
+
+## 安装
+
+推理代码位于 [github.com/ATH-MaaS/PixText](https://github.com/ATH-MaaS/PixText)。需要 Python 3.11 或更高版本，以及支持 CUDA 的 GPU。先安装适合本机 CUDA 环境的 PyTorch 和 torchvision，再安装该代码包：
+
+```bash
+pip install "git+https://github.com/ATH-MaaS/PixText.git"
+```
+
+Pillow 需要支持 RAQM，系统需要提供 HarfBuzz（Debian/Ubuntu 中为 `libharfbuzz0`）。字体从本目录的模型包加载，无需单独安装到系统。
+
+## 本发布包含什么
+
+本目录包含两个模型包、模型所需字体、示例图片和校验值。推理代码位于 [github.com/ATH-MaaS/PixText](https://github.com/ATH-MaaS/PixText)。
+
+| 路径 | 内容 |
+| --- | --- |
+| `models/PixText-Teacher/` | 25 步 Teacher 权重、配置和内置字体。 |
+| `models/PixText-MeanFlow/` | 4 步 MeanFlow 权重、配置和内置字体。 |
+| `examples/` | 两个示例的输入、输出图片和复现元数据。 |
+| `docs/assets/` | 流程图。 |
+| `model_index.json` | 模型标识与权重校验值。 |
+| `manifest.sha256` | 每个模型文件、配置文件和字体的 SHA-256 校验值。 |
+
+在发布根目录执行校验：
+
+```bash
+sha256sum -c manifest.sha256
+```
+
+本模型使用的评测集 TextRefinementBench 作为独立数据集包发布，自带数据卡。
+
+## 模型包
+
+两个模型包已内置在 `models/` 下，结构如下：
+
+```text
+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
+      OFL-GoNoto.txt
+      README.md
+```
+
+Teacher 使用相同的模型包结构。[`model_index.json`](model_index.json) 列出了模型标识和权重校验值。`from_pretrained` 从本地目录加载模型，检查清单中列出的权重、配置和字体。字体缺失或被修改时，会在加载权重前报错。完整模型包可以移动位置，无需修改配置。
+
+## Python 接口
+
+```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")
+```
+
+加载 Teacher 时，将路径替换为 `models/PixText-Teacher`。两种模型可以在同一进程中使用。返回结果包含 `image` 和 `metadata`，记录模型标识、随机种子、样本标识、采样设置及裁剪区域。
+
+## 命令行
+
+创建 `edits.json`：
+
+```json
+[{"bbox": [120, 80, 160, 125], "text": "鹿"}]
+```
+
+```bash
+pixtext --model models/PixText-MeanFlow \
+  --image input.png --edits edits.json --output output.png --seed 42
+```
+
+命令行会保存 PNG 图片及同名 JSON 元数据文件，也可以使用 `python -m pixtext` 调用。`--steps` 和 `--guidance-scale` 可覆盖模型包的默认设置。
+
+## 批量编辑
+
+```python
+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"],
+)
+```
+
+## 输入与像素保留规则
+
+- 输入可以是 Pillow 图片或本地图片路径，会根据 EXIF 方向转为正向 RGB。编辑坐标以转正后的图片为准。
+- 编辑框使用原图像素坐标 `(x0, y0, x1, y1)`，采用左闭右开的区间。无效或超出图片边界的编辑框会被拒绝。
+- 每个目标可以是一个字符或一行文字。
+- 裁剪区域按 16 像素的 patch 对齐。实际编辑范围之外的像素与原始 RGB 图片完全一致。
+- 支持任意图片尺寸。
+- 按输入顺序处理目标，每轮最多 12 个。对齐后的裁剪区域重叠时，后写入的目标生效。编辑列表为空时返回原始 RGB 图片。
+- 字体按普惠体、Go Noto 的顺序选择，要求单个字体覆盖整条目标文字。不支持的文字会报覆盖错误，不会静默绘制缺字方框。
+- 编辑依赖 CUDA FlexAttention。
+
+字形引导在开区间 `(0.1, 1.0)` 内组合有字形和无字形条件的预测。默认引导设置下，MeanFlow 的 4 次更新需要 7 次模型前向计算。首次执行还包含编译开销。
+
+## 许可
+
+模型权重与文档以 Apache License 2.0 发布，见 [LICENSE](LICENSE)。推理代码位于 [ATH-MaaS/PixText](https://github.com/ATH-MaaS/PixText)。内置字体沿用各自条款，详见各模型包的 `fonts/` 目录。

examples/edits.json

@@ -0,0 +1,3 @@
+[
+  {"bbox": [120, 80, 160, 125], "text": "鹿"}
+]

examples/english_case/edits.json

@@ -0,0 +1,29 @@
+[
+  {
+    "bbox": [
+      382,
+      405,
+      396,
+      431
+    ],
+    "text": "d"
+  },
+  {
+    "bbox": [
+      449,
+      410,
+      574,
+      444
+    ],
+    "text": "Excellence"
+  },
+  {
+    "bbox": [
+      595,
+      396,
+      680,
+      439
+    ],
+    "text": "Quality"
+  }
+]

examples/english_case/meanflow_output.json

@@ -0,0 +1,47 @@
+{
+  "model_id": "PixText-MeanFlow",
+  "variant": "meanflow",
+  "seed": 42,
+  "sample_id": "image",
+  "steps": 4,
+  "guidance_scale": 3.3,
+  "guidance_interval": [
+    0.1,
+    1.0
+  ],
+  "precision": "torch.bfloat16",
+  "geometry": [
+    {
+      "offset": 0,
+      "selected_font_indices": [
+        0,
+        0,
+        0
+      ],
+      "reference_size": [
+        1024,
+        1024
+      ],
+      "crops": [
+        [
+          381,
+          402,
+          16,
+          32
+        ],
+        [
+          448,
+          403,
+          128,
+          48
+        ],
+        [
+          590,
+          394,
+          96,
+          48
+        ]
+      ]
+    }
+  ]
+}

examples/english_case/source.json

@@ -0,0 +1,7 @@
+{
+  "sample_id": "english-tagline",
+  "source_image_sha256": "8e5bea2f9d3590ea34a9ca4e2c1db94c3f9a5f7c52e1267237ab58ce9953c4e2",
+  "target_count": 3,
+  "target_coordinates": "original-image pixel coordinates (x0,y0,x1,y1)",
+  "seed": 42
+}

examples/english_case/teacher_output.json

@@ -0,0 +1,47 @@
+{
+  "model_id": "PixText-Teacher",
+  "variant": "teacher",
+  "seed": 42,
+  "sample_id": "image",
+  "steps": 25,
+  "guidance_scale": 3.3,
+  "guidance_interval": [
+    0.1,
+    1.0
+  ],
+  "precision": "torch.bfloat16",
+  "geometry": [
+    {
+      "offset": 0,
+      "selected_font_indices": [
+        0,
+        0,
+        0
+      ],
+      "reference_size": [
+        1024,
+        1024
+      ],
+      "crops": [
+        [
+          381,
+          402,
+          16,
+          32
+        ],
+        [
+          448,
+          403,
+          128,
+          48
+        ],
+        [
+          590,
+          394,
+          96,
+          48
+        ]
+      ]
+    }
+  ]
+}