Skip to content

refactor(pixel-grid): migrate reconstructor to Python - #623

Merged
xyh202131 merged 5 commits into
1024XEngineer:mainfrom
huyanxius:refactor/613-python-pixel-reconstructor
Aug 25, 2026
Merged

refactor(pixel-grid): migrate reconstructor to Python#623
xyh202131 merged 5 commits into
1024XEngineer:mainfrom
huyanxius:refactor/613-python-pixel-reconstructor

Conversation

@huyanxius

@huyanxius huyanxius commented Aug 24, 2026

Copy link
Copy Markdown
Collaborator

将显式网格重建器从 Rust 迁移到服务端 Python。输入仍为 PNG/JPEG bytes + cols + rows + colors,输出仍为 cols × rows 的 RGBA PNG;算法和输出行为不变。

Why

该模块位于 Python 服务端,核心计算是数组距离、聚合投票和图片编解码,可由 NumPy/Pillow 直接完成。保留 Rust 版本需要额外维护 PyO3 接口、跨平台构建产物和 Rust 工具链,本次迁移移除这层跨语言边界。

Algorithm

  1. 从不透明像素中等距采样最多 60,000 个 RGB 点。
  2. 使用固定种子的 xorshift64*、k-means++ 初始化和 15 轮 Lloyd 更新生成结构中心。
  3. 将源像素映射到显式 cols × rows 网格,按三角空间权重投票,确定每个 cell 的结构标签。
  4. 在胜出结构内对原始 RGB 加权平均;alpha 使用 cell 内多数票。

colors 只控制结构聚类数量,不限制最终输出色板。透明像素 RGB 继续沿用现有行为。

Changes

  • 新增 windup_app.server.pixel_perfect.reconstructor,使用 NumPy/Pillow 实现重建入口与错误边界。
  • 保留 32 MiB 编码输入、4 MP 图片和 128 MiB 工作集上限。
  • 同色采样点共享距离计算,距离矩阵按块处理;样本顺序、重复权重和 tie-breaking 不变。
  • 记录上游参考提交 ef376e57e1c272633ca2dbf5f29ec3fcf6596465,保留 MIT 许可证。
  • 增加行为、Rust golden、资源边界测试和固定 benchmark。

Verification

  • uv run pytest -q tests/test_pixel_grid_reconstructor.py --no-cov:14 passed。
  • uv run ruff check ...:All checks passed。
  • uv run ruff format --check ...:4 files already formatted。
  • uv run lint-imports:2 kept,0 broken。
  • uv lock --check:通过。
  • git diff --check upstream/main...HEAD:通过。
  • 1024×1024 固定压测图:Python 中位耗时 72.133 ms;Rust 基线 42.492–45.131 ms,满足 1.7 倍上限。
  • peak RSS 118,915,072 bytes,处理增量 78,397,440 bytes,低于 128 MiB 上限。
  • 固定压测图的 RGBA SHA-256 与 Rust 一致;4 张历史真实图逐像素一致。

Scope

Related Issues

Closes #613

Refs #491
Refs #495
Refs #496

The server reconstructor imports NumPy and Pillow directly.

Declare both packages in the app manifest and refresh the workspace lock metadata.

Deployments no longer rely on transitive image-processing dependencies.
The migrated algorithm remains derived from a fixed MIT-licensed upstream revision.

Record the reuse boundary and include the upstream copyright and license terms.

Reviewers can verify provenance without consulting the retired Rust pull request.
The explicit grid reconstructor does not require a separate Rust delivery path.

Port deterministic clustering and two-stage packing to bounded NumPy and Pillow code.

RGBA behavior stays compatible while removing the future PyO3 integration burden.
A language migration must not alter grid, color, alpha, or resource contracts.

Cover the Rust golden output alongside explicit grids, limits, and transparent RGB behavior.

Future numerical or algorithm substitutions now fail against observable results.
The Python port needs repeatable latency, memory, and output-parity evidence.

Add the same 1024-square workload and Rust RGBA golden used during migration.

Reviewers can measure warmed median latency and peak RSS on their target host.
@vercel

vercel Bot commented Aug 24, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated (UTC)
windup Ignored Ignored Aug 24, 2026 11:46am

@codecov

codecov Bot commented Aug 24, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 91.32231% with 21 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
...c/windup_app/server/pixel_perfect/reconstructor.py 91.32% 21 Missing ⚠️

📢 Thoughts on this report? Let us know!

@fennoai fennoai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review conclusion

Reviewed the complete fixed range d14d07c574a39ae910a7581b4b7b453044e10372...78133b3029e49ec177f12481652d4d9fa329e24f, covering the dependency/lock updates, provenance files, Python reconstructor, tests, and benchmark. I found no actionable correctness, compatibility, resource-bound, or security regression introduced by this PR. Static compilation and git diff --check pass. The focused pytest command was not runnable in this workspace because uv and pytest are unavailable; the PR description reports the focused suite passing.

@xyh202131 xyh202131 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

服务端实现边界清晰,资源上限和回归覆盖齐全;可以合并。

@xyh202131
xyh202131 merged commit 5d066ce into 1024XEngineer:main Aug 25, 2026
11 checks passed
@huyanxius
huyanxius requested a review from nighca August 25, 2026 04:55
@huyanxius

Copy link
Copy Markdown
Collaborator Author

@nighca 老师,这是完美像素化的 PR,还没 review 过,xyh 不小心把他merge 了😂

@nighca nighca left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nighca 老师,这是完美像素化的 PR,还没 review 过,xyh 不小心把他merge 了😂

@huyanxius 好的,PR 本身没啥大问题,不过“不小心 merge”这个不太应该

@@ -0,0 +1,67 @@
"""运行与 PR #495 Rust 基线相同的显式网格重建负载。"""

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

测下来 Python 版本性能怎么样?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

性能基本能和 rust 持平,但是问题是,现在看起来完美像素化图片尚还可以,但是到了视频逐帧就有点灾难了,张靖恒正在 做实验,稍后他会提一个 issue

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

“灾难”是指性能吧?是不是没有控制并行处理的任务数量,如果很多个像素化任务一下子一起跑,有问题是正常的,排队处理就行

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

倒不是性能,是指它的质量,因为它视频截帧之后并不是按照严格的像素逻辑移动的,而且每一次都会带有一定随机性,造成的偏移会更大,所以看起来质量会比完美像素化之前低。
老师可以在这里看看:#665

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

refactor(pixel-grid): migrate reconstructor to Python

3 participants